@anhth2/spec-driven-dev-plugin 0.5.0

package/core/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}
+```
+

package/core/skills/setup-ai-first/SKILL.md

@@ -0,0 +1,160 @@
+---
+description: Sets up the Spec-Driven Development framework in any backend project from scratch. Trigger when: "/setup-ai-first", "setup spec-driven workflow", "initialize ai-first framework", "cài đặt framework", "khởi tạo spec-driven", "set up this workflow", "how do I start using this plugin".
+---
+
+# /setup-ai-first — Initialize Spec-Driven Dev in a Project
+
+Walk the user through a one-time setup that creates all required directories, installs CLAUDE.md, and verifies the environment.
+
+## Precondition Check
+
+First, ask: "Bạn đang ở project nào? Cho tôi đường dẫn root của project."
+
+Check if already set up:
+- If `.claude/commands/` exists with `.md` files → report "Already set up. Run `/validate-traces` to check status."
+- If `specs/` exists → offer to re-initialize or skip
+
+## Step 1 — Create Directory Structure
+
+Create the following directories (skip if already exist):
+
+```
+{project-root}/
+├── specs/
+│   ├── product-definition/   # Output of /define-product
+│   ├── prd/                  # Output of /generate-prd
+│   └── bdd/                  # Output of /generate-bdd (.feature files)
+├── tech-docs/                # Output of /generate-tech-docs
+├── .trace/                   # Traceability state files (.tsv)
+└── .agent/
+    └── review/               # Output of /refine-prd ({prd-slug}-findings.yaml)
+```
+
+Report each directory created or already existing.
+
+## Step 2 — Copy Slash Commands
+
+Tell the user:
+
+> "Plugin này đã cài slash commands vào Claude tự động qua skill system.
+> Nếu bạn muốn dùng commands trực tiếp trong Claude Code project (`.claude/commands/`), chạy lệnh sau:"
+
+```bash
+# Copy all commands from plugin to project
+mkdir -p {project-root}/.claude/commands
+cp {plugin-dir}/commands/*.md {project-root}/.claude/commands/
+```
+
+Note: The `.claude/commands/` copies are optional. Skills in this plugin work without them.
+
+## Step 3 — Create CLAUDE.md
+
+Check if `{project-root}/CLAUDE.md` exists:
+- If yes: ask "CLAUDE.md đã tồn tại. Merge template vào hay bỏ qua?"
+- If no: create from template in `templates/architecture.template.md`
+
+After creating, instruct:
+> "Mở CLAUDE.md và điền vào các placeholder `{{...}}` với thông tin dự án của bạn.
+> Đặc biệt quan trọng: §1 (project overview) và §3 (coding standards)."
+
+## Step 4 — Create project-context.yaml
+
+Create `{project-root}/.agent/project-context.yaml`:
+
+```yaml
+# Project context for AI-First workflow
+# Fill in all fields before starting
+
+project:
+  name: "{{PROJECT_NAME}}"
+  description: "{{ONE_LINE_DESCRIPTION}}"
+
+tech_stack:
+  language: "{{LANGUAGE}}"           # e.g. Java 21, Python 3.12, Node.js 20
+  framework: "{{FRAMEWORK}}"         # e.g. Spring Boot 3.x, FastAPI, NestJS
+  build_tool: "{{BUILD_TOOL}}"       # e.g. Gradle, Maven, npm
+  test_framework: "{{TEST_FW}}"      # e.g. JUnit 5, pytest, Jest
+  orm: "{{ORM}}"                     # e.g. Hibernate/JPA, SQLAlchemy, Prisma
+  database: "{{DATABASE}}"           # e.g. PostgreSQL, MySQL, MongoDB
+
+conventions:
+  build_command: "{{BUILD_COMMAND}}"   # e.g. ./gradlew build -x test
+  test_command: "{{TEST_COMMAND}}"     # e.g. ./gradlew test
+  service_run: "{{RUN_COMMAND}}"       # e.g. ./gradlew bootRun
+  ticket_prefix: "{{TICKET_PREFIX}}"  # e.g. PROJ, FEAT, PD
+
+domains: []  # List your business domains, e.g. [rental, payment, user]
+```
+
+## Step 5 — Verify Setup
+
+Run a quick check:
+- [ ] `specs/` directory exists
+- [ ] `.trace/` directory exists
+- [ ] `.agent/project-context.yaml` exists
+- [ ] `CLAUDE.md` exists
+
+Report:
+```
+/setup-ai-first Complete ✅
+
+Directories created: {N}
+Files created:
+  ✅ CLAUDE.md (needs customization)
+  ✅ .agent/project-context.yaml (needs customization)
+```
+
+# 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}
+```
+