Context Foundry

Foundry

Autonomous build loop that plans, builds, reviews, and learns.

Foundry reads a TASKS.md task list and works through it using Claude Code agents in a TUI, committing each completed task. Several run modes control what happens next: run forever with discovery (Auto), stop when done (Sprint), pause for human review after each task (Review), or run unattended for the build service (Service).

When to use the pipeline: the harness is a multiplier for verifiable engineering work — tasks with file:line references the planner can ground against, constraints the auditor can check, and behavior that BUILD or AUDIT can exercise against the code. For prose work (README updates, brainstorming, architecture decision records, documentation rewrites), the pipeline pays plan-review and audit costs for zero marginal benefit because there's nothing for it to verify. Write those directly. Full guidance: docs/task-composition.md.

Demos

• Building a Second Brain with the Loop — Foundry autonomously works through an implementation plan, building a second-brain app from a task list while the TUI streams each agent's output in real time.
• Enhancing the Second Brain with the Loop — A follow-up run where foundry picks up where it left off, discovering new work and iterating on the second-brain app with patterns learned from the first pass.
• Technical Overview — Architecture reference covering every subsystem: pipeline, dual-model arena, git integration, TUI layout, config, plugins, and MCP tools.
• The Roundup — A Texas-themed pitch page explaining Context Foundry for software architects.

Task Flow

Load patterns from ~/.foundry/patterns/

│ SCOUT → .buildloop/scout-report.md (investigate codebase) │ PLAN (+ patterns + scout report) → .buildloop/current-plan.md │ IMPLEMENT → build the code, run checks │ VERIFY (fresh context) → audit claims, fix issues, write verdict │ PATTERN EXTRACTOR → merge into ~/.foundry/patterns/ │ LOCAL GIT COMMIT → feat(task_id) or WIP(task_id) │ OPTIONAL AUTO-PUSH → only if auto_push_remote is configured

How It Works

Foundry is a harness for Claude Code. Each agent (planner, builder, reviewer, fixer, discoverer) is a Claude Code CLI invocation with a role-specific prompt and scoped tool access. The Rust binary handles orchestration, streaming, and state — Claude does all the reasoning and file editing.

The loop

Without guardrails, an autonomous build loop degrades fast. Task 3 builds on task 2's mistakes, which built on task 1's mistakes. Errors compound and the codebase drifts from the intended architecture.

The core design principle: no agent shares a context window with any other agent. Every stage starts with a clean context and receives only curated artifacts from the previous stage. The scout writes a structured report. The planner reads that report and writes a plan. The builder reads that plan and writes code. The verifier reads the code with zero knowledge of why it was written that way. No shared conversation history, no accumulated reasoning, no inherited blind spots. Each stage gets signal, not noise. This is how foundry prevents compounding errors across a long task queue.

Foundry's loop is designed around two forms of backpressure:

Short-term: the verify gate. After implementation, a verify agent -- in a completely fresh context with no shared history from the builder -- audits the changes by running build checks, tests, and a structured code audit. A model that just wrote the code retains its reasoning and is less likely to question its own decisions. An independent instance, given only the claims and the code, catches bugs the author is blind to. If it finds HIGH or MEDIUM issues, it fixes them and re-runs verification. If everything passes, the task gets a feat(task-id) commit. If issues remain, it gets a WIP(task-id) commit. The verify gate prevents bad code from silently flowing forward.

Pipeline tracking (QRPBA). Every task carries a progress indicator that records which pipeline stages ran and whether they succeeded. The indicator is persisted in TASKS.md next to each task and committed with the code, so you get a permanent audit trail.

- [x] T1.1: Set up project scaffolding          [QRPBA]

• T1.2: Implement auth flow [--PBA]
• T1.3: Add rate limiting [QRPBA!]
• T1.4: Write integration tests [....]

Each character represents a pipeline stage:

Examples: QRPBA = full pipeline, clean pass. --PBA = query and research skipped, planned, built, and audited. QRPBA! = full pipeline but audit found unfixable issues (WIP commit). See docs/progress-indicators.md for the full reference.

The TUI shows these indicators in the task queue with color coding, and they survive across restarts since they're written directly into the task file.

Why curated context matters. This isolated-context architecture is the same multi-instance review pattern described in Anthropic's Claude Certified Architect program as a production best practice. The key: agents communicate through structured file artifacts (.buildloop/scout-report.md, current-plan.md, build-claims.md, review-report.md), not through shared conversation history. Every artifact is a curated handoff -- the planner doesn't get the scout's full tool call history, it gets a concise report. The builder doesn't get the planner's reasoning, it gets a deterministic plan with file operations and verification commands.

