🍋 Lemony

A Harness for AI Coding.

@lemoncode/lemony brings a reproducible Spec-Driven Development (SDD) workflow to AI coding agents. A single CLI installs — into any repo — an Orchestrator that dispatches work to fresh-context sub-agents (spec, implementation, review, architecture), a generic skill catalog, lifecycle hooks, anonymous telemetry, and a versioned update/rollback system. You own your code and your domain knowledge; the harness owns the framework around it and keeps it up to date.

Target: Claude Code is the only operative target today; the design is abstraction-ready, so Cursor / Codex / OpenCode plug in later without a refactor.

Status: 0.x — still evolving. Pins are exact and any pre-1.0 minor can break; 1.0.0 lands when the CLI verbs, config schema, and catalog contract are stable enough to commit to semver.

Prerequisites

• Node.js ≥ 24 and npm ≥ 11 (node --version).
• Claude Code installed in the target repo.

Install

The package is public on npm — no token, no registry config:

npm i -D @lemoncode/lemony   # add the harness to the project
npx lemony install           # scaffold the harness into this repo

The devDependency is the recommended setup: the harness's hooks and agents emit telemetry through a launcher that resolves the CLI from the project's own node_modules/.bin first, then a global install. That local bin is pinned to the repo, so it survives a global PATH change or a Node version switch (fnm/nvm).

No package.json (a non-Node repo)? A one-shot npx @lemoncode/lemony install still scaffolds the harness; telemetry then needs a global install (npm i -g @lemoncode/lemony) so the launcher can resolve the CLI.

install is fresh-only and writes, into the current repo:

.claude/
├── agents/             # the agent role instances (orchestrator, spec, impl, review, …)
├── skills/             # the eligible slice of the generic skill catalog (by capability)
├── settings.json       # the `hooks` block (vendor-owned) merged into your settings
└── .harness/
    └── baseline/<ver>/ # pristine copy of every installed vendor file (the merge base)
agents.md               # Orchestrator entry point for Claude Code
harness.config.yml      # your harness config (see below)

Your own files — CLAUDE.md, CONTEXT.md, docs/, playbooks — are never overwritten. If you run install over a .claude/ that already has managed content, it reconciles instead of refusing (interactive on a TTY).

A day with the harness — when to run what

Two surfaces: CLI verbs in your terminal (setup & maintenance), slash commands inside Claude Code (the daily work).

① First time in a repo (terminal)

npx lemony install     # scaffold the harness
npx lemony doctor      # confirm it's healthy

② You have an idea or a new feature (Claude Code) — /define "add CSV export to the reports page"

Runs the full SDD round-trip. You stop at two human gates; nothing else needs you:

1. the Orchestrator grills the idea into a reviewable PRD,
2. opens the task issue + branch, dispatches a fresh-context Spec Author,
3. ▸ approval gate — you read the spec cold and approve,
4. the Implementer builds it (TDD), the Reviewer checks security / tests / spec-compliance,
5. ▸ merge gate — you approve the PR; on merge, the task closes out.

It honors every human gate and never self-approves — that, plus fresh-context sub-agents, is the difference from prompting an agent ad hoc.

③ A small bug, not a whole feature (Claude Code) — /triage "dates render a day off in Safari"

The lightweight L2 path: find root cause → fix → review → merge, without the full PRD ceremony.

④ Production's on fire (Claude Code) — /hotfix "checkout 500s on empty cart"

Fix and ship now; the review runs async and the issue + postmortem are backfilled after.

⑤ Mid-task you spot an unrelated defect (Claude Code) — /spinoff "typo in the 404 page copy"

Captures it as a tracked pending stub and keeps you on your current task — no context switch. You pick it up later with /resume.

⑥ Stopping for the day, and coming back (Claude Code)

• /pause — writes a resume narrative + a session_closed event so future-you starts cold.
• /resume — lists the open queue (spec-ready, in-progress, pending stubs, parked closeouts) and picks one up from its branch + state.

⑦ Throwaway or spike, no ceremony (Claude Code) — /bypass

Escape hatch: records one l3_bypass event, then you work with no issue / spec / review.

