msd-core/docs/pt-BR/issue-driven-orchestration.md

Orquestração Orientada a Issues com o MSD

Status: guia de fluxo de trabalho estável Público: desenvolvedores que rastreiam trabalho no GitHub Issues, Linear, Jira ou sistemas similares de rastreamento de issues e querem conduzir a implementação assistida por IA através dos primitivos existentes do MSD.

O que é este guia

Uma receita para combinar comandos que o MSD já inclui em um loop rastreador de issues → workspace → planejar/executar → verificar/revisar → PR. É documentação somente. Sem novos comandos, sem daemon, sem integração com rastreador — cada comando referenciado abaixo já existe no MSD hoje.

O formato é inspirado pela referência de orquestração open-source Symphony da OpenAI (repositório). O MSD não vende nem encapsula o Symphony. Os conceitos de orquestração se mapeiam claramente nos primitivos que o MSD já expõe; este guia apenas descreve esse mapeamento para que você possa adotar o padrão sem escrever código de integração ou contornar os controles de segurança do MSD.

Por que isso existe

O MSD tem os blocos de construção para desenvolvimento de IA orientado a issues — /msd-workspace --new, /msd-manager, /msd-autonomous, /msd-verify-work, /msd-review, /msd-ship, além de STATE.md e o conjunto de artefatos de fase — mas não havia um guia que mostrasse como conduzir tudo isso a partir de uma única issue do rastreador sem escrever scripts de orquestração personalizados. Sem esse guia, os modos de falha são:

• Subutilização: desenvolvedores executam discuss/plan/execute manualmente e nunca recorrem a /msd-manager ou /msd-autonomous, mesmo quando seu padrão de trabalho se encaixa.
• Scripts alternativos: desenvolvedores criam loops de shell ad-hoc entre seu rastreador e invocações de claude, contornando STATE.md, o manifesto de fases e os controles de verificação.

Este guia torna o loop canônico descobrível.

Mapeamento de conceitos

Cada linha mapeia um conceito de orquestração no estilo Symphony para o primitivo do MSD que já o serve. Use esta tabela como chave de tradução ao ler documentações do Symphony, posts de blog ou descrições de orquestração de terceiros.

Conceito Symphony	Primitivo MSD
WORKFLOW.md (intenção de alto nível)	ROADMAP.md (intenção do projeto), STATE.md (status em tempo real), CONTEXT.md de fase (escopo por fase), PLAN.md de fase (etapas executáveis)
Um workspace isolado de agente por tarefa	/msd-workspace --new --strategy worktree
Despacho e concorrência de agentes	/msd-manager (painel interativo), /msd-autonomous (sem supervisão)
Etapas de discussão e planejamento por fase	/msd-discuss-phase → /msd-plan-phase → /msd-execute-phase
Prova de trabalho / evidência de testes	/msd-verify-work (UAT.md persistido entre /clear)
Revisão adversarial	/msd-review (revisão por pares entre IAs do plano)
Controle humano de merge	/msd-ship (cria PR, revisão de código opcional, prepara merge)
Captura de trabalho subsequente	/msd-capture, /msd-capture --seed, /msd-new-milestone, ou uma issue aberta manualmente no rastreador
Controle de concorrência	Semântica de agente gerenciador / segundo plano (sem poller sempre ativo)

O mapeamento é unidirecional: o MSD é responsável pelos controles de segurança (verificação, revisão humana, confirmação explícita para criação de trabalho subsequente). O enquadramento de "orquestração contínua" do Symphony é intencionalmente não adotado — veja Não-objetivos.

Fluxo completo

O loop canônico issue → PR, escrito para poder ser executado a partir de uma única issue do rastreador de ponta a ponta. Substitua os marcadores entre colchetes antes de executar.

1. Escolha a issue do rastreador. Selecione uma issue do seu rastreador (GitHub, Linear, etc.) com escopo suficientemente bem definido para implementação autônoma — escopo delimitado, critérios de aceitação observáveis, sem dependências upstream que bloqueiem a execução.
2. Mapeie para uma fase do MSD. Se a issue se mapear para uma fase existente em ROADMAP.md, selecione-a. Caso contrário, execute /msd-new-milestone (para um novo marco de issues relacionadas) ou abra uma fase via /msd-phase / /msd-phase --insert. Capture a URL da issue do rastreador no CONTEXT.md da fase para que a rastreabilidade sobreviva à compactação.
3. Crie um workspace isolado. Execute /msd-workspace --new --strategy worktree <slug> para criar uma git worktree com um diretório .planning/ independente. A worktree é o limite de segurança: qualquer exploração, commits parciais ou planos abandonados ficam fora do main.
4. Execute discuss → plan → execute através do MSD. De dentro do workspace, execute /msd-discuss-phase para esclarecer ambiguidades, /msd-plan-phase para produzir PLAN.md, e /msd-manager (painel interativo) ou /msd-execute-phase / /msd-autonomous (sem supervisão) para implementar. Evite conduzir invocações brutas de claude de fora do MSD — isso contorna as atualizações de STATE.md e o manifesto de fases.
5. Exija prova de trabalho. Execute /msd-verify-work para conduzir o usuário pelo UAT em relação aos critérios de aceitação da fase. Testes, capturas de tela, registros de log e diffs de configuração são todos gravados em UAT.md, que persiste entre /clear e alimenta lacunas no /msd-plan-phase --gaps quando a verificação revela escopo não coberto.
6. Passe pelos controles de revisão e envio. Execute /msd-review para obter revisão por pares adversarial do plano por IAs independentes (detecta pontos cegos modelo a modelo), depois /msd-ship para abrir o PR com um corpo rico montado a partir dos artefatos de planejamento. Ambos os controles exigem uma decisão humana antes de qualquer coisa chegar ao repositório remoto.
7. Capture trabalho subsequente explicitamente. Use /msd-capture para notas inline, /msd-capture --seed para ideias que valem uma fase futura, ou /msd-new-milestone para um grupo coerente de trabalhos subsequentes. Criar uma issue no rastreador a partir de um trabalho subsequente descoberto requer confirmação explícita do usuário — o MSD não publica em rastreadores remotos automaticamente.

