@eltonssouza/development-utility-kit 1.0.0

package/.claude/skills/pair-debug/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: pair-debug
+description: "Pair-debug loop. Use when a bug is reported and the cause is not immediately obvious — typical for runtime errors, intermittent failures, integration mismatches, mysterious 4xx/5xx, missing data in DB after a write, console errors in the browser, race conditions, etc. Forces a disciplined cycle: state the symptom, formulate a hypothesis with a confidence level, choose ONE cheap probe to confirm/deny it (curl, log line, breakpoint, SELECT, browser console via Chrome MCP), gather the evidence, accept or reject the hypothesis, repeat. Bans 'tentar e ver' — every change must follow a tested hypothesis. DO NOT use for obvious bugs with obvious fixes (typo, missing import, syntax error — just fix it), for bugs that already have a solid pre-existing hypothesis, for features that were not yet implemented (use run-sprint), for proactive refactor (not a bug), or for performance tuning without a reported symptom (use dba or tech-lead). PT triggers: 'vamos debugar', 'pair debug', 'investiga esse bug', 'debug pair', 'achar a causa', 'investigar a falha', 'qual a causa raiz', 'descobrir por que', 'estranho, não funciona'."
+tools: Read, Glob, Grep, Bash(curl:*), Bash(grep:*), Bash(tail:*), Bash(head:*), Bash(jq:*), Bash(psql:*), Bash(docker logs:*), Bash(git log:*), Bash(git diff:*), Bash(git blame:*)
+model: sonnet
+---
+
+# Pair-debug — disciplined hypothesis-driven debugging
+
+> **Subagent dispatch (mandatory).** Debug loop runs in the calling session. For writing the confirming test (§3.5), dispatch to `qa-engineer` via Task tool. The disciplined loop below applies regardless.
+
+Your mission, in one line: **find the root cause of a bug by stating hypotheses with confidence, probing one at a time with cheap evidence, and refusing to fix anything until the cause is confirmed.**
+
+Principle: *"'tentar e ver' é debug sem disciplina — cada mudança no código sem hipótese testada vira ruído. Hipótese + probe + evidência + verdict = sinal."*
+
+---
+
+## 1. When you trigger
+
+- "vamos debugar X", "pair debug", "investiga esse bug", "achar a causa raiz", "por que isso não funciona"
+- Specialist está travado depois de 2+ tentativas
+- Bug reportado pelo `api-integration-test` ou pelo Chrome MCP console
+- Falha intermitente (passa 1x, falha outras vezes — sinal de race ou estado sujo)
+- 4xx/5xx misterioso, exception sem stack útil, dados sumindo do banco, console.error no front
+
+## 2. When you do NOT trigger
+
+- **Erro óbvio com fix óbvio** (typo, import faltando, sintaxe quebrada). Apenas conserta — debug ritual é overkill.
+- **Bug já tem hipótese sólida**: vai direto pro fix com confiança alta.
+- **Feature nova que ainda não foi implementada** — não é bug, é falta. Vá pro `run-sprint`.
+- **Falha de teste no `auto-test-guard`** se o erro for de assert claro — `auto-test-guard` já roteia pro specialist.
+
+## 3. The loop (5 fases, repete até convergir)
+
+### Stage 0 — Stack pre-resolution (per ADR-026 Layer 1)
+
+> **MANDATORY before §3.1 Symptom framing.** Resolves the project's stack so the debug loop chooses probes that make sense for the stack (e.g. `psql` for Postgres, `redis-cli` for Redis, `docker logs` for containerized services) and so any dispatch to `qa-engineer` for the confirming test (§3.5) inherits the right knowledge pack.
+
+Steps:
+
+a) Invoke `stack-resolver` via Task tool:
+
+```
+Task(
+  subagent_type: "stack-resolver",
+  description: "Resolve stack for project at CWD",
+  prompt: "resolve stack for project at CWD"
+)
+```
+
+b) Parse the first line of `stack-resolver` output:
+
+- **`[STACK: <lang>/<framework>-<major> | PACK: loaded]`** — extract the full `STACK CONTEXT` block. Store as `STACK_CONTEXT_BLOCK` for use in §3.5 dispatch and as guidance for probe selection in §3.3.
+- **`[STACK: <lang>/<framework>-<major> | PACK: none]`** — pack missing. Dispatch `create-stack-pack` skill conversationally; once the pack is created, repeat Stage 0a.
+
+c) Use `STACK_CONTEXT_BLOCK` to:
+- inform probe selection in §3.3 (which CLI tools, which build commands, which log format are idiomatic for this stack);
+- prefix every Task dispatch to `qa-engineer` / `backend-developer` / `frontend-developer` during §3.5 fix application.
+
+If `stack-resolver` cannot determine the stack, do NOT abort the debug — log a warning and proceed with generic probes:
+
+```
+Stack indeterminada (CLAUDE.md sem `Primary stack`). Seguindo com probes genéricas; considere preencher Project Identity para futuras sessões.
+```
+
+### 3.1. Estado o sintoma — uma frase, sem interpretação
+
+> "POST /api/v1/products retorna 500. Response body: ProblemDetail com detail='null pointer'."
+> "Login funciona uma vez; segundo login no mesmo browser fica em loop de redirect."
+> "Migration V12 roda local mas falha no CI com 'relation product_category does not exist'."
+
+Regras pro sintoma:
+- **Fato observado**, não suposição.
+- **1 sintoma por loop**. Se há 2, escolha o mais reproduzível primeiro.
+- **Reprodutível?** Se não, primeira hipótese tem que ser "como reproduzir isso de forma confiável".
+
+### 3.2. Formule hipóteses com confidence
+
+Liste 2-5 hipóteses do tipo "o sintoma acontece porque X". Cada uma com:
+
+| Campo | Conteúdo |
+|---|---|
+| `id` | H1, H2, ... |
+| `claim` | "X causa o sintoma porque Y" |
+| `confidence` | low / medium / high |
+| `evidence_required` | qual probe específica confirma ou descarta |
+| `cost_to_probe` | trivial (1 comando) / cheap (5min) / medium (30min) / expensive (>1h) |
+
+Exemplo:
+
+```
+H1: NullPointerException no controller porque o produto não tem categoria associada
+    confidence: medium
+    evidence_required: curl com produto sem categoria + log do stack trace na linha exata
+    cost_to_probe: trivial
+
+H2: Bean Validation @NotNull não está sendo aplicada porque o controller ignora @Valid
+    confidence: low
+    evidence_required: grep do controller — tem @Valid no parâmetro?
+    cost_to_probe: trivial
+
+H3: O mapper DTO -> entity está retornando null em caso de campo opcional
+    confidence: medium
+    evidence_required: teste unitário do mapper com input parcial
+    cost_to_probe: cheap (~5min)
+```
+
+**Regra inviolável**: nunca ataque a hipótese com `confidence: high` direto — pode estar enviesado. Probe a com `confidence: medium` primeiro pra calibrar.
+
+### 3.3. Escolha UMA probe — a mais barata por confidence
+
+Trade-off:
+- **Trivial probe** → tente primeiro mesmo se confidence é low; o custo de descartar é zero.
+- **Cheap probe** → se confidence ≥ medium.
+- **Medium/Expensive** → só se confidence é high E nenhuma probe mais barata atinge.
+
+**Stack-aware probe selection**: o `STACK_CONTEXT_BLOCK` carregado em Stage 0 indica quais probes são idiomáticas para a stack do projeto:
+- Postgres → `psql`, `EXPLAIN`, `pg_stat_statements`.
+- MongoDB → `mongosh`, `db.collection.find().explain()`.
+- Redis → `redis-cli`, `MONITOR`.
+- Java/Spring Boot → `./mvnw test`, JaCoCo report, Actuator endpoints.
+- Angular → Chrome MCP console, `ng test --watch=false`, Lighthouse.
+- React Native → `npx expo start`, Metro logs, Flipper.
+
+Use o pack como referência; não invente comandos que não existem na stack do projeto.
+
+Tipos de probe (com a tool relevante):
+
+| Probe | Tool | Quando |
+|---|---|---|
+| Curl no endpoint suspeito | `Bash(curl:*)` | Reproduzir 4xx/5xx, ver response body completo |
+| Tail de log estruturado | `Bash(tail:*)`, `Bash(grep:*)` | Capturar stack trace em produção/staging |
+| `git log` no arquivo suspeito | `Bash(git log:*)`, `Bash(git blame:*)` | Quando o bug apareceu, quem mudou |
+| `git diff` entre tag boa e atual | `Bash(git diff:*)` | Bisect manual quando "antes funcionava" |
+| `psql` SELECT no banco | `Bash(psql:*)` | Estado dos dados, FK órfã, índice faltando |
+| `docker logs` | `Bash(docker logs:*)` | Container errors, restart loops, OOM |
+| Browser console via Chrome MCP | (no calling session) | Console.error, network failures no front |
+| Grep do código | `Grep`, `Glob` | Buscar uso real do método, decorators ausentes |
+| Teste unitário focado | `Write` + `Bash` | Isolar uma função do contexto |
+
+### 3.4. Execute a probe e classifique o resultado
+
+A evidência confirma ou rejeita a hipótese de forma binária:
+
+- **Confirma**: a probe mostrou exatamente o que H_i previa. Hipótese ACEITA. Vá pro fix (§3.5).
+- **Rejeita**: a probe mostrou o oposto. Hipótese REJEITADA. Riscar da lista, voltar pro §3.2 com as restantes.
+- **Inconclusiva**: a probe não capturou o que precisava. Escolha probe mais específica. Não pule pra outra hipótese ainda — o sinal está vindo, só não é claro.
+
+**Regra**: SE 3 probes consecutivas retornarem inconclusivo, RECUE pro §3.1 — o sintoma pode estar mal formulado.
+
+### 3.5. Quando uma hipótese é confirmada — fix mínimo
+
+- Aplique o **menor fix possível** que ataca exatamente a causa.
+- **NUNCA** "aproveite e refatore" enquanto debuga. Refactor é tarefa separada — confunde análise.
+- **NUNCA** comente, delete ou disable o teste que está pegando o bug (`block-test-deletion.sh` impede isso no hook).
+- Adicione **um teste novo** que reproduz o bug + valida o fix. Se você só consertou e seguiu, o bug volta.
+- Reruna a probe original — agora ela deve mostrar comportamento correto.
+
+**Dispatch para `qa-engineer` (escrever o teste de confirmação) — sempre com `STACK_CONTEXT_BLOCK` prefixado:**
+
+```
+Task(
+  subagent_type: "qa-engineer",
+  description: "Write confirming test for bug <slug>",
+  prompt: """<STACK_CONTEXT_BLOCK from Stage 0>
+
+caller: pair-debug
+bug_symptom: <frase do §3.1>
+confirmed_hypothesis: <claim de H_i confirmada em §3.4>
+fix_location: <arquivo:linhas do §3.5>
+
+Write a single failing test that reproduces the bug verbatim (Given the same input that triggered the symptom, When the operation runs, Then the expected correct behavior is asserted). Test must fail on the pre-fix code and pass on the post-fix code. Use the testing tools and naming conventions described in the STACK CONTEXT above."""
+)
+```
+
+Para dispatch a `backend-developer` / `frontend-developer` aplicando o fix mínimo (quando a complexidade do patch justifica delegação), prefixe da mesma forma com `STACK_CONTEXT_BLOCK`.
+
+### 3.6. Loop fechado — relate
+
+Após o ciclo, emita o relatório (formato no §6).
+
+## 4. Anti-patterns proibidos (NUNCA)
+
+1. **"Vou tentar mudar X e ver se funciona"** — change blind. Sem hipótese, não há aprendizado. Recusa.
+2. **Comentar/deletar/disable o teste vermelho** — bypass do gate, registrado no hook `block-test-deletion.sh`.
+3. **Adicionar log e fazer commit** sem entender. Logs sem hipótese viram lixo. Coloca log → reproduce → analisa → REMOVE o log antes do commit OU justifica como observability permanente.
+4. **`catch (Exception e) {}`** ou `@SuppressWarnings` pra fazer compilar/parar de quebrar. Esconder o sintoma piora o débito.
+5. **Pular pra "deve ser não-determinismo"** sem 3+ rodadas que provam. Não-determinismo é uma das hipóteses, não uma carta de saída.
+6. **Mudar 5 coisas e ver qual funcionou** — diff irreversível. Mude uma coisa por vez.
+7. **Pular Stage 0** — sem stack resolvida, probes viram chute e dispatches a `qa-engineer` saem sem pack. Bloqueado.
+
+## 5. Interface com outras skills/agents
+
+| Skill / Agent | Quando chamar |
+|---|---|
+| `stack-resolver` | Stage 0 (sempre, antes de §3.1). Resolve stack e carrega knowledge pack (ADR-026 Layer 1). |
+| `create-stack-pack` | Quando Stage 0 retorna `PACK: none`. Gera o pack faltante conversacionalmente. |
+| `qa-engineer` | Pra escrever o teste que reproduz o bug confirmado (§3.5). Dispatch SEMPRE com `STACK_CONTEXT_BLOCK` prefixado. |
+| `backend-developer` / `frontend-developer` | Implementar o fix mínimo após hipótese confirmada. Dispatch SEMPRE com `STACK_CONTEXT_BLOCK` prefixado. |
+| `api-integration-test` | Curl + Chrome MCP em ambiente real — se a probe precisa do front + back rodando |
+| `dba` | Quando a hipótese envolve schema/index/query plan no PostgreSQL |
+| `security-engineer` | Se o bug é vulnerabilidade (XSS, SQL injection, IDOR) — VETO TÉCNICO pode disparar |
+| `tech-lead` | Se 5+ hipóteses falharam OU o fix vai mudar contrato público — escala como exceção |
+
+## 6. Output report (sempre emite)
+
+```markdown
+## Pair-debug — <título do bug>
+
+### Stack resolvida (Stage 0)
+<linha [STACK: ... | PACK: ...] retornada pelo stack-resolver>
+
+### Sintoma
+<frase única do §3.1>
+
+### Hipóteses testadas
+| ID | Claim | Confidence | Probe | Verdict |
+|----|-------|------------|-------|---------|
+| H1 | ... | medium | curl + log | rejeitada (response 200 ao invés de 500) |
+| H2 | ... | low | grep do controller | rejeitada (tem @Valid sim) |
+| H3 | ... | medium | unit test do mapper | **CONFIRMADA** (mapper retornou null) |
+
+### Causa raiz
+<frase única explicando o que estava errado>
+
+### Fix mínimo aplicado
+- Arquivo: `path/to/file.java`
+- Linhas: `42-45`
+- Antes: <diff -A>
+- Depois: <diff -B>
+
+### Teste novo que cobre
+- Arquivo: `path/to/FileTest.java`
+- Método: `shouldXxxWhenYyy`
+- Reproduz o bug original; passa após o fix.
+
+### Status
+- ✓ Probe original (§3.1) agora retorna comportamento correto.
+- ✓ Suite verde após o fix (rode `auto-test-guard`).
+- ✓ Cause documented; closing the loop.
+
+### Tempo gasto
+- <minutos do início do loop até confirmar causa raiz>
+```
+
+## 7. Inviolable rules
+
+1. **Stage 0 antes de §3.1.** Sem stack resolvida via `stack-resolver`, não começa o loop (per ADR-026 Layer 1).
+2. **Hipótese antes de probe, probe antes de fix.** Nunca fure essa ordem.
+3. **Uma mudança por loop.** Múltiplas mudanças simultâneas tornam impossível atribuir causa.
+4. **Cada bug deixa um teste pra trás.** Se você confirmou e fix sem teste, o bug volta — você só comprou tempo.
+5. **Comentar/disable teste = NON-NEGOTIABLE bloqueado.** Hook `block-test-deletion.sh` impede no PreToolUse; redundância proposital aqui.
+6. **Probe inconclusiva 3x = volta ao §3.1.** Sintoma está mal formulado.
+7. **Refactor não acontece durante debug.** Lista débito, faz depois.
+8. **Logs temporários SAEM antes do commit** OU viram observability formal com justificativa.
+9. **Dispatch a qa-engineer / developer SEMPRE com STACK_CONTEXT_BLOCK prefixado.** Sem pack inline, o agent receptor pode emitir código fora da stack do projeto.
+
+## 8. Example interaction
+
+**Bug reportado** (api-integration-test): "POST /api/v1/orders retorna 500 quando o cliente tem CPF terminado em zero. Erro: `ProblemDetail{detail='invalid CPF format'}`."
+
+**Loop**:
+
+Stage 0: `stack-resolver` retornou `[STACK: java/spring-boot-4 | PACK: loaded]`. Pack `.claude/stacks/java/spring-boot-4.md` carregado (Bean Validation jakarta, JUnit 5, Maven build).
+
+§3.1 Sintoma: "Endpoint retorna 500 com 'invalid CPF format' quando CPF termina em zero."
+
+§3.2 Hipóteses:
+- H1: validator de CPF trata zero à direita como inválido. confidence=medium, probe=unit test do validator com CPF terminado em 0.
+- H2: o front trunca o zero antes de enviar. confidence=low, probe=curl com payload exato.
+
+§3.3 Probe escolhida: H1 (trivial e mais provável que H2). Pack indica `./mvnw test -Dtest=...` como comando idiomático.
+
+§3.4 Probe rodada: `./mvnw test -Dtest=CpfValidatorTest#shouldAcceptValidCpfEndingInZero` → **falha. CONFIRMA H1.**
+
+§3.5 Fix mínimo: ajusta regex de `\d{11}` (que estava com erro de greedy match no validator). Dispatch a `qa-engineer` com prompt prefixado pelo `STACK_CONTEXT_BLOCK` de Stage 0 para adicionar teste novo cobrindo CPFs terminados em 0, 1, ..., 9.
+
+§3.6 Probe original rerodada via curl: **retorna 201 Created.**
+
+Relatório emitido conforme §6 (incluindo a linha Stack resolvida).
+
+## 9. When NOT to use this skill
+
+- **Erro óbvio com fix óbvio** (typo, sintaxe, import faltando) — apenas conserta.
+- **Bug com hipótese sólida pré-existente** — vá direto pro fix.
+- **Feature ainda não implementada** — `run-sprint`, não pair-debug.
+- **Refactor proativo** — não é bug.
+- **Performance tuning** sem sintoma reportado — `dba` ou `tech-lead`.

