spec-implement — Spec-Driven Implementation to PR

Execute implementation from specifications to pull request, following project-specific workflows and enforcing coding rules.

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 (e.g., "in English", "日本語で")

Critical First Steps

BEFORE any implementation, execute these checks in order:

1. Verify environment:

   • Run pwd to confirm working directory
   • Run git status to confirm inside a git repository
   • Run gh auth status to confirm GitHub CLI access

2. Parse user input for options:

   • --resume → resume from last uncompleted task
   • --issue {N} → specify GitHub Issue number
   • --spec {path} → specify .specs/ directory path
   • --dry-run → show execution plan without making changes
   • --parallel → force parallel execution if environment is ready
   • --no-parallel → force sequential execution

3. Locate spec directory:

   • If --spec provided → use that path
   • If issue body contains .specs/ path → use that
   • Otherwise → scan .specs/ and ask user to select:

     AskUserQuestion:
       question: "Which spec to implement?" / "どの仕様書を実装しますか？"
       options: [list discovered .specs/ directories]
     

4. Locate and read project files (in this order):

   Workflow playbook — search in order, use first found:

   1. docs/development/issue-to-pr-workflow.md
   2. docs/issue-to-pr-workflow.md
   3. Fallback: find . -name "issue-to-pr-workflow.md" -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/vendor/*" -not -path "*/dist/*" -not -path "*/build/*" | head -1
   4. If not found → trigger fallback (see Phase 1)

   Coding rules — search in order, use first found:

   1. docs/development/coding-rules.md
   2. docs/coding-rules.md
   3. Fallback: find . -name "coding-rules.md" -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/vendor/*" -not -path "*/dist/*" -not -path "*/build/*" | head -1
   4. If not found → trigger fallback (see Phase 2)

   Project instruction files — read all that exist:

   • CLAUDE.md (project root)
   • src/CLAUDE.md (source-level rules)
   • test/CLAUDE.md (test-level rules)
   • AGENTS.md (agent definitions)

   Spec files:

   • .specs/{feature}/requirement.md → what to build
   • .specs/{feature}/design.md → how to build it
   • .specs/{feature}/tasks.md → task breakdown with checkboxes

5. Detect parallel-capable agent environment (runtime-aware):

   • Determine active runtime from the current execution environment (do NOT infer runtime solely from repository directories)
   • Use repository files only for runtime setup validation:
     • Codex validation: .codex/config.toml
     • Claude Code validation: .claude/agents/workflow-*.md
   • If runtime cannot be determined, ask user to choose runtime
   • Check whether workflow contains a parallel section (Parallel Execution Strategy / Agent Roles)
   • Parse optional workflow section for explicit agent file paths:
     • Agent definition files: / エージェント定義ファイル:
     • Extract paths for implementer / reviewer / tester from list items
     • Use extracted paths as first priority for validation and dispatch context
     • If section is absent, fallback to runtime defaults
   • Validate runtime-specific sub-agent setup:
     • Codex: .codex/config.toml has [features] multi_agent = true and agents.workflow-*
     • Claude Code: agent files from workflow section exist; if absent, use defaults (.claude/agents/workflow-implementer.md, .claude/agents/workflow-reviewer.md, .claude/agents/workflow-tester.md)
   • If any required condition is missing, continue in sequential mode

Execution Flow

Phase 1: Workflow Loading

Read the workflow file (located in Step 4) and interpret each section as instructions to follow:

Follow sections top-to-bottom. Replace {variable} placeholders with actual values (issue number, branch name, etc.). Treat "MUST" and "required" keywords as mandatory; treat "optional" and "if applicable" as conditional.

Base branch detection — determine {base_branch} from the workflow:

1. Look for "branch strategy", "base branch", "PR target", "develop", "main" in the workflow
2. If the workflow specifies a branch (e.g., develop), use it as {base_branch}
3. Default fallback: main

Fallback (no workflow file): If no workflow file is found:

AskUserQuestion:
  question: "Workflow file not found. Generate it?" / "ワークフローファイルが見つかりません。生成しますか？"
  options:
    - "Run spec-workflow-init" / "spec-workflow-initを実行"
    - "Continue without workflow" / "ワークフローなしで続行"

If continuing without workflow, use minimal flow: Issue analysis → branch → implement → test → PR. Use main as {base_branch}.

Phase 1.5: Parallel Mode Resolution (Runtime-Aware)

Enable parallel mode only when ALL are true:

1. Workflow includes a parallel section with role assignment
2. Runtime-specific sub-agent configuration is valid
3. User did not pass --no-parallel (or explicitly passed --parallel)

If runtime cannot be determined from execution context, confirm runtime before dispatch:

AskUserQuestion:
  question: "Which runtime should execute sub-agents?" / "どのランタイムでサブエージェント実行しますか？"
  options:
    - "Codex runtime" / "Codexで実行"
    - "Claude Code runtime" / "Claude Codeで実行"

If enabled:

• Run implementer and tester in parallel, then run reviewer after both complete.
• Use explicit runtime-specific dispatch instructions, not narrative role assignment only.

Codex path:

• Required config: .codex/config.toml with multi_agent = true and agents.workflow-*
• Agent definition file paths:
  • First priority: paths declared in workflow Agent definition files section
  • Fallback: runtime defaults (from .codex/agents/ conventions)
• Dispatch format (example):

Task:
  subagent_type: workflow-implementer
  prompt: "Implement task T001 using design section 2.3. Edit implementation files only."

Task:
  subagent_type: workflow-tester
  prompt: "Create tests for task T001. Edit test files only."

Claude Code path:

• Required files:
  • First priority: paths declared in workflow Agent definition files section
  • Fallback defaults: .claude/agents/workflow-implementer.md, .claude/agents/workflow-reviewer.md, .claude/agents/workflow-tester.md
• Dispatch format: use Claude Code sub-agent call format with subagent_type set to workflow agent names (workflow-implementer, workflow-tester, workflow-reviewer).
• Example (pseudocode):

SubAgent:
  subagent_type: workflow-implementer
  prompt: "Implement task T001 using design section 2.3. Edit implementation files only."

If disabled:

• Continue with the existing single-agent sequential loop.

Phase 2: Quality Rules Loading

Read the coding rules file (located in Step 4) and parse rule structure:

## {Category}
### [{Severity}] {Rule Name}
- {Rule detail}

Apply rules by severity:

Check timing:

• Before task: Review rules relevant to the task's category
• During code generation: Self-check against [MUST] rules
• After task: Verify completion criteria + rule compliance
• Final gate: Check all [MUST] rules across all changes

Fallback (no rules file): If no coding rules file is found:

AskUserQuestion:
  question: "Coding rules not found. Generate them?" / "コーディングルールが見つかりません。生成しますか？"
  options:
    - "Run spec-rules-init" / "spec-rules-initを実行"
    - "Continue without rules" / "ルールなしで続行"

If continuing without rules, use CLAUDE.md or AGENTS.md as fallback reference if available.

Phase 3: Project Instruction Loading

Read all project instruction files found in Step 4 (CLAUDE.md, src/CLAUDE.md, test/CLAUDE.md, AGENTS.md).

These files contain project-specific conditional rules, environment constraints, and coding conventions. Apply them with the same enforcement level as [MUST] rules from coding-rules.md:

• Extract conditional rules: IF-THEN patterns, conditional instructions, and environment-specific constraints (e.g., "when using Docker...", "if the project has...") are mandatory action triggers
• Extract environment constraints: Docker requirements, package manager restrictions, etc.
• Extract commit conventions: Commit message language, format, co-author requirements
• Extract test patterns: Required test helpers, test structure conventions
• Merge with coding-rules.md: These rules supplement (not replace) coding-rules.md

If neither coding-rules.md nor any CLAUDE.md files exist, proceed with framework defaults only.

Phase 4: Issue Analysis

If --issue {N} is provided or an issue number is found in context:

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

Extract from the issue:

• Feature overview and requirements
• Spec directory path (if referenced)
• Phase/task checklists
• Assignees and labels

Phase 5: Branch Creation

🚨 BLOCKING GATE — Feature branch is MANDATORY

Implementation MUST NOT proceed on main, master, or develop branches. This gate cannot be skipped. Violation = immediate stop.

Follow the workflow's branch naming convention:

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

Where {base_branch} is the branch detected in Phase 1 (default: main).

Protected branch list — by default: main, master, develop. If the workflow file defines a "protected branches" or "branch protection" section, use that list instead.

If --resume is active and the branch already exists, switch to it instead.

Post-creation verification:

current_branch=$(git branch --show-current)
if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ] || [ "$current_branch" = "develop" ]; then
  echo "🚨 ERROR: Cannot implement on protected branch: $current_branch"
  echo "Create a feature branch first."
  exit 1
fi

This check MUST pass before proceeding to Phase 6. If it fails, stop and ask the user for guidance.

Phase 6: Spec-Driven Task Loop

Pre-loop: Agent role detection

If the workflow file contains an "Agent Roles", "Sub-agents", or "エージェントロール" section:

0. Parse explicit agent file paths (if present):

   • Read workflow section Agent definition files: / エージェント定義ファイル:
   • Build a map of role → definition file path (implementer/reviewer/tester)
   • If no section exists, use runtime defaults

1. Parse the Role Assignment Table — find the Markdown table with columns like Role | Agent | Responsibility:

   • Extract each row's Agent column value → use as runtime sub-agent identifier (subagent_type)
   • Extract each row's Responsibility column value → use as context in the task prompt

2. Parse the Parallel Execution Strategy Table (if present) — find the table with phase rows and role columns:

   • Each row = a phase (execute sequentially, top to bottom)
   • Cells with - = role is idle in that phase
   • Non-- cells = role's action (roles active in the same row run in parallel)

3. Present options to the user:

   AskUserQuestion:
     question: "Workflow defines agent roles. Use sub-agents for parallel execution?" /
               "ワークフローにエージェントロールが定義されています。サブエージェントで並列実行しますか？"
     options:
       - "Use sub-agents (parallel)" / "サブエージェント使用（並列）"
       - "Single agent (sequential)" / "シングルエージェント（順次）"
   

4. If sub-agents selected, branch by runtime:

   • Codex runtime: spawn agents via Codex Task dispatch using parsed Agent names as subagent_type
   • Claude Code runtime: spawn agents via Claude Code sub-agent dispatch using parsed Agent names as subagent_type
   • Execute phases per strategy table (same-row roles run in parallel)

5. If single agent selected: proceed with sequential execution below

See reference guide for table format examples and runtime-specific sub-agent invocation patterns.

Read specs in order: requirement.md → design.md → tasks.md

For each unchecked task in tasks.md:

1. Read task details (requirements ID, design reference, target files, completion criteria)
2. Reference the corresponding design.md section
3. Implement: create or modify target files
4. 🔍 Implementation Review:
   a. Self-review generated code against design.md specifications
   b. Verify coding-rules.md [MUST] rules for generated code
   c. Verify CLAUDE.md conditional rules for generated code
   d. If review finds issues → fix before proceeding
5. If task includes test implementation:
   a. Write tests following project test patterns (from CLAUDE.md / coding-rules.md)
   b. Run tests to verify they pass
   c. 🔍 Test Review:
      - Verify test coverage matches completion criteria
      - Verify test patterns match project conventions
      - If review finds issues → fix before proceeding
6. Update tasks.md: mark completion criteria (- [ ] → - [x])
7. When all criteria pass: mark top-level task checkbox (- [x])
8. Commit progress:
   git add .specs/{feature}/tasks.md [+ implementation files]
   git commit -m "{commit message following project conventions}"

Commit messages: Follow format/language from coding-rules.md or CLAUDE.md. Default: feat: {task-id} complete — {brief description}. See reference guide for details.

No specs fallback: If .specs/ is missing, use Issue body as guide and generate a simple checklist. See reference guide for details.

Phase 7: Final Quality Gate

After all tasks are complete:

1. Run test commands from the workflow (or language-appropriate default)
2. Run lint/typecheck commands from the workflow (if specified)
3. Verify all [MUST] rules from coding-rules.md pass
4. Verify all CLAUDE.md conditional rules pass
5. If any check fails → fix → recheck
6. All checks pass → proceed to PR creation

Phase 8: PR Creation

Follow the workflow's PR template. Use {base_branch} detected in Phase 1:

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

Where {base_branch} comes from Phase 1 workflow detection (default: main).

Verify --base {base_branch} matches the workflow's branch strategy before creating the PR.

Safety guards:

• Do NOT create PR if tests are failing
• Do NOT force push
• Do NOT push directly to main/master
• Do NOT target wrong base branch (verify against workflow)
• Ask for user confirmation before large-scale code deletions

After PR creation, monitor CI status if the workflow specifies CI verification commands.

Options

Error Handling

Usage Examples

# Full implementation from spec
"Implement from spec for auth-feature"
「auth-featureの仕様書から実装して」

# With issue number
"Implement spec --issue 42"
「Issue #42の仕様を実装して」

# Resume after interruption
"Resume implementation --resume --spec .specs/auth-feature/"
「実装を再開 --resume」

# Dry run to preview plan
"Show implementation plan --dry-run --spec .specs/auth-feature/"
「実装計画を表示 --dry-run」

# Force parallel mode (runtime-aware)
"Implement from spec --spec .specs/auth-feature/ --parallel"
「仕様書から並列実行で実装 --parallel」

# Minimal mode (no specs)
"Implement issue 42"
「Issue 42を実装して」

Post-Completion Actions

After PR is created:

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