Y'all Need a Smarter Build Loop

Context Foundry takes a task queue and drives each task through a four-stage pipeline: Scout reads the territory, Plan draws the route, Implement drives the herd, and Doubt inspects every steer at the gate. No agent shares a context window with any other. Each one starts clean and receives only curated artifacts from the previous stage -- a structured report, a deterministic plan, a set of build claims. No bloated conversation history, no accumulated reasoning, no inherited blind spots. Each stage gets signal, not noise. This is how the loop prevents compounding errors across a long task queue. The system extracts patterns from solved problems and feeds them back into future plans, so it gets better at your codebase over time. It runs on your machine, calls the AI providers you choose, and commits verified code to git. No cloud service. No vendor lock-in. Just a Rust binary and a terminal.

The Trail Drive

Every task follows the trail from start to pen. The SPID pipeline has four stages plus a Ship step that handles git. Two ancillary stages -- Discovery and Pattern Extraction -- run outside the per-task trail.

Scout -- "Rides Ahead"

The scout rides ahead and maps the territory before the herd moves. It reads TASKS.md, SPEC.md, and your source files, then writes a report of what exists and what matters for the current task.

Plan -- "Draws the Route"

The planner reads the scout report, loads matching patterns from the brand book, and writes a step-by-step implementation plan with exact file operations, function signatures, and verification commands. No ambiguity -- the plan is for a machine, not a human.

Implement -- "Drives the Herd"

The builder takes the plan and drives the cattle down the trail. It creates and modifies files, runs the build, runs tests, and records what it claims to have done. In dual mode, two builders fork into separate worktrees and drive independent herds.

Doubt -- "The Trail Boss"

The trail boss inspects every steer at the gate before they enter the pen. A fresh-context reviewer reads the builder's claims, re-runs verification, and fixes issues it finds. If everything passes, the task ships as feat(). If not, it ships as WIP() and the herd keeps moving.

The Ranch Hands

Four ways to run the outfit. Each ranch hand has their own style. Cycle between the first three with Ctrl+M. The fourth is controlled by Ctrl+D -- it works alongside any of the other three.

The Pattern Brand

Every solved problem gets branded with a pattern_id so the herd can be identified and sorted at the gate. Patterns live in ~/.foundry/patterns/ as JSON files. Before planning each task, matching patterns are loaded and injected into the planner's context. The more cattle you drive, the fewer strays at the gate.

The Brand Mark (JSON Schema)

{
  "pattern_id":   "string -- unique identifier",
  "title":        "string -- human-readable name",
  "severity":     "HIGH | MEDIUM | LOW",
  "keywords":     ["array", "of", "match", "terms"],
  "tech_stack":   ["rust", "react", "python"],
  "issue":        "string -- what went wrong",
  "solution": {
    "planner":    "string -- advice injected into planner prompt",
    "reviewer":   "string -- advice injected into reviewer prompt"
  },
  "frequency":    42,
  "first_seen":   "2026-01-15",
  "last_seen":    "2026-03-17",
  "auto_apply":   false,
  "learned_from": "project-name"
}

How Patterns Are Matched

At plan time, the system loads all patterns from ~/.foundry/patterns/ and matches them against the current task description using keyword overlap. If semantic_match_enabled is true, Ollama embeddings provide semantic similarity scoring alongside keyword matching. Up to max_pattern_injection (default 10) patterns are injected into the planner and reviewer prompts as reference data.

Local patterns (project-level JSON files) can be promoted to the global registry using merge_project_patterns(), available as an MCP tool. This is how a solved problem in one project prevents the same mistake in every future project.

The Arena

Two cowboys out of the chute at the same time. The human judge decides who scored.

When builder_models lists two or more model specs (e.g., ["claude:opus", "codex:o4-mini"]), the arena is available. Ctrl+D cycles through four states: Off (single model), First only, Second only, and Both. In Both mode, run_dual_pipelines() forks execution into two independent git worktrees.

How It Works

1. Two git worktrees are created under .buildloop/arena/pipeline-0-{provider}/ and .buildloop/arena/pipeline-1-{provider}/
2. Each worktree gets a full copy of the project
3. Each model runs the full Plan-Implement-Doubt pipeline independently in its own worktree
4. Events are tagged by pipeline index (0 or 1) via DualPipelineEvent
5. The TUI shows a tabbed view -- one tab per model -- so you can watch both trails simultaneously
6. When both finish, the human evaluates and picks the winner

Worktree Layout

.buildloop/arena/
  pipeline-0-claude/     (git worktree for model[0])
    .buildloop/
      scout-report.md    (copied from main)
      current-plan.md    (generated by model[0])
      build-claims.md    (generated by model[0])
      review-report.md   (generated by model[0])
  pipeline-1-codex/      (git worktree for model[1])
    .buildloop/
      scout-report.md
      current-plan.md
      build-claims.md
      review-report.md

Ctrl+D Cycle

Note: After Both, Ctrl+D returns to First, not Off. The cycle is First -> Second -> Both -> First.

The Deed

Every ranch has a title document. Yours is .foundry.json at the project root. Here are the fields that matter most.

The Posse

Specialist deputies, each with their own jurisdiction. Extensions provide domain-specific knowledge to agents. They are discovered from ~/.foundry/extensions/ (global) and <project>/extensions/ (local). Each extension directory contains a CLAUDE.md file whose contents are prepended to agent prompts.

Trail's End

Here is what matters for architects evaluating this system.

• No cloud lock-in. Self-hosted Rust binary. Your code stays on your machine. Swap providers per pipeline role -- Opus for planning, Sonnet for review, Codex for building -- via config, not code changes.
• Pattern learning compounds over time. Every solved problem is extracted into a reusable pattern. Before planning each new task, matching patterns are injected into the agent's context. The system gets better at your codebase the more you use it.
• The doubt loop catches what self-review misses. A fresh-context reviewer audits every build. It has no knowledge of what the builder intended -- only what the builder claims and what the code actually does. This separation of concerns catches blind spots that self-review cannot.
• The dual-model arena absorbs uncertainty. Run two different models against the same task in isolated worktrees. Compare outputs. Pick the winner. No single-vendor dependency.
• Everything is a config change. Pipeline mode, execution mode, model selection, pattern injection limits, PR polling intervals, extension selection -- all in one .foundry.json file. No infrastructure changes required to change behavior.