@tungvivas/angular-vibe-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 angular-vibe-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# angular-vibe-kit
+
+Bootstrap a **Vibe Coding workflow** into any Angular project: a `CLAUDE.md`, a set
+of project docs, and Claude Code slash-commands — with **best-practice rules matched
+to your Angular version**.
+
+Join an existing Angular project, run one command, and your AI assistant gains a
+persistent memory of how *this* codebase works.
+
+---
+
+## Why
+
+AI coding tools have no memory between sessions. Without a project context file they
+re-guess your conventions every time — wrong component patterns, wrong API shapes,
+wrong state management. This kit generates that context **from your actual codebase**,
+and keeps the AI honest with version-correct Angular rules (v14 → v19).
+
+It also handles the real-world case: **the project isn't fully best-practice yet.**
+The kit adds correct rules for *new* code without forcing risky refactors on legacy
+modules (Strangler Fig).
+
+---
+
+## Install
+
+Run inside the root of your Angular project:
+
+```bash
+npx @tungvivas/angular-vibe-kit
+```
+
+The installer (no AI, fully deterministic):
+
+1. Reads `./package.json` → detects your Angular version
+2. Copies slash-commands → `./.claude/commands/`
+3. Copies the **version-matched** best-practice file → `./.claude/angular-practices/`
+4. Copies doc templates → `./.claude/angular-kit/templates/`
+5. Tells you to run `/init` in Claude Code
+
+### Options
+| Flag | Effect |
+|------|--------|
+| `--version <n>` | Override detected version (e.g. `--version 17`) |
+| `--force` | Overwrite files that already exist |
+| `--dry-run` | Show what would happen, write nothing |
+| `-h, --help` | Help |
+
+---
+
+## Use
+
+After install, open the project in **Claude Code**:
+
+```
+/init            ← scan codebase, ask to confirm uncertain bits, generate docs
+```
+
+`/init` generates, one file at a time (you review each):
+`CLAUDE.md` → `docs/API_CONTRACT.md` → `docs/ARCHITECTURE.md` →
+`docs/PROJECT-RULES.md` → `docs/PROJECT-STATUS.md` → `docs/DESIGN_SYSTEM.md` →
+`docs/decisions/`.
+
+Then every working session:
+
+| Command | When | Does |
+|---------|------|------|
+| `/start` | Start of session | Read docs, summarize progress, wait |
+| `/new-feature` | New module | Scaffold → implement → test → docs |
+| `/write-tests` | Code without tests | Service spec + component test |
+| `/write-context` | New/complex module | Create `CONTEXT.md` snapshot |
+| `/review-pr` | Before commit | Angular review checklist → 🔴/🟡/🟢 |
+| `/update-status` | End of session | Update `PROJECT-STATUS.md` + commit |
+
+---
+
+## Version-matched best practices
+
+The installer copies exactly one profile based on your `@angular/core`:
+
+| Angular | Profile | Key idioms |
+|---------|---------|-----------|
+| 14–15 | `v14-15.md` | NgModule, `*ngIf/*ngFor`, constructor DI, RxJS + `BehaviorSubject` |
+| 16 | `v16.md` | `inject()`, required inputs, `takeUntilDestroyed`, Signals (preview) |
+| 17 | `v17.md` | Standalone default, `@if/@for/@switch`, `@defer`, Signals stable |
+| 18–19 | `v18-19.md` | Signal inputs/outputs, `linkedSignal`/`resource`, zoneless (experimental) |
+
+These files cover **framework idioms only** (syntax, DI, components, RxJS/Signals).
+Project-specific choices — folder layout, state-management, naming — are inferred
+from your code and written into `docs/PROJECT-RULES.md`.
+
+---
+
+## Coexistence (joining a not-yet-standard project)
+
+`/init` classifies what it finds as `standard`, `below-standard`, or `uncertain`,
+then writes a **Coexistence Strategy** into `PROJECT-RULES.md`:
+
+- Patterns you already do right → kept as required rules.
+- Sub-standard patterns → correct rule applied to **new code only**.
+- Legacy modules → listed as **do-not-touch** (no refactor unless asked).
+
+Anything uncertain becomes a question — the kit never silently rewrites your rules.
+
+---
+
+## What gets created in your project
+
+```
+your-angular-app/
+├── CLAUDE.md                       # generated by /init
+├── .claude/
+│   ├── commands/                   # 7 slash-commands (copied by installer)
+│   │   ├── init.md  start.md  new-feature.md  review-pr.md
+│   │   ├── write-tests.md  write-context.md  update-status.md
+│   ├── angular-practices/          # 1 version-matched profile (copied)
+│   │   └── v17.md
+│   └── angular-kit/templates/      # doc templates (copied)
+└── docs/                           # generated by /init
+    ├── PROJECT-RULES.md  ARCHITECTURE.md  API_CONTRACT.md
+    ├── PROJECT-STATUS.md  DESIGN_SYSTEM.md
+    └── decisions/
+```
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * angular-vibe-kit installer
+ *
+ * Deterministic, no AI. Detects the target project's Angular version from
+ * package.json, then scaffolds the Vibe Coding workspace:
+ *
+ *   CLAUDE.md                      ← project root (entry point)
+ *   docs/                          ← reference docs
+ *     ARCHITECTURE.md
+ *     API_CONTRACT.md
+ *     DESIGN_SYSTEM.md
+ *     PROJECT-STATUS.md
+ *     decisions/
+ *   .claude/
+ *     commands/                    ← 7 slash-commands
+ *     angular-practices/<ver>.md   ← version-matched best-practice file
+ *     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 { fileURLToPath } from "node:url";
+import { dirname, join, resolve, relative } from "node:path";
+import { createRequire } from "node:module";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const KIT_ROOT = resolve(__dirname, "..");
+
+// --- package metadata (single source of truth = package.json) -----------
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+const VERSION = pkg.version;
+const HOMEPAGE = pkg.homepage;
+
+// --- tiny ansi helpers (no deps) -----------------------------------------
+const c = { reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m", red: "\x1b[31m", green: "\x1b[32m", yellow: "\x1b[33m", cyan: "\x1b[36m" };
+const log = (msg = "") => process.stdout.write(msg + "\n");
+const ok  = (msg) => log(`${c.green}✓${c.reset} ${msg}`);
+const warn = (msg) => log(`${c.yellow}!${c.reset} ${msg}`);
+const err  = (msg) => log(`${c.red}✗${c.reset} ${msg}`);
+
+// --- arg parsing ----------------------------------------------------------
+const args = process.argv.slice(2);
+const flags = {
+  force:   args.includes("--force"),
+  dryRun:  args.includes("--dry-run"),
+  help:    args.includes("--help") || args.includes("-h"),
+  version: getFlagValue("--version"),
+};
+
+function getFlagValue(name) {
+  const i = args.indexOf(name);
+  return i === -1 ? null : (args[i + 1] ?? null);
+}
+
+function printHelp() {
+  log(`${c.bold}angular-vibe-kit${c.reset} — bootstrap the Vibe Coding workflow into an Angular project
+
+${c.bold}Usage${c.reset}
+  npx @tungvivas/angular-vibe-kit [options]
+
+${c.bold}Options${c.reset}
+  --version <n>   Override detected Angular major version (e.g. 17)
+  --force         Overwrite files that already exist
+  --dry-run       Show what would happen without writing anything
+  -h, --help      Show this help
+
+${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/angular-practices/      ← version-matched best-practice file
+  .claude/rules/project-rules.md  ← auto-loaded every Claude Code session`);
+}
+
+// --- version detection ----------------------------------------------------
+const MIN_SUPPORTED = 12;
+const PRACTICE_BY_MAJOR = {
+  12: "v12-13.md", 13: "v12-13.md",
+  14: "v14-15.md", 15: "v14-15.md",
+  16: "v16.md",
+  17: "v17.md",
+  18: "v18-19.md", 19: "v18-19.md",
+  20: "v20plus.md",           // Signal-native: zoneless stable, signals graduated; resource/httpResource still experimental
+};
+const NEWEST_PRACTICE = "v20plus.md"; // fallback for v21+ (future)
+
+function detectAngularMajor(cwd) {
+  const pkgPath = join(cwd, "package.json");
+  if (!existsSync(pkgPath)) return { major: null, reason: "no package.json found" };
+  let pkg;
+  try {
+    const raw = readFileSync(pkgPath, "utf8").replace(/^/, ""); // strip BOM
+    pkg = JSON.parse(raw);
+  } catch { return { major: null, reason: "package.json is not valid JSON" }; }
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const raw = deps["@angular/core"] || deps["@angular/cli"];
+  if (!raw) return { major: null, reason: "no @angular/core or @angular/cli dependency" };
+  const match = String(raw).match(/(\d+)\s*\.\s*\d+/) || String(raw).match(/(\d+)/);
+  if (!match) return { major: null, reason: `could not parse version "${raw}"` };
+  return { major: Number(match[1]), reason: null, raw };
+}
+
+function resolvePractice(major) {
+  if (major === null) return { file: null, issue: "unknown" };
+  if (major < MIN_SUPPORTED) return { file: null, issue: "below-min" };
+  if (PRACTICE_BY_MAJOR[major]) return { file: PRACTICE_BY_MAJOR[major], issue: null };
+  // v20+ future: use newest
+  return { file: NEWEST_PRACTICE, issue: "future" };
+}
+
+// --- copy helpers ---------------------------------------------------------
+let copied = 0;
+let skipped = 0;
+
+function ensureDir(dir) {
+  if (!flags.dryRun) mkdirSync(dir, { recursive: true });
+}
+
+function copyOne(src, 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 copy → ${rel}${c.reset}`);
+    copied++;
+    return;
+  }
+  ensureDir(dirname(dest));
+  copyFileSync(src, dest);
+  ok(rel);
+  copied++;
+}
+
+function copyDir(srcDir, destDir, cwd) {
+  for (const entry of readdirSync(srcDir)) {
+    const srcPath = join(srcDir, entry);
+    const destPath = join(destDir, entry);
+    if (statSync(srcPath).isDirectory()) copyDir(srcPath, destPath, cwd);
+    else copyOne(srcPath, destPath, cwd);
+  }
+}
+
+// --- main -----------------------------------------------------------------
+function main() {
+  if (flags.help) { printHelp(); return; }
+
+  const cwd = process.cwd();
+  log(`${c.bold}angular-vibe-kit${c.reset} ${c.dim}v${VERSION}${c.reset}`);
+  if (flags.dryRun) warn("dry-run: no files will be written");
+  log("");
+
+  // 1. detect version
+  let major;
+  if (flags.version) {
+    major = Number(flags.version);
+    log(`Using forced Angular version: ${c.cyan}${major}${c.reset}`);
+  } else {
+    const detected = detectAngularMajor(cwd);
+    if (detected.major) {
+      major = detected.major;
+      log(`Detected Angular version: ${c.cyan}${major}${c.reset} ${c.dim}(${detected.raw})${c.reset}`);
+    } else {
+      err(`Cannot detect Angular version: ${detected.reason}`);
+      log("");
+      log(`${c.bold}Fix options:${c.reset}`);
+      log(`  1. Run inside the Angular project folder (where package.json lives)`);
+      log(`  2. Use ${c.cyan}--version <n>${c.reset} to specify manually, e.g. ${c.cyan}--version 17${c.reset}`);
+      process.exit(1);
+    }
+  }
+
+  // 2. resolve which practice file to use
+  const { file: practice, issue } = resolvePractice(major);
+
+  if (issue === "below-min") {
+    err(`Angular ${major} is below the minimum supported version (${MIN_SUPPORTED}).`);
+    log("");
+    log(`${c.bold}Supported versions:${c.reset} 12, 13, 14, 15, 16, 17, 18, 19`);
+    log(`If you still want to proceed, use the closest profile:`);
+    log(`  ${c.cyan}npx @tungvivas/angular-vibe-kit --version 12${c.reset}  (v12-13 best practices)`);
+    process.exit(1);
+  }
+
+  if (issue === "future") {
+    warn(`Angular ${major} has no dedicated profile yet — using v20+ profile (${NEWEST_PRACTICE}).`);
+    warn(`Check ${HOMEPAGE} for a dedicated update.`);
+  }
+
+  log(`Best-practice profile: ${c.cyan}${practice}${c.reset}`);
+  log("");
+
+  const claudeDir = join(cwd, ".claude");
+
+  // 3. CLAUDE.md → project root
+  log(`${c.bold}Entry point${c.reset}`);
+  copyOne(join(KIT_ROOT, "templates", "CLAUDE.md"), join(cwd, "CLAUDE.md"), cwd);
+  log("");
+
+  // 4. docs/ → project root/docs/
+  log(`${c.bold}Docs${c.reset} → docs/`);
+  copyDir(join(KIT_ROOT, "templates", "docs"), join(cwd, "docs"), cwd);
+  log("");
+
+  // 5. .claude/commands/ → 7 slash-commands
+  log(`${c.bold}Commands${c.reset} → .claude/commands/`);
+  copyDir(join(KIT_ROOT, "commands"), join(claudeDir, "commands"), cwd);
+  log("");
+
+  // 6. .claude/angular-practices/ → 1 matched BP file
+  log(`${c.bold}Best practices${c.reset} → .claude/angular-practices/`);
+  const practiceSrc = join(KIT_ROOT, "practices", practice);
+  if (existsSync(practiceSrc)) {
+    copyOne(practiceSrc, join(claudeDir, "angular-practices", practice), cwd);
+  } else {
+    err(`practice file missing in kit: ${practice}`);
+  }
+  log("");
+
+  // 7. .claude/rules/project-rules.md → auto-loaded by Claude Code
+  log(`${c.bold}Rules${c.reset} → .claude/rules/ ${c.dim}(auto-loaded every session)${c.reset}`);
+  copyOne(
+    join(KIT_ROOT, "templates", "rules", "project-rules.md"),
+    join(claudeDir, "rules", "project-rules.md"),
+    cwd
+  );
+  log("");
+
+  // 8. 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("");
+  log(`${c.bold}Next steps${c.reset}`);
+  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}.`);
+}
+
+main();

package/commands/dev-cycle.md

@@ -0,0 +1,139 @@
+Run the full feature development cycle for one Angular feature, end to end:
+scaffold → implement → test → context → review → wrap up.
+
+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.
+
+---
+
+## THE GATE RULE (applies after EVERY phase — non-negotiable)
+
+After finishing each phase, you MUST:
+1. Print a short summary of what was just done.
+2. Ask exactly: **"✅ Continue to Phase X? (yes / no)"**
+3. Then WAIT. Do not proceed on silence, timeout, or assumption.
+4. If the user replies **yes / ok / continue / tiếp** → move to the next phase.
+5. If the user replies **anything else** (no / stop / "sửa lại ..." / a change request / a question)
+   → **EXIT the automated cycle immediately.** Drop into normal interactive mode and
+   do whatever the user asks. Do NOT try to resume the cycle unless the user explicitly
+   says to continue.
+
+Never skip a gate. Never batch multiple phases past a gate. The user is always in control.
+
+---
+
+## Phase 0 — Kickoff
+
+1. Read context:
+   - `.claude/rules/project-rules.md`
+   - `docs/ARCHITECTURE.md`
+   - `docs/API_CONTRACT.md`
+   - `docs/DESIGN_SYSTEM.md`
+   - `.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.
+
+---
+
+## 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).
+2. Print the created file tree.
+3. **GATE:** "✅ Folder structure OK? Continue to Phase 2 (Model + Service)? (yes / no)"
+
+---
+
+## 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`).
+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.
+4. **GATE:** "✅ Model + Service OK? Continue to Phase 2b (Routes + UI)? (yes / no)"
+   > This gate matters most — a wrong type/endpoint here breaks every component after it.
+
+---
+
+## Phase 2b — Implement Routes + Pages + Components
+
+1. Write `{feature}.routes.ts` (lazy-loaded).
+2. Write page (smart) components — data, loading/error/empty states.
+3. Write presentational (dumb) components — inputs/outputs only.
+4. Print a summary of files written.
+5. **GATE:** "✅ UI components OK? Continue to Phase 3 (Tests)? (yes / no)"
+
+---
+
+## Phase 3 — Tests + Context
+
+1. Write tests following `/write-tests`:
+   - `{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):**
+   ```
+   round = 1
+   while round <= 3:
+     say "Running tests, round {round}/3..."
+     run: ng test {feature} (or jest {feature})
+     if PASS: break
+     read the failure output → fix the code/test → round += 1
+   if still failing after 3 rounds:
+     print remaining errors
+     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)"
+
+---
+
+## Phase 4 — Review + Harness
+
+1. Run the full `/review-pr` checklist (all 8 categories).
+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:
+   - **GATE:** "🔴 {n} blockers found. Auto-fix and re-review? (yes / no)"
+     - NO → exit the automated cycle; user fixes manually.
+     - YES → **Harness loop — review (max 3 rounds):**
+       ```
+       round = 1
+       while round <= 3:
+         say "Fix round {round}/3 — fixing: {list of blockers}"
+         fix ALL 🔴 blockers
+         re-run /review-pr checklist
+         if 0 blockers: break
+         round += 1
+       if blockers remain after 3 rounds:
+         print remaining blockers
+         GATE: "❌ Blockers remain after 3 rounds. Exiting cycle — handle manually."
+         → exit the automated cycle
+       ```
+5. 🟡 Suggestions are NOT blocking — list them so the user can decide later.
+6. **GATE:** "✅ Review clean (0 blockers after {n} rounds). Continue to Phase 5 (Wrap up)? (yes / no)"
+
+---
+
+## Phase 5 — Wrap up
+
+1. Update `docs/PROJECT-STATUS.md` (per `/update-status` — move to Completed, bump session).
+2. Update `docs/API_CONTRACT.md` if new endpoints were used.
+3. Generate a commit message: `feat({feature-name}): {description} + tests + docs`.
+4. Print the git command for the user to run:
+   ```
+   git add CLAUDE.md docs/ .claude/rules/ src/
+   git commit -m "feat({feature-name}): {description} + tests + docs"
+   ```
+5. **Do NOT run git yourself.** The user reviews and commits.
+6. Final message: "✅ dev-cycle complete. Run the git command above to commit."
+
+---
+
+## Notes
+- Harness loops (Phase 3 tests, Phase 4 review) run automatically WITHIN their phase —
+  they handle mechanical errors (compile, test failures, checklist blockers) without bugging you.
+- But the loops are bounded (max 3 rounds) and never cross a phase gate.
+- Logic correctness ("does it do what I actually wanted?") is checked by YOU at the gates,
+  not by the harness — that is why the human gates exist.

package/commands/init.md

@@ -0,0 +1,103 @@
+Scan this Angular project's codebase and fill in the skeleton docs that were
+created by the installer. This command runs **one-shot**: scan → ask all open
+questions once → write all files → verify → summarize. Reads code and writes
+docs only — never modifies application source files.
+
+The skeleton files already exist at their correct locations:
+  CLAUDE.md                        ← project root (keep under 200 lines)
+  docs/ARCHITECTURE.md
+  docs/API_CONTRACT.md
+  docs/DESIGN_SYSTEM.md
+  docs/PROJECT-STATUS.md
+  docs/decisions/
+  .claude/rules/project-rules.md   ← auto-loaded every session
+
+The version-matched best-practice file is in `.claude/angular-practices/`
+(one file, already matched to this project's Angular version by the installer).
+
+## Core Principles
+- **Infer from code first.** Read before asking — do not ask about things you can determine.
+- **Batch the questions.** Collect EVERY uncertain point across ALL files and ask them in ONE round (Stage 1). Do not drip-feed questions file by file.
+- **Then write everything.** After the answers come back, write all 7 files in one pass (Stage 2) — no per-file stops.
+- **Review is at the end.** The human review happens once, after the summary (Stage 4) — not between files.
+- **Precedence: codebase first, then the BP profile.** A valid project convention wins over the Angular best-practice profile; the profile applies only where the project has no convention or is objectively below standard (new code only). Legacy is never refactored. Write this exact precedence into `project-rules.md` (the `## Precedence` section).
+- **CLAUDE.md stays under 200 lines.** Link to docs/ for details, do not inline everything.
+
+## Stage 0: Scan (read-only, no output yet)
+1. Read the BP file in `.claude/angular-practices/` (one file — the version's idioms).
+2. Read `package.json` → Angular version, UI library, test runner, state libs.
+3. Scan `src/`:
+   - Module system: standalone vs NgModule
+   - State: NgRx / Signals / BehaviorSubject / plain service
+   - Folder layout: `core/ shared/ features/` or other
+   - HTTP pattern: HttpClient in services vs components
+   - Interceptors, guards, auth flow, token handling
+   - Test setup, shared components, UI library usage
+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.
+
+## Stage 1: Ask ALL Open Questions at Once
+1. Gather every `uncertain` item across ALL seven files into a single list
+   (e.g. "both NgRx and Signals present — which is primary?", "response envelope shape?",
+   "auth model?", "which forms approach?", "confirm this legacy do-not-touch list").
+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.
+
+## Stage 2: Write ALL Files (one pass, no stops)
+Using the scan + the answers, write all files in this order. Replace every `{{...}}`
+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).
+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).
+7. **docs/decisions/** — one ADR per real decision confirmed (e.g. `001-state-management.md`, `002-auth-token-storage.md`). Only for actual decisions.
+
+### Coexistence Strategy (inside project-rules.md)
+- `standard` items → required rules (the project already does this; keep doing it).
+- `below-standard` items → correct rule from the BP file, scoped to **new code only**, with note: "Legacy modules keep their style — do NOT refactor unless explicitly asked."
+- List the **legacy / do-not-touch modules** (confirmed in the Stage 1 batch).
+
+## Stage 3: Self-Verification (prove the docs work)
+1. **Placeholder scan:** no leftover `{{...}}` / `TODO` / `TBD`. Report "0 placeholders left".
+2. **Path check:** every file path mentioned (Reference Examples, CLAUDE.md links, ADR pointers) actually exists. Fix any broken path.
+3. **Comprehension test:** answer this using ONLY the generated docs —
+   > "If I add a new `XyzService` + list page: (a) which folder, (b) which DI/RxJS/Signals idiom, (c) what response shape does the service return, (d) where does the test go and what's it named?"
+   If any part can't be answered from the docs, fill the gap.
+
+## Stage 4: Final Summary (always print this last)
+Print a summary so I can review everything at once:
+
+**1. What I did** — 2–4 bullet lines (version detected, key conventions captured, legacy modules flagged).
+
+**2. Files changed** — a table:
+
+| File | Status | Key content / decisions captured |
+|------|--------|----------------------------------|
+| CLAUDE.md | created/updated | ... |
+| docs/API_CONTRACT.md | created/updated | ... |
+| docs/ARCHITECTURE.md | created/updated | ... |
+| .claude/rules/project-rules.md | created/updated | precedence + coexistence + reference examples |
+| docs/PROJECT-STATUS.md | created/updated | ... |
+| docs/DESIGN_SYSTEM.md | created/updated | ... |
+| docs/decisions/00x-*.md | created | ... |
+
+**3. Questions I asked & your answers** — short list (for the record).
+
+**4. Verification** — placeholders left (should be 0), broken paths (should be 0), comprehension-test answer.
+
+**5. Anything still uncertain / needs your eyes** — gaps, assumptions, endpoints to confirm.
+
+Then: "Review the summary above. Commit when ready:
+`git add CLAUDE.md docs/ .claude/rules/ && git commit -m \"docs: init angular-vibe-kit workspace\"`"
+
+## Rules
+- Do NOT modify `.ts`, `.html`, `.scss` application files.
+- Do NOT add content that is not inferable from the codebase or confirmed in the Stage 1 batch.
+- Stage 1 (questions) and Stage 4 (summary + review) are the only interactive points — everything between is one pass.