Parte 2 do OPS50 (fechamento): AGENT-OPS, README, roadmap (ponteiro), AGENTS.md (refs Neon/job gate), rule agent-pr-workflow e 8 skills de operação sem comandos gh (API/MCP + safety net) nem secrets Vercel — fonte canônica única: git.solla.dev/fsolla/teqo.
11 KiB
| name | description | disable-model-invocation |
|---|---|---|
| plan-issue | Transforma ideias humanas em Issues do Forgejo + planos de intenção em docs/plans/ (persona, fluxo, objetivo, direção suave no código — sem decisões duras de engenharia). Se o item muda UI, apresenta no gate um rascunho visual HTML+Tailwind (PNG embutido no plano de intenção). Divide o pedido nas menores tarefas que ainda fazem sentido. Use quando o usuário pedir /plan-issue, planejar features, fatiar um pedido em Issues, ou registrar trabalho novo na fila. | true |
Planejar Issues (intenção, não engenharia)
Esta skill transforma ideias soltas em: (1) um plano de intenção em docs/plans/<slug>.md por item, e (2) uma Issue rastreável no Forgejo (pnpm agent:register, frontmatter id/depends/serializes/priority/model). As Issues do Forgejo (git.solla.dev/fsolla/teqo) são a fonte canônica de spec/status/deps/prio/modelo — docs/roadmap.md é legado congelado e nunca é editado aqui.
Ciclo de vida (obrigatório)
rascunho local (Issue: —)
→ GATE (Passo 5) + confirmação explícita do lote
→ register com --plan → Issue NÃO claimável (blocked; script enforça)
→ commit + PR dos planos (Related #N, nunca Closes)
→ merge em main
→ promote blocked→ready (`pnpm agent:ready` + Action OPS18 — dual, idempotente)
→ fila / pool
Regras duras:
- Nada no Forgejo antes do gate. Antes da confirmação explícita do Passo 5: proibido
pnpm agent:register, criar Issue/PR / push de PR de planos. Planos locais (Issue: —) ok. - Confirmação = OK ao overview do lote (ex. “confirma”, “pode registrar”). “Ok” ambíguo no meio da edição não dispara o Passo 6.
- Register com
--plannão nasceready. O script aplicablockedautomaticamente quando--planestá presente (--blockedexplícito ainda vale para chores sem plano). Sem--plan(chore body-only /file-miss), pode nascerready. - Promote só depois do plano em
main. Nunca flipar parareadycom o PR ainda aberto — isso recria a race de claim. Caminhos: (A)pnpm agent:ready -- --issue Nno fim do Passo 6 após merge; (B) Action determinística no merge que lêRelated #N(OPS18). Ambos idempotentes. - Planos de Issues
in-progress/done/in-prodsão imutáveis. Não editardocs/plans/<slug>.mdnem o body de intenção dessas Issues. Refino → plano + Issue novos (sucessor;dependsno pai se fizer sentido). Enquanto a Issue ainda é sóblocked/ready(sem claim), editar o mesmo plano ainda é barato.
Rascunho UI (obrigatório se muda UI): itens com superfície Impeccable B / C / D (ou qualquer mudança do que o usuário vê/toca) devem ter um rascunho HTML+Tailwind (renderizado em PNG e commitado em docs/plans/) no gate — ver ui-draft-html.md. Classe A / sem UI → sem rascunho.
Divisão com as skills de execução
| Skill | Papel |
|---|---|
plan-issue (esta) |
Intenção humana: o quê / para quem / por quê / outcome. Direção suave no codebase. Proibido travar schema, signatures, migrations, abstrações ou “Abordagem” de engenharia. |
work-issue |
Humano supervisiona: Issue já claimada (claim fora da skill) → plano de implementação (Plan mode) → pausa para confirmação → executa. |
agent-work-issue |
Pool / autonomia: Issue já claimada → plano de implementação → executa sem pausa → /simplify → capture-review-debts → PR Ready + auto-merge. |
Aqui não se implementa código de produto, não se escreve plano de implementação, não se roda Impeccable craft/critique/polish. O rascunho UI/UX (HTML+Tailwind) é artefato do gate de intenção, não entrega de app.
Shaping (não tour): aplique shaping.md em silêncio — appetite, fatia mínima útil, rabbit holes de produto, self-score ≥4 antes de gravar.
Dados (intenção): se o item envolve números/KPIs/mapas, aplique data-presentation.md só até “quem decide o quê com este dado”. A forma (chart/mapa/KPI) fica para o plano de implementação.
Checklist
- [ ] 1. Parse do lote + dedup (intra-lote, Issues existentes, docs/plans, roadmap legacy)
- [ ] 2. Reserva de IDs de uma vez por trilha (roadmap legacy + issuesById())
- [ ] 3. Por item (ordem topológica): classificar → fatiar → explorar só o suficiente → intenção completa
- [ ] 4. Sugestão de modelo × effort via model-selection (uma linha por item)
- [ ] 5. GATE: overview do lote + rascunho UI/UX (se muda UI) + esboços de fluxo → confirmar/iterar (PARAR aqui até o humano confirmar; sem Issue/PR)
- [ ] 6. Registro: `agent:register` (`--plan` → `blocked`) → PR `Related #N` → merge → `pnpm agent:ready`
Passo 1 — Parse e dedup
- Separe os itens. Entrada pode ser 1 ideia ou N. Se ambíguo, assuma a leitura mais provável e liste — a confirmação vai no gate.
- Fatia mínima útil. Prefira várias Issues pequenas a um epic. Cada item deve caber num appetite curto e entregar um outcome verificável sozinho. Mesclar só quando separar criaria trabalho inútil (mesmo fluxo, mesma persona, mesma superfície sem valor incremental).
- Dedup intra-lote: mesclar | absorver (fase de plano existente, sem ID novo) | manter separados com
depends. - Dedup contra o existente:
pnpm issue all+issuesById()+ grep emdocs/plans/*.mdedocs/roadmap.md(legado).- Já coberto / entregue → apontar e não criar.
- Issue
in-progress/done/in-prod: não editar o plano dela — se a intenção mudou, item sucessor (plano + Issue novos). - Issue só
blocked/ready(ainda não claimada): pode editar o plano existente (fase de plano) sem ID novo. - Novo → seguir.
Passo 2 — Reserva de IDs
Último ID por trilha (A/B/C/D/E) via roadmap legacy + issuesById(); distribua antes de escrever planos. Fora de trilha: prefixos O0+, FD+, RS+, OPS+ ou trilha temática mais próxima.
Passo 3 — Por item: intenção completa
Ordem topológica (dependente cita ID do dependido). Por item:
- Tipo
| Tipo | Destino |
|---|---|
Feature /campanha ou site com escopo próprio |
kind:feature + plano de intenção |
| Chore / débito pequeno | kind:chore + plano curto (ou body se trivial) |
| Défice do fluxo de agentes | pnpm agent:file-miss (kind:agent-miss) — não aqui |
| Bloqueio externo (jurídico/LGPD) | blocked + needs:consent/needs:migration; texto no lote jurídico existente |
| Decisão de NÃO fazer | Comentário/doc, não Issue |
- Explorar o código o mínimo — só para apontar direção (rotas/pastas/domínios prováveis) e evitar duplicar algo já entregue. Não inventar signatures, collections novas como decisão travada, nem diagramas de componentes.
- Superfície UI (A–D) como dica para quem for executar — não semear brief Impeccable completo. Classe B/C/D (ou qualquer mudança de UI): criar rascunho HTML+Tailwind (ui-draft-html.md) antes do gate, renderizar o PNG (
pnpm ui-draft:render) e embutir no plano; ASCII no plano fica opcional. Classe A / sem UI: sem rascunho. - Dados (intenção) ou
Dados: N/A. - Posicionamento:
P0..P3,depends, appetite, janela eleitoral se relevante,serializesse tocar recurso compartilhado — nomeie o registro exato (ex.serializes: 'docs/plans/',serializes: 'docs/changelog/'— migrations não serializam, AGENT-OPS). Sem detalhar a migration. - Plano de intenção em
docs/plans/<slug>.mdvia intention-template.md, com campo Rascunho UI preenchido (path do.html+ PNGs embutidos, ouN/A). Self-score ≥4/5 (shaping.md).
O que é proibido no plano de intenção
- Decisões de schema / collection / unicidade / Consent key concreta como “travadas”
- Assinaturas de funções, nomes de arquivos novos obrigatórios, mermaid de arquitetura de solução
- “Abordagem proposta” com componentes e migration nomeada
- Fases de implementação verificáveis com quota de engenharia
- Forçar o executor a uma única forma técnica
O que é obrigatório
- Intenção do humano (problema/oportunidade)
- Persona(s) e fluxo desejado (job / outcome)
- Critérios de aceite em linguagem de produto
- Appetite e fora de escopo (produto)
- Direção provável no codebase (pastas/rotas/domínios — hipotética, revisável)
- Questões em aberto com Opções + Recomendação de produto (não de engenharia)
- Se muda UI: rascunho UI/UX (HTML+Tailwind → PNG) no gate (ui-draft-html.md) + PNG embutido no plano
Passo 4 — Modelo × effort
Skill model-selection. Registre no cabeçalho (Model:) e no gate.
- Default:
composer-2.5 - Grok com effort explícito quando discovery/multi-domínio / falha cara de produto
- Não crie par
{id}-plan/{id}-execpor default — o plano de implementação nasce emwork-issue/agent-work-issue. Reserve bipartição só para blast radius extremo (refactor repo-wide) se o humano pedir.
Passo 5 — GATE
Antes de criar Issues ou abrir PR de planos:
- Overview: ID, título, prio, depends, appetite, modelo, link do plano local
- Para cada item que muda UI: mostre as imagens do rascunho (PNGs embutidos no plano) + link do
.htmlfonte — este é o rascunho visual a validar - Esboço textual de fluxo só se ajudar; não substitui o rascunho quando há UI
- Perguntas acumuladas numa rodada, recomendação de produto primeiro
Pare e espere. Itere (incluindo o rascunho — HTML → re-render do PNG, se houver UI) até confirmação explícita do lote (não basta um “ok” solto durante a edição). Só então Passo 6.
Passo 6 — Registro (não claimável até plano em main)
Ordem obrigatória (OPS17):
- Register (com
--model; com--plano script nasceblocked— não precisa--blockedextra):
pnpm agent:register -- --id <ID> --title "<título>" --prio <P0..P3> \
--depends <A,B> --kind <feature|chore|...> --plan docs/plans/<slug>.md \
--model <slug>
Sem --plan: nasce ready (use --blocked só se quiser não-claimável sem plano).
- Atualize
Issue: #N(e status) no plano local. - Commit +
pnpm push+ PR Ready--base maincomRelated #N(nuncaCloses #Nem PR só dedocs/plans/—plans-only-closes). - Auto-merge via safety net (
agent-pr-ready-automerge.yml— o rollupCI (PR) / checksverde mergea por rebase); espere o merge emmain. - Promote com o script (idempotente se já
ready; só Issuesblocked+ linkdocs/plans/, sem gates humanosneeds:*nemin-progress/done/in-prod):
pnpm agent:ready -- --issue <N[,N…]>
A Action de merge (plan-issue-ready-on-main-merge.yml, OPS18) é safety net se este passo falhar — não pule o promote do agente no caminho feliz.
NÃO faz: editar docs/roadmap.md; implementar código; claim; escrever *-impl.md; editar plano de Issue in-progress/done/in-prod; marcar ready antes do plano em main; registrar/abrir PR antes do gate.
Resumo final
Tabela do lote + mesclados/absorvidos/descartados + decisões de produto assumidas (validar) + o que o gate decidiu + Issues #N + PRs de plano.