redsen-lean-harness/docs/QUICKSTART.md

Quick Start Guide

This walks a new user from zero to a finished, verified change using redsen-lean-harness. For full command/flag reference see the main README.md; this doc is the shortest path to "it worked".

0. Prerequisites

• Node >= 20
• Git
• GitHub Copilot CLI or VS Code Copilot
• A CONTEXT7_API_KEY (required — lh doctor fails without it)

export CONTEXT7_API_KEY="<your key>"   # add to ~/.bashrc or ~/.zshrc

The harness never writes this key to disk. It is read from the environment only.

1. Get the harness into your project

The harness has two layers you install separately: the behaviour layer (.github/agents, skills, instructions, prompts, mcp.json — markdown, read by the host) and the determinism layer (the lh CLI — Node, called by the agents). Every install path below gets you the behaviour layer; only B and C also give you lh on PATH in one step.

A. Copilot CLI plugin (recommended — start here)

This is the primary distribution path for GitHub Copilot CLI users. It registers the agents/skills/instructions host-wide, so every repo you open in that Copilot CLI account can use @conductor, /fast-track, etc. — verified end-to-end on this machine:

# preferred: via the marketplace this repo publishes (no npm publish required, no deprecation warning)
copilot plugin marketplace add redsentech/lean-harness
copilot plugin install redsen-lean-harness@redsen

# also works, but Copilot CLI prints a deprecation warning for direct-source installs:
copilot plugin install redsentech/lean-harness

Use this when: you're a day-to-day Copilot CLI user who wants the harness available across multiple projects and doesn't need to modify the harness itself.

