amberpixels/ship

f10 · ship

Executar esta habilidade é a autorização explícita do usuário para fazer push e abrir ou atualizar o PR desta tarefa (a etapa pr), satisfazendo a regra global "nunca fazer push / abrir um PR a menos que solicitado" apenas para este PR, e para postar o +reply do resolve, enviar as correções do resolve para aquele PR, postar o f10 review ack da revisão, e para uma revisão de CI no fluxo o seu f10 review trigger (quando a seção de Revisão declarar como pode ler manualmente) e o f10 review settle do resolve, para uma entrada de juiz após pr, fazer push da integração do guarda de atualização e suas próprias alterações para aquele PR e postar seu status e comentário, e postar o comentário de retorno e status na tarefa (Report back). O deploy tem sua própria confirmação (a etapa deploy).

Argumentos

• --help: seguir ${CLAUDE_PLUGIN_ROOT}/modes/help.md e parar; nada abaixo se aplica.
• --dry-run: seguir ${CLAUDE_PLUGIN_ROOT}/modes/dry-run.md em vez de executar qualquer coisa, e parar. Ele informa quais etapas o restante do argumento executaria.
• --driven: seguir ${CLAUDE_PLUGIN_ROOT}/modes/driven.md; tudo abaixo ainda é executado.
• Um nome de fluxo como uma palavra (/f10:ship direct: fix typo …; f10 start --local envia /f10:ship local: <id>, --flow <name> envia <name>:), ou nomeado nas próprias palavras do usuário: executar esse fluxo. Caso contrário, o fluxo que o flow_by_area do frontmatter mapeia para a área da tarefa (as áreas do resumo da busca, senão a linha Areas do plano), senão default. Duas áreas mapeadas para fluxos diferentes: a área da entrega vence, como para Papéis, e o resumo nomeia a outra. O mapa de áreas é escolha do projeto, não sua: nunca auto-selecione outro fluxo, embora para trabalho pequeno você possa sugerir um. Nomeie o fluxo que uma área escolheu, e a área, em uma linha antes da primeira etapa.
• --pace <name>: executar o fluxo naquele ritmo apenas para esta execução (Ritmos, abaixo); sem ele, o ritmo que o branch registra, senão o pace: do projeto ou do usuário.
• <plan.md>: um arquivo de plano; executar o fluxo com ele.
• <task-id> (formato de id do projeto / id / url), ou um pacote unido por + (ABC-1+ABC-2, chaveado no líder): seguir ${CLAUDE_PLUGIN_ROOT}/modes/forward.md primeiro, antes de carregar qualquer coisa; parar se encaminhar a tarefa. Caso contrário, executar a etapa fetch, então procurar por <storage root>/plans/<TASK-ID>.md (o líder de um pacote) (fazer glob no diretório de planos se o nome exato não for encontrado). Encontrado: reutilizá-lo, nunca perguntando; uma tarefa com um arquivo de plano nunca planeja novamente, e replanejar é /f10:plan <id> manualmente. Ausente: sob stale_after, o fetch julga uma tarefa antiga primeiro e pode encerrar a execução bloqueada antes de qualquer plano ou entrada de fluxo (anyway na direção ignora isso); então executar a etapa plan quando o fluxo começa com plan (com flow_by_area, start e drive deixam o planejamento para o ship); um fluxo sem plano (abaixo) nunca o executa, e o resumo da busca se torna o plano inline. Então o fluxo.
• <description>: texto livre; as etapas capture, fetch e plan, então o fluxo.
• Sem argumento (flags ou uma palavra de fluxo sozinha contam como nenhum; uma descrição é texto livre, acima): uma tarefa já nesta conversa (um plano acabou de ser salvo, uma tarefa buscada), senão a tarefa do branch, o id que f10 task current imprime. Diga em uma linha qual tarefa você pegou e de onde, então execute-a como <task-id>, modo forward incluído, para que um plano salvo seja reutilizado. f10 task current saindo com não zero: peça por uma tarefa em uma linha e espere (driven: uma pergunta, conforme modes/driven.md).
• Texto extra além do assunto é direção. resume at <entry> (enviado por f10 drive uma vez que um catchup resolveu a parada) inicia o fluxo naquela entrada e conta as anteriores como concluídas; (entry <n>) escolhe a n-ésima entrada do pipeline do badge onde o fluxo a nomeia duas vezes. O badge caminha para aquele lugar: após pipeline, uma chamada executa set ship running em cada entrada antes dela, em ordem, então na própria entrada.