Long-term: pattern learning. After each validated task, a pattern extractor agent scans the build artifacts, review findings, and plan to extract reusable lessons (e.g., "CFrame not Position for moving Roblox parts" or "always validate UTF-8 boundaries before string slicing"). These get saved as structured JSON to ~/.foundry/patterns/. On the next task — in any project — matched patterns are injected into the planner and reviewer prompts as reference data. Patterns that recur 3+ times get auto-promoted (auto_apply), meaning they're scored higher when they match -- but they still require at least one keyword or tech_stack overlap with the task to be included. This is how the system gets better over time: a mistake made once becomes a check applied everywhere.

Complexity-scaled pipeline. Not every task needs the full pipeline. A task complexity classifier scores each task as Simple, Medium, or Complex based on description length, keyword signals, and file count hints. Simple tasks skip query, research, and planner, get fewer patterns (0-2 instead of 10), and can skip the audit loop entirely -- straight from builder to commit. The QRPBA indicator reflects this: ---B- means query, research, planner, and audit were all skipped. Complex tasks always get the full treatment.

Learned doubt confidence. The doubt loop tracks pass/fail history per task shape using Ollama embeddings for semantic clustering. Task descriptions that consistently pass review (5+ consecutive clean passes) earn "trusted" status and skip doubt automatically. Any failure resets the cluster to zero. This compounds over time -- foundry learns which kinds of changes it reliably gets right and reserves thorough review for where it's needed.

Parallel builder. For multi-file tasks, the builder can split into parallel sub-agents. The plan's File Operations section is parsed to build a dependency graph -- files with no cross-references run in parallel worktrees, dependent files run sequentially. The doubt loop catches any integration issues from the merge. Opt-in via parallel_builder: true in .foundry.json.

Session event logging. Every pipeline event (task started, agent done, review findings, commits, pattern usage, rate limits) is appended as a JSON line to ~/.foundry/observatory/events.jsonl. This is the data collection layer for the upcoming Foundry Observatory analytics dashboard (separate project). Best-effort -- never blocks the pipeline.

CCA alignment

Context Foundry's architecture aligns with the principles in Anthropic's Claude Certified Architect -- Foundations exam guide: 43 of 55 principles implemented, 3 partial (architectural constraints), 0 open gaps. The full cross-reference mapping each principle to specific code locations is in the CCA Alignment Matrix (interactive version).

Run modes

Foundry has several run modes that control how the pipeline advances between tasks. Toggle with Ctrl+M on the startup screen or set run_mode in .foundry.json.

Auto is the fully autonomous mode. The loop never stops on its own -- when the task queue empties, a discovery agent scans the codebase for new work and appends it to TASKS.md. This is the mode shown in the demo videos.

Sprint is semi-autonomous. It works through every pending task with the same pipeline as Auto (scout, plan, implement, verify, commit), but stops when the queue is empty instead of running discovery. Use this when you have a known task list and want foundry to finish, not find more work.

Review is the human-in-the-loop mode for team workflows. After each task completes, foundry pushes a feature branch (foundry/{task_id}), creates a GitHub PR, and pauses. The TUI shows PAUSED (Review) and waits for either:

• The user to press Enter to continue manually, or
• GitHub PR approval, which foundry detects by polling gh pr view (configurable via pr_poll_interval_secs, default 30s)

If a reviewer requests changes, the TUI surfaces that status. Review mode requires the gh CLI to be installed and authenticated.

{

"run_mode": "review", "pr_poll_interval_secs": 30, "create_issue_on_wip": true }

The create_issue_on_wip flag works in any mode -- when a task fails verification and gets a WIP() commit, foundry auto-creates a GitHub issue with the review findings.

Service is the unattended mode used by the Context Foundry build service (foundry serve). Like Sprint it runs every pending task then stops with no discovery, but it also treats a WIP / audit-failed task as terminal: the task is recorded with its ! failure indicator and WIP() commit, and the loop advances to the next task with no retry and no consecutive-WIP stop. Headless runs (--no-tui) in this mode also skip the background GitHub update check. Service is meant for automated, bounded build jobs, not interactive use.

Dual-model arena

Foundry can run tasks through different AI providers. Toggle with Ctrl+D on the startup screen or set dual_selection in `.foundry