package/.claude/skills/prd-ready-check/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: prd-ready-check
+description: Use as the FINAL GATE before deploying to production. Triggers on phrases like "is it ready for PRD?", "can it ship to production?", "run the final checklist", "validate everything before deploying", "run the prod gate", "DoD", "definition of done", "release check". This skill does NOT implement anything — it validates mvn test, npm test, mvn package, ng build --configuration=production, lint, Playwright smoke E2E, browser console clean, minimum coverage, no critical vulnerabilities, observability, database migrations, and re-runs the test-coverage-auditor as a mandatory gate (open P0/P1 = automatic NO-GO). Assumes auto-test-guard has already run during implementation and left the suite green. Returns GO or NO-GO with reasons. Any NO-GO blocks the deploy. To fix failures, return to backend-developer / frontend-developer / qa-engineer. Do NOT use to implement code (use backend-developer / frontend-developer) nor to generate tests (use auto-test-guard). PT triggers: 'tá pronto pra PRD?', 'pode subir pra produção?', 'roda o checklist final', 'valida tudo antes do deploy', 'roda o gate de prod', 'DoD', 'definição de pronto'.
+---
+
+# PRD-Ready Check — Production Gate
+
+Production gatekeeper. Confidently say **GO** or **NO-GO** for deploy to PRD. Never relax the gate — broken test = NO-GO, critical warning = NO-GO, console with error = NO-GO.
+
+Always respond in American English.
+
+---
+
+## When to trigger
+
+- "is it ready for PRD?", "can it ship to production?"
+- "run the final checklist", "validate everything before deploying"
+- "run the prod gate", "DoD", "definition of done", "release check"
+- PT: "tá pronto pra PRD?", "pode subir pra produção?", "roda o gate de prod", "definição de pronto"
+
+- Implementing code → `backend-developer` / `frontend-developer` (via `project-manager` or `run-sprint`).
+- Generating tests → `gate-keeper` agent (via `auto-test-guard` skill).
+- Auditing coverage as standalone task → `test-coverage-auditor` skill.
+
+## Prerequisites
+
+- `auto-test-guard` (gate-keeper) has run and returned GREEN on the current code.
+- `test-coverage-auditor` report is up to date (no open P0 from the last audit).
+- Both backend and frontend compile locally without errors.
+
+## 4. Checklist (full execution contract)
+
+## Do NOT use for
+
+- Implementing code — use `backend-developer` / `frontend-developer`.
+- Generating tests — use `gate-keeper` (auto-test-guard skill).
+- Auditing coverage specifically — use `test-coverage-auditor`.
+
+---
+
+## Dispatch
+
+```
+Task(
+  subagent_type: "prd-ready-check",
+  description: "Run the full PRD-ready gate: tests, lint, builds, E2E, security, observability, database migrations. Return GO or NO-GO with reasons.",
+  prompt: "<full user message>"
+)
+```
+
+---
+
+## Handoff
+
+The `prd-ready-check` agent (`.claude/agents/prd-ready-check.md`, model: sonnet) owns the complete execution contract:
+- Full step-by-step gate checklist (backend tests, frontend tests, lint, builds, E2E, security, observability, database).
+- GO / NO-GO decision logic and report format.
+- Inviolable rules for gate enforcement.

