@eltonssouza/development-utility-kit 0.10.0

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

@@ -0,0 +1,1459 @@
+# User Manual — Fullstack (Java 25 + Spring Boot 4 + Angular 21)
+
+Definitive edition. This manual covers the full lifecycle of a fullstack
+project under the `development-utility-kit` harness: Spring Boot 4 backend,
+Angular 21 frontend, monorepo, `docker-compose`, shared contracts via
+OpenAPI, and the end-to-end workflow with Claude Code / Cowork skills and
+agents.
+
+---
+
+## 1. Introduction
+
+This manual targets **fullstack** developers building, evolving, or adopting
+a project with:
+
+- **Java 25 + Spring Boot 4** backend (Maven, JPA, Flyway, Testcontainers).
+- **Angular 21** frontend (standalone, Signals, OnPush, Signal Forms,
+  `ng-bootstrap`).
+- **PostgreSQL 17** + **Redis 7** via `docker-compose`.
+- Shared types via `openapi-typescript` (generated from `/v3/api-docs`).
+- Workflow driven by Cowork / Claude Code agents (analyst, architect,
+  backend-developer, frontend-developer, qa-engineer, gate-keeper,
+  tech-lead, etc.).
+
+### Prerequisites
+
+- **JDK 25** on PATH (`java --version`).
+- **Node.js 22+** and **npm 10+** (`node --version`).
+- **Docker Desktop** or Docker Engine 25+ with Compose v2.
+- **Git** on PATH.
+- **Claude Code** (CLI) or **Cowork** (conversational mode).
+- Optional: **VS Code** or **IntelliJ IDEA** Ultimate.
+
+If you have never used the harness, also read:
+
+- [Quick onboarding](../docs/architecture-overview)
+- [Stack rules](../docs/stack-rules)
+- [Skills reference](../docs/skills-reference)
+- [Agents reference](../docs/agents-reference)
+
+---
+
+## 2. 5-minute onboarding
+
+```bash
+cd C:\development\source\projects
+
+# Create the project via interactive wrapper (Windows):
+C:\development\tools\development-utility-kit\scripts\new-project.bat
+
+# OR Git Bash / WSL / Mac / Linux:
+bash /c/development/tools/development-utility-kit/scripts/new-project.sh
+```
+
+The wrapper opens a wizard asking for:
+
+- **Project name**: `my-fullstack`
+- **Project type**: `Fullstack`
+- **Primary stack**: accept the default (Java 25 + Spring Boot 4 + Angular 21)
+- **Database**: accept `PostgreSQL 17 + Redis 7`
+
+The wrapper:
+
+1. Creates `C:\development\source\projects\my-fullstack\`.
+2. Injects `.claude/` (agents + skills + settings + hooks) and `CLAUDE.md`.
+3. Fills the `Project Identity` block of `CLAUDE.md`.
+4. Opens Claude Code / Cowork pointing at the new folder.
+
+Then, in chat:
+
+```text
+> "scaffold the monorepo"
+```
+
+The `bootstrap-fullstack` skill creates:
+
+- `backend/` — Spring Initializr (Maven, Java 25, Spring Boot 4).
+- `frontend/` — Angular 21 standalone + `ng-bootstrap`.
+- `docker-compose.yml` with Postgres + Redis + Mailhog.
+- Healthchecks, env-scoped CORS, `openapi-typescript` wired in the frontend.
+
+Bring up the local environment:
+
+```bash
+docker compose up -d
+# Services:
+#   postgres :5432   (db: myfullstack, user: app)
+#   redis    :6379
+#   mailhog  :8025   (UI), :1025 (SMTP)
+#   backend  :8080
+#   frontend :4200
+```
+
+Health check:
+
+```bash
+curl http://localhost:8080/api/v1/health
+# {"status":"UP","components":{"db":"UP","redis":"UP"}}
+
+curl http://localhost:8080/v3/api-docs
+# OpenAPI 3.1 spec
+
+# Browser:
+#   http://localhost:4200    → Angular app
+#   http://localhost:8080/swagger-ui.html → OpenAPI UI
+#   http://localhost:8025    → Mailhog
+```
+
+Optional — docs dashboard:
+
+```bash
+duk dashboard          # opens http://localhost:4242
+# duk dashboard --port 4243 --no-open   # variants
+```
+
+---
+
+## 3. Monorepo architecture
+
+```
+my-fullstack/
+├── backend/                              ← Spring Boot 4 (Maven)
+│   ├── src/main/java/com/company/myfullstack/
+│   │   ├── domain/                       ← model, ports (repository interfaces)
+│   │   │   ├── product/
+│   │   │   │   ├── Product.java
+│   │   │   │   └── ProductRepository.java
+│   │   │   └── shared/
+│   │   ├── application/                  ← use cases + DTO records + mappers
+│   │   │   └── product/
+│   │   │       ├── CreateProductUseCase.java
+│   │   │       ├── CreateProductRequest.java   (record)
+│   │   │       └── ProductResponse.java        (record)
+│   │   ├── infrastructure/               ← JPA adapters, security, config
+│   │   │   ├── persistence/jpa/
+│   │   │   ├── security/
+│   │   │   ├── messaging/
+│   │   │   └── config/
+│   │   └── web/                          ← controllers + @ControllerAdvice
+│   │       ├── ProductController.java
+│   │       └── GlobalExceptionHandler.java
+│   ├── src/main/resources/
+│   │   ├── db/migration/V1__init.sql
+│   │   ├── application.yml
+│   │   └── application-prod.yml
+│   ├── src/test/java/...                 ← JUnit 5 + Mockito + Testcontainers
+│   ├── pom.xml
+│   └── Dockerfile
+├── frontend/                             ← Angular 21
+│   ├── src/app/
+│   │   ├── core/                         ← auth, http interceptors, guards
+│   │   │   ├── auth/
+│   │   │   └── http/
+│   │   ├── shared/                       ← reusable components, pipes
+│   │   │   └── ui/
+│   │   └── features/                     ← lazy modules
+│   │       └── products/
+│   │           ├── product-list/
+│   │           │   ├── product-list.component.ts
+│   │           │   ├── product-list.component.html
+│   │           │   └── product-list.component.scss
+│   │           └── product-create/
+│   ├── src/api/types.ts                  ← generated by openapi-typescript
+│   ├── src/environments/
+│   ├── angular.json
+│   ├── package.json
+│   └── Dockerfile
+├── docker-compose.yml                    ← local env (postgres + redis + back + front)
+├── docker-compose.prod.yml               ← optional, for staging
+├── docs/
+│   ├── discovery/                        ← DISCOVERY_*.md  (grill-me skill)
+│   ├── prd/                              ← PRD_*.md         (to-prd skill)
+│   ├── issues/                           ← ISSUES_*.md      (to-issues skill)
+│   ├── plans/                            ← PLAN_*.md        (analyst agent)
+│   ├── decisions/                        ← ADR-NNN-<slug>.md (architect/tech-lead)
+│   └── brain/                            ← Obsidian vault   (brain-keeper agent)
+│       ├── daily/
+│       ├── features/
+│       ├── bugs/
+│       ├── decisions/
+│       └── architecture/tech-debt.md
+├── .claude/                              ← harness config
+│   ├── agents/                           ← 25 agents
+│   ├── skills/                           ← 18 skills
+│   ├── hooks/                            ← PreToolUse, PostToolUse, etc.
+│   └── settings.json
+├── CLAUDE.md                             ← Project Identity + inherited rules
+└── README.md
+```
+
+The two sub-projects (`backend/` and `frontend/`) are **independent** at
+build time but **coupled by contract** (OpenAPI). You run `mvn` in
+`backend/` and `npm` in `frontend/`. `docker-compose.yml` orchestrates both.
+
+---
+
+## 4. CLAUDE.md — Project Identity
+
+After scaffolding, edit **only** the `Project Identity` section of
+`CLAUDE.md`. Everything else is inherited from the template and updated via
+the `update-template` skill.
+
+```markdown
+## Project Identity
+
+- **Project name**: `my-fullstack`
+- **Project type**: `fullstack`
+- **Primary stack**: `Java 25 + Spring Boot 4 + Angular 21`
+- **Database**: `PostgreSQL 17 + Redis 7`
+- **Domain**: `e-commerce`
+- **Team size**: `3 backend, 2 frontend`
+- **Additional rules**:
+```
+
+Important fields:
+
+- `Project type: fullstack` — enables `bootstrap-fullstack`,
+  `api-integration-test`, and the combined gate (JaCoCo + PIT + Jest +
+  Lighthouse).
+- `Primary stack` — steers agents to Java 25 / Spring 4 (not 17 / 3.x) and
+  Angular 21 (not 17).
+- `Database` — used by `database-engineer` to pick migrations, indexes, and
+  types (UUID, TIMESTAMPTZ, NUMERIC).
+
+---
+
+## 5. Skills that apply to fullstack
+
+Skills fire by **keyword in chat**. There is no `duk <skill>`. Everything is
+conversational.
+
+| Skill | EN trigger | Output |
+|---|---|---|
+| `bootstrap-fullstack` | `scaffold the monorepo`, `create fullstack`, `set up backend and frontend` | `backend/` + `frontend/` + `docker-compose.yml` |
+| `grill-me` | `grill me about <X>`, `interview me about <X>`, `stress-test the plan` | `docs/discovery/DISCOVERY_<X>.md` |
+| `to-prd` | `generate PRD`, `create PRD` | `docs/prd/PRD_<X>.md` |
+| `to-issues` | `break into issues` | `docs/issues/ISSUES_<X>.md` |
+| `run-sprint` | `run sprint <N> of PLAN_<X>.md` | Sprint executed by `sprint-runner` |
+| `auto-test-guard` | `run the tests`, `generate tests`, `full suite` | Senior+ gate green |
+| `api-integration-test` | `test the integration` | curl + Chrome MCP across back+front |
+| `prd-ready-check` | `is it production-ready?`, `DoD` | GO / NO-GO |
+| `pair-debug` | `let's debug <X>`, `investigate this bug` | Hypothesis loop |
+| `brain-keeper` | `record in brain`, `update the brain` | `docs/brain/` vault |
+| `active-project` | `/active-project <path>`, `adopt project at <path>` | Non-interactive adoption |
+| `update-template` | `update the template` | Sync `.claude/` + `CLAUDE.md` (merge) |
+| `project-manager` | catch-all | Routes to 1 agent |
+
+### 5.1. `bootstrap-fullstack`
+
+Run **once**, up front. Reads `Project Identity` and creates backend +
+frontend + `docker-compose.yml`. Output:
+
+- `backend/` with Maven package, `application.yml`, `Dockerfile`, migration
+  `V1__init.sql`, `/api/v1/health` endpoint.
+- `frontend/` with Angular 21 standalone, `ng-bootstrap`, error
+  interceptor, placeholder auth guard, `openapi-typescript` wired in.
+- `docker-compose.yml` with postgres + redis + mailhog + back + front.
+
+Prerequisite: `Project type: fullstack` in `CLAUDE.md`.
+
+### 5.2. `grill-me`
+
+Hypothesis-by-hypothesis discovery interview before writing a single line of
+code. Covers persona, business rule, flow, auth, perf, error, audit, LGPD,
+observability. Persists to `docs/discovery/DISCOVERY_<slug>.md` (PLAN seed —
+see ADR-013).
+
+Always use before `to-prd` on the human path (autonomous path via
+`sprint-runner` is exempt).
+
+### 5.3. `to-prd`
+
+Reads the discovery and produces `docs/prd/PRD_<slug>.md` with Overview,
+Goals, User Stories, Functional Requirements, Non-functional Requirements,
+and Out of Scope.
+
+### 5.4. `to-issues`
+
+Reads the PRD and breaks it into `[ISSUE-N]` blocks ready for
+`gh issue create`.
+
+### 5.5. `run-sprint`
+
+`sprint-runner` executes Sprint N of `PLAN_<X>.md`, delegating in parallel
+to `database-engineer`, `backend-developer`, `frontend-developer`,
+`qa-engineer`. At the end, `gate-keeper` runs the senior+ gate.
+
+### 5.6. `auto-test-guard`
+
+Runs the full gate: JaCoCo, PIT, SpotBugs, OWASP DC, Jest, jest-axe,
+`@axe-core/playwright`, Lighthouse CI, pyramid ratio. Blocks merge if any
+threshold fails. See [quality-gate](../docs/quality-gate).
+
+### 5.7. `api-integration-test`
+
+Brings up back + front via `docker compose up` (or reuses what is already
+running) and:
+
+- Tests endpoints with `curl` (auth, CRUD, pagination, 422 error, 401 error).
+- Opens the frontend via Chrome MCP and walks the critical flow.
+- Validates the browser console (0 errors).
+- Validates CORS, security headers, redirects.
+
+### 5.8. `prd-ready-check`
+
+Go / No-Go for production. Runs:
+
+- `./mvnw clean verify` on the backend.
+- `npm test` + `npm run lint` + `npm audit --audit-level=high` on the frontend.
+- `./mvnw package -DskipTests=false`.
+- `ng build --configuration=production`.
+- Playwright E2E.
+- Lighthouse CI (median of 3 runs).
+- `test-coverage-auditor` as a sub-gate.
+
+If any P0/P1 fails → NO-GO with the list.
+
+### 5.9. `pair-debug`
+
+Hypothesis-by-hypothesis loop. Each hypothesis has evidence + test. No
+"try and see".
+
+### 5.10. `brain-keeper`
+
+Provisions / updates `docs/brain/`:
+
+- `daily/2026-05-27.md`
+- `features/<slug>.md`
+- `decisions/ADR-NNN-<slug>.md`
+- `bugs/<id>-<slug>.md`
+- `architecture/tech-debt.md`
+
+All in Obsidian (vault) format, with `[[wiki]]` links, `#feature`, `#bug`,
+`#adr` tags, and a MOC (Map of Content) per area.
+
+### 5.11. `active-project`
+
+Non-interactive adoption of a legacy project:
+
+```text
+> "/active-project C:\projects\legacy-fullstack"
+```
+
+Equivalent to the fast lane of `update-template` when you want to skip the
+wizard.
+
+### 5.12. `update-template`
+
+Syncs `.claude/` + `CLAUDE.md` with the latest harness release. The merge
+preserves the project's `Project Identity` section; everything else is
+overwritten. A backup is created (`CLAUDE.md.bak-<timestamp>`).
+
+### 5.13. `project-manager`
+
+Catch-all. Any prompt without a specific skill falls here and is routed to
+**one** agent.
+
+### 5.15. Impeccable — visual polish
+
+`Impeccable` is an external command pack focused on **visual and
+typographic polish**. Especially relevant on the frontend side of a
+fullstack project.
+
+**Install** (once per project):
+
+```bash
+npx skills add pbakaus/impeccable
+```
+
+**Available commands**:
+
+| Command | What it does | When to use |
+|---|---|---|
+| `/impeccable polish` | Applies targeted tweaks (spacing, alignment, hierarchy, focus ring) | After finishing a screen, before PR |
+| `/impeccable harden` | Hardens visual edge cases (overflow, RTL, dark mode) | Before production |
+| `/impeccable audit` | Full visual audit (typography, color, layout, density) | Monthly or before release |
+| `/impeccable typeset` | Refines type scale and leading | When text feels "dense" |
+| `/impeccable colorize` | Adjusts palette for WCAG AA contrast | After theme change |
+| `/impeccable layout` | Reflows grid, hierarchy, breakpoints | When layout needs traction |
+
+These commands complement the senior+ gate: the gate enforces the
+**technical** floor (coverage, mutation, baseline a11y), Impeccable
+enforces the **visual finish**.
+
+---
+
+## 6. End-to-end feature workflow (with prompts)
+
+Real example: implement **product creation** with:
+
+- Backend: `POST /api/v1/products` with validation, persistence,
+  `ROLE_ADMIN` auth.
+- Frontend: `/products/new` screen with Signal Forms, API integration,
+  redirect to listing.
+- Shared contract via `openapi-typescript`.
+
+### Turn 1 — you
+
+```text
+grill me about product creation: name, price, stock, category
+```
+
+### Turn 1 — Claude (`grill-me` skill)
+
+```text
+Let's get clear. Question 1/N:
+
+Is auth required to create? I'd recommend @PreAuthorize ROLE_ADMIN,
+returning 403 without a valid token. Confirm?
+```
+
+### Turns 2–20 — iterative interview
+
+Covers: persona (catalog admin), validation rules (price > 0, stock >= 0,
+unique name per category), error behavior (RFC 9457 ProblemDetail),
+performance (synchronous create, < 200ms p95), audit (audit log), LGPD
+(product is not personal data — N/A), observability (structured log +
+`products.created` metric).
+
+### Turn 21 — Claude
+
+```text
+Discovery complete. Saved to docs/discovery/DISCOVERY_product-create.md.
+Suggested next step: "generate PRD".
+```
+
+### Turn 22 — you
+
+```text
+generate PRD
+```
+
+### Turn 22 — Claude (`to-prd` skill)
+
+```text
+docs/prd/PRD_product-create.md created with:
+  - Overview, Goals
+  - 3 User Stories
+  - 7 Functional Requirements
+  - 4 Non-functional Requirements (perf, security, observability, a11y)
+  - Out of Scope (bulk import, variants)
+```
+
+### Turn 23 — you
+
+```text
+break into issues
+```
+
+### Turn 23 — Claude (`to-issues` skill)
+
+```text
+docs/issues/ISSUES_product-create.md with 4 issues:
+  [ISSUE-1] DB: products schema + category index
+  [ISSUE-2] Backend: POST /api/v1/products + validation + auth
+  [ISSUE-3] Frontend: /products/new screen (Signal Forms)
+  [ISSUE-4] Integration: openapi-typescript + smoke E2E
+
+Ready for:
+  gh issue create --title "[ISSUE-N] ..." --body-file <block>
+```
+
+### Turn 24 — you
+
+```text
+analyst, generate the plan
+```
+
+### Turn 24 — Claude (`analyst` agent)
+
+```text
+docs/plans/PLAN_product-create.md:
+
+  Sprint 1 — Backend
+    Task 1.1 database-engineer: V2__create_products.sql
+    Task 1.2 backend-developer: domain + application + web
+    Task 1.3 qa-engineer: integration test (Testcontainers)
+    Task 1.4 gate-keeper: JaCoCo + PIT + SpotBugs + OWASP
+
+  Sprint 2 — Frontend
+    Task 2.1 frontend-developer: ProductCreateComponent (3 files)
+    Task 2.2 frontend-developer: ProductService + interceptor
+    Task 2.3 qa-engineer: Jest + jest-axe + Playwright
+    Task 2.4 gate-keeper: coverage + Lighthouse
+
+  Sprint 3 — Integration
+    Task 3.1 devops-engineer: CORS, docker-compose
+    Task 3.2 frontend-developer: regenerate types via openapi-typescript
+    Task 3.3 sprint-runner -> api-integration-test (curl + Chrome MCP)
+
+Goal-ready DoD on every task.
+```
+
+### Turn 25 — you
+
+```text
+run sprint 1 of PLAN_product-create.md
+```
+
+### Turn 25 — Claude (`run-sprint` skill)
+
+```text
+Sprint 1 — parallel execution:
+
+  [Task 1.1] database-engineer:
+    - V2__create_products.sql (UUID PK, TIMESTAMPTZ, NUMERIC(10,2))
+    - idx_products_category (B-tree)
+    - idx_products_name_category_unique (unique partial)
+
+  [Task 1.2] backend-developer (3 parallel):
+    - domain/product/Product.java + ProductRepository.java (port)
+    - application/product/CreateProductUseCase.java + records
+    - infrastructure/persistence/jpa/ProductJpaAdapter.java
+    - web/ProductController.java + @PreAuthorize("hasRole('ADMIN')")
+    - web/GlobalExceptionHandler.java (RFC 9457 ProblemDetail)
+
+  [Task 1.3] qa-engineer:
+    - ProductControllerIT.java (Testcontainers + Postgres)
+    - CreateProductUseCaseTest.java (unit, Mockito)
+
+  [Task 1.4] gate-keeper:
+    - JaCoCo: 88% lines / 82% branches ✓
+    - PIT mutation: 72% in domain/ + application/ ✓
+    - SpotBugs: 0 CRITICAL, 0 HIGH ✓
+    - OWASP DC: 0 CVE with CVSS >= 7.0 ✓
+
+Sprint 1 GREEN ✓
+```
+
+### Turn 26 — you
+
+```text
+run sprint 2
+```
+
+### Turn 26 — Claude (`run-sprint` skill)
+
+```text
+Sprint 2 — parallel execution:
+
+  [Task 2.1] frontend-developer:
+    ProductCreateComponent in 3 physical files (non-negotiable):
+      - product-create.component.ts (standalone, OnPush, Signal Forms)
+      - product-create.component.html (form + ng-bootstrap)
+      - product-create.component.scss
+
+  [Task 2.2] frontend-developer:
+    - core/api/product.service.ts (typed HttpClient)
+    - core/http/error.interceptor.ts (ProblemDetail handler)
+
+  [Task 2.3] qa-engineer:
+    - product-create.component.spec.ts (Jest + Testing Library)
+    - product-create.a11y.spec.ts (jest-axe — 0 serious/critical)
+    - e2e/products/create.spec.ts (Playwright)
+
+  [Task 2.4] gate-keeper:
+    - Jest: 86% statements / 81% branches ✓
+    - jest-axe: 0 violations ✓
+    - @axe-core/playwright: 0 violations ✓
+    - Playwright E2E: 100% green, console 0 errors ✓
+    - Lighthouse: 0.85 perf / LCP 1800ms / CLS 0.05 / TBT 220ms ✓
+    - E2E pyramid ratio: 18% (<= 30% hard-fail; <= 15% ideal) ✓
+
+Sprint 2 GREEN ✓
+```
+
+### Turn 27 — you
+
+```text
+/impeccable polish
+```
+
+### Turn 27 — Claude (Impeccable)
+
+```text
+Polish applied to ProductCreateComponent:
+  - Label alignment (top-aligned, 4px margin-bottom)
+  - Inline error spacing (4px, --bs-danger color)
+  - Consistent focus ring (2px outline, --bs-primary)
+  - Buttons with subtle hover lift (translateY(-1px))
+  - 12-col grid, 16px gutter
+```
+
+### Turn 28 — you
+
+```text
+run sprint 3
+```
+
+### Turn 28 — Claude (`run-sprint` + `api-integration-test`)
+
+```text
+Sprint 3 — execution:
+
+  [Task 3.1] devops-engineer:
+    - docker-compose.yml: backend service with CORS for http://localhost:4200
+    - application-dev.yml: cors.allowed-origins
+    - Rate limit configured (Bucket4j 100 req/min)
+
+  [Task 3.2] frontend-developer:
+    - npm run gen:api → src/api/types.ts regenerated
+    - product.service.ts typed via components["schemas"]["ProductResponse"]
+
+  [Task 3.3] api-integration-test:
+    Bringing up docker compose up -d...
+    Backend UP on :8080, Frontend UP on :4200.
+
+    curl tests:
+      POST /api/v1/products (Bearer admin) → 201 ✓
+        Location: /api/v1/products/<uuid>
+        body: { id, name, price, stock, category, createdAt }
+      POST /api/v1/products (no token) → 401 ✓
+      POST /api/v1/products (negative price) → 422 ✓
+        ProblemDetail: type, title, status, detail, errors[]
+      GET /api/v1/products → 200, pagination OK ✓
+
+    Chrome MCP:
+      http://localhost:4200/products/new
+      fill form (name, price, stock, category)
+      submit → redirect to /products
+      assertion: product appears in listing ✓
+      console: 0 errors ✓
+      a11y: 0 violations ✓
+
+Sprint 3 GREEN ✓
+```
+
+### Turn 29 — you
+
+```text
+is it production-ready?
+```
+
+### Turn 29 — Claude (`prd-ready-check` skill)
+
+```text
+Running:
+  - ./mvnw clean verify (backend)
+  - npm test + npm run lint (frontend)
+  - npm audit --audit-level=high
+  - ./mvnw package
+  - ng build --configuration=production
+  - playwright test
+  - lhci autorun
+  - test-coverage-auditor (sub-gate)
+
+Result:
+  Backend coverage:    88% / 82%   ✓
+  Backend mutation:    72%         ✓
+  Frontend coverage:   86% / 81%   ✓
+  SpotBugs:            0 / 0       ✓
+  OWASP:               0 high      ✓
+  npm audit:           0 high      ✓
+  Playwright:          12/12 green ✓
+  jest-axe:            0           ✓
+  @axe-core/playwright:0           ✓
+  Lighthouse perf:     0.86        ✓
+  LCP / CLS / TBT:     OK          ✓
+  E2E pyramid ratio:   18%         ✓
+  P0/P1 issues:        0           ✓
+
+GO ✓
+```
+
+### Turn 30 — you
+
+```text
+record in brain
+```
+
+### Turn 30 — Claude (`brain-keeper` agent)
+
+```text
+Vault updated:
+  docs/brain/daily/2026-05-27.md        (timeline for the day)
+  docs/brain/features/product-create.md (feature card)
+  docs/brain/decisions/ADR-043-products-tsvector-search.md (search decision)
+  docs/brain/architecture/tech-debt.md  (added: move to event sourcing
+                                         if we cross 100 products/s)
+
+Wiki links: [[product]], [[catalog]], [[admin]]
+Tags: #feature #backend #frontend #shipped
+```
+
+---
+
+## 7. Workflow 2 — Production bug (pair-debug)
+
+Scenario: intermittent 500 in production, only for `*.partner.com` subdomain
+users when saving a product.
+
+### Turn 1 — you
+
+```text
+let's debug: 500 on product create, only from partner.com subdomain.
+log: "CorsConfigurationException: origin not allowed"
+```
+
+### Turn 1 — Claude (`pair-debug` skill)
+
+```text
+Hypothesis 1: CORS allowed-origins does not include subdomain wildcard.
+Expected evidence: application-prod.yml with a finite list.
+Test: read application-prod.yml + grep allowed-origins.
+
+Running...
+```
+
+### Turn 2 — Claude
+
+```text
+Confirmed. application-prod.yml:
+  cors.allowed-origins:
+    - https://app.partner.com
+Missing wildcard pattern.
+
+Hypothesis 2 (discarded): Spring Boot 4 changed the default — no, a CORS
+contract regression is an explicit responsibility.
+
+Plan:
+  1. Backend: swap allowed-origins for allowed-origin-patterns:
+     - https://*.partner.com
+  2. Backend: integration test reproducing the case (Origin header from
+     unexpected subdomain).
+  3. Frontend: verify axios/HttpClient is not sending a custom Origin.
+
+Apply?
+```
+
+### Turn 3 — you
+
+```text
+go ahead
+```
+
+### Turn 3 — Claude (delegating)
+
+```text
+backend-developer:
+  - Diff applied in CorsConfig.java
+  - allowed-origin-patterns: [https://*.partner.com, https://app.company.com]
+
+qa-engineer:
+  - CorsConfigIT.java reproduces: Origin: https://x.partner.com → 200 OK
+  - CorsConfigIT.java reproduces: Origin: https://evil.com → 403
+
+gate-keeper:
+  - Suite green ✓
+
+api-integration-test:
+  - Bringing up back + front locally
+  - curl with Origin: https://test.partner.com → 201 ✓
+
+Suggested commit:
+  fix(security): allow subdomain wildcard for partner.com in CORS
+
+  Resolves 500 in production for dynamic-subdomain users.
+  Replaces allowed-origins with allowed-origin-patterns.
+```
+
+---
+
+## 8. Workflow 3 — Visual polish with Impeccable
+
+Scenario: product listing screen works but "looks off".
+
+### Turn 1 — you
+
+```text
+/impeccable audit
+```
+
+### Turn 1 — Claude
+
+```text
+Full visual audit on ProductListComponent:
+
+  Typography:
+    Consistent scale (1rem base, ratio 1.25)     ✓
+    Leading 1.5 (body), 1.2 (heading)            ✓
+
+  Color:
+    WCAG AA contrast (4.5:1 body, 3:1 large)     ✓
+    Consistent palette (--bs-*)                  ✓
+
+  Layout:
+    12-col grid                                  ✓
+    "product" card needs 8px vertical gap        ✗
+    Uneven section spacing                       ✗
+
+  Density:
+    Card inner padding: 12/16/20 mixed           ✗ (standardize on 16)
+
+  Hierarchy:
+    H1 > H2 > body                               ✓
+
+Recommend:
+  /impeccable polish   → targeted tweaks
+  /impeccable layout   → reflow the grid for a stronger pass
+```
+
+### Turn 2 — you
+
+```text
+/impeccable polish
+```
+
+### Turn 2 — Claude
+
+```text
+Polish applied:
+  - product-list.component.scss:
+      .product-card { padding: 16px; gap: 8px; }
+      .section + .section { margin-top: 24px; }
+  - Lighthouse re-run: 0.88 (was 0.85) ✓
+  - axe: 0 violations ✓
+```
+
+---
+
+## 9. Workflow 4 — Spring Boot 3 → 4 + Angular 17 → 21 migration
+
+Scenario: legacy fullstack project on Spring Boot 3.2 + Angular 17.
+
+### Turn 1 — you
+
+```text
+migrate the project: Spring Boot 3.2 → 4.0 and Angular 17 → 21
+```
+
+### Turn 1 — Claude (`migrator` agent)
+
+```text
+Phase 1 — Assessment (read-only):
+  Reading backend/pom.xml... Spring Boot 3.2.5 + Spring Security 6.2.
+  Reading frontend/package.json... Angular 17.2 + RxJS 7.8.
+
+  Identified risks:
+    Backend:
+      - WebSecurityConfigurerAdapter (deprecated, removed in Spring 6.4+)
+      - antMatchers (renamed to requestMatchers)
+      - JpaSpecificationExecutor unchanged
+      - Spring AI (not used) — N/A
+    Frontend:
+      - Legacy NgModule (12 modules) — migrate to standalone
+      - @Input() decorator-based — migrate to signal input()
+      - effect() still experimental in 17 — stable in 21
+      - Reactive forms — Signal Forms in 21 (opt-in)
+
+  Output: docs/migration/MIGRATION-spring3-to-4_angular17-to-21.md
+
+Phase 2 — Backend (proposed, not yet applied):
+  Sprint 1.1: bump pom.xml + SecurityFilterChain
+  Sprint 1.2: swap antMatchers → requestMatchers
+  Sprint 1.3: run the suite, fix tests
+
+Phase 3 — Frontend (proposed):
+  Sprint 2.1: codemod NgModule → standalone (Angular schematic)
+  Sprint 2.2: @Input() → input() signal
+  Sprint 2.3: reactive forms → Signal Forms (optional)
+
+Approve?
+```
+
+### Turn 2 — you
+
+```text
+approved, go
+```
+
+`migrator` applies sprint by sprint, each passing through `gate-keeper`.
+Automatic rollback if any gate fails.
+
+---
+
+## 10. Workflow 5 — Adopting a legacy fullstack project
+
+Scenario: you have `C:\projects\legacy-fullstack` that was NOT created by the
+harness. You want to onboard it.
+
+```bash
+cd C:\projects\legacy-fullstack
+
+# Inject .claude/ + CLAUDE.md (with backup):
+duk install
+
+# Preview before applying:
+duk install --dry-run
+```
+
+`duk install` is idempotent: if `.claude/` already exists, it does a
+non-destructive merge and creates `CLAUDE.md.bak-<timestamp>` before
+touching anything.
+
+Edit `CLAUDE.md`:
+
+```markdown
+## Project Identity
+- **Project name**: `legacy-fullstack`
+- **Project type**: `fullstack`
+- **Primary stack**: `Java 21 + Spring Boot 3.2 + Angular 17`
+- ...
+```
+
+In chat:
+
+```text
+> "auditor, compare structure with template"
+> "test-coverage-auditor, audit test debt"
+> "tech-lead, prioritize P0/P1"
+> "migrate to Spring Boot 4 + Angular 21"   (optional)
+```
+
+For non-interactive adoption:
+
+```text
+> "/active-project C:\projects\legacy-fullstack"
+```
+
+---
+
+## 11. CORS, openapi-typescript, healthchecks, docker-compose
+
+### 11.1. CORS
+
+Backend (`application-dev.yml`):
+
+```yaml
+app:
+  cors:
+    allowed-origins:
+      - http://localhost:4200
+    allowed-methods: [GET, POST, PUT, PATCH, DELETE, OPTIONS]
+    allowed-headers: ["*"]
+    exposed-headers: [Authorization, Location, X-Total-Count]
+    allow-credentials: true
+    max-age: 3600
+```
+
+Backend (`application-prod.yml`):
+
+```yaml
+app:
+  cors:
+    allowed-origin-patterns:
+      - https://*.company.com
+    allow-credentials: true
+```
+
+**Never** use `*` in production with `allow-credentials: true` (forbidden by
+the CORS spec).
+
+### 11.2. openapi-typescript
+
+Backend already exposes `/v3/api-docs` (Springdoc OpenAPI 3.1).
+
+Frontend `package.json`:
+
+```json
+{
+  "scripts": {
+    "gen:api": "openapi-typescript http://localhost:8080/v3/api-docs -o src/api/types.ts",
+    "gen:api:ci": "openapi-typescript ../backend/target/openapi.json -o src/api/types.ts"
+  }
+}
+```
+
+Typical service usage:
+
+```typescript
+import type { components } from '@app/api/types';
+
+type ProductResponse = components['schemas']['ProductResponse'];
+type CreateProductRequest = components['schemas']['CreateProductRequest'];
+
+@Injectable({ providedIn: 'root' })
+export class ProductService {
+  private http = inject(HttpClient);
+
+  create(req: CreateProductRequest) {
+    return this.http.post<ProductResponse>('/api/v1/products', req);
+  }
+}
+```
+
+Rule: **always regenerate `types.ts` after every contract change.** A
+PostToolUse hook in `.claude/settings.json` warns when the backend changes
+an endpoint and the frontend hasn't regenerated.
+
+### 11.3. Healthchecks
+
+Backend `application.yml`:
+
+```yaml
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health, info, metrics, prometheus
+  endpoint:
+    health:
+      show-details: when_authorized
+      probes:
+        enabled: true
+```
+
+Endpoints:
+
+- `/actuator/health/readiness`
+- `/actuator/health/liveness`
+- `/api/v1/health` (custom public, summarized)
+
+Docker `Dockerfile`:
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
+  CMD curl -fsS http://localhost:8080/actuator/health/liveness || exit 1
+```
+
+### 11.4. docker-compose.yml (summary)
+
+```yaml
+services:
+  postgres:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_DB: myfullstack
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: app
+    ports: ["5432:5432"]
+    volumes: [postgres-data:/var/lib/postgresql/data]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app -d myfullstack"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    ports: ["6379:6379"]
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      retries: 5
+
+  mailhog:
+    image: mailhog/mailhog:latest
+    ports: ["1025:1025", "8025:8025"]
+
+  backend:
+    build: ./backend
+    depends_on:
+      postgres: { condition: service_healthy }
+      redis:    { condition: service_healthy }
+    environment:
+      SPRING_PROFILES_ACTIVE: dev
+      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/myfullstack
+      SPRING_DATA_REDIS_HOST: redis
+    ports: ["8080:8080"]
+
+  frontend:
+    build: ./frontend
+    depends_on: [backend]
+    environment:
+      API_BASE_URL: http://localhost:8080
+    ports: ["4200:4200"]
+
+volumes:
+  postgres-data:
+```
+
+---
+
+## 12. CI/CD — GitHub Actions matrix
+
+`.github/workflows/ci.yml`:
+
+```yaml
+name: CI
+
+on:
+  pull_request:
+    branches: [main, develop]
+  push:
+    branches: [main, develop]
+
+jobs:
+  backend:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_DB: myfullstack_test
+          POSTGRES_USER: app
+          POSTGRES_PASSWORD: app
+        options: >-
+          --health-cmd "pg_isready -U app"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports: [5432:5432]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with: { java-version: '25', distribution: 'temurin', cache: 'maven' }
+      - name: Backend build + test + gate
+        working-directory: backend
+        run: |
+          ./mvnw -B clean verify
+          ./mvnw -B org.pitest:pitest-maven:mutationCoverage
+          ./mvnw -B spotbugs:check
+          ./mvnw -B org.owasp:dependency-check-maven:check
+      - uses: actions/upload-artifact@v4
+        with:
+          name: backend-reports
+          path: backend/target/site/
+
+  frontend:
+    runs-on: ubuntu-latest
+    needs: backend
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '22', cache: 'npm', cache-dependency-path: frontend/package-lock.json }
+      - name: Frontend build + test + gate
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run lint -- --max-warnings 0
+          npm test -- --coverage --watchAll=false
+          npm audit --audit-level=high
+          npm run build -- --configuration=production
+          npx playwright install --with-deps
+          npm run e2e
+          npx @lhci/cli autorun
+
+  integration:
+    runs-on: ubuntu-latest
+    needs: [backend, frontend]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Docker compose up
+        run: docker compose up -d --wait
+      - name: Smoke
+        run: |
+          curl -fsS http://localhost:8080/api/v1/health
+          curl -fsS http://localhost:4200
+```
+
+---
+
+## 13. Cheat sheet — all fullstack triggers
+
+Big table, ordered by intent.
+
+| Intent | Example trigger | Skill / Agent |
+|---|---|---|
+| New monorepo from scratch | `scaffold the monorepo` | `bootstrap-fullstack` |
+| Adopt existing project | `duk install` (CLI) + `auditor, compare structure` | `update-template` + `auditor` |
+| Non-interactive adoption | `/active-project C:\projects\X` | `active-project` |
+| Idea discovery | `grill me about <X>` | `grill-me` |
+| Generate PRD | `generate PRD` | `to-prd` |
+| PRD into issues | `break into issues` | `to-issues` |
+| Technical plan (Sprint) | `analyst, generate the plan` | `analyst` agent |
+| Decision ADR | `architect, propose an ADR for <X>` | `architect` agent |
+| Implement Sprint N | `run sprint <N> of PLAN_<X>.md` | `run-sprint` |
+| Backend feature | `backend-developer, create endpoint <X>` | `backend-developer` agent |
+| Frontend feature | `frontend-developer, create screen <X>` | `frontend-developer` agent |
+| Model a table | `database-engineer, model <X>` | `database-engineer` agent |
+| Write tests | `qa-engineer, write tests for <X>` | `qa-engineer` agent |
+| Run gate | `run the tests` / `full suite` | `auto-test-guard` (→ `gate-keeper`) |
+| Integrated smoke | `test the integration` | `api-integration-test` |
+| Go/No-Go for prod | `is it production-ready?` | `prd-ready-check` |
+| Visual polish | `/impeccable polish` | Impeccable |
+| Visual audit | `/impeccable audit` | Impeccable |
+| Visual harden | `/impeccable harden` | Impeccable |
+| Reflow layout | `/impeccable layout` | Impeccable |
+| Hypothesis-driven debug | `let's debug <X>` / `investigate this bug` | `pair-debug` |
+| Record in vault | `record in brain` | `brain-keeper` |
+| Migrate stack | `migrate from <X> to <Y>` | `migrator` agent |
+| Update template | `update the template` | `update-template` |
+| Catch-all | any prompt without a keyword | `project-manager` |
+
+CLI (terminal, outside chat):
+
+| Command | What it does |
+|---|---|
+| `duk install` | Inject `.claude/` + `CLAUDE.md` in CWD |
+| `duk install --sub backend` | Inject in `backend/` subfolder |
+| `duk install --sub frontend` | Inject in `frontend/` subfolder |
+| `duk install --dry-run` | Preview without writing |
+| `duk update` | Alias of `duk install` |
+| `duk dashboard` | Brings up `http://localhost:4242` |
+| `duk dashboard --port 4243 --no-open` | Variants |
+
+---
+
+## 14. Decision tree — end-to-end flow
+
+```
+                New project?
+                     │
+        ┌────────────┴────────────┐
+       YES                       NO
+        │                         │
+"scaffold the monorepo"   "duk install" + edit CLAUDE.md
+        │                         │
+        └────────────┬────────────┘
+                     │
+              Feature idea?
+                     │
+                    YES
+                     │
+            "grill me about <X>"
+                     │
+              Discovery done?
+                     │
+                    YES
+                     │
+                "generate PRD"
+                     │
+               "break into issues" (optional)
+                     │
+              "analyst, generate the plan"
+                     │
+               PLAN_<X>.md ready?
+                     │
+                    YES
+                     │
+            "run sprint <N> of PLAN_<X>.md"
+                     │
+                Sprint green?
+                     │
+        ┌────────────┴────────────┐
+       YES                       NO
+        │                         │
+        │                  "let's debug"
+        │                         │
+        │                  (pair-debug loop)
+        │                         │
+        ▼                         ▼
+"/impeccable audit"         retry sprint
+        │
+"/impeccable polish"
+        │
+"test the integration"
+        │
+   All green?
+        │
+       YES
+        │
+"is it production-ready?"
+        │
+   GO?
+        │
+       YES
+        │
+"record in brain"
+        │
+      merge
+
+       (in parallel, anytime:)
+       Production bug?       → "let's debug <X>"
+       Migrate stack?        → "migrate from <X> to <Y>"
+       Update the harness?   → "update the template"
+```
+
+---
+
+## 15. Antipatterns
+
+- ❌ Inline `template:` or `styles:` in an Angular component. **Always 3
+  physical files** (.ts / .html / .scss). Hard-blocked by `code-reviewer`.
+- ❌ Exposing a JPA `@Entity` directly in `@RestController`. Use record DTO.
+- ❌ `duk <skill>`. Does not exist. Skills are chat keywords.
+- ❌ `to-prd` without first running `grill-me`. ADR-013 blocks it (human
+  path).
+- ❌ Skipping `gate-keeper`. The senior+ gate is non-negotiable.
+- ❌ Stale TS types. Regenerate `src/api/types.ts` after every OpenAPI
+  contract change.
+- ❌ Hardcoded `http://localhost:8080` in the production frontend. Use
+  `environment.apiBaseUrl`.
+- ❌ `Co-Authored-By: Claude` in commits. Forbidden. Blocks merge.
+- ❌ `allowed-origins: "*"` with `allow-credentials: true`. CORS forbids it.
+- ❌ `var` in a public Java signature/return.
+- ❌ `any` in TypeScript. Use `unknown` + narrowing.
+- ❌ Product decisions by the developer. PO decides. Tech decisions by the
+  PO. TL decides.
+
+---
+
+## 16. Fullstack troubleshooting
+
+### 16.1. CORS error in the browser
+
+Symptom: console shows `Access to XMLHttpRequest at '...' has been blocked
+by CORS policy`.
+
+Investigate:
+
+```bash
+curl -i -X OPTIONS http://localhost:8080/api/v1/products \
+  -H "Origin: http://localhost:4200" \
+  -H "Access-Control-Request-Method: POST"
+```
+
+If it does not return `Access-Control-Allow-Origin`, the issue is on the
+backend.
+
+```text
+> "let's debug CORS on the /api/v1/products endpoint"
+```
+
+### 16.2. TS types out of sync
+
+Symptom: TS compiles but runtime breaks with `Cannot read properties of
+undefined`.
+
+Fix:
+
+```bash
+cd frontend
+npm run gen:api
+```
+
+Commit `src/api/types.ts`.
+
+### 16.3. Network between containers in docker-compose
+
+Symptom: backend can't reach `localhost:5432`.
+
+Cause: inside a container, the Postgres hostname is `postgres` (the service
+name), not `localhost`.
+
+Fix: use `SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/...`.
+
+### 16.4. Port 8080 / 4200 in use
+
+```bash
+# Windows:
+netstat -ano | findstr :8080
+taskkill /F /PID <PID>
+
+# Linux/Mac:
+lsof -i :8080
+kill -9 <PID>
+```
+
+Or change the port in `docker-compose.yml`.
+
+### 16.5. OpenAPI returns 404
+
+Symptom: `http://localhost:8080/v3/api-docs` 404.
+
+Common cause: Springdoc is not in the dependencies.
+
+Fix in `pom.xml`:
+
+```xml
+<dependency>
+  <groupId>org.springdoc</groupId>
+  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+  <version>2.6.0</version>
+</dependency>
+```
+
+### 16.6. Hot reload on both
+
+- **Backend**: `./mvnw spring-boot:run` + DevTools in `pom.xml`.
+- **Frontend**: `ng serve` (native hot reload).
+- **Docker**: bind mount `./backend/src:/app/src` + `./frontend/src:/app/src`,
+  custom command to reload.
+
+### 16.7. Frontend comes up before the backend
+
+Symptom: initial screen 500 / ECONNREFUSED.
+
+Fix: `depends_on` with `condition: service_healthy` in compose. Without it,
+`depends_on` only waits for the container to exist, not for the service to
+be ready.
+
+### 16.8. 401 on integration
+
+Expired / missing / invalid token. Check:
+
+- The auth interceptor is registered in `app.config.ts`.
+- `localStorage` has the token under the right key.
+- Backend accepts the issuer/audience.
+
+### 16.9. Lighthouse below 0.80
+
+- Images without `width/height` → high CLS.
+- Initial bundle > 500KB → high LCP.
+- Blocking JS in `<head>` → high TBT.
+
+Fixes via `frontend-developer` + Impeccable.
+
+More in [troubleshooting](../docs/troubleshooting).
+
+---
+
+## 18. Active hooks
+
+`.claude/settings.json` defines hooks that fire at key moments:
+
+- **PreToolUse**: validates `Edit`/`Write` (blocks inline Angular template,
+  blocks `// TODO`, blocks exposing `@Entity` from a controller).
+- **PostToolUse**: warns if the backend changed the OpenAPI contract and
+  the frontend hasn't regenerated `types.ts`.
+- **UserPromptSubmit**: runs at prompt submit.
+- **SessionStart**: loads `Project Identity` into the context.
+
+Details: [hooks-reference](../docs/hooks-reference).
+
+---
+
+## 19. Quick glossary
+
+- **Skill**: conversational entry-point triggered by a keyword. Routes to
+  one or more agents.
+- **Agent**: specialized executor (analyst, backend-developer, etc.) with
+  defined responsibility and autonomy.
+- **PLAN**: `docs/plans/PLAN_<slug>.md` with Sprints + Tasks + goal-ready DoD.
+- **PRD**: `docs/prd/PRD_<slug>.md` (Product Requirements Document).
+- **ADR**: Architecture Decision Record in `docs/decisions/ADR-NNN-*.md`.
+- **Goal-ready DoD**: verifiable, automatable acceptance criterion aligned
+  with the task goal.
+- **Senior+ gate**: set of thresholds (coverage, mutation, a11y,
+  Lighthouse, pyramid ratio) that blocks merge.
+- **Vault**: `docs/brain/` in Obsidian format (wiki links + tags + MOC).
+- **Impeccable**: external pack (`npx skills add pbakaus/impeccable`) with
+  `/impeccable polish|audit|harden|typeset|colorize|layout` commands for
+  visual polish.
+- **openapi-typescript**: TS type generator from OpenAPI 3.x.
+- **Goal-ready**: explicit, measurable, tied to the objective.
+
+---
+
+## 20. Cross-references
+
+- [Architecture overview](../docs/architecture-overview)
+- [Stack rules](../docs/stack-rules)
+- [Skills reference](../docs/skills-reference)
+- [Agents reference](../docs/agents-reference)
+- [Pipeline](../docs/pipeline)
+- [Quality gate](../docs/quality-gate)
+- [Autonomy matrix](../docs/autonomy-matrix)
+- [Git flow](../docs/git-flow)
+- [Hooks reference](../docs/hooks-reference)
+- [Troubleshooting](../docs/troubleshooting)
+- [Manual — Backend (standalone)](./backend.en)
+- [Manual — Frontend (standalone)](./frontend.en)
+- [Manual — Mobile](./mobile.en)
+- [Manual — Existing project](./existing-project.en)
+
+---
+
+**End of manual.** Happy building.