Forge

AI-assisted development with the discipline of a senior engineer — spec first, test-driven, atomic commits, verified before done.

For engineers who write specs, not prompts.

Install

/plugin install forge@your-marketplace

The Five Commands

/forge:plan-requirement "add OAuth login"
    Analyzes codebase + asks ≤3 questions → .forge/SPEC.md

/forge:review-plan
    Reviews spec, generates task dependency graph → .forge/PLAN.md

/forge:execute-plan
    Git worktree + parallel execution + TDD + deviation rules → commits per task

/forge:verify-plan
    Runs test suite, checks success criteria → .forge/VERIFICATION.md

/forge:ship-plan
    Merges main, bumps version, updates CHANGELOG, creates PR
    Blocked until verification passes

How It Works

/forge:plan-requirement  →  forge-analyst + forge-planner  →  .forge/SPEC.md
/forge:review-plan       →  forge-reviewer                 →  .forge/PLAN.md
/forge:execute-plan      →  forge-executor (parallel)      →  commits per task
                         →  forge-debugger (on failure)    →  .forge/tasks/
/forge:verify-plan       →  forge-verifier                 →  .forge/VERIFICATION.md
/forge:ship-plan         →  forge-shipper                  →  PR URL

Context rot prevention: STATE.md is written before every agent exits. New session = 2-second orientation.

Parallel execution: Independent tasks run concurrently via dependency graph in PLAN.md.

Deviation rules (auto-enforced during execution):

1. Auto-fix bugs
2. Auto-add missing critical functionality (error handling, auth, rate limiting)
3. Auto-fix blockers
4. Checkpoint for architectural changes — requires human decision

Ship gate: /forge:ship-plan will not run until verification passes.

Project State

.forge/
├── STATE.md        — current stage, progress, next action
├── CODEBASE.md     — tech stack and patterns
├── SPEC.md         — structured spec
├── PLAN.md         — task dependency graph
├── VERIFICATION.md — test results
└── tasks/          — per-task summaries and commit hashes

Philosophy

• Spec before code — analyst reads your codebase before writing a line
• Tests before implementation — TDD enforced on tasks with testable behavior
• Atomic commits — each task gets its own commit
• Verified before shipped — ship is gated on passing verification
• Resumable always — STATE.md + session hook = instant orientation

License

MIT