@luanpdd/kit-mcp 1.9.0 → 1.11.0

package/kit/commands/sre.md

@@ -0,0 +1,230 @@
+---
+name: sre
+description: Orquestrador da Suíte SRE (v1.10) — dispatch para agents (golden-signals-instrumenter, toil-auditor, postmortem-writer, prr-conductor) com sinônimos PT/EN.
+argument-hint: "<subcomando> [args...]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Orquestrador único da Suíte SRE (v1.10) — terceiro orquestrador da família após [`/supabase`](./supabase.md) (v1.8) e [`/observabilidade`](./observabilidade.md) (v1.9). Recebe subcomando + args, faz dispatch via `Task(subagent_type=...)` para o agent SRE correto. **Único ponto de chain de agents SRE** (anti-pitfall A10 mantido — agents permanecem função pura).
+
+**Subcomandos cobrem cap 3, 5, 6, 15, 32 do livro Google SRE:**
+- `golden-signals` — 4 signals universais (cap 6)
+- `auditar-toil`/`audit-toil` — eliminating toil (cap 5)
+- `postmortem` — blameless postmortem (cap 15)
+- `prr` — Production Readiness Review (cap 32)
+- `risk-budget`/`budget` — risk continuum (cap 3)
+
+**Cria/Atualiza:** o que cada agent invocado cria (patches OTel, TOIL-AUDIT.md, postmortem, PRR-REPORT.md, snapshot risk-budget).
+
+**Após:** o usuário tem o output do agent (instrumentação aplicada, audit, postmortem revisável, PRR scored, ou snapshot de budget).
+</objective>
+
+<execution_context>
+Skills consultadas pelos agents (Phase 36): [`kit/skills/sre-risk-management/SKILL.md`](../skills/sre-risk-management/SKILL.md), [`kit/skills/four-golden-signals/SKILL.md`](../skills/four-golden-signals/SKILL.md), [`kit/skills/eliminating-toil/SKILL.md`](../skills/eliminating-toil/SKILL.md), [`kit/skills/blameless-postmortems/SKILL.md`](../skills/blameless-postmortems/SKILL.md), [`kit/skills/production-readiness-review/SKILL.md`](../skills/production-readiness-review/SKILL.md) + glossário em [`kit/skills/_shared-sre/glossary.md`](../skills/_shared-sre/glossary.md).
+
+Agents disponíveis (Phase 37):
+- [`golden-signals-instrumenter`](../agents/golden-signals-instrumenter.md) — AGCORE-SRE-01
+- [`toil-auditor`](../agents/toil-auditor.md) — AGCORE-SRE-02
+- [`postmortem-writer`](../agents/postmortem-writer.md) — AGCORE-SRE-03
+- [`prr-conductor`](../agents/prr-conductor.md) — AGCORE-SRE-04
+
+**Subcomando `risk-budget`** é caso especial — comando direto (Plan 05 não usa agent); orquestrador delega aplicando skill [`sre-risk-management`](../skills/sre-risk-management/SKILL.md) inline ou re-encaminhando para `/risk-budget`.
+</execution_context>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — primeiro token é o subcomando; restante é passado para o agent como prompt.
+
+**Subcomandos suportados (sinônimos PT-BR/EN):**
+
+| Subcomando | Sinônimos | Agent dispatched | Cap livro |
+|---|---|---|---|
+| `golden-signals` | `signals`, `4signals`, `golden` | `golden-signals-instrumenter` | 6 |
+| `auditar-toil` | `audit-toil`, `toil`, `auditar` | `toil-auditor` | 5 |
+| `postmortem` | `pm`, `post-mortem` | `postmortem-writer` | 15 |
+| `prr` | `production-readiness`, `readiness-review` | `prr-conductor` | 32 |
+| `risk-budget` | `budget`, `risk`, `continuum` | (comando direto — `/risk-budget`) | 3 |
+| `cascading` | `cascade`, `cascading-failures`, `auditar-cascading` | `cascading-failures-auditor` | 22 (v1.11) |
+| `load-shedding` | `shed`, `load-shed`, `loadshedding` | `load-shedding-instrumenter` | 22 (v1.11) |
+| `release` | `auditar-release`, `release-audit`, `pipeline` | `release-pipeline-auditor` | 8 (v1.11) |
+| `help` | `ajuda`, `?` | exibe esta tabela inline | — |
+
+**Roteamento de flags por subcomando:**
+
+- `golden-signals <target>` — args passados como `<target>` + flags `--service` `--saturation` `--runtime`
+- `auditar-toil` — flags `--time-window` `--team-size` `--output` `--runbooks-paths`
+- `postmortem` — flags **mutuamente exclusivas** `--from-investigation <id>` OU `--incident "<desc>"` + `--severity`
+- `prr` — flags **mutuamente exclusivas** `--service <name>` OU `--feature "<desc>"` + `--engagement` `--reviewer`
+- `risk-budget` — `[<slo_name>]` opcional + `--format` `--explain`
+
+**Exemplos:**
+
+```
+/sre golden-signals supabase/functions/process-emails    # instrumentar Edge Function
+/sre auditar-toil --time-window 6m                       # audit toil últimos 6 meses
+/sre postmortem --from-investigation incident-2026-05-06-1432-checkout-burn  # continuação de v1.9
+/sre prr --service orders-api --reviewer @sre-lead       # PRR de serviço existente
+/sre risk-budget checkout_success --explain              # budget + sabedoria 99.99% inline
+/sre help                                                # exibe tabela de subcomandos
+```
+</context>
+
+<process>
+
+## 1. Parsear subcomando
+
+```bash
+SUBCMD=$(echo "$ARGUMENTS" | awk '{print $1}')
+ARGS=$(echo "$ARGUMENTS" | cut -d' ' -f2-)
+```
+
+**Se `$ARGUMENTS` for vazio ou `SUBCMD` for `help`/`ajuda`/`?`:** exibir tabela de subcomandos inline + exemplo de uso. Sair.
+
+## 2. Resolver sinônimos para agent canônico
+
+```text
+golden-signals, signals, 4signals, golden          → golden-signals-instrumenter
+auditar-toil, audit-toil, toil, auditar            → toil-auditor
+postmortem, pm, post-mortem                        → postmortem-writer
+prr, production-readiness, readiness-review        → prr-conductor
+risk-budget, budget, risk, continuum               → (comando direto — /risk-budget)
+```
+
+**Se subcomando não resolve:** exibir erro inline com lista de subcomandos válidos. Sair.
+
+```
+✗ Subcomando desconhecido: '<SUBCMD>'
+
+Subcomandos válidos:
+  golden-signals    → instrumentar 4 signals OTel (Latency/Traffic/Errors/Saturation)
+  auditar-toil      → audit toil priorizado P0/P1/P2 + esforço de automação
+  postmortem        → postmortem blameless 9 seções (--from-investigation OU --incident)
+  prr               → Production Readiness Review 6 axes (--service OU --feature)
+  risk-budget       → error budget vs risk continuum + sabedoria 99.99%
+
+Uso: /sre <subcomando> <args...>
+Exemplo: /sre prr --service orders-api
+```
+
+## 3. Detectar `supabase/config.toml` (passar `project_id` para agents que usam MCP)
+
+```bash
+PROJECT_ID=""
+if [ -f supabase/config.toml ]; then
+  PROJECT_ID=$(grep -E '^project_id\s*=' supabase/config.toml | sed 's/.*= *"\(.*\)".*/\1/' | head -1)
+fi
+```
+
+Apenas `prr-conductor` usa `mcp__supabase__*` — outros 3 agents não precisam de `project_id` (instrumentação/audit/postmortem são filesystem only).
+
+## 4. Dispatch — caminhos por subcomando
+
+### 4a. `golden-signals` → `golden-signals-instrumenter`
+
+```text
+Task(
+  subagent_type="golden-signals-instrumenter",
+  prompt="
+${ARGS}
+
+Aplicar skill four-golden-signals. Gerar patches OTel para os 4 signals (Latency: histogram bucketed; Traffic: counter; Errors: counter por error.type; Saturation: gauge resource-specific).
+"
+)
+```
+
+### 4b. `auditar-toil` → `toil-auditor`
+
+```text
+Task(
+  subagent_type="toil-auditor",
+  prompt="
+project_root: .
+output_path: .planning/TOIL-AUDIT.md
+${ARGS}
+
+Aplicar skill eliminating-toil. Scan git log + scripts + runbooks; aplicar 6 critérios canônicos; priorizar P0/P1/P2; estimar esforço de automação L0-L4.
+"
+)
+```
+
+### 4c. `postmortem` → `postmortem-writer`
+
+Validar mutuamente exclusivos (`--from-investigation` E `--incident` ambos = ERROR; nenhum = AskUserQuestion sugerido).
+
+```text
+Task(
+  subagent_type="postmortem-writer",
+  prompt="
+${ARGS}
+
+Aplicar skill blameless-postmortems. Modo conforme flag (--from-investigation lê investigation v1.9; --incident standalone com 9 perguntas guiadas). 9 seções obrigatórias: Summary, Impact, Root Causes, Trigger, Resolution, Detection, Action Items, Lessons Learned, Timeline UTC. Foco em sistema/processo (NUNCA pessoas).
+"
+)
+```
+
+### 4d. `prr` → `prr-conductor`
+
+Validar mutuamente exclusivos (`--service` E `--feature` ambos = ERROR; nenhum = ERROR com sugestão). Se `--reviewer` ausente: AskUserQuestion (anti-pattern auto-PRR).
+
+```text
+Task(
+  subagent_type="prr-conductor",
+  prompt="
+${ARGS}
+${PROJECT_ID:+project_id: ${PROJECT_ID}}
+
+Aplicar skill production-readiness-review. Audit em 6 axes (System Architecture, Instrumentation, Emergency Response, Capacity Planning, Change Management, Performance) — todos obrigatórios. Engagement model conforme outage cost. Modo offline fallback graceful.
+"
+)
+```
+
+### 4e. `risk-budget` → comando direto `/risk-budget`
+
+Caso especial — não há agent. Re-encaminhar via shell ou aplicar skill `sre-risk-management` direto.
+
+```bash
+# PT-BR: invocar comando /risk-budget passando args
+# Em Claude Code, isso é equivalente a executar o comando file diretamente
+# (orquestrador apenas valida sinônimo e delega)
+/risk-budget ${ARGS}
+```
+
+Alternativa inline (se não há shell call): orquestrador lê `.planning/slos/*.md`, mapeia para tabela continuum (skill `sre-risk-management` Pattern 1), exibe tabela com status (OPTIMAL/OVER-SPEC/UNDER-SPEC/BUDGET-EXHAUSTED).
+
+## 5. Output
+
+Output do agent (ou do comando direto risk-budget) é o output do orquestrador. Sem post-processing — agent já formata estruturado.
+
+## 6. Sugestões de chains comuns (pós-output)
+
+Após dispatch, orquestrador pode sugerir chains comuns:
+
+| Subcomando rodado | Chain natural |
+|---|---|
+| `golden-signals` | `/sre prr --service <same>` (validar production-readiness) |
+| `auditar-toil` | `/observabilidade omm` (alimentar OMM Capacidade 3) |
+| `postmortem` | `/sre prr --service <affected>` OR `/observabilidade omm` (Capacidade 5 Incident Response) |
+| `prr` | (se Approved) deploy; (se Blocked) fechar P0s e re-PRR |
+| `risk-budget` | `/burn-rate-status` (live forecast) OR `/sre postmortem --incident "..."` se BUDGET-EXHAUSTED |
+
+</process>
+
+<success_criteria>
+- [ ] Subcomando resolvido para agent canônico (5 subcomandos × seus sinônimos)
+- [ ] `project_id` extraído de `supabase/config.toml` se presente (apenas relevante para `prr`)
+- [ ] Dispatch via `Task(subagent_type=...)` — único ponto de chain (anti-pitfall A10)
+- [ ] Subcomando `risk-budget` delega para comando direto `/risk-budget` (não usa Task)
+- [ ] Subcomando `postmortem` valida `--from-investigation` E `--incident` mutuamente exclusivos antes de dispatch
+- [ ] Subcomando `prr` valida `--service` E `--feature` mutuamente exclusivos + AskUserQuestion para reviewer (anti auto-PRR)
+- [ ] Subcomando inválido → mensagem clara com lista de 5 subcomandos válidos
+- [ ] Subcomando `help`/`ajuda`/`?` → exibe tabela inline com 6 linhas (5 + help)
+- [ ] Args após subcomando passam transparentemente para o agent
+- [ ] Sugestões de chains comuns na tabela final (5 chains documentadas)
+</success_criteria>

