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>
43 lines
1.9 KiB
Markdown
43 lines
1.9 KiB
Markdown
# ADR 0001 — Markdown owns behaviour, Node owns determinism
|
|
|
|
- **Status**: Accepted
|
|
- **Date**: 2026-09-09
|
|
|
|
## Context
|
|
|
|
The harness must be *simple*, *lean on context*, *distributable as a plugin*, and run on two
|
|
hosts (GitHub Copilot CLI, VS Code Copilot) that both already contain a capable agent runtime.
|
|
|
|
There is a strong temptation to build an orchestrator process that drives the model directly.
|
|
That path produces a second agent runtime we would have to maintain, and it cannot be shipped
|
|
as a plugin because plugins run *inside* the host.
|
|
|
|
## Decision
|
|
|
|
Split the system in three, with a hard boundary:
|
|
|
|
| Layer | Owns | Artifact |
|
|
| --- | --- | --- |
|
|
| Markdown | Behaviour — agents, skills, instructions | `.github/` |
|
|
| Node CLI (`lh`) | Determinism — index, gates, lanes, telemetry, memory | `src/` |
|
|
| Host | Execution — subagents, fleet, tools, models | Copilot CLI / VS Code |
|
|
|
|
`lh` never calls a model. Agents never do arithmetic, parsing, git plumbing, or bookkeeping
|
|
by hand. **We do not reimplement an agent runtime.**
|
|
|
|
## Consequences
|
|
|
|
- The same `.github/` tree works in both hosts; only the scheduler differs (see ADR 0003).
|
|
- `lh` is trivially testable — it is pure I/O with no model in the loop.
|
|
- Anything the host cannot do, we cannot do. Accepted: host capability detection (`lh host`)
|
|
makes the limitation explicit and degrades rather than failing.
|
|
- Behaviour changes are markdown diffs, reviewable in a PR without running anything.
|
|
|
|
## Alternatives considered
|
|
|
|
- **Standalone orchestrator binary** — rejected: not plugin-distributable, duplicates the host.
|
|
- **Everything in markdown, no CLI** — rejected: indexing, worktrees, structural analysis and
|
|
token accounting are not things an LLM should do by hand; they are slow, expensive and unreliable.
|
|
- **Everything in Node, markdown as prompts only** — rejected: opaque, unreviewable, and it
|
|
breaks the self-documenting requirement.
|