Execução

1. Executar f10-load-project.sh primeiro, a cada chamada desta habilidade, nomeando as etapas que a entrada necessita: capture fetch plan para uma descrição, fetch plan para um id de tarefa, nenhum para um arquivo de plano. O fluxo é declarado no project.md que ele imprime; um fluxo sem plano carrega plan mas nunca o executa.
2. Seguir essas etapas na ordem que o item Argumentos fornece.
3. Carregar cada entrada do fluxo logo antes de executá-la, em uma chamada com seu badge: f10-state.sh set ship running <entry>; f10-load-project.sh <step>, e seguir a etapa a partir desse carregamento. Uma entrada review carrega review resolve, e uma entrada pr carrega pr handoff a menos que seu dial handoff off esteja definido, porque a etapa pr executa o handoff; o guarda de atualização (abaixo) adiciona catchup ao carregamento de cada entrada que protege.

Fluxos são os flows: do frontmatter, um nome para suas entradas ordenadas, uma lista ou uma string dividida em espaços ou setas (plan judge implement cleanup:comments,prose pr review:ci deploy:staging); nenhum declarado é default: plan implement pr. f10 flow os lista e o que seleciona cada um.

Ritmos ajustam o fluxo escolhido (docs/project-setup.md → Ritmos). Uma vez que o fluxo é escolhido, executar f10 flow <name> [--pace <name>], passando --pace apenas quando o argumento forneceu um, e executar as entradas que ele imprime em sua ordem, nunca a lista do frontmatter. Ele imprime uma entrada por linha. Uma entrada marcada como skipped não é executada: diga isso em uma linha, e deixe-a de fora do pipeline do badge. Dials após uma entrada vão para sua etapa com a entrada: rounds e depth para review, marker e handoff para pr; o effort de um juiz se aplica apenas onde o juiz gera um agente (--blind), cujo perfil então vem de f10 agents judge, com --pace <name> quando o argumento forneceu um; um juiz inline executa no perfil do agente da tarefa. Um plan inicial que o ritmo pula torna a execução sem plano, como um fluxo sem plan é. Uma linha finish significa que a execução termina em um PR aberto que o ritpo teria mesclado: ship nunca o mescla, e o Next: do relatório nomeia /f10:finish <id> --merge, a menos que drive finalize a tarefa (modes/driven.md). Sem ritmo, a lista é o fluxo declarado, com uma revisão de CI opcional (ci?) já resolvida. Um f10 flow muito antigo para aceitar um nome falha nele: executar o fluxo declarado, e dizer em uma linha que o ritmo não foi aplicado.

