code-forge

Code Forge

Complete development workflow — from TDD-driven implementation plans to execution, debugging, code review, git worktree management, branch lifecycle, and parallel agent dispatch.

Commands

Command	Description
End-to-End
/code-forge:build @doc.md	Full pipeline: test cases → plan → impl → review → verify
/code-forge:build "add feature"	Same pipeline but derives requirements from prompt + code analysis
/code-forge:build "add tests"	Test-only mode: test cases → tdd → review → verify
Planning & Execution
/code-forge:plan @doc.md	Generate plan from a feature document
/code-forge:plan @dir/	Browse a directory and pick a feature to plan
/code-forge:plan "requirement"	Generate plan from a text prompt
/code-forge:plan --tmp "requirement"	Generate plan in .code-forge/tmp/ (no project pollution)
/code-forge:impl [feature]	Execute pending tasks for a feature
/code-forge:status [feature]	View dashboard or feature detail
Quality & Debugging
/code-forge:review [feature]	Review code quality for a feature or project
/code-forge:review --feedback	Evaluate and respond to incoming review comments
/code-forge:review --github-pr	Post 15-dimension review to a GitHub PR
/code-forge:fix "description"	Debug and fix a bug with upstream trace-back
/code-forge:fix --review	Batch-fix all issues from a review report
/code-forge:debug "description"	Systematic root cause debugging (general-purpose)
Development Methodology
/code-forge:tdd	Enforce Red-Green-Refactor cycle (standalone TDD)
/code-forge:verify	Verify work before claiming completion
Workspace & Branch Lifecycle
/code-forge:worktree <feature>	Create isolated git worktree with project setup
/code-forge:finish	Merge, PR, keep, or discard a completed branch
Advanced
/code-forge:parallel	Dispatch parallel agents for independent problems
/code-forge:port @docs --ref impl --lang java	Port a project to a new language

Each command is a standalone slash command — invoke directly without a router.

---

Subcommand Details

plan — Generate Implementation Plan

Analyzes a feature document (or text prompt) and generates an implementation plan with architecture design, task breakdown, and TDD steps.

Input modes:

# From a specific file
/code-forge:plan @docs/features/user-auth.md

# From a directory — lists features for selection
/code-forge:plan @docs/features/
/code-forge:plan @../../other-project         # External project OK

# From a text prompt — auto-creates feature doc first
/code-forge:plan "Implement JWT-based user authentication"

# Temporary mode — plan files in .code-forge/tmp/ (auto-gitignored)
/code-forge:plan --tmp "Implement JWT-based user authentication"
/code-forge:plan --tmp @docs/features/user-auth.md

What it does:

1. Reads and analyzes the feature document (via sub-agent)
2. Asks for tech stack, testing strategy, and task granularity
3. Generates plan.md with architecture design + task dependency graph
4. Creates tasks/*.md with TDD-first steps, code examples, and acceptance criteria
5. Generates overview.md with task execution order table
6. Initializes state.json for progress tracking
7. Updates project-level planning/overview.md with all features and dependencies

Directory mode: Scans for *.md files and lets you pick one. Works with external paths.

Prompt mode: Auto-delegates to spec-forge:feature to generate a feature spec, then plans from that.

Reference docs: Configure reference_docs.sources in .code-forge.json to inject existing project documentation as context.

---

impl — Execute Tasks

Executes pending tasks for a feature using isolated sub-agents. Each task runs in its own sub-agent to prevent context exhaustion.

/code-forge:impl user-auth     # Execute a specific feature
/code-forge:impl               # Auto-select next pending/in-progress feature

What it does:

1. Locates the feature's state.json
2. Finds the next pending task respecting dependency order
3. Dispatches a sub-agent to execute: write tests → run → implement → verify → commit
4. After each task, asks: completed / pause / skip
5. Supports parallel execution for independent tasks

Pause/resume: Stop anytime. Progress is saved in state.json. Re-run to continue where you left off.

---

status — Project Dashboard

/code-forge:status             # Global dashboard — all features
/code-forge:status user-auth   # Feature detail — tasks and progress

Auto-regenerates planning/overview.md on each run.

---

review — Code Quality Review