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

Auto-detect input language → output in the same language
Japanese input → Japanese output, use references/implement-guide.ja.md
English input → English output, use references/implement-guide.md
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:

Verify environment: pwd, git status, gh auth status
Parse user input: Extract --resume, --issue, --spec, --dry-run, --roles, and --host-runtime options
Check cmux availability:
```
echo $CMUX_SOCKET_PATH
```
If set → record that cmux dispatch is available as an external-pane option.
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.
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.
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:

If running in Codex and .codex/agents/workflow-*.toml exists → use Codex sub-agents by default
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
If cmux is available and the workflow/user explicitly selects cmux → use cmux dispatch
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:

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

For Claude Code agent team:

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

For cmux dispatch:

Read workflow's dispatch strategy and agent definition file paths
Map roles to agents (implementer/tester → cmux-delegate, reviewer → cmux-second-opinion)
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):

Read the task's kind: field (ui | backend | test) from its detail block in tasks.md.
owner = roles[kind] when kind is known and present in the map; otherwise claude (default).
Treat owner as the implementer AI role, not the backend.
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:

Run test commands from workflow (or language defaults)
Run lint/typecheck commands (if specified)
Verify all tasks in tasks.md are checked
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" / "完了"