workflow-commands

name	workflow-commands
description	AgentSpec commands for workflow. Use /workflow-commands + intent. Reads .github/config/grounding.md before executing. Commands: /brainstorm, /build, /validate, /create-pr, /define, /design, /iterate, /ship
license	MIT
compatibility	GitHub Copilot VS Code, GitHub Copilot cloud agent
metadata	{"version":"1.0.0","category":"commands","legacy-source":"claude workflow commands"}

Workflow Commands

Invoke: /workflow-commands + descrição da tarefa

Regras Globais Obrigatórias

Estas regras são mandatórias para todos os comandos deste skill. Se houver conflito entre exemplos antigos, comentários legados ou documentação migrada e esta seção, esta seção vence.

Grounding e Roteamento

1. Este skill só pode ser executado quando a mensagem invocar explicitamente /workflow-commands.
2. Antes de executar qualquer fase, leia .github/config/grounding.md.
3. Como este skill foi invocado, ele tem prioridade sobre roteamento por intent.
4. Leia .github/sdd/architecture/WORKFLOW_CONTRACTS.yaml antes de selecionar ou executar a fase.
5. Leia .github/config/routing.json e selecione o agente da fase pelo comando solicitado.
6. Leia o arquivo do agente selecionado em .github/agents/workflow.*.agent.md.
7. Carregue KB somente se a rota exigir. As rotas de workflow atuais não carregam KB.
8. Toda resposta operacional deve iniciar com o bloco [GROUNDING] exigido por .github/config/grounding.md.

Contrato Canônico de Workflow

WORKFLOW_CONTRACTS.yaml é fonte canônica para fases, entradas obrigatórias, saídas obrigatórias, gates, caminhos, transições e bloqueios de qualidade.

Regras:

• Todo comando deste skill deve carregar .github/sdd/architecture/WORKFLOW_CONTRACTS.yaml antes de executar a fase.
• Se houver conflito entre exemplos legados neste arquivo e WORKFLOW_CONTRACTS.yaml, o contrato vence.
• O agente da fase deve aplicar o contrato antes de escrever, validar, arquivar ou orientar o próximo passo.
• Nenhum gate pode ser relaxado pelo agente sem registrar explicitamente o bloqueio e pedir decisão do usuário.

Inicialização Obrigatória via Skill

As fases SDD (/brainstorm, /define, /design, /build, /validate, /ship, /iterate, /create-pr) não podem ser iniciadas por roteamento genérico, prompt natural ou chamada direta ao agente de workflow. O usuário deve invocar:

/workflow-commands /<fase> ...

Se a intenção for clara mas o /workflow-commands estiver ausente, não execute a fase. Responda com o comando exato que o usuário deve rodar.

Caminhos Canônicos

Tipo	Caminho correto
Features em andamento	.github/sdd/features/{feature-name}/
Brainstorm	.github/sdd/features/{feature-name}/BRAINSTORM_{FEATURE}.md
Define	.github/sdd/features/{feature-name}/DEFINE_{FEATURE}.md
Design	.github/sdd/features/{feature-name}/DESIGN_{FEATURE}.md
Build report	.github/sdd/features/{feature-name}/BUILD_REPORT_{FEATURE}.md
Validation report	.github/sdd/features/{feature-name}/VALIDATION_REPORT_{FEATURE}.md
Runbook	.github/sdd/features/{feature-name}/RUNBOOK_{FEATURE}.md
Remediation roadmap	.github/sdd/features/{feature-name}/ROADMAP_{FEATURE}.md
Build output root	./projects/{feature-name}/
Ship archive	.github/sdd/archive/{feature-name}/SHIPPED_{DATE}.md
Templates	.github/sdd/templates/*.md
Contratos	.github/sdd/architecture/WORKFLOW_CONTRACTS.yaml
Instruções Copilot	.github/copilot-instructions.md
Agentes de workflow	.github/agents/workflow.*.agent.md
Judge runtime	external runtime only; no bundled scripts/archive runner
Judge setup	docs/getting-started/judge-setup.md

Regras de Caminho

• Nunca use caminhos .claude/**.
• Nunca grave artefatos de feature diretamente em .github/sdd/features/ exceto .gitkeep.
• Sempre normalize {FEATURE} em UPPER_SNAKE_CASE para nomes de arquivos.
• Sempre normalize {feature-name} em kebab-case para diretórios.
• Se o usuário fornecer apenas DEFINE_FOO.md, resolva para .github/sdd/features/*/DEFINE_FOO.md; se houver mais de uma correspondência, pare e peça desambiguação.
• Se o diretório .github/sdd/features/{feature-name}/ não existir para uma nova fase, crie-o antes de escrever artefatos.
• Não crie .github/sdd/reports/; build reports pertencem ao diretório da feature.
• Durante /build, todo arquivo de implementação deve ser criado em ./projects/{feature-name}/, preservando o caminho relativo do manifesto.
• Não escreva arquivos de implementação na raiz do repositório; a raiz fica para documentação, instruções e controle do AgentSpec.

Gates Rígidos por Fase

