CONTEXT FOUNDRY

System Overview

Context Foundry is an autonomous build loop that runs AI coding agents through a structured pipeline (Scout, Plan, Implement, Doubt) to complete software engineering tasks. Written in Rust (foundry v0.6.1), it provides a ratatui-based TUI dashboard, pattern learning, extension system, dual-model execution arena, and full git integration with PR workflows. The system reads tasks from TASKS.md, processes each through the SPID pipeline, and commits results -- optionally creating per-task pull requests for human review.

SPID Pipeline

The build loop executes a 5-stage pipeline per task: Scout, Plan, Implement, Doubt, Ship. Two ancillary stages -- Discovery and Pattern Extraction -- run outside the per-task pipeline (Discovery triggers when all tasks complete; Pattern Extraction runs after each successful task).

Pipeline Variants

Execution Modes

Ctrl+D: Dual-Selection States

Ctrl+D cycles through the DualSelection enum (state.rs:216-251). When builder_models has 2+ entries, this controls which model(s) execute:

Note: After "Both", cycling returns to "First" (not "Off"). Confirmed from DualSelection::next() at state.rs:243-249.

Ctrl+M cycles run_mode through: auto -> sprint -> review -> auto.

Dual-Model Arena

When builder_models has 2+ entries and dual_selection is "both", run_dual_pipelines() forks execution into two independent git worktrees. Each model runs the full Plan-Implement-Doubt pipeline independently in its own copy of the project.

Worktree Layout

