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](../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)

```bash
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
invoke its agents (e.g. `redsen-lean-harness:conductor`) and skills (e.g. `/fast-track`) — verified end-to-end on this machine:

```bash
# 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](../README.md#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.

```bash
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 link`s 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`).

```bash
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):

```bash
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):

```
Use the conductor agent to build a rate limiter for the public API
```

> **How agent invocation actually works** (per the [official docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/invoke-custom-agents)):
> `@` in Copilot CLI **only mentions files**, never agents. There are three real ways to invoke
> a custom agent:
> 1. `/agent` — opens an interactive picker to browse and select.
> 2. Name it in your prompt — `Use the conductor agent to ...` — Copilot infers which agent you mean.
> 3. `copilot --agent=NAME -p "..."` — force a specific agent non-interactively.
>
> **Agent name note:** inside this repo (or any repo where the harness lives natively in
> `.github/agents`), the bare name `conductor` resolves. Once installed as a *plugin* into
> another project, Copilot CLI namespaces **agents only** — the resolvable name becomes
> `redsen-lean-harness:conductor`, `redsen-lean-harness:architect`, etc. (confirmed via
> `copilot --agent <bad-name>`, whose error message lists every real agent name it knows,
> always namespaced for plugin-sourced agents). **Skills are never namespaced** —
> `/fast-track`, `/design`, `/build`, `/verify`, `/onboard`, etc. work as plain slash commands
> regardless of install method (confirmed via `copilot plugins list --kind skill --json`, whose
> `name` fields carry no prefix).
>
> **Known limitation:** a plugin-sourced agent can be launched (by full name in a prompt, or
> via `--agent=plugin-name:agent-name`) even when it isn't proactively *suggested*. Copilot's
> own `copilot plugins list` command documents that "custom agents ... require a live session
> and will be added in a follow-up" — i.e. the CLI's own agent-introspection tooling doesn't
> yet fully cover plugin-contributed agents, which likely also affects what the `/agent` picker
> surfaces and what the model volunteers unprompted. Naming the agent explicitly
> (`Use the conductor agent to ...`) reliably works around this today.
>
> If naming the agent explicitly still fails: the plugin was likely loaded before a fix landed.
> Run `copilot plugin marketplace update redsen && copilot plugin update redsen-lean-harness`,
> then start a **new** `copilot` session — an already-running session keeps the plugin
> snapshot it loaded at startup and won't pick up the update until restarted.

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) |
| `npm install -g @redsentech/lean-harness` gives `404`/`403` | `.npmrc` isn't pointed at GitHub Packages, or the token lacks `read:packages`. Run `node scripts/setup-npm-registry.mjs` |
| Pipeline stuck at design gate | `interrogator` is waiting on your answers — this is intentional, answer the questions |

## Next steps

- Read the [Pipeline](../README.md#pipeline) and [Agents](../README.md#agents) sections in the
  README for the full mental model.
- Read the full [`lh` CLI flag reference](../README.md#lh-commands) for every subcommand.
- Read [ADR 0001](adr/0001-markdown-behaviour-node-determinism.md) for why the harness is split
  the way it is.