Quando o PR é mesclado, o loop se fecha. Palavras-chave de fechamento automático no corpo do PR (Closes #NNN / Fixes #NNN) fecham a issue do rastreador no momento do merge.

Limites de segurança

O loop é seguro porque quatro invariantes se mantêm por construção:

• Worktrees isoladas. Cada issue roda em uma worktree de /msd-workspace --new, para que trabalho parcial, planos abandonados e commits exploratórios nunca toquem o main. msd-local-patches/ é a superfície de recuperação se edições manuais de uma worktree precisarem voltar após uma atualização.
• Revisão humana explícita. /msd-review e /msd-ship ambos param para aprovação humana. Não há auto-merge e nenhum caminho de auto-PR a partir da execução. Se você quiser remover o controle humano para um repositório específico, essa é a sua decisão de política de proteção de branch / fila de merge — não algo que o MSD decide por você.
• Nenhuma publicação automática. O MSD nunca abre, comenta ou fecha uma issue do rastreador sem um comando explicitamente iniciado pelo usuário. A captura de trabalho subsequente padrão são artefatos locais (notas, seeds, marcos); empurrar de volta para o rastreador é uma etapa manual separada.
• Verificação antes do envio. O UAT.md do /msd-verify-work deve registrar evidências antes que /msd-ship seja executado. A disciplina recomendada é tratar verification_failed como um bloqueador mesmo quando a implementação parece correta — a falha geralmente revela um critério de aceitação perdido, não um teste instável.

Se qualquer um desses invariantes for contornado (ex: executar claude diretamente na worktree, pular /msd-verify-work, ou criar issues via a API do rastreador sem confirmação do usuário), as garantias deste guia não se aplicam.

Não-objetivos

Este guia deliberadamente não propõe nada do seguinte. Eles estão listados aqui para que futuros contribuidores não voltem a discuti-los em revisão de código:

• Sem venda ou cópia do código Symphony. O MSD reutiliza seus próprios primitivos. O mapeamento acima é conceitual; nenhum código derivado do Symphony está incluído neste repositório.
• Sem daemon de longa execução. O MSD não faz polling no GitHub ou Linear. Os fluxos de trabalho de manager e autonomous lidam com concorrência através da semântica de agente em segundo plano, não de um daemon.
• Sem dependência obrigatória de rastreador. O loop funciona sem qualquer integração com rastreador. A etapa "issue do rastreador" é uma entrada humana — a URL vai para CONTEXT.md. O MSD não tem opinião sobre qual rastreador você usa, ou se você usa algum.
• Sem contorno dos controles de verificação, revisão ou decisão humana. Mesmo ao executar /msd-autonomous, os controles de verificação e revisão ainda disparam. O rótulo "autonomous" se refere à progressão de fase a fase, não ao pulo da aprovação humana.
• Sem expansão da superfície padrão de habilidades / comandos. Cada comando referenciado neste guia já existe. Este guia é uma superfície de documentação, não uma superfície de funcionalidades.

Possível trabalho subsequente

Se a experiência dos mantenedores com esse loop justificar, uma melhoria aprovada poderá adicionar posteriormente uma ponte mínima com rastreadores:

• Importar uma issue do GitHub ou Linear para um workspace / fase do MSD.
• Exportar evidências de UAT.md como comentário na issue de origem.
• Gerar issues de trabalho subsequente no rastreador a partir da saída de /msd-capture --seed.

Cada uma dessas seria sua própria proposta de melhoria, pois cada uma adiciona superfície de integração e carga de manutenção contínua. Elas estão fora do escopo deste guia.

Relacionados

• O loop de fase — como discuss → plan → execute → verify → ship se encaixam como um ciclo repetitivo.
• Como trabalhar com workspaces — guia passo a passo para criar e gerenciar worktrees paralelas.
• Índice de documentação — sumário completo da documentação do MSD Core.
• docs/USER-GUIDE.md — guias orientados a tarefas dos comandos individuais referenciados acima.
• docs/COMMANDS.md — referência completa dos comandos /msd-*.
• docs/FEATURES.md — matriz de capacidades por funcionalidade (workspaces, manager, autonomous, verify, review, ship).
• docs/ARCHITECTURE.md — ciclo de vida dos artefatos de fase e mecânica do STATE.md.