@eltonssouza/development-utility-kit 1.0.0

package/dashboard/public/content/manual/frontend.en.md

@@ -0,0 +1,1065 @@
+# Frontend Manual — development-utility-kit
+
+> Definitive manual for **Angular 21** frontend developers working with the `development-utility-kit` harness. Covers everything from `duk install` to your first merged PR, with exact prompts, step-by-step workflows, and non-negotiable rules.
+
+---
+
+## 1. Introduction
+
+### Who this manual is for
+
+You are a frontend developer building screens with **Angular 21** (standalone, Signals, OnPush, lazy loading, Signal Forms) using the harness. It doesn't matter if you've never opened Cowork — this manual takes you from zero to first component in production.
+
+### What's covered
+
+- 5-minute onboarding
+- The **non-negotiable** 3-file rule (`.ts` / `.html` / `.scss`)
+- Frontend-applicable harness skills
+- External **Impeccable** skill (visual refinement)
+- Complete workflows with real prompts (feature from scratch, visual polish, debugging, mobile)
+- Intent-based trigger cheat sheet
+- Antipatterns and troubleshooting
+
+### Prerequisites
+
+- **Node.js 22+** (`node --version`)
+- **npm 10+** (`npm --version`)
+- **Angular CLI 21+** (`npx @angular/cli@latest version`)
+- **Git** in PATH
+- **Cowork** OR **Claude Code** installed and authenticated
+- Editor with TypeScript support (VS Code recommended)
+
+### What's NOT here
+
+- Spring Boot backend setup → see `[Backend](backend)`
+- Fullstack monorepo → see `[Fullstack](fullstack)`
+- React Native / Expo → see `[Mobile](mobile)`
+- Legacy project adoption → see `[Existing Project](existing-project)`
+
+---
+
+## 2. 5-minute onboarding
+
+### Step 1 — Install the harness
+
+```bash
+# Default path (Windows: C:\development\tools\development-utility-kit)
+npx @eltonssouza/development-utility-kit install
+```
+
+Idempotent: runs `git pull` if the repository already exists.
+
+### Step 2 — Create (or enter) the frontend project
+
+```bash
+# Create from scratch
+mkdir C:\development\source\projects\my-front
+cd C:\development\source\projects\my-front
+git init
+```
+
+### Step 3 — Install harness in the project
+
+```bash
+duk install
+```
+
+Creates `.claude/`, `CLAUDE.md`, `.cursorrules`, Git hooks, scripts. Idempotent.
+
+### Step 4 — Edit `CLAUDE.md` → Project Identity
+
+Open `CLAUDE.md` and edit **ONLY** the `Project Identity` section:
+
+```markdown
+## Project Identity
+
+- **Project name**: `my-front`
+- **Project type**: `frontend`
+- **Primary stack**: `Angular 21`
+- **Frontend stack**: `angular`
+- **Database**: `n/a`
+- **Domain**: `e-commerce`
+- **Team size**: `2 frontend`
+- **Additional rules**:
+```
+
+> **Attention**: The `Frontend stack` field is read by the `bootstrap-frontend` skill to choose between `angular` and `vite-vanilla`. Without it, the skill won't trigger.
+
+### Step 5 — Open Cowork or Claude Code
+
+Open the Cowork terminal (or `claude` CLI) at the project root.
+
+### Step 6 — First conversation
+
+Type in chat:
+
+```text
+scaffold the frontend
+```
+
+The `bootstrap-frontend` skill triggers, runs Angular CLI 21, configures standalone + OnPush + lazy loading + Jest + jest-axe + ng-bootstrap + Playwright. Expected output:
+
+```text
+frontend/
+├── src/app/
+│   ├── core/
+│   ├── shared/
+│   ├── features/
+│   └── app.routes.ts
+├── angular.json
+├── package.json
+├── jest.config.js
+├── playwright.config.ts
+└── tsconfig.json
+```
+
+### Step 7 — Launch dashboard (optional)
+
+```bash
+duk dashboard
+```
+
+Opens `http://localhost:4242` with manual, skills, agents, ADRs, hooks.
+
+Done. You're on the harness. Next stop: the 3-file rule.
+
+---
+
+## 3. NON-NEGOTIABLE RULE — 3 separate files in every Angular component
+
+> **HARD BLOCK.** `tech-lead` and `code-reviewer` refuse merge if you violate. **No exceptions. No size threshold. No "small component" carve-out.** This `CLAUDE.md` rule overrides the threshold-based policy of ADR-008.
+
+### The rule
+
+Every component, directive, or pipe **with a template** uses exactly **three physical files**:
+
+| File | Content |
+|---|---|
+| `<name>.ts` | Component logic. Decorator with `templateUrl` + `styleUrl` (or `styleUrls`). |
+| `<name>.html` | Full HTML template. |
+| `<name>.scss` | SCSS styles. |
+
+**NEVER** use `template: \`...\`` or `styles: [\`...\`]` or `styleUrls: ['...inline...']` inside the `.ts`. No kidding.
+
+### CORRECT example
+
+`product-list.component.ts`
+
+```typescript
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { NgbPaginationModule } from '@ng-bootstrap/ng-bootstrap';
+
+@Component({
+  selector: 'app-product-list',
+  standalone: true,
+  imports: [CommonModule, NgbPaginationModule],
+  templateUrl: './product-list.component.html',
+  styleUrl: './product-list.component.scss',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ProductListComponent {
+  readonly products = signal<readonly Product[]>([]);
+  readonly page = signal(1);
+}
+```
+
+`product-list.component.html`
+
+```html
+<section class="product-list" data-testid="product-list">
+  <ul>
+    @for (product of products(); track product.id) {
+      <li>{{ product.name }}</li>
+    }
+  </ul>
+  <ngb-pagination [collectionSize]="total()" [(page)]="page" />
+</section>
+```
+
+`product-list.component.scss`
+
+```scss
+.product-list {
+  display: grid;
+  gap: var(--spacing-md);
+  padding: var(--spacing-lg);
+}
+```
+
+### FORBIDDEN example
+
+```typescript
+// ❌ HARD BLOCK — code-reviewer / tech-lead refuse merge
+@Component({
+  selector: 'app-product-list',
+  standalone: true,
+  template: `
+    <ul>
+      @for (p of products(); track p.id) { <li>{{ p.name }}</li> }
+    </ul>
+  `,
+  styles: [`.product-list { display: grid; }`],
+})
+export class ProductListComponent {}
+```
+
+### Why so strict?
+
+- Readable PR diff (each layer isolated)
+- HTML/SCSS linting and formatting work correctly
+- `code-reviewer` audits HTML separately from TS
+- Designers/UX can review HTML/SCSS without touching TS
+- Enables Storybook extraction without refactoring
+
+---
+
+## 4. Frontend-applicable skills
+
+The harness exposes skills that trigger by **keyword** in Claude Code/Cowork conversations. There is **NO** `duk bootstrap-frontend` or `duk grill-me` — you type in chat.
+
+### Master table
+
+| Skill | When to use | Exact trigger |
+|---|---|---|
+| `bootstrap-frontend` | Initial project scaffold | `scaffold the frontend`, `create Angular frontend`, `build the front skeleton`, `set up Angular` |
+| `grill-me` | Discovery (interview before PRD) | `grill me on <X>`, `interview me about <X>`, `stress-test the plan` |
+| `to-prd` | Generate PRD from discovery | `generate PRD`, `create PRD` |
+| `to-issues` | Break PRD into GitHub issues | `break into issues`, `generate issues` |
+| `run-sprint` | Execute a PLAN sprint | `run sprint <N>`, `execute the sprint`, `let's code this sprint` |
+| `auto-test-guard` | Generate tests + run senior+ gate | `run tests`, `generate tests`, `test everything`, `full suite` |
+| `api-integration-test` | Smoke test front+back integration | `test integration`, `smoke test` |
+| `pair-debug` | Hypothesis-driven debugging | `let's debug <X>`, `investigate this bug`, `find root cause` |
+| `prd-ready-check` | GO/NO-GO for production | `is it production ready?`, `DoD` |
+| `brain-keeper` | Record history in Obsidian | `record in brain`, `update brain` |
+| `honcho-memory` | Cross-session memory | `remember that <X>`, `/honcho save`, `/honcho list` |
+| `caveman` | Telegraphic mode (default ON) | `caveman lite/full/ultra`, `stop caveman` |
+| `project-manager` | Catch-all (default) | Any prompt without a specific skill |
+
+### Detailed cards
+
+#### `bootstrap-frontend`
+
+- **When**: new project, `CLAUDE.md` configured with `Project type: frontend`.
+- **Trigger**: `scaffold the frontend`
+- **Prerequisite**: `Frontend stack: angular` (or `vite-vanilla`) field filled.
+- **Output**: `frontend/` folder with Angular CLI 21, standalone, OnPush, lazy loading, Jest, jest-axe, Playwright, ng-bootstrap, ESLint, Prettier, design tokens in `src/styles/_tokens.scss`.
+- **Next step**: `grill me on <first screen>`.
+
+#### `grill-me` (opt-in)
+
+- **When**: starting a new feature/screen. **Mandatory** before `to-prd` on the human path.
+- **Trigger**: `grill me on <X>`
+- **Output**: `docs/discovery/DISCOVERY_<feature>.md` with pains, personas, flows, constraints, technical decisions, risks. In some cases also produces `Proposed ADR` for tech choices.
+- **Next step**: `generate PRD`.
+
+#### `to-prd` (opt-in)
+
+- **When**: after `grill-me`.
+- **Trigger**: `generate PRD`
+- **Output**: `docs/prd/PRD_<feature>.md` (Overview, Goals, User Stories, Functional Requirements, Non-functional, Out of scope).
+- **Next step**: `analyst generates plan` → `PLAN_*.md`.
+
+#### `run-sprint`
+
+- **When**: PLAN approved.
+- **Trigger**: `run sprint 1 of PLAN_<feature>.md`
+- **Output**: sprint executed with `qa-engineer` (failing tests) → `frontend-developer` (3 green files) → `gate-keeper` (senior+ gate).
+- **Next step**: `/impeccable polish` for visual refinement.
+
+#### `auto-test-guard`
+
+- **When**: end of any task; or explicitly when you want to run the suite.
+- **Trigger**: `run tests`
+- **Output**: full senior+ gate (coverage, mutation, jest-axe, Lighthouse, Playwright, pyramid ratio). Blocks if it fails.
+
+#### `api-integration-test`
+
+- **When**: after the sprint, before PRD-ready.
+- **Trigger**: `test integration`
+- **Output**: spins up backend + frontend, runs real `curl` on endpoints, opens Chrome MCP on critical flows, validates clean console.
+
+#### `pair-debug`
+
+- **When**: non-obvious bug (don't "run and see").
+- **Trigger**: `let's debug <X>`
+- **Flow**: hypothesis (with confidence %) → probe → confirm → fix → regression test.
+
+#### `prd-ready-check`
+
+- **When**: before calling a PR "ready for prod".
+- **Trigger**: `is it production ready?`
+- **Output**: GO / NO-GO with listed gaps.
+
+#### `brain-keeper`
+
+- **When**: at the end of each PLAN.
+- **Trigger**: `record in brain`
+- **Output**: `docs/brain/daily/<date>.md`, `docs/brain/features/<feature>.md`, ADRs, MOC updated.
+
+#### `honcho-memory`
+
+- **When**: you want Claude to remember something across sessions.
+- **Trigger**: `remember that <preference>` or commands `/honcho save`, `/honcho list`, `/honcho forget`, `/honcho status`.
+- **Output**: `[HONCHO MEMORY]` block injected into every future prompt.
+
+#### `caveman`
+
+- **When**: already ON by default. You only tune intensity.
+- **Trigger**: `caveman lite/full/ultra` or `stop caveman`.
+- **Effect**: responses ~65-75% shorter.
+
+#### `project-manager` (catch-all)
+
+- **When**: any prompt that doesn't match a specific skill.
+- **Output**: routes to ONE specialist agent via Task tool (`frontend-developer`, `ux-designer`, `qa-engineer`, etc.).
+
+---
+
+## 5. External **Impeccable** skill — visual refinement
+
+> Impeccable does not ship with `development-utility-kit`. It's an independent skill by Paul Bakaus. **For frontend it is highly recommended.**
+
+### Origin
+
+- Author: Paul Bakaus
+- Repo: `github.com/pbakaus/impeccable`
+
+### Installation
+
+```bash
+npx skills add pbakaus/impeccable
+```
+
+Installs as an additional Claude Code skill. The `/impeccable *` commands become available in chat.
+
+### Available commands
+
+| Command | What it does |
+|---|---|
+| `/impeccable polish` | Refines fine details: spacing, alignment, visual hierarchy, microinteractions. |
+| `/impeccable harden` | Hardens visual robustness against edge cases: overflow, long text, RTL, 200% zoom, dark mode. |
+| `/impeccable audit` | Full scan: typography, color, layout, WCAG contrast, hierarchy. Produces report. |
+| `/impeccable typeset` | Refines typography (scale, line-height, tracking, leading). |
+| `/impeccable colorize` | Refines palette and ensures WCAG AA/AAA contrast. |
+| `/impeccable layout` | Reviews hierarchy, spacing, density, grid alignment. |
+
+### When to use
+
+- **After** `frontend-developer` implements a screen.
+- **Before** `prd-ready-check`.
+- In short cycle: `polish` → re-run `jest-axe` → `harden` → re-run Lighthouse → `audit`.
+
+### When **NOT** to use Impeccable
+
+- Before the component is functional (markup needs to be stable).
+- To decide the brand palette → that's `ux-designer` + `product-owner` (ADR-010).
+- As a substitute for `jest-axe` or Lighthouse → complementary, not redundant.
+
+### Authority
+
+`ux-designer` + `product-owner` decide visual identity. **Impeccable is a tool, not an authority.** ADR-010 makes it clear: refinement yes, design decision no.
+
+### Gate
+
+`scripts/impeccable-gate.mjs` runs in **WARN-only** mode. Does not block merge (yet). Runs automatically in the pipeline to record visual drift.
+
+---
+
+## 6. Workflow 1 — Feature from scratch with exact prompts
+
+> Real example: **product list with server-side pagination, full-text search, and full WCAG AA a11y**.
+
+### Turn 1 — Discovery
+
+You:
+
+```text
+grill me on building a product list screen with pagination and search
+```
+
+Claude (`grill-me`):
+
+```text
+> Let's understand. How many products expected in the database?
+> I recommend server-side pagination via NgbPagination + Spring endpoint with
+> Pageable. OK?
+```
+
+### Turn 2
+
+You:
+
+```text
+ok server-side, expect ~50k products
+```
+
+Claude:
+
+```text
+> Search: case-insensitive? Substring or prefix?
+> I recommend PostgreSQL full-text with tsvector + GIN index. database-engineer
+> will model later. OK with you?
+```
+
+### Turn 3
+
+You:
+
+```text
+yes, case-insensitive substring. Filter by category too.
+```
+
+Claude:
+
+```text
+> Category: single dropdown or multi-select? Hierarchical?
+```
+
+### Turn 4
+
+You:
+
+```text
+multi-select, flat (no hierarchy for now)
+```
+
+Claude continues asking about: sorting, list density (table vs cards), mobile-first, empty state, error state, loading skeleton, filter persistence (URL? localStorage?).
+
+### Turn 10 — Discovery closes
+
+Claude:
+
+```text
+> Discovery complete. Persisted to docs/discovery/DISCOVERY_product-list.md.
+> Next step: type "generate PRD" for Claude to turn into a formal PRD.
+```
+
+### Turn 11 — PRD
+
+You:
+
+```text
+generate PRD
+```
+
+Claude (`to-prd`):
+
+```text
+> Created docs/prd/PRD_product-list.md with:
+>   - Overview
+>   - Goals (3)
+>   - User Stories (5)
+>   - Functional Requirements (12)
+>   - Non-functional (a11y AA, LCP <2.5s, mobile-first)
+>   - Out of scope (CSV export, bulk actions)
+> Next: "analyst generates plan".
+```
+
+### Turn 12 — Technical plan
+
+You:
+
+```text
+analyst generates technical plan from PRD_product-list.md
+```
+
+Claude (`analyst`):
+
+```text
+> Created docs/plans/PLAN_product-list.md:
+>   Sprint 1 (4 tasks):
+>     1.1 Backend: GET /api/v1/products?page&size&q&category[]
+>     1.2 DB: GIN index on tsvector + Flyway migration
+>     1.3 Frontend: ProductListComponent (3 files, OnPush, Signal)
+>     1.4 E2E: Playwright flow search + pagination + filter
+>   Goal-ready DoD with measurable criteria.
+```
+
+### Turn 13 — Execute sprint
+
+You:
+
+```text
+run sprint 1 of PLAN_product-list.md
+```
+
+Claude (`run-sprint`):
+
+```text
+> [Task 1.1] backend-developer implements ProductController...
+> [Task 1.2] database-engineer creates V20260527__product_search_index.sql...
+> [Task 1.3] qa-engineer writes product-list.component.spec.ts (red) ✓
+> [Task 1.3] frontend-developer implements 3 files:
+>   - frontend/src/app/features/products/product-list.component.ts
+>   - frontend/src/app/features/products/product-list.component.html
+>   - frontend/src/app/features/products/product-list.component.scss
+> [Task 1.3] gate-keeper runs senior+ gate:
+>   - Jest coverage: 87% statements / 81% branches ✓
+>   - Mutation score (domain): 73% ✓
+>   - jest-axe: 0 critical, 0 serious ✓
+>   - Playwright E2E: 4/4 green ✓
+>   - Lighthouse (median 3 runs): 0.84 ✓
+>     - LCP 2200ms ✓ | CLS 0.05 ✓ | TBT 220ms ✓
+>   - Pyramid: E2E 18% of total ✓
+>   - Initial bundle: 412KB gzip ✓
+>   - GREEN ✓
+> [Task 1.4] E2E complete.
+> Sprint 1 done.
+```
+
+### Turn 14 — Visual refinement
+
+You:
+
+```text
+/impeccable polish
+```
+
+Claude (Impeccable):
+
+```text
+> Polish analysis on ProductListComponent:
+>   1. "Next page" button without legible aria-label ("›" as label)
+>      → added aria-label="Next page"
+>   2. Inconsistent spacing between cards (16px and 20px mixed)
+>      → standardized to var(--spacing-md) (16px)
+>   3. Focus ring missing on internal card links
+>      → outline: 2px solid var(--focus-ring); offset 2px
+>   4. Loading skeleton without reduced animation for prefers-reduced-motion
+>      → media query added
+> Diff applied to 4 files. Recommend re-running jest-axe and Lighthouse.
+```
+
+### Turn 15 — Re-validate
+
+You:
+
+```text
+run jest-axe and lighthouse
+```
+
+Claude:
+
+```text
+> jest-axe: 0 violations ✓
+> Lighthouse: 0.88 (LCP 2100ms, CLS 0.04, TBT 210ms) ✓
+```
+
+### Turn 16 — Smoke test
+
+You:
+
+```text
+test integration
+```
+
+Claude (`api-integration-test`):
+
+```text
+> Spinning up backend (port 8080) + frontend (port 4200)...
+> GET /api/v1/products?page=0&size=20 → 200 (147ms) ✓
+> GET /api/v1/products?q=notebook → 200 (89ms) ✓
+> Chrome MCP opens http://localhost:4200/products
+>   - Search "notebook" → 12 results ✓
+>   - Pagination page 2 → ✓
+>   - Filter category "electronics" → ✓
+>   - Console: 0 errors ✓
+> Smoke GREEN.
+```
+
+### Turn 17 — Final gate
+
+You:
+
+```text
+is it production ready?
+```
+
+Claude (`prd-ready-check`):
+
+```text
+> PRD-ready checklist:
+>   ✓ Backend coverage 87% / branches 82%
+>   ✓ Frontend coverage 88% / branches 83%
+>   ✓ Mutation domain 73%
+>   ✓ A11y 0 critical/serious (component + E2E)
+>   ✓ Lighthouse 0.88 ≥ 0.80
+>   ✓ Pyramid E2E 18% ≤ 30%
+>   ✓ Initial bundle 412KB gzip
+>   ✓ Playwright E2E 4/4
+>   ✓ Clean console in smoke
+>   ✓ ProblemDetail (RFC 9457) on all errors
+>   ✓ No TODO, no any, no inline template/styles
+> GO ✓
+```
+
+### Turn 18 — Record history
+
+You:
+
+```text
+record in brain
+```
+
+Claude (`brain-keeper`):
+
+```text
+> Updated:
+>   - docs/brain/daily/2026-05-27.md
+>   - docs/brain/features/product-list.md
+>   - docs/brain/MOC.md (link added)
+> Next: commit + PR to develop.
+```
+
+### Turn 19 — Commit
+
+You:
+
+```text
+commit and open PR
+```
+
+Claude:
+
+```text
+> Commits created (Conventional Commits, NO AI references):
+>   feat(products): add product list with server-side pagination
+>   feat(products): add full-text search with tsvector
+>   test(products): add jest-axe and Playwright e2e coverage
+>   docs(products): record discovery, PRD and plan
+> PR opened: feature/product-list → develop
+```
+
+Done. Feature from scratch in ~19 conversational turns, without ever opening an IDE to write boilerplate.
+
+---
+
+## 7. Workflow 2 — Refine visuals with Impeccable
+
+Scenario: component already functional, senior+ gate passed, but visuals need care before final PR.
+
+### Recommended cycle: `polish` → `harden` → `audit`
+
+You:
+
+```text
+/impeccable polish
+```
+
+Claude:
+
+```text
+> 7 fine adjustments applied:
+>   - Input spacing unified to var(--spacing-sm)
+>   - Header typography hierarchy (h1 → 1.875rem, h2 → 1.5rem)
+>   - :hover and :focus states with 150ms ease-out transition
+>   - Border-radius standardized to var(--radius-md) (6px)
+>   - Tokenized shadows (--shadow-sm, --shadow-md)
+>   - Icons with consistent height (1em)
+>   - Primary button with 12px 20px padding
+```
+
+You:
+
+```text
+/impeccable harden
+```
+
+Claude:
+
+```text
+> 5 robustness reinforcements:
+>   - Long text: text-overflow ellipsis + title on short columns
+>   - Horizontal overflow on tables: touch scroll + gradient shadow
+>   - RTL support: dir="auto" on text fields, icon mirroring
+>   - 200% zoom: layout intact, no cutoff
+>   - prefers-reduced-motion: animations respected
+```
+
+You:
+
+```text
+/impeccable audit
+```
+
+Claude:
+
+```text
+> Audit report:
+>   Typography: ✓ (1.250 scale, 1.5 line-height in body)
+>   Color: ✓ (15 tokens, no direct hex)
+>   Contrast: ✓ (minimum 4.7:1, AA guaranteed)
+>   Layout: ✓ (12-column grid, breakpoints sm/md/lg/xl)
+>   Hierarchy: ✓ (h1-h4, no h5/h6)
+>   Density: ✓ (compact in tables, comfortable in forms)
+>   Microinteractions: ✓ (consistent transitions)
+> Impeccable score: 9.2/10
+```
+
+### When NOT to use Impeccable
+
+- **Before** the component works: markup must be stable; refining code that will change = waste.
+- **To decide brand palette**: `ux-designer` + `product-owner` decide that. Impeccable refines within already-established tokens.
+- **Replacing jest-axe or Lighthouse**: Impeccable doesn't run screen reader or performance audit. They're complementary.
+
+---
+
+## 8. Workflow 3 — Angular debug with `pair-debug`
+
+Scenario: `ProductListComponent` is `OnPush` and doesn't re-render after `search()` changes.
+
+### Turn 1
+
+You:
+
+```text
+let's debug — ProductListComponent doesn't update after search
+```
+
+Claude (`pair-debug`):
+
+```text
+> Symptom: list doesn't re-render despite signal visibly changing in debug.
+> Hypothesis 1 (confidence 80%): you're mutating the array instead of creating
+>  a new one (this.resources().push() instead of this.resources.set([...])).
+> Probe: grep ".push(" + ".pop(" + "splice(" + ".sort(" in product-list/.
+> Confirm probe?
+```
+
+### Turn 2
+
+You:
+
+```text
+yes
+```
+
+Claude:
+
+```text
+> Found in product-list.service.ts:42:
+>   this.resources().push(item);
+> Hypothesis 1 CONFIRMED.
+> Fix: this.resources.update(arr => [...arr, item]);
+> Dispatching frontend-developer to apply + qa-engineer for regression test.
+```
+
+### Turn 3
+
+You:
+
+```text
+go
+```
+
+Claude:
+
+```text
+> [frontend-developer] Fix applied to product-list.service.ts.
+> [qa-engineer] Regression test add-product-updates-list.spec.ts:
+>   - Before: ❌ red (mutation doesn't trigger CD)
+>   - After: ✓ green (immutable update triggers CD)
+> [gate-keeper] Full suite: GREEN ✓
+```
+
+### Other common hypotheses `pair-debug` raises
+
+- Signal not being read in template (use `()` to call).
+- `ChangeDetectorRef.markForCheck()` missed in external async callback.
+- `trackBy` changing item identity between renders.
+- Child component with non-signal input receiving signal without `.()`.
+
+---
+
+## 9. Workflow 4 — Angular → Mobile conversion
+
+When you need to port an Angular screen to React Native, the `mobile-developer` agent covers it.
+
+```text
+I want to convert ProductListComponent to mobile RN
+```
+
+`project-manager` → `mobile-developer` dispatches conversion preserving domain logic.
+
+Full details in `[Mobile](mobile)`.
+
+---
+
+## 10. Cheat sheet — Intent-based triggers (frontend)
+
+| I want to... | Type |
+|---|---|
+| Start frontend project | `scaffold the frontend` |
+| Feature discovery | `grill me on <X>` |
+| Generate PRD | `generate PRD` |
+| Break into GitHub issues | `break into issues` |
+| Technical plan | `analyst generates technical plan` |
+| Execute sprint | `run sprint <N>` |
+| Run tests / gate | `run tests` |
+| Polish visuals | `/impeccable polish` |
+| Harden visual edge cases | `/impeccable harden` |
+| Full visual audit | `/impeccable audit` |
+| Refine typography | `/impeccable typeset` |
+| Refine palette | `/impeccable colorize` |
+| Review layout/grid | `/impeccable layout` |
+| Smoke E2E backend+frontend | `test integration` |
+| Final gate | `is it production ready?` |
+| Obscure debug | `let's debug <X>` |
+| Wireframe / screen flow | `wireframe for <screen>` |
+| Refactor component | `refactor <ComponentName>` |
+| Standalone a11y audit | `accessibility audit on <feature>` |
+| Macro ADR (signal vs RxJS, etc.) | `architect proposes ADR for <decision>` |
+| Remember preference | `remember that <X>` |
+| List memories | `/honcho list` |
+| Forget | `/honcho forget <id>` |
+| Record history | `record in brain` |
+| Stop caveman | `stop caveman` |
+| Back to caveman | `caveman full` |
+
+---
+
+## 11. Decision tree — Which skill when?
+
+```text
+New project, empty frontend                 → scaffold the frontend
+New feature, scope still fuzzy              → grill me on <X>
+Discovery done, no docs yet                 → generate PRD
+PRD done, no plan                           → analyst generates plan
+Plan done, time to code                     → run sprint <N>
+Component done, visuals raw                 → /impeccable polish
+Visuals polished, robustness missing        → /impeccable harden
+Everything applied, want report             → /impeccable audit
+Obvious bug                                 → frontend-developer (project-manager)
+Obscure bug, no hypothesis                  → let's debug <X>
+Poor performance                            → /impeccable audit + Lighthouse audit
+Refactor legacy                             → refactor <X> (project-manager)
+Mobile from Angular                         → I want to convert <X> to mobile
+A11y before PR                              → accessibility audit
+Before asking for merge                     → is it production ready?
+Post-feature, before leaving                → record in brain
+```
+
+---
+
+## 12. `CLAUDE.md` Project Identity configuration (frontend)
+
+Edit **only** the `Project Identity` section in `CLAUDE.md`:
+
+```markdown
+## Project Identity
+
+- **Project name**: `my-frontend`
+- **Project type**: `frontend`
+- **Primary stack**: `Angular 21`
+- **Frontend stack**: `angular`
+- **Database**: `n/a`
+- **Domain**: `e-commerce`
+- **Team size**: `2 frontend`
+- **Additional rules**:
+```
+
+Vite Vanilla alternative:
+
+```markdown
+- **Frontend stack**: `vite-vanilla`
+```
+
+> Without `Frontend stack`, the `bootstrap-frontend` skill aborts.
+
+---
+
+## 13. Antipatterns
+
+| ❌ Anti | Why it hurts |
+|---|---|
+| Inline `template:` or `styles:` in `@Component` | Hard block. `code-reviewer` / `tech-lead` refuse merge. |
+| Using `any` in TypeScript | Kills type safety. `tsconfig` strict + ESLint block it. |
+| Mutating array inside signal (`signal().push(...)`) | OnPush doesn't detect. Use `update(arr => [...arr, item])`. |
+| Forgetting `ChangeDetectionStrategy.OnPush` | Performance degrades exponentially in large trees. |
+| HttpClient without typed error interceptor | Errors become `any`, ProblemDetail lost. |
+| Component without `data-testid` on interactive elements | Playwright becomes fragile with CSS selectors. |
+| Commit with `Co-Authored-By: Claude` | Hard block. NEVER mention AI/Claude/Anthropic in commits. |
+| Trying `duk project-manager "X"` | Doesn't exist. Skills are keyword, not CLI. |
+| Running `to-prd` without `grill-me` first | `analyst` refuses input without `DISCOVERY_*.md`. |
+| Skipping `gate-keeper` "because in a hurry" | Gate is non-negotiable. |
+| Mixing Reactive Forms and Signal Forms | Pick one model per feature; preference: Signal Forms. |
+| `any` in HttpClient response | Use `HttpClient.get<Resource>(...)` always typed. |
+| Giant "smart" components (>200 lines TS) | Split into sub-components or facade service. |
+| Forgetting `@if` / `@for` (new template syntax) | Angular 21 uses new control flow; `*ngIf` is legacy. |
+| Lazy loading only on root route | Lazy on features too — bundle splitting. |
+| `console.log` left in code | ESLint blocks. Use injectable `LoggerService`. |
+
+---
+
+## 14. Frontend-specific troubleshooting
+
+### HMR not updating after edit
+
+- Kill the server (`Ctrl+C`) and restart with `ng serve`.
+- Verify you edited the correct `.ts`/`.html`/`.scss` file (no cache).
+- Lower `--poll` if you're on WSL/mounted volume.
+
+### "Stale" signal in template
+
+- Confirm you're calling `()`: `{{ products() }}` not `{{ products }}`.
+- For external async callback (non-Angular), wrap in `NgZone.run()` or inject `ChangeDetectorRef`.
+
+### `ChangeDetectorRef.markForCheck()` needed?
+
+- In 99% of Signal cases, **no**. Signals already notify.
+- Only needed when the trigger comes from outside the zone (e.g., native WebSocket, `setTimeout` in external libs, SDK callback).
+
+### Initial bundle > 500KB
+
+- Audit with `ng build --stats-json` + `webpack-bundle-analyzer`.
+- Lazy loading on feature routes.
+- Tree-shake imports (`import { x } from 'lib'` not `import 'lib'`).
+- Move heavy libs (charts, editor) into lazy chunks.
+
+### Playwright E2E timeout
+
+- Increase timeout only on flows with real external calls.
+- Prefer `page.waitForLoadState('networkidle')` over `waitForTimeout`.
+- Use `data-testid` instead of fragile CSS/XPath selectors.
+
+### `bootstrap-frontend` doesn't trigger
+
+- `CLAUDE.md` without `Frontend stack`. Add `Frontend stack: angular`.
+- Cowork/Claude Code must be at project root.
+- Confirm `duk install` ran without error.
+
+### `jest-axe` fails on "color-contrast"
+
+- You have direct hex in SCSS? Move to token.
+- Check contrast on `var(--text-primary)` vs `var(--surface-base)`.
+- Minimum AA = 4.5:1 (normal text), 3:1 (large text).
+
+### Lighthouse score < 0.80
+
+- High LCP → preload critical, optimize hero image, server push.
+- High CLS → reserve space (`aspect-ratio`, `width`/`height` on img).
+- High TBT → split chunks, defer scripts, web worker for CPU.
+- Heavy bundle → aggressive lazy loading.
+
+### Pyramid ratio E2E > 30%
+
+- Testing business rules in E2E? Move to Jest unit.
+- E2E should test **flow**, not **logic**.
+- Mock API in Jest, leave E2E only for critical end-to-end flows.
+
+### `duk dashboard` doesn't open
+
+- Port 4242 in use? `duk dashboard --port 5252`.
+- Firewall blocking localhost? Allow Node.
+- Logs in `~/.duk/dashboard.log`.
+
+### Skills don't trigger (general)
+
+- Check Cowork/Claude Code has `.claude/skills/` loaded.
+- Restart the session.
+- Confirm exact keyword — `scaffold the front` ≠ `scaffold the frontend`.
+
+---
+
+## 15. Honcho memory in practice (frontend)
+
+Honcho injects a `[HONCHO MEMORY]` block into every prompt. Useful frontend preferences to record:
+
+```text
+remember that I always use 3 separate files in Angular components
+```
+
+```text
+remember that I prefer Signal Forms over Reactive Forms
+```
+
+```text
+remember that I never use any in TypeScript
+```
+
+```text
+remember that every interactive element needs data-testid
+```
+
+```text
+remember that I prefer OnPush + Signal in every new component
+```
+
+```text
+remember that brand palette is #1a73e8 primary, #0f5fc7 hover, #e8f0fe surface
+```
+
+```text
+remember mobile-first on all breakpoints
+```
+
+Direct commands:
+
+```text
+/honcho save always commit with Conventional Commits
+/honcho list
+/honcho forget abc123
+/honcho status
+/honcho setup
+```
+
+Details: `[Honcho memory](../docs/honcho-memory)`.
+
+---
+
+## 16. Active hooks
+
+The harness installs Git hooks that run automatically:
+
+- `pre-commit`: lint, formatting, type check, jest-axe smoke
+- `commit-msg`: validates Conventional Commits + blocks AI/Claude mentions
+- `pre-push`: runs full unit suite
+- `post-merge`: suggests `duk install` if `.claude/` changed
+
+Full reference: `[Hooks reference](../docs/hooks-reference)`.
+
+---
+
+## 17. Quick glossary
+
+| Term | Definition |
+|---|---|
+| **Skill** | Harness entry layer. Triggers by keyword in chat. |
+| **Agent** | Specialist executor. Invoked by skill via Task tool. |
+| **Task tool** | Claude mechanism to invoke sub-agent in parallel/sequence. |
+| **PLAN** | `docs/plans/PLAN_*.md` — technical plan with sprints and DoD. |
+| **PRD** | `docs/prd/PRD_*.md` — Product Requirements Document. |
+| **DISCOVERY** | `docs/discovery/DISCOVERY_*.md` — `grill-me` output. |
+| **ADR** | Architecture Decision Record. Macro architectural decisions. |
+| **Goal-ready DoD** | Definition of Done with measurable criteria (not vague). |
+| **Senior+ gate** | Set of non-negotiable thresholds (coverage, mutation, a11y, Lighthouse, pyramid). |
+| **Signal** | Angular 21 reactive primitive (`signal()`, `computed()`, `effect()`). |
+| **OnPush** | Change detection strategy that only updates on input/signal change. |
+| **Standalone** | Component without NgModule. Default in Angular 21. |
+| **ng-bootstrap** | UI lib (modal, datepicker, pagination, etc.). Harness default. |
+| **Impeccable** | External visual refinement skill (Paul Bakaus). |
+| **jest-axe** | Jest plugin that runs axe-core for a11y in component tests. |
+| **Lighthouse** | Automated performance/a11y/best-practices/SEO audit. |
+| **Honcho** | Cross-session persistent memory system (v3 self-hosted). |
+| **Caveman** | Telegraphic response mode (default ON, ~65-75% fewer tokens). |
+| **Pyramid ratio** | % of E2E vs total tests. Limit: ≤30%, ideal ≤15%. |
+
+---
+
+## 18. Cross-references
+
+- `[Architecture](../docs/architecture-overview)` — harness macro view
+- `[Agents reference](../docs/agents-reference)` — full agent list
+- `[Skills reference](../docs/skills-reference)` — full skill list
+- `[Pipeline](../docs/pipeline)` — PO → analyst → architect → run-sprint → gate-keeper flow
+- `[Quality gate](../docs/quality-gate)` — detailed senior+ thresholds
+- `[Stack rules](../docs/stack-rules)` — Angular/Spring/etc. conventions
+- `[Hooks reference](../docs/hooks-reference)` — active Git hooks
+- `[Honcho memory](../docs/honcho-memory)` — cross-session memory
+- `[Git Flow](../docs/git-flow)` — standard Git flow
+- `[Troubleshooting](../docs/troubleshooting)` — general common issues
+- `[Backend](backend)` — Spring Boot backend manual
+- `[Fullstack](fullstack)` — monorepo manual
+- `[Mobile](mobile)` — React Native manual
+- `[Existing project](existing-project)` — legacy adoption