redsen-lean-harness/AGENTS.md

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.