vek1 subagents

Specs reutilizáveis pra atacar issues do vek1. Cada agent tem escopo cirúrgico, conhecimento do codebase via brain/projects/vek1/, e workflow de worktree isolado.

Convenção de worktrees

# Cada agent cria seu worktree:
git -C C:/Users/User/vek1 worktree add C:/Users/User/vek1-wt/{slug} -b {branch-name}

# Branch naming: tipo/issue-{num}-{slug-curto}
# Ex: fix/issue-15-evolution-key-typo
#     refactor/issue-24-actions-migration
#     feat/issue-25-stripe-billing

# Ao terminar:
cd ..../vek1
git worktree remove ../vek1-wt/{slug}

Agents disponíveis

Agent	Escopo	Issues cobertas
bug-fixer	Bugs cirúrgicos pequenos	#15, #16, #17, #18, #20, #21, #31
schema-versioner	Versionar schema Supabase em migrations	#22 (crítico)
action-migrator	API routes → Server Actions, dedupe lib/supabase.ts	#19, #23, #24, KOD-109
test-author	Cobertura Jest, suite por feature	#28
billing-builder	Stripe + token_usage writes + spending_limit	#25, KOD-98 (guardrail)
file-processor	Extrator real PDF/DOCX	#26
stats-builder	Stats reais substituindo mock	#27
orders-builder	Schema orders + página + fluxo de venda	#8, KOD-107, KOD-108
perf-engineer	PPR + Suspense + caching audit	#32
docs-writer	.env.example, correções README/CHECKLIST	#30

Como executar

Quando quiser disparar um agent:

1. Confirmar pré-requisitos (algumas issues bloqueiam outras — ex: schema-versioner antes de billing-builder)
2. Copiar o .md correspondente para ~/.claude/agents/ (sem o prefixo vek1- se quiser; manter ajuda no autocomplete)
3. Invocar via Task tool com subagent_type: "vek1-bug-fixer" (ou nome escolhido)
4. Passar contexto da issue no prompt (URL ou número da issue)
5. Agent abre worktree, executa, abre PR

Ordem sugerida (depende de pré-requisitos)

Fase 1 (paralelo, sem deps):
  bug-fixer (#15, #16, #18, #20, #31)        ← bugs simples
  docs-writer (#30)                          ← docs
  schema-versioner (#22)                     ← desbloqueia tudo

Fase 2 (depois de #22):
  action-migrator (#19, #23, #24)            ← antes de adicionar features
  bug-fixer (#21)                            ← cleanup que pode tocar schema

Fase 3:
  test-author (#28)                          ← antes de features grandes
  perf-engineer (#32)                        ← independente

Fase 4 (features):
  billing-builder (#25)
  file-processor (#26)
  stats-builder (#27)
  orders-builder (#8 + Linear)