Code Forge — Impl

Execute pending implementation tasks for a feature, following the plan generated by /code-forge:plan.

When to Use

•Have a generated plan (state.json + tasks/ directory) ready for execution
•Need to resume a partially completed feature
•Need task-by-task execution with TDD and progress tracking

Workflow

code

Locate Feature → Confirm Execution → Task Loop (sub-agents) → Verify → Complete

Context Management

Step 11 dispatches a dedicated sub-agent for each task, so code changes from one task don't pollute the context of the next. The main context only handles coordination: reading state, dispatching sub-agents, and updating status.

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:

code

.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):

•
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"
•
User global config (~/.code-forge.json, if exists) → deep-merge into defaults
•
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)

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

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 1: Locate Feature

1.1 With Feature Name Argument

If the user provided a feature name (e.g., /code-forge:impl user-auth):

•Look for {output_dir}/{feature_name}/state.json
•If not found, search {output_dir}/*/state.json for a feature whose feature field matches
•If still not found, show error: "Feature '{feature_name}' not found. Run /code-forge:status to see available features."

1.2 Without Argument

If no feature name is provided:

•Scan {output_dir}/*/state.json for all features
•Filter to features with status = "pending" or "in_progress" (exclude "completed")
•If none found: "No features ready for execution. Run /code-forge:plan to create one."
•If one found: use it automatically
•If multiple found: display table and use AskUserQuestion to let user select

1.3 Validate Feature State

After locating the feature:

•Read state.json
•Check that tasks array is non-empty
•Check that task files in tasks/ directory exist
•Show feature progress summary: completed/in_progress/pending counts
•If all tasks are "completed": "All tasks already completed. Run /code-forge:review {feature} to review."

Step 10: Ask for Execution Method

Use AskUserQuestion:

•"Start Execution Now (Recommended)" — execute tasks one by one, auto-track progress → enter Step 11
•"Manual Execution Later" — save plan, show resume instructions (/code-forge:impl {feature})
•"Team Collaboration Mode" — show guidelines: commit plan to Git, claim tasks via assignee, sync state.json
•"Generate Plan Only" — only generate plan files, stop here

Step 11: Task Execution Loop (via Sub-agents)

Each task is executed by a dedicated sub-agent to prevent cross-task context accumulation. The main context only handles coordination: reading state, dispatching sub-agents, and updating status.

11.1 Coordination Loop (Main Context)

•Read state.json
•Find the next task in execution_order that is "pending" with no unmet dependencies
•If no such task exists: display "All tasks completed!" and exit loop
•Display: "Starting task: {id} - {title}"
•Update task status to "in_progress" in state.json
•Dispatch sub-agent for this task (see 11.2)
•Review the sub-agent's execution summary
•
Ask user via AskUserQuestion: "Is the task completed?"
- •"Completed, continue to next" → update status to "completed", continue loop
- •"Encountered issue, pause" → keep "in_progress", exit loop
- •"Skip this task" → update status to "skipped", continue loop
•Repeat from step 1

11.2 Task Execution Sub-agent

Spawn a Task tool call with:

•subagent_type: "general-purpose"
•description: "Execute task: {task_id}"

Sub-agent prompt must include:

•The task file path: {output_dir}/{feature_name}/tasks/{task_id}.md (sub-agent reads it)
•The project root path
•Tech stack and testing strategy (from state.json metadata or plan.md)
•Instruction to follow TDD: write tests → run tests → implement → verify
•Instruction to return ONLY a concise execution summary

Sub-agent executes:

•Read the task file from disk
•Follow the task steps (TDD: write tests → run tests → implement → verify)
•Commit changes if all tests pass (with descriptive commit message)

Sub-agent must return a concise execution summary:

code

STATUS: completed | partial | blocked
FILES_CHANGED:
- path/to/file.ext (created | modified)
- ...
TEST_RESULTS: X passed, Y failed
SUMMARY: <1-2 sentence description of what was done>
ISSUES: <any blockers or concerns, or "none">

Main context retains: Only the execution summary (~0.5-1KB per task). All code changes, test outputs, and file reads stay in the sub-agent's context and are discarded.

11.3 Parallel Execution (Optional)

When multiple pending tasks have no mutual dependencies (none depends on another), they may be dispatched as parallel sub-agents using multiple Task tool calls in a single message. Each sub-agent works in isolation on its own task.

Use parallel execution only when:

•Tasks modify different files (no overlap in "Files Involved")
•Tasks have no dependency relationship (neither depends on the other)
•User has agreed to parallel execution

After all parallel sub-agents complete, review each summary and update state.json for all completed tasks before continuing the loop.

Step 11.5: Verify Generated Files

Before completion summary, verify all generated files:

Checks:

•Required files exist and are non-empty: overview.md, plan.md, state.json
•tasks/ directory exists and contains .md files with descriptive names
•state.json is valid JSON with required fields (feature, status, tasks, execution_order); task count matches task files; all IDs in execution_order match tasks entries
•plan.md contains: title heading, ## Goal, ## Task Breakdown, ## Acceptance Criteria
•overview.md contains ## Task Execution Order table

On pass: Show checklist with all items passing, continue.

On error (missing required files): Show what's missing. Attempt auto-fix:

•Empty overview.md → generate template from plan data
•Missing tasks/ → create directory
•Missing state.json → generate initial state from task files found Then re-verify.

On warnings (count mismatch, missing optional section): Show warnings, continue by default.

Step 12: Completion Summary

After all tasks are completed:

•Update state.json with final status
•Regenerate the project-level overview ({output_dir}/overview.md)

code

Feature implementation completed!

Completed tasks: {completed}/{total}
Location: {output_dir}/{feature_name}/
Total time: {actual_time}

Next steps:
  /code-forge:review {feature_name}   Review code quality
  /code-forge:status {feature_name}   View final status