@anhth2/spec-driven-dev-plugin 0.7.0 → 0.9.0

package/ARCHITECTURE.md

@@ -196,7 +196,7 @@ spec-driven-dev/
 │   ├── build.js             ← assembles *.tmpl → *.md
 │   └── index.js             ← npm installer + hook installer
 ├── commands/
-│   └── *.tmpl               ← slash commands (14 commands)
+│   └── *.tmpl               ← slash commands (23 commands)
 ├── hooks/
 │   ├── data-guard.js        ← PreToolUse sensitive file protection
 │   └── settings.json        ← hook registration template
@@ -209,10 +209,12 @@ spec-driven-dev/
 │   ├── data-protection.md   ← what AI must NEVER read/write
 │   └── workflow.md          ← general AI behavior rules
 ├── skills/
-│   └── {name}/SKILL.tmpl    ← Claude plugin skills (7 skills)
+│   └── {name}/SKILL.tmpl    ← Claude plugin skills (8 skills)
 ├── steps/
 │   ├── gate.md              ← shared: file resolve + checkpoint
 │   ├── context-loader.md    ← shared: load all project context
+│   ├── spawn-agent.md       ← shared: sub-agent orchestration
+│   ├── capture-lesson.md    ← shared: record a guardrail (/learn etc.)
 │   └── report-footer.md     ← shared: standard output format
 └── templates/
     ├── project-context.yaml ← consumer project config template
