File Layout

File Layout

Every file Foundry creates, where it lives, and why.

Directory Structure

~/.copilot/foundry/<task-slug>/          ← All Foundry working/output files
├── crucible-state.md                    ← Crucible resume state (temp)
├── crucible-round-1-opus.md             ← Round 1 Opus output (temp)
├── crucible-round-1-codex.md            ← Round 1 Codex output (temp)
├── crucible-round-1-gemini.md           ← Round 1 Gemini output (temp)
├── crucible-round-2-*.md                ← Round 2+ outputs (temp)
├── plan.md                              ← ✅ Final plan (OUTPUT)
├── design-doc.md                        ← ✅ Final design doc (OUTPUT, large only)
├── forge-state.md                       ← Forge resume state (temp)
├── forge-coordination.md                ← Consolidated verifier feedback (temp)
├── forge-verifier-plan.md               ← Plan verifier result (temp)
├── forge-verifier-design.md             ← Design verifier result (temp, large only)
├── forge-verifier-architecture.md       ← Architecture verifier result (temp, large only)
├── forge-diff-filename.patch            ← Per-file diff for verifiers (temp)
├── forge-summary-plan.md                ← Plan summary for code agents (temp)
├── forge-summary-design.md              ← Design doc summary (temp, large only)
├── forge-summary-architecture.md        ← Architecture summary (temp)
├── forge-summary.md                     ← ✅ Execution summary (OUTPUT)
└── forge-task-log.md                    ← ✅ Iteration log (OUTPUT)

Legend

• ✅ OUTPUT — persists after completion
• (temp) — deleted during cleanup

Task Slug

The <task-slug> is derived from the task title or work item:

• Lowercased
• Spaces → hyphens
• Special characters removed
• Truncated to reasonable length

Examples:

• standardize-enum-conversion (from "Standardize enum string conversion")
• task-2878724-billing-refactor (from work item)

Why Outside the Repo?

Previous versions stored working files in the repo with .gitignore entries. Problems:

1. Pollution risk — one missed .gitignore entry = state files in commits
2. Multi-repo confusion — which repo's .gitignore gets modified?
3. Cleanup burden — must undo .gitignore changes at completion
4. Tool interference — IDEs index these files, slowing down searches

The ~/.copilot/foundry/ location eliminates all these issues. The repo is touched ONLY for actual code changes.

Shared Directory

Both Crucible and Forge use the same directory for a given task:

1. Crucible creates it — during Phase 2, creates ~/.copilot/foundry/<task-slug>/
2. Crucible writes — crucible-state.md, crucible-round-*.md, then outputs plan.md + design-doc.md
3. Crucible cleans up — deletes its temp files, leaves outputs
4. Forge reuses it — finds plan.md already there, writes its own state files
5. Forge cleans up — deletes its temp files, leaves forge-summary.md + forge-task-log.md

After Crucible (before Forge):

~/.copilot/foundry/<task-slug>/
├── plan.md
└── design-doc.md  (large tasks only)

After Forge (final state):

~/.copilot/foundry/<task-slug>/
├── plan.md
├── design-doc.md        (large tasks only)
├── forge-summary.md
└── forge-task-log.md

Source Repository Impact

The source repository is modified ONLY by:

• edit tool — modifying existing code files
• create tool — creating new code files
• git add <specific-file> — staging only planned files
• git commit — with descriptive message + Co-authored-by trailer
• git push — with fetch + rebase first

Nothing else touches the repo. No config files, no .gitignore, no temporary files, no working state.