jumibot/flujo_tareas

Fluxo de tarefas

A regra de cada mudança de estado está em references/estados.md: um cartão por mudança, com quando, quem, que autorização pede, o que faz no repositório e sua ordem. Este arquivo diz como usá-la.

Como a fila é alterada

Toda escrita na fila passa pelo CLI, nunca manualmente:

python -I -X utf8 "$HOME/.claude/sf/cola.py" [--raiz CAMINHO] [--quem proprietario|principal] [--via cli|painel] [--json] <ordem> …

• Sempre esse comando, igual em bash, zsh e PowerShell, em qualquer projeto; também os subagentes. Se o mod disser ao iniciar a sessão que nesta máquina o Python é lançado com outro nome (no macOS, python3), use esse em vez de python, aqui e em todo comando Python da SF («O comando Python é o interpretador detectado», 236); a tarefa cola.py encargo também informa. Nunca o tools/cola.py de uma pasta (na SF, plugins/sf/tools/cola.py muda com o ramo ativo): o que vale é o do plugin carregado. Ao carregar, o painel copia seu cola.py para ~/.claude/sf/cola-<sessao>.py e o executa («O painel executa uma cópia do cola.py feita ao carregar», 136); ~/.claude/sf/cola.py é um lançador que passa a ordem para essa cópia, via CLAUDE_CODE_SESSION_ID: Claude e o painel usam o mesmo (tarefa 252). Sem a cópia, sai com 2 e avisa: /reload-plugins a refaz.
• --raiz: a pasta do projeto, por padrão a atual. Para testar, o caminho de uma cópia da fila.
• --quem: principal por padrão; proprietario quando a mudança é uma decisão dele (seu OK para fechar).
• Sai com 0 se fizer a mudança, 1 se não fizer (diz por que e não mexe em nada) e 2 se a ordem estiver mal escrita; choques, que só consulta, com 3 se houver choques. cola.py <ordem> -h mostra o uso de cada uma.

O que o CLI faz em cada escrita: bloqueia a fila (.sf/peticoes.lock), salva antes uma cópia em .sf/copias/ (as últimas 50), anota a mudança no histórico da tarefa e, se a tarefa sair da fila, a move com seu histórico para .sf/histórico.jsonl. Os números não são reutilizados.

Regras que o CLI não aplica

O CLI aplica as condições de cada mudança (estado de partida, ramo, passos, git). Quando e como usá-lo na conversa (o menu ao anotar, colocar em andamento, lançar e recolher subagentes, propor testar e fechar, sugerir fusões e redescrições, as tarefas de documentos, o que fazer livre) está na skill sf:orquestracao. Aqui fica o que diz respeito à fila em si:

• Apenas o principal escreve na fila. Um subagente não executa ordens que escrevem; ele informa no seu relatório e o principal as executa.
• Toda solicitação é feita sob uma tarefa em andamento; sem ela, não se começa a trabalhar. Reorganizar a fila (fundir, separar, redescrever, adicionar passos, alterar tipos) não precisa dela («Orquestração com um subagente vivo por tarefa», 149).
• O OK do proprietário: fechar, para-observacao, reobservar e descartar o esperam; para-fila de uma em andamento também, só sem trabalho: com commits próprios em seu ramo (ou no auxiliar de seu subagente) não volta para a fila; fecha-se, passa-se para observação ou descarta-se («Uma tarefa em andamento com ramo não volta para a fila», 170). Com o ramo vazio ou já removido, para-fila o apaga e recolhe o subagente vazio (275).
• Tipo ao criar (criar --tipo): deliberar, documentar, projetar, implementar, especificar, corrigir ou investigar; se mudar, tipo N T.
• Choques antes de em-andamento: choques N, com --arquivos e os previstos, deduzidos da descrição, se ainda não tiver ramo. Não ao lançar subagentes de tarefas já em andamento («Prever choques ao colocar uma tarefa em andamento», 130).
• Ramo antes do primeiro ativo (ramo), avisando. Para um subagente, o principal o cria sem ativar e o anota antes de lançá-lo (ramo --sem-ativar, subagente); o subagente trabalha em um ramo auxiliar a partir dele e o principal o traz com git merge --ff-only. O subagente nunca ativa o ramo da tarefa em seu worktree: assim a T e a C funcionam com o worktree configurado («Orquestração com um subagente vivo por tarefa», 149).
• Recolhimento do subagente: o CLI o faz, com os worktrees e ramos anotados com subagente (--worktree aceita caminho relativo ao projeto), em toda ordem que deixa a tarefa sem ele: fechar, para-observacao, descartar, excluir, para-proposta, reverter, limpar, reabrir e, nas absorvidas, fundir (só se seu auxiliar já está no ramo que fica; o que permanece conserva o seu). Sem forçar: um worktree com mudanças não commitadas, um auxiliar com commits que não entraram no develop ou um não integrado ao fundir permanecem, e avisa-se. descartar e limpar, em contrapartida, removem tudo, também o auxiliar com commits que não entraram e o worktree com mudanças não commitadas: o descarte descarta tudo (189). fechar e para-observacao recusam-se antes se um auxiliar tiver commits não trazidos para o ramo da tarefa, e dizem como trazê-los. reabrir, ao contrário, limpa tudo, também com mudanças não commitadas e sem avisar: um worktree antigo nunca é reutilizado. Histórico: recolhido ou recolhido-com-avisos. O principal apenas interrompe o subagente e atende os avisos («cola.py recolhe o subagente ao deixar a tarefa sem ele», 169).
• A assinatura dos commits («A assinatura do commit de fechamento é configurável; sem configurar, sem linha», 238): o squash de fechar e para-observacao, o commit de decisao e o da versão RELEASE levam a linha de coautor de .sf/projeto.json (na própria SF, que não tem esse arquivo, a sua: Co-Authored-By: Claude Opus 5.5 <[email protected]>). fechar, para-observacao, decisao e tarefa aceitam --coautor "…", que sobrescreve a configurada. Sem nenhuma, os commits vão sem linha de coautoria, e a tarefa informa assim ao subagente.
• Decisões do proprietário: decisao "Título" --arquivo CAMINHO|--texto T [--numero NNN] [--coautor "Co-Authored-By: …"] [--push] não mexe na fila. Dá o próximo número de docs/decisoes/ no develop e o nome NNN-AAAA-MM-DD-titulo.md (com --numero, reescreve essa sem mudar o nome); escreve o arquivo (o texto, com # Título na frente se não o tiver; se o tiver, deve coincidir), refaz o README.md e faz o commit «Decisão NNN: Título» no develop, também com outro ramo ativo, sem alterá-lo nem mexer em sua cópia de trabalho, como para-proposta (tarefa 273). Não o faz se develop estiver em outro worktree ou, sendo o ativo, docs/decisoes/ tiver mudanças não commitadas. Com develop ativo, refaz também README.html. --push sobe develop; informa o número e o hash. Sem git ou sem develop, apenas escreve os arquivos e avisa (tarefa 283).
• Fundir e separar são escritas pelo proprietário (/sf_fundir, /sf_split no painel); o principal, com fundir, apenas duas tarefas de atualizar o mesmo documento («Uma tarefa por documento a atualizar», 142).

Ordens por momento

Momento	Ordens
Criação e início	criar, choques, em-andamento, para-fila, ramo
Durante o trabalho	passo adicionar, passo marcar, passo remover, renomear, tipo, subagente, relatorio
Teste	pronto, verificado, testar
Fechamento	fechar, para-observacao
Em observação	observando, continuar, fechar, reobservar e, se der errado, reverter
Desfazer	descartar, limpar, reverter, reabrir, excluir, restaurar, para-proposta
Juntar e separar	fundir, dividir
Consulta e cópias	listar, ver, copias, recuperar
Fora da fila	decisao

Todo fechamento (fechar, para-observacao), com ramo ou sem ele, também uma proposta, exige o passo «Fechar a tarefa» e nenhum outro pendente exceto «Ativar ramo para poder testar». Os dois passos de fechamento são colocados pelo cola.py ao entrar a tarefa em andamento (criar --em-andamento, em-andamento, reabrir, testar desde a fila, restaurar, fundir), uma vez e no final, e não são removidos nem alterados no texto; uma tarefa em andamento que não os tiver os recebe ao carregar a fila. Um passo de trabalho novo deixa novamente pendente «Ativar ramo para poder testar», se estava feito: é preciso testar novamente. As ajudas de teste (passo adicionar N "texto" --teste) vão entre os dois passos de fechamento; nenhum fechamento as exige, deixando-as como estão, e adicioná-las não retorna «Ativar ramo» a pendente («Ajudas de teste: após ativar o ramo e não obrigatórias para fechar», 184). pronto apenas guarda o que testar («Os passos de fechamento, desde que a tarefa entra em andamento», 174). testar integra develop no ramo (merge; com choques, desfaz e não ativa; com commits da sub-NN não trazidos, nem integra nem ativa), ativa-o, ou o deixa se já estiver, e marca feito «Ativar ramo para poder testar», e fechar também: o OK do proprietário é fechar (172, 121). Os passos são numerados a partir de 1, como o n de cada um em ver. O que sai da fila leva em .sf/histórico.jsonl o estado com que saiu (fechada, excluída, absorvida, descartada e, de antes de reverter excluir ou deixar pendente (134), revertida), e ver o mostra.

Reverter pede o destino: reverter N --excluir tira da fila sem rastro, como a E; reverter N --pendente devolve a Pendentes, na fila e reaberta, sem ramo. Nunca fica em Fechadas com R («Reverter exclui a tarefa ou a deixa pendente», 134). Se o proprietário não disser, perguntar qual.

Quando uma ordem falha por git (choques no squash ou no revert, mudanças não commitadas, o ramo em outro worktree), o CLI desfaz e informa o que acontece; o principal resolve e repete a ordem. Um push falho não impede o fechamento: fica no histórico (push-falho) e repete-se o push manualmente.