@arimakouyou/spec-workflow-mcp 2.2.7

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

@@ -0,0 +1,130 @@
+---
+name: spec-requirements
+description: "Phase 1 of spec-driven development: create a requirements document for a feature. Use this skill when the user wants to start a new spec, define requirements, or begin the spec workflow for a feature. Triggers on: 'create requirements', 'new spec for X', 'start spec workflow', 'define what to build', or any request to create a requirements.md document."
+---
+
+# Spec Requirements (Phase 1)
+
+Create a requirements document that defines **what** to build based on user needs. This is the first phase of the spec-driven development workflow (Requirements -> Design -> Tasks -> Implementation).
+
+## Inputs
+
+You need a **spec name** in kebab-case (e.g., `user-authentication`, `data-export`). Ask the user if they haven't provided one.
+
+## Process
+
+### 1. Gather Context
+
+Read steering documents if they exist — these contain project-level guidance that should inform your requirements:
+
+```
+.spec-workflow/steering/product.md
+.spec-workflow/steering/tech.md
+.spec-workflow/steering/structure.md
+```
+
+### 2. Load the Template
+
+Check for a custom template first. If none exists, fall back to the default:
+
+1. `.spec-workflow/user-templates/requirements-template.md` (custom)
+2. `.spec-workflow/templates/requirements-template.md` (default)
+
+Follow the template structure exactly for consistency across the project.
+
+### 3. Research and Write
+
+- If web search is available, research current market expectations and best practices
+- Generate requirements as user stories using EARS criteria (Event, Action, Response, State)
+- Cover all functional and non-functional requirements
+- Be comprehensive — the design phase depends on complete requirements
+
+### 4. Create the Document
+
+Write the file to:
+```
+.spec-workflow/specs/{spec-name}/requirements.md
+```
+
+### 5. Self-Review via Subagent (before approval)
+
+Validate the document in **2 stages** before requesting 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 requirements 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}/requirements.md
+
+    Document type: requirements
+
+    Auto-fix targets (you may directly modify the file):
+    - Remove placeholder text ([describe...], TODO, TBD)
+    - Fix markdown formatting (table alignment, heading levels, etc.)
+    - Fix obvious typos
+
+    Not auto-fix targets (report as issues only):
+    - Adding or removing sections
+    - Adding or changing content (requirements, Acceptance Criteria, etc.)
+
+    Mode: fix — Return a structured report (auto-fixed items + remaining issues)."
+})
+```
+
+#### Step B: check (content validation)
+
+After fix is complete, detect content issues. Do not modify the file:
+
+```
+Agent({
+  subagent_type: "general-purpose",
+  description: "Review requirements 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}/requirements.md
+
+    Document type: requirements
+    Template: {project-path}/.spec-workflow/templates/requirements-template.md
+
+    Checks:
+    1. TEMPLATE: Every section from the template must exist with real content (no [describe...] or TODO)
+    2. Every requirement needs User Story ('As a [role]...') and EARS Acceptance Criteria (WHEN/IF...THEN...SHALL)
+    3. Non-Functional Requirements must cover: Code Architecture, Performance, Security, Reliability, Usability
+    4. Requirements should be uniquely identified (REQ-1, REQ-2, etc.)
+
+    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.
+
+### 6. Approval Workflow
+
+This is a strict, automated process. Verbal approval from the user is never accepted — only dashboard or VS Code extension approval counts.
+
+1. **Request approval**: Use the `approvals` MCP tool with `action: 'request'`. Pass `filePath` only — never include content in the request.
+
+2. **Poll for status**: Use `approvals` with `action: 'status'`. Keep polling until the status changes from `pending`.
+
+3. **Handle the result**:
+   - **needs-revision**: Read the reviewer's comments, update the document accordingly, spawn the review subagent again, then submit a NEW approval request. Do not proceed to design.
+   - **approved**: Move to cleanup.
+
+4. **Cleanup**: Use `approvals` with `action: 'delete'`. This must succeed before proceeding.
+   - If delete fails: STOP. Return to polling. Never proceed without successful cleanup.
+
+5. **Next phase**: Only after cleanup succeeds, proceed to Phase 2 (Design). Use the `/spec-design` skill.
+
+## Rules
+
+- Feature names use kebab-case (e.g., `user-authentication`)
+- One spec at a time
+- Approval requests: filePath only, never content
+- Never accept verbal approval — dashboard/VS Code extension only
+- Never proceed if approval delete fails
+- Must have approved status AND successful cleanup before moving to design

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

@@ -0,0 +1,274 @@
+---
+name: spec-review
+description: "Self-review a specification document before requesting user approval. This skill is designed to run as a subagent — spawn it with the Agent tool to keep review details out of the main context. Use automatically after creating or updating any spec document (requirements.md, design.md, tasks.md) and BEFORE requesting approval. Triggers on: any spec document creation, before approval requests, 'review spec', 'check spec quality'."
+---
+
+# Spec Review (Subagent)
+
+This skill is designed to run as a **subagent** via the Agent tool. It has two modes.
+
+## Mode: check (default — review before Approval)
+
+**Do not modify the file.** Only detect and return a list of issues. The caller reviews the issues and makes corrections themselves, then runs check again. Do not add or change content (the reviewer must not "invent" content).
+
+```javascript
+Agent({
+  subagent_type: "general-purpose",
+  description: "Review spec document (check)",
+  prompt: `You are a spec document reviewer. Check the document at:
+    {project-path}/.spec-workflow/specs/{spec-name}/{doc-type}.md
+
+    Document type: {doc-type}
+    Spec name: {spec-name}
+    Mode: check
+
+    Follow the /spec-review skill instructions below:
+
+    1. TEMPLATE COMPLIANCE: Re-read the template at .spec-workflow/templates/{doc-type}-template.md
+       and verify every section is present with substantive content (no placeholders like [describe...] or TODO).
+
+    2. CROSS-REFERENCE CHECK:
+       - For design.md: verify every requirement in requirements.md has a design solution
+       - For tasks.md: verify every requirement has a task, every design component has a task,
+         _Requirements references match actual IDs, task ordering respects dependencies
+
+    3. QUALITY CHECK: No placeholder text, no duplicates, consistent naming, testable acceptance criteria,
+       realistic error scenarios, task descriptions specific enough for AI implementation.
+
+    4. DO NOT modify the file. List all issues found with their location and suggested fix.
+
+    5. Return a structured report (see Output Format below).`
+})
+```
+
+Caller flow:
+1. Run spec-review in check mode
+2. If issues = 0 → proceed to Approval
+3. If issues >= 1 → caller reviews issues and corrects design.md/tasks.md
+4. Run check mode again (repeat until issues = 0, up to 3 times)
+
+## Mode: fix (minor automated fixes only)
+
+Performs **only mechanical fixes** such as removing placeholder text and fixing formatting. Does not add or change content (adding sections, requirements, error codes, etc.) — those are reported as issues.
+
+```javascript
+Agent({
+  subagent_type: "general-purpose",
+  description: "Review spec document (fix)",
+  prompt: `You are a spec document reviewer. Check and auto-fix minor issues in the document at:
+    {project-path}/.spec-workflow/specs/{spec-name}/{doc-type}.md
+
+    Document type: {doc-type}
+    Spec name: {spec-name}
+    Mode: fix
+
+    Items eligible for auto-fix (may directly modify the file):
+    - Remove placeholder text ([describe...], TODO, TBD)
+    - Fix markdown formatting (table alignment, heading levels, etc.)
+    - Obvious typos
+
+    Items NOT eligible for auto-fix (report as issues only):
+    - Adding or removing sections
+    - Adding or changing content (requirements, design components, error codes, etc.)
+    - Traceability inconsistencies
+
+    Return a structured report with auto-fixed items and remaining issues.`
+})
+```
+
+## Review Checklist by Document Type
+
+### Requirements (`requirements.md`)
+
+**Template compliance:**
+- Introduction section with clear feature overview
+- Alignment with Product Vision section (references steering docs if they exist)
+- Every requirement has User Story: "As a [role], I want [feature], so that [benefit]"
+- Every requirement has Acceptance Criteria using EARS pattern (WHEN/IF...THEN...SHALL)
+- Non-Functional Requirements: Code Architecture, Performance, Security, Reliability, Usability
+
+**Quality:**
+- No placeholder text (`[describe...]`, `TODO`, `TBD`)
+- Acceptance criteria are testable and specific
+- Requirements are uniquely identified (REQ-1, REQ-2, etc.)
+
+### Design (`design.md`)
+
+**Template compliance:**
+- Overview with architectural description
+- Steering Document Alignment (tech.md, structure.md)
+- Code Reuse Analysis (see dedicated check below)
+- Architecture section with diagram
+- Components/Interfaces: Purpose, Interfaces, Dependencies, Reuses
+- Data Models with concrete field definitions
+- Error Handling with specific scenarios
+- Requirements Traceability Matrix (see dedicated check below)
+
+**Code Reuse Analysis (concrete paths required):**
+- Is the table format listing "Reuse target / Path / Usage" present?
+- Are paths concrete file paths (e.g., `src/middleware/auth.rs`) rather than abstract descriptions (e.g., "leverage existing middleware")?
+- Do the paths actually exist in the codebase?
+- Is the granularity fine enough to be copied directly into each task's `_Leverage` field in Phase 3?
+
+**Requirements Traceability Matrix:**
+- Are all requirement IDs (REQ-1, REQ-2, ...) included in the matrix?
+- Is the corresponding design component listed for each requirement?
+- Reverse check: are there any design components with no backing requirement?
+- Testing Strategy: Unit, Integration, E2E
+
+**Cross-reference (read requirements.md):**
+- Every requirement has a corresponding design solution
+- No design component without a backing requirement
+- Data models cover all entities from requirements
+
+**DB Schema review (strictly validated to prevent post-approval changes):**
+- Every table lists column names, types, and constraints (NOT NULL, UNIQUE, DEFAULT, etc.)
+- Primary keys, foreign keys, and indexes are defined
+- **Each FK explicitly specifies `ON DELETE` behavior (CASCADE / RESTRICT / SET NULL)** — leaving it unspecified is not allowed; this is a design decision directly tied to business logic and must always be explicit
+- Relationships between tables (1:1, 1:N, N:M) and cardinality are clear
+- Migration strategy is documented (column add/drop order, data migration if needed)
+- Normalization level is appropriate (no unnecessary redundancy; denormalization for performance must have justification)
+- **The meaning of nullable columns is clear** (why NULL is allowed; if a DEFAULT value exists, its meaning is documented)
+- Timestamp columns (created_at, updated_at) are present
+- Soft-delete vs. hard-delete policy is explicitly stated (where applicable)
+
+**API Design review (strictly validated to prevent post-approval changes):**
+- All endpoints list HTTP method, path, and description
+- Each endpoint defines request body / query parameter types, required/optional status, and validation rules
+- Each endpoint defines response types (success + error) and HTTP status codes
+- Error response format is consistent (e.g., `{ "error": { "code": "...", "message": "..." } }`)
+- **Error codes are defined in a table** (columns: error code name, HTTP Status, trigger condition). Must be exhaustive to prevent undeclared error codes from being added during implementation
+- Authentication/authorization requirements are specified per endpoint
+- Pagination, filtering, and sorting parameter design is documented (where applicable)
+- RESTful conventions are followed (plural resource names, appropriate HTTP methods)
+
+**Data Model review (strictly validated to prevent post-approval changes):**
+- DB Model (e.g., Queryable) and DTOs (request/response types) are defined separately
+- DTO fields match the request/response definitions in the API Design
+- Fields that must not be exposed (e.g., password_hash) are excluded in the Model → DTO conversion
+- Validation rules are defined in request DTOs
+- Enum values (status, role, etc.) are exhaustive
+
+**Quality:**
+- No placeholder text
+- Consistent component naming
+- Error scenarios cover realistic failure modes
+- DB Schema / API / Data Model are concrete enough that implementers have minimal room to interpret the design
+
+### Test Design (`test-design.md`)
+
+**Template compliance:**
+- Test Strategy Overview section with overall test approach and Test Pyramid
+- Unit Test Specifications for every component in design.md
+- Integration Test Specifications for significant component interactions
+- E2E Test Specifications derived from user stories in requirements.md
+- Requirements-Test Traceability Matrix covering all Requirement IDs
+- Test Data Requirements section with shared fixtures and generation strategy
+- E2E Test Infrastructure section with project type, container setup, and test runner
+
+**UT Coverage:**
+- Every component in design.md has corresponding UT specifications
+- Each component's UT specs cover applicable categories (Happy Path / Boundary Values / Error Handling / Edge Cases)
+- Test case IDs follow naming convention (UT-N.M)
+- design.md Error Handling table entries have corresponding error handling test cases
+
+**IT/E2E Coverage:**
+- Every significant component interaction in design.md Architecture has an IT specification (IT-N)
+- Every user story in requirements.md has at least one E2E specification (E2E-N)
+- IT/E2E Technology fields are consistent with design.md Container Architecture
+
+**Cross-reference (read requirements.md and design.md):**
+- Every Requirement ID has at least one UT and one IT or E2E in the Traceability Matrix
+- E2E scenarios trace back to specific user stories and acceptance criteria
+- Container test setup aligns with design.md Container Architecture (if present)
+
+**Quality:**
+- No placeholder text in Input / Expected Output / Verification fields
+- Test cases are specific and concrete (not abstract like "verify success")
+- Test data is realistic and covers the necessary scenarios
+- Naming conventions are consistent (UT-N.M, IT-N, E2E-N)
+
+### Tasks (`tasks.md`)
+
+**Template compliance:**
+- Every task has `- [ ]` checkbox marker
+- Every task specifies target file path(s)
+- Every implementation task has `_Leverage` field (Phase 0 setup tasks, PhaseReview tasks, and IT/E2E test tasks may omit it)
+- Every task has `_Requirements` field
+- Every task has `_Prompt` field with: Role, Task, Restrictions, Success
+- `_Prompt` contains Role, Task, Restrictions, Success fields in the format "Role: ... | Task: ... | Restrictions: ... | Success: ..."
+- Tasks are atomic (1-3 files each)
+
+**Cross-reference (read requirements.md and design.md):**
+- Every requirement has at least one implementing task
+- Every design component has at least one creating task
+- `_Requirements` IDs match actual requirement IDs
+- `_Leverage` paths are plausible (match paths in the design.md Code Reuse Analysis table)
+- Task ordering respects dependencies (interfaces before implementations, models before services)
+
+**Traceability Matrix back-fill validation (read design.md):**
+- Are all rows in the Requirements Traceability Matrix in design.md filled in with a "Target Task ID"?
+- Do the "Target Task ID" values match actual task IDs that exist in tasks.md?
+- If any component row is empty, a task must be added to tasks.md and the matrix must be updated
+
+**`_TDDSkip` and Interface-only task validation:**
+- Is `_TDDSkip: true` applied appropriately (only to tasks that cannot be tested in isolation)?
+  - OK: project initialization, Dockerfile, migrations, config files (tasks that are self-contained)
+  - NG: tasks that only define a trait/struct (not self-contained → should be merged into an implementation task)
+- If an interface-only task is detected (`_TestFocus` all "N/A" + Success is only "compiles" + no `_TDDSkip`):
+  - Either add `_TDDSkip: true`, or merge into the first task that references it via `_Leverage`
+  - Decision rule: "Is this task self-contained?" → Yes: `_TDDSkip`, No: merge
+
+**`_TestFocus` format validation:**
+- Does every non-PhaseReview task's `_TestFocus` use the 4-category structure (Happy Path / Boundary Values / Error Handling / Edge Cases)?
+- Is free-form text being used instead (e.g., "CRUD success/failure, validation boundaries")?
+- Are categories that do not apply explicitly marked as "N/A" (not omitted)?
+- Is each category's content specific (not abstract like "Happy Path: success path" but rather "Happy Path: all CRUD operation success paths")?
+
+**Single responsibility validation:**
+- Does the `_Prompt` Task field join multiple behaviors with "and"?
+- Can the task be described in a single sentence? (If multiple sentences are needed → consider splitting)
+- Do the Success criteria contain multiple independent conditions? (e.g., "A compiles and B validates and C works" → split into 3 tasks)
+- If a task needs splitting, split it and update tasks.md
+
+**Quality:**
+- No placeholder text
+- Task descriptions specific enough for AI agent implementation
+- No duplicate tasks
+
+## Output Format
+
+### check mode
+
+```
+## Spec Review: {spec-name}/{doc-type}.md (check)
+
+### Checks Performed
+- Template compliance: {PASS / N issues}
+- Cross-references: {PASS / N issues / N/A for requirements}
+- Quality: {PASS / N issues}
+
+### Issues (caller must fix)
+1. [category: Template/CrossRef/Quality] {description of issue} — location: {section name or line number} — suggested fix: {concrete suggestion}
+2. ...
+
+### Items for User Attention
+- [any gaps requiring human judgment, if any]
+
+### Result: {PASS (issues 0) / FAIL (issues N)}
+```
+
+### fix mode
+
+```
+## Spec Review: {spec-name}/{doc-type}.md (fix)
+
+### Auto-Fixed
+- [list of auto-fixed items with before/after]
+
+### Remaining Issues (caller must fix)
+1. [category] {description of issue} — location: {section name} — suggested fix: {suggestion}
+2. ...
+
+### Result: {PASS (remaining 0) / FAIL (remaining N)}
+```