@anhth2/spec-driven-dev-plugin 0.5.0

package/skills/discovery/SKILL.tmpl

@@ -0,0 +1,147 @@
+---
+description: Guides product discovery for a new feature through structured Q&A. Trigger when: "/define-product", "khám phá tính năng", "define new feature", "start new feature", "product discovery", "tôi muốn build tính năng mới", "let's define a feature", "begin feature discovery".
+---
+
+# /define-product — Feature Discovery (9-Phase Q&A)
+
+Lead the user through 9 structured checkpoints to fully define a new feature before writing any code. Each phase ends with a summary and confirmation before proceeding.
+
+## Pre-check
+
+{{include:steps/context-loader.md}}
+
+If `.agent/project-context.yaml` does not exist, ask for basic context upfront: "What domain does this feature belong to? Who are the main user types in your system?"
+
+## Phase 1 — Problem & Goal
+**CHECKPOINT 1/9**
+
+Ask:
+1. What problem does this feature solve? What pain point are users experiencing?
+2. Who is the primary user (persona/role)?
+3. What is the desired outcome?
+
+Summarize → confirm → proceed.
+
+## Phase 2 — User Flow
+**CHECKPOINT 2/9**
+
+Ask the user to describe the end-to-end flow from the user's perspective:
+- Trigger: what initiates this flow?
+- Steps: what does the user do?
+- End state: what does the user see/have?
+
+Confirm flow is complete before proceeding.
+
+## Phase 3 — Use Case List
+**CHECKPOINT 3/9**
+
+Derive use cases from the flow. Present as:
+```
+{DOMAIN}-UC1: {Use Case Name}
+{DOMAIN}-UC2: {Use Case Name}
+```
+
+Ask: "Does this cover everything? Any missing use cases?"
+
+## Phase 4 — Business Rules
+**CHECKPOINT 4/9**
+
+For each use case, identify constraints:
+- Validation rules (what inputs are required/invalid?)
+- Business logic rules (what calculations/decisions happen?)
+- State rules (what must be true before this UC runs?)
+
+Format:
+```
+BR-{N}: {Rule description} → applies to UC{N}
+```
+
+## Phase 5 — Acceptance Criteria
+**CHECKPOINT 5/9**
+
+For each use case, define measurable acceptance criteria:
+```
+AC-UC{N}-{M}: Given {context}, when {action}, then {expected result}
+```
+
+## Phase 6 — Edge Cases
+**CHECKPOINT 6/9**
+
+Explore failure scenarios:
+- What if required data is missing?
+- What if concurrent requests happen?
+- What if an upstream dependency fails?
+- What are the boundary conditions?
+
+## Phase 7 — Scope Boundary
+**CHECKPOINT 7/9**
+
+Explicitly define what is OUT of scope for this feature iteration. This prevents scope creep.
+
+Format:
+```
+OUT OF SCOPE:
+- {thing}: deferred to {reason/future phase}
+```
+
+## Phase 8 — Cross-Service / Cross-Module Dependencies
+**CHECKPOINT 8/9**
+
+Identify dependencies on other modules or services:
+- What data does this feature need from other services?
+- What events/callbacks does it produce?
+- What APIs must it call?
+
+## Phase 9 — Validation & Summary
+**CHECKPOINT 9/9**
+
+Produce final summary:
+```
+Feature: {name}
+Domain: {domain}
+Primary Persona: {role}
+Use Cases: {N} (list)
+Business Rules: {N}
+Dependencies: {list}
+Estimated Complexity: Low / Medium / High
+```
+
+Ask: "Approved? Or any changes needed?"
+
+## Output
+
+On approval, write file: `specs/product-definition/{feature-slug}.md`
+
+```markdown
+# Product Definition — {Feature Name}
+
+**Date**: {date}
+**Domain**: {domain}
+**Status**: draft
+
+## Problem Statement
+{from Phase 1}
+
+## User Flow
+{from Phase 2}
+
+## Use Cases
+| UC-ID | Name | Priority |
+|-------|------|----------|
+| {DOMAIN}-UC1 | {name} | High |
+
+## Business Rules
+| BR-ID | Rule | Applies To |
+|-------|------|-----------|
+
+## Acceptance Criteria
+{from Phase 5}
+
+## Out of Scope
+{from Phase 7}
+
+## Cross-Service Dependencies
+{from Phase 8}
+```
+
+{{include:steps/report-footer.md}}

package/skills/prd/SKILL.md

