@tungvivas/angular-vibe-kit 0.2.0 → 0.3.0

package/bin/cli.js

@@ -13,15 +13,18 @@
  *     PROJECT-STATUS.md
  *     decisions/
  *   .claude/
- *     commands/                    ← 7 slash-commands
+ *     commands/                    ← 8 slash-commands
  *     angular-practices/<ver>.md   ← version-matched best-practice file
+ *     skills/                      ← skills Claude auto-applies (no command needed)
+ *     agents/                      ← Angular subagents (isolated context, run in parallel)
+ *     settings.json                ← allowlist (fewer prompts) + build-verify hook
  *     rules/
  *       project-rules.md           ← auto-loaded by Claude Code every session
  *
  * Generation (filling in actual content) happens later via /init in Claude Code.
  */
 
-import { existsSync, mkdirSync, readFileSync, copyFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, readdirSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve, relative } from "node:path";
 import { createRequire } from "node:module";
@@ -71,8 +74,11 @@ ${c.bold}Options${c.reset}
 ${c.bold}What gets created${c.reset}
   CLAUDE.md                       ← project root entry point
   docs/                           ← reference docs (fill in with /init)
-  .claude/commands/               ← 7 slash-commands
+  .claude/commands/               ← 8 slash-commands
   .claude/angular-practices/      ← version-matched best-practice file
