code-forge

name	code-forge
description	Complete Codex development workflow for turning requirements, feature docs, or prompts into working code. Use when the user asks to plan implementation work, execute tasks, enforce TDD, review code, fix bugs, debug failures, verify completion, manage worktrees or branch finishing, dispatch parallel agents, port a project to another language, check progress, or run an end-to-end build flow. Supports complex orchestration across plan -> impl -> review -> fix -> verify, plus build, forge smart dispatch, worktree, finish, parallel, port, tdd, debug, and status workflows.
version	1
subcommands	["build","forge","plan","impl","status","review","fix","debug","tdd","verify","worktree","finish","parallel","port"]

Code Forge Orchestrator

Code Forge is a development execution workflow suite. This root skill is the Codex-facing orchestrator: decide which child skill or command workflow to load, preserve the planning/execution contract, and avoid loading large references until they are needed.

Trigger Patterns

Use this skill when the user asks for any of the following:

• End-to-end implementation from spec or prompt: use commands/build.md
• Smart natural-language dispatch to a code-forge workflow: use commands/forge.md
• Generate an implementation plan from docs, a directory, or a prompt: use skills/plan/SKILL.md
• Execute pending feature tasks or resume work: use skills/impl/SKILL.md
• Check feature or project progress: use skills/status/SKILL.md
• Review code quality, handle feedback, or post a GitHub PR review: use skills/review/SKILL.md
• Debug and fix bugs with upstream trace-back: use skills/fix/SKILL.md
• Investigate root cause for untracked bugs or failures: use skills/debug/SKILL.md
• Enforce Red-Green-Refactor for ad-hoc implementation: use skills/tdd/SKILL.md
• Verify work before claiming done: use skills/verify/SKILL.md
• Create isolated git worktrees: use skills/worktree/SKILL.md
• Merge, PR, keep, or discard completed branch work: use skills/finish/SKILL.md
• Dispatch independent problems to parallel agents: use skills/parallel/SKILL.md
• Port a documentation-driven project to a new language: use skills/port/SKILL.md

Also treat slash-like requests as aliases:

User request	Route
/code-forge:build ... or /build ...	Build
/code-forge:forge ... or /forge ...	Smart dispatch
/code-forge:plan ... or /plan ...	Plan
/code-forge:impl ... or /impl ...	Impl
/code-forge:status ... or /status ...	Status
/code-forge:review ... or /review ...	Review
/code-forge:fix ... or /fix ...	Fix
/code-forge:debug ... or /debug ...	Debug
/code-forge:tdd ... or /tdd ...	TDD
/code-forge:verify or /verify	Verify
/code-forge:worktree ... or /worktree ...	Worktree
/code-forge:finish or /finish	Finish
/code-forge:parallel or /parallel	Parallel
/code-forge:port ... or /port ...	Port

The commands/*.md files are compatibility command definitions from the Claude-oriented implementation. In Codex, prefer reading the child skills/*/SKILL.md files directly for single-skill routes. Use commands/build.md and commands/forge.md because those are orchestrator workflows, not child skill directories.

Progressive Loading

Keep context small.

