spec-implement

Coordinate worker skills (spec-code, spec-review, spec-test) to implement from specifications to pull request. This skill does NOT write code or review — it delegates.

Language Rules

1. Auto-detect input language → output in the same language
2. Japanese input → Japanese output, use references/implement-guide.ja.md
3. English input → English output, use references/implement-guide.md
4. Explicit override takes priority

Options

| Option | Description | |--------|-------------| | --resume | Resume from last uncompleted task in tasks.md | | --issue {N} | Specify GitHub Issue number for context | | --spec {path} | Specify .specs/ directory path (default: auto-detect) | | --dry-run | Show execution plan without making any changes | | --roles {map} | Per-task owner routing by kind. Format: ui=claude,backend=codex,test=codex, or a path to a pipeline.yml whose roles.impl_{kind} keys supply the mapping. Omitted → every task uses spec-code and every review uses spec-review (legacy behavior, no agent-delegate involvement). | | --host-runtime {claude\|codex} | Runtime executing this skill. Required with --roles; the orchestrator passes its recorded host_runtime so AI role and execution backend are resolved separately. | | --review-fallback {block\|native-independent} | Review-only capability policy for the --roles path. Default block preserves standalone behavior. native-independent lets a missing cross-AI reviewer fall back to a fresh, read-only runtime-native reviewer subagent; spec-orchestrate passes this explicitly. |

Role: Orchestrator Only

🚨 BLOCKING — This rule overrides everything below.

This skill is an orchestrator. It coordinates worker skills but does NOT perform work itself.

• Do NOT write implementation code yourself. Always delegate to spec-code.
• Do NOT perform code reviews yourself. Always delegate to spec-review.
• Do NOT write tests yourself. Always delegate to spec-test.

If a worker skill is not installed, stop and suggest installation. Never fall back to doing it yourself.

Critical First Steps

BEFORE any implementation, execute these checks in order:

1. Verify environment: pwd, git status, gh auth status

2. Parse user input: Extract --resume, --issue, --spec, --dry-run, --roles, and --host-runtime options

3. Check cmux availability:

   echo $CMUX_SOCKET_PATH
   

   If set → record that cmux dispatch is available as an external-pane option.

