Spec Ops Pipeline (Lead-Worker)

O que Spec Ops Pipeline (Lead-Worker) faz?

SKILL_DIR = o diretório que contém este arquivo.

Limites de função (innegociáveis)

Função	Pode	Não pode
Líder (você)	Ler/buscar código, executar testes/linters/builds, escrever especificações, revisões e estado da execução (no diretório run), gerenciar worktrees via worktree.sh; após o 'sim' explícito do usuário, executar migrate_to_bare.sh --apply; uma vez que o checkpoint seja aprovado, commitar o trabalho aprovado nos branches sop/* (organizado: também entre estágios) e executar pr.sh open / pr.sh merge (merge conforme auto_merge_risk); conforme auto_cleanup (ou com consentimento do usuário) limpar após PRs mesclados	Editar, criar, excluir ou mover qualquer arquivo de aplicação — no checkout principal ou em uma worktree de trabalhador (únicas exceções: migrate_to_bare.sh --apply e o fast-forward de worktree.sh sync); resolver conflitos de merge manualmente; mesclar uma tarefa que não foi APROVADA, usar --admin, ou contornar a proteção de branch
Trabalhador (subagente)	Editar arquivos na whitelist em sua worktree até que a DoD seja aprovada	Tocar arquivos não incluídos na whitelist, commitar/push, trabalhar fora de sua worktree

Com vontade de "só consertar isso"? Escreva uma especificação.

Atribuição de modelo

O pré-voo runtime fornece os modelos por função (lead = fase 1, lead_phase2, worker, worker_light, scout); o Revisor executa no lead. Funções, padrões, substituições, níveis: models.md. Se você não estiver no modelo Lead da fase atual, informe ao usuário como mudar (/model, /effort no Claude Code); não continue silenciosamente — exceto uma execução single, que mantém o modelo Lead da fase 1.

Sessões e contexto

• Fase 1: etapas 0–2 no modelo Lead da fase 1.
• Fase 2: etapas 3–6. split: começa com Retomar em uma nova sessão no modelo Lead da fase 2, lendo apenas o plano, estado e as especificações do estágio atual (autocontido). single: continua na mesma sessão.

session_split (env SOP_SESSION_SPLIT): auto (padrão) = split para qualquer tarefa de alto risco, três ou mais tarefas, ou modo staged, senão single; always → split; never → single.

O checkpoint mostra isso; o usuário pode substituir.

O estado da execução reside no diretório run (run.run_dir, <git common dir>/sop-run/): fora de toda árvore de trabalho, compartilhado por todas as worktrees, mantido entre sessões. Nunca use um bloco de anotações da sessão.

Saída de comando — execute cada comando de lint/teste/build/DoD através de bash SKILL_DIR/scripts/run_logged.sh <run dir>/logs/<slug>-<step>-<n>.log '<command>' (imprime exit=<rc> lines=<n> log=<path> + as últimas 40 linhas em caso de falha). Leia mais do log apenas quando a cauda não explicar uma falha. Nunca coloque a saída completa do teste no chat.

Fluxo de trabalho

0. Pré-voo

bash SKILL_DIR/scripts/preflight.sh --agent <claude|gemini|codex> --fetch (seu próprio runtime; --fetch atualiza um default_base remoto primeiro) imprime uma linha JSON: runtime (note worker, session_split), config (note source_worktree, default_base, provision, max_parallel, auto_merge_risk, merge_method, auto_cleanup; layout), leftovers, run, pr, baseline, base_check, docker_pool. Em um layout bare, execute comandos git/teste do Lead dentro de source_worktree. Aja em:

1. run.has_state: true (execução em andamento): pergunte ao usuário se deseja retomar , limpar (se todas as tarefas tiverem PRs aguardando o usuário), ou arquivar (worktree.sh rundir --archive) e começar de novo.
2. leftovers (tarefas de execuções anteriores): mencione-as.
3. config.offer_bare_migration: true: execute bash SKILL_DIR/scripts/migrate_to_bare.sh (dry run), pergunte ao usuário se deseja converter para o layout de worktree bare-repo, formatado conforme bare-layout.md. Apenas com um 'sim' explícito: migrate_to_bare.sh --apply, re-executar preflight.sh, reler os documentos do agente do novo source_worktree. Bloqueado ou recusado → layout padrão.
4. pr.ok: false: a execução apenas commita localmente; o checkpoint diz isso. Anote pr.into. Regras de merge: execution-plan.md.
5. base_check.match: false, fetch_error ou error: combine a base com o usuário primeiro.
6. docker_pool.error: informe ao usuário que a capacidade é desconhecida; senão docker: false: pule; senão free < config.max_parallel: avise (etapa 3 verifica novamente).
7. baseline = saída de git status --porcelain=v1 && git diff HEAD | sha256sum, já executada em source_worktree. Mantenha para state.json.

1. Auditoria (somente leitura)

• Estabeleça o escopo com o usuário (caminhos; segurança / desempenho / dívida / lacunas de especificação).
• Varra estaticamente; para um escopo grande, primeiro faça uma varredura com scouts paralelos somente leitura (scout.md) e verifique as pistas deles. Execute os comandos existentes de lint/teste/type-check do projeto para obter a verdade via run_logged.sh (logs audit-<n>.log); não instale ferramentas nem altere a configuração.
• Produza um relatório de lacunas: descobertas numeradas com file:line, severidade, evidência, correção proposta. Agrupe-as em tarefas de tamanho adequado para o Trabalhador, com whitelists pequenas e não sobrepostas.
• Com várias tarefas, elabore o plano de execução conforme execution-plan.md: sem dependências → independent (todos paralelos); relacionados → staged (estágios ordenados por dependência, paralelo dentro de um estágio, cada um construído sobre o resultado integrado do estágio anterior).

2. Especificação (checkpoint)

• Para cada tarefa, preencha worker-spec-template.md e escolha seu nível de Trabalhador (models.md). Preencha as Regras do repo a partir dos documentos do agente (AGENTS.md, CLAUDE.md, também em diretórios que a whitelist toca): comandos de teste/lint, flags, regras de linguagem; adicione armadilhas do repo de sua memória e quaisquer worker_notes. Os Trabalhadores não podem ver seu contexto. Escreva comandos DoD conforme essas regras exigem.
• Salve no diretório run, nunca em uma worktree: gap-report.md, plan.md, spec-<slug>.md, <slug>.wl.
• Verificação de sobreposição por estágio: bash SKILL_DIR/scripts/check_scope.sh --overlap <source_worktree> <slug>.wl...; OVERLAP → redividir ou reorganizar; verifique cada POSSIBLE manualmente.
• Dry run da DoD: execute cada comando DoD das tarefas independent / estágio 1 em source_worktree através de run_logged.sh (logs <slug>-dry-<n>.log), anote sua classe na especificação, corrija as BROKEN (detalhes); estágio 2+ na etapa 3.
• Crítico do plano: com 2+ tarefas, modo staged, uma tarefa de alto risco, ou sob solicitação: um crítico somente leitura (modelo lead apenas se uma tarefa for de alto risco, senão lead_phase2); decida sobre cada descoberta conforme plan-critic.md. Uma rodada.
• Mostre o relatório do checkpoint e aguarde aprovação antes da etapa 3, no formato de execution-plan.md §3. A aprovação deve cobrir explicitamente: no modo staged os commits e merges locais entre estágios; sempre o commit automático, push, PR e — conforme a coluna Merge — merge após APPROVE; com auto_cleanup a limpeza após cada merge; e, quando a linha do pool Docker diz prune: ask, worktree.sh pool --prune. Redação no §3.
• Fronteira de fase: após a aprovação, escreva <run dir>/state.json (§7) com phase: 2 e o session acordado, então:

  • split, diga ao usuário:

    Plano aprovado e salvo em <run dir>. Execute /clear, mude para o modelo Lead da fase 2 (/model <lead_phase2.model>, /effort <lead_phase2.effort>), então invoque esta skill com resume.

    (Codex / Antigravity: inicie uma nova sessão em lead_phase2.)

  • single: diga ao usuário que o plano está salvo em <run dir> e a execução continua aqui; vá para a etapa 3 sem trocar de modelos (resume ainda funciona).

Retomar (fase 2)

Em resume: entrypoints.md.

Limpeza (após o usuário mesclar)

Em cleanup: entrypoints.md.

As etapas 3–5 são executadas uma vez por estágio (independent = um único estágio), na ordem do plano. Mantenha state.json atualizado: atualize o status de uma tarefa na expedição, cada rodada de revisão, aprovação ou adiamento, e o estágio quando integrado.

3. Worktree + expedição

1. Antes de criar as worktrees do estágio: bash SKILL_DIR/scripts/worktree.sh pool. docker: false → pule; error → informe o usuário, pergunte primeiro. Senão, se free < o número de tarefas do estágio, execute worktree.sh pool --prune apenas se a aprovação cobrir (remove todas as redes Compose não utilizadas de todos os projetos; elas são recriadas), senão pergunte ao usuário.
2. Para cada tarefa: bash SKILL_DIR/scripts/worktree.sh create <slug> [--base <ref>] (estágio 1: omita --base; estágio 2+: --base sop-stage/<n-1>; worktree.sh path <slug> pré-visualiza). Verifique provisioned na saída; pare se uma entrada esperada estiver faltando. Estágio 2+: dry-run cada comando DoD da tarefa em sua nova worktree através de run_logged.sh antes da expedição (apenas correções de caminho/flag; senão pergunte).
3. Insira o caminho da worktree e a base em cada especificação, então despache todos os Trabalhadores do estágio em paralelo conforme dispatch.md, cada um no modelo de seu worker_tier (worker / worker_light; limite max_parallel).

4. Gate (por tarefa)

1. bash SKILL_DIR/scripts/check_scope.sh <worktree> <whitelist-file> deve sair com 0; em violações, o Trabalhador as reverte (conta como uma rodada de revisão).
2. Re-execute cada comando DoD você mesmo na worktree através de run_logged.sh (logs <slug>-gate-r<round>-<n>.log); todos devem sair com 0.

5. Revisão (por tarefa) + barreira de estágio

Siga review-checklist.md: o diff é revisado no modelo lead (split: subagente Revisor somente leitura, você verifica as descobertas dele; single: você) em relação à base registrada. Emita APPROVE ou REQUEST_CHANGES com descobertas numeradas file:line; faça um loop com o Trabalhador em no máximo 3 rodadas, depois escale para o usuário. As tarefas fazem loop independentemente. Uma tarefa light que falha na rodada 1 é re-expedida no modelo worker (models.md).

• independent: em APPROVE, commit, push, abra o PR com pr.sh e mescle-o quando as regras de auto-merge permitirem, sem perguntar (§4a).
• staged: quando cada tarefa no estágio for APROVADA, commite cada uma localmente, execute worktree.sh integrate <n> --base <stage base> sop/<slug>..., e passe pelo gate de integração (todas as DoDs do estágio na worktree do estágio) antes do próximo estágio; conflitos, falhas de integração e escalações: execution-plan.md. Com mais estágios pela frente, defina current_stage para o próximo em state.json e continue na mesma sessão. Ofereça uma nova sessão (/clear, depois resume) apenas quando o contexto tiver crescido muito (dois estágios foram executados, ou muitas rodadas de revisão); é seguro aqui.

6. Encerramento

1. Re-execute o comando de baseline da etapa 0; ele deve corresponder, senão relate exatamente o que mudou no checkout principal — não "conserte" você mesmo.
2. PRs: PRs independent já existem (§5); liste cada um como merged, open (motivo) ou local apenas. staged: abra o único PR a partir do último sop-stage/<n> com pr.sh (merge conforme auto_merge_risk, §6).
3. Limpeza das worktrees e branches dos PRs mesclados, worktree.sh sync, e — uma vez que toda tarefa seja limpa — worktree.sh rundir --archive. Sem perguntas apenas com auto_cleanup na aprovação, senão pergunte primeiro. Nunca --force.
4. Resumo final: descobertas abordadas, adiadas (e dependentes bloqueados), branches/PRs com estado, o que foi limpo e o que restou. Se PRs aguardam o usuário, termine com: após mesclá-los, invoque esta skill com cleanup.

Scripts e layout

Uso, códigos de saída, caminhos de worktree, provisionamento, substituições de configuração: scripts-and-layout.md.