@@ -220,6 +222,8 @@ spec-driven-dev/
     └── platform-guide.template.md
 ```
 
+> Build output (gitignored): `commands/*.md`, `skills/**/SKILL.md`, and `core/` (the distributable copied into a consumer's `.agent/` by `--init`). Consumer-side tester artifacts live in the shared spec repo under `feedback/bug-reports/` and `feedback/bdd-proposals/`.
+
 ---
 
 ## Maintenance Guide

package/bin/index.js

@@ -29,6 +29,10 @@ const serviceList = servicesRaw
     }).filter(s => s.name)
   : [];
 
+const isUmbrella    = args.includes('--umbrella');
+const specSourceIdx = args.indexOf('--spec-source');
+const specSource    = specSourceIdx !== -1 ? args[specSourceIdx + 1] : null;
+
 const AVAILABLE_MODULES = [
   'java-spring', 'angular', 'react', 'nextjs',
   'dotnet', 'golang', 'php-laravel', 'context-engineering',
@@ -59,6 +63,9 @@ if (showHelp) {
   console.log('Install modes:');
   console.log('  --init                    Install framework to .agent/ + create shortcuts in .claude/commands/');
   console.log('                            Recommended for new projects. Run upgrade.sh to upgrade later.');
+  console.log('  --init --umbrella         Umbrella repo setup: installs framework at umbrella level only.');
+  console.log('                            Generates project-context.yaml with services routing.');
+  console.log('                            Does NOT install into service submodule directories.');
   console.log('  --project                 Install full commands to ./.claude/commands/ (project-scoped, legacy)');
   console.log('  (no flag)                 Install full commands to ~/.claude/commands/ (global, legacy)');
   console.log('');
@@ -67,6 +74,9 @@ if (showHelp) {
   console.log('  --services <list>         Monorepo setup: install into each service subfolder in one command.');
   console.log('                            Format: name:module,name:module,...');
   console.log('                            Example: backend:java-spring,web-admin:react,app-mobile:flutter');
+  console.log('  --umbrella                Umbrella mode (use with --init). See above.');
+  console.log('  --spec-source <path>      Path to PO spec submodule (e.g. free-trial-specs).');
+  console.log('                            Auto-configures prd_dir, design_spec_dir, domain_knowledge_dir.');
   console.log('  --hooks                   Install data-guard hook to .claude/hooks/ + update .claude/settings.json');
   console.log('');
   console.log('Available modules:');
@@ -77,6 +87,9 @@ if (showHelp) {
   console.log('  npx @anhth2/spec-driven-dev-plugin --init --module java-spring    # with stack module');
   console.log('  npx @anhth2/spec-driven-dev-plugin --init \\');
   console.log('    --services backend:java-spring,web-admin:react,app-mobile:flutter  # monorepo setup');
+  console.log('  npx @anhth2/spec-driven-dev-plugin --init --umbrella \\');
+  console.log('    --spec-source free-trial-specs \\');
+  console.log('    --services mass-product-web:nextjs   # umbrella with one FE service');
   console.log('  npx @anhth2/spec-driven-dev-plugin --project --hooks              # legacy project install');
   process.exit(0);
 }
@@ -178,6 +191,83 @@ if (isInit) {
     installDataGuardHook();
   }
 
+  // 5-alt. Umbrella mode: generate umbrella project-context.yaml (do NOT install into submodules)
+  if (isUmbrella) {
+    const rootCtxPath = path.join(agentDir, 'project-context.yaml');
+    if (!fs.existsSync(rootCtxPath)) {
+      const specSrc = specSource || 'TODO-spec-submodule';
+
+      let servicesBlock = '';
+      if (serviceList.length > 0) {
+        servicesBlock = serviceList.map(s => [
+          `  ${s.name}:`,
+          `    path: "${s.name}"`,
+          `    module: "${s.module || 'TODO'}"`,
+          `    specs_dir: "${s.name}/specs/bdd"`,
+          `    tech_docs_dir: "${s.name}/specs/tech-docs"`,
+        ].join('\n')).join('\n');
+      } else {
+        servicesBlock = [
+          `  # {domain}:`,
+          `  #   path: "{service-submodule-dir}"`,
+          `  #   module: "{stack-module}"`,
+          `  #   specs_dir: "{service-dir}/specs/bdd"`,
+          `  #   tech_docs_dir: "{service-dir}/specs/tech-docs"`,
+        ].join('\n');
+      }
+
+      const domainsBlock = serviceList.length > 0
+        ? serviceList.map(s => `  - "${s.name}"`).join('\n')
+        : `  - "TODO"`;
+
+      const umbrellaYaml = [
+        `project:`,
+        `  name: "${path.basename(projectRoot)}"`,
+        `  description: ""`,
+        ``,
+        `setup:`,
+        `  mode: umbrella`,
+        `  spec_source: "${specSrc}"`,
+        ``,
+        `# Paths auto-derived from spec_source by context-loader.`,
+        `# Override here only if your structure differs.`,
+        `paths:`,
+        `  prd_dir:              "${specSrc}/specs/prd"`,
+        `  design_spec_dir:      "${specSrc}/specs/design-spec"`,
+        `  domain_knowledge_dir: "${specSrc}/specs/domain-knowledge"`,
+        `  business_dictionary:  "${specSrc}/specs/domain-knowledge/business-dictionary.md"`,
+        `  core_entities:        "${specSrc}/specs/domain-knowledge/core-entities.md"`,
+        `  product_definitions_dir: "${specSrc}/specs/product-definition"`,
+        `  refinement_dir:       ".agent/review"`,
+        `  trace_dir:            ".trace"`,
+        ``,
+        `# Domain → service submodule routing.`,
+        `# Each key must match @trace.domain in your PRD files.`,
+        `services:`,
+        servicesBlock,
+        ``,
+        `tech_stack:`,
+        `  language: multi-service`,
+        `  module: ""`,
+        ``,
+        `conventions:`,
+        `  ticket_prefix: FEAT`,
+        ``,
+        `domains:`,
+        domainsBlock,
+        ``,
+      ].join('\n');
+
+      fs.writeFileSync(rootCtxPath, umbrellaYaml, 'utf8');
+      console.log('');
+      console.log('  ✅ .agent/project-context.yaml (umbrella mode, generated)');
+      if (specSource) console.log(`     spec_source : ${specSrc}`);
+      if (serviceList.length > 0) console.log(`     services    : ${serviceList.map(s => s.name).join(', ')}`);
+    } else {
+      console.log('  ℹ️  .agent/project-context.yaml (already exists — skipped)');
+    }
+  }
+
   // 5. Monorepo: install into each service subfolder
   if (serviceList.length > 0) {
     console.log('');
@@ -307,6 +397,21 @@ if (isInit) {
   }
   console.log(`✅ Framework v${frameworkVersion} installed!`);
   console.log('');
+  if (isUmbrella) {
+    console.log('Umbrella workspace ready:');
+    console.log('  Open Claude Code at project root (umbrella)');
+    console.log('  Agent reads specs from: ' + (specSource || 'spec_source in project-context.yaml'));
+    if (serviceList.length > 0) {
+      console.log('  Service submodules configured:');
+      serviceList.forEach(s => console.log(`    ${s.name} (${s.module || 'no module'})`));
+    }
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. Review .agent/project-context.yaml — update service paths + domain names');
+    console.log('  2. Run /setup-ai-first in Claude Code');
+    console.log('  3. Commit .agent/ to git');
+    console.log('');
+  } else
   if (serviceList.length > 0) {
     console.log('Monorepo workspaces ready:');
     console.log('  PO/BA    → open Claude Code at project root');

package/commands/debug.md

@@ -134,6 +134,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -145,11 +146,75 @@ If `paths` section is absent, use these defaults:
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
 - `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
+- `design_spec_dir` = `specs/design-spec`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
 
 ---
 
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**2. Route to service** — if active domain matches a key in `services`:
+- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- Store `active_service` = `services.{domain}.path`
+- Store `active_service_module` = `services.{domain}.module`
+- If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
+- Override `paths.prd_dir` → `{spec_source}/specs/prd`
+- Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
+- Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
+- Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
+- Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
+- Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
+
+> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+
+---
+
+## Step 1.6 — [SERVICE CONVENTIONS] Load service-specific conventions (umbrella mode)
+
+*Skip this step entirely if `active_service` is `"unresolved"` or context is single-service mode.*
+
+When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-service/`):
+
+**1. Locate service config** — try in priority order:
+- `{active_service}/.agent/project-context.yaml`
+- `{active_service}/project-context.yaml`
+
+**2. If found, override with service-specific values:**
+
+| Variable | Source |
+|----------|--------|
+| `conventions.test_command` | service's `conventions.test_command` |
+| `conventions.build_command` | service's `conventions.build_command` |
+| `paths.trace_dir` | `{active_service}/{service paths.trace_dir}` — default: `{active_service}/.trace` |
+| `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
+
+**3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
+- Shell commands (`/run-tests`, `/generate-tests`) run **from within** `service_root`
+- File write operations (test files, trace TSVs) use paths **relative to** `service_root`
+
+**4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -240,6 +305,25 @@ These two variables (`active_module`, `platform_type`) are the canonical source
 
 ---
 
+## Step 6.7 — [GUARDRAILS] Load Project Lessons (conditional)
+
+*Accumulated mistakes the AI must not repeat in this project. These are added over time via `/learn`
+or accepted during `/review-code`, `/fix-bug`, `/debug`.*
+
+Resolve the lessons file path:
+- Use `paths.lessons_file` if set (may be service-overridden in umbrella mode, Step 1.6)
+- Else default `specs/domain-knowledge/lessons-learned.md`
+- In umbrella/service mode (when `service_root` is set), if `paths.lessons_file` is unset, default to `{service_root}/.agent/project-lessons.md`
+
+If the file exists, read it and store ALL lessons as **ACTIVE GUARDRAILS** for the session:
+- Treat each lesson's **Rule** as a hard constraint — same priority as CLAUDE.md coding standards (Step 3).
+- Before generating or modifying any artifact (PRD, BDD, tech-doc, code, test), check the output against every lesson whose `category` matches the current command AND whose `scope` matches the target (domain / file).
+- If a generated output would violate a lesson → correct it **before** presenting, and note which lesson (`L-NNN`) was applied.
+
+If the file does not exist → skip silently (no lessons captured yet).
+
+---
+
 ## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
 
 After loading all context, synthesize and output a compact summary block.
@@ -255,6 +339,9 @@ Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Ser
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Lessons   : {loaded — N guardrails | none yet}
+Service   : {active_service} ({active_service_module}) | single-service
+Svc Root  : {service_root} — conventions + trace_dir loaded from service config | —
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -512,7 +599,8 @@ Suggest the logical next command based on workflow phase:
 | /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 |
+| /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 |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
@@ -526,6 +614,11 @@ Suggest the logical next command based on workflow phase:
 | /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {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:
 ```
@@ -558,3 +651,98 @@ See CLAUDE.md §{section}
 - To fully fix → /fix-bug {TICKET_ID}
 - Just needed analysis → done
 ```
+
+---
+
+## Offer to Record a Lesson (optional)
+
+If the root cause is a **mistake the AI made when generating code and could repeat**
+(not an environment/config issue or external cause), ask:
+
+```
+This looks like a repeatable AI mistake. Record it as a project lesson? (Y/N)
+```
+
+If `Y` → run the capture procedure below with `source=/debug`, an appropriate `category`
+(usually `code-gen`), and `scope` = the affected domain or file glob.
+
+# Capture Lesson — Record a Recurring Mistake as a Guardrail
+
+Reusable procedure to persist a "lesson" so the AI does not repeat a mistake in this project.
+Used by `/learn` (manual) and offered by `/review-code`, `/fix-bug`, `/debug` (auto).
+
+> **Project memory, not model training.** A lesson is plain text injected into context at the
+> start of every command (context-loader Step 6.7). Functionally this stops the repeat — the AI
+> sees the guardrail before it generates. No model weights change.
+
+## L1 — Resolve the lessons file
+
+Resolve `lessons_path` in this order:
+1. `paths.lessons_file` from loaded context (may be service-overridden in umbrella mode, Step 1.6)
+2. Default `specs/domain-knowledge/lessons-learned.md` (single-service)
+3. In umbrella/service mode (when `service_root` is set) default `{service_root}/.agent/project-lessons.md`
+
+## L2 — Build the lesson
+
+Gather these fields — from `$ARGUMENTS` (for `/learn`) or from the calling command's findings
+(for `/review-code`, `/fix-bug`, `/debug`):
+
+| Field | Meaning |
+|-------|---------|
+| `category` | one of: `code-gen` \| `bdd` \| `tech-docs` \| `tests` \| `prd` \| `general` |
+| `title` | short phrase naming the mistake |
+| `mistake` | concretely, what the AI did wrong |
+| `rule` | imperative correction — "Always …" / "Never …" — testable, not vague |
+| `scope` | where it applies: a domain, a file glob (e.g. `*Controller.*`), or `all` |
+| `source` | how captured: `/learn` \| `/review-code {UC-ID}` \| `/fix-bug {TICKET}` \| `/debug` |
+
+If `rule` is vague (e.g. "be careful"), rewrite it into a concrete, checkable instruction before saving.
+
+## L3 — De-duplicate
+
+Read existing lessons in `lessons_path`. If one already covers the same mistake:
+- **Refine** that entry (tighten the Rule, widen/narrow Scope, bump Date, append the new Source) — do NOT add a duplicate.
+
+Otherwise assign the next id `L-{NNN}` = (highest existing number + 1), zero-padded to 3 digits.
+
+## L4 — Write
+
+If `lessons_path` does not exist, create it with this header first:
+
+```markdown
+# Project Lessons — Learned Guardrails
+
+> Mistakes the AI must NOT repeat in this project. Loaded by context-loader at the start of
+> every command and treated as hard constraints (same priority as CLAUDE.md coding standards).
+> Add with /learn, or accept the prompt during /review-code, /fix-bug, /debug.
+> Commit this file so the whole team shares the guardrails.
+
+| Category | Applies to |
+|----------|-----------|
+| code-gen | /generate-code output |
+| bdd | /generate-bdd output |
+| tech-docs | /generate-tech-docs output |
+| tests | /generate-tests output |
+| prd | /generate-prd, /refine-prd output |
+| general | every command |
+
+---
+```
+
+Insert the new lesson directly under the `---` separator (**newest first**), in this exact shape:
+
+```markdown
+### L-{NNN} — [{category}] {title}
+- **Date**: {today YYYY-MM-DD}
+- **Scope**: {scope}
+- **Mistake**: {mistake}
+- **Rule**: {rule}
+- **Source**: {source}
+
+```
+
+## L5 — Confirm
+
+Print: `📝 Lesson {id} recorded → {lessons_path}  ([{category}] {title})`
+Then remind: `Commit {lessons_path} so the team shares this guardrail.`
+

package/commands/debug.tmpl

@@ -239,3 +239,19 @@ See CLAUDE.md §{section}
 - To fully fix → /fix-bug {TICKET_ID}
 - Just needed analysis → done
 ```
+
+---
+
+## Offer to Record a Lesson (optional)
+
+If the root cause is a **mistake the AI made when generating code and could repeat**
+(not an environment/config issue or external cause), ask:
+
+```
+This looks like a repeatable AI mistake. Record it as a project lesson? (Y/N)
+```
+
+If `Y` → run the capture procedure below with `source=/debug`, an appropriate `category`
+(usually `code-gen`), and `scope` = the affected domain or file glob.
+
+{{include:steps/capture-lesson.md}}

package/commands/define-product.md

@@ -131,6 +131,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -142,11 +143,75 @@ If `paths` section is absent, use these defaults:
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
 - `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
+- `design_spec_dir` = `specs/design-spec`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
 
 ---
 
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**2. Route to service** — if active domain matches a key in `services`:
+- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- Store `active_service` = `services.{domain}.path`
+- Store `active_service_module` = `services.{domain}.module`
+- If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
+- Override `paths.prd_dir` → `{spec_source}/specs/prd`
+- Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
+- Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
+- Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
+- Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
+- Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
+
+> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+
+---
+
+## Step 1.6 — [SERVICE CONVENTIONS] Load service-specific conventions (umbrella mode)
+
+*Skip this step entirely if `active_service` is `"unresolved"` or context is single-service mode.*
+
+When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-service/`):
+
+**1. Locate service config** — try in priority order:
+- `{active_service}/.agent/project-context.yaml`
+- `{active_service}/project-context.yaml`
+
+**2. If found, override with service-specific values:**
+
+| Variable | Source |
+|----------|--------|
+| `conventions.test_command` | service's `conventions.test_command` |
+| `conventions.build_command` | service's `conventions.build_command` |
+| `paths.trace_dir` | `{active_service}/{service paths.trace_dir}` — default: `{active_service}/.trace` |
+| `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
+
+**3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
+- Shell commands (`/run-tests`, `/generate-tests`) run **from within** `service_root`
+- File write operations (test files, trace TSVs) use paths **relative to** `service_root`
+
+**4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -237,6 +302,25 @@ These two variables (`active_module`, `platform_type`) are the canonical source
 
 ---
 
+## Step 6.7 — [GUARDRAILS] Load Project Lessons (conditional)
+
+*Accumulated mistakes the AI must not repeat in this project. These are added over time via `/learn`
+or accepted during `/review-code`, `/fix-bug`, `/debug`.*
+
+Resolve the lessons file path:
+- Use `paths.lessons_file` if set (may be service-overridden in umbrella mode, Step 1.6)
+- Else default `specs/domain-knowledge/lessons-learned.md`
+- In umbrella/service mode (when `service_root` is set), if `paths.lessons_file` is unset, default to `{service_root}/.agent/project-lessons.md`
+
+If the file exists, read it and store ALL lessons as **ACTIVE GUARDRAILS** for the session:
+- Treat each lesson's **Rule** as a hard constraint — same priority as CLAUDE.md coding standards (Step 3).
+- Before generating or modifying any artifact (PRD, BDD, tech-doc, code, test), check the output against every lesson whose `category` matches the current command AND whose `scope` matches the target (domain / file).
+- If a generated output would violate a lesson → correct it **before** presenting, and note which lesson (`L-NNN`) was applied.
+
+If the file does not exist → skip silently (no lessons captured yet).
+
+---
+
 ## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
 
 After loading all context, synthesize and output a compact summary block.
@@ -252,6 +336,9 @@ Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Ser
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Lessons   : {loaded — N guardrails | none yet}
+Service   : {active_service} ({active_service_module}) | single-service
+Svc Root  : {service_root} — conventions + trace_dir loaded from service config | —
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -446,7 +533,8 @@ Suggest the logical next command based on workflow phase:
 | /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 |
+| /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 |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
@@ -460,6 +548,11 @@ Suggest the logical next command based on workflow phase:
 | /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {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:
 ```