Spec Implement

spec-implement — Orchestrator for Spec-Driven Implementation

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

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

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

Post-Completion Actions

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