Comando	Entrada obrigatória	Saída obrigatória	Agente
/brainstorm	Ideia, problema ou notas	BRAINSTORM_{FEATURE}.md	.github/agents/workflow.brainstorm-agent.agent.md
/define	Input direto ou BRAINSTORM_{FEATURE}.md	DEFINE_{FEATURE}.md	.github/agents/workflow.define-agent.agent.md
/design	DEFINE_{FEATURE}.md	DESIGN_{FEATURE}.md	.github/agents/workflow.design-agent.agent.md
/build	DESIGN_{FEATURE}.md	Código + BUILD_REPORT_{FEATURE}.md	.github/agents/workflow.build-agent.agent.md
/validate	DEFINE, DESIGN, BUILD_REPORT, código em projects/{feature-name}/	VALIDATION_REPORT_{FEATURE}.md + RUNBOOK ou ROADMAP	.github/agents/workflow.validate-agent.agent.md
/ship	DEFINE, DESIGN, BUILD_REPORT, VALIDATION_REPORT aprovado e RUNBOOK	SHIPPED_{DATE}.md	.github/agents/workflow.ship-agent.agent.md
/iterate	BRAINSTORM, DEFINE ou DESIGN existente	Mesmo arquivo atualizado, com revision history	.github/agents/workflow.iterate-agent.agent.md

• /design não pode iniciar sem DEFINE_{FEATURE}.md.
• /build não pode iniciar sem DESIGN_{FEATURE}.md e manifesto de arquivos no design.
• /validate não pode iniciar se BUILD_REPORT_{FEATURE}.md não existir ou se o código não existir em projects/{feature-name}/.
• /ship não pode iniciar se VALIDATION_REPORT_{FEATURE}.md não existir, registrar CRITICAL issues ou score abaixo de 90.
• Se um gate falhar, pare a fase e diga exatamente qual arquivo ou condição falta.
• Não invente requisitos ausentes para passar gate; peça a menor clarificação necessária.

Comandos Disponíveis

Comando	Descrição	Arquivo	Agente
/brainstorm	Ideação e exploração inicial	commands/brainstorm.md	brainstorm-agent
/define	Definição de requisitos e escopo	commands/define.md	define-agent
/design	Design técnico e arquitetura	commands/design.md	design-agent
/build	Implementação e geração de código	commands/build.md	build-agent
/validate	Quality gate multi-agente (Phase 3.5)	commands/validate.md	validate-agent
/ship	Empacotamento e arquivamento	commands/ship.md	ship-agent
/iterate	Revisão e atualização cross-phase	commands/iterate.md	iterate-agent
/create-pr	Criação de Pull Request	commands/create-pr.md	N/A

Knowledge Context Commands

Skill complementar para gestão de contexto de projeto. Invoke via /knowledge-context-commands.

Comando	Descrição	Skill
/create-context	Criar knowledge context completo para um projeto	.github/skills/knowledge-context/commands/create-context.md
/update-context	Atualizar arquivos de contexto de um projeto existente	.github/skills/knowledge-context/commands/update-context.md
/check-context	Auditar o knowledge context ativo e reportar gaps	.github/skills/knowledge-context/commands/check-context.md

O Knowledge Context é carregado automaticamente no Passo 0 do /brainstorm (Knowledge Checkpoint). Configure o projeto ativo com /knowledge-context-commands /create-context <slug> --set-active antes de iniciar o workflow.

Skill completo: .github/skills/knowledge-context/SKILL.md

Fluxo de Fases

/brainstorm → /define → /design → /build → /validate → /ship
                                      ↑                    |
                                      └── /iterate ←───────┘

Delegação

Durante /build, o agente pode delegar tarefas a especialistas via @{agent-name}:

• @{container-specialist} — Docker, Compose, infraestrutura
• @{dbt-specialist} — Modelos dbt, testes, docs
• @{airflow-specialist} — DAGs, operators, scheduling
• @{python-developer} — Scripts, testes, CLI tools

Cada especialista delegado deve:

1. Ler seu agent file em .github/agents/{category}/{name}.agent.md
2. Carregar KB quick-reference se declarado no agent
3. Cumprir quality gates do agente
4. Registrar evidência no BUILD_REPORT_{FEATURE}.md
5. Escrever arquivos em ./projects/{feature-name}/

Validação (Phase 3.5)

/validate usa 4 juntas hierárquicas Copilot-nativas (sem dependências externas):

Junta	Tipo	Personas	Output
SpecCrew	Paralela	MGR, ARC, ENG, SWE	01_SPEC_REPORT.json
CodeCrew	Paralela	MGR, SWE, ENG, OPS	02_CODE_REPORT.json
DeliveryCrew	Sequencial	CMP, GAP	03_DELIVERY_DELTA.json
CouncilCrew	Sequencial	JDG, RPT, PRD	04_COUNCIL_VERDICT.json

Scoring é determinístico (sem LLM): score = alignment×0.30 + quality×0.25 + architecture×0.20 + devops×0.15 + delta×0.10

Contrato canônico: .github/sdd/architecture/VALIDATE_JUNTAS_CONTRACT.yaml Prompts das juntas: .github/skills/workflow-commands/references/*.md Renderer: .github/skills/workflow-commands/scripts/render.py