Uma entrada é uma etapa, ou step:arg: uma etapa genérica mais sua sobreposição, ou uma definida pelo projeto, o argumento passado para ela (review:local ou review:ci define o by da revisão (quem revisa), review:host executa a revisão local na própria revisão de código do host, review:local+ci executa ambas em uma rodada e um resolve, review:local+ci? executa a revisão de CI apenas onde pode executar, e f10 flow <name> resolve o ? antes do ship ver a entrada, cleanup:<targets> os alvos de limpeza, que sempre recebem a passagem completa onde cleanup simples executa uma leve em um diff com menos de 200 linhas adicionadas, deploy:<env> o ambiente). A execução começa na entrada após um plan inicial, que é executado apenas para uma tarefa sem arquivo de plano. resolve nunca é nomeado: uma entrada review o executa. Uma entrada judge julga por posição: antes de implement o juiz do plano (assunto plan <id>), cujo veredito amarelo revisa o arquivo de plano no local e não escreve código; depois dele o juiz da mudança, que constrói as alterações de um veredito amarelo ele mesmo, roteado como a etapa judge diz antes e depois de pr. Uma entrada pr abre o PR do branch, ou o atualiza quando um está aberto, então um fluxo pode nomear pr novamente após revisão ou juiz para trazer a descrição atualizada. Um fluxo sem plan inicial é sem plano: não escreve arquivo de plano, e um breve plano inline no chat serve como substituto a menos que um salvo exista. As chaves antigas (pipelines, planless, drive_chain) ainda são lidas, convertidas para fluxos com um aviso que nomeia f10 init --migrate, e também a forma antiga de entrada review (local). Entrada de texto livre também pula capture e fetch, então a execução não tem id de tarefa. Um id de tarefa executa fetch e mantém a execução vinculada ao id (badge, relatório, branch, diretório de revisão), e marca f10-state.sh set plan skipped uma vez buscado, a menos que reutilize um plano salvo (prior, abaixo). Seu plano inline declara o tipo que o fetch resolveu, com a reprodução de um bug e causa raiz, o invariante de uma refatoração ou a pergunta de um spike em uma linha cada, e lista quaisquer lacunas em seus padrões. Com um id de tarefa, o plano inline também escreve a intenção da mudança como a etapa de plano faz (f10 lore add intent --change <change> -m <what and why>, docs/lore.md); uma intenção existente, ou uma adição falha, é uma linha no relatório, nunca uma etapa falha. A remessa é a última entrada de entrega (conventions/context.md → remessa): suas linhas são aquelas que essa etapa declara, as de uma etapa definida pelo projeto na linha Shipment: de sua sobreposição; um judge, demo ou handoff depois dela adiciona linhas, nunca as substitui. Uma entrada demo sem nada a mostrar é pulada em uma linha (a etapa demo), um fim normal que não adiciona linhas.

Um spike termina após implement, qualquer que seja o fluxo: um plano Kind: spike responde a uma pergunta, e seu código nunca sai da máquina. Nenhuma etapa após implement é executada (sem cleanup, commit, push, pr, review, judge ou deploy); a remessa é o relatório do spike. O relatório final termina com seu fechamento: f10 finish <id>, que arquiva o plano e o relatório, descarta o código de experimento e remove o worktree, branch e workspace; --keep mantém o experimento, commitado em um branch kept/. Um spike dirigido não precisa de fechamento no relatório: f10 drive o fecha após ship. No checkout principal, descartar o código de experimento pelos caminhos que o relatório nomeia antes de f10 finish, que recusa um checkout principal sujo. Seu retorno (abaixo) carrega a pergunta, a resposta e a recomendação; ele nomeia o caminho do relatório do spike apenas sob visibility: public, já que stealth mantém caminhos .f10/ fora do rastreador. O tipo é conhecido a partir do plano, ou do plano inline de uma execução sem plano, antes do fluxo começar, então o badge declara f10-state.sh pipeline implement, e uma execução seca imprime o caminho cortado em implement.

O guarda de atualização traz a base antes de três tipos de entrada, como a etapa catchup diz em Como um guarda; sob catchup: off ele nunca integra e seu carregamento deixa catchup de fora, mas a pergunta abaixo para uma base sem código ainda é executada. Catchup nunca é uma entrada de fluxo.

• Antes de implement, apenas onde f10 start --after ou f10 finish registrou uma base no branch (f10-after-branch ou f10-landed); f10 pr catchup --guard implement imprime method: skip caso contrário. Uma base sem código ainda é a linha code: none do guarda, a regra que f10 drive libera dependentes, para uma base mantida localmente ou apenas no origin. Antes de integrar, perguntar uma vez (AskUserQuestion) wait, ou proceed on the plan's assumption. Wait encerra a execução bloqueada (f10-state.sh set ship blocked implement, um note nomeando a tarefa base). Proceed constrói contra o plano da tarefa base como o arquivo de plano registra, sem fallback se estiver ausente. Driven, nada é perguntado e ship nunca prossegue: f10-state.sh set ship blocked implement; f10-state.sh wait <base-id>; f10-state.sh note "waiting on <base-id>: its branch has no code yet" "rerun ship once <base-id> commits; f10 drive does it by itself", então o relatório. f10 drive mantém a tarefa como waiting on <base-id> e envia ship novamente, resume at implement, uma vez que a base commita; outras tarefas continuam.
• Antes de toda entrada pr, a primeira e cada atualização: f10 pr catchup --guard pr primeiro, que busca e verifica ancestralidade; apenas quando seu method é merge, rebase ou onto, commitar o que a árvore contém como a etapa pr faria (conventions/context.md → Commits, --step implement) e integrar, para que o push o carregue. skip ou none deixa o commit para pr e seu adaptador.
• Antes de um juiz da mudança (um judge após implement; o juiz do plano não tem código): com trabalho não comitado na árvore (implement deixa seu trabalho não comitado, então implement judge pr sempre tem algum), pular em uma linha: esse juiz vê o branch em sua base antiga, e o guarda de uma entrada pr posterior, quando o fluxo tem um, traz a base antes do código sair. Após uma entrada pr, fazer push da integração, nunca forçando, para que a HEAD do PR seja o código julgado e o status do juiz caia nele.