+  .claude/skills/                 ← skills Claude auto-applies (no command needed)
+  .claude/agents/                 ← Angular subagents (isolated context, run in parallel)
+  .claude/settings.json           ← allowlist (fewer prompts) + build-verify hook
   .claude/rules/project-rules.md  ← auto-loaded every Claude Code session`);
 }
 
@@ -147,6 +153,76 @@ function copyDir(srcDir, destDir, cwd) {
   }
 }
 
+// Write generated content to a file, honoring --force / --dry-run like copyOne.
+function writeOne(content, dest, cwd) {
+  const rel = relative(cwd, dest);
+  if (existsSync(dest) && !flags.force) {
+    warn(`skip (exists): ${rel}`);
+    skipped++;
+    return;
+  }
+  if (flags.dryRun) {
+    log(`${c.dim}would create → ${rel}${c.reset}`);
+    copied++;
+    return;
+  }
+  ensureDir(dirname(dest));
+  writeFileSync(dest, content);
+  ok(rel);
+  copied++;
+}
+
+// Angular profile filename → human label for the skill description.
+// e.g. "v20plus.md" → "v20+", "v18-19.md" → "v18-19", "v17.md" → "v17"
+function profileLabel(practiceFile) {
+  return practiceFile.replace(/\.md$/, "").replace(/plus$/, "+");
+}
+
+// Detect the package manager from the target project's lockfile.
+function detectPackageManager(cwd) {
+  if (existsSync(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(cwd, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+
+// Resolve the build-verify command for the Stop hook. Prefers a project "typecheck"
+// script; otherwise falls back to a fast type-check (npx tsc --noEmit). Returns null
+// only if there is no package.json at all.
+function buildVerifyCommand(cwd) {
+  const pkgPath = join(cwd, "package.json");
+  if (!existsSync(pkgPath)) return null;
+  const pm = detectPackageManager(cwd);
+  try {
+    const raw = readFileSync(pkgPath, "utf8").replace(/^/, "");
+    const scripts = (JSON.parse(raw).scripts) || {};
+    if (scripts.typecheck) return pm === "npm" ? "npm run typecheck" : `${pm} typecheck`;
+  } catch { /* fall through to tsc */ }
+  // Fast type-check that works without an Angular-specific script.
+  // Swap for `ng build` / `${pm} run build` if you want full template checking.
+  return "npx tsc --noEmit";
+}
+
+// Build the .claude/settings.json object: a safe allowlist + (optionally) a Stop hook
+// that type-checks only when .ts/.html files changed since HEAD (skips question-only turns).
+function buildSettings(cwd) {
+  const settings = {
+    permissions: {
+      allow: [
+        "Bash(ng *)", "Bash(npm *)", "Bash(npx *)", "Bash(pnpm *)", "Bash(yarn *)",
+        "Bash(git status *)", "Bash(git diff *)", "Bash(git log *)", "Bash(git show *)",
+      ],
+    },
+  };
+  const buildCmd = buildVerifyCommand(cwd);
+  if (buildCmd) {
+    const hookCmd = `git diff --quiet HEAD -- '*.ts' '*.html' || ${buildCmd}`;
+    settings.hooks = {
+      Stop: [{ hooks: [{ type: "command", command: hookCmd }] }],
+    };
+  }
+  return { settings, buildCmd };
+}
+
 // --- main -----------------------------------------------------------------
 function main() {
   if (flags.help) { printHelp(); return; }
@@ -208,7 +284,7 @@ function main() {
   copyDir(join(KIT_ROOT, "templates", "docs"), join(cwd, "docs"), cwd);
   log("");
 
-  // 5. .claude/commands/ → 7 slash-commands
+  // 5. .claude/commands/ → 8 slash-commands
   log(`${c.bold}Commands${c.reset} → .claude/commands/`);
   copyDir(join(KIT_ROOT, "commands"), join(claudeDir, "commands"), cwd);
   log("");
@@ -232,7 +308,50 @@ function main() {
   );
   log("");
 
-  // 8. summary
+  // 7b. .claude/references/ → shared source of truth for review/test (read by both commands & agents)
+  log(`${c.bold}References${c.reset} → .claude/references/ ${c.dim}(shared standards for commands + agents)${c.reset}`);
+  copyDir(join(KIT_ROOT, "references"), join(claudeDir, "references"), cwd);
+  log("");
+
+  // 8. .claude/skills/ → model-invoked skills (auto-applied by Claude, no command needed)
+  log(`${c.bold}Skills${c.reset} → .claude/skills/ ${c.dim}(auto-applied by Claude — no command needed)${c.reset}`);
+  const skillsDir = join(claudeDir, "skills");
+  const kitSkillsDir = join(KIT_ROOT, "skills");
+
+  // Static skills: copy each folder wholesale (preserves templates/ and references/ subfiles).
+  // angular-practices is the only generated one (needs profile injection) — handled below.
+  for (const skill of readdirSync(kitSkillsDir)) {
+    if (skill === "angular-practices") continue;
+    const src = join(kitSkillsDir, skill);
+    if (!statSync(src).isDirectory()) continue;
+    copyDir(src, join(skillsDir, skill), cwd);
+  }
+
+  // angular-practices: generated — inject the matched profile filename + label
+  const apTemplate = join(kitSkillsDir, "angular-practices", "SKILL.md");
+  if (existsSync(apTemplate)) {
+    const body = readFileSync(apTemplate, "utf8")
+      .replace(/\{\{PRACTICE_FILE\}\}/g, practice)
+      .replace(/\{\{NG_PROFILE_LABEL\}\}/g, profileLabel(practice));
+    writeOne(body, join(skillsDir, "angular-practices", "SKILL.md"), cwd);
+  } else {
+    err(`skill template missing in kit: angular-practices/SKILL.md`);
+  }
+  log("");
+
+  // 9. .claude/agents/ → Angular-specialized subagents (isolated context, run in parallel)
+  log(`${c.bold}Agents${c.reset} → .claude/agents/ ${c.dim}(isolated context — dispatch to run in background/parallel)${c.reset}`);
+  copyDir(join(KIT_ROOT, "agents"), join(claudeDir, "agents"), cwd);
+  log("");
+
+  // 10. .claude/settings.json → permission allowlist + Stop-hook build verify
+  log(`${c.bold}Settings${c.reset} → .claude/settings.json ${c.dim}(allowlist + build verify)${c.reset}`);
+  const { settings, buildCmd } = buildSettings(cwd);
+  if (!buildCmd) warn("no package.json found — writing permissions only (no build-verify hook)");
+  writeOne(JSON.stringify(settings, null, 2) + "\n", join(claudeDir, "settings.json"), cwd);
+  log("");
+
+  // 11. summary
   log(`${c.bold}Done.${c.reset} ${copied} file(s) created, ${skipped} skipped.`);
   if (skipped > 0 && !flags.force) log(`${c.dim}Re-run with --force to overwrite skipped files.${c.reset}`);
   log("");
@@ -240,6 +359,13 @@ function main() {
   log(`  1. Open this project in ${c.cyan}Claude Code${c.reset}.`);
   log(`  2. Run ${c.cyan}/init${c.reset} — it will scan your codebase and fill in all the docs.`);
   log(`  3. Each session: ${c.cyan}/start${c.reset} → work → ${c.cyan}/update-status${c.reset}.`);
+  log("");
+  log(`${c.dim}Skills in .claude/skills/ apply automatically when you write or review`);
+  log(`Angular code — no command needed to trigger them.`);
+  log(`Agents in .claude/agents/ run in an isolated context — ask Claude to use one`);
+  log(`(e.g. "use angular-build-fixer to fix this build error"), even in the background.`);
+  log(`settings.json pre-allows ng/npm/pnpm/yarn/git-read (fewer prompts) and type-checks`);
+  log(`at turn end only when .ts/.html changed. Remove its "hooks" block to disable.${c.reset}`);
 }
 
 main();

package/commands/dev-cycle.md

@@ -5,6 +5,11 @@ This is an ORCHESTRATOR. It chains the other commands' logic, but it is NOT
 fully autonomous: after every phase it STOPS at a gate and waits for your
 explicit confirmation before continuing.
 
+Angular idioms depend on the project version — read `.claude/angular-practices/` and follow it.
+**Precedence** (see `.claude/rules/project-rules.md` → Precedence): a valid project convention wins
+over the BP profile; the profile applies only where the project has no convention or is below
+standard (new code only); legacy modules are never refactored.
+
 ---
 
 ## THE GATE RULE (applies after EVERY phase — non-negotiable)
@@ -26,28 +31,50 @@ Never skip a gate. Never batch multiple phases past a gate. The user is always i
 ## Phase 0 — Kickoff
 
 1. Read context:
-   - `.claude/rules/project-rules.md`
+   - `CLAUDE.md`
+   - `.claude/rules/project-rules.md` → naming, structure, Coexistence, **Reference Examples**
    - `docs/ARCHITECTURE.md`
    - `docs/API_CONTRACT.md`
-   - `docs/DESIGN_SYSTEM.md`
+   - `docs/DESIGN_SYSTEM.md` → shared components + Wrapped Components table
    - `.claude/angular-practices/` (the version profile)
-2. Ask ONE question: **"What is the feature name and what does it do?"** (name + one sentence)
-3. **GATE:** Wait for the answer. Write no code until you have it.
+   - **`docs/plans/`** → if a plan for this feature exists, read it in full; it is the source of
+     truth for scope, File Map, and task Interfaces (written by `/plan` per
+     `.claude/references/plan-spec.md`)
+   - **Open the Reference Example files** listed in `project-rules.md` (best existing service / page /
+     component / spec) and mirror their style — the strongest signal for matching real conventions
+2. Establish the feature:
+   - **If a plan was found** → the name and scope come from the plan's Goal. Do NOT re-ask them;
+     just confirm: **"Found plan `docs/plans/<file>` — follow it? (yes / no)"**.
+   - **If no plan** → ask ONE question: **"What is the feature name and what does it do?"** (name +
+     one sentence). If anything else about scope is unclear, ask it in the same batch — don't guess.
+     When the feature looks large (several screens or endpoints), add one line:
+     *"This looks sizeable — consider running `/plan` first for a reviewed task breakdown."* — then
+     continue anyway if the user wants to.
+3. **GATE:** Wait for the answer / confirmation. Write no code until you have it.
 
 ---
 
 ## Phase 1 — Scaffold
 
-1. Create the full folder + empty-file structure for `features/{feature-name}/`
-   (model, service, routes, pages/, components/ — match the layout in project-rules.md).
+1. Create the full folder + empty-file structure. **If a plan was found in Phase 0, create exactly
+   the files in the plan's File Map** (it already reflects the project's real layout). Otherwise
+   follow `.claude/references/feature-structure.md` → Folder Structure, using the project's actual
+   layout and folder names from `project-rules.md` (the reference file's tree is only the default shape).
 2. Print the created file tree.
 3. **GATE:** "✅ Folder structure OK? Continue to Phase 2 (Model + Service)? (yes / no)"
 
 ---
 
+> Follow `.claude/references/feature-structure.md` → Coding Rules throughout Phase 2a and 2b
+> (`OnPush`, subscription teardown per profile, no `any`, project's forms approach, no hardcoded
+> URLs, wrapper priority — never import a raw UI-library component when a wrapper exists).
+
+> If a plan was found in Phase 0, implement each piece from its tasks: use the exact model/DTO
+> shapes and service signatures declared in the tasks' `Interfaces: Consumes/Produces` blocks.
+
 ## Phase 2a — Implement Model + Service
 
-1. Write `models/{feature}.model.ts` — interfaces mirroring the backend's actual response shape from `API_CONTRACT.md` (envelope, raw DTO, or GraphQL type — per `project-rules.md`).
+1. Write `models/{feature}.model.ts` — interfaces mirroring the backend's actual response shape from `API_CONTRACT.md` (envelope, raw DTO, or GraphQL type — per `project-rules.md`), matching the plan's declared types if a plan exists.
 2. Write `services/{feature}.service.ts` — data-access methods returning `Observable<T>` typed with the project's response shape,
    following the DI/idiom of the version profile.
 3. Print the two files.
@@ -68,10 +95,14 @@ Never skip a gate. Never batch multiple phases past a gate. The user is always i
 
 ## Phase 3 — Tests + Context
 
-1. Write tests following `/write-tests`:
+1. **Verify the build first**: `ng build` / `npx tsc --noEmit` and `ng lint`. Fix any failure
+   immediately — a broken build makes test results meaningless, and this must not slip through to
+   Phase 4 or the commit in Phase 5.
+2. Write tests by dispatching the **`angular-test-writer`** agent (isolated — it follows
+   `.claude/references/test-spec.md`), or run `/write-tests` inline:
    - `{feature}.service.spec.ts` (mock HttpClient: success + error + empty per method)
    - `{feature}-list.component.spec.ts` (mock service: render + interaction + loading + error)
-2. **Harness loop — tests (automated within this phase, max 3 rounds):**
+3. **Harness loop — tests (automated within this phase, max 3 rounds):**
    ```
    round = 1
    while round <= 3:
