# redsen-lean-harness

An imperative, token-lean, self-documenting agent harness. It runs unchanged in
**GitHub Copilot CLI** and **VS Code Copilot**.

## Division of labour

| Layer | Owns | Where |
| --- | --- | --- |
| Markdown | Behaviour — agents, skills, instructions | `.github/` |
| Node CLI (`lh`) | Determinism — index, gates, worktree lanes, telemetry, memory | `src/` |
| Host | Execution — subagents, fleet, tools | Copilot CLI / VS Code |

We never reimplement an agent runtime. If the host can do it, the host does it.

## Pipeline

```
design  → gated Q&A, nothing inferred        → .agents/specs/<slug>/decisions.md
plan    → spec + acceptance criteria + DAG   → spec.md, plan.dag.json
build   → worktree lanes, Ralph loop         → builder ⇄ verifier
integrate → sequential merge + full verify   → integrator
document  → runs throughout                  → scribe
```

The **conductor re-plans at every checkpoint**: lanes may be spawned, killed, or
re-scoped based on results. Failures are isolated, retried within bounds, then
planned around.

## Agents

| Agent | Tier | Invokable | Responsibility |
| --- | --- | --- | --- |
| `conductor` | strong | yes | Entry point. Owns the pipeline and the dynamic DAG. |
| `interrogator` | strong | yes | Design-phase Q&A with recommended answers. |
| `scout` | cheap | no | Read-only recon, fanned out N-wide. |
| `architect` | strong | yes | Spec, acceptance criteria, architecture doc, ADRs. |
| `splitter` | mid | no | Decomposes spec into lanes with file-scope globs. |
| `builder` | mid | no | Implements one lane inside its worktree. |
| `verifier` | cheap | no | Runs verify commands + structural gate. |
| `reviewer` | strong | yes | Acceptance-criteria and scope gate. |
| `integrator` | strong | no | Sequential merge, conflict resolution, full verify. |
| `scribe` | cheap | no | Journal, ADRs, living spec, conventions. |

## Skills

`init` `design` `plan` `build` `verify` `integrate` `onboard` `memory` `index`
`telemetry` `fast-track` `doctor`

## `lh` commands

| Command | Purpose |
| --- | --- |
| `lh init` | First-run wizard, writes `.agents/harness.config.json`. |
| `lh index` | Token-budgeted tree-sitter repo map. |
| `lh graph` | Structural gate: duplicates, orphans, unresolved calls. Exit 1 on violation. |
| `lh lane` | git worktree lane lifecycle + file-scope leases. |
| `lh run` | NDJSON telemetry + live board. |
| `lh memory` | Memory shard CRUD, compaction, secret scanning. |
| `lh host` | Detect host capabilities, print orchestration strategy. |
| `lh report` | Markdown telemetry report. |
| `lh doctor` | Environment checks. |

## Per-repo footprint

```
.agents/
  harness.config.json
  architecture.md          # living, ADR log inside      [committed]
  conventions.md           # living                      [committed]
  memory/INDEX.md          # the ONLY always-loaded file [committed]
  memory/{seed,failures,corrections,insights,conventions,quirks}.md
  specs/<slug>/{questionnaire,decisions,spec}.md, plan.dag.json
  runs/<id>/{board.md,events.ndjson,journal.md}
  .cache/                  # repomap, symbols, wasm      [gitignored]
```

## Token-leanness

1. Only `memory/INDEX.md` is always loaded; shards pull on demand.
2. `lh index --budget` caps repo-map size.
3. Cheap-tier subagents absorb exploration cost; only summaries return.
4. `lh graph` and `lh report` emit briefs, never dumps.
5. Skill bodies stay short; procedures live in `templates/`.

## Context7

Mandatory for external library work. Key is read from `CONTEXT7_API_KEY`
**environment variable only** — the harness never writes secrets to disk.