@anhth2/spec-driven-dev-plugin 0.5.0

package/core/steps/context-loader.md

@@ -0,0 +1,163 @@
+# Context Loader — Load All Project Context
+
+Execute these steps in order. Store everything in memory for the duration of the command session.
+
+**Priority guide (anti-lost-in-middle):**
+- Steps 1–2 are PROJECT-CONFIG — loaded first, resolve all paths and metadata.
+- Step 3 is CRITICAL — architecture + coding standards, the highest-priority facts for generation.
+- Step 4 is SAFETY — data protection rules, enforced silently for the entire session.
+- Steps 5–6 are DOMAIN KNOWLEDGE — terminology and entity definitions.
+- Step 7 is the WORKING MEMORY RECAP — locks critical facts into the top of working memory.
+
+---
+
+## Step 1 — [PROJECT-CONFIG] Load project-context.yaml
+
+Read `.agent/project-context.yaml`. Extract and store:
+
+**Tech Stack:**
+- `tech_stack.language` → active language (e.g., Java 17, TypeScript, C#, Go)
+- `tech_stack.framework` → active framework (e.g., Spring Boot 3.2, Angular 17, .NET 8)
+- `tech_stack.build_tool` → build tool (e.g., Maven, npm, dotnet, go)
+- `tech_stack.test_framework` → test framework (e.g., JUnit 5 + Mockito, Jest, xUnit)
+- `tech_stack.database` → database (e.g., PostgreSQL, MySQL, MongoDB)
+- `tech_stack.module` → active module profile (e.g., java-spring, angular, dotnet, golang, context-engineering)
+
+**Conventions:**
+- `conventions.build_command` → how to compile/build
+- `conventions.test_command` → how to run tests
+- `conventions.service_run` → how to start the service
+- `conventions.ticket_prefix` → ticket ID prefix (e.g., PROJ, FEAT, UC)
+
+**Domains:**
+- `domains` → list of active business domains
+
+**Paths (if present):**
+- `paths.specs_dir` → BDD specs root
+- `paths.prd_dir` → PRD documents root
+- `paths.refinement_dir` → findings/review output dir
+- `paths.product_definitions_dir` → product definitions root
+- `paths.domain_knowledge_dir` → domain knowledge root
+- `paths.business_dictionary` → path to business-dictionary.md
+- `paths.core_entities` → path to core-entities.md
+- `paths.tech_docs_dir` → technical documentation root
+- `paths.trace_dir` → trace state directory
+
+If `paths` section is absent, use these defaults:
+- `specs_dir` = `specs/bdd`
+- `prd_dir` = `specs/prd`
+- `refinement_dir` = `.agent/review`
+- `product_definitions_dir` = `specs/product-definition`
+- `domain_knowledge_dir` = `specs/domain-knowledge`
+- `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
+- `core_entities` = `specs/domain-knowledge/core-entities.md`
+- `tech_docs_dir` = `tech-docs`
+- `trace_dir` = `.trace`
+
+If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
+
+---
+
+## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
+
+If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
+Merge framework-specific conventions (layer patterns, test patterns, naming rules) into the loaded context.
+If the file does not exist → skip silently.
+
+---
+
+## Step 3 — [CRITICAL] Load CLAUDE.md
+
+*This is the highest-priority context — it defines HOW to write code and documents for this project.*
+
+Read `CLAUDE.md`. Extract and store:
+
+- **§1 Project Overview** → project name, language, framework, build/test commands, domains
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
+- **§7 Git Conventions** → branch naming pattern, commit message format
+
+If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+
+---
+
+## Step 4 — [SAFETY] Load Data Protection Rules
+
+Read `.agent/rules/data-protection.md` (or `rules/data-protection.md` from the framework installation).
+
+Store the sensitive file patterns — you must **never** read, write, display, or reference content from files matching those patterns for the entire session.
+
+If neither file exists → apply built-in defaults: never access `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`.
+
+---
+
+## Step 5 — [DOMAIN] Load Business Dictionary (conditional)
+
+Check if the business dictionary file exists (use `paths.business_dictionary` resolved in Step 1).
+
+If it exists, read it and extract:
+- **Canonical Terms** → complete list of approved terms and their definitions
+- **Banned Terms** → complete list of banned terms and their canonical replacements
+- **Status / Enum Registry** → allowed enum values per entity
+
+Store the banned terms list for **active enforcement** throughout the command session:
+- When generating any text (PRD, BDD, code comments, tech docs), verify no banned terms appear
+- Replace banned terms with their canonical equivalents automatically
+
+If the file does not exist → skip silently. Do not warn or block.
+
+---
+
+## Step 6 — [DOMAIN] Load Core Entities (conditional)
+
+Check if the core entities file exists at `paths.core_entities` (resolved in Step 1).
+Default path: `specs/domain-knowledge/core-entities.md`.
+
+If it exists, read it and store:
+- **Entity catalog** → for each entity: its name, purpose, owner service, key fields (name + type), business invariants, and relationships
+- **Field name registry** → canonical field names to use in generated code and documents
+- **Relationship map** → how entities relate to each other (1:N, N:N, embedded, etc.)
+
+**How to use this catalog:**
+- When generating code: use the field names, types, and relationships defined here — do NOT infer from existing code
+- When generating PRD/BDD: reference entity names from this catalog for consistency
+- When generating tech-docs: use this catalog as the source-of-truth for entity definitions
+
+If the file does not exist → skip silently.
+
+---
+
+## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
+
+After loading all context, synthesize and output a compact summary block.
+This recap ensures the most critical facts are stated at the END of context loading
+(recency effect — freshest in working memory when the task begins).
+
+Output exactly this block:
+```
+[CTX LOADED]
+Stack     : {language} / {framework} / {database}
+Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Ticket    : {ticket_prefix}-
+Dict      : {loaded — N canonical terms, M banned terms | missing}
+Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
+```
+
+If any CRITICAL file is missing (CLAUDE.md), flag it clearly so the user can decide whether to proceed.
+
+---
+
+## Context Load Complete
+
+After completing all steps, you have loaded:
+- Project identity, tech stack, module conventions
+- Architecture rules and layer order  ← **[CRITICAL — hold in working memory]**
+- Coding standards and naming conventions  ← **[CRITICAL — hold in working memory]**
+- Data protection rules (sensitive file patterns to never access)
+- Terminology rules with banned-term list  ← **[DOMAIN — apply to every generated word]**
+- Entity catalog (field names, types, invariants)  ← **[DOMAIN — use for code generation]**
+- All configured paths
+
+Proceed to the next step of the calling command.

package/core/steps/gate.md

@@ -0,0 +1,81 @@
+# 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.

package/core/steps/report-footer.md

@@ -0,0 +1,53 @@
+# 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/steps/spawn-agent.md

@@ -0,0 +1,123 @@
+# Sub-Agent Orchestration Pattern
+
+Used by heavy commands when the target exceeds the complexity threshold.
+The main session becomes a **lightweight orchestrator** — it only coordinates.
+Each unit of work runs in its own sub-agent with a fresh context window.
+
+---
+
+## Complexity Thresholds
+
+| Signal | Threshold | Action |
+|--------|-----------|--------|
+| UC count in PRD | > 3 UCs | spawn 1 agent per UC |
+| PRD length | > 300 lines | spawn agents regardless of UC count |
+
+If **either** threshold is exceeded → switch to orchestration mode.
+
+---
+
+## Orchestrator Steps (main session)
+
+### Step A — Build slim context
+
+Extract only what sub-agents need — do NOT pass full CLAUDE.md or full business-dictionary:
+
+```json
+{
+  "project_name": "{project.name}",
+  "tech_stack": {
+    "language":       "{tech_stack.language}",
+    "framework":      "{tech_stack.framework}",
+    "build_tool":     "{tech_stack.build_tool}",
+    "test_framework": "{tech_stack.test_framework}",
+    "database":       "{tech_stack.database}",
+    "module":         "{tech_stack.module}"
+  },
+  "conventions": {
+    "build_command":  "{conventions.build_command}",
+    "commit_format":  "{conventions.commit_format}"
+  },
+  "paths": {
+    "specs_dir":     "{paths.specs_dir}",
+    "prd_dir":       "{paths.prd_dir}",
+    "trace_dir":     "{paths.trace_dir}",
+    "tech_docs_dir": "{paths.tech_docs_dir}"
+  },
+  "architecture_summary": "<3-5 bullet points: layer order + key rules only>",
+  "domains": ["{domain1}", "{domain2}"],
+  "banned_terms": ["{term1}", "{term2}"]
+}
+```
+
+### Step B — Extract UC list
+
+Scan the target PRD for `#### {TICKET-ID}-UC{N}:` headings.
+Build list: `[ { uc_id, uc_name, line_start, line_end } ]`
+
+### Step C — Announce plan
+
+```
+High complexity detected — {N} UCs / {L} lines in {prd_file}
+Spawning {N} sub-agents (1 per UC)...
+  Agent 1 → {TICKET-ID}-UC1: {UC name}
+  Agent 2 → {TICKET-ID}-UC2: {UC name}
+  ...
+```
+
+### Step D — Spawn one sub-agent per UC
+
+Build payload and invoke Agent tool for each UC:
+
+```json
+{
+  "_agent_mode": true,
+  "command":      "{generate-bdd | generate-code | generate-tests}",
+  "uc_id":        "{TICKET-ID}-UC{N}",
+  "target_file":  "{absolute path to PRD or feature file}",
+  "uc_section":   { "line_start": {N}, "line_end": {N} },
+  "context":      { "<slim context from Step A>" }
+}
+```
+
+Serialize this JSON and pass as `$ARGUMENTS` when invoking the sub-agent command.
+
+### Step E — Collect and merge results
+
+Each sub-agent returns:
+```json
+{
+  "uc_id":         "{TICKET-ID}-UC{N}",
+  "files_created": ["path/to/file1", "path/to/file2"],
+  "status":        "success | error",
+  "errors":        []
+}
+```
+
+Merge into a single report (follow report-footer.md format).
+If any sub-agent errors → list them clearly and suggest re-run for that UC only.
+
+---
+
+## Sub-Agent Entry Point (called commands)
+
+When `gate.md Step 0` detects `_agent_mode: true`:
+
+1. Parse full payload from `$ARGUMENTS`
+2. **Skip context-loader.md** — use `payload.context` directly
+3. **Scope to `payload.uc_id` only** — do not process other UCs in the file
+4. Read only the PRD section between `payload.uc_section.line_start` and `line_end`
+5. Execute the command's normal logic for this single UC
+6. Return structured result JSON (Step E format above)
+
+---
+
+## Context Window Savings
+
+| Mode | What loads per session |
+|------|------------------------|
+| Single session (≤ 3 UC) | Full context + full PRD + all UCs |
+| Orchestrator | Slim context + UC headings only |
+| Each sub-agent | Slim context + **1 UC section only** |
+
+The larger the PRD, the bigger the saving per sub-agent.

package/core/templates/architecture.template.md

@@ -0,0 +1,113 @@
+# §1. Project Overview
+
+Project    : {{PROJECT_NAME}}
+Language   : {{LANGUAGE}}          # e.g., Java 17 / TypeScript / C# / Go
+Framework  : {{FRAMEWORK}}         # e.g., Spring Boot 3.2 / Angular 17 / .NET 8
+Build      : {{BUILD_COMMAND}}     # e.g., mvn clean install -DskipTests / dotnet build / ng build
+Test       : {{TEST_COMMAND}}      # e.g., mvn test / dotnet test / ng test
+Domains    : {{COMMA_SEPARATED_DOMAINS}}
+
+# §2. Architecture
+
+style: "{{ARCH_STYLE}}"  # e.g., Layered / Clean / Hexagonal / Component-based
+
+layers: "{{LAYER_STACK}}"
+# Examples:
+#   Java/Spring:  Controller → Facade → Service → Repository
+#   .NET Clean:   Presentation → Application → Domain → Infrastructure
+#   Angular:      Component → Service → HTTP Client → Backend API
+#   Go:           Handler → UseCase → Repository → Domain
+
+rules:
+  - "{{ARCH_RULE_1}}"  # e.g., Controllers must not contain business logic
+  - "{{ARCH_RULE_2}}"  # e.g., Services own transaction boundaries
+  - "{{ARCH_RULE_3}}"  # e.g., Repositories must not call services
+
+# Layer dependency direction (inner layers must not depend on outer):
+# {{OUTER_LAYER}} → {{MIDDLE_LAYER}} → {{INNER_LAYER}}
+
+# §3. Coding Standards
+
+naming:
+  classes: "{{CLASS_NAMING}}"        # e.g., PascalCase / PascalCase+Suffix
+  methods: "{{METHOD_NAMING}}"       # e.g., camelCase / PascalCase
+  packages: "{{PACKAGE_NAMING}}"     # e.g., lowercase / lowercase.snake_case
+  files: "{{FILE_NAMING}}"           # e.g., PascalCase.java / kebab-case.ts
+
+patterns:
+  response_wrapper: "{{RESPONSE_WRAPPER}}"  # e.g., ApiResponse<T> / Result<T> / IActionResult
+  mapping: "{{MAPPING_LIBRARY}}"            # e.g., MapStruct / AutoMapper / manual
+  exception_base: "{{BASE_EXCEPTION}}"      # e.g., ResourceNotFoundException / DomainException
+
+forbidden:
+  - "Magic numbers — use named constants"
+  - "Debug print statements in production code"
+  - "{{PROJECT_SPECIFIC_FORBIDDEN_PATTERN}}"
+
+# §4. API Conventions
+
+versioning: "{{API_VERSIONING}}"     # e.g., /v1/ prefix / header-based / query param
+auth: "{{AUTH_MECHANISM}}"           # e.g., JWT Bearer / OAuth2 / API Key
+
+http_status:
+  get_list:    200   # paginated or full list
+  get_single:  200
+  create:      201
+  update:      200
+  delete:      204
+  bad_request: 400
+  unauthorized: 401
+  forbidden:   403
+  not_found:   404
+  server_error: 500
+
+error_response_format: |
+  {
+    "code": "ERROR_CODE",
+    "message": "Human readable message",
+    "details": {}   // optional field-level errors
+  }
+
+# §5. Error Handling
+
+not_found_exception: "{{NOT_FOUND_EXCEPTION_CLASS}}"  # e.g., ResourceNotFoundException
+validation_exception: "{{VALIDATION_EXCEPTION_CLASS}}" # e.g., ValidationException
+domain_exception: "{{DOMAIN_EXCEPTION_CLASS}}"         # e.g., DomainException / BusinessRuleViolationException
+
+global_handler: "{{GLOBAL_EXCEPTION_HANDLER}}"  # e.g., @ControllerAdvice / ExceptionHandlerMiddleware
+
+rules:
+  - "Never swallow exceptions silently"
+  - "Log at error level with full stack trace for 5xx"
+  - "{{PROJECT_SPECIFIC_ERROR_RULE}}"
+
+# §6. Testing Standards
+
+unit_test_framework: "{{UNIT_TEST_FW}}"        # e.g., JUnit 5 + Mockito / xUnit + Moq / Jest
+integration_test_framework: "{{IT_TEST_FW}}"   # e.g., Spring Boot Test / WebApplicationFactory
+
+coverage_targets:
+  unit: "{{UNIT_COVERAGE_PCT}}%"          # e.g., 80%
+  integration: "{{IT_COVERAGE_PCT}}%"     # e.g., key flows covered
+
+naming_pattern: "{{TEST_METHOD_NAMING}}"  # e.g., methodName_whenCondition_shouldExpectation
+
+rules:
+  - "Unit tests mock direct dependencies only"
+  - "Integration tests cover happy path + main error paths"
+  - "Every scenario in .feature must have a corresponding test"
+
+# §7. Git Conventions
+
+branch_feature: "feature/{{TICKET_PREFIX}}-{N}-{slug}"
+branch_fix:     "fix/{{TICKET_PREFIX}}-{N}-{slug}"
+branch_chore:   "chore/{slug}"
+
+commit_feature: "feat({{TICKET_PREFIX}}-{N}): {description}"
+commit_fix:     "fix({{TICKET_PREFIX}}-{N}): {description}"
+commit_chore:   "chore: {description}"
+commit_docs:    "docs: {description}"
+
+pr_title: "{{TICKET_PREFIX}}-{N}: {feature name}"
+pr_requires_review: true
+pr_branch_protection: "{{BASE_BRANCH}}"  # e.g., main / develop