pi-dsr-workflow

Pacote para o Pi que conduz um trabalho de desenvolvimento por etapas verificáveis: um comando /work, três tools pequenas, estado persistente fora da conversa e evidências ligadas ao conteúdo verificado.

As especificações normativas estão em pi-workflow-specs/.

Instalação

pi install npm:pi-dsr-workflow           # do npm
pi -e /caminho/para/pi-dsr-workflow      # uma execução a partir do código
pi install /caminho/para/pi-dsr-workflow # instalação local a partir do código

Compatibilidade

A versão 0.3 foi validada com o Pi 1.3.0 e 1.4.0; outra versão carrega, e o /work doctor a informa como não validada. Requer Node 22.19.0 ou mais recente e um repositório Git; a execução paralela exige o Git 2.40 ou mais recente. Medido no Linux x64; macOS e WSL não foram testados, e no Windows nativo o plugin fica desligado (/work doctor mostra a causa). A publicação de issues e o /work pr só falam com o github.com, pelo gh autenticado. As jornadas reais usaram quantforge-openai/deepseek-v4.1-flash, que precisa de compat.requiresReasoningContentOnAssistantMessages no models.json para não recusar o turno seguinte com HTTP 400. Extensões que forçam turnos, reativam tools ou gravam estado no repositório conflitam com o fluxo, e o /work doctor aponta as conhecidas. No código-fonte, docs/matriz-de-compatibilidade.md traz os detalhes e a evidência de cada item.

Skills para uso manual

O fluxo injeta a skill de cada etapa, e nenhuma delas entra na lista de skills do modelo. Para usá-las por conta própria, inicie o Pi com --work-manual-skills: o plugin publica cópias sem alteração das skills do upstream em <agentDir>/pi-dsr-workflow/manual-skills/, com a licença MIT do upstream ao lado. As que o upstream deixa visíveis entram na lista do modelo, e todas ficam acessíveis por /skill:nome; nesse perfil o /work fica desligado na sessão. Um nome que já exista em outra fonte, como ~/.agents/skills/codebase-design, continua com a skill existente; /work doctor lista esses nomes.

Execução delegada

A execução paralela vem desligada. /work parallel on a liga no repositório, /work parallel off a desliga e /work parallel 1 a 4 a liga com esse limite de executores; sem argumento, o comando mostra o estado e de onde ele vem. A escolha fica em <agentDir>/pi-dsr-workflow/<repositório>/settings.json; o arquivo <agentDir>/pi-dsr-workflow/settings.json, editado à mão, vale para todos os repositórios, no mesmo formato ({ "parallel": true, "maxExecutors": 3 }). A flag --work-parallel liga a execução paralela só naquela sessão. Vale a flag, depois o arquivo do repositório, depois o global; o limite vem dos arquivos, até 3 por padrão, de 1 a 4. Uma mudança no meio do trabalho vale a partir do próximo passo do controlador, e um arquivo inválido é ignorado com um aviso. Com a execução paralela ligada, depois do aceite do plano o controlador entrega cada ticket sem dependência pendente a um executor próprio, em vez de implementar um ticket por vez na conversa. Cada executor roda numa sessão isolada do Pi, com o modelo da sessão, sem shell e sem extensões: só lê e edita arquivos do seu worktree (<agentDir>/pi-dsr-workflow/<repositório>/worktrees/<trabalho>/<ticket>, no branch <branch do trabalho>--<ticket>), roda os checks do ticket e reporta o resultado. Do workspace principal, o worktree recebe apenas o node_modules; um projeto cujos checks dependam de outros diretórios fora do Git deve seguir com a execução paralela desligada. Os checks e as revisões do ticket rodam sobre o worktree. Aceito, o ticket entra no workspace principal por merge de 3 vias (git merge-tree, que exige Git 2.40 ou mais novo): o merge é montado contra um retrato do workspace, os checks dos tickets já integrados e os do ticket rodam sobre ele num worktree à parte (worktrees/<trabalho>/_integration), e só então o resultado é escrito, sem tocar no índice do usuário. Um conflito ou um check que falhe depois do merge rejeita a tentativa: nada é escrito, o merge fica em refs/pi-dsr-workflow/<trabalho>/merges/<ticket>, o worktree e o branch ficam preservados, e o ticket recomeça do estado integrado num worktree novo (<ticket>-2, <ticket>-3), com o diff da tentativa anterior no pacote do executor (inteiro, ou o caminho do arquivo que o guarda quando não cabe no pacote, que o executor pode ler); depois de 3 rejeições o trabalho bloqueia. No diálogo do plano, um aviso aponta tickets independentes que rodam o mesmo check, porque o worktree de cada um só vê o seu lado. Nenhum limite de tokens ou de tempo interrompe um executor; /work status mostra os tokens que executores e revisões já gastaram. Um executor que termina sem integrar o ticket, sem reportar ou com erro, devolve o ticket a pendente e bloqueia o trabalho, e /work next delega de novo no mesmo worktree. /work pause e /work cancel param os executores, e nada no worktree é apagado. Terminados os tickets, a verificação e a revisão finais seguem em segundo plano, e o plugin avisa quando a entrega espera /work next. Na entrega, os worktrees com exatamente o conteúdo integrado são removidos sem --force, junto com seus branches; os demais ficam, e /work doctor gc lista e remove, com confirmação, os de trabalhos encerrados cujo conteúdo uma ref do plugin guarda.