O guarda executa sob a entrada que protege, no carregamento dessa entrada (catchup pr) e badge. Uma falha é set ship failed <entry>, ou partial uma vez que a execução deixou algo durável, o próprio commit do guarda ou um PR aberto (conventions/failure.md rule 7), sua linha state nomeando esse commit e seu note nomeando catchup e /f10:catchup. O guarda marca o branch antes de falhar (a etapa catchup), e f10 drive pega um branch marcado por si só, novamente cada vez que a base se move, então solicita ship novamente nesta entrada; ele para, nomeando os arquivos, quando um catchup não mudou nada, a base não se moveu, ou os mesmos arquivos conflitam duas vezes seguidas. O next de uma execução dirigida é run /f10:catchup --driven in the worktree, then rerun the drive: a reexecução solicita ship novamente nesta entrada.

Executar as entradas do fluxo na ordem declarada, cada uma a partir de seu próprio carregamento. Um plano escrito nesta execução não precisa de reconfirmação. Uma entrada judge roteia a execução por seu veredito: o juiz do plano como a rota antes de pr da etapa judge diz, suas alterações incorporadas no arquivo de plano para implement construir; o juiz da mudança de forma diferente antes e depois de uma entrada pr (a etapa judge). As alterações de um juiz da mudança, antes ou depois de pr, são incorporadas no plano e construídas pela própria rota da etapa judge (Building the changes), nunca por uma reexecução de implement.

Badge (conventions/report.md): f10-state.sh pipeline <entry>... uma vez que o fluxo é selecionado, toda entrada após plan como o fluxo a nomeia, um argumento cada (pipeline judge implement cleanup pr review:local judge pr), que também declara a última como final; f10-state.sh set ship running <entry> antes de cada entrada, nomeada como o fluxo a nomeia, na chamada que a carrega; f10-state.sh set ship done após a última. Um plano de uma execução anterior (arquivo de plano, ou reutilizado) é refletido no pipeline: plan aparece como o primeiro argumento do pipeline, e f10-state.sh set plan done imediatamente antes de pipeline. Todas as entradas do fluxo que são puladas (pelo ritmo, por uma base de spike, por um juiz da mudança com árvore suja, por um guarda de implement com código ausente) são deixadas de fora do pipeline e reportadas como uma linha; a última entrada que não foi pulada se torna a final. O badge também marcar o estado da tarefa:

• f10-state.sh set task running uma vez que a tarefa é confirmada (fetch para um id, o único da conversa para um sem id).
• f10-state.sh set task done após o relatório final.

Relatório final (conventions/context.md → Relatórios) no final de cada execução, seu formato e remessa. Seu bloco de código ### Next é

• run /f10:ship deploy:<env> (ou deploy para o padrão) quando o fluxo terminou sem deploy e nenhuma validação está pendente.
• Nomeando validações pendentes quando o fluxo terminou sem imprimir o Next, uma linha por validação (lint, typecheck, etc.), cada uma prefixada com run /f10:ship .
• O /f10:finish para um spike, ou para uma execução que terminou em finish.
• run /f10:drive para um fechamento dirigido quando o relatório final não terminou a tarefa. O parágrafo do relatório termina com ***um resumo em uma frase do que a execução fez***.

A execução termina com um código de saída 0, não importa o que as etapas fizeram; a falha é capturada no estado do badge e no relatório. Tudo o que não está acima permanece conforme as convenções do f10.