mozempkandCopilot
383129f571
Recovered from crashed session (Node OOM). Repo contains full P0-P6 scaffold: plugin.json/marketplace.json, AGENTS.md, ADRs 0001-0006, lh CLI (init/index/graph/lane/run/memory/host/report/doctor), 10 .github/agents, 12 CLI skills, instructions, context7 mcp.json, and unit/e2e test suite. Fixed: run.mjs read --in-tokens/--out-tokens but tests and CLI docs use --input-tokens/--output-tokens, so telemetry totals were always 0. Now accepts both forms. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
90 lines
3.6 KiB
Markdown
90 lines
3.6 KiB
Markdown
# 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.
|