1. Read this root file first.
2. Read only the child SKILL.md or commands/*.md file matching the user's request.
3. When a child skill references skills/shared/execution-entrypoint.md, read it before acting.
4. Read skills/shared/configuration.md when the workflow needs .code-forge.json or output/input directory resolution.
5. Read skills/shared/project-analysis.md when the workflow needs codebase awareness.
6. Read skills/shared/design-first.md before code-writing workflows that must avoid patch-first implementation.
7. Read skills/shared/multi-repo.md only when --repos or multi-repo work is requested.

The skills/shared/scripts/ layer (Python 3, stdlib only) absorbs deterministic bookkeeping so it does not cost tokens or risk hand-merge errors: cf-config.py (config resolution), cf-state.py (state.json read/mutate), cf-status.py (dashboard rendering), cf-verify-plan.py (plan structure validation), and cf-scan.py (project facts collection). The skills that use them invoke them on a fast path and keep a manual fallback. See skills/shared/scripts/README.md.

Do not bulk-load every child skill. Do not read all shared references just because the suite is complex.

Global Rules

• Preserve the user's requested language for user-facing responses.
• Prefer existing project conventions, test frameworks, architecture, and helper APIs.
• Never claim work is done without fresh verification evidence. Use skills/verify/SKILL.md.
• Code changes must be design-first and test-disciplined. For ad-hoc work, use skills/tdd/SKILL.md.
• For bugs, investigate root cause before fixing. Use fix for code-forge tracked features and debug for untracked problems.
• Avoid bloat: modify existing abstractions when appropriate instead of adding wrappers, duplicate modules, or parallel implementations.
• Respect dirty worktrees. Do not revert user changes unless explicitly asked.
• Keep code-forge outputs in the configured output directory, default planning/, unless --tmp or config says otherwise.
• Preserve planning state files and task names because downstream impl, status, review, and fix depend on them.
• Ask only necessary questions. If config, docs, state files, or code provide the answer, use them and state the assumption.

Shared References

Use these references only when relevant:

• skills/shared/execution-entrypoint.md: common execution start rules.
• skills/shared/configuration.md: .code-forge.json, directory hierarchy, and defaults.
• skills/shared/project-analysis.md: project scan protocol for codebase-aware workflows.
• skills/shared/design-first.md: anti-bloat design discipline before implementation.
• skills/shared/coding-standards.md: implementation standards.
• skills/shared/overview-generation.md: generated overview structure.
• skills/shared/multi-repo.md: multi-repo orchestration.
• skills/shared/scripts/: deterministic Python helpers (config, state, status) with a README and per-skill fast-path/fallback wiring.

Main Workflows

Build

Read commands/build.md.

Use when the user wants an end-to-end pipeline from a feature spec, tech design, feature name, or plain prompt to working code. The build flow orchestrates:

requirement understanding -> test cases -> plan -> impl -> review -> verify

Confirm before moving between major stages when the command workflow requires it.

Forge Smart Dispatch

Read commands/forge.md.

Use when the user gives a natural-language code-forge request and expects routing. Classify intent, print one routing line, then load the selected skill.

Plan

Read skills/plan/SKILL.md.

Use for turning a spec, feature doc, directory selection, or prompt into a multi-file implementation plan. Mandatory outputs are:

• {output_dir}/{feature}/overview.md
• {output_dir}/{feature}/plan.md
• {output_dir}/{feature}/tasks/*.md
• {output_dir}/{feature}/state.json
• project-level {output_dir}/overview.md

Default output_dir is planning/, unless configuration or --tmp changes it.

Impl

Read skills/impl/SKILL.md.

Use for executing pending tasks from a code-forge plan. It depends on state.json and tasks/*.md. It supports resume and --repos multi-repo execution.

Status

Read skills/status/SKILL.md.

Use for dashboards, progress checks, "what's left", or feature detail.

Review

Read skills/review/SKILL.md.

Use for feature review, project review, feedback response, or GitHub PR review. Respect review modes such as --project, --feedback, --github-pr, and --save.

Fix

Read skills/fix/SKILL.md.

Use for bugs, review batch-fixes, and code-forge tracked issues. It traces root cause across code, task, plan, and requirements, then applies a TDD fix and syncs upstream documents where needed.

Debug

Read skills/debug/SKILL.md.

Use for untracked bugs, failures, and root-cause questions. It requires investigation before fixes.

TDD

Read skills/tdd/SKILL.md.

Use for ad-hoc implementation or implementing test cases outside impl. Honor driven mode from @test-cases.md, auto-analysis mode, and standalone mode.

Verify

Read skills/verify/SKILL.md.

Use before claiming completion, fixed status, passing tests, or build success.

Worktree

Read skills/worktree/SKILL.md.

Use when starting feature or hotfix work in an isolated git worktree. Verify the worktree directory is git-ignored when project-local.

Finish

Read skills/finish/SKILL.md.

Use when branch work is complete and the user wants to merge, create a PR, keep, or discard the branch/worktree.

Parallel

Read skills/parallel/SKILL.md.

Use only for independent problems that can safely run concurrently. If problems share files, state, or dependencies, run sequentially.

Port

Read skills/port/SKILL.md.

Use for cross-language or multi-language project ports from documentation and/or a reference implementation.

Output Locations

Default locations:

• Configuration: .code-forge.json
• Plans: planning/{feature}/
• Temporary plans: .code-forge/tmp/{feature}/
• Feature overview: planning/{feature}/overview.md
• Feature plan: planning/{feature}/plan.md
• Tasks: planning/{feature}/tasks/*.md
• State: planning/{feature}/state.json
• Project overview: planning/overview.md
• Worktrees: .worktrees/{feature}/ or configured/global worktree directory

If .code-forge.json changes these directories, follow the configuration and state the location used.

Completion Criteria

Before finishing a code-forge task:

• Confirm the requested plan, code change, report, status, or branch action was completed, or explain the blocker.
• Mention the exact files changed or generated.
• For code changes, report the verification command and result.
• For plan/status workflows, report the planning directory and next executable action.
• For review/fix/debug workflows, summarize findings or root cause with concrete file references.
• For build workflows, summarize which stages completed and which stage is next or blocked.