@luanpdd/kit-mcp 1.33.0 → 1.34.0

package/kit/commands/auditar-observabilidade-cobertura-workflow.md

@@ -0,0 +1,121 @@
+---
+name: auditar-observabilidade-cobertura-workflow
+description: Variante Dynamic Workflows do audit de cobertura — 1 agent por Edge Function em paralelo + verify adversarial por gap. PoC para comparar contra /auditar-observabilidade-cobertura.
+argument-hint: "[--traffic-window 30d] [--top-n 5] [--dimensions signals,slo,burn-alert,characterization] [--output PATH]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - Write
+  - Workflow
+  - mcp__supabase__list_edge_functions
+  - mcp__supabase__get_logs
+  - mcp__supabase__execute_sql
+---
+
+# auditar-observabilidade-cobertura-workflow
+
+> **PoC — Dynamic Workflows (Opus 4.8+).** Mesma intenção do [`/auditar-observabilidade-cobertura`](./auditar-observabilidade-cobertura.md) mas executa em paralelo via `Workflow()`: 1 agent por Edge Function auditando as 4 dimensões + verify adversarial só nos gaps reportados + synthesizer final.
+
+> Use este comando para **comparar** wall-clock e qualidade do report contra a versão serial.
+
+<objective>
+Roda o script `auditar-observabilidade-cobertura.workflow.js` registrado em `.claude/workflows/`, que faz fan-out por função e remove a barreira do agent monolítico.
+
+**Por que existe (PoC):**
+- A versão serial encadeia N funções × 4 dimensões em UM agent — context grows linearly, foco se perde a partir de ~30 funções.
+- Esta versão tem 1 contexto por função (audit pequeno, foco preservado) + verify só onde houve gap (cost-controlled).
+- Cross-suite (v1.9 + v1.10 + v1.12) intacto — só a topologia muda.
+
+**Output:** mesmo `.planning/OBSERVABILITY-COVERAGE.md` da versão serial (mesma estrutura), permitindo `diff` direto.
+</objective>
+
+<context>
+**Argumentos (idênticos ao command original):**
+- `--traffic-window 30d` (default `30d`)
+- `--top-n 5` (default `5`)
+- `--dimensions signals,slo,burn-alert,characterization` (default todos)
+- `--output PATH` (default `.planning/OBSERVABILITY-COVERAGE.md` — use `.planning/OBSERVABILITY-COVERAGE-WORKFLOW.md` para A/B)
+
+**Pré-requisitos:**
+- Claude Code Max / Team / Enterprise (Dynamic Workflows em research preview)
+- `Workflow` tool habilitada na sessão
+- Resto idêntico ao command original (projeto Supabase + MCP recomendado)
+
+**Quando usar PoC ao invés do original:**
+- Você tem ≥ 10 Edge Functions e quer medir ganho real
+- Você está validando se Dynamic Workflows cabe no kit-mcp antes de migrar outros orquestradores
+- Auditoria pesada que hoje toma > 10min na versão serial
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+TRAFFIC_WINDOW=$(echo "$ARGUMENTS" | grep -oE -- '--traffic-window [^ ]+' | awk '{print $2}')
+TOP_N=$(echo "$ARGUMENTS" | grep -oE -- '--top-n [0-9]+' | awk '{print $2}')
+DIMENSIONS=$(echo "$ARGUMENTS" | grep -oE -- '--dimensions [^ ]+' | awk '{print $2}')
+OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
+
+[ -z "$TRAFFIC_WINDOW" ] && TRAFFIC_WINDOW="30d"
+[ -z "$TOP_N" ]          && TOP_N=5
+[ -z "$DIMENSIONS" ]     && DIMENSIONS="signals,slo,burn-alert,characterization"
+[ -z "$OUTPUT_PATH" ]    && OUTPUT_PATH=".planning/OBSERVABILITY-COVERAGE.md"
+```
+
+## 2. Disparar o Workflow
+
+```text
+Workflow(
+  name: "auditar-observabilidade-cobertura",
+  args: {
+    projectRoot: ".",
+    trafficWindow: "${TRAFFIC_WINDOW}",
+    topN: ${TOP_N},
+    dimensions: ["${DIMENSIONS//,/\",\"}"],
+    outputPath: "${OUTPUT_PATH}"
+  }
+)
+```
+
+Acompanhe o progresso ao vivo em `/workflows` (CLI/Desktop/VS Code). Cada Edge Function aparece como um chip no phase `Audit`; gaps reais entram em `Verify`.
+
+## 3. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► AUDITAR-OBSERVABILIDADE-COBERTURA-WORKFLOW
+═══════════════════════════════════════════════════════════
+
+Status:          <GREEN|YELLOW|RED>
+Total functions: <N>
+Tier:            <full|partial>
+Output:          ${OUTPUT_PATH}
+
+Cobertura por dimensão:
+  4 Signals:  <X>/<N>
+  SLO:        <Y>/<N>
+  Burn alert: <Z>/<N>
+  Char tests: <W>/<N>
+
+Top ${TOP_N} críticas: [resumo do workflow]
+
+──────────────────────────────────────────────────────────
+A/B vs versão serial:
+  - Para comparar, rode também /auditar-observabilidade-cobertura --output .planning/OBSERVABILITY-COVERAGE-SERIAL.md
+  - Diff: diff .planning/OBSERVABILITY-COVERAGE.md .planning/OBSERVABILITY-COVERAGE-SERIAL.md
+  - Wall-clock: /workflows mostra duração total; cronometre a serial manualmente
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (defaults idênticos ao command original)
+- [ ] `Workflow(name: "auditar-observabilidade-cobertura", args: ...)` invocado
+- [ ] Output em `${OUTPUT_PATH}` com mesma estrutura do command original
+- [ ] Tabela X/N + top-N críticas + recomendações priorizadas
+- [ ] Verify adversarial reportado (quantos gaps confirmados vs refutados)
+- [ ] Instruções de A/B contra versão serial inclusas no pós-output
+</success_criteria>

package/kit/commands/auditar-observabilidade-cobertura.md

@@ -1,183 +1,183 @@
----
-name: auditar-observabilidade-cobertura
-description: Audita projeto Supabase mostrando X/N Edge Functions com 4 golden signals + Y/N com SLO + Z/N com burn alert + W/N com characterization tests. Top 5 críticas (por traffic 30d) sem cobertura.
-argument-hint: "[--traffic-window 30d] [--top-n 5] [--dimensions signals,slo,burn-alert,characterization] [--output PATH]"
-allowed-tools:
-  - Read
-  - Bash
-  - Grep
-  - Glob
-  - Task
-  - Write
-  - mcp__supabase__list_edge_functions
-  - mcp__supabase__get_logs
-  - mcp__supabase__execute_sql
----
-
-<objective>
-**O comando que você roda hoje pra ver o tamanho do buraco e priorizar.** Audit horizontal de cobertura cross-suite (Observabilidade v1.9 + SRE v1.10 + Legacy v1.12). Roda contra projeto Supabase, gera relatório:
-
-- Edge functions emitindo 4 golden signals: **X / N**
-- Edge functions com SLO definido: **Y / N**
-- Edge functions com burn rate alert: **Z / N**
-- Edge functions com characterization tests: **W / N**
-- **Top 5 funções mais críticas (por chamadas 30d) sem cobertura completa**
-
-Invoca o agente [`observability-coverage-auditor`](../agents/observability-coverage-auditor.md) que cross-references skills v1.9 + v1.10 + v1.12.
-
-**Cria/Atualiza:**
-- `.planning/OBSERVABILITY-COVERAGE.md` — relatório scored com tabela X/N por dimensão + top críticas + recomendações priorizadas
-
-**Após:** o user vê tamanho do buraco quantitativamente e tem fila ordenada por (traffic × missing dimensions). As 2 que ele instrumentou às pressas viram baseline; as outras N entram na fila ordenada.
-</objective>
-
-<context>
-**Argumentos:**
-- `--traffic-window 30d` — janela para criticidade (default: 30d)
-- `--top-n 5` — quantas críticas listar (default: 5)
-- `--dimensions <list>` — quais dimensões auditar (default: `signals,slo,burn-alert,characterization`)
-- `--output PATH` — caminho do output (default: `.planning/OBSERVABILITY-COVERAGE.md`)
-
-**Exemplos:**
-```
-/auditar-observabilidade-cobertura                                    # defaults
-/auditar-observabilidade-cobertura --top-n 10                         # listar top 10
-/auditar-observabilidade-cobertura --dimensions signals,slo           # só 2 dimensões
-/auditar-observabilidade-cobertura --traffic-window 7d                # janela menor
-```
-
-**Pré-requisitos:**
-- Projeto Supabase (`supabase/config.toml` presente)
-- MCP Supabase conectado para traffic data + Edge Functions list (recomendado)
-- Sem MCP: agent reverte para enumerate via filesystem (sem traffic data → top-N por filesystem only)
-
-**Quando este comando é o caminho:**
-- Você quer "ver o buraco" antes de priorizar instrumentação
-- Você instrumentou algumas Edge Functions ad-hoc; agora quer audit estruturado das outras
-- Audit trimestral cross-suite
-- Pré-requisito de `/concluir-marco` quando `workflow.observability_coverage_threshold` opt-in
-- `/auditar-marco` chain (audit milestone consume este)
-</context>
-
-<process>
-
-## 1. Parsear argumentos
-
-```bash
-TRAFFIC_WINDOW=$(echo "$ARGUMENTS" | grep -oE -- '--traffic-window [^ ]+' | awk '{print $2}')
-TOP_N=$(echo "$ARGUMENTS" | grep -oE -- '--top-n [0-9]+' | awk '{print $2}')
-DIMENSIONS=$(echo "$ARGUMENTS" | grep -oE -- '--dimensions [^ ]+' | awk '{print $2}')
-OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
-
-[ -z "$TRAFFIC_WINDOW" ] && TRAFFIC_WINDOW="30d"
-[ -z "$TOP_N" ]          && TOP_N=5
-[ -z "$DIMENSIONS" ]     && DIMENSIONS="signals,slo,burn-alert,characterization"
-[ -z "$OUTPUT_PATH" ]    && OUTPUT_PATH=".planning/OBSERVABILITY-COVERAGE.md"
-
-mkdir -p "$(dirname "$OUTPUT_PATH")"
-```
-
-## 2. Validar pré-requisitos
-
-```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
-
-# Detectar tier (Full vs Partial)
-TIER="full"
-if [ -z "$PROJECT_ID" ]; then
-  TIER="partial"
-  echo "ℹ project_id não detectado em supabase/config.toml — degradando para tier partial (sem traffic data)"
-fi
-
-# Detectar Edge Functions via filesystem
-NUM_EDGE_FNS=$(find supabase/functions -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l)
-if [ "$NUM_EDGE_FNS" -eq 0 ]; then
-  echo "ERROR: nenhuma Edge Function detectada em supabase/functions/. Audit cancelado."
-  exit 1
-fi
-```
-
-## 3. Dispatch para `observability-coverage-auditor`
-
-```text
-Task(
-  subagent_type="observability-coverage-auditor",
-  prompt="
-project_root: .
-output_path: ${OUTPUT_PATH}
-traffic_window: ${TRAFFIC_WINDOW}
-top_n_critical: ${TOP_N}
-dimensions: ${DIMENSIONS}
-${PROJECT_ID:+project_id: ${PROJECT_ID}}
-tier: ${TIER}
-
-Aplicar skills (cross-suite v1.9+v1.10+v1.12). Etapas:
-1. Enumerar Edge Functions (via mcp__supabase__list_edge_functions ou filesystem fallback)
-2. Para cada Edge Function, auditar:
-   - 4 Golden Signals (grep por createHistogram/createCounter/createObservableGauge)
-   - SLO definido (.planning/slos/<name>.md ou .planning/SLO.md menção)
-   - Burn rate alert (config presente)
-   - Characterization tests (tests/characterization/<name>/ presente)
-3. Coletar traffic 30d via mcp__supabase__get_logs (Tier Full) ou skip (Tier Partial)
-4. Calcular criticality_score = traffic × missing_count
-5. Compilar matriz + top ${TOP_N} críticas + recomendações priorizadas
-6. Output: .planning/OBSERVABILITY-COVERAGE.md
-"
-)
-```
-
-## 4. Pós-output
-
-```
-═══════════════════════════════════════════════════════════
- framework ► AUDITAR-OBSERVABILIDADE-COBERTURA ▸ ${OUTPUT_PATH}
-═══════════════════════════════════════════════════════════
-
-[output do observability-coverage-auditor]
-
-## Próximos passos priorizados
-
-1. **Atacar top 1 crítica primeiro** — comando direto:
-   - Se signals missing: `/golden-signals <function-path>`
-   - Se SLO missing: `/definir-slo <function-name>`
-   - Se char missing: `/caracterizar <function-path>`
-   - Se burn alert missing: configurar via `/burn-rate-status` + alert manager
-
-2. **Continuar pela ordem de criticality** (top 2, 3, ...)
-
-3. **Bulk approach** se há > 10 funções missing:
-   - Priorize SIGNALS primeiro (visibility é fundação)
-   - Depois SLO (define o que importa)
-   - Depois BURN ALERT (early warning)
-   - Depois CHARACTERIZATION (refactor safety)
-
-4. **Auto-completion** via:
-   - `/observabilidade audit-coverage` — sinônimo deste comando
-   - `/observabilidade omm` — OMM scoring v1.9 que consume este audit
-   - `/auditar-marco` — milestone audit que opt-in invoca este
-
-## Cross-suite
-
-Este audit é o **HUB** que conecta as 3 suítes:
-- v1.9 Observabilidade (golden signals + SLO + burn alert)
-- v1.10 SRE (PRR Axe 2 Instrumentation + Axe 4 Capacity)
-- v1.12 Legacy (characterization safety net)
-
-Re-rodar trimestralmente OR após cada milestone com novas Edge Functions.
-```
-
-</process>
-
-<success_criteria>
-- [ ] $ARGUMENTS parseados (todos opcionais, defaults razoáveis)
-- [ ] Project_id resolvido OU degradado para tier partial sem warning
-- [ ] Edge Functions enumeradas (≥ 1 detectada)
-- [ ] `observability-coverage-auditor` invocado via Task
-- [ ] Output forwarded transparentemente
-- [ ] Próximos passos PRIORIZADOS com comandos prontos para copy-paste
-- [ ] Cross-references com /observabilidade, /auditar-marco, /golden-signals, /caracterizar
-- [ ] Atende explicitamente ao user-request "comando que você roda hoje pra ver o tamanho do buraco"
-</success_criteria>
+---
+name: auditar-observabilidade-cobertura
+description: Audita projeto Supabase mostrando X/N Edge Functions com 4 golden signals + Y/N com SLO + Z/N com burn alert + W/N com characterization tests. Top 5 críticas (por traffic 30d) sem cobertura.
+argument-hint: "[--traffic-window 30d] [--top-n 5] [--dimensions signals,slo,burn-alert,characterization] [--output PATH]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - Write
+  - mcp__supabase__list_edge_functions
+  - mcp__supabase__get_logs
+  - mcp__supabase__execute_sql
+---
+
+<objective>
+**O comando que você roda hoje pra ver o tamanho do buraco e priorizar.** Audit horizontal de cobertura cross-suite (Observabilidade v1.9 + SRE v1.10 + Legacy v1.12). Roda contra projeto Supabase, gera relatório:
+
+- Edge functions emitindo 4 golden signals: **X / N**
+- Edge functions com SLO definido: **Y / N**
+- Edge functions com burn rate alert: **Z / N**
+- Edge functions com characterization tests: **W / N**
+- **Top 5 funções mais críticas (por chamadas 30d) sem cobertura completa**
+
+Invoca o agente [`observability-coverage-auditor`](../agents/observability-coverage-auditor.md) que cross-references skills v1.9 + v1.10 + v1.12.
+
+**Cria/Atualiza:**
+- `.planning/OBSERVABILITY-COVERAGE.md` — relatório scored com tabela X/N por dimensão + top críticas + recomendações priorizadas
+
+**Após:** o user vê tamanho do buraco quantitativamente e tem fila ordenada por (traffic × missing dimensions). As 2 que ele instrumentou às pressas viram baseline; as outras N entram na fila ordenada.
+</objective>
+
+<context>
+**Argumentos:**
+- `--traffic-window 30d` — janela para criticidade (default: 30d)
+- `--top-n 5` — quantas críticas listar (default: 5)
+- `--dimensions <list>` — quais dimensões auditar (default: `signals,slo,burn-alert,characterization`)
+- `--output PATH` — caminho do output (default: `.planning/OBSERVABILITY-COVERAGE.md`)
+
+**Exemplos:**
+```
+/auditar-observabilidade-cobertura                                    # defaults
+/auditar-observabilidade-cobertura --top-n 10                         # listar top 10
+/auditar-observabilidade-cobertura --dimensions signals,slo           # só 2 dimensões
+/auditar-observabilidade-cobertura --traffic-window 7d                # janela menor
+```
+
+**Pré-requisitos:**
+- Projeto Supabase (`supabase/config.toml` presente)
+- MCP Supabase conectado para traffic data + Edge Functions list (recomendado)
+- Sem MCP: agent reverte para enumerate via filesystem (sem traffic data → top-N por filesystem only)
+
+**Quando este comando é o caminho:**
+- Você quer "ver o buraco" antes de priorizar instrumentação
+- Você instrumentou algumas Edge Functions ad-hoc; agora quer audit estruturado das outras
+- Audit trimestral cross-suite
+- Pré-requisito de `/concluir-marco` quando `workflow.observability_coverage_threshold` opt-in
+- `/auditar-marco` chain (audit milestone consume este)
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+TRAFFIC_WINDOW=$(echo "$ARGUMENTS" | grep -oE -- '--traffic-window [^ ]+' | awk '{print $2}')
+TOP_N=$(echo "$ARGUMENTS" | grep -oE -- '--top-n [0-9]+' | awk '{print $2}')
+DIMENSIONS=$(echo "$ARGUMENTS" | grep -oE -- '--dimensions [^ ]+' | awk '{print $2}')
+OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
+
+[ -z "$TRAFFIC_WINDOW" ] && TRAFFIC_WINDOW="30d"
+[ -z "$TOP_N" ]          && TOP_N=5
+[ -z "$DIMENSIONS" ]     && DIMENSIONS="signals,slo,burn-alert,characterization"
+[ -z "$OUTPUT_PATH" ]    && OUTPUT_PATH=".planning/OBSERVABILITY-COVERAGE.md"
+
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+```
+
+## 2. Validar pré-requisitos
+
+```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
+
+# Detectar tier (Full vs Partial)
+TIER="full"
+if [ -z "$PROJECT_ID" ]; then
+  TIER="partial"
+  echo "ℹ project_id não detectado em supabase/config.toml — degradando para tier partial (sem traffic data)"
+fi
+
+# Detectar Edge Functions via filesystem
+NUM_EDGE_FNS=$(find supabase/functions -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l)
+if [ "$NUM_EDGE_FNS" -eq 0 ]; then
+  echo "ERROR: nenhuma Edge Function detectada em supabase/functions/. Audit cancelado."
+  exit 1
+fi
+```
+
+## 3. Dispatch para `observability-coverage-auditor`
+
+```text
+Task(
+  subagent_type="observability-coverage-auditor",
+  prompt="
+project_root: .
+output_path: ${OUTPUT_PATH}
+traffic_window: ${TRAFFIC_WINDOW}
+top_n_critical: ${TOP_N}
+dimensions: ${DIMENSIONS}
+${PROJECT_ID:+project_id: ${PROJECT_ID}}
+tier: ${TIER}
+
+Aplicar skills (cross-suite v1.9+v1.10+v1.12). Etapas:
+1. Enumerar Edge Functions (via mcp__supabase__list_edge_functions ou filesystem fallback)
+2. Para cada Edge Function, auditar:
+   - 4 Golden Signals (grep por createHistogram/createCounter/createObservableGauge)
+   - SLO definido (.planning/slos/<name>.md ou .planning/SLO.md menção)
+   - Burn rate alert (config presente)
+   - Characterization tests (tests/characterization/<name>/ presente)
+3. Coletar traffic 30d via mcp__supabase__get_logs (Tier Full) ou skip (Tier Partial)
+4. Calcular criticality_score = traffic × missing_count
+5. Compilar matriz + top ${TOP_N} críticas + recomendações priorizadas
+6. Output: .planning/OBSERVABILITY-COVERAGE.md
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► AUDITAR-OBSERVABILIDADE-COBERTURA ▸ ${OUTPUT_PATH}
+═══════════════════════════════════════════════════════════
+
+[output do observability-coverage-auditor]
+
+## Próximos passos priorizados
+
+1. **Atacar top 1 crítica primeiro** — comando direto:
+   - Se signals missing: `/golden-signals <function-path>`
+   - Se SLO missing: `/definir-slo <function-name>`
+   - Se char missing: `/caracterizar <function-path>`
+   - Se burn alert missing: configurar via `/burn-rate-status` + alert manager
+
+2. **Continuar pela ordem de criticality** (top 2, 3, ...)
+
+3. **Bulk approach** se há > 10 funções missing:
+   - Priorize SIGNALS primeiro (visibility é fundação)
+   - Depois SLO (define o que importa)
+   - Depois BURN ALERT (early warning)
+   - Depois CHARACTERIZATION (refactor safety)
+
+4. **Auto-completion** via:
+   - `/observabilidade audit-coverage` — sinônimo deste comando
+   - `/observabilidade omm` — OMM scoring v1.9 que consume este audit
+   - `/auditar-marco` — milestone audit que opt-in invoca este
+
+## Cross-suite
+
+Este audit é o **HUB** que conecta as 3 suítes:
+- v1.9 Observabilidade (golden signals + SLO + burn alert)
+- v1.10 SRE (PRR Axe 2 Instrumentation + Axe 4 Capacity)
+- v1.12 Legacy (characterization safety net)
+
+Re-rodar trimestralmente OR após cada milestone com novas Edge Functions.
+```
+
+</process>
+
+<success_criteria>
+- [ ] $ARGUMENTS parseados (todos opcionais, defaults razoáveis)
+- [ ] Project_id resolvido OU degradado para tier partial sem warning
+- [ ] Edge Functions enumeradas (≥ 1 detectada)
+- [ ] `observability-coverage-auditor` invocado via Task
+- [ ] Output forwarded transparentemente
+- [ ] Próximos passos PRIORIZADOS com comandos prontos para copy-paste
+- [ ] Cross-references com /observabilidade, /auditar-marco, /golden-signals, /caracterizar
+- [ ] Atende explicitamente ao user-request "comando que você roda hoje pra ver o tamanho do buraco"
+</success_criteria>