.buildloop/arena/
├── pipeline-0-{provider}/    (git worktree for model[0])
│   ├── .buildloop/
│   │   ├── scout-report.md   (copied from main)
│   │   ├── current-plan.md   (generated by model[0]'s planner)
│   │   ├── build-claims.md   (generated by model[0]'s builder)
│   │   └── review-report.md  (generated by model[0]'s reviewer)
│   └── ... (full project copy)
└── pipeline-1-{provider}/    (git worktree for model[1])
    ├── .buildloop/
    │   ├── scout-report.md
    │   ├── current-plan.md
    │   ├── build-claims.md
    │   └── review-report.md
    └── ... (full project copy)

Event Tagging

Each pipeline wraps its events with AppEvent::DualPipelineEvent(usize, Box<AppEvent>) where the usize is the pipeline index (0 or 1). The TUI dispatches these to the correct stream in DualBuildState.streams[idx].

TUI Tab Bar

The agent output pane shows a tab bar when dual build is active. DualBuildState.tab (0 or 1) controls which stream is displayed. The tab bar shows model labels from DualBuildState.models[0] and DualBuildState.models[1].

Winner Selection

No automated winner selection runs. The human evaluates both worktrees and decides which to keep.

Per-Pipeline State

Tracked in DualBuildState (state.rs:254-264):

Git Integration

commit_task_pr Flow (Review Mode)

commit_and_push (Auto/Sprint Mode)

The simpler flow for auto and sprint modes:

1. git add -A
2. git reset -- .buildloop/logs/
3. git diff --cached --quiet (bail if nothing staged)
4. git commit -m "feat({task_id}): {desc}" (or WIP prefix)
5. maybe_push_commit() -- push to auto_push_remote if set

Key Details

TUI Layout

The running screen layout is defined in tui/mod.rs:122-165. Five vertical zones, with the middle zone split 60/40 horizontally.

┌────────────────────────────────────────────────────────────────────────┐
│ HEADER (5 lines)                                                       │
│  Project name │ Phase badge (Startup/Planning/Running)                  │
│  Mode badge (auto/sprint/review) │ Task: T1.1 -- description           │
│  Agent: IMPLEMENT (claude:opus) ⠋ 2m34s                                │
│  [dual tab bar when active: model[0] │ model[1]]                       │
├────────────────────────────────────────────────────────────────────────┤
│ PIPELINE DIAGRAM (7 lines)                                             │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐ │
│  │  SCOUT   │──>│   PLAN   │──>│IMPLEMENT │──>│  DOUBT   │──>│  SHIP    │ │
│  │ sonnet   │   │  opus    │   │  opus    │   │ sonnet   │   │ GitHub   │ │
│  │scout-rpt │   │curr-plan │   │bld-claim │   │fresh ctx │   │ git+pr   │ │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘ │
│  ┌──────────┐   ┌──────────┐  (disconnected)                            │
│  │ DISCOVER │   │ PATTERNS │                                             │
│  └──────────┘   └──────────┘                                             │
├──────────────────────────────────┬─────────────────────────────────────┤
│ AGENT OUTPUT (60% width)         │ TASK QUEUE (40% width, min 6 lines) │
│  [scrollable log of agent text,  │  H1.1: Create overview...           │
│   tool calls, tool results]      │  D32.1: Fix pipeline bug...         │
│                                  │  (H=yellow, D=blue, T=white)        │
│  Events: AppEvent::AgentOutput   │                                     │
│                                  ├─────────────────────────────────────┤
│                                  │ PATTERNS LEARNED (6 lines)          │
│                                  │  [pattern activity feed]            │
│                                  ├─────────────────────────────────────┤
│                                  │ EXTENSIONS USED (6 lines)           │
│                                  │  [extension injection feed]         │
├──────────────────────────────────┴─────────────────────────────────────┤
│ STATS PANEL (6 lines)                                                  │
│  Progress: [████████░░░░] 3/7 │ Git: main (3 dirty)                   │
│  Context%: S:45% P:72% I:89% D:-- │ Patterns: 3 injected, 1 used     │
│  Session: 12m │ Cost: $0.47 │ Commits: 2 feat, 0 WIP                  │
│  Agent: IMPLEMENT (claude:opus) running... ⠋                           │
├────────────────────────────────────────────────────────────────────────┤
│ STATUS BAR (1 line)                                                    │
│  q stop  Ctrl+C quit  ↑↓ scroll  i inject  PgUp/PgDn queue  p patt   │
│  ^T theme  Tab explore  [Enter continue]  [f findings]                 │
└────────────────────────────────────────────────────────────────────────┘

Pane-to-Event Mapping

Keybinds

From tui/running.rs:695-814:

Configuration Reference

Extensions

Extensions provide domain-specific knowledge to agents. They are discovered from ~/.foundry/extensions/ (global), ancestor directories' extensions/ folders, and <project>/extensions/ (local). Each extension directory must contain a CLAUDE.md file. Project-local extensions override global ones with the same name. Extension context is built by load_extension_context() and prepended to agent prompts via wrap_with_extensions().

8.0 Extension Taxonomy

An extension (or domain pack) is a directory containing any combination of the following component types:

The patterns/ directory is ONLY for canonical-schema pattern JSON. Every file in patterns/ must be parseable by the pattern loader (src/patterns.rs) as either a Vec<Pattern>, a PatternWrapper, or a single Pattern. Reference docs, asset catalogs, expertise metadata, and governance lists belong in docs/.

extensions/<name>/
├── CLAUDE.md                          # Instructions (required)
├── patterns/
│   └── <name>-common-issues.json      # Canonical pattern JSON only
├── docs/                              # Reference guides, specs, asset catalogs
├── templates/                         # Starter blueprints, command templates
├── examples/                          # Working reference projects
├── scripts/                           # Utility scripts
└── config/                            # Configuration files

8.1 Roblox

extensions/roblox/

• Purpose: Domain knowledge for Roblox world generation using Lune scripting and .rbxl/.rbxm files.
• Key files: CLAUDE.md, patterns/roblox-common-issues.json
• Critical patterns:
  • Use add_to_world.luau, NOT generate_world.luau -- terrain has varying elevations
  • Use CFrame, not Position, for moving parts (Position does not persist in Lune)
  • Do not extract and reapply rotation -- offset CFrame directly to preserve rotation
• Gotchas: Generating worlds from scratch causes floating/sinking objects due to terrain elevation.

8.2 Workday Extend

extensions/extend/

• Purpose: Workday Extend PaaS application development -- building custom apps inside Workday tenants.
• Key files: CLAUDE.md, WORKDAY_EXTEND_DEVELOPER_GUIDE.md, WORKDAY_EXTEND_ARCHITECTURE.md, orchestrations-integrations-guide.md, security-reporting-birt-notes.md, LATEST_DEVELOPMENTS.md, patterns/extend-common-issues.json
• Critical rules:
  • No local file-based development -- Extend apps built entirely in browser App Builder
  • Security policy activation is mandatory after ANY security change
  • Credentials never migrate between tenants
  • WIDs are tenant-specific -- use Reference IDs instead
  • CORS requires explicit configuration for REST API clients
  • Test before every biannual Workday release
• Gotchas: Extend requires a license; not all Workday customers have access.

8.3 Recon

extensions/recon/

• Purpose: Fleet reconnaissance from a management server -- inventory lookups, iDRAC queries, racadm commands, batch operations against Dell servers.
• Key files: CLAUDE.md, config/inventory-schema.json, templates/idrac-checks.md, templates/batch-loops.md, patterns/recon-common-issues.json
• Critical rules:
  • Always use grep -w (whole-word match) for hostname lookups
  • SSH to iDRAC needs -o ConnectTimeout=5 to avoid hanging loops
  • Always label batch output with the current hostname
  • Quote variables in loops
• Gotchas: Unlabeled batch output is useless; always prefix with hostname.

8.4 Flowise

extensions/flowise/

• Purpose: Building Flowise AgentFlow v2 workflows. Output is single JSON files.
• Key files: CLAUDE.md, FLOWISE.md, docs/flowise-expertise.json, example-flows/masterclass-2025/*.json, node-templates/*.json
• Critical rules:
  • Use HTML span format for ALL variable references: <span class="variable">$flow.state.varName</span>
  • Use correct field names: llmStructuredOutput, llmUpdateState, directReplyMessage
  • Every flow needs a Start node with proper startInput configuration
• Gotchas: Follow the validation checklist in FLOWISE.md before importing.

8.5 Mindcraft

extensions/mindcraft/

• Purpose: Python orchestrator for an AI Minecraft bot ("Andy") that plays autonomously.
• Key files: No CLAUDE.md. Only __pycache__ remnants of Python modules: client, detector, goals, learner, models, monitor, orchestrator, persistence, planner. Config in config/.
• Architecture: Monitors bot state, assigns goals, recalls bot if too far from spawn.
• Gotchas: The Python source files were cleaned up; only cached bytecode remains. Documentation is based on the root CLAUDE.md description and module names.

MCP Tools

Context Foundry exposes five MCP (Model Context Protocol) tools that allow AI agents to interact with the pattern store and delegate work. The MCP server source is not in this repo (only __pycache__ remnants in tools/); documentation is derived from CLAUDE.md and the patterns module API.

Pattern Store

Location: ~/.foundry/patterns/ (configurable via patterns_dir in .foundry.json). Tilde is expanded via $HOME (or $LOCALAPPDATA/$USERPROFILE on Windows). Fallback: /tmp/.foundry/patterns/ if HOME is unset.

JSON Schema

From src/patterns.rs:17-41:

{
  "pattern_id": "string (unique identifier)",
  "title": "string",
  "first_seen": "string (ISO date)",
  "last_seen": "string (ISO date)",
  "frequency": 0,
  "severity": "HIGH | MEDIUM | LOW | null",
  "keywords": ["string"],
  "tech_stack": ["string"],
  "issue": "string | null",
  "solution": {
    "planner": "string (advice for planner agent)",
    "reviewer": "string (advice for reviewer agent, alias: validator)"
  },
  "auto_apply": false,
  "learned_from": "string | null (project/task that produced this pattern)"
}

Supported JSON Formats

Three formats are accepted:

• Bare array: [{...}, {...}]
• Wrapper object: {"patterns": [{...}]} (via PatternWrapper struct)
• Single object: {...}

Pattern Matching at Plan Time

• Keyword scoring: Each pattern's keywords array is compared against the task description and codebase context. Higher overlap = higher score.
• Auto-apply bonus: Patterns with frequency >= 3 get auto_apply: true and a +2 score bonus.
• Semantic matching (optional): When semantic_match_enabled is true, uses Ollama (embedding_model, default "nomic-embed-text") to compute cosine similarity. Circuit breaker with 60s cooldown on failure.
• Injection cap: Top max_pattern_injection (default 10) patterns are injected into planner and reviewer prompts as "REFERENCE DATA" blocks.

Pattern Lifecycle

1. After each task: pattern_extraction agent writes .buildloop/patterns-extracted.json
2. Extraction model: pattern_extraction_model (default "sonnet")
3. merge_patterns() deduplicates by pattern_id, increments frequency on duplicates, updates last_seen
4. Auto-apply graduation: patterns reaching frequency >= 3 gain auto_apply: true

Samsara / Discovery

When all tasks in TASKS.md are complete AND run_mode is "auto" (not sprint or review), the Discovery stage triggers. The name "Samsara" refers to the cycle of rebirth -- after Discovery, the build loop restarts with new tasks, forming an infinite improvement cycle.

Discovery Agent

The Discovery agent (AgentRole::Discovery) scans:

• Codebase for bugs, gaps, missing features
• Build output and test results
• Git history for context
• Build history from prior session tasks (injected into prompt for focus)

Output

Appends new tasks under a ## Discovery Round N header in TASKS.md.

Task ID Convention

Format: D{round}.{sub} -- e.g., D33.1, D33.2. The highest_discovery_round() function (task.rs:188-214) parses both section headers (## Discovery Round N) and task ID regex (D(\d+)\.) to find the max round number.

Cooldown

discovery_cooldown_minutes (default 5). When Discovery finds 0 new tasks, the cooldown doubles (up to 30 minutes maximum). This prevents tight loops of empty discovery scans.

Prompts

prompts::discovery() for scanning, prompts::append_tasks() for writing new tasks to TASKS.md.

Samsara Loop

┌─────────────┐
│  TASKS.md   │<──────────────────────────────┐
│  (pending)  │                               │
└──────┬──────┘                               │
       │                                      │
       v                                      │
┌─────────────┐    ┌───────────┐    ┌─────────┴───────┐
│ SPID Pipeline│──>│   SHIP    │──>│    DISCOVERY     │
│ per task     │    │ commit/PR │    │ scan codebase   │
└─────────────┘    └───────────┘    │ append new tasks │
                                    └─────────────────┘
                                    (auto mode only)