diff --git a/.agents/skills/agent-work-issue/SKILL.md b/.agents/skills/agent-work-issue/SKILL.md index 7684d0a9..eed2e251 100644 --- a/.agents/skills/agent-work-issue/SKILL.md +++ b/.agents/skills/agent-work-issue/SKILL.md @@ -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` → `# — ` (padrão canônico; truncar só o título). 2. `open_resource` no plano de intenção (`docs/plans/.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: []` 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/-` (worktrees Cursor podem já ter criado). -2. **`pnpm push -u origin HEAD`** -3. PR **Ready** (nunca draft): `gh pr create --base main` com `Closes #` — ou Cloud `ManagePullRequest` com `draft: false` -4. `gh pr merge --auto --merge` imediatamente -5. `gh pr checks --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/-` (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: []` 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 diff --git a/.agents/skills/model-selection/SKILL.md b/.agents/skills/model-selection/SKILL.md index 572cd2b9..058d858a 100644 --- a/.agents/skills/model-selection/SKILL.md +++ b/.agents/skills/model-selection/SKILL.md @@ -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. diff --git a/.agents/skills/plan-issue/SKILL.md b/.agents/skills/plan-issue/SKILL.md index 5bd89714..3b1793b4 100644 --- a/.agents/skills/plan-issue/SKILL.md +++ b/.agents/skills/plan-issue/SKILL.md @@ -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. diff --git a/.agents/skills/rebase-on-main/SKILL.md b/.agents/skills/rebase-on-main/SKILL.md index 96154b1f..ddb8e64f 100644 --- a/.agents/skills/rebase-on-main/SKILL.md +++ b/.agents/skills/rebase-on-main/SKILL.md @@ -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 diff --git a/.agents/skills/work-issue/SKILL.md b/.agents/skills/work-issue/SKILL.md index 65768bff..fcf4d038 100644 --- a/.agents/skills/work-issue/SKILL.md +++ b/.agents/skills/work-issue/SKILL.md @@ -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 ) -- [ ] 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/-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 -``` +A Issue chega no prompt/`$ARGUMENTS` do `/work-issue` (`--issue ` 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 `: 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 `; 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: `# — ` via `cursor-app-control` `rename_chat`. -Abra o plano de intenção com `open_resource` (`file:///…/docs/plans/.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/.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/-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/-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:** `-` 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. diff --git a/.agents/skills/work-issue/execution-pipeline.md b/.agents/skills/work-issue/execution-pipeline.md new file mode 100644 index 00000000..cfbbce6e --- /dev/null +++ b/.agents/skills/work-issue/execution-pipeline.md @@ -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 #` +4. `gh pr merge --auto --merge` imediatamente +5. `gh pr checks --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`) | `-` (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/-` (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 | diff --git a/.opencode/commands/work-issue.md b/.opencode/commands/work-issue.md index 00ad048f..ca9724ec 100644 --- a/.opencode/commands/work-issue.md +++ b/.opencode/commands/work-issue.md @@ -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 --- diff --git a/docs/AGENT-OPS.md b/docs/AGENT-OPS.md index e98bedd1..18f0e674 100644 --- a/docs/AGENT-OPS.md +++ b/docs/AGENT-OPS.md @@ -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 diff --git a/docs/CHANGELOG-AGENTS.md b/docs/CHANGELOG-AGENTS.md index 7f8a80ba..97705ad6 100644 --- a/docs/CHANGELOG-AGENTS.md +++ b/docs/CHANGELOG-AGENTS.md @@ -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 `, 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 `-` vs `agent/-`, 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 --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). diff --git a/docs/plans/work-issue-paradigma-issue-claimada-impl.md b/docs/plans/work-issue-paradigma-issue-claimada-impl.md new file mode 100644 index 00000000..0682fd93 --- /dev/null +++ b/docs/plans/work-issue-paradigma-issue-claimada-impl.md @@ -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
(OPS33: já claimada)"] --> C["Contexto: /work-issue --issue N
ou $ARGUMENTS; ausente → 1 pergunta
com validação (gh issue view)"] + C --> P["Plan mode → docs/plans/<slug>-impl.md
(engineering-brief + template)"] + P -->|pausa| H["Gate humano"] + H -->|aprovado| E["Execução → gates"] + E --> Q["/simplify + fixes"] + Q --> D["capture-review-debts
com gate humano"] + D --> PR["PR Ready --base main
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 ` 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/-`, 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 ` 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) diff --git a/scripts/agent-claim.mjs b/scripts/agent-claim.mjs index 01c80014..7bc78eef 100644 --- a/scripts/agent-claim.mjs +++ b/scripts/agent-claim.mjs @@ -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.`, ) diff --git a/scripts/lib/agent-pool-prompt.mjs b/scripts/lib/agent-pool-prompt.mjs index 326eb15f..264382e8 100644 --- a/scripts/lib/agent-pool-prompt.mjs +++ b/scripts/lib/agent-pool-prompt.mjs @@ -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.`,