delegate-skills

delegate-chore

Destino de fallback para tarefas secundárias. task_type=chore, modelo padrão haiku (mais barato). A ramificação de execução (Codex / Devin / Cursor / Claude) é feita pelo dispatch.sh.

Caminhos dos scripts

• Claude Code: skill_dir=.claude/skills/delegate-chore
• Codex: skill_dir=.agents/skills/delegate-chore

Os exemplos de comando a seguir usam .claude/skills/delegate-chore. Para usar no Codex, substitua pela estrutura relativa equivalente .agents/skills/delegate-chore.

Referência de preços do modelo

Somente se for necessária análise de custos ou comparação de tarifas, leia <skill_dir>/model-token-prices.json. Estes dados são apenas para referência e não são usados para decidir se a delegação deve ser iniciada.

Antes de delegar (portão de custo)

A delegação envolve overhead (inicialização do worker, ida e volta de request/response, leitura pelo agente principal). Se esta tarefa puder ser transformada em um único comando de script (como sed / find / chmod etc.) e o conteúdo alvo não precisar ser carregado no contexto do modelo, a delegação provavelmente será pura perda (o overhead supera os ganhos tanto em higiene de contexto quanto em tokens). Nesse caso, não delegue; execute diretamente no agente principal ou, se for repetitivo, encaminhe para a proposta de automação do ciclo de feedback. A delegação vale a pena para tarefas pesadas que exigem que o modelo leia e processe conteúdo. Justificativa em docs/design/delegate-chore.md §5.

Fluxo de execução (one-shot)

1. Criação da requisição: Passe um Markdown com Objective / Scope / Context / Acceptance criteria / Verification / Constraints via stdin. Escreva a requisição de forma concisa: não cole o conteúdo do arquivo no Context; faça referência ao caminho (e intervalo de linhas, se necessário) para não aumentar os tokens de saída do agente principal.
   • Se o usuário especificar modelo ou esforço na conversa, prefixe a chamada run com variáveis de ambiente inline (ex: DELEGATE_CHORE_MODEL=gpt-5.5@high bash .../run.sh ...). Se houver exit 6, use a linha do stderr que contém a enumeração de valores permitidos como explicação direta ao usuário.
2. Execução: out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-chore/scripts/run.sh chore DELEGATE_CHORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID")" (se for uma inicialização de nível superior, $PARENT_TASK_TYPE_CHAIN pode ficar vazio).
   • O run executa internamente prepare → dispatch → read-response em sequência. O stdout retorna um único JSON (contendo exit_code / status / content / content_truncated / response_file / observe_file / run_dir) tanto em caso de sucesso quanto de falha.
   • O valor padrão para o seletor, quando omitido, é auto. O 6º argumento posicional é o seletor do read-response, que tem significado diferente do 6º argumento posicional do prepare.sh (session_mode).
   • O código de saída é transparente para os scripts internos. Exit 3 = pré-requisitos insuficientes / Exit 4 = ciclo de delegação, então abortar.
   • O run emite observe_file: <path> no stderr antes do dispatch. Em caso de encerramento forçado, use esse caminho como rota de recuperação.
   • Em modo não interativo (como claude -p), execute o run sempre em foreground e defina um timeout Bash maior que o tempo estimado da delegação (para Claude Code, BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS ou o argumento timeout da ferramenta Bash).
3. Consumo da resposta: Leia status="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .status)" / content="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .content)". Se content_truncated for true, extraia response_file="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .response_file)" e use bash .claude/skills/delegate-chore/scripts/read-response.sh "$response_file" <N> para leitura incremental das seções necessárias. Após a leitura, não resuma nem faça echo do conteúdo do worker. A resposta do agente principal ao usuário deve ser uma única linha apontando para o Summary (para não aumentar os tokens de saída do agente principal, conforme spec.md §6).

Fluxo avançado (scripts individuais)

Para fluxos que exigem intervenção do agente principal durante o andamento (como monitoramento do observe durante o dispatch, execução em background, resumable / follow-up), use os scripts individuais tradicionais.

1. Preparação (agregada): Unifique verificação de pré-requisitos → resolução do modelo → verificação da cadeia → geração da requisição em um único prepare.sh (reduzindo viagens de ida e volta do bash e a saída para o contexto principal). Passe um Markdown com Objective / Scope / Context / Acceptance criteria / Verification / Constraints via stdin. Escreva a requisição de forma concisa: não cole o conteúdo do arquivo no Context; faça referência ao caminho (e intervalo de linhas, se necessário) para não aumentar os tokens de saída do agente principal. Exit 3 = pré-requisitos insuficientes / Exit 4 = ciclo de delegação, então abortar.
   • Se o usuário especificar modelo ou esforço na conversa, prefixe a chamada prepare com variáveis de ambiente inline (ex: DELEGATE_CHORE_MODEL=gpt-5.5@high bash .../prepare.sh ...). Se houver exit 6, use a linha do stderr que contém a enumeração de valores permitidos como explicação direta ao usuário.
   • out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-chore/scripts/prepare.sh chore DELEGATE_CHORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID")" (se for uma inicialização de nível superior, $PARENT_TASK_TYPE_CHAIN pode ficar vazio)
   • Leia model="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .model)" / request_file="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .request_file)" / response_file="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .response_file)" / run_dir="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .run_dir)" / observe_file="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .observe_file)"