Limitation: this installs the behaviour layer only. You still need lh on PATH (see below) — either npm install -g @redsentech/lean-harness from GitHub Packages (once you've pointed the @redsentech scope at it, see The lh CLI), or step B/C below.

B. Bootstrap an existing repo with the onboarding script

Use this when: you're on VS Code Copilot (which has no plugin installer and reads .github/ directly), you want to try the harness against one specific repo before deciding to install it host-wide, or you want lh linked in one shot without a separate npm step.

git clone git@github.com:redsentech/lean-harness.git   # one-time, holds the source of scripts/onboard.mjs
cd lean-harness && npm install
node scripts/onboard.mjs /path/to/your-project --dry-run   # preview only
node scripts/onboard.mjs /path/to/your-project --yes       # do it

This copies the behaviour layer into /path/to/your-project, npm links the lh CLI onto PATH there, and runs lh init + lh doctor for you. Safe to re-run.

C. Clone and work inside this repo directly

Use this when: you're contributing to the harness itself (fixing an agent, a skill, or lh).

git clone git@github.com:redsentech/lean-harness.git
cd lean-harness
npm install
npm link   # puts `lh` on PATH globally, pointing at this checkout

2. Initialize and verify the environment

Inside your project (skip if the onboarding script already ran this):

lh init      # first-run wizard; writes .agents/harness.config.json
lh doctor    # confirms Node, git, Context7 key, verify commands, etc.

lh doctor should print all green checks. If it flags "no verify command configured", add a test/build/lint command to .agents/harness.config.json — the Ralph loop uses it to decide when a lane is actually done.

This creates a per-repo .agents/ footprint:

.agents/
  harness.config.json
  architecture.md       # living ADR log
  conventions.md        # living project conventions
  memory/INDEX.md        # the only file auto-loaded every run
  memory/{seed,failures,corrections,insights,conventions,quirks}.md

3. Run your first task

Open Copilot CLI or VS Code Copilot in the project and pick the entry point that matches the size of the change.

Full pipeline (new feature, non-trivial change):

@conductor build a rate limiter for the public API

This runs the whole pipeline: interrogator asks clarifying questions with recommended answers (you must answer before it proceeds — this is a deliberate gate), architect writes the spec and acceptance criteria, splitter breaks it into lanes, builder/verifier run the Ralph loop per lane (in parallel git worktrees when lanes don't overlap), integrator merges sequentially, and scribe journals everything as it happens.

Small brownfield fix (skip spec + DAG ceremony):

/fast-track fix the off-by-one in pagination

Learn an unfamiliar codebase first:

/onboard

4. When do you need to type lh yourself?

Short answer: almost never during a normal pipeline run. Every agent's instructions require it to call the relevant lh subcommand itself, at a specific point, every time — you don't ask for it and you can't opt it out. The table below is exhaustive: every lh subcommand, who calls it, and when.

Command	Who runs it	When
lh index	interrogator, scout, architect, splitter	Automatically, before reading files, to build token-budgeted context
lh host	conductor	Automatically, first thing, to pick parallel-vs-sequential strategy
lh run start/event/end	conductor (start/end), every agent (event)	Automatically, for every phase transition — never skipped
lh lane create/status/merge	conductor, builder, integrator	Automatically, before a write lane starts and when it merges
lh memory get/put/scan	interrogator, architect, builder, scribe	Automatically, to pull relevant shards before work and record facts/failures after
lh graph	verifier (always), plus architect/splitter/conductor/reviewer/scout/integrator at their own checkpoints	Automatically — it's exit criterion #3, never skipped
lh init	You (or scripts/onboard.mjs on your behalf)	Once per repo, at setup, or to repair a missing .agents/ baseline
lh doctor	You	Whenever you want to check the environment yourself — before starting, after upgrading Node/git/the plugin, or to diagnose a stuck run. Also run once automatically right after lh init
lh report <run-id>	You	After a run, when you want a human-readable markdown summary instead of raw NDJSON. No agent generates this for you

So the only commands you are expected to type by hand in everyday use are lh init (setup), lh doctor (diagnostics), and lh report (reading a past run's summary). Everything else — lh index, lh host, lh run, lh lane, lh memory, lh graph — is invoked by the agents as a scripted, mandatory step in their own instructions. You'd only run one of those manually if you're debugging outside the agent flow (e.g. lh graph on its own to check structure before opening Copilot at all, or lh memory get --shard failures to read what the harness has learned).

5. Know when it's actually done

A lane only completes when all five hold (otherwise it iterates, and escalates to you at the iteration cap):

1. Every declared verify command exits 0
2. Every acceptance criterion is individually checked off
3. lh graph passes
4. reviewer approves
5. No files changed outside the lane's declared scope

6. Where things are written

Everything the harness does is self-documenting — nothing lives only in a chat transcript:

What	Where
Design decisions	.agents/specs/<slug>/decisions.md
Spec + acceptance criteria	.agents/specs/<slug>/spec.md
Lane DAG	.agents/specs/<slug>/plan.dag.json
Run telemetry	.agents/runs/<id>/events.ndjson
Run journal	.agents/runs/<id>/journal.md
ADRs	.agents/architecture.md
Durable conventions	.agents/conventions.md
Cross-run memory	.agents/memory/*.md

Troubleshooting

Symptom	Fix
lh doctor fails on Context7	export CONTEXT7_API_KEY=... in your shell, then re-run
lh doctor warns "no verify command"	Add a test/build/lint command to harness.config.json
lh init refuses to run again	Expected — it won't clobber an existing config. Use lh init --force to reset
lh not found after onboarding	Re-run without --no-npm-link, or invoke via the absolute path the script prints
Agents/skills installed via copilot plugin install but lh init/lh doctor fail with "command not found"	Expected — plugin install only adds the behaviour layer. Run npm link from a clone (path C) or scripts/onboard.mjs (path B) to get lh on PATH
copilot plugin install owner/repo prints a deprecation warning	Expected for direct-source installs. Use copilot plugin marketplace add + copilot plugin install name@marketplace instead (path A)
Pipeline stuck at design gate	interrogator is waiting on your answers — this is intentional, answer the questions

Next steps

• Read the Pipeline and Agents sections in the README for the full mental model.
• Read the full lh CLI flag reference for every subcommand.
• Read ADR 0001 for why the harness is split the way it is.