spec-implement — Spec-Driven Implementation to PR

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

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

Critical First Steps

BEFORE any implementation, execute these checks in order:

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

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]

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

Workflow Section	Action
Development Environment	Extract setup commands, environment variables
Issue Analysis and Setup	Follow branch naming convention, issue reading steps
Branch Strategy / PR Target	Extract base branch (e.g., `develop`, `main`) and PR target branch
Phased Implementation	Follow implementation order and guidelines
Agent Roles / Sub-agents	Extract agent role definitions (if present)
Agent Definition Files (Optional)	Extract explicit sub-agent definition file paths
Testing	Extract test commands and coverage thresholds
PR Creation and Quality Gates	Extract pre-PR checks and PR template
CI/CD Monitoring	Extract CI verification commands
Commit Message Rules	Extract commit message format and language requirements

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:

Look for "branch strategy", "base branch", "PR target", "develop", "main" in the workflow
If the workflow specifies a branch (e.g., develop), use it as {base_branch}
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:

Workflow includes a parallel section with role assignment
Runtime-specific sub-agent configuration is valid
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:

Severity	On Violation	Action
`[MUST]`	Error	Stop → fix → recheck before continuing
`[SHOULD]`	Warning	Log warning → continue
`[MAY]`	Info	Log info only

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:

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

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)" / "シングルエージェント（順次）"

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

Run test commands from the workflow (or language-appropriate default)
Run lint/typecheck commands from the workflow (if specified)
Verify all [MUST] rules from coding-rules.md pass
Verify all CLAUDE.md conditional rules pass
If any check fails → fix → recheck
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

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 (output format: see reference guide)
`--parallel`	Force parallel mode (requires valid runtime sub-agent setup for Codex or Claude Code)
`--no-parallel`	Disable parallel mode and run sequentially

Error Handling

Situation	Response
Not a git repository	Error: "Must be in a git repository" / "gitリポジトリ内で実行してください"
`gh` CLI not available	Error: guide user to install/authenticate gh CLI
`.specs/` not found	Warning: switch to Issue-only minimal mode
Parallel requested but runtime sub-agent config missing/invalid	Warning: explain missing setup, fallback to sequential mode
Workflow-declared agent definition file path does not exist	Warning: explain missing file path, fallback to sequential mode
Workflow references sub-agent names that are not configured in selected runtime	Warning: explain missing agent definitions, fallback to sequential mode
Parallel file edit collision	Warning: stop parallel for current task, continue sequentially
`requirement.md` missing	Warning: use Issue body as requirements source
`tasks.md` missing	Warning: generate simple checklist from Issue
`[MUST]` rule violation	Error: stop, fix, recheck before continuing
Tests failing before PR	Block PR creation, report failures
Branch already exists	Ask: switch to it or create new
On protected branch (main/master/develop)	🚨 BLOCKING: stop immediately, require feature branch
Workflow/rules file not at expected path	Search alternate paths before declaring missing

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" / "完了"