2. Execução: bash .claude/skills/delegate-chore/scripts/dispatch.sh "$model" chore "$request_file" "$response_file" "$run_dir" "$observe_file". A ramificação de execução (Codex / Devin / Cursor / Claude) com base no prefixo do nome do modelo é feita pelo dispatch.sh. O stdout retorna apenas o caminho do response_file. Em modo não interativo (como claude -p), execute o dispatch sempre em foreground e defina um timeout Bash maior que o tempo estimado da delegação (para Claude Code, BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS ou o argumento timeout da ferramenta Bash). Para monitoramento normal durante a execução, leia apenas state.phase / state.started_at / heartbeat.ts / heartbeat.stdout_bytes / heartbeat.stderr_bytes / heartbeat.last_stream_change_at do observe_file usando read-json.sh. state.phase pode ser: prepared | running | superseded | stalled | ended. Os estados prepared / superseded indicam observe que não foram despachados (state.started_at == null, usage não definido, equivalente a null no read-json.sh), portanto, exclua-os do denominador ao agregar usage.
3. Leitura da resposta: bash .claude/skills/delegate-chore/scripts/read-response.sh "$response_file" auto. auto significa: se a resposta for pequena (menos de 10KB, padrão), lê status e todas as seções de uma vez; se for grande, retorna status + índice + seção Summary, permitindo buscar seções adicionais com ... "$response_file" <N>. Após a leitura, não resuma nem faça echo do conteúdo do worker. A resposta do agente principal ao usuário deve ser uma única linha apontando para o Summary (para não aumentar os tokens de saída do agente principal, conforme spec.md §6).

Reutilização de sessão (resumable / follow-up)

Os modos resumable / follow-up não são cobertos pelo fluxo one-shot, portanto, use scripts individuais.

O padrão é uma execução normal. Apenas quando houver alta probabilidade de revisão pelo agente principal (como em grandes alterações transversais), especifique o modo resumable initial run desde o início. Evite uso excessivo.

• Resumable initial run: Passe resumable como 6º argumento do prepare.sh. O dispatch passa resumable como 7º argumento e strings vazias como 8º e 9º argumentos.
  • out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-chore/scripts/prepare.sh chore DELEGATE_CHORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID" resumable)"
  • session_mode="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .session_mode)" / lineage_id="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .lineage_id)"
  • bash .claude/skills/delegate-chore/scripts/dispatch.sh "$model" chore "$request_file" "$response_file" "$run_dir" "$observe_file" "$session_mode" "" ""
  • Após ler a resposta, verifique bash .claude/skills/delegate-chore/scripts/read-json.sh .backend_session.persistence "$observe_file". Se não for resumable, considere que follow-up não é possível e tome a decisão no momento; não espere fallback implícito posterior.
• Follow-up run: Use apenas quando o agente principal encontrar problemas ao verificar as diferenças. Passe followup=<observe_file_anterior> como 6º argumento do prepare.sh. Exit 5 significa falha de validação, então aborte e refaça como uma delegação normal. Não faça fallback implícito.
  • out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-chore/scripts/prepare.sh chore DELEGATE_CHORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID" "followup=$previous_observe_file")"
  • session_mode="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .session_mode)" / resume_id="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .resume_id)" / backend_session_home="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .backend_session_home)"
  • bash .claude/skills/delegate-chore/scripts/dispatch.sh "$model" chore "$request_file" "$response_file" "$run_dir" "$observe_file" "$session_mode" "$resume_id" "$backend_session_home"
  • A requisição de follow-up deve incluir obrigatoriamente: o problema encontrado pelo agente principal, o escopo relevante do git diff mais recente e uma referência ao response_file anterior. Não dependa apenas do contexto antigo da conversa do worker.

Proposta de promoção de skill (ciclo de feedback)

As tarefas que chegam ao delegate-chore são um sinal de que não existe uma skill dedicada para aquele trabalho. Após consumir a resposta, se o trabalho:

• Aparece repetidamente / é uma categoria claramente delimitada e reutilizável

Então, proponha ao usuário, via AskUserQuestion, a criação de uma nova skill dedicada delegate-<nome> (incluindo nome sugerido / modelo padrão / permissões de ferramentas / tipo de inicialização). Após acordo, use o skill-creator para criar o esqueleto seguindo este protocolo. Não faça a proposta para chores únicos e insignificantes.

Proposta de automação de processos determinísticos

Com o mesmo espírito da promoção de skill, se você perceber que uma mesma sequência de comandos de múltiplas etapas, procedimentos de verificação ou edições padronizadas aparecem repetidamente e sem necessidade de julgamento do LLM (ramificações fixas), proponha via AskUserQuestion a automação adequada: script / git hook / npm script / CI, etc. (incluindo o procedimento alvo / destino da automação / gatilho sugerido). Não proponha para procedimentos únicos ou que envolvam tomada de decisão.

Ocultação do tempo de espera (para agentes interativos)

Em agentes interativos, é possível ocultar o tempo de espera executando o dispatch.sh (ou run.sh) em background, verificando state.phase / heartbeat no observe_file e chamando read-response.sh somente após o estado ended. A melhoria é perceptual; o tempo total (wall time) não muda. Em agentes não interativos, a execução em foreground é obrigatória.

Restrições

• Edição é permitida. Mas não faça push (push/PR devem ser tratados diretamente pelo agente principal).
• Não re-delegue para um tipo já presente em task_type_chain (é permitido delegar para outro tipo de delegate).
• O agente principal não deve fazer echo ou re-sumário da saída do worker. A resposta ao usuário deve ser uma única linha apontando para o Summary (para não aumentar os tokens de saída, conforme spec.md §6).