@arimakouyou/spec-workflow-mcp 2.2.7

package/.claude-plugin/skills/spec-design/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: spec-design
+description: "Phase 2 of spec-driven development: create a technical design document for a feature. Use this skill after requirements are approved, when the user wants to create a design doc, define architecture, or plan how to build a feature. Triggers on: 'create design', 'design document', 'technical architecture for X', 'how should we build X', or any request to create a design.md document."
+---
+
+# Spec Design (Phase 2)
+
+Create a technical design document that defines **how** to build the feature. This phase follows approved requirements and precedes task breakdown.
+
+The design document is created in **two stages (Waves)**. Wave 1 aligns the architectural direction with the user before Wave 2 fills in the details, preventing rework caused by misaligned direction.
+
+## Prerequisites Check (MANDATORY — DO NOT SKIP)
+
+Before doing anything else, verify the prerequisite file exists:
+
+1. Check `.spec-workflow/specs/{spec-name}/requirements.md` exists
+
+If missing — **STOP immediately.** Tell the user: "Cannot start design because requirements.md does not exist. Please run `/spec-requirements` first." Then exit this skill.
+
+---
+
+Requirements must be approved and cleaned up (Phase 1 complete). If not, use `/spec-requirements` first.
+
+## Inputs
+
+The same **spec name** used in Phase 1 (kebab-case, e.g., `user-authentication`).
+
+## Process
+
+### 1. Load Resources
+
+**Template** — prefer custom, fall back to default:
+1. `.spec-workflow/user-templates/design-template.md` (custom)
+2. `.spec-workflow/templates/design-template.md` (default)
+
+**Steering documents** — load if they exist:
+```
+.spec-workflow/steering/product.md
+.spec-workflow/steering/tech.md
+.spec-workflow/steering/structure.md
+```
+
+### 2. Analyze and Research
+
+- Read the approved requirements: `.spec-workflow/specs/{spec-name}/requirements.md`
+- Explore the codebase to understand existing patterns and reusable components
+- If web search is available, research best practices for technology choices
+- Confirm that design solutions exist for all requirements
+
+---
+
+## Wave 1: Architecture Skeleton
+
+**Goal**: Align the architectural direction with the user before diving into details.
+
+### 3. Create Wave 1 Document
+
+Write only the sections listed below and create `.spec-workflow/specs/{spec-name}/design.md`.
+Leave the detail sections (API spec, error handling, traceability, etc.) as `(to be written in Wave 2)` placeholders.
+
+**Sections to write in Wave 1:**
+
+1. **Overview** — Summary of the feature and its place in the system
+2. **Architecture** — Architecture diagram (mermaid) + rationale for the chosen pattern
+3. **Component List** — Component names with a one-line description of each role only (details in Wave 2)
+4. **DB Schema** — Table definitions, columns, and constraints (critical decisions that form the implementation foundation)
+5. **Key Design Decisions** — Technologies and patterns chosen and why (include rejected alternatives)
+
+**Wave 1 placeholder examples:**
+```markdown
+## Components and Interfaces
+(to be written in Wave 2)
+
+## Data Models
+(to be written in Wave 2)
+
+## API Design
+(to be written in Wave 2)
+
+## Error Handling
+(to be written in Wave 2)
+
+## Requirements Traceability Matrix
+(to be written in Wave 2)
+
+## Code Reuse Analysis
+(to be written in Wave 2)
+```
+
+### 4. Architecture Confirmation (Present to User)
+
+After creating the Wave 1 document, present the following to the user **without using the formal approval tool**:
+
+```
+## Architecture Confirmation
+
+The Wave 1 skeleton is ready. Please review the direction below before proceeding to Wave 2 (detailed writing).
+
+**Design Overview**
+{2–3 sentence summary of the Overview}
+
+**Chosen Architecture**
+{Architecture diagram or configuration summary}
+
+**Key Components**
+{Component list}
+
+**Main DB Schema Tables**
+{Table list}
+
+**Key Design Decisions**
+{Summary of Key Design Decisions}
+
+---
+If the direction looks good, reply "continue". If changes are needed, please provide specific instructions.
+```
+
+Branch based on user feedback:
+
+- **"continue" / approval**: Proceed to Wave 2
+- **Revision instructions**: Update the Wave 1 sections in design.md and present the confirmation again. Once agreed, proceed to Wave 2
+
+---
+
+## Wave 2: Detailed Writing
+
+**Goal**: Fill in all details based on the finalized architecture and obtain formal approval.
+
+### 5. Complete Wave 2 Document
+
+Fill in all sections left as `(to be written in Wave 2)` from Wave 1.
+
+#### Components and Interfaces
+
+Describe each component in this format:
+```markdown
+### ComponentName
+- **Purpose:** [Responsibility this component owns]
+- **Interfaces:** [Public method / API signatures]
+- **Dependencies:** [Components / external services depended on]
+- **Reuses:** [Existing code to leverage (with concrete paths)]
+```
+
+#### Data Models
+
+Describe all entities in type definition or schema format.
+
+#### API Design (if applicable)
+
+For each endpoint, describe:
+- HTTP method, path, and description
+- Request / response types (fields, types, required / optional)
+- Error responses
+
+#### Code Reuse Analysis Format
+
+Search the codebase with grep/glob and list existing code to reuse with **concrete file paths**. Because these are copied into the `_Leverage` field in Phase 3, abstract descriptions (e.g., "use the existing auth middleware") are not acceptable.
+
+```markdown
+| Reuse Target | Path | Purpose |
+|-------------|------|---------|
+| Auth middleware | `src/middleware/auth.rs` | Protect endpoints |
+| AppError | `src/error.rs` | Unified error responses |
+| TestContext | `tests/integration/helpers/context.rs` | Test setup |
+```
+
+#### Requirements Traceability Matrix Format
+
+Mapping of requirements to design components. **List one component per row** (do not join with `+`). The "Target Task ID" column is filled in retrospectively after Phase 3 (spec-tasks) is complete.
+
+```markdown
+| Requirement ID | Design Component | Target Task ID | Notes |
+|---------------|-----------------|---------------|-------|
+| REQ-1 | UserHandler | (fill in after Phase 3) | CRUD endpoints |
+| REQ-1 | UserRepository | (fill in after Phase 3) | DB access |
+| REQ-2 | AuthMiddleware | (fill in after Phase 3) | Auth check |
+```
+
+#### Error Handling Format
+
+List all error codes in table format. Because the design-conformance rule prohibits adding error codes outside this list during implementation, define all anticipated error cases exhaustively.
+
+```markdown
+## Error Handling
+
+Error response format: `{ "error": { "code": "...", "message": "..." } }`
+
+| Error Code | HTTP Status | Trigger Condition |
+|-----------|-------------|------------------|
+| NotFound | 404 | Resource does not exist |
+| BadRequest | 400 | Validation failure, invalid input |
+| Unauthorized | 401 | Auth failure, invalid / expired token |
+| Forbidden | 403 | Authorization failure, insufficient permissions |
+| Conflict | 409 | Duplicate key, optimistic lock conflict |
+| Internal | 500 | Unexpected internal error |
+```
+
+### 6. Self-Review via Subagent (before approval)
+
+After Wave 2 is complete, review in **2 steps** before requesting formal approval.
+
+#### Step A: fix (automated mechanical corrections)
+
+Auto-fix placeholders, formatting, and typos. Do not add or change content:
+
+```
+Agent({
+  subagent_type: "general-purpose",
+  description: "Fix design spec (auto-fix)",
+  prompt: "You are a spec document reviewer. Auto-fix minor issues in the document at:
+    {project-path}/.spec-workflow/specs/{spec-name}/design.md
+
+    Document type: design
+
+    Auto-fix targets (you may edit the file directly):
+    - Remove placeholder text ([describe...], TODO, TBD, '(to be written in Wave 2)', etc.)
+    - Fix markdown formatting (table alignment, heading levels, etc.)
+    - Obvious typos
+
+    Do NOT auto-fix (report as issues only):
+    - Adding or removing sections
+    - Adding or changing content (design components, error codes, DB schema, etc.)
+    - Traceability inconsistencies
+
+    Mode: fix — Return a structured report (auto-fixed items + remaining issues)."
+})
+```
+
+#### Step B: check (content validation)
+
+After fix is complete, detect content problems. Do not modify the file:
+
+```
+Agent({
+  subagent_type: "general-purpose",
+  description: "Review design spec (check)",
+  prompt: "You are a spec document reviewer. Review the document (do NOT modify the file) at:
+    {project-path}/.spec-workflow/specs/{spec-name}/design.md
+
+    Document type: design
+    Template: {project-path}/.spec-workflow/templates/design-template.md
+    Requirements: {project-path}/.spec-workflow/specs/{spec-name}/requirements.md
+
+    Checks:
+    1. TEMPLATE: Every section from the template must exist with real content (no placeholders or '(to be written in Wave 2)' remaining)
+    2. CROSS-REFERENCE: Read requirements.md — every requirement must have a corresponding design solution.
+       No design component should exist without a backing requirement.
+    3. Must include: Overview, Architecture diagram, Component details (Purpose/Interfaces/Dependencies/Reuses),
+       Data Models, Error Handling table, Requirements Traceability Matrix, Code Reuse Analysis with concrete paths
+    4. Data models must cover all entities referenced in requirements
+    5. Error Handling must have a complete table (not just scenario descriptions)
+
+    Mode: check — DO NOT modify the file. List all issues with location and suggested fix.
+    Return a structured report (PASS/FAIL with issues list)."
+})
+```
+
+If check returns FAIL, fix the issues yourself and re-run check (up to 3 times). Once PASS, proceed to approval.
+
+### 7. Approval Workflow
+
+Formal approval — verbal approval is not accepted.
+
+1. **Request approval**: `approvals` tool, `action: 'request'`, filePath only (do not include content)
+2. **Poll status**: `approvals` tool, `action: 'status'`, poll until status changes
+3. **Handle result**:
+   - **needs-revision**: Read the review comments, update the document, re-run the subagent review, submit a NEW approval request
+   - **approved**: Proceed to cleanup
+4. **Cleanup**: `approvals` tool, `action: 'delete'` — must succeed
+   - If delete fails: STOP, return to polling
+5. **Next phase**: After successful cleanup, proceed to Phase 3 (Test Design). Use the `/spec-test-design` skill.
+
+## Rules
+
+- Feature names use kebab-case
+- One spec at a time
+- **Do not start Wave 2 before Wave 1 is complete** — user confirmation is required
+- **Verbal confirmation is allowed for Wave 1** — formal approval tool not required
+- **Formal approval is required after Wave 2** — verbal approval is not accepted
+- Approval requests: filePath only, never content
+- Never proceed if approval delete fails
+- Must have approved status AND successful cleanup before moving to tasks

