forge

Structured development workflow for Claude Code. Enforces phased execution (brainstorm → plan → execute → review → verify → finish) with persistent context tracking, TDD methodology, and behavioral guardrails.

Inspired by Andrej Karpathy's observations on LLM coding pitfalls.

Quick Reference

# Tracker CLI (LLM-operated, never run by humans directly)
python3 ~/.claude/skills/forge/scripts/tracker.py <command> [args]

Workflow Phases

Phase	File	When
1. Brainstorm	phases/brainstorming.md	Refine idea before coding
2. Plan	phases/planning.md	Break work into verifiable tasks
3. Execute	phases/executing.md	Implement tasks (TDD, parallel agents)
4. Debug	phases/debugging.md	When something breaks
5. Review	phases/code-review.md	Before merging code
6. Verify	phases/verification.md	Before declaring done
7. Finish	phases/finishing.md	Merge, cleanup, close session
8. Security Audit	phases/security-audit.md	On-demand, pre-deploy

Adopt (phases/adopting.md) is not a phase. It onboards existing projects. TDD (methods/tdd.md) is the mandatory methodology during execution. Guardrails (methods/guardrails.md) are injected into every agent prompt.

Commands

Command	Action
/forge or /forge help	Show available commands and status
/forge brainstorm <idea>	Start brainstorming a new idea
/forge plan	Create implementation plan
/forge execute	Start executing the plan
/forge debug	Enter systematic debugging mode
/forge review	Run code review
/forge verify	Run verification checks
/forge finish	Merge, cleanup, close session
/forge audit	Run security audit
/forge adopt	Onboard an existing project
/forge status	Show current project, phase, pending tasks

How to Use

Starting a new project

1. Read phases/brainstorming.md and follow its process
2. Brainstorm handles project creation, index population, and session start
3. Flow into planning when design is approved

Resuming work (the most common case)

Most forge sessions are continuations, not new projects. The "where am I?" command is status. Always run it first when entering a project context cold.

1. Run python3 ~/.claude/skills/forge/scripts/tracker.py status
2. If no_active_session: response includes projects (with pending counts) and last_session. Ask the user which project to resume, or pick the most recent one if obvious. Then tracker.py start <project>.
3. If active: response includes project, duration, in_progress tasks (with IDs and titles), backlog (top 5 + total). You now know exactly where work stopped and what is queued. Resume the in-progress tasks first, then pick from backlog.
4. Determine the current phase from task statuses (in-progress = execution, none in progress = planning or finishing).
5. Confirm direction with the user before writing any code.

This is the bridge that makes forge survive context compaction: project knowledge lives in ~/.forge/, not in the conversation. status brings it back.

Adopting an existing project

1. Read phases/adopting.md and follow its process
2. Scans codebase, populates index, starts session

Dispatching parallel agents

Read ~/.forge/config.yaml (use the Read tool, not cat) to check dispatch strategy.

If agent (default): Use Claude Code's built-in Agent tool If cmux: Use spawn-workspace.sh from cmux skill

Each agent receives: task description, acceptance criteria, TDD methodology, guardrails.

Phase Transitions

brainstorm → [user approves] → plan
plan → [user approves] → execute
execute → [tasks complete] → review
review → [approved] → verify → finish
review → [changes requested] → execute
debug → enters from any phase, returns to previous
security-audit → independent, runs anytime

User approval required: brainstorm→plan and plan→execute. Other transitions automatic if clean.

Rules

1. Never skip brainstorm for new features. Quick brainstorm OK, no brainstorm not OK.
2. Never write production code without failing test first. TDD mandatory.
3. Never declare done without verification. Evidence before claims.
4. Never merge without code review. Even self-written code.
5. Always track context. Sessions start with start, end with end.
6. Always update index on architectural changes. Tasks are ephemeral, index is permanent.
7. Completed tasks must not accumulate. Use --discard, --into-index, or --into-memory.
8. Check index staleness on session start. Warn if stale.
9. CLAUDE.md stays lean. Max 30 lines. Hook enforces this.
10. Inject guardrails into agent prompts. Read methods/guardrails.md.

Configuration

~/.forge/config.yaml:

dispatch: agent          # "agent" or "cmux"
claude_md_guard:
  enabled: true
  max_lines: 30

Data Directory

~/.forge/
  config.yaml
  state.json
  projects/
    <project>/
      index.md           # Living reference (LLM-managed)
      DESIGN.md           # From brainstorming
      PLAN.md             # From planning
      tasks/
        TASK-NNN.md       # Active tasks
      sessions/
        YYYY-MM-DD_*.md   # Session logs
      archive/
        tasks/            # Completed/discarded tasks
      REVIEW-*.md         # Code review reports
      VERIFICATION-*.md   # Verification reports
      SECURITY-AUDIT-*.md # Security audit reports

Note: Files like DESIGN.md, PLAN.md, REVIEW-.md, VERIFICATION-.md, and SECURITY-AUDIT-*.md are written by the LLM via the Write tool during their respective phases. The tracker only manages index.md, tasks/, sessions/, and archive/.