tercel/code-forge/impl

Code Forge — Impl

⚡ Execution Entry Point

@../shared/execution-entrypoint.md

For this skill: start at Step 1. If you catch yourself about to say "falling back to manual implementation", STOP and go to the indicated step.

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
• Multi-repo: Same feature planned across multiple language repos (e.g., Python + TypeScript + Rust)

Examples

/code-forge:impl user-auth          # Execute tasks for user-auth feature
/code-forge:impl                    # Auto-detect pending feature
/code-forge:impl core-dispatcher --repos ~/apcore-python ~/apcore-typescript ~/apcore-rust

Workflow

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

Context Management

Step 3 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

@../shared/configuration.md

Step 0.1: Detect Multi-Repo Mode

If $ARGUMENTS does not contain --repos, skip this step and continue below.

If --repos is present: first, resolve <cf_scripts> per Locating the script layer (the configuration step). The code-forge install directory <cf_install> is its grandparent (<cf_scripts>/../.. — the folder that contains skills/); this is the install, not the user's project. Then dispatch Agent(subagent_type="general-purpose", description="Impl --repos coordinator") with prompt containing the resolved absolute paths:

Read these two files and follow them exactly:

1. <cf_install>/skills/shared/multi-repo.md — the protocol steps MR-1~MR-5

2. <cf_install>/skills/impl/multi-repo-defs.md — the impl-specific definitions

The code-forge scripts are at <cf_install>/skills/shared/scripts/ — pass this absolute path to each repo sub-agent.

User arguments: $ARGUMENTS

Then stop — do not continue to Step 0.5.

Step 0.5: Project Analysis

Before executing tasks, ensure the project context is understood:

@../shared/project-analysis.md

Execute PA.1 (Project Profile), PA.3 (Language-Specific Deep Scan for the feature's modules), and PA.5 (Existing Test Assessment). This context is passed to each task sub-agent so they:

• Write tests using the CORRECT framework and patterns
• Follow the project's ACTUAL architecture (not assumed patterns)
• Handle language-specific constructs properly (Rust lifetimes, Go error chains, etc.)

Step 1: Locate Feature

1.1 With Feature Name Argument

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

1. Look for {output_dir}/{feature_name}/state.json
2. If not found, search {output_dir}/*/state.json for a feature whose feature field matches
3. If not found in output_dir, also search `.code-forge/tmp/{feature_name}/state.json` and .code-forge/tmp/*/state.json (plan may have been created with --tmp)
4. If still not found, show error: "Feature '{feature_name}' not found. Run /code-forge:status to see available features."

If found in .code-forge/tmp/, set output_dir to .code-forge/tmp/ and tmp_mode to true for the rest of the session.

1.2 Without Argument

If no feature name is provided:

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

1.3 Validate Feature State

After locating the feature:

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

Step 2: Ask for Execution Method

Use AskUserQuestion:

• "Start Execution Now (Recommended)" — execute tasks one by one, auto-track progress → enter Step 3
• "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
• "View Plan Details" — display plan.md contents for review before executing

Step 3: 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.

3.1 Coordination Loop (Main Context)

Deterministic state operations: use the state helper for every state.json read and mutation in this loop — it recomputes progress, fixes timestamps, and derives the next runnable task without pulling the whole file into context. Resolve <cf_scripts> once (see Locating the script layer in the configuration step) and quote paths, then:

• Next task: python3 "<cf_scripts>/cf-state.py" next "<state.json>" → prints

id\ttitle, or ALL_DONE.

• Set status: python3 "<cf_scripts>/cf-state.py" set-status "<state.json>" <id> <status>

(status ∈ in_progress|completed|skipped|blocked|pending).

• Quick view: python3 "<cf_scripts>/cf-state.py" show "<state.json>".

If python3 is unavailable, fall back to editing state.json by hand (set the task status, fix started_at/completed_at, recompute the progress block and the feature-level status).

1. Get the next runnable task: cf-state.py next <state.json>
2. If it prints ALL_DONE: display "All tasks completed!" and exit loop
3. Display: "Starting task: {id} - {title}"
4. cf-state.py set-status <state.json> {id} in_progress
5. Dispatch sub-agent for this task (see 3.2)
6. Review the sub-agent's execution summary
7. Ask user via AskUserQuestion: "Is the task completed?"

• "Completed, continue to next" → set-status {id} completed, continue loop
• "Encountered issue, pause" → set-status {id} blocked (or leave in_progress), exit loop
• "Skip this task" → set-status {id} skipped, continue loop

1. Repeat from step 1

3.2 Task Execution Sub-agent

Spawn an Agent 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
• Coding standards (mandatory): include the following standards in the sub-agent prompt so it writes quality code from the start:

@../shared/coding-standards.md

• Design discipline (mandatory): include the following discipline in the sub-agent prompt. The sub-agent MUST run the four-question pre-code checklist before writing any production code, and MUST prefer refactoring existing structure over adding patches/wrappers/parallel modules. This is the upstream defense against incremental bloat:

@../shared/design-first.md

• Instruction to return ONLY a concise execution summary

Sub-agent executes:

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

Sub-agent must return a concise execution summary:

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.

3.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 Agent 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 4: Verify Generated Files

Before completion summary, verify all generated files:

Fast path: run the structural validator and act on its result:

python3 "<cf_scripts>/cf-verify-plan.py" "<output_dir>/<feature>" --output-dir "<output_dir>"

It prints a PASS/FAIL/WARN checklist and exits non-zero on any structural error (missing/empty required files, invalid or inconsistent state.json, a referenced task file that is missing). Treat content-section gaps as warnings. On a non-zero exit, apply the auto-fixes below and re-run. If python3 is unavailable, run the checks by hand.

Checks (the validator covers all of these):

1. Required files exist and are non-empty: overview.md, plan.md, state.json
2. tasks/ directory exists and contains .md files with descriptive names
3. 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
4. plan.md contains: title heading, ## Goal, ## Task Breakdown, ## Acceptance Criteria
5. 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 5: Completion Summary

After all tasks are completed:

1. Finalize state.json: python3 "<cf_scripts>/cf-state.py" recompute "<state.json>" (recomputes the progress block and sets the feature-level status). Fall back to editing by hand if python3 is unavailable.
2. Regenerate the project-level overview ({output_dir}/overview.md)

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:verify                                       Verify all tests pass
  /code-forge:finish {feature_name}                        Merge / create PR