@edupia-tutor/spec-driven-docs 0.14.0

package/steps/gate.md

@@ -0,0 +1,87 @@
+# 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 (or latest Opus model)
+  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 **bare UC-ID / ticket ID / partial name** (no path) → resolve it to a file by globbing the feature-package layout. The `{prd-slug}` is **not known yet**, so use a `*` wildcard for that segment, and a recursive `**` under `bdd/` so the platform subfolders (`bdd/web/`, `bdd/app/`, `bdd/system/`) are all covered:
+   - **BDD commands** (target is a `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — or `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` if the domain is also unknown. If a platform/scope is implied by the command (e.g. a system tech-doc needs the `system/` BDD), prefer the match under that platform subfolder.
+   - **PRD commands** (target is `prd.md`): `{specs_dir}/{domain}/*/prd.md` (match the feature folder whose id corresponds), else `{specs_dir}/*/*/prd.md`.
+   - **tech-docs commands**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
+   - **design-spec commands**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
+
+   Once a file matches: set it as the target **and** record `domain` + `prd_slug` from its path (per the extraction rule in `context-loader.md` Step 1 — `prd_slug` = first segment after `{specs_dir}/{domain}/`). Every path the command later reads or writes (sibling BDD/tech-docs/design-spec/trace) uses **that resolved `prd_slug`**, so all artifacts stay in one feature package. If several files match (e.g. multiple platforms), pick per the command's platform/scope or list them and ask.
+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/steps/report-footer.md

@@ -0,0 +1,100 @@
+# 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)`.
+
+## Pipeline Position
+
+Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
+so the user always sees where this command sits in the end-to-end flow:
+
+```
+Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+```
+
+Find the current command in this phase legend and mark **its** phase in the map above:
+
+| Phase | Commands |
+|-------|----------|
+| Discovery | `/define-product` |
+| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| Design Spec | `/generate-design-spec` |
+| BDD | `/generate-bdd` · `/review-context` (BDD) |
+| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
+| Code | `/generate-code` · `/review-code` |
+| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
+| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
+| Trace Audit | `/validate-traces` |
+
+For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
+`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
+
+**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
+**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /setup-ai-first         | `/define-product` to start your first feature |
+| /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)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
+| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
+| /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          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+| /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
+| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
+| /learn                  | Continue working — lesson applies on next command |
+| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
+
+Format the footer as:
+```
+---
+Status   : {badge}
+{Output Artifacts block}
+Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {suggested command with example arguments}
+```
+*(Omit the `Pipeline` line for cross-cutting commands listed above.)*

package/steps/review-fanout.md

@@ -0,0 +1,138 @@
+# Exhaustive Review Fan-Out + Completeness Convergence
+
+**Why this exists:** A single-pass review never lists every issue at once — the model
+stops at "enough" findings, so each later review round surfaces *new* problems
+(whack-a-mole). This procedure forces the review to **converge in one command run**:
+fan out across review dimensions in parallel, then loop a completeness critic until a
+round produces nothing new, *before* writing the findings file.
+
+The calling command supplies two things:
+- **DIMENSIONS** — the list of review dimensions to fan out over
+  (`/refine-prd` → the 4 lenses; `/review-context` → the P-checks or B-checks).
+- **FINDINGS SCHEMA** — the YAML shape each finding must follow (defined in the command).
+
+> **Sub-agent mode bypass:** If Gate Step 0 set `_agent_mode: true`, this whole
+> procedure is **skipped** — the orchestrator is already running one dimension/UC per
+> sub-agent. Run the command's checks directly on the scoped section and return findings.
+
+---
+
+## Phase 1 — Parallel dimension scan
+
+**How many sub-agents:** the agent *count* is not the completeness lever — breadth is
+fixed by the DIMENSION taxonomy (adding agents to the same dimension just re-finds the
+same issues), and *depth* is owned by the Phase 2 critic loop. Pick the **fan-out
+granularity** by target size, reusing the `steps/spawn-agent.md` thresholds:
+
+| Target size | Granularity | Agent count |
+|-------------|-------------|-------------|
+| ≤ 3 UCs **and** ≤ 300 lines | one agent per DIMENSION over the whole file | = number of dimensions |
+| > 3 UCs **or** > 300 lines | one agent per **DIMENSION × UC-scope** (UCs + a PRD-global scope), batched to fit the agent cap | `dimensions × (UCs + 1)`, capped (see below) |
+
+The larger granularity keeps each sub-agent's context small and its scan exhaustive on a
+single UC — which is what prevents misses on big PRDs.
+
+> **Global (non-UC) sections — required in `DIMENSION × UC` mode.** Per-UC agents only
+> see one UC each, so PRD-wide sections that belong to no UC (scope, success metrics,
+> problem statement, terminology, glossary, changelog) would go unscanned. Whenever you
+> fan out per UC, also include a **"PRD-global"** scope (the non-UC sections, findings get
+> `uc_id: ""`) alongside the UC list. So the natural agent count is `dimensions × (UCs + 1)`.
+> (Not needed in the whole-file mode — there each agent already sees the global sections.)
+
+### Agent cap — batch UCs when the fan-out gets too wide
+
+`dimensions × (UCs + 1)` can explode on large PRDs (e.g. 6 checks × (8 UCs + 1) = 54
+agents). Cap the wave at **`AGENT_CAP = 12`** agents and batch UC scopes to fit:
+
+1. Build the scope list = `[UC1, UC2, …, UCn, PRD-global]` (length `UCs + 1`).
+2. Compute scopes-per-agent-bucket: `groups = max(1, floor(AGENT_CAP / dimensions))`.
+   - If `groups ≥ UCs + 1` → no batching needed, run one agent per `DIMENSION × scope`.
+   - Else split the scope list into `groups` contiguous buckets of roughly equal size
+     (keep `PRD-global` in its own bucket if it fits; otherwise append it to the last
+     bucket). Each agent then handles **one DIMENSION over one bucket of UCs**.
+3. Resulting wave size = `dimensions × groups ≤ AGENT_CAP`.
+
+A batched agent reviews several UCs at once — still scoped far tighter than the whole
+file, so coverage stays high. `AGENT_CAP` is the only knob; raise it if the host allows
+more concurrency, lower it to save tokens. Whole-file mode (≤ 3 UCs) never hits the cap.
+
+Spawn the chosen sub-agents using the Agent tool (send them in a single message so they
+run concurrently). Each sub-agent gets a **fresh context window** and scans its scope
+through its **one** dimension only — deeper coverage than one session juggling every
+dimension at once (avoids lost-in-the-middle).
+
+Sub-agent prompt template (fill the braces):
+
+```
+You are a {DIMENSION_NAME} reviewer. Read the full target file at {target_file}.
+Scope: review ONLY through the {DIMENSION_NAME} lens/check — {DIMENSION_DESCRIPTION}.
+Be exhaustive: scan every section, every UC, every AC/BR/scenario. Do not stop early.
+Project context (terminology, entities, architecture):
+{slim_context — banned terms, canonical entities, layer order, domains}
+
+Return a JSON array of findings, each:
+{ "dimension": "{DIMENSION_NAME}", "severity": "critical|major|minor",
+  "section": "...", "uc_id": "...", "quote": "<verbatim ≤120 chars>",
+  "finding": "...", "suggestion": "...", "auto_fixable": true|false }
+Return [] if this dimension is clean. Return ONLY the JSON array.
+```
+
+Collect every sub-agent's array into one consolidated list `ALL_FINDINGS`.
+
+---
+
+## Phase 2 — Completeness-critic convergence loop
+
+This is the anti-whack-a-mole step. Repeat until **two consecutive rounds add zero new
+findings**, or a hard cap of **3 rounds**, whichever comes first:
+
+1. Spawn one **completeness-critic** sub-agent with the Agent tool. Give it:
+   - the full target file (`{target_file}`),
+   - the current `ALL_FINDINGS` list (so it knows what is already captured),
+   - the same slim context.
+   Prompt it:
+   ```
+   Here is a document and a list of issues already found. Read the WHOLE document.
+   List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
+   contradictions, missing edge/negative paths, coverage holes, terminology drift,
+   structural omissions, and any issue that a fix to an existing finding would expose.
+   Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
+   nothing new.
+   ```
+2. Append any genuinely new findings (not already in `ALL_FINDINGS`) to the list.
+3. If this round returned 0 new → increment the dry-round counter; else reset it to 0.
+4. Stop when dry-round counter reaches 2, or after 3 rounds total.
+
+Record `convergence_rounds` (how many critic rounds ran) for the report.
+
+---
+
+## Phase 3 — Dedup, resolve conflicts, merge
+
+Sub-agents run **blind to each other** (independence = diverse coverage). They never
+talk or reconcile among themselves — all duplicate/conflict resolution happens **here in
+the orchestrator**, where the full set is visible.
+
+1. **Deduplicate** `ALL_FINDINGS`: two findings are duplicates if they target the same
+   `section` + `uc_id` and describe the same underlying issue. Keep the one with the
+   richer `suggestion`; if they differ on severity, keep the **higher** severity.
+2. **Resolve conflicts** — group remaining findings by `section` + `uc_id` and check for
+   contradictions (two findings whose `suggestion`s cannot both be applied, or that
+   propose opposite fixes for the same spot):
+   - If the two suggestions can be **merged** into one coherent fix → merge them into a
+     single finding.
+   - If they are **mutually exclusive** → emit **one** finding that states both options
+     and set `auto_fixable: false` with `status: "needs_discussion"` (PRD) /
+     `status: "pending"` (review) so a human picks — never silently drop one side.
+   - If a finding is **invalidated** by another (e.g. a structural finding says a section
+     is missing, but another quotes content from it) → drop the invalid one.
+3. **Sort** by severity (critical → major → minor), then by `section` order in the file.
+4. **Assign stable IDs** `F001, F002, …` in that sorted order.
+5. Map each finding's `dimension` into the command's schema field
+   (`lens` for `/refine-prd`; `check_id` for `/review-context`).
+6. Write the **single** findings file in the FINDINGS SCHEMA the command defines.
+
+In the command's final report, add one line:
+```
+Convergence: {convergence_rounds} critic round(s) — findings file is complete; re-running should surface 0 new issues.
+```

package/steps/spawn-agent.md

@@ -0,0 +1,124 @@
+# 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}",
+    "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",
+  "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>" }
+}
+```
+
+> **Command scope**: Only `/generate-bdd` initiates orchestration mode. `/generate-code` and `/dev-gen-test` can run as sub-agents (they respect `_agent_mode: true` from Gate Step 0), but they do not spawn further sub-agents — their scope is already a single UC.
+
+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/steps/trace-mirror.md

@@ -0,0 +1,26 @@
+# Refresh Living Docs panel mirror *(local, umbrella mode)*
+
+*Skip entirely in single-service mode (no `services` and no `setup.spec_source`) — there
+the repo's own `.trace/` IS the panel location, so nothing to mirror.*
+
+After updating the authoritative TSV(s) at `{paths.trace_dir}`:
+
+**When `setup.spec_source` is set (consolidated trace — the common case):**
+`{paths.trace_dir}` resolves to `{spec_source}/.trace` — the single authoritative location.
+This command runs from `service_root`, so the write is **cross-repo into the spec submodule**;
+commit/push the spec submodule for the trace update (same as `feedback/`).
+1. Resolve `panel_mirror = ./.trace` at the **current workspace root**.
+2. If `panel_mirror` resolves to a different path than `{paths.trace_dir}`, copy each
+   just-updated `{UC-ID}.tsv` → `{panel_mirror}/{UC-ID}.tsv` (create the dir; overwrite).
+   No per-service namespacing — there is one trace set; the owning service is carried in each
+   row's `@trace.service`.
+
+**Legacy (no `spec_source` — per-service trace):**
+Copy each just-updated `{UC-ID}.tsv` → `{panel_mirror}/{service-name}/{UC-ID}.tsv`
+(namespaced by `active_service`).
+
+This keeps the open workspace's Living Docs panel current **between syncs** — it is a
+**local convenience mirror only**. The merged `trace-report.json` (canonical, in
+`{spec_source}/.living-docs/`) is rebuilt by `/sync` or `/validate-traces`. For orchestrated
+commands, do this once in the orchestrator after all sub-agents return — not inside each
+sub-agent.

package/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