@@ -84,14 +115,15 @@ Never skip a gate. Never batch multiple phases past a gate. The user is always i
      GATE: "❌ Tests still failing after 3 rounds. Exiting cycle — handle manually."
      → exit the automated cycle
    ```
-3. After tests pass, write the feature's `CONTEXT.md` in the same folder created in Phase 1 (per `/write-context`).
-4. **GATE:** "✅ Tests pass (round {n}) + CONTEXT.md written. Continue to Phase 4 (Review)? (yes / no)"
+4. After tests pass, write the feature's `CONTEXT.md` in the same folder created in Phase 1 (per `/write-context`).
+5. **GATE:** "✅ Build/lint clean + tests pass (round {n}) + CONTEXT.md written. Continue to Phase 4 (Review)? (yes / no)"
 
 ---
 
 ## Phase 4 — Review + Harness
 
-1. Run the full `/review-pr` checklist (all 8 categories).
+1. Review by dispatching the **`angular-reviewer`** agent (isolated), or run `/review-pr` inline —
+   both apply `.claude/references/review-checklist.md` (all dimensions).
 2. Print the result: count of 🔴 blockers, 🟡 suggestions, 🟢 good parts.
 3. If 0 blockers → skip the loop, go straight to the Phase 4 gate.
 4. If there are blockers:

package/commands/init.md

@@ -48,8 +48,12 @@ The version-matched best-practice file is in `.claude/angular-practices/`
 4. **Find the best-example files** — the most complete, idiomatic feature to use as a
    reference template. Pick the best example for each of: a service, a smart/page
    component, a dumb component, a test spec. Verify each path exists.
-5. Classify each finding: `standard` / `below-standard` / `uncertain`.
-6. Print a short findings summary (3–5 lines) + the chosen best-example files.
+5. **Detect the commit convention** — run `git log --oneline -50` (skip if no git history) and infer:
+   - **Prefix**: a consistent leading token before the type (e.g. `VIVAS_feat(...)` → prefix `VIVAS_`); none if not present.
+   - **Language**: the language of commit subjects (`vi` / `en`).
+   - **Scope source**: the folder level scopes come from (e.g. `src/app/features/<scope>` or `src/app/modules/<scope>`), based on the detected Folder Structure.
+6. Classify each finding: `standard` / `below-standard` / `uncertain`.
+7. Print a short findings summary (3–5 lines) + the chosen best-example files.
 
 ## Stage 1: Ask ALL Open Questions at Once
 1. Gather every `uncertain` item across ALL seven files into a single list
@@ -58,6 +62,8 @@ The version-matched best-practice file is in `.claude/angular-practices/`
    - **Wrapper auto-detection**: if wrappers were detected in Stage 0, confirm for each:
      (a) which library component it wraps, (b) custom additions, (c) is it required (BLOCKER) or preferred (SUGGESTION).
      Default if team does not answer: treat as SUGGESTION.
+   - **Commit convention**: if the prefix or language is ambiguous from `git log`, confirm them
+     (default: no prefix, language vi).
 2. Ask them as ONE grouped batch of multiple-choice questions.
 3. **WAIT** for the answers. Do not write any file until the batch is answered.
 4. If nothing is uncertain, say so and proceed directly to Stage 2.
@@ -69,7 +75,7 @@ placeholder with real content. Do NOT stop between files.
 1. **CLAUDE.md** (root) — `Read first` links, `Common commands` from `package.json` scripts, `Runtime and tooling` from detected stack, `High-level architecture` (2–4 line summary, link to docs/ARCHITECTURE.md). Under 200 lines.
 2. **docs/API_CONTRACT.md** — infer from existing `*.service.ts` calls; map endpoints → service methods → TypeScript interfaces. Mark gaps.
 3. **docs/ARCHITECTURE.md** — actual layer structure, routing/lazy-loading, state approach, HTTP/interceptor flow, auth strategy. Full detail here (not in CLAUDE.md).
-4. **.claude/rules/project-rules.md** — tech stack, naming, coding rules (actionable, not prose). Include the `## Precedence` section, the `## Reference Examples` section (best-example files from Stage 0 — paths that exist only), and the `## Coexistence Strategy` section (see below).
+4. **.claude/rules/project-rules.md** — tech stack, naming, coding rules (actionable, not prose). Include the `## Precedence` section, the `## Commit Convention` section (prefix / language / scope source detected in Stage 0 — default prefix none, language vi), the `## Reference Examples` section (best-example files from Stage 0 — paths that exist only), and the `## Coexistence Strategy` section (see below).
 5. **docs/PROJECT-STATUS.md** — snapshot: what exists, in progress, known issues, next tasks. Session counter = 1.
 6. **docs/DESIGN_SYSTEM.md** — UI library, design tokens (infer from styles/theme), shared/reusable components in whatever the project calls that folder (record the actual name), AND the **Wrapped Components** table (filled from Stage 0 detection, confirmed in Stage 1). If no wrappers found, OMIT the Wrapped Components section and add: `> This project uses UI library components directly — no shared wrappers.`
 7. **docs/decisions/** — one ADR per real decision confirmed (e.g. `001-state-management.md`, `002-auth-token-storage.md`). Only for actual decisions.

package/commands/new-feature.md

@@ -11,60 +11,39 @@ has no convention or is below standard (new code only); legacy modules are never
 - Read `docs/ARCHITECTURE.md` → where this feature fits
 - Read `docs/API_CONTRACT.md` → which endpoints this feature calls
 - Read `docs/DESIGN_SYSTEM.md` → shared components to use, **AND the Wrapped Components table → which wrapper to use for each UI library primitive** (e.g. for a dropdown, use `<app-select>` not `p-dropdown`)
+- Check `docs/plans/` → **if a plan for this feature exists** (written by `/plan`), it is the source
+  of truth for scope, File Map, and task Interfaces — follow it for Steps 2 and 3. If the feature is
+  large and no plan exists, suggest running `/plan` first, then continue if I want to.
 - **Open the Reference Example files** listed in `project-rules.md` (best existing service / page / component / spec) and mirror their style — this is the strongest signal for matching the project's real conventions
 - Ask me if anything is unclear before writing code
 
 ## Step 2: Create Feature Structure
-
-> **Use the project's actual layout and folder names from `project-rules.md`.**
-> The tree below is only the DEFAULT shape — if the project calls things differently
-> (e.g. `containers/` instead of `pages/`, `ui/` or `common/` instead of `shared/`,
-> an Nx `libs/` layout, or NgModule-based folders), follow the project, not this tree.
-
-```
-{features-dir}/{feature-name}/        # e.g. features/, modules/, or an Nx lib
-├── {feature}.routes.ts
-├── models/
-│   └── {feature}.model.ts           # Interfaces mirroring the backend response shape
-├── services/
-│   └── {feature}.service.ts         # All data-access calls
-├── pages/                           # Smart (container) components — project may call these containers/
-│   ├── {feature}-list/
-│   │   ├── {feature}-list.component.ts
-│   │   ├── {feature}-list.component.html
-│   │   └── {feature}-list.component.scss
-│   └── {feature}-detail/
-└── components/                      # Dumb (presentational) components
-    └── {feature}-form/
-```
-
-## Step 3: Implement in This Order
-1. **Model** — interfaces for entity, request/response, mirroring the backend's actual DTOs / response shape (per `project-rules.md` — envelope, raw DTO, or GraphQL type)
-2. **Service** — data-access methods returning `Observable<T>` typed with the project's response shape (HttpClient, or the project's client if it uses Apollo/another)
-3. **Routes** — lazy-loaded, guard-protected where needed
-4. **Page components (smart)** — data, loading/error/empty states
-5. **Presentational components (dumb)** — inputs/outputs only, no data access
-
-## Step 4: Write Tests (see /write-tests)
+If a plan was found in Step 1, create exactly the files in its File Map. Otherwise follow
+`.claude/references/feature-structure.md` → Folder Structure. **Always use the project's
+actual layout and folder names from `project-rules.md`** — the reference file's tree is only the
+default shape (e.g. the project may use `containers/` instead of `pages/`, an Nx `libs/` layout, etc.).
+
+## Step 3: Implement
+Follow `.claude/references/feature-structure.md` for both **Implementation Order** (Model → Service →
+Routes → Page components → Presentational components) and **Coding Rules** (data access in services
+only, `OnPush`, subscription teardown, no `any`, project's forms approach, no hardcoded URLs, wrapper
+priority) — apply the rules AS you write each piece, not as an afterthought. If a plan was found, use
+the exact model/DTO shapes and service signatures from its tasks' `Interfaces` blocks.
+
+## Step 4: Write Tests
+Dispatch the **`angular-test-writer`** agent (isolated context — it follows
+`.claude/references/test-spec.md`), or run `/write-tests` inline for a small feature. Either way:
 - Service: mock HttpClient, test success + error + empty per method
 - Component: mock service, test render + interaction + loading + error states
 
-## Step 5: Rules (from .claude/rules/project-rules.md + .claude/angular-practices/)
-- Data access ONLY in services — never in components
-- `ChangeDetectionStrategy.OnPush` on every component
-- Tear down subscriptions per profile: `takeUntilDestroyed` (v16+) or `takeUntil(destroy$)` + `ngOnDestroy` (v12–15)
-- No `any` — interfaces/types for every model and response
-- Use the project's forms approach from `project-rules.md` (Reactive Forms by default; Formly / template-driven if that's what the project uses)
-- No hardcoded backend URL — use `environment`
-- **Wrapper priority**: import from `@shared/components/<name>` (or the project's wrapper folder) if a wrapper exists; never import the library component directly. See `docs/DESIGN_SYSTEM.md` → Wrapped Components.
-
-## Step 6: Update Documentation
+## Step 5: Update Documentation
 - `docs/API_CONTRACT.md` if you used/discovered endpoints
 - Create `CONTEXT.md` inside the feature folder (use /write-context)
 - `docs/PROJECT-STATUS.md` (use /update-status)
 
-## Step 7: Verify
+## Step 6: Verify
 - Build passes: `ng build` / `npx tsc --noEmit`
 - All tests pass: `ng test` / `jest`
 - Lint passes: `ng lint`
-- Review with /review-pr before committing
+- Review before committing: dispatch the **`angular-reviewer`** agent (applies
+  `.claude/references/review-checklist.md` in an isolated context), or run `/review-pr` inline

package/commands/plan.md

@@ -0,0 +1,136 @@
+Plan a feature before writing any code: clarify the requirement, weigh approaches, agree on a
+design, then write a detailed, task-by-task implementation plan to `docs/plans/`.
+
+This command produces a PLAN, not code. It writes exactly one file — the plan document — and
+nothing else. `/dev-cycle` (gated, recommended) or `/new-feature` (linear) then execute it.
+
+Angular idioms depend on the project version — the plan defers to `.claude/angular-practices/` and
+to the **Precedence** rule in `.claude/rules/project-rules.md` (a valid project convention wins over
+the BP profile; the profile applies only where the project has no convention or is below standard,
+new code only; legacy modules are never refactored).
+
+## Running under Claude Code's Plan Mode
+
+If this session is in **Plan Mode** (you were given a plan-mode file path and told to use
+`ExitPlanMode` for approval), `Write`/`Edit` are restricted to that one file — you cannot write
+`docs/plans/<feature>.md` directly until Plan Mode ends. In that case:
+- Phases A–D run exactly as written below (they are read-only or pure conversation).
+- Phase D's GATE is skipped as a separate yes/no — approval happens via `ExitPlanMode` instead (see
+  Phase E's Plan Mode branch).
+- Phase E branches: compose + self-review the plan first, write it into the Plan Mode file, call
+  `ExitPlanMode`, and only after the user approves (Plan Mode ends) write the real
+  `docs/plans/<feature>.md` — same content, now at its real path.
+
+If this session is NOT in Plan Mode, ignore this section — run every phase as written, gates
+included.
+
+---
+
+## THE GATE RULE (applies after Phases B, C, D — non-negotiable)
+
+After a gated phase you MUST:
+1. Print a short summary of what was decided.
+2. Ask the gate question exactly as written for that phase.
+3. Then WAIT. Do not proceed on silence or assumption.
+4. If the user approves → continue to the next phase.
+5. If the user asks for changes → revise in place and re-ask the same gate. Do not skip ahead.
+
+Write NO code and scaffold NOTHING in any phase. The only file this command creates is the plan doc.
+
+---
+
+## Phase A — Context (no gate)
+
+Read, in this order:
+- `CLAUDE.md`
+- `.claude/rules/project-rules.md` → Precedence, naming, structure, Coexistence, **Reference Examples**
+- `docs/ARCHITECTURE.md` → where this feature fits
+- `docs/API_CONTRACT.md` → endpoints + payload shapes this feature will touch
+- `docs/DESIGN_SYSTEM.md` → shared components + **Wrapped Components table**
+- `.claude/angular-practices/` → the version profile
+- **Open the Reference Example files** listed in `project-rules.md` (best existing service / page /
+  component / spec) — the plan's file shapes and interfaces should mirror them.
+
+---
+
+## Phase B — Clarify the requirement
+
+1. **Scope check first.** If the request describes several independent subsystems (e.g. "a portal
+   with orders, chat, billing, and reports"), STOP and propose splitting it: name the independent
+   pieces and suggest one plan per piece. Brainstorm the first piece here; the rest get their own
+   `/plan` runs later. Do not spend questions on a feature that needs decomposition first.
+2. For an appropriately-scoped feature, ask the clarifying questions you need — purpose,
+   constraints, success criteria, edge cases, which endpoints/screens are in scope.
+   - **Batch them** (ask all open questions in one message, like `/init` Stage 1). Do not drip one
+     question per message.
+   - Prefer multiple-choice / yes-no phrasing where possible.
+   - Don't ask what the docs already answer — pull it from Phase A instead.
+3. **Adaptive follow-up:** if an answer reveals a new ambiguity you didn't anticipate (e.g. the user
+   mentions a status field that implies a workflow you need to understand), ask that **one**
+   follow-up question before the gate — don't silently guess, and don't revert to asking every
+   remaining question one at a time.
+4. **GATE:** "✅ Requirements clear? (yes / add more)" — WAIT for answers. Write nothing until you
+   have them.
+
+---
+
+## Phase C — Approaches
+
+1. Propose **2-3 approaches** with trade-offs (e.g. one feature service vs. split by concern;
+   reuse an existing service's pagination vs. a new one; smart/dumb split granularity).
+2. Lead with your **recommendation and why**, framed against this project's conventions and version
+   idioms — not generic advice.
+3. **GATE:** "✅ Which approach? (1 / 2 / 3 / other)" — WAIT.
+
+---
+
+## Phase D — Design
+
+1. Present the design in short sections, each scaled to its complexity (a few sentences each, more
+   only if nuanced): architecture & where it sits, data flow, components (smart/dumb split),
+   error/loading/empty handling, testing scope.
+2. Note explicitly which **shared wrappers** the UI will use (from the Wrapped Components table) and
+   which **endpoints** from `API_CONTRACT.md` it consumes.
+3. **GATE (skip if in Plan Mode — see below):** "✅ Design OK? Write the plan? (yes / revise)" — WAIT.
+   There is no separate design file — once approved, the design goes straight into the plan header.
+   **If in Plan Mode**, don't ask this separately — go straight to Phase E; `ExitPlanMode` there is
+   the approval.
+
+---
+
+## Phase E — Write the plan
+
+1. Determine today's date and the feature name → target path
+   `docs/plans/YYYY-MM-DD-<feature-name>.md`.
+2. Compose the plan content **strictly following `.claude/references/plan-spec.md`**: header (Goal /
+   Architecture / Approach chosen / Global Constraints), File Map, then tasks in Implementation
+   Order (Model → Service → Routes → Pages → Components → Tests), each with `Files:`,
+   `Interfaces: Consumes/Produces`, and concrete steps with real code — **no placeholders**.
+3. Run the **Self-Review checklist** from `plan-spec.md` (requirement coverage, placeholder scan,
+   type consistency vs. `API_CONTRACT.md`, wrapper check, layout check). Fix issues inline. Do this
+   BEFORE anything gets written below — either route commits the reviewed version.
+
+**Not in Plan Mode:**
+4. Create `docs/plans/` if it doesn't exist, write the reviewed content to the target path. Done.
+
+**In Plan Mode:**
+4. Write the reviewed content to the Plan Mode file (the one path you're currently allowed to
+   write). This is the plan the user will see when reviewing.
+5. Call `ExitPlanMode`. This IS the approval gate for Phases D and E — do not also ask the Phase D
+   text gate.
+6. Once the user approves and Plan Mode ends, immediately — before doing anything else — create
+   `docs/plans/` if needed and write the **same reviewed content** to
+   `docs/plans/YYYY-MM-DD-<feature-name>.md`. This is the real deliverable; the Plan Mode file was
+   only the approval copy.
+
+---
+
+## Phase F — Handoff
+
+Once `docs/plans/<file>.md` exists for real (directly from Phase E, or after the Plan Mode
+approval + follow-up write), print:
+> ✅ Plan saved to `docs/plans/<file>` — <N> tasks. I ran the self-review and fixed: <list, or "no
+> issues">. Review it, then run **`/dev-cycle`** (gated, recommended) or **`/new-feature`** (linear)
+> — both will detect and follow this plan.
+
+Do not start implementing. The user reviews the plan first.

package/commands/review-pr.md

@@ -1,71 +1,12 @@
-Review the code changes in this PR. Check every item — flag violations clearly.
-
-Read `.claude/angular-practices/` for version-correct idioms, and
-`.claude/rules/project-rules.md` for project-specific rules.
-
-**Precedence (see `project-rules.md` → Precedence):** a valid project convention wins over
-the BP profile; flag a BP deviation as a blocker only when it's an objective defect in NEW
-code. Do NOT flag legacy modules listed in the Coexistence Strategy — they are kept as-is.
-Do NOT flag a valid project choice (naming, structure, state lib, response shape) just
-because it differs from the profile.
-
-## Architecture
-- [ ] Smart / dumb separation: pages own data; presentational components only render + emit
-- [ ] HTTP calls ONLY in services — never in components
-- [ ] No business logic in templates
-- [ ] Feature routes are lazy-loaded
-
-## Type Safety
-- [ ] No `any` — interfaces/types for every model and API response
-- [ ] Responses typed with the project's response shape recorded in `project-rules.md` (e.g. an `ApiResponse<T>` envelope, a raw DTO, or a GraphQL type — whatever the backend actually returns)
-- [ ] No `@ts-ignore` / `@ts-expect-error`
-
-## Dependency Injection (follow `.claude/angular-practices/`)
-- [ ] DI matches the profile: `inject()` (v16+) or constructor injection (v12–15) — consistent across the project
-- [ ] Services `@Injectable({ providedIn: 'root' })`
-
-## Reactive / RxJS / Signals (follow `.claude/angular-practices/`)
-- [ ] Subscriptions torn down: `takeUntilDestroyed` (v16+) or `takeUntil(destroy$)` + `ngOnDestroy` (v12–15)
-- [ ] `async` pipe preferred over manual subscribe
-- [ ] No `toPromise()` — use `firstValueFrom()` if needed
-- [ ] Services return `Observable<T>` — do NOT subscribe internally
-- [ ] Signals used per profile: stable for state (v16+); derived state via `computed()`. `resource`/`httpResource` are experimental (v19+) — only if the team opted in
-
-## Error Handling
-- [ ] Loading / error / empty states handled in list/detail pages
-- [ ] HTTP errors surfaced to user (not swallowed)
-- [ ] Auth errors (e.g. 401) handled centrally by an interceptor — not per-feature
-
-## Security
-- [ ] Auth handled per the project's model in `project-rules.md` (token in memory / httpOnly cookie / session / OAuth) — and consistent with it. If tokens are used, they are NOT in localStorage
-- [ ] No hardcoded backend URL — uses `environment`
-- [ ] Routes needing auth are guarded
-- [ ] No unsanitized HTML (`innerHTML` / `bypassSecurityTrust*`) without a clear, reviewed reason
-
-## Performance
-- [ ] `ChangeDetectionStrategy.OnPush` on every component (or zoneless on v20+ if enabled)
-- [ ] List tracking present: `@for` with `track` (v17+) or `*ngFor` with `trackBy` (v12–16)
-
-## Code Quality
-- [ ] Component file < ~300 lines; method < ~50 lines
-- [ ] No dead code, no `console.log`
-- [ ] Naming follows `.claude/rules/project-rules.md`
-
-## Component Wrapping (follow `docs/DESIGN_SYSTEM.md` → Wrapped Components)
-- [ ] No feature imports a raw UI library component (`p-dropdown`, `mat-form-field`, `nz-input`, etc.) when a wrapper exists in `shared/components/`
-- [ ] All UI primitive imports go through the project's wrapper (check the import path matches the wrapper's location)
-- [ ] If a wrapper exists for the need but the PR uses the library directly → 🔴 BLOCKER
-- [ ] If no wrapper exists and the library is used directly → 🟡 SUGGESTION: "Consider creating a wrapper in `shared/components/` for consistency"
-- [ ] New components do NOT silently re-implement logic an existing wrapper already provides
-- [ ] If a brand-new wrapper is introduced → verify it follows the Wrapper Reference Example from `project-rules.md`
-
-## Documentation
-- [ ] New feature: `CONTEXT.md` created inside feature folder
-- [ ] Logic changed: `CONTEXT.md` Refactor Log updated (append only)
-- [ ] Endpoint changed: `docs/API_CONTRACT.md` updated
-- [ ] `docs/PROJECT-STATUS.md` updated
-
-## Summary
-1. **Blockers** 🔴 — must fix before merge
-2. **Suggestions** 🟡 — improve but not blocking
-3. **Good parts** 🟢 — what was done well
+Review the current code changes against this project's Angular standards.
+
+1. Get the diff: run `git diff` (unstaged) and `git diff --staged`, or `git diff <base>...HEAD` if a
+   base branch is named. Review only the changed code.
+2. Apply the full checklist in `.claude/references/review-checklist.md` — it defines the review
+   dimensions, the Precedence rule (a valid project convention wins; don't flag legacy), and the
+   🔴/🟡/🟢 output format. That file is the single source of truth for what "correct" means here.
+3. Output the report **inline** in this conversation using the format from the checklist. If there are
+   no blockers, say so explicitly.
+
+> For a large diff, or to review in the background while you keep coding, dispatch the
+> `angular-reviewer` agent instead — it applies the same checklist in an isolated context.