4. Check runtime-native agent availability:

   ls .codex/agents/workflow-*.toml 2>/dev/null
   ls .claude/agents/workflow-*.md 2>/dev/null
   

   If running in Codex and .codex/agents/workflow-*.toml exists → prefer runtime-native Codex sub-agents over cmux for workflow roles. Codex discovers custom agents from .codex/agents/*.toml; do not require [agents.<name>] config_file entries. If running in Claude Code and .claude/agents/workflow-*.md exists → prefer Claude Code agent team over cmux for workflow roles only when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set. If it is not set, use normal Claude Code subagents or single-agent sequential mode.

5. Locate spec directory 🚨 BLOCKING:

   • If --spec provided → verify the path exists, then use it
   • Always scan .specs/ regardless of whether Issue body contains a path:

     find .specs -maxdepth 2 -name "tasks.md" 2>/dev/null
     

   • If a matching spec directory is found → use it and proceed
   • If no .specs/ found → ask user via AskUserQuestion:

     question: "No spec directory found. Where are your specifications?" /
               "仕様書ディレクトリが見つかりません。仕様書の場所を教えてください。"
     options:
       - "Specify path manually" / "パスを手動で指定する"
       - "Generate specs with spec-generator" / "spec-generator で仕様書を生成する"
     

     • If user specifies a path → verify it exists and use it
     • If user chooses spec-generator → stop and instruct: Run /spec-generator first, then re-run /spec-implement
   • Do NOT proceed to Phase 5 (branch creation) until a valid spec directory is confirmed.

6. Locate and read project files:

   • Workflow: docs/development/issue-to-pr-workflow.md → docs/ → find → fallback
   • Coding rules: docs/development/coding-rules.md → docs/ → find → fallback
   • Review rules: docs/development/review_rules.md → docs/ → find → optional
   • Project instructions: CLAUDE.md, AGENTS.md
   • Spec files: requirement.md, design.md, tasks.md

Execution Flow

Phase 1-3: Load Context

Read workflow, coding rules, and project instructions. Same search/fallback logic as before — see references/implement-guide.md for details.

Extract from workflow:

• Base branch (default: main)
• Branch naming convention
• Commit message format
• Test/lint/build commands
• Dispatch strategy and agent definitions (if present)

Phase 4: Issue Analysis

If --issue {N} is provided:

gh issue view {N} --json title,body,labels,assignees

Phase 5: Branch Creation

🚨 BLOCKING — Feature branch is MANDATORY

git checkout {base_branch} && git pull origin {base_branch}
git checkout -b feature/issue-{N}-{brief-description}

Post-creation verification — MUST NOT be on main, master, or develop.

Phase 6: Task Loop (Orchestration)

Read tasks.md and process phases by role tag:

If a phase has NO role tag (legacy specs without [code]/[orchestrator]), treat it as [code] by default. This ensures backward compatibility with specs generated before v3.

Review gate phases: Phases with -R suffix (e.g., Phase 2-R: Review Gate [orchestrator]) are review gates. When processing these, run spec-review + spec-test for each task in the preceding [code] phase.

for each phase in tasks.md:
  if phase has [orchestrator] tag AND phase name contains "Review Gate":
    // This is a review gate — run spec-review + spec-test for preceding [code] tasks
    for each task in the preceding [code] phase:
      invoke spec-review --task {task-id} --spec {path}
      read review result → if FAIL, run fix loop (spec-code --feedback → re-review, max 3)
      invoke spec-test --task {task-id} --spec {path}
      read test result → if FAIL, run fix loop (spec-code --feedback → re-test)
      if review PASS AND test PASS: mark review gate task checkbox

  elif phase has [orchestrator] tag:
    execute tasks directly (run commands, check results — do NOT modify files)

  elif phase has [code] tag (or NO tag — legacy fallback):
    for each unchecked task in phase:
      // Implement only — review/test happens in the Review Gate phase
      invoke spec-code --issue {N} --task {task-id} --spec {path}
      mark task checkbox: - [ ] → - [x]
      commit progress

Dispatch modes:

When invoking worker skills, the method depends on execution mode:

| Mode | How to invoke | |---|---| | Single agent | Call the skill directly in the current session | | Codex sub-agents | Spawn the workflow custom agent by the Agent column value (e.g., workflow-implementer) and instruct it to run /spec-code, /spec-review, or /spec-test for the assigned task | | Claude Code agent team | Ask Claude Code to create an agent team with teammates based on the Agent column values (e.g., workflow-implementer) and assign /spec-code, /spec-review, or /spec-test tasks to those teammates | | cmux dispatch | Use cmux-delegate --agent {ai} --task "/spec-code --issue {N} --task {id} --spec {path}" when external panes are explicitly selected or runtime-native agents are unavailable |

Mode priority:

1. If running in Codex and .codex/agents/workflow-*.toml exists → use Codex sub-agents by default
2. If running in Claude Code, .claude/agents/workflow-*.md exists, and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set → use Claude Code agent team by default
3. If cmux is available and the workflow/user explicitly selects cmux → use cmux dispatch
4. Otherwise use single-agent sequential execution

This priority applies to the legacy path without --roles. When --roles is active, Phase 6b's host-aware capability fallback takes precedence: report an unavailable native worker to the caller and do not silently switch to cmux or single-agent execution.

For Codex sub-agents:

1. Validate .codex/agents/workflow-implementer.toml, .codex/agents/workflow-reviewer.toml, and .codex/agents/workflow-tester.toml exist when referenced by the workflow
2. Use the Agent column value as the custom agent type
3. Do not inline the TOML content into the prompt; Codex loads developer_instructions from the custom agent file
4. Pass only task-specific context: issue, spec path, task id, relevant files, and expected artifact/result

For Claude Code agent team:

1. Validate .claude/agents/workflow-implementer.md, .claude/agents/workflow-reviewer.md, and .claude/agents/workflow-tester.md exist when referenced by the workflow
2. Verify CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set
3. Ask Claude Code to create an agent team with predictable teammate names and to use the workflow agent definitions by Agent column value
4. Do not inline the Markdown agent definition into the prompt when Claude Code can select that agent directly
5. Pass task-specific context: issue, spec path, task id, relevant files, dependencies, expected artifact/result, and file ownership to avoid conflicts

For cmux dispatch:

1. Read workflow's dispatch strategy and agent definition file paths
2. Map roles to agents (implementer/tester → cmux-delegate, reviewer → cmux-second-opinion)
3. Pass skill commands — worker skills handle their own context loading

Phase 6b: Kind-Based Task Routing (--roles)

This layer sits on top of the Phase 6 loop and only activates when --roles is provided (orchestrated mode). Without --roles, every task uses spec-code and every review uses spec-review — identical to legacy behavior, with no agent-delegate involvement. The loop's control flow (per-phase iteration, fix loop with its 3-iteration cap, gate evaluation, checkbox marking, spec-test) is unchanged; only the executor of each step is resolved per task.

Owner resolution (per task):

1. Read the task's kind: field (ui | backend | test) from its detail block in tasks.md.
2. owner = roles[kind] when kind is known and present in the map; otherwise claude (default).
3. Treat owner as the implementer AI role, not the backend.
4. Resolve the executor from --host-runtime:
   • owner == host_runtime → run spec-code in a runtime-native subagent; do not start agent-delegate.
   • owner != host_runtime → run the agent-delegate script with --mode delegate --target <owner> --detach. Retain the expected run id and use the contract's 15–30-second report-first state wait. Re-evaluate at 30-minute intervals and apply the contract's controlled stop at 2 hours.

Reviewer inversion (review gate): choose the preferred reviewer as the opposite AI role from the task's implementer, then resolve that reviewer through the same host-aware matrix:

| Implementer AI role | Reviewer AI role | |---|---| | codex | claude | | claude | codex |

Matching reviewer and host use a runtime-native spec-review subagent; differing roles use agent-delegate --mode review --target <reviewer> (sync only with a concrete <=5-minute basis; otherwise detach). Fixes route to the implementer AI role and resolve through the same matrix again. An agent-delegate review file is spec-review-compatible (severity sections + Gate: PASS|FAIL), so the existing fix loop consumes it unchanged.

If that cross-AI reviewer is unavailable, the default --review-fallback block reports a blocker. Only native-independent may continue with the host AI role, and only by spawning a fresh runtime-native reviewer subagent that is not the implementer instance, does not resume or receive the implementation conversation, has no write tools, and leaves the workspace unchanged. If that independent native reviewer cannot be created, block. Each use is recorded in orchestrator state and the PR body; never disguise it as cross-AI review. To preserve state ownership, spec-implement returns one structured fallback record per use to its caller. spec-orchestrate appends those records to state and the PR; a standalone caller shows them in the completion summary without writing pipeline state.

agent-delegate is a public-contract dependency: call the script per agent-delegate/references/contract.md and always pass --target explicitly (the contract's nested-chain caveat forbids self-detection for programmatic callers). See references/implement-guide.md → "Kind-Based Task Routing" for invocation details, expected-run polling, sandbox stages, resume, and unavailable-peer fallback.

Phase 7: Final Quality Gate

After all tasks complete:

1. Run test commands from workflow (or language defaults)
2. Run lint/typecheck commands (if specified)
3. Verify all tasks in tasks.md are checked
4. If any check fails → fix via spec-code --feedback → recheck

Phase 8: PR Creation

Treat the PR body as a review index, not an audit log, specification, or implementation diary. Before composing it, inspect the repository's pull request template and PR-writing rules. When a project template exists, preserve its headings, order, required fields, and checkboxes.

Select only facts whose removal would change a reviewer's judgment about correctness, risk, scope, verification, or merge readiness. Summarize changed behavior, design rationale, affected scope, known constraints, verification, and review focus. Keep complete review rounds, all findings, acceptance tables, evidence manifests, task progress, and arbitration history in their durable local records; do not copy them wholesale into the PR body.

When no project template exists, use headings that serve these roles: summary, background or reason, changes, verification, known constraints, and review focus.

gh pr create \
  --title "{type}: {description} (closes #{N})" \
  --body "{PR body following workflow template}" \
  --base {base_branch}

Safety guards:

• Do NOT create PR if tests are failing
• Do NOT force push or push to main/master
• Verify base branch matches workflow

Deferred findings: for each review finding carried with fix_before: trial / required_check / follow_up, create a follow-up issue (gh issue create — finding text, severity, fix_before stage, file/section, link back to the PR; same-class findings may share one issue). Keep the full finding in that Issue. Put only the Issue link, its effect on changed behavior, and why the current PR can land before the follow-up in the PR body. If issue creation fails or gh is unavailable, keep the full finding text in the PR body with a warning — a deferred finding must never survive only in a run record.

Summarize a review fallback in the PR only when it reduces review assurance. State the preferred and actual reviewer roles, why the fallback occurred, and its effect on merge judgment; do not dump every structured fallback record.

Error Handling

| Situation | Response | |---|---| | Not a git repository | Error: must be in a git repository | | gh CLI not available | Error: guide user to install/auth | | .specs/ not found | 🚨 BLOCKING: ask user for path or suggest spec-generator | | requirement.md missing | Warning: use Issue body as requirements | | tasks.md missing | Warning: generate simple checklist from Issue | | On protected branch | 🚨 BLOCKING: stop, require feature branch | | Worker skill not installed | Error: suggest npx skills add anyoneanderson/agent-skills --skill {name} | | --roles provided without a valid --host-runtime | Report a configuration blocker to the orchestrator. Standalone: ask the user for claude or codex; do not guess | | Runtime-native subagent unavailable for an owned task | Report the blocker to the orchestrator, which applies its manual/auto role fallback. Standalone: ask before reassigning the AI role | | agent-delegate unavailable for cross-AI implementation (script missing / exit 2 / tool_unavailable) | Report the blocker to the orchestrator, which applies its manual/auto owner fallback. Standalone: ask before reassigning to the host AI | | agent-delegate unavailable for cross-AI review | With default --review-fallback block, report a blocker. With explicit native-independent, use a fresh read-only host-native reviewer subagent and record the degraded review; if that subagent is unavailable, block | | Review FAIL after 3 iterations | Ask user to decide | | Test FAIL after fix attempt | Ask user to decide |

Post-Completion Actions

AskUserQuestion:
  question: "PR created. What's next?" / "PRを作成しました。次は？"
  options:
    - "Monitor CI status" / "CIステータスを監視"
    - "Done" / "完了"