mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-13 15:13:07 +00:00
Merge pull request #603 from fsolla/OPS32-work-issue-no-paradigma-de-issue-ja-claimada-model-sel
OPS32: work-issue no paradigma de Issue já claimada + model-selection só-Cursor
This commit is contained in:
Francisco Solla
GitHub
commit
7b044ff6ef
12 changed files with 238 additions and 146 deletions
|
|
@ -11,7 +11,7 @@ disable-model-invocation: true
|
|||
|
||||
# Agent work-issue (autônomo)
|
||||
|
||||
Conduz **uma** Issue já claimada do plano de implementação ao merge em `main`. É o contrato dos workers do **agent pool** e a base de execução de `work-issue` (versão humana só adiciona claim + pausa).
|
||||
Conduz **uma** Issue já claimada do plano de implementação ao merge em `main`. É o contrato dos workers do **agent pool** (Cursor Cloud, autônomo). O fluxo humano supervisionado é `work-issue` — skill própria, com gate humano no impl plan e contexto de Issue vindo da sessão.
|
||||
|
||||
**Proibido:** DB de prod / `ALLOW_REMOTE_DB`; merge sem CI green; editar outras Issues `in-progress`; pular `/simplify`; entregar Draft ou sem auto-merge.
|
||||
|
||||
|
|
@ -24,14 +24,14 @@ Conduz **uma** Issue já claimada do plano de implementação ao merge em `main`
|
|||
| ----- | ----- |
|
||||
| `plan-issue` | Intenção (já feita) |
|
||||
| **`agent-work-issue` (esta)** | Impl plan → execução → simplify → débitos → PR |
|
||||
| `work-issue` | Igual, mas claim + **confirmação humana** do impl plan |
|
||||
| `work-issue` | Humano: Issue já claimada → impl plan → **pausa humana** → execução → simplify → débitos → PR |
|
||||
|
||||
## Checklist
|
||||
|
||||
```
|
||||
- [ ] 0. Prep: `pnpm i` se preciso; Cloud → §Prep Cloud (sem Docker)
|
||||
- [ ] 1. Sessão: rename_chat + open_resource na intenção
|
||||
- [ ] 2. Modelo (best effort) vs `model:` da Issue
|
||||
- [ ] 2. Modelo: spawn do pool já fixou (`model:` da Issue) — sem comparação
|
||||
- [ ] 3. Plan mode → plano de implementação (`*-impl.md`)
|
||||
- [ ] 4. Executar o impl plan (schema/server → UI → gates)
|
||||
- [ ] 5. /simplify → fixes; capture-review-debts (modo autônomo)
|
||||
|
|
@ -50,18 +50,17 @@ Não use `pnpm db:start`. Postgres via `.cursor/environment.json`. `gate:fast` /
|
|||
|
||||
## Passo 1 — Sessão (Issue já claimada)
|
||||
|
||||
**Não** rode `pnpm agent:claim` — o pool (ou o humano via `work-issue`) já claimou.
|
||||
**Não** rode `pnpm agent:claim` — o pool (ou o claim pré-sessão do humano — hoje `pnpm agent:claim` manual; OPS33 via `worktree next`) já claimou.
|
||||
|
||||
1. `rename_chat` → `#<N> <id> — <título>` (padrão canônico; truncar só o título).
|
||||
2. `open_resource` no plano de intenção (`docs/plans/<slug>.md`).
|
||||
|
||||
## Passo 2 — Modelo
|
||||
|
||||
Compare `model:` da Issue com a sessão (`model-selection`):
|
||||
O spawn do pool já fixou o modelo (`model:` da Issue — ver `model-selection`); não há comparação assimétrica a fazer:
|
||||
|
||||
- Sessão mais fraca → informa e segue
|
||||
- Sessão mais forte → informa; em autonomia do pool, **segue** (o spawn já fixou o modelo)
|
||||
- Ausente → trate como `composer-2.5`
|
||||
- Fallback do pool (slug inválido → `composer-2.5`) pode deixar a sessão **mais fraca** que o declarado → informa e segue
|
||||
- Ausente → o pool spawna no default `composer-2.5`; segue
|
||||
|
||||
## Passo 3 — Plano de implementação (Plan mode)
|
||||
|
||||
|
|
@ -75,32 +74,18 @@ Compare `model:` da Issue com a sessão (`model-selection`):
|
|||
|
||||
## Passo 4 — Executar
|
||||
|
||||
`SwitchMode` → `agent` se ainda estiver em plan. Ordem:
|
||||
`SwitchMode` → `agent` se ainda estiver em plan. Siga a mecânica de
|
||||
[`../work-issue/execution-pipeline.md`](../work-issue/execution-pipeline.md)
|
||||
(executar → simplify → fechar em main), com os deltas do ator pool:
|
||||
|
||||
1. **Schema/server** — migrations (`payload-migrations`), utilities, actions, testes de domínio. Invariantes do engineering-brief.
|
||||
2. **UI** — se Impeccable B/C/D: shape → craft → critique → polish (harden/optimize só sob gatilho). Tokens `data-theme='campaign'`; shells existentes.
|
||||
3. **Gates** — `pnpm gate:fast` na iteração; entrega com `pnpm push` (não `git push` nu).
|
||||
|
||||
Tracer bullet cedo se o item for grande. Inclua o `*-impl.md` no commit da entrega.
|
||||
|
||||
## Passo 5 — `/simplify` + débitos
|
||||
|
||||
1. Rode o comando `/simplify` completo (3 reviewers paralelos via Task, read-only) no diff da sessão.
|
||||
2. Aplique fixes pontuais que preservem comportamento.
|
||||
3. Rode `capture-review-debts` em **modo autônomo**:
|
||||
- Colha e pontue como a skill manda
|
||||
- **Sem** gate humano: registre só `expensive_lock` com score ≥4 (Issues novas com `depends: [<id-pai>]` se necessário)
|
||||
- Score ≤3 / cheap_polish / defer_trigger → defer com gatilho no `*-impl.md` ou descarte — **não** polua a fila
|
||||
- Nunca edite a Issue `in-progress` atual para absorver débitos
|
||||
|
||||
## Passo 6 — Fechar em main
|
||||
|
||||
1. Branch `agent/<id>-<slug>` (worktrees Cursor podem já ter criado).
|
||||
2. **`pnpm push -u origin HEAD`**
|
||||
3. PR **Ready** (nunca draft): `gh pr create --base main` com `Closes #<N>` — ou Cloud `ManagePullRequest` com `draft: false`
|
||||
4. `gh pr merge --auto --merge` imediatamente
|
||||
5. `gh pr checks <PR> --watch --required` (`checks` + `migration-lock`; ignore Vercel Git)
|
||||
6. CI flipa `done`/`in-prod` no merge. Comente na Issue o desfecho em uma linha.
|
||||
- **Branch:** `agent/<id>-<slug>` (worktrees Cursor podem já ter criado).
|
||||
- **UI:** shape → craft → critique → polish (harden/optimize só sob gatilho).
|
||||
- **`capture-review-debts`:** **autônomo** — só `expensive_lock` com score ≥4
|
||||
(Issues novas com `depends: [<id-pai>]` se necessário); score ≤3 /
|
||||
cheap_polish / defer_trigger → defer com gatilho no `*-impl.md` ou descarte —
|
||||
**não** polua a fila.
|
||||
- **Cloud:** PR via `ManagePullRequest` com `draft: false`; Prep Cloud no
|
||||
Passo 0.
|
||||
|
||||
## Resumo final
|
||||
|
||||
|
|
|
|||
|
|
@ -3,30 +3,19 @@ name: model-selection
|
|||
description: >-
|
||||
Escolhe o modelo (e o nível de raciocínio/effort) com melhor custo/valor
|
||||
para cada classe de tarefa do Teqo, e despacha subagentes já no modelo certo
|
||||
via o parâmetro `model` da tool Task. Dois ambientes: pool (Composer 2.5,
|
||||
Grok 4.5, Kimi K3 Low) e local/Zed (Composer 2.5, Grok 4.5, DeepSeek V4
|
||||
Pro, DeepSeek V4 Flash). Toda Issue declara `model:` (pool) + `model-local:`
|
||||
(alternativa DeepSeek V4 high|max para trabalho local). Usar no início de
|
||||
implementação, ao despachar subagentes, antes de /simplify, ou quando o
|
||||
usuário perguntar "qual modelo usar".
|
||||
via o parâmetro `model` da tool Task. Cardápio único Cursor (Composer 2.5,
|
||||
Grok 4.5, Kimi K3 Low). Toda Issue declara `model:` único. Usar ao sugerir
|
||||
modelo em plan-issue, ao despachar subagentes, antes de /simplify, ou quando
|
||||
o usuário perguntar "qual modelo usar".
|
||||
---
|
||||
|
||||
# Seleção de modelo × effort × ambiente
|
||||
# Seleção de modelo × effort
|
||||
|
||||
**Dois ambientes, cardápios diferentes:**
|
||||
**Um cardápio para `model:` (Cursor):**
|
||||
|
||||
| Ambiente | Modelos disponíveis | Frontmatter |
|
||||
| -------- | ------------------- | ----------- |
|
||||
| **Pool (remoto)** | Composer 2.5, Grok 4.5 (low\|medium\|high), Kimi K3 Low | `model:` |
|
||||
| **Local (Zed)** | Composer 2.5, Grok 4.5, **DeepSeek V4 Pro** (high\|max), **DeepSeek V4 Flash** (high\|max) | `model-local:` |
|
||||
Dois eixos, nesta ordem: **(1) classe da tarefa → família de modelo**, **(2) se Grok → effort**. Preço e contexto compram capacidade; effort compra deliberação. **Não pule o eixo 2** — High não é o default automático.
|
||||
|
||||
**Toda Issue declara os dois**: `model:` para o pool + `model-local:` com a alternativa DeepSeek V4 (high ou max) para trabalho local. O agente local **pode** escolher Composer/Grok se fizer mais sentido na sessão, mas o `model-local:` é a referência declarada.
|
||||
|
||||
Três eixos, nesta ordem: **(1) classe da tarefa → família de modelo**, **(2) ambiente → cardápio disponível**, **(3) se Grok ou DeepSeek → effort**. Preço e contexto compram capacidade; effort compra deliberação. **Não pule o eixo 3** — High/Max não é o default automático.
|
||||
|
||||
## Tabela canônica (2026-08-03)
|
||||
|
||||
### Pool (remoto) — `model:`
|
||||
## Tabela canônica (2026-08-10) — `model:`
|
||||
|
||||
| Prioridade | Família | Slug `model:` | Quando |
|
||||
| ---------- | ------- | ------------- | ------ |
|
||||
|
|
@ -34,15 +23,6 @@ Três eixos, nesta ordem: **(1) classe da tarefa → família de modelo**, **(2)
|
|||
| 2 | **Grok 4.5** | `cursor-grok-4.5-low` \| `cursor-grok-4.5-medium` \| `cursor-grok-4.5-high` | Precisa de deliberação além do Composer (abaixo) |
|
||||
| 3 | **Kimi K3 Low** | `kimi-k3-low` | Só na **fase de execução** de issues bipartidas (refactor grande / simplify / migrations+RBAC de blast radius alto), depois de um plano fechado |
|
||||
|
||||
### Local (Zed) — `model-local:`
|
||||
|
||||
| Família | Slug `model-local:` | Quando |
|
||||
| ------- | -------------------- | ------ |
|
||||
| **DeepSeek V4 Flash** | `deepseek-v4-flash-high` \| `deepseek-v4-flash-max` | Pareia com **Composer 2.5** — execução rápida, tarefas mecânicas ou com julgamento leve. Flash-high é o default para `composer-2.5`. |
|
||||
| **DeepSeek V4 Pro** | `deepseek-v4-high` \| `deepseek-v4-max` | Pareia com **Grok 4.5** — deliberação, multi-domínio, design não óbvio. Pro-high para Grok Low/Medium; Pro-max para Grok High. |
|
||||
|
||||
**Pool + local também aceitam** Composer 2.5 e Grok 4.5 localmente, mas o `model-local:` é **sempre** um slug DeepSeek — é a referência canônica para quem abre a Issue no Zed.
|
||||
|
||||
**Removidos** desta skill (não usar como 1ª escolha nem fallback documentado): Kimi K2.7, Haiku, GLM, Gemini, Luna. O pool mapeia os slugs `model:` para a API Cloud (`grok-4.5`+`effort`, `kimi-k3`+`reasoning`); slug desconhecido → fallback `composer-2.5`.
|
||||
|
||||
### Quando sair do Composer → Grok (eixo 1)
|
||||
|
|
@ -70,24 +50,6 @@ Depois de escolher Grok, **obrigatório** pickar um effort. Escreva o slug compl
|
|||
|
||||
**Heurística anti-viés:** se você ia marcar High por hábito, pergunte "a falha é cara **e** o desenho é aberto?". Se só uma das duas → Medium (ou Low). Se nenhuma → Composer.
|
||||
|
||||
### Effort DeepSeek V4 (eixo 3 local)
|
||||
|
||||
Depois de escolher o `model:` do pool, **obrigatório** declarar o `model-local:` com o slug DeepSeek correspondente. A família (Flash vs Pro) e o effort (high vs max) são determinados pelo `model:` do pool:
|
||||
|
||||
**Mapeamento canônico `model:` → `model-local:`:**
|
||||
|
||||
| `model:` (pool) | `model-local:` (DeepSeek) | Por quê |
|
||||
| --------------- | ------------------------- | ------- |
|
||||
| `composer-2.5` | `deepseek-v4-flash-high` | Composer-class → Flash: rápido, barato, execução com julgamento leve |
|
||||
| `cursor-grok-4.5-low` | `deepseek-v4-high` | Grok-class → Pro: deliberação, mesmo que leve |
|
||||
| `cursor-grok-4.5-medium` | `deepseek-v4-high` | Grok-class → Pro: análise moderada, trade-offs |
|
||||
| `cursor-grok-4.5-high` | `deepseek-v4-max` | Grok High → Pro-max: multi-domínio, design não óbvio, custo de falha alto |
|
||||
| `kimi-k3-low` | `deepseek-v4-max` | Kimi K3 > Grok 4.5 em capacidade → Pro-max: execução de blast radius alto (refactors, migrations+RBAC, simplify amplo) |
|
||||
|
||||
**Flash-max (`deepseek-v4-flash-max`)** existe mas é exceção: só quando uma Issue Composer-class tem complexidade inesperada e o agente local decide subir o effort sem trocar de família. Não é o default de mapeamento nenhum.
|
||||
|
||||
**Kimi K3 Low é exceção à regra Flash/Pro:** mais potente que Grok 4.5, vai direto para Pro-max — é execução, mas de blast radius alto e com plano fechado, não execução mecânica trivial.
|
||||
|
||||
### Pool × API Cloud
|
||||
|
||||
| Slug `model:` | API `model.id` | params |
|
||||
|
|
@ -98,8 +60,6 @@ Depois de escolher o `model:` do pool, **obrigatório** declarar o `model-local:
|
|||
| `kimi-k3-low` | `kimi-k3` | `reasoning=low` |
|
||||
| `composer-2.5` | `composer-2.5` | `fast=false` |
|
||||
|
||||
Slugs `model-local:` (`deepseek-v4-high`, `deepseek-v4-max`, `deepseek-v4-flash-high`, `deepseek-v4-flash-max`) **não são enviados ao pool** — são consumidos apenas pelo agente local (Zed).
|
||||
|
||||
## Issues muito complexas
|
||||
|
||||
O plano de **implementação** nasce em `work-issue` / `agent-work-issue` (`*-impl.md`), não em `plan-issue`. Preferir **uma** Issue de intenção + Grok no `model:` quando a deliberação de engenharia for cara.
|
||||
|
|
@ -108,26 +68,25 @@ Bipartir (`{id}-plan` Grok High → `{id}-exec` `kimi-k3-low`) só sob pedido ex
|
|||
|
||||
## Regras
|
||||
|
||||
1. **Composer 2.5 é o default de pool.** Se a tarefa cabe nele, não suba de modelo.
|
||||
1. **Composer 2.5 é o default.** Se a tarefa cabe nele, não suba de modelo.
|
||||
2. **Grok exige effort explícito** (`-low` / `-medium` / `-high` no slug). Não deixe `cursor-grok-4.5` sem sufixo; não use High como coringa.
|
||||
3. **Toda Issue declara `model-local:`** com o slug DeepSeek V4 correspondente, conforme o mapeamento canônico. Issue sem `model-local:` está incompleta.
|
||||
3. **Toda Issue declara `model:` único** (slug Cursor conforme a tabela). Issue sem `model:` está incompleta.
|
||||
4. **Nunca `-fast`.** Nem em Issue, nem em `Task.model`, nem sob pedido — recusar e usar o slug sem `-fast`.
|
||||
5. **Kimi K3 Low só na exec bipartida** (ou quando a Issue já declara `kimi-k3-low` após um plan).
|
||||
6. **Nunca economizar em:** migrations (história congelada), access control (`overrideAccess: false`), Consent/LGPD — se for uma Issue só disso e complexa, bipartir (plan Grok High → exec K3).
|
||||
7. **Usuário pediu modelo específico:** a escolha dele vence (exceto `-fast`, sempre recusado); avise uma vez se houver desperdício claro.
|
||||
8. **`model-local:` é sempre DeepSeek.** O agente local pode usar Composer/Grok na sessão se fizer sentido, mas o frontmatter declara o DeepSeek canônico.
|
||||
|
||||
## Como aplicar
|
||||
|
||||
- **Frontmatter da Issue:** `model:` (slug pool) + `model-local:` (slug DeepSeek, conforme mapeamento). Ambos obrigatórios.
|
||||
- **Frontmatter da Issue:** `model:` único (slug Cursor). No `plan-issue`, sugerir um slug completo com effort; no pool, o spawn usa exatamente o `model:`.
|
||||
- **Subagentes (`Task.model`):** prefira o slug da Issue quando o enum do produto listar (`composer-2.5`, `cursor-grok-4.5-high`, `kimi-k3-low`, …). **Nunca** escolha variantes `-fast` do enum. Se a Issue é `-low`/`-medium` e o enum não tem o slug, use `inherit` (sessão já no effort certo) ou `cursor-grok-4.5-high` só se a subtarefa for a parte difícil — **não** "promova" a Issue inteira para High.
|
||||
- **Sessão principal:** o agente não troca o próprio modelo. Se o atual não for o da tabela, diga em uma linha e siga.
|
||||
- **Sessão principal:** o agente não troca o próprio modelo. No `work-issue` (máquina do humano) o modelo é fixo por ambiente — a skill não verifica `model:` (ver gates). No pool, o spawn já fixa o modelo da Issue.
|
||||
- **Pool:** `POOL_DEFAULT_MODEL_SLUG` = `composer-2.5`; `resolvePoolModel` mapeia os slugs canônicos → API e **sempre** inclui `fast=false` quando o modelo Cloud aceita o param (senão o dashboard fatura `*-fast`).
|
||||
|
||||
## Gates por fluxo
|
||||
|
||||
- **`/simplify`:** herda o modelo da sessão. Preferir sessão em Kimi K3 Low **só** quando houver Issue de exec bipartida; caso contrário Composer ou Grok (effort pela tabela) conforme complexidade.
|
||||
- **`work-issue`:** verifica `model:` + `model-local:` (assimétrico: mais fraca → informa e segue; mais forte → informa e **pausa**). Ausentes → aplica esta tabela.
|
||||
- **`work-issue`:** **não verifica modelo** — a sessão nasce no modelo fixo do ambiente (máquina do humano: DeepSeek V4 Flash). `model:` da Issue é metadata consultiva (o pool spawna nele; o claim brief o imprime).
|
||||
- **`agent-work-issue`:** pool já fixou o modelo no spawn; sessão mais forte → informa e segue.
|
||||
- **`plan-issue`:** sugere via esta tabela (slug completo com effort); bipartição só sob blast radius extremo / pedido explícito.
|
||||
- **`plan-issue`:** sugere via esta tabela (slug único completo com effort); bipartição só sob blast radius extremo / pedido explícito.
|
||||
- **`agent-pool` smoke:** Composer default; Grok com effort explícito / Kimi K3 Low em Issues de teste bipartidas.
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ rascunho local (Issue: —)
|
|||
| 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: claim → plano de **implementação** (Plan mode) → **pausa** para confirmação → executa. |
|
||||
| **`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 canvas de rascunho UI/UX é artefato do **gate de intenção**, não entrega de app.
|
||||
|
|
|
|||
|
|
@ -183,7 +183,7 @@ Opcional e leve (se o rebase tocou schema/types): `pnpm exec tsc --noEmit` nos a
|
|||
3. Quantos commits rebased / se no-op
|
||||
4. Conflitos resolvidos — rebase e/ou stash pop (paths + uma linha de racional cada) **ou** “nenhum”
|
||||
5. Se abortou: por quê + o que precisa de decisão
|
||||
6. Próximo passo natural: `capture-review-debts` (se ainda não rodou) e o fechamento da sessão no Passo 6 de `work-issue` (PR `--base stage` + CI até o merge)
|
||||
6. Próximo passo natural: `capture-review-debts` (se ainda não rodou) e o fechamento da sessão no Passo 6 de `work-issue` (PR `--base main` + CI até o merge)
|
||||
|
||||
## Anti-padrões
|
||||
|
||||
|
|
|
|||
|
|
@ -1,80 +1,106 @@
|
|||
---
|
||||
name: work-issue
|
||||
description: >-
|
||||
Versão humana de agent-work-issue: claim de uma Issue, Plan mode com plano
|
||||
de implementação deliberado a partir da intenção, pausa para confirmação
|
||||
humana, depois execução → /simplify → capture-review-debts → PR Ready em
|
||||
main com auto-merge. Use quando o usuário pedir /work-issue, quiser
|
||||
supervisionar a abordagem de engenharia, ou trabalhar uma Issue com gate
|
||||
humano antes do código.
|
||||
Executa uma Issue já claimada de ponta a ponta com supervisão humana:
|
||||
o contexto da sessão identifica a Issue (sem claim), Plan mode com plano
|
||||
de implementação, pausa para confirmação humana, depois execução →
|
||||
/simplify → capture-review-debts com gate → PR Ready em main com
|
||||
auto-merge. Use quando o usuário pedir /work-issue, quiser supervisionar
|
||||
a abordagem de engenharia, ou trabalhar uma Issue com gate humano antes
|
||||
do código.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Work-issue (humano supervisiona)
|
||||
|
||||
Mesmo pipeline de [`agent-work-issue`](../agent-work-issue/SKILL.md), com duas diferenças:
|
||||
Fluxo próprio do humano na sua máquina, com a sessão aberta no worktree da
|
||||
Issue. A sessão **já nasce no contrato**: Issue claimada, worktree correto,
|
||||
branch correta, modelo fixo do ambiente — o claim é feito **fora da skill**
|
||||
(hoje: `pnpm agent:claim` manual antes da sessão; OPS33: o `worktree next`
|
||||
claima). A skill assume isso e vai direto ao trabalho — **nenhum passo de
|
||||
claim/ambiente/modelo** (só a validação de contexto do Passo 1).
|
||||
|
||||
1. **Você claima** a Issue (`pnpm agent:claim`).
|
||||
2. **Pausa após o plano de implementação** até o humano confirmar — só então executa.
|
||||
O pool tem a skill irmã `agent-work-issue` (workers Cursor Cloud, autônoma) —
|
||||
não é base nem filha desta. Os materiais compartilhados vivem aqui como
|
||||
referência: `engineering-brief.md`, `implementation-template.md`,
|
||||
`decision-quality.md`, `execution-pipeline.md` (mecânica de execução →
|
||||
fechamento, com deltas por ator).
|
||||
|
||||
**Proibido:** DB de prod; merge sem CI green; editar outras Issues `in-progress`; pular a pausa do impl plan; Draft / sem auto-merge.
|
||||
**Proibido:** DB de prod; merge sem CI green; editar outras Issues `in-progress`;
|
||||
pular a pausa do impl plan; Draft / sem auto-merge.
|
||||
|
||||
## Checklist
|
||||
|
||||
```
|
||||
- [ ] 0. Prep: `pnpm i` se preciso
|
||||
- [ ] 1. Claim: pnpm agent:claim (ou -- --issue <N>)
|
||||
- [ ] 1b. rename_chat + open_resource (intenção)
|
||||
- [ ] 2. Verificação de modelo (assimétrica — pausa se sessão mais forte)
|
||||
- [ ] 3. Plan mode → escrever `*-impl.md` → **PARAR e confirmar com o humano**
|
||||
- [ ] 4. Após “ok”: executar como agent-work-issue Passos 4–6
|
||||
- [ ] 1. Contexto: Issue do prompt/`$ARGUMENTS` da sessão (ausente → UMA pergunta com validação; nunca claim)
|
||||
- [ ] 2. Abrir o plano de intenção do body da Issue (`Plano: docs/plans/...`; sem link → body é spec)
|
||||
- [ ] 3. Plan mode → escrever `docs/plans/<slug>-impl.md` → **PARAR e confirmar com o humano**
|
||||
- [ ] 4. Após “ok”: Passo 4 (execução → /simplify → débitos com gate → PR, via `execution-pipeline.md`)
|
||||
```
|
||||
|
||||
## Passo 0–1 — Prep e claim
|
||||
## Passo 1 — Contexto da sessão
|
||||
|
||||
```bash
|
||||
pnpm i
|
||||
pnpm agent:claim # topo da fila
|
||||
pnpm agent:claim -- --issue <N>
|
||||
```
|
||||
A Issue chega no prompt/`$ARGUMENTS` do `/work-issue` (`--issue <N>` ou o número —
|
||||
contrato OPS33; chamada manual: passar o número). Sempre consulte o GitHub para o
|
||||
resto (fonte única é a Issue, nunca um brief duplicado).
|
||||
|
||||
O brief do stdout é o contrato de **produto** (id, prio, model, link da intenção). Claim = `ready → in-progress`.
|
||||
- **Presente** → valide o básico (`gh issue view <N>`: existe, `OPEN`, label
|
||||
`in-progress` — confirma que o claim foi feito fora da skill) e use.
|
||||
- **Ausente** → **uma** pergunta ao humano ("Qual Issue?"), valide o número
|
||||
informado com a mesma checagem e siga.
|
||||
- **Checagem falhou** (não existe / não `OPEN` / sem `in-progress`) → a Issue
|
||||
não está claimada: **pare e peça ao humano** para claimar fora da skill
|
||||
(`pnpm agent:claim --issue <N>`; no pós-OPS33, o `worktree next` já claima).
|
||||
Nunca siga com Issue não claimada, nunca claim na sessão.
|
||||
- **Nunca rode `pnpm agent:claim`** — claim é contrato do ambiente (worktree
|
||||
next / script), não da skill.
|
||||
- **Modelo: não verifique.** `model:` da Issue é metadata consultiva (o pool
|
||||
spawna nele; o claim brief o imprime). A sessão da máquina do humano é sempre
|
||||
o modelo fixo do ambiente (DeepSeek V4 Flash).
|
||||
|
||||
### Rename + abrir intenção
|
||||
## Passo 2 — Intenção
|
||||
|
||||
Padrão: `#<N> <id> — <título>` via `cursor-app-control` `rename_chat`.
|
||||
Abra o plano de intenção com `open_resource` (`file:///…/docs/plans/<slug>.md`).
|
||||
|
||||
## Passo 2 — Modelo
|
||||
|
||||
Regra assimétrica (`model-selection`):
|
||||
|
||||
- Sessão **mais fraca** que `model:` → informa e segue
|
||||
- Sessão **mais forte** → **informa e pausa** (“pedir X, está em Y — seguir?”)
|
||||
- Ausente → aplique model-selection e registre na Issue
|
||||
O path do plano de intenção vem do **body da Issue** (`Plano: [docs/plans/<slug>.md]` —
|
||||
mesmo contrato de `extractPlanPath` do prompt do pool). Sem plano linkado → o body
|
||||
é a spec. Abra e leia.
|
||||
|
||||
## Passo 3 — Plano de implementação + GATE humano
|
||||
|
||||
Siga o **Passo 3** de `agent-work-issue` (Plan mode, engineering-brief, decision-quality, `docs/plans/<slug>-impl.md`).
|
||||
Plan mode: `SwitchMode` → `plan` (deliberar engenharia a partir da intenção).
|
||||
|
||||
Depois de gravar o impl plan:
|
||||
1. Leia `engineering-brief.md` e aplique skills/princípios sob demanda.
|
||||
2. Explore o código o bastante para **reavaliar** a "Direção no codebase" da
|
||||
intenção — você **deve** escolher a melhor abordagem maintainable, mesmo que
|
||||
difira da hipótese do plano de intenção, desde que o **aceite de produto** se
|
||||
mantenha.
|
||||
3. Escreva `docs/plans/<slug>-impl.md` via `implementation-template.md`.
|
||||
Qualidade: `decision-quality.md` ≥4/5.
|
||||
4. Apresente no chat: abordagem recomendada, opções rejeitadas, fases, riscos,
|
||||
o que diverge da hipótese de direção da intenção.
|
||||
5. **Pare.** Não escreva código de feature até confirmação explícita ("ok",
|
||||
"pode executar", "aprovado", …).
|
||||
6. Se o humano pedir mudança de abordagem → revise o `*-impl.md` e reapresente.
|
||||
7. Confirmação → marque Status `aprovado` no impl plan → `SwitchMode` `agent` →
|
||||
continue.
|
||||
|
||||
1. Apresente no chat: abordagem recomendada, opções rejeitadas, fases, riscos, o que diverge da hipótese de direção da intenção.
|
||||
2. **Pare.** Não escreva código de feature até confirmação explícita (“ok”, “pode executar”, “aprovado”, …).
|
||||
3. Se o humano pedir mudança de abordagem → revise o `*-impl.md` e reapresente.
|
||||
4. Confirmação → marque Status `aprovado` no impl plan → `SwitchMode` `agent` → continue.
|
||||
Divergência material de produto (aceite/persona/lockdown da intenção não cabem):
|
||||
pare e **pergunte ao humano** — ele decide entre item sucessor ou `blocked`;
|
||||
nunca invente produto novo.
|
||||
|
||||
## Passos 4–6 — Execução
|
||||
## Passo 4 — Executar
|
||||
|
||||
Idênticos a `agent-work-issue`:
|
||||
`SwitchMode` → `agent` se ainda estiver em plan. Siga a mecânica de
|
||||
[`execution-pipeline.md`](execution-pipeline.md) (executar → simplify →
|
||||
fechar em main), com os deltas do ator humano:
|
||||
|
||||
- Executar fases (schema/server → UI → gates)
|
||||
- `/simplify` completo + fixes
|
||||
- `capture-review-debts` **com** gate humano (Passo 5 daquela skill) — não use o modo autônomo do pool
|
||||
- `pnpm push` → PR Ready `--base main` + `Closes #N` → auto-merge → `gh pr checks --watch --required`
|
||||
|
||||
Detalhes, Prep Cloud, invariantes e templates: leia [`agent-work-issue/SKILL.md`](../agent-work-issue/SKILL.md) e os arquivos em `.agents/skills/work-issue/` (`engineering-brief.md`, `implementation-template.md`, `decision-quality.md`).
|
||||
- **Branch:** `<Code>-<slug>` do worktree — nunca crie branch nova na sessão.
|
||||
- **UI:** shape → craft → critique → polish.
|
||||
- **`capture-review-debts`:** **com gate humano** — colha e pontue como a
|
||||
skill manda, apresente ao humano antes de registrar (Issues novas com
|
||||
`depends` no pai se necessário).
|
||||
|
||||
## Resumo final
|
||||
|
||||
Issue claimada · sessão renomeada · intenção aberta · modelo · **impl plan confirmado pelo humano** · execução · simplify/débitos · PR + merge.
|
||||
Issue (contexto da sessão) · impl plan (abordagem + rejeitadas + divergências da
|
||||
hipótese) · simplify + débitos registrados/deferidos · PR + estado do merge.
|
||||
|
|
|
|||
44
.agents/skills/work-issue/execution-pipeline.md
Normal file
44
.agents/skills/work-issue/execution-pipeline.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
# Pipeline de execução compartilhada (work-issue / agent-work-issue)
|
||||
|
||||
Mecânica comum de execução → fechamento das duas skills do fluxo (humano e
|
||||
workers do pool). O corpo mora aqui; cada skill declara os **deltas do seu
|
||||
ator** e referencia este material — nenhuma é "base" da outra.
|
||||
|
||||
## Executar
|
||||
|
||||
Ordem:
|
||||
|
||||
1. **Schema/server** — migrations (`payload-migrations`), utilities, actions,
|
||||
testes de domínio. Invariantes do engineering-brief.
|
||||
2. **UI** — se Impeccable B/C/D: shape → craft → critique → polish. Tokens
|
||||
`data-theme='campaign'`; shells existentes.
|
||||
3. **Gates** — `pnpm gate:fast` na iteração; entrega com `pnpm push` (não
|
||||
`git push` nu).
|
||||
|
||||
Tracer bullet cedo se o item for grande. Inclua o `*-impl.md` no commit da
|
||||
entrega.
|
||||
|
||||
## /simplify + débitos
|
||||
|
||||
1. Rode o comando `/simplify` completo (3 reviewers paralelos via Task,
|
||||
read-only) no diff da sessão.
|
||||
2. Aplique fixes pontuais que preservem comportamento.
|
||||
3. Rode `capture-review-debts` no modo do ator (ver deltas). Nunca edite a
|
||||
Issue `in-progress` atual para absorver débitos.
|
||||
|
||||
## Fechar em main
|
||||
|
||||
1. Branch do ator (ver deltas) — nunca crie branch nova fora dela.
|
||||
2. **`pnpm push -u origin HEAD`**
|
||||
3. PR **Ready** (nunca draft): `gh pr create --base main` com `Closes #<N>`
|
||||
4. `gh pr merge --auto --merge` imediatamente
|
||||
5. `gh pr checks <PR> --watch --required` (`checks` + `migration-lock`; ignore
|
||||
Vercel Git)
|
||||
6. CI flipa `done`/`in-prod` no merge. Comente na Issue o desfecho em uma linha.
|
||||
|
||||
## Deltas por ator
|
||||
|
||||
| Ator | Branch | UI | `capture-review-debts` | Cloud |
|
||||
| ---- | ------ | --- | ---------------------- | ----- |
|
||||
| **Humano** (`work-issue`) | `<Code>-<slug>` (worktree; nunca crie branch nova na sessão) | shape → craft → critique → polish | **com gate humano** — colha, pontue e apresente antes de registrar | n/a (máquina do humano) |
|
||||
| **Pool** (`agent-work-issue`) | `agent/<id>-<slug>` (worktrees Cursor podem já ter criado) | shape → craft → critique → polish (harden/optimize só sob gatilho) | **autônomo** — só `expensive_lock` com score ≥4 (Issues novas com `depends`); score ≤3 / cheap_polish / defer_trigger → defer no `*-impl.md` ou descarte | `ManagePullRequest` com `draft: false`; Prep Cloud no Passo 0 |
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
description: Executa uma Issue claimada de ponta a ponta com supervisão humana (claim → plano de implementação → pausa → execução → simplify → PR)
|
||||
description: Executa uma Issue já claimada de ponta a ponta com supervisão humana (plano de implementação → pausa → execução → simplify → débitos → PR)
|
||||
model: deepseek/deepseek-v4-flash
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -18,9 +18,9 @@ claim → feature branch → PR --base main → CI PR green (cascade + skips)
|
|||
main → ci.yml full suite → vercel deploy --prod (se verde) → requeue se HEAD andou
|
||||
```
|
||||
|
||||
**Skills:** `plan-issue` (intenção + Issues) → `work-issue` (humano: claim → impl plan → confirmação → execução) ou `agent-work-issue` (pool: já claimada → impl plan → execução sem pausa) → `/simplify` → `capture-review-debts` → PR `--base main` → `project-status`. `docs/roadmap.md` = legado congelado; fonte canônica = GitHub Issues.
|
||||
**Skills:** `plan-issue` (intenção + Issues) → `work-issue` (humano: Issue já claimada → impl plan → confirmação → execução) ou `agent-work-issue` (pool: já claimada → impl plan → execução sem pausa) → `/simplify` → `capture-review-debts` → PR `--base main` → `project-status`. `docs/roadmap.md` = legado congelado; fonte canônica = GitHub Issues.
|
||||
|
||||
- **Agente faz sozinho:** `pnpm agent:claim` → implementa → **`pnpm push`** → PR **Ready** (nunca draft) com `Closes #N` → `gh pr merge --auto --merge` → `gh pr checks --watch --required`. Regra always-on: `.agents/rules/agent-pr-workflow.mdc`. Em Cursor Cloud: `ManagePullRequest` com `draft: false`, depois armar auto-merge via `gh pr merge --auto --merge` (o default draft da tool **não** vale neste repo).
|
||||
- **Agente faz sozinho:** claim (pool-supervisor no pool; humano via `pnpm agent:claim` fora da sessão — OPS33: `worktree next` claima) → implementa → **`pnpm push`** → PR **Ready** (nunca draft) com `Closes #N` → `gh pr merge --auto --merge` → `gh pr checks --watch --required`. Regra always-on: `.agents/rules/agent-pr-workflow.mdc`. Em Cursor Cloud: `ManagePullRequest` com `draft: false`, depois armar auto-merge via `gh pr merge --auto --merge` (o default draft da tool **não** vale neste repo).
|
||||
- **Só humano:** secrets Vercel (`VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`), `POOL_GITHUB_TOKEN`, `pnpm configure:branch-protection`, editar envs Neon/Vercel.
|
||||
|
||||
### Dono do PR, dono do CI
|
||||
|
|
|
|||
|
|
@ -4,6 +4,8 @@ Conteúdo movido do `AGENTS.md` em 2026-07-30 (fatiamento do paradigma de agente
|
|||
|
||||
---
|
||||
|
||||
**Recently resolved (2026-08-10):** **OPS32** (Issue #594) — `/work-issue` no paradigma de **Issue já claimada** + `model-selection` volta ao cardápio só-Cursor. A skill `work-issue` foi reescrita como **fluxo próprio do humano**: nenhum passo de claim/ambiente/modelo — a sessão nasce no contrato (claim fora da skill: hoje `pnpm agent:claim` manual, OPS33 no `worktree next`); o número da Issue vem do prompt/`$ARGUMENTS` (`--issue <N>`, contrato OPS33) e, ausente, **uma** pergunta ao humano com validação (`gh issue view`: OPEN + `in-progress`; **checagem falhou → para e pede o claim fora da skill** — nunca claima); o plano de intenção é recuperado do body da Issue (`Plano: [docs/plans/…]`, mesmo contrato de `extractPlanPath` do pool; sem link → body é spec). Fluxo: Plan mode → `*-impl.md` → pausa humana → execução → `/simplify` → `capture-review-debts` com gate → PR Ready `--base main` + auto-merge. **Desacoplada de `agent-work-issue`** (pool): saíram "base de execução", a linha da tabela e o wording de claim; a mecânica de execução→fechamento (Passos 4–6) foi extraída para **`.agents/skills/work-issue/execution-pipeline.md`** (material compartilhado com tabela de deltas por ator — branch `<Code>-<slug>` vs `agent/<id>-<slug>`, UI, modo do `capture-review-debts`, Cloud) e as duas skills passaram a referenciá-la, cada uma com seus deltas; os materiais de engenharia (engineering-brief/implementation-template/decision-quality) seguem como referência. **`model-selection` perdeu** a tabela Local/Zed, o frontmatter `model-local:` e o mapeamento canônico `model:`→DeepSeek (regras 3/8 e o "Como aplicar" dual): cardápio único Cursor (Composer 2.5 default; Grok com effort; Kimi K3 Low só exec bipartida), Issues declaram `model:` único, e os gates dizem que work-issue não verifica modelo. Correlatos: brief do `agent:claim` ("metadata consultiva" + footer sem o fluxo stage extinto), pool prompt (linha "verificação assimétrica" → spawn já fixa), `.opencode/commands/work-issue.md` (description sem claim), `docs/AGENT-OPS.md` (linha Skills + bullet "Agente faz sozinho" com claim fora da sessão), `plan-issue` (linha da tabela de relação alinhada), `rebase-on-main` (Passo 6 cita `--base main`). Verificado: o pool não quebra — `agent-pool-models.mjs` consome só `model:` (unit pinam slugs Cursor). AGENTS.md intocado (texto do claim do worktree é OPS33). Sem migration/access/Consent/UI. Intenção [`work-issue-paradigma-issue-claimada.md`](plans/work-issue-paradigma-issue-claimada.md); impl [`work-issue-paradigma-issue-claimada-impl.md`](plans/work-issue-paradigma-issue-claimada-impl.md).
|
||||
|
||||
**Recently resolved (2026-08-10):** **B193** (Issue #542) — card de município mobile denso + edit-where-you-see + última atualização expandível. O card de `/campanha/municipios` no mobile deixou o grid de labels e virou composição do wireframe: cabeçalho nome+território com **posição de voto 2022 à direita** (percentual em cima; colocação · votos embaixo), **barra de cenários** (pessimista·central·otimista + marcador do ativo — `VoteEstimateScenarioStrip` como trigger da sheet de votos existente), **chips** classe/tendência/nível (tendência e nível com label à esquerda, dentro do trigger — tocar no label abre a sheet; classe com razão via tooltip que abre no toque), **3 grupos de avatares com label** (Assessores/Lideranças/Dobradinhas — um avatar por entidade, wrap, sem cap; leitura de assessores para não-coordenador), rodapé **"Última atualização há X dias" + chevron que expande o limite inferior** revelando o último card de atualização (badges + corpo + autor · data, sem moldura) + CTA "Registrar atualização" (sheet existente); **sem atualização → o rodapé vira CTA direto** (sem chevron/expansão); prioritário = **borda lateral direita 6px** `border-primary` no lugar do flag; Salvador read-only; "Cobertura" (conta da cadeira) sai do card (fica na tabela/detalhe — gate humano); rodapé mede a idade da **atualização** (não o frescor update∨pledge — coluna desktop intacta). **C109 corrigida no caminho (a "sheet quebra ao abrir" era real):** os callbacks dos controles (autosave `onOpenChange`, `handleOpenChange` do nível) são recriados por render — qualquer re-render com a sheet aberta (digitar no sheet!) fazia o host descartar a sessão e o corpo sumia; sessões do host agora são **keyed por id de sessão** (imune a identidade) e o **footer customizado** (submit + `DialogClose`) passou a ser **registrado e renderizado pelo host dentro da árvore do Drawer** (portal perdia o Dialog context — o e2e antigo só abria a sheet de tendência, sem footer custom, por isso a C109 não reproduzia). Controles ganharam prop `trigger`/`triggerClassName` (precedente `RelationChipCell.trigger`); `MunicipalityRelationAvatarStack` ganhou modo wrap. Dado: `MunicipalityListViewModel.lastUpdate` (batch por página via `loadMunicipalityLastUpdates`, scoped por portfólio). E2E novos (390×844): barra abre sheet e reflete valores salvos, chip Nível abre a sheet, borda de prioridade (6px + cor), expansão/CTA vazio. Sem migration/access/Consent. Intenção [`municipios-card-mobile-edit-where-you-see.md`](plans/municipios-card-mobile-edit-where-you-see.md); impl [`municipios-card-mobile-edit-where-you-see-impl.md`](plans/municipios-card-mobile-edit-where-you-see-impl.md).
|
||||
|
||||
**Recently resolved (2026-08-10):** **OPS26** (Issue #571) — `worktree next`/`plan` **no terminal** terminam com o TUI do opencode aberto no worktree: a função `worktree()` de `.agents/shell/worktree.sh` marca `TEQO_WORKTREE_TERMINAL=1` e o script imprime a diretiva `launch opencode <dir> --model deepseek/deepseek-v4-flash --auto [--prompt /work-issue]` **antes** do `cd` (que segue sendo a última linha — contrato OPS24 intacto); a função aplica o cd e executa a linha (sem `exec`: sair do TUI volta ao shell no worktree; sem auto-`kill`). `next` envia `/work-issue` (o comando OPS25 roda o ciclo completo); `plan` abre **sem prompt** — a CLI do opencode não tem pre-fill sem submit (`--prompt` sempre auto-envia; fallback acordado: `/plan-` + autocomplete; gap registrado para o repo do opencode). Presets são constantes em `scripts/lib/worktree.mjs` (`OPENCODE_PRESET_MODEL`, `OPENCODE_SKILL_COMMAND_BY_PURPOSE`, `opencodeLaunchDirective` — pura, unit-testada; trocar de modelo é editar a constante). **Sem o marcador (comando `/worktree` do opencode, automação) a diretiva não é impressa** — nunca abre TUI aninhado; `--stay` suprime cd e launch; `kill` intocado. Docs: AGENTS.md ("Per-worktree environments"), header/uso do script, `.opencode/commands/worktree.md`, skill `worktree-next-issue`. Sem migration/dados/access/UI. Intenção [`worktree-go-abre-opencode-com-presets.md`](plans/worktree-go-abre-opencode-com-presets.md); impl [`worktree-go-abre-opencode-com-presets-impl.md`](plans/worktree-go-abre-opencode-com-presets-impl.md).
|
||||
|
|
|
|||
76
docs/plans/work-issue-paradigma-issue-claimada-impl.md
Normal file
76
docs/plans/work-issue-paradigma-issue-claimada-impl.md
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
# Impl: Work-issue no paradigma de Issue já claimada (+ model-selection volta ao cardápio Cursor)
|
||||
|
||||
Status: aprovado
|
||||
Atualizado em: 2026-08-10
|
||||
Issue: #594
|
||||
Intenção: docs/plans/work-issue-paradigma-issue-claimada.md
|
||||
Appetite restante: herdado (~1–1,5 dia; entrega pura de skills/scripts/docs — sem schema/UI)
|
||||
|
||||
## Leitura da intenção
|
||||
|
||||
- **Outcome:** uma sessão `/work-issue` sem nenhum passo de verificação (sem claim, sem checagem de worktree/branch, sem checagem de modelo) — a skill assume o contrato "Issue já claimada, worktree correto, branch correta, modelo fixo" e vai direto ao impl plan → pausa humana → execução → simplify → débitos → PR.
|
||||
- **O que NÃO negociar:** fluxo continua com impl plan → **pausa** → execução → `/simplify` → `capture-review-debts` **com gate humano** → PR Ready `--base main` + auto-merge; nunca claimar por conta própria; não duplicar a lógica de claim do pool; não virar guarda-costas (anti-goals).
|
||||
- **O que reavaliar:** a hipótese listava `AGENTS.md` como área — verificada e **descartada**: o texto de claim do `worktree next` é do OPS33 (este item é o receptor, não o produtor); a única menção a work-issue no AGENTS.md é o bullet do launch (`/work-issue` já enviado), que continua válido.
|
||||
|
||||
## Abordagem recomendada
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
S["Sessão no worktree<br/>(OPS33: já claimada)"] --> C["Contexto: /work-issue --issue N<br/>ou $ARGUMENTS; ausente → 1 pergunta<br/>com validação (gh issue view)"]
|
||||
C --> P["Plan mode → docs/plans/<slug>-impl.md<br/>(engineering-brief + template)"]
|
||||
P -->|pausa| H["Gate humano"]
|
||||
H -->|aprovado| E["Execução → gates"]
|
||||
E --> Q["/simplify + fixes"]
|
||||
Q --> D["capture-review-debts<br/>com gate humano"]
|
||||
D --> PR["PR Ready --base main<br/>Closes #N → auto-merge → checks"]
|
||||
```
|
||||
|
||||
**Opções consideradas:** A) work-issue vira fluxo próprio que consome contexto do prompt/args; B) work-issue continua delegando a agent-work-issue só tirando o claim; C) fundir as duas skills.
|
||||
**Recomendação:** A — o anti-goal da intenção proíbe "um terceiro fluxo", mas B mantém o acoplamento que a intenção quer quebrar ("deixa de ser a versão humana de agent-work-issue": o pool tem regras próprias — prep Cloud, sem pausa, débitos autônomos — e o humano tem gate humano, pergunta de contexto, validate do claim); C duplicaria as duas superfícies de operação (pool vs humano) numa só — o custo de falha do pool (claim coordenado) não cabe na skill humana.
|
||||
**Rejeitadas:** B porque mantém "base de execução" e arrastaria Prep Cloud/débitos autônomos para a sessão humana; C porque misturaria contratos de atores diferentes.
|
||||
|
||||
### Componentes / mudanças
|
||||
|
||||
- **`.agents/skills/work-issue/SKILL.md`** (reescrever): descrição no frontmatter + fluxo próprio — (0) prep `pnpm i`; (1) contexto: número da Issue vindo de `$ARGUMENTS`/prompt da sessão (`--issue <N>` ou número puro — contrato OPS33); ausente → **uma** pergunta ao humano com validação (`gh issue view`: OPEN + label `in-progress` — claim é contrato do ambiente, nunca da skill; **checagem falhou → pare e peça o claim fora da skill**); plano de intenção recuperado do **body da Issue** (`Plano: [\`docs/plans/…\`]`— mesma regex`extractPlanPath`do pool; sem plano linkado → body é spec); (2) sem verificação de modelo —`model:`é metadata consultiva, sessão da máquina do humano é sempre Flash; (3) Plan mode →`\*-impl.md`(engineering-brief/implementation-template/decision-quality como **materiais de referência**, não pipeline herdado) → **PARA**; (4) após confirmação: execução →`/simplify`→`capture-review-debts`com gate humano → PR. **Extração do /simplify:** a mecânica de execução→fechamento (Passos 4–6) vira material compartilhado novo`execution-pipeline.md`(no diretório da work-issue), referenciado pelas duas skills com tabela de deltas por ator (branch, UI, modo do capture-review-debts, Cloud) — elimina a duplicação que o rewrite introduziria. Proibidos: DB de prod, merge sem CI green, editar Issues`in-progress` de outros, pular a pausa, Draft.
|
||||
- **`.agents/skills/model-selection/SKILL.md`** (reescrever seções): remover ambiente Local/Zed, frontmatter `model-local:` e o mapeamento canônico `model:`→DeepSeek (tabelas + regras 3 e 8 + "Como aplicar" dual). Fica: cardápio só-Cursor (Composer 2.5 default; Grok 4.5 com effort obrigatório; Kimi K3 Low só exec bipartida), tabela pool×API Cloud, proibição `-fast`, heurística anti-viés, bipartição, "Issues muito complexas", e gates por fluxo atualizados: `work-issue` = **não verifica modelo** (contexto fixo; `model:` consultivo); `agent-work-issue` = pool fixou no spawn. Frontmatter description reescrito (sai "Toda Issue declara model-local"). Slug da Issue: `model:` único.
|
||||
- **`.agents/skills/agent-work-issue/SKILL.md`** (edição pontual): remover "a base de execução de `work-issue`" (linha 14) e a linha da tabela de relação (`work-issue` | "Igual, mas claim + confirmação") → passar a descrever work-issue como fluxo humano próprio; Passo 2 (modelo) fica, com wording compatível com cardápio único. Passos 4–6 passam a referenciar o `execution-pipeline.md` compartilhado, com os deltas do ator pool (branch `agent/<id>-<slug>`, harden/optimize só sob gatilho, `capture-review-debts` autônomo com score ≥4, `ManagePullRequest` com `draft: false`).
|
||||
- **`scripts/agent-claim.mjs`** (brief): linha `model:` → "(metadata consultiva — o fluxo work-issue não verifica modelo; o pool spawna nele; ver skill model-selection)"; linha "ausente" → "model: ausente — registrar slug único na Issue (gh issue edit; ver skill model-selection)". Resto do brief intacto (o claim continua existindo como script — transição + OPS33 o invoca).
|
||||
- **`scripts/lib/agent-pool-prompt.mjs`** (uma linha): "a verificação assimétrica de work-issue não se aplica" → "o work-issue não verifica modelo — o spawn do pool já fixa o modelo". Header e demais strings intactos (unit tests pinam "NÃO rode agent:claim" e "agent-work-issue/SKILL.md" — não mudam).
|
||||
- **`.opencode/commands/work-issue.md`** (description): "(claim → plano de implementação → pausa → execução → simplify → PR)" → "(Issue já claimada → plano de implementação → pausa → execução → simplify → PR)". Corpo e frontmatter `model:` intactos (guard `opencodeCommands.unit.spec.ts` só pina existência/name/$ARGUMENTS/model pin).
|
||||
- **`docs/AGENT-OPS.md`** (linha Skills): "`work-issue` (humano: claim → impl plan → confirmação → execução)" → "(humano: Issue já claimada → impl plan → confirmação → execução)".
|
||||
- **`docs/CHANGELOG-AGENTS.md`**: uma entrada no topo (entrega OPS32).
|
||||
- **Migration:** sem migration. **Access/Consent:** N/A. **UI:** Impeccable A (skills de agente, sem superfície de produto).
|
||||
|
||||
### Dados → forma
|
||||
|
||||
- N/A — sem superfície de dados.
|
||||
|
||||
## Fases verificáveis
|
||||
|
||||
1. **Skills (cardápio + desacoplamento + reescrita)** — model-selection primeiro (fonte do cardápio), depois agent-work-issue (texto), depois work-issue (fluxo novo) e o command description. Verificação: grep repo-wide de `model-local` → só hits em docs/plans congelados de outras Issues (história) e no histórico do CHANGELOG — zero hits em código vivo/skills.
|
||||
2. **Scripts + docs** — brief do claim, linha do pool prompt, AGENT-OPS, CHANGELOG. Verificação: unit tests do pool prompt e do guard opencodeCommands verdes sem edição; `pnpm gate:fast`.
|
||||
3. **Gates de entrega** — `pnpm gate:fast` na iteração; entrega com `pnpm push` (não `git push` nu); `/simplify` completo no diff da sessão; `capture-review-debts` com gate humano.
|
||||
|
||||
## Rabbit holes / Não escopo (engenharia)
|
||||
|
||||
- **Editar a intenção** (`docs/plans/work-issue-paradigma-issue-claimada.md`): imutável (Issue `in-progress` desde o claim).
|
||||
- **Texto de claim do `worktree next` / skill `worktree-next-issue` / `scripts/worktree.mjs`** ("claim continua sendo pnpm agent:claim", linha 368): é o OPS33 (produtor do claim) — este item é o receptor.
|
||||
- **`plan-issue`**: verificado — Passo 4 já sugere slug único, zero menções a `model-local`; única mudança: a linha da tabela de relação (Passo "Divisão com as skills") passa a dizer "Issue já claimada" (achado do /simplify).
|
||||
- **Mudar o comportamento do pool** (claim coordenado, `agent-pool-models.mjs`, spawn): intacto — `resolvePoolModel` só consome `model:` (verificado no código; unit tests pinam slugs Cursor).
|
||||
- **Script novo para parsear `$ARGUMENTS`**: a skill é um documento — o agente parseia os args; criar runtime seria guarda-costas.
|
||||
- **Editar impl plans congelados de outras Issues** que citam `model-local:` (ex. `porta-e2e-isolada-por-worktree-impl.md`, `c97-…-impl.md`): história, não código.
|
||||
- **README.md / docs/roadmap.md**: fluxo genérico ("claim → PR") permanece verdadeiro; sem mudança.
|
||||
|
||||
## Riscos e mitigação
|
||||
|
||||
- **Remover `model-local` quebra o spawn do pool?** Não — `agent-pool-models.mjs` consome só `model:`; nenhum `.mjs` referencia `model-local` (grep). Mitigação: gate:fast cobre os unit do pool.
|
||||
- **Sessão /work-issue sem número da Issue (fallback humano)**: pergunta única com validação `gh issue view` (OPEN + `in-progress`) — nunca claim; 1 round resolve (decisão de produto do gate 2026-08-10).
|
||||
- **Drift do contrato com o OPS33**: este item define o **consumo** (`--issue <N>` ou número no prompt); o OPS33 define a **produção**; contrato explícito nas duas skills (`worktree-next-issue` + `work-issue`) para o merge de OPS33 não quebrar.
|
||||
- **Sessão desta própria Issue (transição)**: já rodou `pnpm agent:claim` pelo fluxo antigo — transição esperada, documentada na intenção (claim fora da skill continua sendo `pnpm agent:claim` manual).
|
||||
|
||||
## Aceite de engenharia
|
||||
|
||||
- [x] Aceite de produto da intenção ainda coberto (skill sem claim/verificações; contexto do body; cardápio Cursor único; #582 fechado por eliminação da situação)
|
||||
- [x] Invariantes AGENTS/engineering-standards (nada de DB/access/Consent/migration; docs são a entrega)
|
||||
- [x] Testes de domínio previstos: unit existentes (pool prompt, opencode commands, worktree) verdes sem edição; sem unit novo (delta é texto/processo)
|
||||
- [x] Self-score decision-quality: 5/5 (decisões com rejeitadas; cabe no appetite; rabbit holes nomeados; reusa contrato `extractPlanPath`; intenção preservada)
|
||||
|
|
@ -104,11 +104,11 @@ console.log(` id: ${issueId ?? '(none)'} priority: ${pick.priority}`)
|
|||
console.log(` rename_chat: ${sessionTitle.slice(0, 200)}`)
|
||||
if (pick.meta.model) {
|
||||
console.log(
|
||||
` model: ${pick.meta.model} (propriedade da Issue — verificar, não recalcular; ver skill model-selection)`,
|
||||
` model: ${pick.meta.model} (metadata consultiva — o work-issue não verifica modelo; o pool spawna nele; ver skill model-selection)`,
|
||||
)
|
||||
} else {
|
||||
console.log(
|
||||
' model: ausente — aplicar model-selection uma vez e registrar na Issue (gh issue edit)',
|
||||
' model: ausente — registrar slug único na Issue (gh issue edit; ver skill model-selection)',
|
||||
)
|
||||
}
|
||||
if (pick.satisfiedWithoutIssue.length > 0) {
|
||||
|
|
@ -120,6 +120,6 @@ console.log(` url: https://github.com/fsolla/teqo/issues/${pick.issue.number}`)
|
|||
console.log('\n--- spec ---\n')
|
||||
console.log(rest.trim() || '(empty body — see linked plan)')
|
||||
console.log(
|
||||
'\n[agent:claim] Fluxo: rename_chat (cursor-app-control) → implementar → gate:fast → pnpm push -u origin HEAD → gh pr create --base main (Closes #' +
|
||||
`${pick.issue.number}) → PARAR. Promote stage→main é automático após CI stage green.`,
|
||||
'\n[agent:claim] Fluxo: claim feito fora da sessão → abra a sessão de trabalho no worktree (skill `work-issue`, humano; no pool, o prompt do worker aponta `agent-work-issue`) → gates → PR Ready --base main (Closes #' +
|
||||
`${pick.issue.number}) → auto-merge.`,
|
||||
)
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ export const buildPoolWorkerPrompt = ({ issueNumber, issueTitle, issueId, planPa
|
|||
'- Tratar o plano de intenção como contrato de engenharia — ele é intenção; o `*-impl.md` é a engenharia.',
|
||||
'',
|
||||
modelSlug
|
||||
? `Modelo declarado da Issue: \`${modelSlug}\` — você foi spawnado nele (ou no fallback documentado pelo pool); a verificação assimétrica de work-issue não se aplica.`
|
||||
? `Modelo declarado da Issue: \`${modelSlug}\` — você foi spawnado nele (ou no fallback documentado pelo pool); o spawn do pool já fixa o modelo.`
|
||||
: 'A Issue não declara `model:` — você foi spawnado no default do pool (composer-2.5).',
|
||||
'',
|
||||
`Ao terminar — merge concluído ou falha terminal — comente na Issue #${issueNumber} o desfecho em uma linha e encerre.`,
|
||||
|
|
|
|||
Loading…
Reference in a new issue