teqo-backup/docs/plans/work-issue-paradigma-issue-claimada.md

Work-issue no paradigma de Issue já claimada (+ model-selection volta ao cardápio Cursor)

Status: rascunho Atualizado em: 2026-08-10 Issue: #594 Priority: P2 Model: composer-2.5 Impeccable: A — N/A (skills de agente, sem superfície de produto) Canvas UI: N/A — sem UI Appetite: ~1–1,5 dia; um outcome verificável (sessão /work-issue sem nenhum passo de verificação) Responsável: —

Intenção

Todo /work-issue hoje re-executa passos que o contexto já garante: claim (é um script determinístico — o próprio fluxo vai rodá-lo antes, no worktree next), verificação de worktree/branch (a sessão nasce no worktree certo) e verificação de modelo (a sessão é sempre DeepSeek V4 Flash na máquina do humano). Isso gasta requests/tokens toda sessão e ainda permitiu o agente-miss #582 (branch criada no main em vez da worktree). No novo paradigma, a skill assume o contrato: Issue já claimada, worktree correto, branch correta, modelo fixo — e vai direto ao trabalho. Desacopla de agent-work-issue (que segue sendo a skill dos workers do Cursor Cloud/pool, com suas próprias regras) e simplifica model-selection: sem alternativas locais (model-local), só o cardápio Cursor como era antes.

Persona e fluxo

• Persona / contexto: o humano na sua máquina, sessão opencode no worktree da Issue (aberta pelo worktree next — OPS33). Sessão sempre DeepSeek V4 Flash.
• Job principal: sair do plano de intenção ao PR com gate humano no impl plan — sem overhead de verificação.
• Fluxo desejado:
  1. worktree next claima e abre o opencode com /work-issue já informando a Issue;
  2. a skill identifica a Issue pelo contexto da sessão (prompt/marcador do ambiente) e abre o plano de intenção — sem rodar agent:claim;
  3. Plan mode → *-impl.md → pausa → confirmação humana → execução → /simplify → capture-review-debts com gate → PR.
• Anti-goals: não virar um guarda-costas que re-verifica o que o ambiente garante; não duplicar a lógica de claim do pool; não inventar um terceiro fluxo de execução (continua havendo: humano = work-issue, pool = agent-work-issue).

Objetivo e aceite

• /work-issue não roda pnpm agent:claim, não verifica worktree/branch e não checa modelo — assume os três do contexto (se a sessão estiver em outro modelo, segue; o fluxo é da máquina do humano, sempre Flash).
• A skill recupera o contexto da Issue deterministicamente: número/ID vindo do prompt da sessão (OPS33) — se ausente, uma pergunta ao humano com validação, nunca um claim por conta própria.
• O path do plano de intenção é recuperado do body da Issue (Plano: [\docs/plans/…`]— oagent:register --planjá grava; sem plano linkado, o body é a spec — mesmo contrato do prompt do pool). Nenhuma mudança noplan-issue` é necessária para registrar o path: ele já registra.
• Work-issue deixa de ser "a versão humana de agent-work-issue": fluxo próprio (impl plan → pausa → execução → simplify → débitos → PR), reutilizando só os materiais de engenharia (engineering-brief, implementation-template, decision-quality) como referência.
• model-selection perde a tabela Local/Zed, o frontmatter model-local: e o mapeamento canônico model: → DeepSeek: volta ao cardápio só-Cursor (Composer 2.5 default; Grok com effort; Kimi K3 Low só exec bipartida). Issues declaram model: único.
• Textos correlatos ajustados (passo de modelo em agent-work-issue e no claim brief ficam compatíveis com o cardápio novo; plan-issue segue sugerindo um slug único).
• Resolve o agente-miss #582: o paradigma novo elimina a situação (a skill não cria branch nem claima — a entrega fecha #582).

Dados (intenção)

• Vou apresentar dados? Não — sem superfície de dados.

Direção no codebase (hipótese)

• Áreas prováveis: .agents/skills/work-issue/SKILL.md (reescrever: remove claim/modelo/verificações, contexto por parâmetro), .agents/skills/agent-work-issue/SKILL.md (referência a "base de work-issue" e passo de modelo), .agents/skills/model-selection/SKILL.md (remover ambiente local/model-local), .agents/skills/plan-issue/SKILL.md (Passo 4 — slug único, sem alternativa local), scripts/agent-claim.mjs (brief: texto de modelo sem model-local), AGENTS.md / docs/CHANGELOG-AGENTS.md.
• Precedente a olhar: scripts/lib/agent-pool-prompt.mjs — o pool já resolveu "como avisar o agente da Issue claimada" (buildPoolWorkerPrompt + extractPlanPath): é o molde do contexto que a skill vai consumir.
• Risco de acoplamento: o pool e o plan-issue dependem de model-selection — remover model-local não pode quebrar o spawn do pool (ele usa só model:). Work-issue parado (sem OPS33) fica com o claim fora da skill: chamada manual pede o número, não claima.

Dependências

• Nenhuma (é a fundação do paradigma; OPS33 depende dela).
• OPS32 é pré-requisito para o ponta a ponta do OPS33 (work-issue aceitar Issue já claimada).

Fora de escopo

• O claim no worktree next (OPS33 — fluxo separado).
• Mudar o comportamento do pool (claim coordenado, prompt de worker, spawn) — continua intacto.
• Mecânica fina de como o prompt do launch entrega o número da Issue (OPS33 define; aqui é só consumir o que vier).

Rabbit holes de produto

• "Já que é tudo novo, reescrever a skill inteira com novo paradigma de gates" (ex.: pausas extras, revisão de cada passo). A única mudança pedida é remover verificação/claim/modelo e ajustar a recuperação de contexto — o restante do fluxo (impl plan → pausa → execução → simplify → débitos → PR) já é o que o humano aprova.
• "Aproveitar para resolver a fila de agent-miss" (#582 entra porque é o mesmo defeito; os demais agent-miss da fila são independentes). Corte: só o #582, por causalidade direta.

Questões em aberto (produto)

• Como o agente descobre a Issue quando o prompt não trouxe o número? Decisão (gate 2026-08-10): pergunta ao humano e valida — chamada manual é exceção e 1 round resolve; claim fora da skill preserva o contrato "quem claima é o script".
• model: deve sumir do claim brief/work-issue? Decisão (gate 2026-08-10): fica como metadata consultiva — o pool ainda spawna por model: e a linha do claim é consulta barata; só a exigência de model-local sai.

Referências

• GitHub Issue #594
• Canvas UI (gate): N/A
• scripts/lib/agent-pool-prompt.mjs (precedente do contexto claimado + extractPlanPath)
• docs/plans/opencode-comandos-work-issue-e-plan-issue.md (OPS25 — origem dos comandos)
• Issue #582 (agente-miss absorvido)