cairn-builder

cairn-builder

A Claude Code plugin for unattended, long-horizon app builds. The operator writes a spec, runs one slash command, and walks away. A small orchestrator dispatches fresh-context subagents one feature at a time, for hours or days, until every feature in feature_list.json is verified passing.

A cairn is a pile of stones left to mark a trail for whoever comes next. That is the design metaphor: each session leaves durable markers — passing tests, commit messages, decisions — so the next fresh-context agent can pick up the trail without ever having seen the prior session's reasoning.

Lineage and inspiration

This project is a direct descendant of Anthropic's autonomous-coding quickstart — the original two-agent reference harness (Python + Claude Agent SDK) that demonstrated long-running autonomous coding via an initializer-then-coder loop driven by a 200-entry feature_list.json. That quickstart is the thing that drove direction here. The core ideas survive intact:

• One source of truth — a 200+ entry feature_list.json of end-to-end tests.
• Hard invariant — features only ever flip passes: false → true. They are never edited, reordered, or removed.
• Fresh context every session — each coding pass starts blank and re-orients from the spec, the feature list, the git log, and a small hand-off note.
• Two starting roles — an initializer that runs once to scaffold, then a coder that runs many times.
• Verification before new work — every coding session re-checks already-passing features before implementing new ones.

cairn-builder keeps all of that and pushes further on three axes:

1. Plugin-native, no Python harness. The orchestrator is itself a Claude Code prompt (commands/build-app.md), not an external script. There is no agent.py, no Agent SDK loop, no requirements.txt. Install the plugin, run /build-app, and the operator's Claude Code session is the orchestrator.
2. Context discipline as the load-bearing idea. A single Claude context cannot productively code for 18+ hours — it bloats and drifts. cairn-builder formalizes that with a strict orchestrator/subagent split: the orchestrator routes (~60–100 tokens per iteration), and all reading, coding, and verification happens in disposable subagent contexts. A 200-feature build fits in ~25K orchestrator tokens over the whole run.
3. Durable state across sessions. The original quickstart used claude-progress.txt as a single rolling log. cairn-builder splits that into DECISIONS.md (durable architectural choices with replacement semantics) and last-session.md (a bounded, overwrite-only hand-off note). claude-progress.txt is deprecated here.

Architecture

The whole design is a context-discipline pattern, not a code framework.

                      operator
                          |
                  /spec-author skill          (Socratic Q&A -> app_spec.xml)
                          |
                  /build-app command          <-- the orchestrator (YOU)
                          |
        +----------------+-----------------+
        |                |                 |
   initializer        coder            stuck-resolver
    (runs once)    (runs many)       (3-strike escalation)
        |                |                 |
        +----------------+-----------------+
                          |
                feature_list.json
                DECISIONS.md
                last-session.md
                git log

The orchestrator/subagent split

Role	File	Lifetime	What it does
Orchestrator	commands/build-app.md	Persists across whole run	Routes only. Inspects state via jq / grep. Dispatches exactly one subagent per iteration. Never reads app source, the spec, the feature list, or any project doc.
Initializer	agents/initializer.md	Runs once	Reads app_spec.xml, writes feature_list.json (≥200 entries), init.sh, README.md, seeds DECISIONS.md, makes the initial commit.
Coder	agents/coder.md	Fresh context, runs many times	Picks the next failing feature, implements it, verifies through the UI, flips passes:true, commits.
Stuck-resolver	agents/stuck-resolver.md	Fresh context, escalation	Triggered when the same feature hits the 3-strike .stuck counter. Either gets it working or marks blocked:true.
Spec author	skills/spec-author/SKILL.md	Operator-facing	Walks the operator through writing app_spec.xml section by section. Run before /build-app.
Spec updater	skills/spec-updater/SKILL.md	Operator-facing	Amends app_spec.xml mid-run for scope changes. Appends to feature_list.json without editing existing entries.

The protocol-line contract

Subagents end their final message with exactly one line, on a line by itself, matching one of: