@anhth2/spec-driven-dev-plugin 0.5.0

package/skills/spec/SKILL.md

@@ -0,0 +1,361 @@
+---
+description: Generates BDD .feature files from an approved PRD, or generates technical design documents. Trigger when: "/generate-bdd", "/generate-tech-docs", "tạo BDD", "tạo spec", "generate feature file", "write BDD scenarios", "tạo technical design", "tech design", "sinh tech docs", "API design", "sinh .feature".
+---
+
+# Spec Skills — BDD & Technical Design
+
+This skill handles two commands: `/generate-bdd` to create BDD feature files, and `/generate-tech-docs` to create technical design documents.
+
+---
+
+## /generate-bdd — Generate BDD Feature Files
+
+### 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.
+
+
+Also verify: Check that the PRD `Status` is `approved` (not `draft`).
+- If `draft`: warn "PRD is still draft. Proceed anyway? Findings from /refine-prd may not be addressed yet."
+
+### UC Decomposition
+
+For each Use Case in the PRD, derive scenarios. Present outline:
+
+```
+{DOMAIN}-UC1: {Name}
+  SC1: Happy path — {client/role type} — {success scenario}
+  SC2: Happy path — {other client/role type} (if applicable)
+  SC3: Validation error — {invalid input}
+  SC4: Not found / resource missing
+  BRs covered: BR-1, BR-2
+
+{DOMAIN}-UC2: {Name}
+  ...
+```
+
+**CHECKPOINT** — Ask: "Does this outline look correct? Any missing scenarios?"
+Wait for confirmation before generating files.
+
+### Generate
+
+For each UC, write `specs/bdd/{domain}/{UC-ID}-{slug}.feature`:
+
+```gherkin
+# @trace.source=specs/prd/{domain}/{slug}.md
+# @trace.uc={UC-ID}
+Feature: {UC Name}
+
+  Background:
+    Given the system is running
+    And a {persona} is authenticated
+
+  Scenario: SC1 — {Happy path description}
+    Given {precondition}
+    When {action}
+    Then {expected outcome}
+    And {secondary outcome if any}
+
+  Scenario: SC2 — {Another happy path}
+    Given {precondition}
+    When {action}
+    Then {expected outcome}
+
+  Scenario: SC3 — Validation error
+    Given {precondition}
+    When {invalid action}
+    Then the system returns a validation error
+    And the error message mentions "{field}"
+
+  Scenario: SC4 — Resource not found
+    Given no {resource} exists with id {id}
+    When {action}
+    Then the system returns a not-found error
+```
+
+### Quality Check
+
+After generating, self-evaluate:
+- [ ] Every acceptance criteria from PRD has at least one scenario
+- [ ] Every business rule is covered by at least one scenario
+- [ ] Error scenarios are present (validation, not-found, unauthorized)
+- [ ] Scenarios are atomic (one behavior per scenario)
+- [ ] No implementation details in feature files (no SQL, no class names)
+
+### Output
+
+```
+/generate-bdd Complete — {domain}
+
+Files created:
+  ✅ specs/bdd/{domain}/{UC-ID}-{slug}.feature ({N} scenarios)
+  ...
+
+Quality: {score}%
+```
+
+# 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}
+```
+
+
+---
+
+## /generate-tech-docs — Generate Technical Design Document
+
+### Gate
+
+Check BDD quality (read .feature files, verify scenarios are well-formed).
+If quality < 80%, halt and report: "BDD quality insufficient. Fix these issues first: [list]"
+
+### Generate
+
+Write `tech-docs/{domain}/{UC-ID}-tech-design.md`:
+
+```markdown
+# Technical Design — {UC-ID}: {Feature}
+
+**Domain**: {domain}
+**Date**: {date}
+**Spec**: specs/bdd/{domain}/{UC-ID}.feature
+
+## §1. Overview
+{Brief description of what this UC implements}
+
+## §2. API Endpoints
+
+| Method | Path | Auth/Role | Request Body | Response |
+|--------|------|-----------|--------------|----------|
+| GET    | /v1/{resource} | {role} | — | {ResponseDTO} |
+| POST   | /v1/{resource} | {role} | {RequestDTO} | {ResponseDTO} |
+
+## §3. Data Model
+
+{Entity diagram or table structure}
+
+Key entities:
+- `{Entity}`: {description, key fields}
+
+## §4. Service Flow
+
+Sequence for each UC:
+```
+{Client} → Controller → {Facade} → {Service} → {Repository}
+                              ↓
+                    {OtherService} (if cross-service)
+```
+
+## §5. Business Rules Implementation
+
+| BR-ID | Rule | Implementation approach |
+|-------|------|------------------------|
+| BR-1 | {rule} | {how to implement} |
+
+## §6. Error Handling
+
+| Scenario | Exception | HTTP Status |
+|----------|-----------|-------------|
+| {resource} not found | {NotFoundException} | 404 |
+| Validation failure | {ValidationException} | 400 |
+| Unauthorized | {AuthException} | 403 |
+
+## §7. Database Changes
+
+{Migration script or schema changes needed}
+
+## §8. Caching Strategy
+
+{Which data to cache, TTL, invalidation triggers — or "N/A"}
+
+## §9. Cross-Service Dependencies
+
+{List external service calls, event producers/consumers}
+```
+
+Instruct: "SA/Lead should review and approve before running /generate-code."
+
+# 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}
+```
+

package/skills/spec/SKILL.tmpl