Publicação no GitHub

No caminho completo, /work publish publica a spec aprovada e os tickets do plano como issues do repositório origin no github.com, pelo gh autenticado; o token nunca passa pelo plugin. O primeiro uso pede para ativar a publicação no repositório e guarda a escolha em <agentDir>/pi-dsr-workflow/<repositório>/github.json (enabled_at); apague o campo para desativar. Cada envio mostra antes o lote de issues novas e de atualizações e espera a confirmação. As issues levam a label pi-dsr-workflow e uma chave no corpo; os tickets viram sub-issues da spec, e as dependências do plano viram dependências nativas quando o repositório as aceita. Depois disso, o plugin fecha sem perguntar a issue de cada ticket integrado, a da spec na entrega, e todas como não planejadas num /work cancel. Um envio de resultado incerto é reconciliado pela chave antes de qualquer nova tentativa. Uma issue editada no GitHub depois da publicação bloqueia o trabalho sem ser sobrescrita: /work publish substitui o texto remoto, ou /work change ajusta o plano. Publicar nunca faz push nem abre PR. O /work doctor mostra o repositório configurado e o que falta enviar de cada trabalho.

Depois da entrega local, /work pr [id] envia o commit entregue a um branch próprio em origin (pi-dsr/<trabalho>) e abre um PR em rascunho para o branch em que o trabalho começou. O push usa as credenciais do seu Git, e o PR o gh autenticado. O consentimento é separado do das issues: o primeiro /work pr pede para ativar push e PRs no repositório e grava push_enabled_at no mesmo github.json (apague o campo para desativar); ter ativado as issues nunca autoriza um push. Cada envio mostra antes o push, os commits, head → base e o título, e espera a confirmação; quando pushurl ou pushInsteadOf do seu Git levam o push para fora do repositório consentido, o diálogo mostra a URL, e um envio pendente aprovado para outro repositório ou outra URL de push é descartado e volta ao diálogo. O push nunca é forçado: se o branch remoto divergiu da entrega, nada é sobrescrito e você escolhe entre um branch novo (pi-dsr/<trabalho>-2) e resolver à mão. Um branch base ausente em origin não é enviado pelo plugin; publique-o antes. O corpo do PR traz o objetivo, os critérios, a garantia, o commit entregue e Refs às issues publicadas do trabalho. Um push ou uma abertura de resultado incerto é conferido em origin e procurado pelo branch e pela chave antes de qualquer nova tentativa, e um PR editado no GitHub só é substituído se você escolher. Sem id, vale o trabalho vinculado à sessão ou, se não houver, o único entregue (ou o que você escolher); um trabalho já encerrado também pode ser enviado. O plugin nunca faz merge, nunca fecha o PR e não acompanha CI nem revisões; /work status mostra o número e o estado do PR, e o /work doctor os envios pendentes.