Code Forge — Plan

Generate an implementation plan from a feature document or a requirement prompt.

When to Use

• •Have a feature document that needs to be broken into development tasks
• •Have a requirement idea (text prompt) that needs planning
• •Need a structured plan with TDD task breakdown

Workflow

Input (Document or Prompt) → Analysis → Planning → Task Breakdown → Status Tracking

Context Management

Steps 2, 6, and 7 are offloaded to sub-agents via the Task tool to prevent context window exhaustion on large projects. The main context retains only concise summaries returned by each sub-agent, while full document analysis, file generation, and code implementation happen in isolated sub-agent contexts that are discarded after completion.

Actual execution order: 0 → 0.8 (prompt mode only) → 1 → 2 (sub-agent) → 3 → 4 → 6 (sub-agent) → 7 (sub-agent) → 5 → 8 → 8.5 → 9

Step 5 (overview.md) executes after Steps 6 and 7 because it references task files generated by those steps.

Detailed Steps

Step 0: Configuration Detection and Loading

Important: Detect and load configuration before any operation.

0.1 Detect Project Root

Search upward for project root markers:

.git/ | .code-forge.json | pyproject.toml | package.json | Cargo.toml | go.mod | build.gradle | pom.xml | Makefile

If no root is found, use the current directory as the project root.

0.2 Load Configuration (three-layer merge)

Load configuration by priority (each layer deep-merges into previous):

1. •

   System defaults:

   • •_tool.name = "code-forge" (read-only, not overridable)
   • •_tool.description = "Transform documentation into actionable development plans with task breakdown and status tracking" (read-only)
   • •_tool.url = "https://github.com/tercel/code-forge" (read-only)
   • •_tool.skills_collection = "https://github.com/tercel/claude-code-skills" (read-only)
   • •directories.base = "planning/", directories.input = "features/", directories.output = "implementation/"
   • •git.auto_commit = false, git.commit_state_file = true, git.gitignore_patterns = []
   • •execution.default_mode = "ask", execution.auto_tdd = true, execution.task_granularity = "medium"
2. •

   User global config (~/.code-forge.json, if exists) → deep-merge into defaults

3. •

   Project config (<project_root>/.code-forge.json, if exists) → deep-merge (highest priority)

0.3 Validate Configuration

Validation rules:

• •directories.base must NOT contain .. (security risk)
• •directories.base must NOT be a system/source directory (src/, node_modules/, build/, .git/)
• •git.commit_state_file must be boolean (not string "true")
• •execution.default_mode must be one of: "ask", "manual", "auto"

On validation failure: display all errors with descriptions, then continue with system defaults.

0.4 Show Configuration Summary and Continue

Display a brief configuration summary showing:

• •Base/input/output directories
• •Configuration sources detected (system defaults, user config, project config)
• •Resolved file creation path: {base_dir}/{output_dir}/{feature_name}/

Then proceed directly — no "Continue?" confirmation needed.

Error handling:

• •Config file not found → note "using defaults" and continue
• •Config file parse error → show error, fall back to defaults, continue
• •Invalid config values → show warnings, fall back to defaults for invalid fields, continue

0.6 Store Configuration Context

Track resolved values for subsequent steps:

• •config — final merged configuration object
• •project_root — detected project root path
• •base_dir — resolved: <project_root>/<config.directories.base>
• •input_dir — resolved: <base_dir>/<config.directories.input>
• •output_dir — resolved: <base_dir>/<config.directories.output>

Step 0.8: Prompt to Document (Prompt Mode Only)

This step only runs when the input is NOT a file path (does NOT start with @).

If the input starts with @, skip directly to Step 1.

0.8.1 Generate Slug

Convert the prompt text to a kebab-case slug for the filename:

• •ASCII text: lowercase, replace spaces/special chars with hyphens (e.g., "User Login Feature" → user-login-feature)
• •Non-ASCII text (Chinese, Japanese, etc.): use AskUserQuestion to let user confirm or provide a custom slug. Suggest a reasonable English slug based on the prompt meaning.

0.8.2 Check for Existing Document

Check if {input_dir}/{slug}.md already exists:

• •Exists → ask via AskUserQuestion:
  • •"Append to existing document" — append the prompt text under a new ## Additional Requirements section
  • •"Overwrite" — replace the file
  • •"Use existing document as-is" — skip writing, proceed with existing file
• •Does not exist → continue

0.8.3 Generate Minimal Feature Document

Write {input_dir}/{slug}.md with minimal content:

# {Feature Title}

## Requirements