package/.claude-plugin/skills/spec-e2e-implement/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: spec-e2e-implement
+description: "Implement IT/E2E tests independently from main implementation. Uses test-design.md IT/E2E specifications to generate test code with container-based infrastructure (testcontainers, Playwright, docker-compose). Can run in parallel with /spec-implement. Triggers on: 'implement e2e tests', 'create e2e tests', 'e2e for X', 'integration tests for X', '/spec-e2e-implement'."
+user-invokable: true
+argument-hint: "<spec-name> [--scope it|e2e|all] [--spec-id IT-1,E2E-1]"
+---
+
+# E2E Test Implementation (Independent Line)
+
+メイン実装（`/spec-implement`）とは独立して、test-design.md の IT/E2E 仕様に基づいてテストコードを生成する。コンテナベースのテストインフラ（testcontainers、docker-compose.test.yml、Playwright）を使用する。
+
+## Prerequisites Check (MANDATORY — DO NOT SKIP)
+
+1. Check `.spec-workflow/specs/{spec-name}/requirements.md` exists
+2. Check `.spec-workflow/specs/{spec-name}/design.md` exists
+3. Check `.spec-workflow/specs/{spec-name}/test-design.md` exists
+4. Check `.spec-workflow/specs/{spec-name}/tasks.md` exists
+
+If ANY file is missing — **STOP immediately.** Inform the user which file is missing and which skill to run.
+
+| Missing File | Required Skill |
+|-------------|---------------|
+| requirements.md | `/spec-requirements` |
+| design.md | `/spec-design` |
+| test-design.md | `/spec-test-design` |
+| tasks.md | `/spec-tasks` |
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|:--------:|-------------|
+| `spec-name` | YES | Spec name in kebab-case |
+| `--scope` | NO | `it` (統合テストのみ), `e2e` (E2E のみ), `all` (デフォルト: 両方) |
+| `--spec-id` | NO | 特定の仕様のみ実装（例: `IT-1,E2E-2`） |
+
+## Process
+
+### 1. Read Test Design
+
+1. Read `.spec-workflow/specs/{spec-name}/test-design.md`
+2. IT/E2E 仕様を抽出（`--scope` / `--spec-id` でフィルタ）
+3. **E2E Test Infrastructure** セクションから技術選定を取得:
+   - テストランナー（Playwright / reqwest / supertest 等）
+   - DB 戦略（testcontainers / docker-compose.test.yml）
+   - Container Test Setup 方法
+
+### 2. Check Implementation Readiness
+
+IT/E2E テストの対象コンポーネントがメイン実装で実装済みか確認する:
+
+```bash
+# tasks.md で対象タスクの完了状態を確認
+grep -E '\[x\]|\[-\]|\[ \]' .spec-workflow/specs/{spec-name}/tasks.md
+```
+
+| 状態 | アクション |
+|------|----------|
+| 対象コンポーネントが全て `[x]` | テスト実装を開始 |
+| 一部が `[-]` (実装中) | 完了済みコンポーネントの IT のみ実装可。E2E は待機 |
+| 対象が `[ ]` (未着手) | ユーザーに報告: 「対象コンポーネントが未実装です。`/spec-implement` でメイン実装を先に進めてください」 |
+
+### 3. Infrastructure Setup (初回のみ)
+
+テストインフラが未セットアップの場合、以下を実行する。`_TDDSkip: true` 相当（テストインフラ自体のテストは不要）。
+
+#### 3.1 docker-compose.test.yml の確認
+
+```bash
+# docker-compose.test.yml が存在するか確認
+test -f docker-compose.test.yml && echo "exists" || echo "missing"
+```
+
+- 存在しない場合 → parallel-worker でdocker-compose.test.ymlを作成
+- 存在する場合 → スキップ
+
+#### 3.2 テストランナーのセットアップ
+
+E2E Test Infrastructure の選定に基づいて:
+
+| ランナー | セットアップ |
+|---------|-------------|
+| Playwright | `npm init playwright@latest`、`playwright.config.ts` 生成 |
+| reqwest | `Cargo.toml` に `[dev-dependencies]` 追加 |
+| supertest | `npm install --save-dev supertest @types/supertest` |
+| testcontainers (Rust) | `Cargo.toml` に `testcontainers` 依存追加 |
+| testcontainers (Node) | `npm install --save-dev testcontainers` |
+
+#### 3.3 テストヘルパー・共通フィクスチャの作成
+
+parallel-worker で以下を作成:
+
+- **テスト用 DB ヘルパー**: testcontainers の起動・マイグレーション・シードデータ投入を共通化
+- **テスト用 HTTP クライアント**: 認証トークン付きリクエスト送信のヘルパー
+- **共通フィクスチャ**: test-design.md の Test Data Requirements に基づくシードデータ
+
+### 4. IT Implementation
+
+test-design.md の各 IT 仕様に対して parallel-worker でテストコードを生成する。
+
+```javascript
+Agent({
+  subagent_type: "parallel-worker",
+  description: "IT: Implement integration test IT-{N}",
+  prompt: `Implement integration test based on the following specification.
+
+    Project path: {project-path}
+    Spec name: {spec-name}
+    Worktree path: {WORKTREE_PATH}
+    Branch: {BRANCH}
+
+    IT Specification (from test-design.md):
+    {paste IT-N specification including Technology, Steps, Verification Points}
+
+    Test design doc path: {project-path}/.spec-workflow/specs/{spec-name}/test-design.md
+    Design doc path: {project-path}/.spec-workflow/specs/{spec-name}/design.md
+
+    Container setup:
+    - DB: Use testcontainers to start a clean DB container for each test
+    - Apply migrations before test execution
+    - Seed test data as defined in Test Data Requirements
+
+    Important:
+    - Always cd {WORKTREE_PATH} before starting
+    - Test must be self-contained: start container → migrate → seed → test → cleanup
+    - Each test function must clean up its own state
+    - Use the test helpers created in step 3.3
+
+    After implementation, run the test to confirm it passes.`
+})
+```
+
+### 5. E2E Implementation
+
+test-design.md の各 E2E 仕様に対してテストコードを生成する。
+
+#### 5.1 API E2E (Test Type: API E2E)
+
+```javascript
+Agent({
+  subagent_type: "parallel-worker",
+  description: "E2E: Implement API E2E test E2E-{N}",
+  prompt: `Implement API E2E test based on the following specification.
+
+    {same context as IT implementation}
+
+    E2E Specification (from test-design.md):
+    {paste E2E-N specification}
+
+    Server startup:
+    1. docker-compose -f docker-compose.test.yml up -d
+    2. Wait for health check to pass
+    3. Run test scenarios against the running server
+    4. docker-compose -f docker-compose.test.yml down after tests
+
+    Use reqwest (Rust) or supertest (Node.js) to send HTTP requests.`
+})
+```
+
+#### 5.2 Browser E2E (Test Type: Browser E2E / Full-Stack E2E)
+
+```javascript
+Agent({
+  subagent_type: "parallel-worker",
+  description: "E2E: Implement browser E2E test E2E-{N}",
+  prompt: `Implement browser E2E test using Playwright based on the following specification.
+
+    {same context as IT implementation}
+
+    E2E Specification (from test-design.md):
+    {paste E2E-N specification including Scenario Steps}
+
+    Server startup:
+    1. docker-compose -f docker-compose.test.yml up -d
+    2. Wait for health check + frontend readiness
+    3. Run Playwright tests (Scenario Steps → test code conversion)
+    4. Capture screenshots on failure
+    5. docker-compose -f docker-compose.test.yml down after tests
+
+    Playwright guidelines:
+    - Use page.goto(), page.click(), page.fill() for user interactions
+    - Use page.waitForSelector() for dynamic content
+    - Use expect(page).toHaveURL() for navigation assertions
+    - Use expect(locator).toHaveText() for content assertions`
+})
+```
+
+### 6. Quality Verification
+
+全 IT/E2E テストを実行し、品質を検証する。
+
+```bash
+# IT テスト実行
+cargo test --tests --quiet                 # Rust
+npm run test:integration                   # Node.js
+
+# E2E テスト実行
+docker-compose -f docker-compose.test.yml up -d
+npx playwright test                        # Browser E2E
+cargo test --tests --quiet                 # Rust API E2E
+npm run test:e2e                           # Node.js API E2E
+docker-compose -f docker-compose.test.yml down
+```
+
+review-worker でテストコードのレビュー:
+- テストが test-design.md の仕様を正しく反映しているか
+- テストの独立性（他テストへの依存がないか）
+- コンテナの適切なクリーンアップ
+- テストデータの適切な管理
+
+### 7. Report
+
+結果を `.spec-workflow/specs/{spec-name}/reviews/e2e-implementation.md` に保存:
+
+```markdown
+# E2E Test Implementation Report
+
+## Spec: {spec-name}
+## Date: {date}
+## Scope: {it|e2e|all}
+
+## IT Tests
+| Spec ID | Test File | Status | Notes |
+|---------|-----------|--------|-------|
+| IT-1 | tests/integration/test_xxx.rs | PASS | |
+| IT-2 | tests/integration/test_yyy.rs | PASS | |
+
+## E2E Tests
+| Spec ID | Test File | Type | Status | Notes |
+|---------|-----------|------|--------|-------|
+| E2E-1 | tests/e2e/test_xxx.rs | API | PASS | |
+| E2E-2 | e2e/journey.spec.ts | Browser | PASS | |
+
+## Infrastructure
+- docker-compose.test.yml: [created|existing]
+- Test helpers: [created|existing]
+- Playwright config: [created|N/A]
+
+## Coverage
+| Spec Type | Total | Implemented | Skipped (not ready) |
+|-----------|-------|-------------|---------------------|
+| IT | {N} | {M} | {K} |
+| E2E | {N} | {M} | {K} |
+```
+
+## メイン実装との関係
+
+- `/spec-implement` と `/spec-e2e-implement` は**独立して実行可能**
+- `/spec-implement` の Final E2E Gate (Step 9) は `/spec-e2e-implement` で作成したテストも自動的に実行する
+- メイン実装の進捗に応じて、実装済みコンポーネントから順次 IT テストを作成できる
+- E2E テストは全コンポーネントが実装済みになってから実行する
+
+## Rules
+
+- Feature names use kebab-case
+- テストコードはコンテナベースで実装する（testcontainers / docker-compose.test.yml）
+- テストは自己完結的であること（他テストへの依存禁止）
+- コンテナは必ずクリーンアップすること
+- test-design.md の仕様に忠実に実装すること
+- 口頭承認は不要（テスト実装は承認プロセスなし、Final E2E Gate で検証）