@@ -0,0 +1,174 @@
+---
+description: Generates BDD .feature files from an approved PRD, or generates technical design documents. Trigger when: "/generate-bdd", "/generate-tech-docs", "tạo BDD", "tạo spec", "generate feature file", "write BDD scenarios", "tạo technical design", "tech design", "sinh tech docs", "API design", "sinh .feature".
+---
+
+# Spec Skills — BDD & Technical Design
+
+This skill handles two commands: `/generate-bdd` to create BDD feature files, and `/generate-tech-docs` to create technical design documents.
+
+---
+
+## /generate-bdd — Generate BDD Feature Files
+
+### Gate
+
+<!-- Directory: specs/prd/**/*.md -->
+{{include:steps/gate.md}}
+
+Also verify: Check that the PRD `Status` is `approved` (not `draft`).
+- If `draft`: warn "PRD is still draft. Proceed anyway? Findings from /refine-prd may not be addressed yet."
+
+### UC Decomposition
+
+For each Use Case in the PRD, derive scenarios. Present outline:
+
+```
+{DOMAIN}-UC1: {Name}
+  SC1: Happy path — {client/role type} — {success scenario}
+  SC2: Happy path — {other client/role type} (if applicable)
+  SC3: Validation error — {invalid input}
+  SC4: Not found / resource missing
+  BRs covered: BR-1, BR-2
+
+{DOMAIN}-UC2: {Name}
+  ...
+```
+
+**CHECKPOINT** — Ask: "Does this outline look correct? Any missing scenarios?"
+Wait for confirmation before generating files.
+
+### Generate
+
+For each UC, write `specs/bdd/{domain}/{UC-ID}-{slug}.feature`:
+
+```gherkin
+# @trace.source=specs/prd/{domain}/{slug}.md
+# @trace.uc={UC-ID}
+Feature: {UC Name}
+
+  Background:
+    Given the system is running
+    And a {persona} is authenticated
+
+  Scenario: SC1 — {Happy path description}
+    Given {precondition}
+    When {action}
+    Then {expected outcome}
+    And {secondary outcome if any}
+
+  Scenario: SC2 — {Another happy path}
+    Given {precondition}
+    When {action}
+    Then {expected outcome}
+
+  Scenario: SC3 — Validation error
+    Given {precondition}
+    When {invalid action}
+    Then the system returns a validation error
+    And the error message mentions "{field}"
+
+  Scenario: SC4 — Resource not found
+    Given no {resource} exists with id {id}
+    When {action}
+    Then the system returns a not-found error
+```
+
+### Quality Check
+
+After generating, self-evaluate:
+- [ ] Every acceptance criteria from PRD has at least one scenario
+- [ ] Every business rule is covered by at least one scenario
+- [ ] Error scenarios are present (validation, not-found, unauthorized)
+- [ ] Scenarios are atomic (one behavior per scenario)
+- [ ] No implementation details in feature files (no SQL, no class names)
+
+### Output
+
+```
+/generate-bdd Complete — {domain}
+
+Files created:
+  ✅ specs/bdd/{domain}/{UC-ID}-{slug}.feature ({N} scenarios)
+  ...
+
+Quality: {score}%
+```
+
+{{include:steps/report-footer.md}}
+
+---
+
+## /generate-tech-docs — Generate Technical Design Document
+
+### Gate
+
+Check BDD quality (read .feature files, verify scenarios are well-formed).
+If quality < 80%, halt and report: "BDD quality insufficient. Fix these issues first: [list]"
+
+### Generate
+
+Write `tech-docs/{domain}/{UC-ID}-tech-design.md`:
+
+```markdown
+# Technical Design — {UC-ID}: {Feature}
+
+**Domain**: {domain}
+**Date**: {date}
+**Spec**: specs/bdd/{domain}/{UC-ID}.feature
+
+## §1. Overview
+{Brief description of what this UC implements}
+
+## §2. API Endpoints
+
+| Method | Path | Auth/Role | Request Body | Response |
+|--------|------|-----------|--------------|----------|
+| GET    | /v1/{resource} | {role} | — | {ResponseDTO} |
+| POST   | /v1/{resource} | {role} | {RequestDTO} | {ResponseDTO} |
+
+## §3. Data Model
+
+{Entity diagram or table structure}
+
+Key entities:
+- `{Entity}`: {description, key fields}
+
+## §4. Service Flow
+
+Sequence for each UC:
+```
+{Client} → Controller → {Facade} → {Service} → {Repository}
+                              ↓
+                    {OtherService} (if cross-service)
+```
+
+## §5. Business Rules Implementation
+
+| BR-ID | Rule | Implementation approach |
+|-------|------|------------------------|
+| BR-1 | {rule} | {how to implement} |
+
+## §6. Error Handling
+
+| Scenario | Exception | HTTP Status |
+|----------|-----------|-------------|
+| {resource} not found | {NotFoundException} | 404 |
+| Validation failure | {ValidationException} | 400 |
+| Unauthorized | {AuthException} | 403 |
+
+## §7. Database Changes
+
+{Migration script or schema changes needed}
+
+## §8. Caching Strategy
+
+{Which data to cache, TTL, invalidation triggers — or "N/A"}
+
+## §9. Cross-Service Dependencies
+
+{List external service calls, event producers/consumers}
+```
+
+Instruct: "SA/Lead should review and approve before running /generate-code."
+
+{{include:steps/report-footer.md}}