package/kit/commands/storytelling.md

@@ -0,0 +1,179 @@
+---
+name: storytelling
+description: Invoca storytelling-analyst — IA gera mental model de codebase desconhecido (story 5 frases + inventário + naked CRC + responsibility hot spots + extract candidates). Modernização cap 16-17 Feathers para era IA.
+argument-hint: "<target_dir_or_file> [--depth deep|shallow] [--include-tests] [--output PATH]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - Write
+---
+
+<objective>
+Gerar **mental model de codebase desconhecido** via IA — story em 5 frases + inventário de classes/funções + naked CRC sketch + responsibility hot spots + extract candidates priorizados. Invoca o agente [`storytelling-analyst`](../agents/storytelling-analyst.md) que aplica a skill [`legacy-storytelling-naked-crc`](../skills/legacy-storytelling-naked-crc/SKILL.md) — caps 16-17 do livro Feathers + modernização IA primeiro draft.
+
+**Cria/Atualiza:**
+- `.planning/storytelling/<module-slug>.md` — relatório com story + inventário + CRC + hot spots
+
+**Após:** o user reduz tempo de comprehension de codebase desconhecido de 4-8h (leitura cega manual) para 30 min (revisão informada de IA primeiro draft). Pré-requisito recomendado para `/encontrar-seams` ou `/refactor-seguro` em código novo.
+</objective>
+
+<context>
+**Argumentos:**
+- `<target_dir_or_file>` — diretório ou arquivo a analisar — OBRIGATÓRIO
+- `--depth deep|shallow` — `shallow` = só story + inventário; `deep` = + CRC + hot spots + extract candidates (default: deep)
+- `--include-tests` — incluir tests no scope (default: false; distinção comportamento prod vs harness)
+- `--max-lines N` — limite de leitura (default: 1500; agent quebra em chunks se maior)
+- `--output PATH` — caminho do output (default: `.planning/storytelling/<slug>.md`)
+
+**Exemplos:**
+```
+/storytelling src/orders/                                       # diretório completo
+/storytelling src/orders/OrderService.ts                        # arquivo específico
+/storytelling src/orders/ --depth=shallow                       # rápido — só story + inventário
+/storytelling src/orders/ --include-tests                       # incluir tests no scope
+/storytelling supabase/functions/process-payments/              # Edge Function module
+```
+
+**Quando este comando é o caminho:**
+- Você herdou módulo desconhecido (onboarding, transferência, post-acquisition)
+- Vai modificar código que não conhece
+- Pré-requisito de `/encontrar-seams` ou `/refactor-seguro`
+- Precisa identificar candidates de extract class antes de planejar refactor
+- Code review onde reviewer não conhece o módulo
+
+**Quando NÃO é o caminho:**
+- Codebase < 200 linhas — leitura direta é mais rápida
+- Você já trabalhou no módulo nas últimas 2 semanas — mental model fresco
+- Mudança trivial (typo, comment) — overhead > valor
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+TARGET=$(echo "$ARGUMENTS" | awk '{print $1}')
+DEPTH=$(echo "$ARGUMENTS" | grep -oE -- '--depth[= ][^ ]+' | sed 's/--depth[= ]//')
+MAX_LINES=$(echo "$ARGUMENTS" | grep -oE -- '--max-lines [0-9]+' | awk '{print $2}')
+OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
+INCLUDE_TESTS=false
+echo "$ARGUMENTS" | grep -qE -- '--include-tests' && INCLUDE_TESTS=true
+
+[ -z "$DEPTH" ]     && DEPTH="deep"
+[ -z "$MAX_LINES" ] && MAX_LINES=1500
+
+if [ -z "$TARGET" ]; then
+  echo "ERROR: target obrigatório (arquivo ou diretório)"
+  exit 1
+fi
+
+if [ ! -e "$TARGET" ]; then
+  echo "ERROR: target não encontrado: $TARGET"
+  exit 1
+fi
+
+# auto-output path
+if [ -z "$OUTPUT_PATH" ]; then
+  SLUG=$(basename "$(realpath "$TARGET")" | sed 's/[^a-zA-Z0-9]/-/g')
+  OUTPUT_PATH=".planning/storytelling/${SLUG}.md"
+fi
+
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+```
+
+## 2. Detectar tamanho
+
+```bash
+if [ -f "$TARGET" ]; then
+  TOTAL_LINES=$(wc -l < "$TARGET")
+elif [ -d "$TARGET" ]; then
+  TOTAL_LINES=$(find "$TARGET" -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" -o -name "*.java" -o -name "*.go" \) ! -path "*node_modules*" -exec cat {} + 2>/dev/null | wc -l)
+fi
+
+if [ "$TOTAL_LINES" -gt "$MAX_LINES" ]; then
+  echo "ℹ Target tem $TOTAL_LINES linhas (> $MAX_LINES). Agent vai chunkar análise."
+fi
+```
+
+## 3. Dispatch para `storytelling-analyst`
+
+```text
+Task(
+  subagent_type="storytelling-analyst",
+  prompt="
+target: ${TARGET}
+depth: ${DEPTH}
+output_path: ${OUTPUT_PATH}
+max_lines: ${MAX_LINES}
+include_tests: ${INCLUDE_TESTS}
+
+Aplicar skill legacy-storytelling-naked-crc. Etapas:
+1. Inventário inicial (listar files + classes/funções top-level)
+2. Leitura + síntese — produzir story em ≤ 5 frases
+3. Inventário canônico (tabela com responsabilidade primária + cluster)
+4. (depth=deep) Naked CRC sketch ASCII
+5. (depth=deep) Responsibility hot spots — classes fazendo > 3 coisas distintas
+6. (depth=deep) Abstrações ausentes (sugestões)
+7. (depth=deep) Extract class candidates priorizados
+8. Gotchas / surpresas
+9. Próximas ações sugeridas (effect sketch, /caracterizar, /refactor-seguro)
+10. Output: .planning/storytelling/<slug>.md
+
+PRINCÍPIO: você É a IA primeiro draft. Não busque perfeição — busque utilidade. Seja honesto sobre incertezas.
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► STORYTELLING ▸ ${OUTPUT_PATH}
+═══════════════════════════════════════════════════════════
+
+[output do storytelling-analyst]
+
+## ⚠ Validação obrigatória
+
+Esta análise é PRIMEIRA PASSADA por IA. Erros possíveis:
+- Relações alucinadas (LLM "viu" colaborador que não existe)
+- Hot spots inflated (cluster coeso marcado como hot spot)
+- Sugestões fora de escopo (extract candidate com 2-week effort marcado como 3h)
+
+Cross-check OBRIGATÓRIO antes de basear decisões:
+1. **Spot-check 3-5 funções aleatórias** contra inventário (existem? responsabilidade descrita está correta?)
+2. **Confirmar colaboradores** existem (grep no codebase pelos nomes mencionados)
+3. **Validar hot spots** contra leitura humana (são realmente "fazendo demais"?)
+4. **Refinar story** se necessário; versão final em ${OUTPUT_PATH} é HUMANA, IA é primeiro draft
+
+## Próximos passos
+
+1. Validar story (5-15 min)
+2. Se vai modificar: `/encontrar-seams ${TARGET}` (se arquivo) ou `/storytelling <sub-target>` (refinar para sub-módulo)
+3. Se vai refactorar: `/refactor-seguro ${TARGET}` (chain canônico)
+4. Se vai extrair: revisar extract candidates — `/legacy refactor` por candidate
+5. Se há shotgun surgery em outros módulos relacionados: `/detectar-duplicacao src/`
+
+## Cross-suite
+
+- **/encontrar-seams** (v1.12) — story informa onde existem deps externas
+- **/caracterizar** (v1.12) — story prioriza qual hot spot caracterizar primeiro
+- **/refactor-seguro** (v1.12) — chain canônico após storytelling
+- **/detectar-duplicacao** (v1.12) — shotgun across módulos relacionados
+- **/mapear-codebase** (framework v1.7+) — comando análogo mais geral; storytelling complementa com narrativa
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (target obrigatório)
+- [ ] Tamanho detectado e chunking ativado se necessário
+- [ ] `storytelling-analyst` invocado via Task com depth resolvido
+- [ ] Output forwarded transparentemente
+- [ ] Warning de validação manual obrigatória emitido
+- [ ] Próximos passos sugerem encontrar-seams, caracterizar, refactor-seguro
+- [ ] Cross-references com /detectar-duplicacao, /mapear-codebase, /caracterizar
+</success_criteria>