package/.claude-plugin/skills/spec-impl-code/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: spec-impl-code
+description: "TDD GREEN phase for spec-implement workflow. Writes minimal production code to make failing tests pass. Designed to run as a subagent — spawn it with the Agent tool. Triggers on: subagent calls from spec-implement orchestrator only."
+---
+
+# Code Writer — GREEN Phase (Subagent)
+
+This skill is designed to run as a **subagent** via the Agent tool. It writes the minimal production code needed to make failing tests pass, following TDD's GREEN phase.
+
+## How the Calling Agent Should Invoke This
+
+```javascript
+Agent({
+  subagent_type: "general-purpose",
+  description: "GREEN: Implement to pass tests",
+  prompt: `You are a TDD implementer. Write minimal code to make the failing tests pass.
+
+    Project path: {project-path}
+    Spec name: {spec-name}
+    Task ID: {task-id}
+    Task prompt: {task _Prompt content}
+    Test files: {test-file-paths}
+    Leverage files: {_Leverage file paths}
+
+    Follow the /spec-impl-code skill instructions.
+
+    Return the list of files created/modified and implementation approach.`
+})
+```
+
+## GREEN Phase Rules
+
+1. **Make the tests pass** — that is the only goal
+2. **Write minimal code** — just enough to satisfy the tests (YAGNI)
+3. **Do NOT modify test files** — tests are the specification
+4. **Do NOT add untested features** — if there's no test for it, don't build it
+
+## Execution Steps
+
+### 1. Read and Understand the Tests
+
+- Read each test file to understand:
+  - What modules/functions are imported (these need to be created)
+  - What interfaces are expected (parameters, return types)
+  - What behavior is verified (assertions define the contract)
+  - What error conditions are tested
+
+### 2. Plan the Implementation
+
+From the tests, derive:
+- Which files need to be created
+- What functions/classes/methods are needed
+- What types/interfaces are expected
+- What the input/output contracts are
+
+### 3. Choose a Green Strategy
+
+Follow `/tdd-skills` Green Strategies:
+
+1. **Obvious Implementation** (preferred when solution is clear): Implement the real logic directly
+2. **Fake It** (when uncertain): Return a constant first, then generalize
+3. **Triangulation** (when multiple cases exist): Generalize from multiple test assertions
+
+### 4. Implement
+
+- Read `_Leverage` files to understand existing patterns and utilities
+- Follow the codebase's existing conventions (naming, structure, error handling)
+- Create the modules that tests import
+- Implement functions/classes with the expected signatures
+- Handle all test cases including error scenarios
+
+**Key constraint**: Write only what the tests demand. If a test doesn't check for input validation, don't add it. If a test doesn't verify logging, don't add it.
+
+### 5. Verify Locally (Optional Quick Check)
+
+If possible, do a quick mental check that:
+- All imported modules now exist
+- All expected exports are present
+- Function signatures match what tests call
+- Return types match what tests assert
+
+## Output Format
+
+Return to the calling agent:
+
+```
+## GREEN Phase Complete
+
+### Files Created
+- {path/to/new-file-1}: {brief description}
+- {path/to/new-file-2}: {brief description}
+
+### Files Modified
+- {path/to/existing-file}: {what was changed}
+
+### Implementation Approach
+{1-3 sentences describing the approach taken and key decisions}
+
+### Green Strategy Used
+{Obvious Implementation / Fake It / Triangulation} — {reason}
+```