@luanpdd/kit-mcp 1.35.0 → 1.36.0

package/kit/commands/golden-signals.md

@@ -1,142 +1,142 @@
----
-name: golden-signals
-description: Invoca golden-signals-instrumenter para serviço/Edge Function/fase — instrumenta 4 golden signals OTel (Latency histogram, Traffic counter, Errors counter, Saturation gauge).
-argument-hint: "<target> [--service <name>] [--saturation <resource>] [--runtime <node|deno|python>]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Grep
-  - Glob
-  - Task
-  - AskUserQuestion
----
-
-<objective>
-Instrumentar um serviço/Edge Function/fase com os **4 golden signals** do cap 6 do livro Google SRE — Latency (histogram bucketed), Traffic (counter), Errors (counter por `error.type`), Saturation (gauge resource-specific). Invoca o agente [`golden-signals-instrumenter`](../agents/golden-signals-instrumenter.md) que aplica a skill [`four-golden-signals`](../skills/four-golden-signals/SKILL.md).
-
-**Cria/Atualiza:**
-- Patches OTel nos arquivos do `<target>` (Latency + Traffic + Errors + Saturation)
-- `GOLDEN-SIGNALS.md` por target com tabela de instrumentação aplicada (output do agent)
-
-**Após:** os 4 signals estão instrumentados e o user pode rodar smoke local para verificar histogram/counter/gauge no backend OTel.
-</objective>
-
-<context>
-**Argumentos:** `$ARGUMENTS` — primeiro token é o `<target>` (path de arquivo, diretório de service, ou número de fase como `38`); restante são flags.
-
-**Flags:**
-- `--service <name>` — nome canônico do serviço (default: deriva de `package.json#name` ou diretório)
-- `--saturation <resource>` — recurso de saturation (`db_connection_pool` | `cache_memory` | `queue_depth` | `concurrency_limit` | `cpu_load` | `egress_bandwidth`); se omitido, agent infere via heurística
-- `--runtime <node|deno|python>` — runtime; se omitido, detecta via `package.json`/`deno.json`/`pyproject.toml`
-
-**Exemplos:**
-```
-/golden-signals src/orders/handler.ts                              # 1 arquivo
-/golden-signals supabase/functions/process-emails                  # 1 Edge Function
-/golden-signals 38                                                 # todos os arquivos modificados pela Phase 38
-/golden-signals src/api --service orders-api --saturation db_connection_pool
-```
-
-**Pré-requisito:** OTel SDK pode estar ausente — agent flagga deps necessárias no output. Caller decide instalar.
-</context>
-
-<process>
-
-## 1. Parsear argumentos
-
-```bash
-TARGET=$(echo "$ARGUMENTS" | awk '{print $1}')
-SERVICE=$(echo "$ARGUMENTS" | grep -oE -- '--service [^ ]+' | awk '{print $2}')
-SATURATION=$(echo "$ARGUMENTS" | grep -oE -- '--saturation [^ ]+' | awk '{print $2}')
-RUNTIME=$(echo "$ARGUMENTS" | grep -oE -- '--runtime [^ ]+' | awk '{print $2}')
-
-if [ -z "$TARGET" ]; then
-  echo "Uso: /golden-signals <target> [--service N] [--saturation R] [--runtime RT]"
-  echo "Exemplos:"
-  echo "  /golden-signals src/orders/handler.ts"
-  echo "  /golden-signals supabase/functions/process-emails"
-  echo "  /golden-signals 38                  # todos arquivos da Phase 38"
-  exit 1
-fi
-```
-
-## 2. Resolver target → lista de target_files
-
-```bash
-# PT-BR: 3 modos de resolução
-if [[ "$TARGET" =~ ^[0-9]+$ ]]; then
-  # Modo fase — extrai files_modified de PLAN.md(s) da Phase $TARGET
-  PHASE_STATE=$(node "./.claude/framework/bin/tools.cjs" init phase-op "$TARGET")
-  PHASE_DIR=$(echo "$PHASE_STATE" | jq -r .phase_dir)
-  if [ "$PHASE_DIR" = "null" ] || [ ! -d "$PHASE_DIR" ]; then
-    echo "Fase $TARGET ainda não foi planejada."
-    exit 1
-  fi
-  TARGET_FILES=$(grep -rh "^  - " "$PHASE_DIR"/*-PLAN-*.md | grep -oE '[a-zA-Z0-9_/.-]+\.(ts|js|py|deno|sql)' | sort -u | tr '\n' ' ')
-elif [ -d "$TARGET" ]; then
-  # Modo diretório — todos arquivos relevantes (.ts, .js, .py)
-  TARGET_FILES=$(find "$TARGET" -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" \) | tr '\n' ' ')
-elif [ -f "$TARGET" ]; then
-  # Modo arquivo único
-  TARGET_FILES="$TARGET"
-else
-  echo "Erro: target '$TARGET' não é arquivo, diretório ou número de fase válido."
-  exit 1
-fi
-
-if [ -z "$TARGET_FILES" ]; then
-  echo "Nenhum arquivo encontrado para target '$TARGET'."
-  exit 0
-fi
-```
-
-## 3. Dispatch para `golden-signals-instrumenter`
-
-```text
-Task(
-  subagent_type="golden-signals-instrumenter",
-  prompt="
-target_files: ${TARGET_FILES}
-${SERVICE:+service_name: ${SERVICE}}
-${RUNTIME:+runtime: ${RUNTIME}}
-${SATURATION:+saturation_resource: ${SATURATION}}
-
-Aplicar skill four-golden-signals. Gerar patches OTel para os 4 signals em cada arquivo:
-1. Latency: histogram com explicitBucketBoundaries exponencial, dimension result=success|error
-2. Traffic: counter incrementado antes de processar request
-3. Errors: counter por error_type enum (5-15 valores; NÃO error.message)
-4. Saturation: ObservableGauge do recurso mais escasso (callback lê estado real)
-
-Validar 6 checks no Step 3 do agent (latency separado success/error, error_type enum, etc.).
-Output: tabela de patches gerados + GOLDEN-SIGNALS.md por target.
-"
-)
-```
-
-## 4. Pós-output
-
-```
-═══════════════════════════════════════════════════════════
- framework ► GOLDEN-SIGNALS ▸ ${TARGET}
-═══════════════════════════════════════════════════════════
-
-[output do golden-signals-instrumenter — ver Step 4 do agent]
-
-## Próximos passos
-1. Smoke local — enviar request e verificar histogram/counter/gauge no backend OTel
-2. Cross-ref: rodar `/instrumentar-fase ${TARGET}` se spans/wide events ainda ausentes (complementar)
-3. Após validar baseline, definir SLO event-based: `/observabilidade slo <feature>`
-4. PRR antes de production: `/prr --service ${SERVICE:-<name>}`
-```
-
-</process>
-
-<success_criteria>
-- [ ] `<target>` parseado de $ARGUMENTS (arquivo, diretório, ou número de fase)
-- [ ] `target_files` resolvido para lista não-vazia (3 modos suportados)
-- [ ] `golden-signals-instrumenter` invocado via `Task(subagent_type=...)`
-- [ ] Patches aplicados em todos os arquivos do target (4 signals cada)
-- [ ] Output forwarded transparentemente do agent (sem post-processing)
-- [ ] Próximos passos sugerem cross-ref para `/instrumentar-fase`, `/observabilidade slo`, `/prr`
-</success_criteria>
+---
+name: golden-signals
+description: Invoca golden-signals-instrumenter para serviço/Edge Function/fase — instrumenta 4 golden signals OTel (Latency histogram, Traffic counter, Errors counter, Saturation gauge).
+argument-hint: "<target> [--service <name>] [--saturation <resource>] [--runtime <node|deno|python>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Instrumentar um serviço/Edge Function/fase com os **4 golden signals** do cap 6 do livro Google SRE — Latency (histogram bucketed), Traffic (counter), Errors (counter por `error.type`), Saturation (gauge resource-specific). Invoca o agente [`golden-signals-instrumenter`](../agents/golden-signals-instrumenter.md) que aplica a skill [`four-golden-signals`](../skills/four-golden-signals/SKILL.md).
+
+**Cria/Atualiza:**
+- Patches OTel nos arquivos do `<target>` (Latency + Traffic + Errors + Saturation)
+- `GOLDEN-SIGNALS.md` por target com tabela de instrumentação aplicada (output do agent)
+
+**Após:** os 4 signals estão instrumentados e o user pode rodar smoke local para verificar histogram/counter/gauge no backend OTel.
+</objective>
+
+<context>
+**Argumentos:** `$ARGUMENTS` — primeiro token é o `<target>` (path de arquivo, diretório de service, ou número de fase como `38`); restante são flags.
+
+**Flags:**
+- `--service <name>` — nome canônico do serviço (default: deriva de `package.json#name` ou diretório)
+- `--saturation <resource>` — recurso de saturation (`db_connection_pool` | `cache_memory` | `queue_depth` | `concurrency_limit` | `cpu_load` | `egress_bandwidth`); se omitido, agent infere via heurística
+- `--runtime <node|deno|python>` — runtime; se omitido, detecta via `package.json`/`deno.json`/`pyproject.toml`
+
+**Exemplos:**
+```
+/golden-signals src/orders/handler.ts                              # 1 arquivo
+/golden-signals supabase/functions/process-emails                  # 1 Edge Function
+/golden-signals 38                                                 # todos os arquivos modificados pela Phase 38
+/golden-signals src/api --service orders-api --saturation db_connection_pool
+```
+
+**Pré-requisito:** OTel SDK pode estar ausente — agent flagga deps necessárias no output. Caller decide instalar.
+</context>
+
+<process>
+
+## 1. Parsear argumentos
+
+```bash
+TARGET=$(echo "$ARGUMENTS" | awk '{print $1}')
+SERVICE=$(echo "$ARGUMENTS" | grep -oE -- '--service [^ ]+' | awk '{print $2}')
+SATURATION=$(echo "$ARGUMENTS" | grep -oE -- '--saturation [^ ]+' | awk '{print $2}')
+RUNTIME=$(echo "$ARGUMENTS" | grep -oE -- '--runtime [^ ]+' | awk '{print $2}')
+
+if [ -z "$TARGET" ]; then
+  echo "Uso: /golden-signals <target> [--service N] [--saturation R] [--runtime RT]"
+  echo "Exemplos:"
+  echo "  /golden-signals src/orders/handler.ts"
+  echo "  /golden-signals supabase/functions/process-emails"
+  echo "  /golden-signals 38                  # todos arquivos da Phase 38"
+  exit 1
+fi
+```
+
+## 2. Resolver target → lista de target_files
+
+```bash
+# PT-BR: 3 modos de resolução
+if [[ "$TARGET" =~ ^[0-9]+$ ]]; then
+  # Modo fase — extrai files_modified de PLAN.md(s) da Phase $TARGET
+  PHASE_STATE=$(node "./.claude/framework/bin/tools.cjs" init phase-op "$TARGET")
+  PHASE_DIR=$(echo "$PHASE_STATE" | jq -r .phase_dir)
+  if [ "$PHASE_DIR" = "null" ] || [ ! -d "$PHASE_DIR" ]; then
+    echo "Fase $TARGET ainda não foi planejada."
+    exit 1
+  fi
+  TARGET_FILES=$(grep -rh "^  - " "$PHASE_DIR"/*-PLAN-*.md | grep -oE '[a-zA-Z0-9_/.-]+\.(ts|js|py|deno|sql)' | sort -u | tr '\n' ' ')
+elif [ -d "$TARGET" ]; then
+  # Modo diretório — todos arquivos relevantes (.ts, .js, .py)
+  TARGET_FILES=$(find "$TARGET" -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" \) | tr '\n' ' ')
+elif [ -f "$TARGET" ]; then
+  # Modo arquivo único
+  TARGET_FILES="$TARGET"
+else
+  echo "Erro: target '$TARGET' não é arquivo, diretório ou número de fase válido."
+  exit 1
+fi
+
+if [ -z "$TARGET_FILES" ]; then
+  echo "Nenhum arquivo encontrado para target '$TARGET'."
+  exit 0
+fi
+```
+
+## 3. Dispatch para `golden-signals-instrumenter`
+
+```text
+Task(
+  subagent_type="golden-signals-instrumenter",
+  prompt="
+target_files: ${TARGET_FILES}
+${SERVICE:+service_name: ${SERVICE}}
+${RUNTIME:+runtime: ${RUNTIME}}
+${SATURATION:+saturation_resource: ${SATURATION}}
+
+Aplicar skill four-golden-signals. Gerar patches OTel para os 4 signals em cada arquivo:
+1. Latency: histogram com explicitBucketBoundaries exponencial, dimension result=success|error
+2. Traffic: counter incrementado antes de processar request
+3. Errors: counter por error_type enum (5-15 valores; NÃO error.message)
+4. Saturation: ObservableGauge do recurso mais escasso (callback lê estado real)
+
+Validar 6 checks no Step 3 do agent (latency separado success/error, error_type enum, etc.).
+Output: tabela de patches gerados + GOLDEN-SIGNALS.md por target.
+"
+)
+```
+
+## 4. Pós-output
+
+```
+═══════════════════════════════════════════════════════════
+ framework ► GOLDEN-SIGNALS ▸ ${TARGET}
+═══════════════════════════════════════════════════════════
+
+[output do golden-signals-instrumenter — ver Step 4 do agent]
+
+## Próximos passos
+1. Smoke local — enviar request e verificar histogram/counter/gauge no backend OTel
+2. Cross-ref: rodar `/instrumentar-fase ${TARGET}` se spans/wide events ainda ausentes (complementar)
+3. Após validar baseline, definir SLO event-based: `/observabilidade slo <feature>`
+4. PRR antes de production: `/prr --service ${SERVICE:-<name>}`
+```
+
+</process>
+
+<success_criteria>
+- [ ] `<target>` parseado de $ARGUMENTS (arquivo, diretório, ou número de fase)
+- [ ] `target_files` resolvido para lista não-vazia (3 modos suportados)
+- [ ] `golden-signals-instrumenter` invocado via `Task(subagent_type=...)`
+- [ ] Patches aplicados em todos os arquivos do target (4 signals cada)
+- [ ] Output forwarded transparentemente do agent (sem post-processing)
+- [ ] Próximos passos sugerem cross-ref para `/instrumentar-fase`, `/observabilidade slo`, `/prr`
+</success_criteria>