@eltonssouza/development-utility-kit 0.10.0

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

@@ -0,0 +1,1053 @@
+# Backend Manual — Java 25 + Spring Boot 4
+
+This manual is the definitive starting point for any backend developer who
+opens the `development-utility-kit` dashboard for the first time. It covers the
+backend flow only (Java 25 + Spring Boot 4 + DDD), with no fluff and no
+generic examples. Every command, trigger, and agent reference here was
+checked against the real harness code — nothing was invented.
+
+Prerequisites before you start:
+
+- JDK 25 or higher installed (`java -version` should respond 25+)
+- Maven 3.9+ (`mvn -v`) — the `./mvnw` wrapper is generated by the scaffold
+- Docker Desktop + Docker Compose v2 (for Testcontainers + local stack)
+- Node.js 18+ (required by the `duk` binary distributed via npx)
+- Cowork (recommended) **or** Claude Code CLI (`claude`) authenticated
+
+If any of these are missing, **stop here** and install them first. The
+harness assumes the environment is already healthy.
+
+---
+
+## 1. Five-minute onboarding
+
+This is the shortest path from "I have an empty folder" to "I have a Spring
+Boot 4 backend with a senior+ gate running". Five steps, every command real.
+
+### Step 1 — Create or enter the canonical project folder
+
+Every new project lives in `C:\development\source\projects\<name>\`. If the
+folder doesn't exist yet:
+
+```bash
+mkdir -p C:\development\source\projects\my-backend-api
+cd C:\development\source\projects\my-backend-api
+git init
+```
+
+If you prefer the guided scaffold, use the interactive wrapper:
+
+```bash
+# Windows (CMD or double-click)
+C:\development\tools\development-utility-kit\scripts\new-project.bat
+
+# Git Bash / WSL / Mac / Linux
+bash /c/development/tools/development-utility-kit/scripts/new-project.sh
+```
+
+### Step 2 — Install the harness into the folder
+
+The `duk` binary (installed via npx) injects `.claude/`, `CLAUDE.md`, and
+the skill/agent settings. It is idempotent — run it as often as you like.
+
+```bash
+# Recommended form (no global install):
+npx @eltonssouza/development-utility-kit install
+
+# If the duk binary is already on PATH:
+duk install
+
+# Preview what would be modified (writes nothing):
+duk install --dry-run
+
+# Install into a subdirectory only (e.g. monorepo):
+duk install --sub backend
+```
+
+Expected output: creation of `.claude/`, `CLAUDE.md`, `docs/`, and a backup
+`.claude.backup-YYYYMMDD-HHMMSS/` if previous configuration existed.
+
+### Step 3 — Edit the `Project Identity` section of `CLAUDE.md`
+
+This is the **only section** of `CLAUDE.md` you should edit by hand. The
+remaining sections are harness-owned and will be overwritten on
+`update-template` (the `Project Identity` section is preserved by the merge).
+
+Open `CLAUDE.md` and fill in:
+
+```markdown
+## Project Identity
+
+- **Project name**: `my-backend-api`
+- **Project type**: `backend`
+- **Primary stack**: `Java 25 + Spring Boot 4`
+- **Database**: `PostgreSQL 17 + Redis 7`
+- **Domain**: `e-commerce`
+- **Team size**: `3 backend`
+- **Additional rules**: _(leave empty if none)_
+```
+
+The `Project type` field is decisive — bootstrap skills read this value to
+decide what to scaffold.
+
+### Step 4 — Open Cowork or Claude Code in the folder
+
+In any terminal **inside** the project folder:
+
+```bash
+# Claude Code CLI:
+claude
+
+# OR open the folder in Cowork as a local session
+```
+
+You are ready for the first conversation.
+
+### Step 5 — First prompt: scaffold the backend
+
+Type **literally** into the chat:
+
+```text
+scaffolda o backend
+```
+
+(Yes — the trigger phrase is Portuguese by design; the skill matches the
+keyword regardless of UI language. The English alias `scaffold the backend`
+also works.)
+
+The `bootstrap-backend-java` skill fires by keyword match, reads
+`Project Identity`, calls Spring Initializr (Spring Boot 4.0+, Java 25+),
+and generates:
+
+```
+backend/
+├── pom.xml                          (Spring Boot 4 parent, Java 25)
+├── src/main/java/com/<org>/<app>/
+│   ├── domain/                       (model, repository ports)
+│   ├── application/                  (use cases, record DTOs)
+│   ├── infrastructure/               (JPA adapters, security, config)
+│   └── web/                          (controllers, advice, ProblemDetail)
+├── src/main/resources/
+│   ├── application.yml
+│   └── db/migration/V1__init.sql     (Flyway baseline)
+├── src/test/                         (JUnit 5 + Mockito + Testcontainers)
+└── README.md
+docker-compose.yml                    (postgres + redis at root level)
+```
+
+In parallel, the initial gate is configured: JaCoCo (coverage), Pitest
+(mutation), SpotBugs, OWASP dependency-check. `gate-keeper` has what it
+needs to live by from the very first commit.
+
+From here on, you no longer touch the scaffold — every new iteration is via
+chat prompt.
+
+---
+
+## 2. How the harness actually works
+
+Before listing skills, understand the architecture. **There is no CLI
+command that invokes a skill or an agent.** This is a common mistake.
+
+### The real `duk` CLI
+
+The `duk` binary (in `bin/cli.js`) exposes exactly three commands:
+
+| Command | Purpose |
+|---|---|
+| `duk install` | Injects `.claude/` + `CLAUDE.md` into CWD. Alias: `duk update`. |
+| `duk install --sub backend` | Same, into a subfolder. |
+| `duk install --dry-run` | Show the diff without writing. |
+| `duk dashboard` | Start the local dashboard at `http://localhost:4242`. |
+| `duk dashboard --port 4243 --no-open` | Custom port, no browser. |
+
+There is **no** `duk grill-me`, `duk project-manager`, `duk run-sprint`, or
+`duk <any-skill>`. Skills are not command-line entities — they are
+`SKILL.md` files that Claude Code/Cowork **fires automatically by keyword
+match in the user prompt**.
+
+### Skill vs Agent vs Task tool
+
+| Layer | Lives in | How it's invoked |
+|---|---|---|
+| Skill | `.claude/skills/<name>/SKILL.md` | Keyword match in the user prompt |
+| Agent | `.claude/agents/<name>.md` | Skill calls via Task tool (not directly by user) |
+| Task tool | Claude Code built-in | Skills use it to delegate work to agents |
+
+You talk to the skill in natural language. It delegates to the appropriate
+agents through the Task tool. Agents do the real work (write code, run
+tests, produce ADRs) and return to the skill, which returns to you.
+
+### Keyword → skill map
+
+| Skill | Triggers (type literally; mixed PT/EN supported) |
+|---|---|
+| `bootstrap-backend-java` | `scaffolda o backend`, `scaffold the backend`, `bootstrap backend`, `start a Spring Boot backend` |
+| `grill-me` | `grill me about <X>`, `interview me on <X>`, `stress-test the plan for <Y>`, `rubber duck` |
+| `to-prd` | `generate PRD`, `create PRD`, `to-prd` |
+| `to-issues` | `break into issues`, `generate issues`, `to-issues` |
+| `run-sprint` | `run sprint 1`, `execute sprint 2 of PLAN_<X>.md`, `implement the sprint tasks` |
+| `auto-test-guard` | `run the tests`, `generate tests`, `full suite`, `make sure nothing broke` |
+| `prd-ready-check` | `ready for production?`, `DoD`, `can we ship`, `run the final checklist` |
+| `api-integration-test` | `integration test`, `smoke test`, `bring everything up and test` |
+| `pair-debug` | `let's debug <X>`, `investigate this bug`, `find the root cause`, `why doesn't this work` |
+| `brain-keeper` | `record in the brain`, `update brain`, `daily log`, `save ADR to vault` |
+| `active-project` | `/active-project <path>`, `activate project at <path>` |
+| `update-template` | `update the template`, `sync with development-utility-kit`, `pull the new skills` |
+| `project-manager` | catch-all — any prompt without a more specific skill |
+| `caveman` | `caveman lite`, `caveman ultra`, `stop caveman` |
+
+---
+
+## 3. Skills relevant to the backend
+
+The master table below lists every skill relevant to a backend project.
+Each one has a dedicated card in the following subsections.
+
+| Skill | When to use | Output |
+|---|---|---|
+| `bootstrap-backend-java` | Empty folder, after first `duk install` | `backend/` Spring Boot 4 + compose |
+| `grill-me` | Vague idea, before any PRD/PLAN | `docs/discovery/DISCOVERY_<NAME>.md` |
+| `to-prd` | Discovery done, missing product doc | `docs/prd/PRD_<NAME>.md` |
+| `to-issues` | PRD done, you want GitHub issues | `docs/issues/ISSUES_<NAME>.md` |
+| `run-sprint` | PLAN ready with sprints defined | Code + green tests (TDD) |
+| `auto-test-guard` | End of task or explicit gate request | Full suite + thresholds |
+| `prd-ready-check` | Before tagging a release | GO/NO-GO verdict |
+| `api-integration-test` | You want a real smoke (not unit) | curl report + logs |
+| `pair-debug` | Non-obvious bug, intermittent failure | hypothesis→probe→fix loop |
+| `brain-keeper` | End of sprint/feature, want history | `docs/brain/` daily + feature + ADR |
+| `active-project` | Fast non-interactive adoption by path | `.claude/` installed at path |
+| `update-template` | Pull new skills/agents from harness | Merge into `.claude/` + backup |
+| `caveman` | You want telegraphic answers | Output 65-75% smaller |
+
+### 3.1. `bootstrap-backend-java`
+
+**When to use:** first time in a new `type: backend` project, or whenever
+you need the standard skeleton.
+
+**Triggers:**
+
+```text
+scaffold the backend
+scaffolda o backend
+bootstrap backend
+start a Spring Boot backend
+```
+
+**What it does:**
+
+1. Reads `CLAUDE.md` → `Project Identity` (name, stack, db).
+2. Calls Spring Initializr with Spring Boot 4.0+ / Java 25+.
+3. Creates DDD structure (`domain/`, `application/`, `infrastructure/`, `web/`).
+4. Adds `pom.xml` with JaCoCo, Pitest, SpotBugs, OWASP DC.
+5. Creates root `docker-compose.yml` with postgres + redis.
+6. Generates first Flyway migration (`V1__init.sql`).
+7. Configures `application.yml` (dev profile, datasource, actuator).
+8. Test stub with working Testcontainers Postgres.
+
+**Typical chat output:**
+
+```text
+[bootstrap-backend-java]
+✓ Read CLAUDE.md → my-backend-api / e-commerce
+✓ Spring Initializr → spring-boot 4.0.0, java 25
+✓ DDD structure created at backend/
+✓ pom.xml with senior+ gate (JaCoCo 0.8.12, Pitest 1.17, SpotBugs 4.8, OWASP 10.0)
+✓ docker-compose.yml (postgres:17, redis:7)
+✓ Flyway baseline at V1__init.sql
+✓ application.yml dev profile ready
+✓ Sample test with @Testcontainers green
+
+Suggested next step: "grill me about <first feature>"
+```
+
+### 3.2. `grill-me`
+
+**When to use:** any new feature idea, before going to PRD/PLAN. The skill
+runs a Socratic interview (10-30 turns) and forces you to make scope, edge
+cases, priority, and success metric explicit. **On the human path, `analyst`
+refuses to produce a PLAN without a valid DISCOVERY** (see ADR-013/017).
+
+**Triggers:**
+
+```text
+grill me about adding JWT authentication
+interview me on the payment module
+stress-test the plan for distributed cache
+rubber duck on the orders webhook idea
+```
+
+**Real conversation example (8 turns):**
+
+```text
+You:
+grill me about adding JWT authentication
+
+Claude (grill-me):
+> Let's understand the goal. Will JWT be issued by your own backend (login
+> with email/password) or by an external IdP (Keycloak, Auth0)? I recommend
+> your own backend for the MVP — less integration. Confirm?
+
+You:
+own backend
+
+Claude:
+> Refresh token: opaque (uuid in Redis) or JWT too? I recommend opaque +
+> rotation on every refresh. Trade-off: one extra Redis trip vs immediate
+> revocability. OK?
+
+You:
+opaque + rotation
+
+Claude:
+> RBAC: fixed roles (USER/ADMIN) or granular (permissions table)? I
+> recommend fixed roles for the MVP — granularize when a 3rd user type
+> appears.
+
+You:
+fixed roles, USER and ADMIN
+
+Claude:
+> Expiration policy: access 15min, refresh 7d? OK for your "stay logged in
+> for a week" window?
+
+You:
+yes
+
+Claude:
+> Password: bcrypt cost 12 (Spring Security 6+ default) or argon2? Bcrypt
+> covers 99% of cases. I recommend bcrypt 12 + rate limit on /login
+> (5/min/IP).
+
+You:
+bcrypt 12
+
+Claude:
+> Success metric? Suggest: POST /login P95 < 200ms, expected 401 error
+> rate < 5% (attack), 0 tokens leaked in logs.
+
+You:
+done
+
+Claude:
+> Persisted to docs/discovery/DISCOVERY_auth-jwt.md with 8 sections.
+> Suggested next step: "generate PRD"
+```
+
+### 3.3. `to-prd`
+
+**When to use:** when the DISCOVERY is done and you want a formal product
+document (with Goals, User Stories, FR, NFR, Out of scope) for team
+reference.
+
+**Triggers:**
+
+```text
+generate PRD
+create PRD
+to-prd
+```
+
+**Output:** `docs/prd/PRD_<NAME>.md` with 6 sections:
+
+1. Overview
+2. Goals (measurable)
+3. User Stories
+4. Functional Requirements
+5. Non-functional Requirements
+6. Out of scope
+
+### 3.4. `to-issues`
+
+**When to use:** PRD is ready and you want to break it into issues, ready
+for `gh issue create`.
+
+**Triggers:**
+
+```text
+break into issues
+generate issues
+to-issues
+```
+
+**Output:** `docs/issues/ISSUES_<NAME>.md` with `[ISSUE-N]`
+copy-paste-ready blocks.
+
+### 3.5. `run-sprint`
+
+**When to use:** a `docs/plans/PLAN_<NAME>.md` exists (produced by
+`analyst`) and you want to execute a specific sprint in orchestrated TDD
+mode.
+
+**Non-negotiable prerequisite:** the PLAN must have **goal-ready DoD**
+(Definition of Done expressed as a verifiable objective, not a task
+checklist). `analyst` refuses to produce a PLAN without DISCOVERY.
+
+**Triggers:**
+
+```text
+run sprint 1 of PLAN_auth-jwt.md
+execute sprint 2
+implement the sprint 1 tasks
+let's code sprint 1
+```
+
+**What it does per task:**
+
+1. `qa-engineer` writes a failing test (JUnit 5 + Mockito or Testcontainers).
+2. `backend-developer` implements code until the test passes.
+3. `gate-keeper` validates senior+ thresholds (coverage, mutation, SpotBugs).
+4. If the gate fails, it routes back to `backend-developer` with diagnosis.
+5. If the gate passes, move on to the next task.
+
+### 3.6. `auto-test-guard`
+
+**When to use:** at the end of any significant task, or explicitly.
+
+**Triggers:**
+
+```text
+run the tests
+generate tests
+test everything
+full suite
+make sure nothing broke
+```
+
+**Mandatory backend thresholds:**
+
+| Metric | Minimum | Tool |
+|---|---|---|
+| Line coverage | 85% | JaCoCo |
+| Branch coverage | 80% | JaCoCo |
+| Mutation score (domain + application) | 70% | Pitest |
+| SpotBugs CRITICAL/HIGH | 0 | SpotBugs Maven |
+| OWASP CVE CVSS≥7.0 | 0 | OWASP DC |
+| Pyramid — % E2E | ≤30% (hard) / ≤15% (ideal) | auto count |
+
+If any threshold fails, `gate-keeper` blocks the merge. `tech-lead` rejects
+the PR.
+
+### 3.7. `api-integration-test`
+
+**When to use:** real smoke — app started via docker compose plus actual
+curl/HTTP. Not unit, not mock.
+
+**Triggers:**
+
+```text
+integration test
+smoke test
+bring everything up and test
+```
+
+**What it does:**
+
+1. `docker compose up -d` (postgres + redis + backend).
+2. Waits for `/actuator/health` to return UP.
+3. Runs the list of critical endpoints (main CRUD, auth, error paths).
+4. Verifies ProblemDetail (RFC 9457) in error responses.
+5. Tear down + report.
+
+### 3.8. `prd-ready-check`
+
+**When to use:** before tag/release/deploy. This is the final gate that
+cross-references PRD/DoD with the real code state.
+
+**Triggers:**
+
+```text
+ready for production?
+DoD
+can we ship?
+run the final checklist
+```
+
+**Output:** GO or NO-GO verdict with a detailed list of what's missing.
+
+### 3.9. `pair-debug`
+
+**When to use:** non-obvious bug. Intermittent failure. Error only in prod.
+Behavior diverges between environments. **Never** use this in "try and see"
+mode — the skill forces explicit hypotheses before any change.
+
+**Triggers:**
+
+```text
+let's debug this 500 on GET /users
+investigate this Hibernate LazyInitException
+find the root cause of the migration failure
+why does this work locally but not in prod
+```
+
+**Loop example:**
+
+```text
+You:
+let's debug this 500 on GET /api/v1/users in prod
+
+Claude (pair-debug):
+> Symptom: 500 on GET /api/v1/users only in prod.
+> Hypothesis 1 (70% confidence): Lazy loading of User.roles fires outside
+> a transaction. Probe: grep "@Transactional" in UserService + Hibernate
+> logs for LazyInitializationException.
+> Run probe? (yes/no)
+
+You:
+yes
+
+Claude:
+> Probe done. Result: UserService.findAll() has no @Transactional.
+> Prod log has 47 occurrences of LazyInitializationException in the last
+> 24h. Hypothesis 1 CONFIRMED.
+> Fix: add @Transactional(readOnly=true) to UserService.findAll().
+> Dispatching backend-developer to apply + qa-engineer for a regression
+> test that fails without the fix.
+```
+
+### 3.10. `brain-keeper`
+
+**When to use:** at the end of a sprint or feature, to record history in
+Obsidian format (vault at `docs/brain/`).
+
+**Triggers:**
+
+```text
+record in the brain
+update brain
+daily log
+save ADR to vault
+```
+
+**Output:**
+
+- `docs/brain/daily/2026-05-27.md`
+- `docs/brain/features/<slug>.md`
+- `docs/brain/decisions/ADR-NNN-<slug>.md`
+- `docs/brain/architecture/tech-debt.md` (updated)
+- MOC (Map of Content) regenerated
+
+### 3.12. `active-project`
+
+**When to use:** fast, non-interactive adoption of an existing project at a
+specific path.
+
+**Triggers:**
+
+```text
+/active-project C:\my-legacy-project
+activate project at C:\my-legacy-project
+adopt the project at C:\old-code
+```
+
+### 3.13. `update-template`
+
+**When to use:** pull new skills/agents/ADRs from the harness into a
+project that was already adopted.
+
+**Triggers:**
+
+```text
+update the template
+sync with development-utility-kit
+pull the new skills
+```
+
+The `Project Identity` section of the project's `CLAUDE.md` is preserved in
+the merge.
+
+### 3.14. `caveman`
+
+**When to use:** when you want telegraphic answers (~65-75% fewer tokens).
+
+**Triggers:**
+
+```text
+caveman lite       (default telegraphic mode)
+caveman full       (reduced markdown)
+caveman ultra      (max compression, clean code)
+stop caveman       (back to normal)
+```
+
+By default, `caveman` is **on** with profile ULTRA for code and FULL for
+`.md`.
+
+---
+
+## 4. Agents — who does what
+
+You don't invoke agents directly. But you do need to know who is
+responsible for what — so that you understand the responses and can escalate
+correctly in case of conflict.
+
+| Agent | Model | When it acts |
+|---|---|---|
+| `product-owner` | Opus 4.7 | Product decisions, scope, rules, priority, API contract |
+| `tech-lead` | Opus 4.7 | Final technical decisions, approves/blocks merges |
+| `security-engineer` | Opus 4.7 | OWASP audit, LGPD/GDPR, technical veto on high/critical |
+| `architect` | Sonnet 4.6 | Architecture ADRs (DDD, Hexagonal, patterns) |
+| `analyst` | Sonnet 4.6 | Produces `PLAN_*.md` with goal-ready DoD |
+| `backend-developer` | Sonnet 4.6 | Java/Spring implementation (delegated by `sprint-runner`) |
+| `database-engineer` | Sonnet 4.6 | Schema, index, migration, query perf |
+| `qa-engineer` | Sonnet 4.6 | Writes tests (JUnit 5 + Mockito + Testcontainers) |
+| `gate-keeper` | Sonnet 4.6 | Runs senior+ gate, validates thresholds |
+| `code-reviewer` | Sonnet 4.6 | Initial PR review |
+| `devops-engineer` | Sonnet 4.6 | Dockerfile, CI/CD, infra |
+| `migrator` | Sonnet 4.6 | Java 8/11/17 → 25, Spring Boot 2/3 → 4 |
+| `sprint-runner` | Sonnet 4.6 | Orchestrates the sprint, delegates in parallel |
+| `brain-keeper` | Sonnet 4.6 | History in `docs/brain/` |
+| `auditor` | Sonnet 4.6 | Audits `.claude/` consistency |
+| `release-engineer` | Sonnet 4.6 | Version bump, CHANGELOG, tag |
+| `scaffold` | Haiku 4.5 | Initial scaffold pipeline |
+
+### Autonomy Matrix — the master rule
+
+Agents decide on their own. Asking the human is a rare exception. Summary:
+
+- `product-owner` escalates to the human **only in 4 cases**: irreversible
+  action on customer data, relevant financial cost, breaking change in a
+  published public contract, identity/brand change.
+- `tech-lead` escalates **only in 3 cases**: unresolvable technical
+  conflict, breaking change on a public contract in production, extra
+  infra > R$ 200/month.
+- `security-engineer` holds **technical veto** on high/critical (OWASP) —
+  blocks merges without needing the human.
+- Other agents **never** escalate to the human — they go up to PO (product)
+  or TL (technical).
+
+---
+
+## 5. Workflow 1 — Build a feature from scratch
+
+Concrete example: implement `POST /api/v1/products` with JWT authentication
+requiring the ADMIN role. I'll show every turn the way you'd really do it.
+
+### Turn 1 — Discovery
+
+```text
+You:
+grill me about creating POST /api/v1/products with JWT authentication
+
+Claude (grill-me fires):
+> Let's understand the goal. Should POST /products accept creation by any
+> authenticated user or only the ADMIN role? I recommend restricting to
+> ADMIN via @PreAuthorize. Confirm?
+```
+
+### Turn 2
+
+```text
+You:
+confirm ADMIN
+
+Claude:
+> Next: validation. Expected fields are name, price, stock. Acceptable
+> price range? I recommend positive BigDecimal, max 9999999.99. Should
+> name be unique per tenant? I recommend a DB-level unique constraint.
+```
+
+### Turn 3
+
+```text
+You:
+positive BigDecimal up to 9999999.99, name unique per tenant
+
+Claude:
+> Idempotency: can the client send the same POST twice? I recommend an
+> Idempotency-Key header (UUID), 24h Redis store, returning the same
+> response on the second hit. OK?
+```
+
+### Turns 4-9
+
+It continues until the discovery covers: errors (ProblemDetail), success
+metric, mandatory tests, observability (correlation ID), rate limit.
+Around turn 10:
+
+```text
+Claude:
+> Persisted the discovery to docs/discovery/DISCOVERY_products-crud.md
+> with 9 sections. Suggested next step: "generate PRD"
+```
+
+### Turn 11 — PRD
+
+```text
+You:
+generate PRD
+
+Claude (to-prd):
+> Created docs/prd/PRD_products-crud.md with 6 sections: Overview, Goals,
+> User Stories, FR (8 items), NFR (latency, throughput, security), Out of
+> scope. Next: "break into issues" or "analyst, produce the plan".
+```
+
+### Turn 12 — PLAN
+
+```text
+You:
+analyst, produce the plan
+
+Claude (analyst):
+> Produced docs/plans/PLAN_products-crud.md with 2 sprints, 6 tasks,
+> goal-ready DoD per sprint. Sprint 1: schema + create + validation.
+> Sprint 2: idempotency + rate limit + observability.
+> To execute: "run sprint 1 of PLAN_products-crud.md"
+```
+
+### Turn 13 — Sprint execution
+
+```text
+You:
+run sprint 1 of PLAN_products-crud.md
+
+Claude (run-sprint):
+> [Sprint 1 — 3 tasks, TDD mode]
+> [Task 1.1] Schema + Flyway migration
+>   ├─ database-engineer: V2__create_products.sql + index (name, tenant_id)
+>   ├─ qa-engineer: migration test via Testcontainers
+>   └─ gate-keeper: ✓
+> [Task 1.2] DTO record + Bean Validation
+>   ├─ qa-engineer: failing ProductRequestTest
+>   ├─ backend-developer: ProductRequest record + @NotBlank + @Positive
+>   └─ gate-keeper: coverage 92% / mutation 78% / SpotBugs 0 ✓
+> [Task 1.3] Controller + service + @PreAuthorize("hasRole('ADMIN')")
+>   ├─ qa-engineer: ProductControllerTest (201, 400, 403, 409)
+>   ├─ backend-developer: ProductController + ProductService
+>   └─ gate-keeper: coverage 89% / mutation 74% / SpotBugs 0 ✓
+> Sprint 1 GREEN. Next: "run sprint 2" or "integration test"
+```
+
+### Turn 14 — Smoke
+
+```text
+You:
+integration test
+
+Claude (api-integration-test):
+> docker compose up -d (postgres + redis + backend) ...
+> /actuator/health UP in 4.2s
+> POST /api/v1/products with valid payload + ADMIN token → 201 ✓
+> POST without token → 401 + ProblemDetail ✓
+> POST with USER token → 403 + ProblemDetail ✓
+> POST with duplicate name → 409 + ProblemDetail ✓
+> POST with negative price → 400 + ProblemDetail (field "price") ✓
+> Tear down. Integration OK.
+```
+
+### Turn 15 — Final gate
+
+```text
+You:
+ready for production?
+
+Claude (prd-ready-check):
+> Running ./mvnw clean verify, OWASP scan, E2E smoke, lint...
+> Line coverage: 89% (>= 85%) ✓
+> Branch coverage: 82% (>= 80%) ✓
+> Mutation score: 74% (>= 70%) ✓
+> SpotBugs: 0 CRITICAL, 0 HIGH ✓
+> OWASP: 0 CVE CVSS >= 7.0 ✓
+> Pyramid: 12% E2E (<= 30%) ✓
+> VERDICT: GO ✓
+```
+
+### Turn 16 — History
+
+```text
+You:
+record in the brain
+
+Claude (brain-keeper):
+> Created:
+> - docs/brain/daily/2026-05-27.md
+> - docs/brain/features/products-crud.md
+> - docs/brain/decisions/ADR-042-jwt-auth.md
+> - docs/brain/architecture/tech-debt.md (updated)
+> MOC regenerated.
+```
+
+---
+
+## 6. Workflow 2 — Debug a production bug
+
+Scenario: mysterious 500 on `GET /api/v1/users`, only in production, does
+not reproduce locally.
+
+```text
+You:
+let's debug this 500 on GET /api/v1/users in prod
+
+Claude (pair-debug):
+> Symptom: 500 on GET /api/v1/users only in prod.
+> Known prod vs local diffs: prod has real data (10k users), local has 5.
+> Prod connection pool 20, local 5.
+> Hypothesis 1 (70% confidence): Lazy loading of User.roles fires outside
+> a transaction in the controller. Locally every user has their roles
+> already in the 2nd-level cache; in prod the cache mixes.
+> Probe: grep "@Transactional" in UserService + UserController;
+> grep "LazyInitializationException" in the last 24h of prod logs.
+> Run probe? (yes/no)
+
+You:
+yes
+
+Claude:
+> Probe done.
+> ✓ UserController.list() calls userService.findAll() returning List<User>.
+> ✗ UserService.findAll() has NO @Transactional.
+> ✗ User.roles is @OneToMany(fetch = LAZY).
+> ✗ Prod logs: 47 LazyInitializationException in the last 24h, all on
+>   /api/v1/users.
+> Hypothesis 1 CONFIRMED with 99% confidence.
+>
+> Proposed fix (option A — smaller blast radius):
+>   1. Add @Transactional(readOnly=true) to UserService.findAll().
+>   2. Map to UserResponse (record DTO) inside the transaction.
+>   3. Controller only serializes the DTO — User never leaks.
+>
+> Proposed fix (option B — only if A doesn't cover):
+>   Eager fetch of roles via @EntityGraph.
+>
+> I recommend A — decouples the web layer from the entity.
+> Dispatching backend-developer for A + qa-engineer for regression test
+> (List<User> without a transaction must fail with LazyInitException).
+```
+
+---
+
+## 7. Workflow 3 — Spring Boot 2/3 → 4 migration
+
+```text
+You:
+migrate this project from Spring Boot 2.7 to 4.0
+
+Claude (migrator):
+> Phase 1 — Assessment (read-only)
+>   Catalogued: 23 removed APIs, 5 deprecated, 8 config changes.
+>   Generating MIGRATION-2.7-to-4.0.md at project root.
+>   Estimate: 2-3 dev days + 1 test day.
+>
+> Phase 2 — Quick wins (non-breaking)
+>   - List.of() where Arrays.asList()
+>   - Optional.orElseThrow() where .get()
+>   - records where the DTO is purely immutable
+>   - Pattern matching in switch
+>   Estimate: 2h.
+>
+> Phase 3 — Breaking changes (explicit ADR per major)
+>   3.1 javax.* → jakarta.* (Spring Boot 3)
+>   3.2 WebSecurityConfigurerAdapter → SecurityFilterChain
+>   3.3 RestTemplate → RestClient (Spring Boot 4)
+>   3.4 application.properties → ConfigData reorg
+>   Each item becomes an ADR in docs/decisions/.
+>
+> Phase 4 — Validation gate
+>   mvn verify GREEN at end of each phase, regression mandatory.
+>
+> Prerequisite: gate-keeper must establish a green baseline first. Run
+> baseline now? (yes/no)
+```
+
+---
+
+## 8. Workflow 4 — Adopting an existing project
+
+Three scenarios, three flows.
+
+### Case 1 — I'm already inside the folder
+
+```bash
+cd C:\my-legacy-project
+duk install                   # idempotent, takes automatic backup
+# Edit CLAUDE.md > Project Identity
+```
+
+### Case 2 — Activate by path (non-interactive)
+
+In any terminal with Cowork/Claude Code open, in chat:
+
+```text
+/active-project C:\my-legacy-project
+```
+
+### Case 3 — Update template in an adopted project
+
+```bash
+duk install                   # re-injects current harness version
+```
+
+Or in chat:
+
+```text
+update the template
+```
+
+The `Project Identity` section of the project's `CLAUDE.md` is
+**preserved** in the merge; the other sections are overwritten with the
+latest harness version.
+
+---
+
+## 9. Cheat sheet — triggers by intent
+
+| I want to... | Type in chat |
+|---|---|
+| Start a new project | `scaffold the backend` |
+| Feature discovery | `grill me about <X>` |
+| Generate PRD | `generate PRD` |
+| Break into issues | `break into issues` |
+| Generate technical plan | `analyst, produce the plan from the PRD` |
+| Execute a sprint | `run sprint <N> of PLAN_<NAME>.md` |
+| Run tests / gate | `run the tests` or `full suite` |
+| Smoke integration | `integration test` |
+| Final production gate | `ready for production?` |
+| Debug a non-obvious bug | `let's debug <X>` |
+| Record history | `record in the brain` |
+| Coverage audit | `audit the tests` |
+| Technical decision | `tech-lead, decide between <A> and <B>` |
+| Security audit | `security audit` |
+| Model the DB | `model the database for <X>` |
+| Dockerize | `dockerize the backend` |
+| Migrate version | `migrate from Spring Boot 2.7 to 4.0` |
+| Save a memory | `remember that <fact>` |
+| Telegraphic style | `caveman ultra` |
+| Back to normal | `stop caveman` |
+| Update template | `update the template` |
+| Activate project by path | `/active-project <path>` |
+
+---
+
+## 10. Decision tree — which skill to use
+
+```
+You have...                              Use...
+─────────────────────────────────        ──────────────────────────────────
+Empty folder (new project)               scaffold the backend
+Legacy project, first adoption           duk install + edit CLAUDE.md
+Legacy project at a known path           /active-project <path>
+Vague feature idea                       grill me about <X>
+DISCOVERY done, missing PRD              generate PRD
+PRD done, want issues                    break into issues
+PRD done, want technical PLAN            analyst, produce the plan
+PLAN with sprints defined                run sprint <N>
+Task implemented, want gate              run the tests
+Sprint complete                          integration test
+Everything green, before release         ready for production?
+Obscure/intermittent bug                 let's debug <X>
+Obsolete stack version                   migrate from <X> to <Y>
+Save a preference                        remember that <X>
+Sprint history                           record in the brain
+Sync with updated harness                update the template
+Conflict between 2 technical approaches  tech-lead, decide between <A> and <B>
+Security vuln suspicion                  security audit
+Don't know which skill fits              just type the request — project-manager catches it
+```
+
+---
+
+## 11. Minimal `CLAUDE.md` configuration
+
+This is the section you edit. **Don't touch the rest** — `update-template`
+overwrites everything except this.
+
+```markdown
+## Project Identity
+
+- **Project name**: `my-backend-api`
+- **Project type**: `backend`
+- **Primary stack**: `Java 25 + Spring Boot 4`
+- **Database**: `PostgreSQL 17 + Redis 7`
+- **Domain**: `e-commerce`
+- **Team size**: `3 backend`
+- **Additional rules**: _(leave empty if none)_
+```
+
+Tips:
+
+- `Project type: backend` unlocks `bootstrap-backend-java`.
+  For mobile/frontend/fullstack, adjust and use the matching bootstrap.
+- `Primary stack` must mention `Java <N>` so the scaffold picks the right
+  JDK.
+- `Database` is used by `database-engineer` to choose dialect and
+  Testcontainer image.
+- `Additional rules` accepts free text — things like "SOX audit
+  mandatory", "deploy only in the 22h-04h window", etc.
+
+---
+
+## 12. Antipatterns — what NOT to do
+
+| ❌ Wrong | ✓ Right |
+|---|---|
+| `duk project-manager "create endpoint"` | type `create endpoint POST /products` in chat |
+| `duk grill-me` | type `grill me about <X>` in chat |
+| Skipping `grill-me` and going straight to `analyst` (human path) | always go through discovery |
+| Forcing an implementation while ignoring `gate-keeper` | wait for the gate to pass before moving on |
+| Commit with `Co-Authored-By: Claude` | commit as a human author (CLAUDE.md forbids it) |
+| Mentioning Claude/AI/LLM in commit subject/body | Conventional Commit, no trace of AI |
+| `@Entity` exposed in controller | always a record DTO (separate req/res) |
+| H2 in tests | `Testcontainers` with real Postgres |
+| `// TODO` in committed code | `docs/brain/architecture/tech-debt.md` |
+| Hardcoded credentials | `C:\development\tools\credentials\vps.txt` |
+| `var` in a public method signature/return | explicit type |
+| Inline `@Transactional` floating in a controller | service method with `@Transactional(readOnly=true)` |
+| `permitAll()` in prod | RBAC with `@PreAuthorize` + CORS per domain |
+| Log of token/PII/password | never log it — `security-engineer` vetoes |
+| Flyway migration without index | index in the same `V<N>__*.sql` that creates the FK |
+
+---
+
+## 13. Backend troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `Address already in use: 8080` | Previous app hung | `netstat -ano | findstr :8080` + `taskkill /PID <pid> /F` |
+| `java: invalid target release: 25` | Wrong JDK on PATH | `sdk use java 25.0.0-tem` or fix `JAVA_HOME` |
+| `Flyway: Found non-empty schema(s)` | Local DB dirty from a previous test | `docker compose down -v && docker compose up -d` |
+| `Flyway lock not released` | Aborted migration | `UPDATE flyway_schema_history SET success=true WHERE installed_rank=<n>` or drop schema |
+| CORS blocks the frontend call | `permitAll()` or origin not listed | configure `addAllowedOriginPattern` in `WebMvcConfigurer` |
+| Secret committed by mistake | `application.yml` with real password | rebase + `git filter-repo` + rotate credential |
+| `sprint-runner` doesn't delegate | PLAN without goal-ready DoD | re-run `analyst` with a valid DISCOVERY |
+| `gate-keeper` fails on coverage | JaCoCo not configured in pom | check `jacoco-maven-plugin` + `prepare-agent` goal |
+| Mutation score < 70% | Tests only check getters/setters | write business-rule tests in `domain/` |
+| OWASP fails with CVE ≥ 7.0 | Vulnerable dependency | bump the version; if unfeasible, acceptance ADR signed by `security-engineer` |
+| `Testcontainers` slow on the first run | postgres image not cached | `docker pull postgres:17` ahead of time |
+| 401 on an endpoint that should be public | Too-generic SecurityFilterChain | explicit `requestMatchers("/api/v1/public/**").permitAll()` |
+| `LazyInitializationException` in production | Missing `@Transactional` | add `@Transactional(readOnly=true)` in the query service |
+| Local build OK, CI fails | Plugin pinned to incompatible version | check `pom.xml` against the CI matrix |
+
+---
+
+## 15. Active hooks (summary)
+
+The `.claude/settings.json` installed by `duk install` activates four hooks
+that run automatically:
+
+- **UserPromptSubmit** — runs at prompt submit
+  of every prompt so agents respect preferences without repetition.
+- **PreToolUse `Bash`** — blocks commands that delete test files
+  (`rm src/test/...`, etc.). Hard fail.
+- **PostToolUse `Write`** — runs Prettier on freshly-written `.json`/`.md`
+  files and injects a "write the matching test" reminder.
+- **Stop** — at the end of each turn, saves a project-context summary to
+  
+
+Details: [Hooks reference](../docs/hooks-reference).
+
+---
+
+## 16. Quick glossary
+
+| Term | Short definition |
+|---|---|
+| Skill | `.claude/skills/<name>/SKILL.md` file. Entry point by keyword. |
+| Agent | `.claude/agents/<name>.md` file. Executor invoked by a skill via the Task tool. |
+| Task tool | Claude Code built-in. Skills use it to delegate to agents. |
+| DISCOVERY | `docs/discovery/DISCOVERY_<X>.md`, output of `grill-me`. |
+| PRD | `docs/prd/PRD_<X>.md`, product document. Output of `to-prd`. |
+| ISSUES | `docs/issues/ISSUES_<X>.md`. Output of `to-issues`. |
+| PLAN | `docs/plans/PLAN_<X>.md`. Technical plan with sprints and goal-ready DoD. |
+| ADR | `docs/decisions/ADR-NNN-<slug>.md`. Recorded technical decision. |
+| Goal-ready DoD | Definition of Done expressed as a verifiable objective (not a checklist). |
+| Senior+ gate | Set of thresholds in `auto-test-guard` + `gate-keeper`