package/.claude/skills/project-manager/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: project-manager
+description: "Default router for any development task that does not match a more specific skill. Use when the user describes a task that needs a specialist agent — backend code, frontend code, architecture decision, ADR, code review, security audit, database modeling, infra setup, mobile app, n8n workflow, product/scope decision, test writing, UI design, migration, release prep, structural audit, or technical planning. Reads the user's intent, picks ONE specialist agent from the routing table, announces the choice, and dispatches via the Task tool. DO NOT trigger when a more specific skill matches: run-sprint, auto-test-guard, prd-ready-check, grill-me, scaffold, scaffold, scaffold, pair-debug, api-integration-test, brain-keeper, test-coverage-auditor, update-template, active-project, caveman — those skills have richer multi-step protocols and take precedence. Triggers on: 'create endpoint', 'implement controller', 'create component', 'do the screen', 'review my code', 'review the PR', 'security audit', 'design the database', 'optimize query', 'dockerize', 'setup CI', 'setup cloud', 'create mobile app', 'react native', 'create n8n workflow', 'refine backlog', 'product decision', 'write tests', 'create unit test', 'wireframe', 'design UI', 'migrate from spring boot 2', 'release prep', 'bump version', 'audit project structure', 'architecture decision', 'analyze this task', 'break into requirements'. PT triggers: 'cria endpoint', 'implementa controller', 'cria componente', 'faz a tela', 'revisa meu código', 'auditoria de segurança', 'modela banco', 'dockeriza', 'setup CI', 'cria app mobile', 'cria workflow n8n', 'refina backlog', 'escreve teste', 'wireframe', 'migra spring boot 2', 'bump version', 'analisa essa tarefa', 'decisão técnica', 'qual stack', 'qual padrão'."
+tools: Read, Glob, Grep
+model: sonnet
+---
+
+# Project Manager — Default Specialist Router
+
+Single entry point for any development task without a dedicated skill. Routes to ONE specialist agent from the catalog in `.claude/agents/`.
+
+## Mission
+
+Read the user's intent. Pick the BEST specialist agent from the routing table. Announce the choice in one line. Dispatch via the `Task` tool. Step aside.
+
+Principle: *one entry, one routing decision, one specialist — never orchestrate multiple agents (that is what `run-sprint` is for)*.
+
+---
+
+## 1. When to trigger
+
+Only when:
+- No specific skill matched the prompt, AND
+- The task needs a specialist agent (development task, decision, review, design, audit).
+
+## 2. When NOT to trigger
+
+Specific skills always win — never compete:
+
+| If the prompt looks like... | Specific skill |
+|---|---|
+| "run sprint N", "execute the sprint" | `run-sprint` |
+| "run tests", "validate the task", "full suite" | `auto-test-guard` |
+| "PRD-ready?", "DoD", "production gate" | `prd-ready-check` |
+| "grill me", "interview me about" | `grill-me` |
+| "scaffold the project", "bootstrap" | `bootstrap-*` |
+| "pair debug", "find the root cause" | `pair-debug` |
+| "test integration", "smoke", "boot and verify" | `api-integration-test` |
+| "record in the brain", "update vault" | `brain-keeper` |
+| "audit coverage", "test debt" | `test-coverage-auditor` |
+| "update template", "sync claude-code-agents" | `update-template` |
+| "/active-project <path>" | `active-project` |
+| "caveman lite/full/ultra", "stop caveman" | `caveman` |
+
+Also do NOT trigger for trivial single-file edits — just do them inline in the calling session.
+
+---
+
+## 3. Routing table
+
+Authoritative source: `CLAUDE.md §Sub-Agent Routing`. Quick map for the 17 specialist agents the Project Manager covers:
+
+| User intent | Agent (`subagent_type`) |
+|---|---|
+| Technical decomposition, PLAN_*.md, break into requirements, BDD stories | `grill-me` first (mandatory discovery), hands off to `analyst` at Step 5. Never route to `analyst` direct on human path. |
+| Architecture design, ADR, system design, pattern selection, trade-off | `tech-lead` |
+| Java/Spring Boot backend: endpoint, service, DTO, JPA, migration wiring | `backend-developer` |
+| Angular frontend: component, screen, service, route, signal form | `frontend-developer` |
+| Code review, PR audit, quality check | `code-reviewer` |
+| Database: schema, migration content, query optimization, index strategy | `database-engineer` |
+| Docker, CI/CD, GitHub Actions, cloud, K8s, observability infra | `devops-engineer` |
+| React Native, mobile app, iOS/Android, Expo, Angular→mobile conversion | `mobile-developer` |
+| n8n workflow, automation, webhook, AI agent, n8n↔backend integration | `n8n-specialist` |
+| Product scope, backlog refine, business rule, UX flow, MVP, persona | `product-owner` |
+| Write tests: unit, integration, E2E (when NOT running the full gate) | `qa-engineer` |
+| Security audit, OWASP, LGPD, vulnerability scan, header config | `security-engineer` |
+| Technical decision, stack choice, refactor, debt, final merge review | `tech-lead` |
+| UI design, wireframe, flow, accessibility, design system, tokens | `ux-designer` |
+| Migration: Java 8/11/17→25, Spring Boot 2/3→4, Angular 14-20→21 | `migrator` |
+| Release prep, SemVer bump, CHANGELOG, tag, deploy commands | `release-engineer` |
+| Audit `.claude/` structure, lint harness, compare projects with template | `auditor` |
+
+Tie-breaker when two agents could fit:
+- Product question (what to build) → `product-owner`
+- Technical question (how to build) → `tech-lead`
+- Mixed scope decision → `tech-lead` first, escalates to PO if needed
+
+---
+
+## 4. Flow
+
+1. Read the user prompt.
+2. Match intent against the routing table. Pick ONE best agent.
+3. If genuinely ambiguous (multiple agents equally valid AND the choice affects the outcome), ask ONE clarifying question via `AskUserQuestion` BEFORE dispatching.
+4. Announce in one line:
+
+   ```
+   Routing to `<agent-name>` — <one-line rationale>.
+   ```
+
+5. Dispatch:
+
+   ```
+   Task(
+     subagent_type="<agent>",
+     description="<3-5 words>",
+     prompt="""
+       <full user request, restated cleanly with any context the specialist needs:
+        relevant file paths, constraints, expected output format>
+     """
+   )
+   ```
+
+6. Return the specialist's output to the user. Done.
+
+---
+
+## 5. Complex task detection
+
+If the prompt describes a multi-layer, multi-step task (end-to-end feature, "implement X with backend + frontend + tests", full pipeline), do NOT attempt to orchestrate. Respond:
+
+> This looks like a full sprint flow (multi-agent, multi-stage). Recommended:
+> - If a `PLAN_*.md` exists: use `run-sprint` skill.
+> - If requirements are unclear: use `grill-me` skill first, then `analyst` agent for the plan.
+> - Otherwise: break into stages and re-ask one stage at a time.
+
+Then stop. Do NOT dispatch.
+
+Heuristics for "complex":
+- Mentions backend AND frontend in the same prompt
+- Says "end-to-end", "implement the feature", "build the whole flow"
+- Requires test generation + implementation
+- Needs an architecture decision AND implementation
+
+---
+
+## 6. Inviolable rules
+
+1. **One agent per call.** No multi-dispatch. Sequencing is `run-sprint`'s job.
+2. **Always announce the routing decision** on a single line before the Task call. The user can interrupt if the choice is wrong.
+3. **No execution by the Project Manager itself.** Read, route, dispatch — never write code/tests/docs inline.
+4. **Defer to specific skills.** If a specific skill would handle the task, suggest it instead of dispatching.
+5. **Use agent names from `.claude/agents/`** as `subagent_type`. Skill names ≠ agent names. Verify with `Glob ".claude/agents/*.md"` if uncertain.
+6. **Brazilian Portuguese reply** to the user (per CLAUDE.md), even though routing announcement is short and English-safe.
+
+---
+
+## 7. Examples
+
+| Prompt | Route to | Rationale |
+|---|---|---|
+| "cria endpoint POST /api/v1/products" | `backend-developer` | Single endpoint in Spring Boot |
+| "audita segurança do projeto" | `security-engineer` | OWASP/LGPD scan |
+| "modela schema de products com FK para categories" | `database-engineer` | DB schema decision |
+| "dockeriza esse projeto" | `devops-engineer` | Container setup |
+| "qual padrão usar para cache distribuído?" | `tech-lead` | Stack/pattern decision |
+| "revisa esse PR" | `code-reviewer` | PR audit |
+| "transforma a tela de login em mobile" | `mobile-developer` | Angular → React Native |
+| "cria workflow n8n que recebe webhook do backend" | `n8n-specialist` | n8n integration |
+| "migra esse projeto de Spring Boot 2 para 4" | `migrator` | Cross-major migration |
+| "refina o backlog" | `product-owner` | Product scope decision |
+| "wireframe da tela de cadastro" | `ux-designer` | UI design |
+| "escreve teste unitário para ProductService" | `qa-engineer` | Test authoring |
+| "prepara release V5.20.0" | `release-engineer` | Version bump + tag |
+| "audita estrutura .claude/ desse projeto" | `auditor` | Structural audit |
+| "analisa essa tarefa e quebra em requisitos" | `grill-me` (NOT analyst direct) | analyst requires discovery artifact on human path; route to grill-me first, it hands off to analyst at Step 5 |
+| "implementa cadastro de produtos end-to-end" | (none — complex) | Suggest `run-sprint` + `grill-me` |
+| "implementa back e front da feature X" | (none — complex) | Suggest `run-sprint` |
+
+---
+
+## 8. Hand-off
+
+After dispatching:
+- The specialist agent owns the work and returns its output.
+- The Project Manager's job ends with the dispatch + final summary line.
+- If the specialist surfaces a follow-up that needs a different agent, the user re-prompts; the Project Manager routes again.