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:

docs/development/issue-to-pr-workflow.md

```
docs/issue-to-pr-workflow.md
```

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

If not found → trigger fallback (see Phase 1)

Coding rules — search in order, use first found:

```
docs/development/coding-rules.md
```
```
docs/coding-rules.md
```

Fallback:

find . -name "coding-rules.md" -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/vendor/*" -not -path "*/dist/*" -not -path "*/build/*" | head -1

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

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

text

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

text

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

--issue {N}

is provided or an issue number is found in context:

bash

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:

bash

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.

--resume

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

Post-creation verification:

bash

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:

bash

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

spec-implement

NPX Install

Tags

SKILL.md Content

spec-implement — Spec-Driven Implementation to PR

Language Rules

Critical First Steps

Execution Flow

Phase 1: Workflow Loading

Phase 1.5: Parallel Mode Resolution (Runtime-Aware)

Phase 2: Quality Rules Loading

Phase 3: Project Instruction Loading

Phase 4: Issue Analysis

Phase 5: Branch Creation

Phase 6: Spec-Driven Task Loop

Phase 7: Final Quality Gate

Phase 8: PR Creation

Options

Error Handling

Usage Examples

Post-Completion Actions