Not sure which mode? Just describe what you want — the Orchestrator routes "I have an idea for…" → DEFINE, "there's a bug in…" → TRIAGE, "continue #42" → RESUME.

| Slash command | Mode | Use it to | | ----------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | /define | L1 | Start a new feature/idea: grill → PRD → spec → implement → review → merge. | | /triage | L2 | Handle a small bug on the lightweight path. | | /hotfix | L2! | Urgent fast-track: fix and ship now; the review runs async, issue + postmortem are backfilled. | | /spinoff | — | Capture an unrelated, non-blocking defect mid-task as a tracked stub — without leaving your current task. | | /resume | — | Pick up an existing harness task (or a /spinoff stub) from its branch and state. | | /pause | — | Pause the session: writes a narrative resume + a session_closed event. | | /bypass | L3 | Escape hatch: record one l3_bypass event, then work with no issue/state/review. | | /add-capability | — | Activate an opt-in capability your repo reported as available (see Opt-in capabilities) — e.g. have the Architect bootstrap docs/architecture.md. |

Behind the slash commands the harness installs a catalog of agents (orchestrator, spec-author, implementer, reviewer, architect, ui-designer) and skills (grill-with-docs, tdd, senior-review, security-review, …) that the agents invoke — you don't call skills directly; the Orchestrator and sub-agents do, gated by your repo's capabilities.

Commands

The CLI ships nine verbs. Run lemony <command> --help (or -h) for usage; lemony version (or -v) prints the installed version.

| Command | What it does | Key flags | | ----------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | install | Install into a fresh repo, or reconcile a pre-existing .claude/. | --target=<claude-code> --task-storage-repo=<owner/name> --on-conflict=<vendor\|client> | | update | Move the install to the CLI's catalog version (3-way merge). | --on-conflict=<vendor\|client> --dry-run | | repair | Re-sync at the pinned version (restore missing files, never clobber edits). | --dry-run | | rollback | Restore a pre-change snapshot (offline). | --to=<version> --list --cleanup --force | | uninstall | Remove vendor-managed files (keeps your docs, state, adopted skills). | --labels | | doctor | Diagnose the installation (read-only); proposes repair. | — | | status | Show installed version, branch drift, and open tasks. | — | | emit | Append a telemetry event to .claude/state/events.jsonl. | <type> [--key=value …] | | telemetry | Inspect or control the local anonymous telemetry. | status show disable enable |

The harness keeps a committed baseline under .claude/.harness/baseline/<version>/ — a verbatim copy of every installed vendor file at the pinned version — so update is a true 3-way merge that travels with your repo. Overlapping edits get git-style <<< / >>> markers and a report; your copy is always snapshotted first, so rollback is one command away.

harness.config.yml

The installer writes a config that pins and shapes your install (validated with a strict schema; harness.config.schema.json ships for IDE autocomplete):

| Key | Meaning | | ---------------- | ------------------------------------------------------------ | | vendor_version | Exact semver pin. update bumps it; never edit by hand. | | target | Which AI-coding harness the install targets (claude-code). | | task_storage | Where tasks live (owner/name of the issues repo). | | paths | Where managed files land. |

Opt-in capabilities

Some skills stay dormant until your repo keeps a convention file — the harness never creates one for you (that would impose an architecture), so you opt in deliberately.

• What it is. Today the one convention is docs/architecture.md. Keep it and the update-architecture skill activates on your next update / repair, keeping that map current as your system's shape changes.
• See what's available. install lists the capabilities your repo qualifies for, and lemony doctor shows them under an ℹ capabilities line — informational, never a failure.
• Turn one on. Run /add-capability inside Claude Code: it has the right agent author the convention file for you, then re-syncs so the gated skill installs.

Privacy

The harness emits anonymous, opt-out telemetry to improve the framework.

• What's collected. Coarse usage signals only — no source, no file contents, no identifiers. Events are written locally to .claude/state/events.jsonl first.
• Opt out. Set DO_NOT_TRACK=1, or run npx lemony telemetry disable.
• Inspect it. npx lemony telemetry status / show shows exactly what's on disk.

Full details are in PRIVACY.md, shipped with the package.

Made with 🍋 by Lemoncode.