@@ -0,0 +1,456 @@
+---
+description: Generates a PRD from a product definition, or analyzes an existing PRD through 4 review lenses (QA, DEV, SA, PO) to find gaps and risks. Trigger when: "/generate-prd", "/refine-prd", "tạo PRD", "generate PRD", "phân tích PRD", "review PRD", "refine PRD", "PRD có vấn đề gì không", "check PRD quality".
+---
+
+# PRD Skills — Generate & Refine
+
+This skill handles two commands: `/generate-prd` to create a PRD, and `/refine-prd` to analyze it for gaps.
+
+---
+
+## /generate-prd — Generate Product Requirements Document
+
+### Gate
+
+<!-- Directory: specs/product-definition/**/*.md -->
+# Gate — Universal Entry Procedure
+
+Every command must execute this gate before proceeding with its specific logic.
+
+## Step 0 — Sub-Agent Mode Check
+
+Before anything else, check if `$ARGUMENTS` is a JSON payload from an orchestrator:
+
+1. Attempt to parse `$ARGUMENTS` as JSON.
+2. If it parses successfully **and** contains `"_agent_mode": true`:
+   - **Skip Steps 1, 2, and 3 of this Gate entirely.**
+   - Set target file = `payload.target_file`
+   - Set loaded context = `payload.context` (do NOT run context-loader.md)
+   - Set UC scope = `payload.uc_id` (process only this UC)
+   - Set line range = `payload.uc_section` (read only that PRD section)
+   - Proceed directly to the command-specific logic.
+3. If `$ARGUMENTS` is not JSON or `_agent_mode` is absent → continue to Step 1 (normal mode).
+
+## Step 0-B — Model Check
+
+*Skip this step if `_agent_mode: true` (sub-agent — orchestrator already validated).*
+
+Complex generation and review commands require strong reasoning.
+Using a smaller model risks missed edge cases, incomplete spec analysis, and architecture violations.
+
+Display and wait for response:
+
+```
+⚙️  MODEL CHECK
+──────────────────────────────────────────────────────────────────
+  Recommended  : claude-opus-4-5 (or claude-opus-4)
+  Why needed   : Spec analysis, architecture review, code generation
+                 require deep reasoning. Smaller models miss edge cases.
+
+  To switch in Claude Code:
+    • Settings → Model → select "claude-opus"
+    • or: /model → choose claude-opus
+
+  Running on claude-opus?
+    Y — yes, on claude-opus → proceed
+    S — skip check (I accept lower quality risk with current model)
+──────────────────────────────────────────────────────────────────
+```
+
+- "Y" → proceed to Step 1.
+- "S" → proceed to Step 1 (user accepts risk, add ⚠️ to final report).
+- "N" or anything else → **STOP.** Output: "Please switch to claude-opus, then re-run this command."
+
+## Step 1 — Resolve Target File
+
+1. If `$ARGUMENTS` is provided and points to an existing file → use it directly as the target.
+2. If `$ARGUMENTS` is a UC-ID, ticket ID, or partial name → search for matching files in the relevant directory.
+3. If `$ARGUMENTS` is empty or no match found:
+   - List files in the relevant directory for this command (e.g., `specs/prd/**/*.md` for PRD commands, `specs/bdd/**/*.feature` for BDD commands).
+   - Present the list to the user and ask: "Which file do you want to work with? (Enter number or filename)"
+   - Wait for user selection before continuing.
+
+## Step 2 — Execute Context Loader
+
+Load all project context by following the procedure in `steps/context-loader.md`.
+Store all loaded context in memory for use throughout this command session.
+
+## Step 3 — CHECKPOINT
+
+After completing Steps 1 and 2, display a summary and wait for confirmation:
+
+```
+CHECKPOINT
+-----------
+Target     : {resolved file path}
+Project    : {project.name from project-context.yaml}
+Tech stack : {language} / {framework}
+Module     : {module if set, else "not configured"}
+Domains    : {comma-separated domain list}
+
+Proceed? (Y/N)
+```
+
+Wait for explicit "Y" or "N" from the user before continuing.
+- "Y" → proceed to the command-specific steps below.
+- "N" → stop and ask what the user wants to change.
+
+
+### Generate
+
+Write `specs/prd/{domain}/{slug}.md`:
+
+```markdown
+# PRD — {Feature Name}
+
+**Version**: 1.0
+**Status**: draft
+**Domain**: {domain}
+**Ticket**: {TICKET_PREFIX}-{N} (if available)
+**Date**: {date}
+
+## 1. Problem Statement
+{from product-definition}
+
+## 2. Goals & Non-Goals
+
+### Goals
+- {goal 1}
+
+### Non-Goals
+- {non-goal 1}
+
+## 3. User Stories
+
+As a {persona}, I want to {action} so that {benefit}.
+
+## 4. Use Cases
+
+| UC-ID | Name | Priority | Description |
+|-------|------|----------|-------------|
+| {DOMAIN}-UC1 | {name} | High | {description} |
+
+## 5. Business Rules
+
+| BR-ID | Rule | UC |
+|-------|------|----|
+| BR-1 | {rule} | UC1 |
+
+## 6. Acceptance Criteria
+
+### {DOMAIN}-UC1: {Name}
+- AC1: Given {context}, when {action}, then {result}
+
+## 7. Out of Scope
+{from product-definition}
+
+## 8. Cross-Service Dependencies
+{from product-definition}
+
+## 9. Open Questions
+- [ ] {question requiring clarification}
+```
+
+### Output
+
+```
+✅ PRD created: specs/prd/{domain}/{slug}.md
+Status: draft
+```
+
+# Report Footer — Standard Command Output Format
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /define-product         | `/generate-prd {product-definition-file}`     |
+| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
+| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
+| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
+| /generate-code          | `/generate-tests {UC-ID}`                     |
+| /generate-tests         | `/run-tests {UC-ID}`                          |
+| /run-tests (passing)    | `/review-code {UC-ID}`                        |
+| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/smoke-test {UC-ID}` or create PR            |
+| /smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | `/generate-code {UC-ID}` for gaps             |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+
+Format the footer as:
+```
+---
+Status : {badge}
+{Output Artifacts block}
+Next   : {suggested command with example arguments}
+```
+
+
+---
+
+## /refine-prd — Analyze PRD Through 4 Review Lenses
+
+Performs a structured multi-perspective analysis of a PRD and writes findings to a YAML file for human review.
+
+### Gate
+
+<!-- Directory: specs/prd/**/*.md -->
+# Gate — Universal Entry Procedure
+
+Every command must execute this gate before proceeding with its specific logic.
+
+## Step 0 — Sub-Agent Mode Check
+
+Before anything else, check if `$ARGUMENTS` is a JSON payload from an orchestrator:
+
+1. Attempt to parse `$ARGUMENTS` as JSON.
+2. If it parses successfully **and** contains `"_agent_mode": true`:
+   - **Skip Steps 1, 2, and 3 of this Gate entirely.**
+   - Set target file = `payload.target_file`
+   - Set loaded context = `payload.context` (do NOT run context-loader.md)
+   - Set UC scope = `payload.uc_id` (process only this UC)
+   - Set line range = `payload.uc_section` (read only that PRD section)
+   - Proceed directly to the command-specific logic.
+3. If `$ARGUMENTS` is not JSON or `_agent_mode` is absent → continue to Step 1 (normal mode).
+
+## Step 0-B — Model Check
+
+*Skip this step if `_agent_mode: true` (sub-agent — orchestrator already validated).*
+
+Complex generation and review commands require strong reasoning.
+Using a smaller model risks missed edge cases, incomplete spec analysis, and architecture violations.
+
+Display and wait for response:
+
+```
+⚙️  MODEL CHECK
+──────────────────────────────────────────────────────────────────
+  Recommended  : claude-opus-4-5 (or claude-opus-4)
+  Why needed   : Spec analysis, architecture review, code generation
+                 require deep reasoning. Smaller models miss edge cases.
+
+  To switch in Claude Code:
+    • Settings → Model → select "claude-opus"
+    • or: /model → choose claude-opus
+
+  Running on claude-opus?
+    Y — yes, on claude-opus → proceed
+    S — skip check (I accept lower quality risk with current model)
+──────────────────────────────────────────────────────────────────
+```
+
+- "Y" → proceed to Step 1.
+- "S" → proceed to Step 1 (user accepts risk, add ⚠️ to final report).
+- "N" or anything else → **STOP.** Output: "Please switch to claude-opus, then re-run this command."
+
+## Step 1 — Resolve Target File
+
+1. If `$ARGUMENTS` is provided and points to an existing file → use it directly as the target.
+2. If `$ARGUMENTS` is a UC-ID, ticket ID, or partial name → search for matching files in the relevant directory.
+3. If `$ARGUMENTS` is empty or no match found:
+   - List files in the relevant directory for this command (e.g., `specs/prd/**/*.md` for PRD commands, `specs/bdd/**/*.feature` for BDD commands).
+   - Present the list to the user and ask: "Which file do you want to work with? (Enter number or filename)"
+   - Wait for user selection before continuing.
+
+## Step 2 — Execute Context Loader
+
+Load all project context by following the procedure in `steps/context-loader.md`.
+Store all loaded context in memory for use throughout this command session.
+
+## Step 3 — CHECKPOINT
+
+After completing Steps 1 and 2, display a summary and wait for confirmation:
+
+```
+CHECKPOINT
+-----------
+Target     : {resolved file path}
+Project    : {project.name from project-context.yaml}
+Tech stack : {language} / {framework}
+Module     : {module if set, else "not configured"}
+Domains    : {comma-separated domain list}
+
+Proceed? (Y/N)
+```
+
+Wait for explicit "Y" or "N" from the user before continuing.
+- "Y" → proceed to the command-specific steps below.
+- "N" → stop and ask what the user wants to change.
+
+
+### Analyze — 4 Lenses (run all four perspectives)
+
+#### QA Lens — Test Coverage & Edge Cases
+Evaluate:
+- Are all acceptance criteria testable and measurable?
+- Are edge cases and error scenarios specified?
+- Are boundary conditions defined?
+- Is there ambiguity in expected behavior?
+
+#### DEV Lens — Technical Clarity & Feasibility
+Evaluate:
+- Are API inputs/outputs clearly defined?
+- Are business rules unambiguous enough to implement?
+- Are there performance or scalability concerns?
+- Are cross-service dependencies fully described?
+- Is there anything technically infeasible or risky?
+
+#### SA Lens — Architecture & Design
+Evaluate:
+- Does this fit the existing architecture?
+- Are there design patterns or constraints to apply?
+- Is data modeling clear (entities, relationships)?
+- Are there security or auth implications?
+
+#### PO Lens — Business Value & Scope
+Evaluate:
+- Is scope clearly bounded?
+- Are priorities clear?
+- Are success metrics defined?
+- Are stakeholder needs fully captured?
+- Any scope creep risk?
+
+### Write Output
+
+Derive the output filename from the PRD slug:
+- PRD file: `specs/prd/payment/create-invoice.md` → output: `.agent/review/create-invoice-findings.yaml`
+- Rule: take the PRD filename (without `.md`), append `-findings.yaml`
+
+Write findings to `.agent/review/{prd-slug}-findings.yaml`:
+
+```yaml
+# Generated by /refine-prd
+# Review each finding and mark: accepted / rejected / needs_discussion
+prd_source: "specs/prd/{domain}/{slug}.md"
+generated_at: "{ISO datetime}"
+status: "pending_review"
+
+findings:
+  - id: "F001"
+    lens: "QA"           # QA | DEV | SA | PO
+    severity: "major"    # critical | major | minor
+    section: "§6. Acceptance Criteria"
+    finding: "{Clear description of the gap or issue}"
+    suggestion: "{Specific actionable improvement}"
+    status: "pending"    # pending | accepted | rejected | needs_discussion
+
+  - id: "F002"
+    lens: "DEV"
+    severity: "minor"
+    section: "§8. Cross-Service Dependencies"
+    finding: "{finding}"
+    suggestion: "{suggestion}"
+    status: "pending"
+
+summary:
+  total_findings: {N}
+  by_severity:
+    critical: {N}
+    major: {N}
+    minor: {N}
+  by_lens:
+    QA: {N}
+    DEV: {N}
+    SA: {N}
+    PO: {N}
+  recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
+```
+
+### Report to User
+
+```
+/refine-prd Complete — {PRD name}
+
+Findings: {total} total
+  🔴 Critical: {N}  🟡 Major: {N}  🟢 Minor: {N}
+
+Top issues:
+  [F001] QA/major — {brief description}
+  [F002] DEV/minor — {brief description}
+
+Review file: .agent/review/{prd-slug}-findings.yaml
+→ Open with Review Board extension (right-click file) to accept/reject each finding
+→ After review: update PRD and run /generate-bdd
+```
+
+# Report Footer — Standard Command Output Format
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /define-product         | `/generate-prd {product-definition-file}`     |
+| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
+| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
+| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
+| /generate-code          | `/generate-tests {UC-ID}`                     |
+| /generate-tests         | `/run-tests {UC-ID}`                          |
+| /run-tests (passing)    | `/review-code {UC-ID}`                        |
+| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/smoke-test {UC-ID}` or create PR            |
+| /smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | `/generate-code {UC-ID}` for gaps             |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+
+Format the footer as:
+```
+---
+Status : {badge}
+{Output Artifacts block}
+Next   : {suggested command with example arguments}
+```
+