@eltonssouza/development-utility-kit 1.0.0

package/.claude/skills/run-sprint/SKILL.md

@@ -0,0 +1,342 @@
+---
+name: run-sprint
+description: Use when an approved development plan exists (in docs/plans/PLAN_*.md) and the user asks to execute a specific sprint. Triggers on phrases like "run sprint 1", "execute sprint 2 of plan X", "implement the current sprint tasks", "let's code this sprint", "take PLAN_product_registration and run sprint 1". This skill does NOT create a plan — it CONSUMES a plan. To create a plan use analyst. This skill does NOT validate for PRD — it implements. For the final gate use prd-ready-check. Do NOT use to create a development plan (use analyst) nor to validate PRD-readiness (use prd-ready-check). PT triggers: 'roda a sprint 1', 'executa a sprint', 'implementa as tarefas da sprint', 'bora codar essa sprint'.
+---
+
+# Run Sprint — Sprint Execution from a Plan
+
+You are the sprint executor. Always respond in American English.
+
+Your mission: read a plan in `docs/plans/PLAN_<NAME>.md`, locate the indicated sprint, implement each task ~ dependencies, validate, and report.
+
+---
+
+## 0. Input
+
+- **Plan**: path to `docs/plans/PLAN_<NAME>.md` (mandatory).
+- **Sprint**: sprint number or name (mandatory). Ex.: "Sprint 1", "2", "backend-base".
+
+If anything is missing, ask before starting.
+
+---
+
+## Step 0 — Stack pre-resolution (NON-NEGOTIABLE, per ADR-026 Layer 1)
+
+**Runs BEFORE every other phase in this skill.** Determines which stack pack must be injected into the prompt of every downstream agent spawned by this orchestrator. Without this step, downstream agents (`backend-developer`, `frontend-developer`, `qa-engineer`, `gate-keeper`, `database-engineer`) fall back to baked-in defaults that may not match the project's actual stack (e.g. Spring Boot 3.2 vs 4, Angular 18 vs 21).
+
+### 0.a — Invoke `stack-resolver`
+
+```
+Task(
+  subagent_type="stack-resolver",
+  description="resolve stack for project",
+  prompt="Resolve the stack for the project at the current working directory. Read CLAUDE.md > Project Identity, identify primary stack (lang + framework + major version), check whether the matching pack exists under .claude/stacks/<lang>/<framework>-<major>.md, and emit the canonical STACK CONTEXT block as your output."
+)
+```
+
+### 0.b — Parse the resolver output
+
+The resolver's first line is the marker:
+
+- `[STACK: <lang>/<framework>-<major> | PACK: loaded]` — extract the full **STACK CONTEXT** block from the body and keep it in memory for Step 4 onward. Proceed to Phase 1.
+- `[STACK: <lang>/<framework>-<major> | PACK: none]` — the project's declared stack has no pack yet. **Stop the sprint orchestration** and dispatch the `create-stack-pack` skill:
+  ```
+  Skill(name="create-stack-pack")
+  ```
+  Once the pack has been generated and committed, **repeat Step 0.a**. Do NOT proceed without a loaded pack — running downstream agents with stale defaults is a silent quality regression.
+- `[STACK: unknown | ...]` or no marker — the resolver could not parse `Project Identity`. Report this back to the user and ask them to populate `## Project Identity` in `CLAUDE.md` (project name, type, primary stack, database). Do not proceed.
+
+### 0.c — Capture the STACK CONTEXT for downstream injection
+
+Store the entire STACK CONTEXT block returned by the resolver (versions, structure conventions, build commands, anti-patterns, testing tooling). It will be **prepended to every downstream Task prompt** spawned by this skill (see §0.1 below).
+
+> Stage 0 runs before any of the example flows in this document — the examples in Phases 1–6 assume `<STACK CONTEXT>` has already been captured.
+
+---
+
+## 0.1 Mandatory delegation via Task tool (NON-NEGOTIABLE)
+
+This skill is an **orchestrator**, not an implementer. Every task in the sprint MUST be executed by spawning the matching specialist agent through the `Task` tool. Inline implementation in the orchestrator session is forbidden — wastes Opus tokens, defeats the model-per-agent matrix in CLAUDE.md.
+
+### Task type -> agent mapping
+
+| Task type | Agent (`subagent_type`) | Model |
+|---|---|---|
+| Backend (controller, service, DTO, persistence, migration) | `backend-developer` | sonnet |
+| Frontend (component, service, route, form) | `frontend-developer` | sonnet |
+| Frontend vanilla / React Native | `frontend-developer` / `mobile-developer` | sonnet |
+| DB schema / index / query optimization | `database-engineer` | sonnet |
+| Test generation + regression + senior+ gate | `gate-keeper` | sonnet |
+| Brain record at end of sprint | `brain-keeper` | sonnet |
+
+### Required call form — STACK CONTEXT injection mandatory
+
+Every Task dispatch from this skill MUST prepend the STACK CONTEXT block captured in Step 0.c to the prompt. Template:
+
+```
+Task(
+  subagent_type="backend-developer",
+  description="<3-5 words>",
+  prompt="""
+<STACK CONTEXT block from Step 0.c — full content, verbatim>
+
+---
+
+Task <N> of sprint <S>: <task description from plan>
+Acceptance criteria: <list>
+Files touched: <list or 'detect via git'>
+Run the stack's build + relevant test before returning (commands from STACK CONTEXT).
+Return: list of files created/modified + test commands run.
+Your first output line MUST be: [STACK: <lang>/<framework>-<major> | PACK: loaded]
+"""
+)
+```
+
+The same template applies to `frontend-developer`, `qa-engineer`, `database-engineer`, `gate-keeper`, and `brain-keeper` dispatches. The STACK CONTEXT is the contract that prevents version drift (per ADR-026 Layer 1).
+
+### Inviolable
+
+- Orchestrator (this skill) only: read plan, route, render checkpoints, aggregate reports.
+- Code, migrations, tests = always inside spawned agents.
+- Direct `Bash(...)` in orchestrator only for fast verification of agent output (e.g., the stack's `compile`/`build` command after an agent claims completion).
+- Every spawned agent receives STACK CONTEXT as the first block of its prompt. No exceptions.
+
+---
+
+## 1. Phase 1 — Plan analysis
+
+1. Read the full plan.
+2. Locate the indicated sprint.
+3. Extract:
+ - Ordered task list
+ - Dependencies (task X depends on task Y)
+ - Acceptance criteria per task
+ - Suggested agent/specialist per task
+ - User stories covered by the sprint
+5. **CHECKPOINT**: present to the user:
+ - Sprint summary (N tasks, X user stories)
+ - Proposed execution order
+ - Dependencies between tasks
+ - Known risks
+ - Ask: "Proceed?"
+
+Only continue with OK.
+
+---
+
+## 2. Phase 2 — Code reconnaissance
+
+Before writing a line, understand the current code. Use the structure conventions from the STACK CONTEXT (Step 0.c) to know where to look:
+
+1. Backend package/module structure (per STACK CONTEXT pack)
+2. Frontend module structure (per STACK CONTEXT pack)
+3. Existing migrations (location per STACK CONTEXT pack)
+4. Routes (location per STACK CONTEXT pack)
+5. Existing tests: patterns, conventions, helpers
+
+Identify:
+- Impacts (which files will be touched).
+- Technical dependencies (libraries already installed or that need to be added).
+- Potential conflicts (does any module already do something similar?).
+
+---
+
+## 3. Phase 3 — Detailed planning
+
+Build the **real execution order**, respecting dependencies. Example shape (concrete paths come from the STACK CONTEXT pack):
+
+```
+Sprint 1 — Execution order:
+ 1. [backend] Migration V001__create_products_table
+ 2. [backend] Product entity + Repository
+ 3. [backend] DTOs + Mapper + RegisterProduct use case
+ 4. [backend] Controller + error advice
+ 5. [backend] Unit + integration tests
+ 6. [frontend] Model + HTTP service
+ 7. [frontend] List component + lazy route
+ 8. [frontend] Reactive form component
+ 9. [frontend] Frontend tests
+```
+
+**CHECKPOINT**: show the order. "Proceed with implementation?"
+
+Only continue with OK.
+
+---
+
+## 4. Phase 4 — Implementation (task by task)
+
+For EACH task, in order:
+
+1. **Announce**: "Starting task X of N: <description>".
+2. **TDD step — spawn `qa-engineer` FIRST** (NEVER skip — NON-NEGOTIABLE). The prompt MUST be prefixed with the STACK CONTEXT captured in Step 0.c:
+   ```
+   Task(
+     subagent_type="qa-engineer",
+     description="write failing tests for task <N>",
+     prompt="""
+<STACK CONTEXT block from Step 0.c — full content, verbatim>
+
+---
+
+Write failing tests for task <N> of sprint <S>: <task description>
+Acceptance criteria: <list from plan>
+Tests must be RED (failing) before implementation starts.
+Use the testing tooling declared in the STACK CONTEXT (test runner, assertion libs, integration test infra).
+Return: list of test files created + confirmation tests are failing.
+Your first output line MUST be: [STACK: <lang>/<framework>-<major> | PACK: loaded]
+"""
+   )
+   ```
+   Wait for `qa-engineer` to confirm tests are written and failing before proceeding to step 3.
+3. **Implementation step — spawn developer** via `Task` tool (NEVER inline), with STACK CONTEXT prepended:
+   - Backend task -> `Task(subagent_type="backend-developer", prompt="""<STACK CONTEXT>\n\n---\n\n<task body>""")`
+   - Frontend task -> `Task(subagent_type="frontend-developer", prompt="""<STACK CONTEXT>\n\n---\n\n<task body>""")`
+   - Migration/data model -> `Task(subagent_type="database-engineer", ...)` then `Task(subagent_type="backend-developer", ...)` for the entity wiring (both prompts carry STACK CONTEXT)
+   - Each spawn returns a structured report (files created/modified, commands run). Aggregate.
+   - **Post-hoc validation (ADR-026 Layer 3)**: confirm the first line of the agent's output matches `[STACK: <expected> | PACK: loaded]`. If absent, re-invoke once with an enforcing reminder.
+4. **Do not advance** to the next task until the current one is:
+   - Code complete (no TODO)
+   - Compiling (run the stack's compile/build command from STACK CONTEXT)
+   - Tests passing for that task (the failing tests from step 2 must now be GREEN)
+5. **Parallelize backend and frontend** ONLY when:
+   - The API contract (endpoint + DTOs) is defined and agreed upon
+   - There is no direct dependency between the touched files
+   - Both `qa-engineer` spawns (for backend and frontend respectively) complete before their paired developer agents start
+
+### 4.1 Golden rule: do not "implement and pray"
+
+After each task, **mandatorily spawn** `gate-keeper` with STACK CONTEXT prepended:
+
+```
+Task(
+  subagent_type="gate-keeper",
+  description="validate task <N>",
+  prompt="""
+<STACK CONTEXT block from Step 0.c — full content, verbatim>
+
+---
+
+Validate task <N> of sprint <S> at senior+ gate.
+Generate any additional automated tests for the new code, run the full regression suite using the STACK CONTEXT's commands, and report GREEN/RED.
+Your first output line MUST be: [STACK: <lang>/<framework>-<major> | PACK: loaded]
+"""
+)
+```
+
+1. It **generates** any additional automated tests for the new code (unit + integration + E2E as appropriate) beyond those written by `qa-engineer`.
+2. It **runs the FULL regression suite** of the project using the test commands declared in the STACK CONTEXT pack.
+3. **RED return** = task not done. Go back, fix, run the suite again. Never accumulate failures.
+4. **GREEN return** = you can mark the task as done and move to the next.
+
+Manual shortcuts (exploratory only, **do not replace** auto-test-guard) — use the per-test commands from the STACK CONTEXT pack.
+
+---
+
+## 5. Phase 5 — Sprint validation
+
+When all sprint tasks are done:
+
+1. **Spawn `gate-keeper`** (with STACK CONTEXT prepended) one last time in the scope of the entire sprint. It:
+ - Confirms that the full regression suite is **green** (using the stack's full suite commands from STACK CONTEXT).
+ - Generates any missing tests discovered when stitching the tasks together.
+ - If it returns RED — **the sprint is not done**. Go back to phase 4.
+2. **Run lint** (complementary): the lint commands declared in the STACK CONTEXT pack.
+3. **Verify the sprint's acceptance criteria** (listed in the plan) one by one.
+4. **Validate user stories** covered by the sprint. Each US must have a corresponding green test.
+5. If everything is OK, proceed to the report. If something failed, **do not report success** — go back to phase 4 and fix.
+
+---
+
+## 5.1 Phase 5.1 — Brain record (brain-keeper)
+
+After `auto-test-guard` GREEN on the sprint:
+
+1. **Spawn** `brain-keeper` with STACK CONTEXT prepended:
+   ```
+   Task(
+     subagent_type="brain-keeper",
+     description="record sprint <N>",
+     prompt="""
+<STACK CONTEXT block from Step 0.c — full content, verbatim>
+
+---
+
+Record outcome of sprint <N> of <PLAN_path>: tasks done, files, ADRs, debt.
+Your first output line MUST be: [STACK: <lang>/<framework>-<major> | PACK: loaded]
+"""
+   )
+   ```
+2. Provisions `docs/brain/` on the first run with `.obsidian/` + per-folder color snippet.
+3. Records:
+   - `daily/YYYY-MM-DD.md` — daily log (append in `## Update HH:MM` if it already exists).
+   - `features/<plan-slug>.md` — updates sprint progress (status: `in-progress` if not the last sprint, `completed` if it is).
+   - `decisions/ADR-NNN-*.md` — if there was a new architectural decision.
+   - `bugs/<slug>.md` — if there was a relevant fix.
+   - `architecture/tech-debt.md` — append the accepted debt.
+4. Idempotent — running it twice does not duplicate.
+
+The sprint **only closes** after brain-keeper returns an OK report.
+
+---
+
+## 6. Phase 6 — Sprint report
+
+Print:
+
+```
+## Sprint <N> — <name> — Completed
+
+### Stack
+- <lang>/<framework>-<major> (pack: loaded)
+
+### Tasks
+- [x] 1. <description> -> files: <list>
+- [x] 2. ...
+
+### Files
+- Created (N):
+ - <paths>
+- Modified (M):
+ - <paths>
+- Deleted (K):
+ - (none | list)
+
+### Tests
+- Backend: N tests (X unit, Y integration) — ALL passing
+- Frontend: M tests — ALL passing
+- Domain coverage: Z%
+
+### User Stories covered
+- [x] US-01
+- [x] US-02
+- [ ] US-03 (deferred to sprint N+1)
+
+### Technical decisions made
+- ...
+- If a new decision was made: ADR-NNN created at
+
+### Accepted technical debt
+- ...
+
+### Next steps
+- Sprint N+1 of plan PLAN_<NAME>.md
+```
+
+---
+
+## 8. Inviolable rules
+
+1. **Stage 0 (Stack pre-resolution) is non-skippable.** No Task dispatch happens before STACK CONTEXT is captured. Pack missing -> `create-stack-pack` first.
+2. **Every downstream Task dispatch carries STACK CONTEXT as the first block of its prompt.** No exceptions.
+3. **Do not skip phases.** Checkpoints in phases 1 and 3 are mandatory.
+4. **One task at a time**, respecting dependencies.
+5. **Complete code, no TODO**, with tests that validate the behavior.
+6. **Follow CLAUDE.md** and the project conventions.
+7. **NEVER delete, disable (`@Disabled`/`.skip()`/`xit`/`it.skip`), comment out, or move out of scope a test to make a gate pass — NON-NEGOTIABLE.** A red test means: (a) fix the production code, OR (b) fix the test if it is genuinely wrong (requires an ADR justifying why), OR (c) report it as a real failure and stop. Deleting a failing test is a silent bypass of the senior+ gate — the exact opposite of this skill's purpose. The hook `block-test-deletion.sh` enforces this at the filesystem level, but the rule stands even where the hook cannot reach (e.g. an Edit adding `@Disabled`).
+8. **If a test breaks, fix it** — never comment it out or delete it (see rule 7).
+9. **If the sprint has ambiguity** that the plan did not resolve, ask the user BEFORE implementing.
+10. **Every completed task goes through `auto-test-guard`** (generates tests + runs the full suite). There is no "task done" without its GREEN return.
+11. **Sprint only closes after `brain-keeper`** records daily + feature + ADRs in `docs/brain/`. Project history is part of the deliverable.
+12. **`qa-engineer` precedes every developer agent** — spawn `qa-engineer` to write failing tests BEFORE spawning `backend-developer` or `frontend-developer`. No implementation without pre-existing failing tests. This rule applies universally to all plans, including those created before this rule was introduced.
+

package/.claude/skills/scaffold/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: scaffold
+description: "Unified entry point for new project scaffolding. Triggers when user wants to create a new project skeleton — backend, frontend, or fullstack. Keyword triggers: 'scaffold the project', 'scaffold backend', 'scaffold frontend', 'scaffold backend and frontend', 'create fullstack skeleton', 'bootstrap fullstack', 'bootstrap backend', 'bootstrap frontend', 'monta o esqueleto', 'scaffolda o projeto', 'monta a estrutura', 'cria o esqueleto', 'inicializa o backend', 'inicializa o frontend', 'cria novo projeto', 'criar esqueleto do projeto', 'criar estrutura do projeto'. Reads `type:` from `## Project Identity` section in CLAUDE.md. DO NOT use for feature implementation after scaffold — use backend-developer / frontend-developer."
+---
+
+# Scaffold — Unified Project Scaffolding Entry Point
+
+This skill is the single entry point for all project scaffold operations.
+It reads the project type from CLAUDE.md and dispatches to the `scaffold` agent.
+
+## When to trigger
+
+Use this skill at the **very first conversation** of a new project, before any Java or Angular code exists. Scenarios:
+
+- "scaffold the project" / "scaffolda o projeto"
+- "monta a estrutura" / "monta o esqueleto"
+- "create fullstack skeleton" / "cria o esqueleto" / "bootstrap fullstack"
+- "scaffold the backend" / "bootstrap backend" / "inicializa o backend"
+- "scaffold the frontend" / "bootstrap frontend" / "inicializa o frontend"
+- "create new project" / "cria novo projeto"
+- Any variant: "criar esqueleto do projeto", "criar estrutura do projeto", "monta o monorepo"
+
+## Prerequisites
+
+1. The project's `CLAUDE.md` must exist at the project root.
+2. The `## Project Identity` section must have `- **Project type**: \`backend\`` | `\`frontend\`` | `\`fullstack\``.
+3. The project folder must be under `C:\development\source\projects\<name>\`.
+4. No `backend/pom.xml`, `frontend/angular.json`, or `frontend/package.json` exists yet (idempotent guard is in the agent).
+
+If `Project type` is missing or unrecognized, the `scaffold` agent routes to `tech-lead` automatically.
+
+## Do NOT use for
+
+- Implementing features after scaffold is complete — use `backend-developer` / `frontend-developer`.
+- Migrating an existing project to a newer stack — use `migrator`.
+- Updating the harness template — use `update-template`.
+- Adopting the template in an existing project — use `active-project`.
+
+## Dispatch
+
+```
+Task(
+  subagent_type: "scaffold",
+  description: "Scaffold the project. Read ## Project Identity from CLAUDE.md, detect project type, run the appropriate pipeline (backend | frontend | fullstack).",
+  prompt: "<full user message>"
+)
+```
+
+The `scaffold` agent (`.claude/agents/scaffold.md`, model: haiku) handles:
+- Reading `## Project Identity` → parsing `Project type:` value.
+- Running the Spring Initializr pipeline (backend), Angular CLI pipeline (frontend), or both (fullstack).
+- Smoke builds and final report.
+
+## Handoff
+
+After dispatch, the `scaffold` agent handles execution autonomously. All decisions about Java packages, ports, optional dependencies are resolved by the agent (it may ask the user for missing values per its inviolable rules).
+
+See `.claude/agents/scaffold.md` for the complete execution contract, pipeline steps, and inviolable rules.

package/.claude/skills/stack-discovery/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: stack-discovery
+description: "Conversational sabatina for NEW projects with empty Project Identity in CLAUDE.md. Walks user through 5-8 focused questions to declare language, framework, version, database, UI lib, domain. Each question comes with a recommended answer + 1-line rationale (same UX pattern as grill-me, but focused on stack rather than feature requirements). Persists results to ## Project Identity in CLAUDE.md. If the chosen stack has no matching pack in .claude/stacks/, dispatches create-stack-pack skill. Triggers: 'sabatina pra projeto novo', 'stack discovery', 'ajuda escolher stack', 'configura stack', 'duk new chat', auto-triggered after duk new <name> creates empty Project Identity. Do NOT use for feature discovery (use grill-me), to migrate stack of existing project (use migrator), or for code implementation. PT triggers: 'sabatina pra projeto novo', 'discovery da stack', 'configura stack do projeto', 'duk new chat'."
+---
+
+# Stack-discovery — conversational sabatina for new projects
+
+> Sonnet conversational skill. Walks the human through declaring the project's stack — language, framework, version, database, UI lib, domain — and persists the answers to `## Project Identity` in `CLAUDE.md`. UX mirrors `grill-me`: one focused question per turn, each with a recommended answer + 1-line rationale.
+
+---
+
+## 1. When you trigger
+
+- "sabatina pra projeto novo", "stack discovery", "ajuda escolher stack", "configura stack", "duk new chat".
+- Auto-triggered after `duk new <name>` scaffolds a project with empty `## Project Identity` placeholders (`<project-name>`, etc.).
+- Manual invocation when adopting a new project where the stack is not yet declared.
+
+## 2. When you do NOT trigger
+
+- Project already has a populated `## Project Identity` -> use `update-template` to refresh harness files.
+- Existing project changing stack (Java 21 -> 25, Angular 19 -> 21) -> use `migrator`.
+- Feature requirements discovery -> use `grill-me`.
+- Implementation -> use `run-sprint` / specialist agents.
+- Scaffold the project skeleton -> use `scaffold` skill (run AFTER this skill finishes).
+
+## 3. Prerequisites
+
+- `CLAUDE.md` exists at project root with the harness template's `## Project Identity` section.
+- An engaged human (this is conversational — never invoke from `sprint-runner` or CI).
+
+## 4. Flow
+
+### Step 1 — Frame
+
+Open with a 1-line intro: "Vou entrevistar sobre stack — 6-8 perguntas, uma por turno. Persisto tudo em CLAUDE.md no fim."
+
+### Step 2 — Sabatina (8 questions, one per turn)
+
+Each question follows the grill-me pattern: question + recommended answer + 1-line rationale + "Confirm?". Default by context (if user said "API backend" earlier, default Q2 to `java`).
+
+**Q1 — Project type**
+> Tipo de projeto: `backend` / `frontend` / `fullstack` / `mobile` / `library` / `cli`?
+> Recomendo: **fullstack** (se você vai ter API + UI integradas). Confirme?
+
+**Q2 — Language**
+> Linguagem principal: `java` / `typescript` / `python` / `go` / `rust` / `kotlin`?
+> Recomendo: **java** para backend corporativo (ecossistema maduro, equipe domina). Confirme?
+
+**Q3 — Framework**
+> Framework: `spring-boot` / `quarkus` / `micronaut` (Java) | `angular` / `react` / `vue` (TS) | `django` / `fastapi` (Python) | `gin` / `echo` (Go)?
+> Recomendo: **spring-boot** (defaults do harness, packs prontos). Confirme?
+
+**Q4 — Major version**
+> Versão major: para Spring Boot, `3` (Java 17/21, legado mantido) ou `4` (Java 25, novos)?
+> Recomendo: **4** para projeto novo (target da equipe, packs canônicos). Confirme?
+>
+> _Nota: stack-discovery PODE consultar Maven Central / npm registry pra confirmar a última GA. Fallback é o hardcoded em `scripts/latest-versions.json`._
+
+**Q5 — Database (if backend / fullstack)**
+> SGBD: `postgresql` / `mysql` / `mongodb` / `none`?
+> Recomendo: **postgresql** (default do harness — UUID, JSONB, transações ACID). Confirme?
+
+**Q6 — UI library (if frontend / fullstack / mobile)**
+> Lib de UI: `ng-bootstrap` / `material` / `primeng` (Angular) | `mui` / `chakra` / `tailwind` (React)?
+> Recomendo: **ng-bootstrap** (default do harness, a11y WCAG 2.1 AA). Confirme?
+
+**Q7 — Domain**
+> Domínio do produto: e-commerce / fintech / healthcare / SaaS interno / marketplace / outro?
+> Recomendo: marque o que mais aproxima — usado em prompts de geração e ADRs. Confirme?
+
+**Q8 — Team size**
+> Tamanho do time: solo / 2-3 devs / 4-10 devs / 10+?
+> Recomendo: **2-3 devs** (calibra Autonomy Matrix, ritmo de PR, gate rigor). Confirme?
+
+### Step 3 — Latest version detection (opcional, automático)
+
+Antes de fechar a sabatina, se `Q3 + Q4` apontam para uma stack com versão major declarada, consulte (silenciosamente) Maven Central / npm registry para confirmar a última GA daquela major. Se diferir do que o user respondeu, retorne 1 pergunta de confirmação: "Detectei que Spring Boot 4.0.2 é a última GA — usar essa versão na CLAUDE.md? Recomendo: sim."
+
+Fallback determinístico: `scripts/latest-versions.json` (hardcoded no harness).
+
+### Step 4 — Confirm
+
+Mostre o bloco `## Project Identity` proposto e peça OK final:
+
+```markdown
+## Project Identity
+
+- **Project name**: `meu-projeto`
+- **Project type**: `fullstack`
+- **Primary stack**: `Java 25 + Spring Boot 4.0.2 + Angular 21`
+- **Database**: `PostgreSQL 17 + Redis 7`
+- **Domain**: `e-commerce`
+- **Team size**: `2-3 devs`
+- **Additional rules**: _(vazio)_
+```
+
+### Step 5 — Persist (MANDATORY)
+
+Use `Edit` para substituir SOMENTE a seção `## Project Identity` em `CLAUDE.md`. Demais seções permanecem intactas (base do plugin). Validar via `Read` pós-Edit.
+
+### Step 6 — Pack check + handoff
+
+1. Resolva pack esperado: `.claude/stacks/<lang>/<framework>-<major>.md`.
+2. **Se pack existe** -> imprima sucesso + próximos passos (ver §Output).
+3. **Se pack ausente** -> dispatch `create-stack-pack` skill ANTES de finalizar:
+   > "Pack `.claude/stacks/java/spring-boot-5.md` não existe. Disparando `create-stack-pack` para gerar antes de continuar."
+   Depois que `create-stack-pack` retorna, feche com o output normal.
+
+## 5. Inviolable rules
+
+1. **Sabatina conversacional, opt-in.** Nunca rode em CI, `sprint-runner`, ou qualquer fluxo autônomo.
+2. **Uma pergunta por turno, sempre com recomendação.** Nunca dump de lista, nunca pergunta aberta sem default.
+3. **Persistência obrigatória.** Sessão não fecha sem `## Project Identity` preenchida em `CLAUDE.md`.
+4. **Edit cirúrgico.** Só toca em `## Project Identity` — preserva todo o resto do template (override do plugin).
+5. **Pack ausente bloqueia handoff.** Dispatch `create-stack-pack` antes do output final.
+6. **Nunca decide stack pelo user.** Recomenda, mas o user confirma a cada Q.
+7. **No implementation.** Esta skill só descobre + persiste — código vem do `scaffold` skill depois.
+
+## 6. Output
+
+Bloco final em chat:
+
+```
+✓ Project Identity persistida em CLAUDE.md
+✓ Pack resolvido: .claude/stacks/java/spring-boot-4.md (loaded)
+
+Próximos passos sugeridos:
+  1. Rode 'scaffolda o projeto' para gerar a estrutura inicial (backend + frontend).
+  2. Quando tiver primeira feature em mente, rode 'grill me sobre <feature>' pra discovery.
+  3. Depois, 'analyst' gera PLAN -> 'sprint-runner' executa.
+```
+
+Se pack faltava e foi gerado:
+
+```
+✓ Project Identity persistida em CLAUDE.md
+✓ Pack criado via create-stack-pack: .claude/local/stacks/java/spring-boot-5.md
+   Considere abrir PR pro harness repo (development-utility-kit) pra reusar.
+
+Próximos passos:
+  1. Rode 'scaffolda o projeto' para gerar a estrutura inicial.
+```
+
+## 7. Interface with other skills/agents
+
+- `scaffold` — handoff natural após esta skill (gera esqueleto baseado em `## Project Identity`).
+- `create-stack-pack` — disparado SE pack ausente para a stack escolhida.
+- `stack-resolver` — agente Haiku que valida o pack pós-persistência (usado pelas skills downstream).
+- `grill-me` — fase seguinte, quando user tem primeira feature em mente.
+- `update-template` — não invocar daqui; é caminho separado para sincronizar harness em projeto já adotado.
+- `migrator` — não confundir: este é para projeto NOVO; migrator é para mudar stack de projeto existente.
+
+## 8. References
+
+- ADR-026 (Generic agents + stack packs — fundação)
+- ADR-028 (duk workflow — esta skill é o passo "new chat" do fluxo)
+- ADR-029 (Pack canonical format — o que `create-stack-pack` deve gerar)
+- `.claude/skills/grill-me/SKILL.md` (padrão UX de sabatina reusado aqui)
+- `scripts/latest-versions.json` (fallback de versões hardcoded)

package/.claude/skills/test-coverage-auditor/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: test-coverage-auditor
+description: Use to AUDIT the project's automated test coverage and flag TECHNICAL DEBT from manual verification. Triggers on "audit the tests", "is there test debt?", "is coverage ok?", "what depends on manual testing here?", "do a coverage audit", "list what has no test", "look for test debt". Also called automatically by `run-sprint` (Stage 5) and is a mandatory prerequisite of `prd-ready-check`. Scans backend code (controllers, services, domain) and frontend code (components, HTTP services, guards), checks whether matching automated tests exist (JUnit/Mockito/Testcontainers or Jest/Testing Library/Playwright), reads recent dailies and feature notes looking for "tested manually", "checked in the browser", "deployed and tested", and emits a debt report. Updates `docs/brain/architecture/tech-debt.md` and creates notes in `docs/brain/bugs/` for critical debt items. Does NOT implement tests — only flags them. To write the tests, use `backend-developer` / `frontend-developer` / `qa-engineer`. Do NOT use to write tests (use those specialists) nor to run the regression suite (use auto-test-guard). PT triggers: 'audita os testes', 'tem débito de teste?', 'cobertura tá ok?', 'o que depende de teste manual aqui?', 'faz auditoria de cobertura', 'lista o que não tem teste', 'procura débito de teste'.
+---
+
+# Test Coverage Auditor — Test technical debt detector
+
+Skill that invokes the `test-coverage-auditor` agent. Always respond in American English.
+
+---
+
+## When to trigger
+
+**Explicit**:
+- "audit the tests", "is there test debt here?", "is coverage ok?"
+- "what depends on manual testing?", "look for test debt", "list what has no test"
+- "do a coverage audit"
+
+**Automatic**:
+- `run-sprint` Stage 5 — mandatory gate between integration (Stage 4) and PRD-ready (Stage 6).
+- `prd-ready-check` — production gate requires an up-to-date report with no open P0/P1.
+
+---
+
+## Prerequisites
+
+- Project has `backend/` and/or `frontend/` directories with source code.
+- `CLAUDE.md` exists at the project root with `## Project Identity` declaring the project type.
+
+---
+
+## Do NOT use for
+
+- Writing tests — use `qa-engineer` / `backend-developer` / `frontend-developer`.
+- Running the regression suite — use `gate-keeper` (auto-test-guard skill).
+- Performance or security audits — use `security-engineer` for those.
+
+---
+
+## Dispatch
+
+```
+Task(
+  subagent_type: "test-coverage-auditor",
+  description: "Audit test coverage and flag technical debt. Scan backend and frontend code, identify classes/components without tests, check JaCoCo/Jest thresholds, classify debt P0-P3, update tech-debt.md.",
+  prompt: "<full user message>"
+)
+```
+
+---
+
+## Handoff
+
+The `test-coverage-auditor` agent (`.claude/agents/test-coverage-auditor.md`, model: sonnet) owns the complete execution contract:
+- Backend and frontend scan methodology (source ↔ test mapping).
+- JaCoCo and Jest coverage threshold enforcement.
+- P0/P1/P2/P3 severity classification.
+- tech-debt.md update and bug note creation for P0 items.
+- Full audit report format and PRD gate verdict.