{user's original prompt text, verbatim}

## Notes

- Generated from prompt by code-forge
- Created: {ISO timestamp}

Design principles:

• •Document is minimal — only wraps the user's original text, no AI expansion
• •Expansion and analysis happen in Step 2 (sub-agent) as normal
• •All subsequent steps see a standard file path, unaware of input source

0.8.4 Set File Path

Set the generated file path as the current input document path (prefixed with @), then continue to Step 1.

Step 1: Validate Input Document

1.1 Check Document Path

User should provide an @file path:

/code-forge:plan @planning/features/user-auth.md

Note: Use configured path ({base_dir}/{input_dir}/)

1.2-1.4 Validate Document and Handle Errors

Perform these checks on the provided document:

1. •File exists — if not found, list available files in {input_dir}/ and suggest corrections (check for typos)
2. •File is not empty — if empty, suggest adding requirements content with a minimal example
3. •File is Markdown — if not .md, warn and ask whether to continue as plain text

If no document is provided and Step 0.8 was not triggered: display usage instructions with examples.

On any error: display the issue, suggest a fix, and stop.

1.5 Detect Existing Plan

Check whether <output_dir>/<feature_name>/ already exists:

• •

  Has state.json → Resume mode: show progress summary (task statuses), ask via AskUserQuestion:

  • •Continue (recommended) — resume from current progress
  • •Restart — delete all files and regenerate
  • •View plan — open plan.md
  • •Cancel
• •

  Directory exists but no state.json → Conflict mode: warn about existing files, ask:

  • •Backup and overwrite — move to .backup/ then regenerate
  • •Force overwrite — overwrite directly
  • •Cancel — handle manually then rerun

Step 2: Analyze Document Content (via Sub-agent)

Offload to sub-agent to keep the full document content out of the main context.

Spawn a Task tool call with:

• •subagent_type: "general-purpose"
• •description: "Analyze feature document"

Sub-agent prompt must include:

• •The input document file path (so the sub-agent reads it, NOT the main context)
• •Instruction to return ONLY a structured summary

Sub-agent must analyze and return:

1. •Feature Name — extracted from filename or document title (kebab-case)
2. •Technical Requirements — tech stack, frameworks, languages mentioned
3. •Functional Scope — 2-3 sentence summary of what needs to be implemented
4. •Constraints — performance, security, compatibility requirements
5. •Testing Requirements — testing strategy mentioned, or "not specified"
6. •Key Components — major modules/components to build (bulleted list)
7. •Estimated Complexity — low/medium/high with brief rationale

Main context retains: Only the structured summary returned by the sub-agent (~1-2KB). The full document content stays in the sub-agent's context and is discarded.

Important: Store the returned summary for use in Steps 3 and 6.

Step 3: Ask for Additional Information

If not clearly specified in the document, use a single AskUserQuestion combining up to 3 questions. Skip any question already answered by the document:

Question 1: Technology Stack Confirmation

• •"Use {extracted_tech} mentioned in document"
• •"Use existing project tech stack" — analyze project code, use existing frameworks
• •"Custom" — user specifies

Question 2: Testing Strategy

• •"Strict TDD (Recommended)" — write tests first for each task
• •"Tests After" — implement first, write tests at end
• •"Minimal Testing" — test only core logic

Question 3: Task Granularity

• •"Fine-grained (5-10 tasks)" — each task 1-2 hours
• •"Medium-grained (3-5 tasks)" — each task half day
• •"Coarse-grained (2-3 tasks)" — each task 1-2 days

Step 4: Create Directory Structure

Extract feature name from filename or document title (convert to kebab-case).

Create directory structure and proceed directly — no confirmation needed:

{output_dir}/{feature_name}/
├── overview.md
├── plan.md
├── tasks/
└── state.json

Step 6: Generate plan.md (via Sub-agent)

Offload to sub-agent to keep plan generation output out of the main context.

Spawn a Task tool call with:

• •subagent_type: "general-purpose"
• •description: "Generate implementation plan"

Sub-agent prompt must include:

• •The input document file path (sub-agent re-reads the original for full context)
• •The structured summary from Step 2 (paste it into the prompt)
• •User answers from Step 3 (tech stack choice, testing strategy, task granularity)
• •The output file path: {output_dir}/{feature_name}/plan.md
• •Instructions to write the plan file AND return a concise task list summary

Sub-agent must write plan.md with these required sections:

• •Goal — one sentence describing what to implement
• •Architecture Design — component structure, data flow, technical choices with rationale
• •Task Breakdown — dependency graph (mermaid graph TD) + task list with estimated time and dependencies
• •Risks and Considerations — identified technical challenges
• •Acceptance Criteria — checklist (tests pass, code review, docs, performance)
• •References — related technical docs and examples

Sub-agent must return (as response text, separate from the file it writes) a concise task list summary:

TASK_COUNT: <number>
TASKS:
- <task_id>: <task_title> [depends on: <deps or "none">] (~<estimated_time>)
- <task_id>: <task_title> [depends on: <deps or "none">] (~<estimated_time>)
...
EXECUTION_ORDER: <task_id_1>, <task_id_2>, ...

Main context retains: Only the task list summary (~1-2KB). The full plan content is on disk.

Step 7: Task Breakdown (via Sub-agent)

Offload to sub-agent to keep task file generation out of the main context.

Spawn a Task tool call with:

• •subagent_type: "general-purpose"
• •description: "Generate task breakdown files"

Sub-agent prompt must include:

• •The plan file path: {output_dir}/{feature_name}/plan.md (sub-agent reads it from disk)
• •The task list summary returned by Step 6 (paste it into the prompt)
• •The tasks directory path: {output_dir}/{feature_name}/tasks/
• •All the principles and format requirements below

Sub-agent must create tasks/{name}.md for each task, following these principles:

• •TDD first: test → implement → verify
• •Concrete steps: include code examples and commands
• •Traceable: annotate dependencies (depends on / required by)

Each task file must include:

• •Goal — what this task accomplishes
• •Files Involved — files to create/modify
• •Steps — numbered, with code examples where helpful
• •Acceptance Criteria — checklist
• •Dependencies — depends on / required by
• •Estimated Time

Naming: Use descriptive filenames (setup.md, models.md — no numeric prefixes). Execution order is defined in overview.md and state.json, not in filenames.

Sub-agent must return (as response text) the list of generated files:

GENERATED_FILES:
- tasks/<task_id>.md: <task_title>
- tasks/<task_id>.md: <task_title>
...

Main context retains: Only the file list (~0.5KB). All task file content is on disk.

Step 5: Generate overview.md

Execution order: This step executes AFTER Steps 6 and 7. Use the task list summary returned by the Step 6 sub-agent and the file list returned by the Step 7 sub-agent to populate task-related sections.

Generate feature overview with these required sections:

• •Overview — extract or summarize from source document
• •Scope — included and excluded items
• •Technology Stack — language/framework, key dependencies, testing tools
• •Task Execution Order — table: #, Task File (linked to ./tasks/), Description, Status
• •Progress — total/completed/in_progress/pending counts
• •Reference Documents — link to source document

Step 8: Initialize state.json

Create state.json with these required fields:

Each task object in the tasks array:

Step 8.5: Generate/Update Project-Level Overview

After initializing state.json, generate or update {output_dir}/overview.md — a bird's-eye view of all features.

8.5.1 Scan and Analyze

1. •Scan {output_dir}/*/state.json for all existing features
2. •Read each feature's overview.md and plan.md for descriptions and dependencies
3. •Determine implementation order based on actual dependencies (not alphabetical)

8.5.2 Generate Overview

Create or overwrite {output_dir}/overview.md with these required sections:

• •Overall Progress — progress bar + module counts (completed/in_progress/pending)
• •Module Overview — table: #, Module (linked to directory), Description, Status, Progress
• •Module Dependencies — mermaid dependency graph
• •Recommended Implementation Order — phased with rationale ("Why first", "Why next")

Key principles:

• •Implementation order must reflect actual dependencies
• •Status aggregated from state.json files (not manually maintained)
• •Use relative links to feature directories

8.5.3 When to Regenerate

• •After creating a new feature plan (this step)
• •After feature completion

Display: Project overview updated: {output_dir}/overview.md

Step 9: Display Plan and Next Steps

Output plan summary:

Implementation plan generated

Location: {output_dir}/{feature_name}/
Total Tasks: {count}
Estimated Total Time: {estimate}

Task Overview:
  {id}  - {title}  [{status}]
  ...

Next steps:
  /code-forge:impl {feature_name}     Execute tasks
  /code-forge:status {feature_name}   View progress
  cat {output_dir}/{feature_name}/plan.md   View detailed plan

Integration with Claude Code Tasks

Optionally synchronize tasks to Claude Code's Task system:

• •For each task in execution_order, call TaskCreate with:
  • •subject: "<task_id>: <task_title>"
  • •description: contents of the task file
  • •activeForm: "Implementing <task_title>"

Coordination with Other Skills

• •With /brainstorming: Brainstorm design first → generate feature doc → /code-forge:plan @feature-doc.md
• •With /code-forge:impl: After plan generated → /code-forge:impl {feature} to execute
• •With /code-forge:review: After implementation → /code-forge:review {feature} to review

Notes

1. •Document Quality: The more detailed the input document, the more accurate the generated plan
2. •Prompt Mode: When using prompt mode, the generated document is minimal. Step 2 sub-agent analysis handles expansion.
3. •Git Commits: Recommend committing the planning directory and .code-forge.json to Git for team visibility
4. •State Files: state.json can be optionally committed or added to .gitignore
5. •Task Granularity: Recommend 1-3 hours per task for easy tracking
6. •Dependency Management: Dependencies between tasks affect execution order
7. •Project Overview: The project-level overview.md in {output_dir}/ is auto-generated and shows all features, dependencies, and recommended implementation order
8. •Tool Discovery: .code-forge.json contains a _tool section with the plugin URL — new team members can find and install the tool from there
9. •Status Definitions: pending, in_progress, completed, blocked, skipped
10. •Directory Structure:
    code

    planning/
    ├── features/              # Input: feature documents
    │   └── user-auth.md
    └── implementation/        # Output: implementation plans
        ├── overview.md        # Project-level overview (auto-generated)
        └── {feature}/         # Per-feature directory
            ├── overview.md    # Feature overview + task execution order
            ├── plan.md        # Implementation plan
            ├── tasks/         # Task breakdown files
            └── state.json     # Status tracking
    

11. •Naming Conventions: Feature directories use kebab-case (user-auth). Task files use descriptive names (setup.md). No "claude-" or tool prefixes. Suitable for Git commits.