@anhth2/spec-driven-dev-plugin 0.5.0

package/commands/setup-ai-first.md

@@ -0,0 +1,278 @@
+# /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.
+
+## Gate
+# 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.
+
+
+*Note: For this command, there is no input file. Skip Step 1 file discovery. In Step 2, skip project-context.yaml loading (it does not exist yet). Ask: "Which project are you setting up? Give me the root path of the project."*
+
+---
+
+## Precondition Check
+
+Check if already set up:
+- If `.claude/commands/` exists with `.md` files → report "Already set up."
+- If `specs/` exists → offer to re-initialize or skip
+
+## Step 1 — Create Directory Structure
+
+Create these directories (skip if they exist):
+
+```
+{project-root}/
+├── specs/
+│   ├── product-definition/
+│   ├── prd/
+│   ├── bdd/
+│   └── domain-knowledge/     ← business dictionary & domain context
+├── tech-docs/
+├── .trace/
+└── .agent/
+    └── review/
+```
+
+## Step 2 — Create CLAUDE.md
+
+Check if `CLAUDE.md` exists:
+- Yes → ask "Merge template or skip?"
+- No → create from the template below
+
+After creating, instruct: "Open CLAUDE.md and fill in the `{{PLACEHOLDER}}` values with your project information."
+
+### CLAUDE.md Template
+
+```
+# §1. Project Overview
+Project: {{PROJECT_NAME}}
+Language: {{LANGUAGE}}
+Framework: {{FRAMEWORK}}
+Build: {{BUILD_COMMAND}}
+Test: {{TEST_COMMAND}}
+Domains: {{COMMA_SEPARATED_DOMAINS}}
+
+# §2. Architecture
+layers: "{{LAYER_STACK}}"
+# Example: Controller → Facade → Service → Repository
+rules:
+  - "Controllers must not contain business logic"
+  - "Services own transaction boundaries"
+
+# §3. Coding Standards
+naming:
+  classes: "{{NAMING_CONVENTION}}"
+  methods: "{{METHOD_CONVENTION}}"
+response_wrapper: "{{WRAPPER}}"
+forbidden:
+  - "Magic numbers"
+  - "Debug print statements"
+
+# §4. Traceability
+# Every controller method must be tagged:
+# @trace.implements={UC-ID}-{SC-ID}
+# @trace.source=specs/bdd/{domain}/{UC-ID}.feature
+# Tests must be tagged:
+# @trace.verifies={UC-ID}
+
+# §5. Error Handling
+not_found: "{{NOT_FOUND_EXCEPTION}}"
+http_codes: { get: 200, create: 201, not_found: 404, validation: 400 }
+
+# §6. Build & Test
+build_command: "{{BUILD_COMMAND}}"
+test_command: "{{TEST_COMMAND}}"
+run_command: "{{RUN_COMMAND}}"
+
+# §7. Git Conventions
+branch_feature: "feature/{{TICKET_PREFIX}}-{N}-{slug}"
+commit_feature: "feat({{TICKET_PREFIX}}-{N}): {description}"
+```
+
+## Step 3 — Create project-context.yaml
+
+Create `.agent/project-context.yaml` using `templates/project-context.yaml` as the source template.
+
+Copy the template and instruct: "Open `.agent/project-context.yaml` and fill in all `{{PLACEHOLDER}}` values. The `paths` section is pre-configured with sensible defaults — adjust if your project uses different directory names."
+
+## Step 4 — Create business-dictionary.md
+
+Create `specs/domain-knowledge/business-dictionary.md` if it does not exist:
+
+```markdown
+# Business Dictionary — {{PROJECT_NAME}}
+
+> Canonical terminology for this project. All PRDs, BDD specs, and code must follow these terms.
+> Managed by: PO / SA team.
+
+## Canonical Terms
+
+| Canonical Term | Description / Context |
+|----------------|----------------------|
+| {Term}         | {Short description, usage scope} |
+
+## Banned Terms
+
+| ❌ Do NOT use | ✅ Use instead    | Reason |
+|---------------|-------------------|--------|
+| {banned}      | {canonical}       | {why}  |
+
+## Status / Enum Registry
+
+| Entity | Field   | Allowed Values     |
+|--------|---------|--------------------|
+| {Entity} | status | {value1, value2} |
+```
+
+Instruct: "Open `specs/domain-knowledge/business-dictionary.md` and add your project terminology. This file will be read by all commands to enforce consistent naming."
+
+## Step 5 — Create core-entities.md
+
+Create `specs/domain-knowledge/core-entities.md` if it does not exist:
+
+```markdown
+# Core Entities — {{PROJECT_NAME}}
+
+> Machine-readable entity glossary for AI-assisted development.
+> Loaded by all commands so AI knows your domain model without reading source code.
+> Managed by: Tech Lead / Architect.
+>
+> HOW TO USE:
+> - Add one `## Entity: {Name}` section per domain entity (aggregate root, value object, etc.)
+> - Keep field descriptions concise — this is a REFERENCE, not API docs
+> - Update this file whenever you add/rename fields or change business invariants
+
+---
+
+## Entity: {EntityName}
+
+**Purpose**: {1-2 sentences — what this entity represents and why it exists in the domain}
+**Domain**: {domain}
+**Storage**: {e.g., `orders` table in PostgreSQL | `orders` collection in MongoDB}
+**Owner service**: {service/module that owns this entity}
+
+| Field        | Type    | Nullable | Description                         |
+|--------------|---------|----------|-------------------------------------|
+| id           | UUID    | No       | Primary key                         |
+| {field_name} | {type}  | Yes/No   | {short description}                 |
+| status       | Enum    | No       | See Status Registry in business-dictionary.md |
+
+**Business invariants:**
+- {Rule 1: e.g., "status can only transition: PENDING → ACTIVE → CLOSED"}
+- {Rule 2: e.g., "total must equal sum of line items"}
+
+**Relationships:**
+- `{EntityA}` 1:N `{EntityB}` — {one sentence description}
+- `{EntityA}` N:N `{EntityC}` via `{junction_table}` — {description}
+
+---
+
+## Entity: {AnotherEntity}
+
+*(Add more entities following the same pattern above)*
+```
+
+Instruct: "Open `specs/domain-knowledge/core-entities.md` and define your key domain entities. Start with aggregate roots. This file is loaded by every AI command — good definitions here save significant back-and-forth during code generation."
+
+## Step 6 — Verify
+
+- [ ] `specs/` exists
+- [ ] `specs/domain-knowledge/` exists
+- [ ] `.trace/` exists
+- [ ] `.agent/project-context.yaml` exists
+- [ ] `CLAUDE.md` exists
+- [ ] `specs/domain-knowledge/business-dictionary.md` exists
+- [ ] `specs/domain-knowledge/core-entities.md` exists
+
+## Output
+
+```
+/setup-ai-first Complete ✅
+Next:
+  1. Fill CLAUDE.md (replace {{PLACEHOLDER}} values)
+  2. Fill .agent/project-context.yaml
+  3. Fill specs/domain-knowledge/business-dictionary.md  ← terminology rules
+  4. Fill specs/domain-knowledge/core-entities.md        ← entity glossary for code gen
+  5. git add and commit those 4 files
+  6. /define-product to start your first feature
+```

package/commands/setup-ai-first.tmpl

@@ -0,0 +1,197 @@
+# /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.
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, there is no input file. Skip Step 1 file discovery. In Step 2, skip project-context.yaml loading (it does not exist yet). Ask: "Which project are you setting up? Give me the root path of the project."*
+
+---
+
+## Precondition Check
+
+Check if already set up:
+- If `.claude/commands/` exists with `.md` files → report "Already set up."
+- If `specs/` exists → offer to re-initialize or skip
+
+## Step 1 — Create Directory Structure
+
+Create these directories (skip if they exist):
+
+```
+{project-root}/
+├── specs/
+│   ├── product-definition/
+│   ├── prd/
+│   ├── bdd/
+│   └── domain-knowledge/     ← business dictionary & domain context
+├── tech-docs/
+├── .trace/
+└── .agent/
+    └── review/
+```
+
+## Step 2 — Create CLAUDE.md
+
+Check if `CLAUDE.md` exists:
+- Yes → ask "Merge template or skip?"
+- No → create from the template below
+
+After creating, instruct: "Open CLAUDE.md and fill in the `{{PLACEHOLDER}}` values with your project information."
+
+### CLAUDE.md Template
+
+```
+# §1. Project Overview
+Project: {{PROJECT_NAME}}
+Language: {{LANGUAGE}}
+Framework: {{FRAMEWORK}}
+Build: {{BUILD_COMMAND}}
+Test: {{TEST_COMMAND}}
+Domains: {{COMMA_SEPARATED_DOMAINS}}
+
+# §2. Architecture
+layers: "{{LAYER_STACK}}"
+# Example: Controller → Facade → Service → Repository
+rules:
+  - "Controllers must not contain business logic"
+  - "Services own transaction boundaries"
+
+# §3. Coding Standards
+naming:
+  classes: "{{NAMING_CONVENTION}}"
+  methods: "{{METHOD_CONVENTION}}"
+response_wrapper: "{{WRAPPER}}"
+forbidden:
+  - "Magic numbers"
+  - "Debug print statements"
+
+# §4. Traceability
+# Every controller method must be tagged:
+# @trace.implements={UC-ID}-{SC-ID}
+# @trace.source=specs/bdd/{domain}/{UC-ID}.feature
+# Tests must be tagged:
+# @trace.verifies={UC-ID}
+
+# §5. Error Handling
+not_found: "{{NOT_FOUND_EXCEPTION}}"
+http_codes: { get: 200, create: 201, not_found: 404, validation: 400 }
+
+# §6. Build & Test
+build_command: "{{BUILD_COMMAND}}"
+test_command: "{{TEST_COMMAND}}"
+run_command: "{{RUN_COMMAND}}"
+
+# §7. Git Conventions
+branch_feature: "feature/{{TICKET_PREFIX}}-{N}-{slug}"
+commit_feature: "feat({{TICKET_PREFIX}}-{N}): {description}"
+```
+
+## Step 3 — Create project-context.yaml
+
+Create `.agent/project-context.yaml` using `templates/project-context.yaml` as the source template.
+
+Copy the template and instruct: "Open `.agent/project-context.yaml` and fill in all `{{PLACEHOLDER}}` values. The `paths` section is pre-configured with sensible defaults — adjust if your project uses different directory names."
+
+## Step 4 — Create business-dictionary.md
+
+Create `specs/domain-knowledge/business-dictionary.md` if it does not exist:
+
+```markdown
+# Business Dictionary — {{PROJECT_NAME}}
+
+> Canonical terminology for this project. All PRDs, BDD specs, and code must follow these terms.
+> Managed by: PO / SA team.
+
+## Canonical Terms
+
+| Canonical Term | Description / Context |
+|----------------|----------------------|
+| {Term}         | {Short description, usage scope} |
+
+## Banned Terms
+
+| ❌ Do NOT use | ✅ Use instead    | Reason |
+|---------------|-------------------|--------|
+| {banned}      | {canonical}       | {why}  |
+
+## Status / Enum Registry
+
+| Entity | Field   | Allowed Values     |
+|--------|---------|--------------------|
+| {Entity} | status | {value1, value2} |
+```
+
+Instruct: "Open `specs/domain-knowledge/business-dictionary.md` and add your project terminology. This file will be read by all commands to enforce consistent naming."
+
+## Step 5 — Create core-entities.md
+
+Create `specs/domain-knowledge/core-entities.md` if it does not exist:
+
+```markdown
+# Core Entities — {{PROJECT_NAME}}
+
+> Machine-readable entity glossary for AI-assisted development.
+> Loaded by all commands so AI knows your domain model without reading source code.
+> Managed by: Tech Lead / Architect.
+>
+> HOW TO USE:
+> - Add one `## Entity: {Name}` section per domain entity (aggregate root, value object, etc.)
+> - Keep field descriptions concise — this is a REFERENCE, not API docs
+> - Update this file whenever you add/rename fields or change business invariants
+
+---
+
+## Entity: {EntityName}
+
+**Purpose**: {1-2 sentences — what this entity represents and why it exists in the domain}
+**Domain**: {domain}
+**Storage**: {e.g., `orders` table in PostgreSQL | `orders` collection in MongoDB}
+**Owner service**: {service/module that owns this entity}
+
+| Field        | Type    | Nullable | Description                         |
+|--------------|---------|----------|-------------------------------------|
+| id           | UUID    | No       | Primary key                         |
+| {field_name} | {type}  | Yes/No   | {short description}                 |
+| status       | Enum    | No       | See Status Registry in business-dictionary.md |
+
+**Business invariants:**
+- {Rule 1: e.g., "status can only transition: PENDING → ACTIVE → CLOSED"}
+- {Rule 2: e.g., "total must equal sum of line items"}
+
+**Relationships:**
+- `{EntityA}` 1:N `{EntityB}` — {one sentence description}
+- `{EntityA}` N:N `{EntityC}` via `{junction_table}` — {description}
+
+---
+
+## Entity: {AnotherEntity}
+
+*(Add more entities following the same pattern above)*
+```
+
+Instruct: "Open `specs/domain-knowledge/core-entities.md` and define your key domain entities. Start with aggregate roots. This file is loaded by every AI command — good definitions here save significant back-and-forth during code generation."
+
+## Step 6 — Verify
+
+- [ ] `specs/` exists
+- [ ] `specs/domain-knowledge/` exists
+- [ ] `.trace/` exists
+- [ ] `.agent/project-context.yaml` exists
+- [ ] `CLAUDE.md` exists
+- [ ] `specs/domain-knowledge/business-dictionary.md` exists
+- [ ] `specs/domain-knowledge/core-entities.md` exists
+
+## Output
+
+```
+/setup-ai-first Complete ✅
+Next:
+  1. Fill CLAUDE.md (replace {{PLACEHOLDER}} values)
+  2. Fill .agent/project-context.yaml
+  3. Fill specs/domain-knowledge/business-dictionary.md  ← terminology rules
+  4. Fill specs/domain-knowledge/core-entities.md        ← entity glossary for code gen
+  5. git add and commit those 4 files
+  6. /define-product to start your first feature
+```