Spec Driven Development

README.md

Você é o agente executor responsável por instalar o SDD Framework neste projeto.

Sua tarefa é configurar o framework descrito neste prompt e, quando disponível no projeto, no arquivo SDD_BUILD.md. Você deve produzir uma instalação durável, reutilizável e segura para execuções futuras de Specification-Driven Development.

Resultado Esperado

Instale um fluxo SDD completo com:

• especificação aprovada como fonte primária da verdade;
• DRY;
• Dependency First;
• KISS;
• SOLID;
• composição em vez de herança;
• arquitetura orientada a capacidades;
• rastreabilidade de spec até evidência;
• subagentes com identidade, escopo e permissões explícitas;
• isolamento de contexto entre agentes;
• ownership de arquivos;
• execução paralela segura;
• quality gates;
• Definition of Ready;
• Definition of Done;
• auditoria contratual, testes, segurança e arquitetura;
• handoffs formais;
• prevenção de drift entre spec, task graph, código, testes e evidências.

Regras Obrigatórias

• Não execute nenhuma run SDD agora.
• Não inicie SPEC_PATH.
• Não inicie PLAN_PATH.
• Não retome RUN_DIR.
• Não crie arquivos dentro de docs/sdd/runs/<run_id>/.
• Pode criar a pasta vazia docs/sdd/runs/.
• Não implemente funcionalidade.
• Não altere código de aplicação.
• Não faça commit, stage, push ou PR.
• Não sobrescreva arquivo existente sem mesclar a intenção útil dele.
• Se existir AGENTS.md, preserve o conteúdo atual e acrescente apenas uma seção SDD.
• Se não existir AGENTS.md, crie um arquivo mínimo com regras do projeto e seção SDD.
• Leia o projeto vivo antes de preencher contrato, stack, comandos e paths.
• Quando não souber algo com evidência local, use <TODO> em vez de inventar.
• Não transplante contrato opaco de outro projeto; adapte ao repositório atual.

Fontes de Verdade

Use esta ordem:

1. Instruções explícitas deste prompt.
2. SDD_BUILD.md, se existir.
3. Estrutura e intenção já existentes no projeto.
4. O contrato mínimo embutido neste prompt.

Se SDD_BUILD.md existir, leia-o integralmente antes de criar arquivos. Use as seções dele como conteúdo canônico dos arquivos correspondentes.

Leitura Inicial

Antes de editar:

1. Liste a raiz do projeto.
2. Verifique se existem AGENTS.md, SDD_BUILD.md, docs/, .codex/, .agents/, manifests, lockfiles, CI, contratos e arquivos de teste.
3. Leia SDD_BUILD.md, se existir.
4. Leia AGENTS.md, se existir.
5. Identifique stack, comandos, contratos, generated artifacts e paths protegidos com base em arquivos reais do repo.

Comandos úteis, adaptando ao shell do ambiente:

git status --short --branch
find . -maxdepth 3 -type f | sort

No Windows/PowerShell, use equivalentes como:

git status --short --branch
Get-ChildItem -Force -Recurse -Depth 3

Estrutura a Criar ou Atualizar

Crie ou atualize estes arquivos e diretórios:

.codex/
  agents/
    sdd-meta-runner.toml
    sdd-context-scout.toml
    sdd-architect.toml
    sdd-engineer.toml
    sdd-reviewer.toml
    sdd-contract-auditor.toml
    sdd-test-auditor.toml
    sdd-security-auditor.toml
.agents/
  skills/
    sdd-meta-runner/
      SKILL.md
      references/
        meta-runner-checklist.md
    sdd-architect/
      SKILL.md
    sdd-engineer/
      SKILL.md
    sdd-reviewer/
      SKILL.md
docs/
  sdd/
    PROJECT_CONTRACT.md
    SDD_CONSTITUTION.md
    ACTIVE_SPEC.md
    specs/
    reviews/
    handoffs/
    runs/
    templates/
      RUN_STATE_TEMPLATE.md
      SPEC_TEMPLATE.md
      CONTEXT_PACK_TEMPLATE.md
      TASK_GRAPH_TEMPLATE.md
      SPEC_TRACEABILITY_MATRIX_TEMPLATE.md
      AGENT_ROSTER_TEMPLATE.md
      FILE_OWNERSHIP_TEMPLATE.md
      GAP_MATRIX_TEMPLATE.md
      EVIDENCE_LEDGER_TEMPLATE.md
      FINAL_REPORT_TEMPLATE.md
      WORK_ORDER_TEMPLATE.md

Não crie uma run dentro de docs/sdd/runs/. A pasta deve ficar vazia até um pedido futuro com SPEC_PATH, PLAN_PATH ou RUN_DIR.

Como Preencher os Arquivos

AGENTS.md

Acrescente uma seção ## SDD Meta Runner com estas regras:

• A especificação aprovada é a fonte primária.
• SPEC_PATH inicia uma run a partir de uma spec aprovada.
• PLAN_PATH inicia descoberta ou planejamento, mas não substitui spec aprovada.
• RUN_DIR retoma uma run existente.
• Não implementar sem Definition of Ready.
• Não fechar run sem Definition of Done ou bloqueio documentado.
• Work orders devem ficar em docs/sdd/runs/<run_id>/WORK_ORDERS/.
• Prompts reais enviados a subagentes devem ficar em docs/sdd/runs/<run_id>/AGENT_PROMPTS/.
• Auditorias são read-only por padrão.
• Não editar generated artifacts manualmente quando houver gerador.
• Não tocar segredos, logs sensíveis, dumps, caches ou paths protegidos.
• Código estrutural deve usar nomes em Inglês.
• Comunicação com usuário deve seguir o idioma definido em PROJECT_CONTRACT.md.

docs/sdd/PROJECT_CONTRACT.md

Crie um contrato do projeto com:

• identidade do projeto;
• idioma humano padrão;
• idioma de nomes estruturais de código;
• stack real;
• manifests, lockfiles e política de dependências;
• comandos canônicos de install, build, lint, test, typecheck e contract generation;
• contratos API/event/schema;
• generated artifacts e respectivos geradores;
• paths protegidos;
• ownership rules;
• Definition of Ready;
• Definition of Done;
• quality gates.

Use <TODO> para qualquer item sem evidência local.

docs/sdd/SDD_CONSTITUTION.md

Inclua os princípios:

• Specification first;
• DRY;
• Dependency First;
• KISS;
• SOLID;
• composição em vez de herança;
• arquitetura orientada a capacidades;
• traceability always;
• evidence over assumption;
• context isolation;
• controlled autonomy;
• no invented requirements.

Inclua lifecycle:

specify -> clarify -> approve -> dependency-map -> plan -> task -> implement -> review -> verify -> report

Inclua stop conditions para:

• spec incompleta;
• P0/P1 aberto;
• ownership conflitante;
• path protegido;
• generated artifact exigindo edição manual;
• contrato ou segurança ambíguos;
• comando de validação desconhecido para mudança arriscada.

docs/sdd/ACTIVE_SPEC.md

Crie com status inicial none, sem spec ativa, e instruções de uso futuro para SPEC_PATH, PLAN_PATH e RUN_DIR.

Skills

Crie as skills permanentes:

• sdd-meta-runner: orquestra runs, work orders, prompts, traceability, gaps e evidence.
• sdd-architect: cria ou refina specs antes de implementação.
• sdd-engineer: implementa somente escopo aprovado e owned.
• sdd-reviewer: revisa diff real contra spec, task graph e evidence.

Regras comuns das skills:

• Ler AGENTS.md, PROJECT_CONTRACT.md e SDD_CONSTITUTION.md.
• Não depender apenas do chat.
• Não inventar requisito.
• Não editar fora do work order.
• Não reverter trabalho do usuário ou de outro agente.
• Registrar gaps e evidências nos artefatos corretos.

Agent Configs

Crie configs TOML para:

• sdd-meta-runner;
• sdd-context-scout;
• sdd-architect;
• sdd-engineer;
• sdd-reviewer;
• sdd-contract-auditor;
• sdd-test-auditor;
• sdd-security-auditor.

Cada config deve conter:

• name;
• description;
• model;
• model_reasoning_effort;
• nickname_candidates;
• developer_instructions.

Os auditores devem ser read-only por padrão.

Templates

Crie os templates abaixo. Eles devem ser completos o suficiente para uma run futura ser retomável sem histórico do chat:

• RUN_STATE_TEMPLATE.md: status, stage, decisions, Ready, Done, next action, resume prompt.
• SPEC_TEMPLATE.md: objective, scope, out of scope, contexto, dependências, contratos, ACs, testes, riscos, Ready, Done.
• CONTEXT_PACK_TEMPLATE.md: regras, spec, dependency map, arquivos relevantes, protected paths, comandos.
• TASK_GRAPH_TEMPLATE.md: requirements, dependency graph, work slices, readiness checks.
• SPEC_TRACEABILITY_MATRIX_TEMPLATE.md: spec section, requirement, work order, files, validation, evidence, gap.
• AGENT_ROSTER_TEMPLATE.md: agentes, missão, fase, permissão, writes allowed, status.
• FILE_OWNERSHIP_TEMPLATE.md: path, write owner, wave, reason, conflict status.
• GAP_MATRIX_TEMPLATE.md: gap, requirement, severity, category, owner, status, evidence.
• EVIDENCE_LEDGER_TEMPLATE.md: evidence id, command/check, environment, result, artifact, sanitized flag.
• FINAL_REPORT_TEMPLATE.md: summary, requirements, traceability, files, validations, gaps, resume prompt.
• WORK_ORDER_TEMPLATE.md: identity lock, mission, phase, permissions, required reading, scope, ownership, validation, stop conditions, output format.

O WORK_ORDER_TEMPLATE.md deve deixar explícito que cada subagente tem:

• nome;
• missão;
• fase;
• permissões;
• arquivos que deve ler;
• arquivos que pode escrever;
• arquivos que não pode escrever;
• critérios de parada;
• formato de saída esperado;
• relação com SPEC_TRACEABILITY_MATRIX.md;
• relação com EVIDENCE_LEDGER.md;
• regra contra assumir outro papel;
• regra contra inventar requisito;
• regra contra editar fora do work order;
• regra contra reverter trabalho de usuário ou outro agente.

Contrato Mínimo Embutido

Se SDD_BUILD.md não existir, implemente estes conceitos mínimos:

• SPEC_PATH inicia run futura a partir de uma especificação aprovada.
• PLAN_PATH inicia descoberta ou planejamento futuro, mas não substitui spec.
• RUN_DIR retoma uma run futura pelo estado persistido.
• SDD_CONSTITUTION.md define princípios, lifecycle, precedência e stop conditions.
• PROJECT_CONTRACT.md define stack, comandos, dependências, generated artifacts e paths protegidos.
• ACTIVE_SPEC.md aponta para a spec ativa aprovada.
• RUN_STATE.md guarda estado da run.
• TASK_GRAPH.md quebra requisitos derivados da spec aprovada.
• SPEC_TRACEABILITY_MATRIX.md liga spec, requisitos, arquivos, testes, evidências e gaps.
• WORK_ORDERS/ trava identidade, escopo e permissões dos agentes.
• AGENT_PROMPTS/ guarda o prompt real enviado a cada subagente.
• FILE_OWNERSHIP.md evita conflito de escrita.
• GAP_MATRIX.md bloqueia P0/P1 aberto.
• EVIDENCE_LEDGER.md registra evidência real.
• FINAL_REPORT.md fecha a run ou documenta bloqueio.

Validação da Instalação

Depois de editar:

1. Liste arquivos criados e alterados.
2. Verifique que deep-research-report.md, código de aplicação e arquivos fora do escopo não foram alterados.
3. Verifique que nenhuma run foi criada dentro de docs/sdd/runs/<run_id>/.
4. Verifique que docs/sdd/runs/ está vazio ou contém apenas conteúdo preexistente.
5. Verifique que PROJECT_CONTRACT.md não inventa stack, comando ou ownership sem evidência.
6. Verifique que os templates possuem os campos obrigatórios.
7. Não faça commit, stage, push ou PR.

Resposta Final Esperada

Ao final, responda com:

• arquivos criados/alterados;
• pontos preenchidos com <TODO>;
• confirmação de que nenhuma run foi executada;
• como usar futuramente.

Inclua estes prompts de uso futuro:

Utilize o meta runner com SPEC_PATH="docs/sdd/specs/minha-feature.md" MODE=supervised

Utilize o meta runner com PLAN_PATH="docs/plans/minha-sprint.md" MODE=supervised

Utilize o meta runner com PLAN_PATH="docs/plans/minha-sprint.md" MODE=auto

Utilize o meta runner com RUN_DIR="docs/sdd/runs/YYYY-MM-DD-minha-sprint"

deep-research-report.md

Otimização de um fluxo SDD existente para uma abordagem DRY, dependency-first e spec-driven com sub-agentes corretamente definidos

Resumo executivo

O material-base que você enviou já descreve um fluxo SDD surpreendentemente maduro: ele trata a especificação aprovada como fonte primária, persiste o estado da run em artefatos rastreáveis, separa papéis de agentes, define ondas de execução e só permite implementação após Definition of Ready, com fechamento condicionado a Definition of Done ou bloqueio documentado. Em outras palavras, o núcleo metodológico já está correto. O principal espaço de otimização não está em “inventar um processo novo”, mas em operacionalizar melhor três princípios que hoje aparecem mais como regra de governança do que como regra executável do build e da arquitetura: DRY como fonte única de verdade, dependency-first como grafo explícito de módulos e versões, e spec-driven development como contrato formal que dirige geração, validação e evidência. fileciteturn0file0 fileciteturn0file1

A recomendação central desta pesquisa é transformar o fluxo atual em uma arquitetura de três planos: governança SDD, contratos e dependências, e execução automatizada. Na prática, isso significa: promover specs e contratos para formatos reaproveitáveis e verificáveis; centralizar dependências e versões em manifests/lockfiles/version catalogs; separar build logic de application code; formalizar a interface de sub-agentes com work orders + envelopes de handoff; e usar CI com reusable workflows, matrix jobs e artefatos de evidência. OpenAPI e AsyncAPI sustentam explicitamente a ideia de contrato primário reutilizável; npm, PyPA e Gradle oferecem mecanismos concretos para centralizar dependências e tornar builds reproduzíveis; e GitHub Actions fornece primitives oficiais para reuso de pipeline, parametrização, matriz e evidências. citeturn11view0turn11view1turn11view5turn8view1turn8view2turn9view1turn9view3turn10view1turn10view2turn7view6turn7view7turn7view8

O resultado esperado dessa atualização é um fluxo com menos duplicação de conhecimento, menor acoplamento implícito entre módulos e agentes, menos deriva entre spec e implementação, mais previsibilidade no build, e paralelização muito mais segura de sub-agentes. O que muda, portanto, não é só a “documentação do processo”, mas a cadeia inteira entre spec → contratos → dependências → build → testes → evidência. fileciteturn0file0 citeturn11view2turn11view4turn10view1turn16view3

Princípios atuais e diagnóstico do fluxo existente

No fluxo atual, há quatro virtudes estruturais claras: regras permanentes do projeto, skill de orquestração com runs persistidas, agentes com papéis fixos e artefatos de run que registram estado, lacunas, evidências e ownership. Além disso, o kit que você enviou explicita corretamente que a spec aprovada é a fonte primária, que planos e tarefas derivam da spec, que MODE=auto só pode implementar após Definition of Ready e que a run não fecha com lacunas P0/P1 abertas. Isso já coloca o seu fluxo acima da média de muitos “SDD” que, na prática, são apenas checklists de prompts. fileciteturn0file0

Abaixo está a leitura mais útil dos três princípios para uma atualização moderna do fluxo:

Princípio	Leitura prática correta	Implicação para o fluxo
DRY	Cada peça de conhecimento deve ter uma representação autoritativa e não ambígua	Specs, contratos, versões, comandos canônicos e ownership não devem ser duplicados em múltiplos arquivos editáveis
Dependency-first	Dependências de módulo, runtime, contrato, build e validação devem ser conhecidas antes da implementação	O planejamento precisa explicitar o grafo de dependências e o build precisa centralizar versões e locks
SDD spec-driven	A implementação deriva de uma spec aprovada e rastreável, e não de interpretação livre do agente	Especificação, critérios de aceitação, contratos, testes e evidências precisam estar encadeados

Essa síntese é coerente com a formulação clássica do DRY como representação única de conhecimento, com o seu kit atual — que já consagra a spec como fonte de verdade e a rastreabilidade até a evidência — e com o modo como OpenAPI e AsyncAPI tratam descrições formais de interface e reutilização via referências. citeturn12search1turn11view0turn11view1turn11view5 fileciteturn0file0

A nuance importante é que “dependency-first” não é um rótulo universalmente padronizado como DRY ou OpenAPI, mas, no seu material, ele já aparece como princípio constitucional e regra de implementação. A melhor interpretação contemporânea é esta: antes de codificar, o fluxo precisa conhecer quem depende de quem, qual contrato é estável, qual versão é autorizada, qual comando valida o quê, e qual artefato é gerado e não deve ser editado manualmente. Em Gradle isso se traduz em version catalogs e dependency locking; em npm, em workspaces e package-lock; em Python, em pyproject.toml, especificadores formais de dependência e separação clara entre metadata, tooling e grupos de dependências. fileciteturn0file0 citeturn10view1turn10view2turn10view3turn8view1turn8view2turn9view0turn9view1turn9view7

O diagnóstico mais objetivo do fluxo existente, portanto, é o seguinte: a governança está forte, mas a camada executável ainda pode ficar mais canônica. Hoje o fluxo já tem TASK_GRAPH, SPEC_TRACEABILITY_MATRIX, GAP_MATRIX, EVIDENCE_LEDGER e FILE_OWNERSHIP; o próximo passo é garantir que o build, os manifests e os contratos externos/internalizados reflitam essas mesmas decisões sem repetição manual. Essa é a passagem de um SDD “bem documentado” para um SDD “realmente dirigindo a entrega”. fileciteturn0file0 citeturn11view2turn11view4turn10view1turn8view2

Pontos típicos de refatoração em fluxos SDD

Em fluxos SDD já existentes, os maiores problemas quase nunca estão na ausência de documentos; eles aparecem quando a documentação deixa de ter força executável. Em geral, a refatoração precisa atacar arquitetura, modularização, contratos, testes, CI/CD e versionamento ao mesmo tempo, porque esses elementos formam um único circuito de rastreabilidade. O que segue é a lista dos pontos que mais frequentemente exigem reestruturação. A tabela é uma síntese analítica baseada no seu kit atual e nas práticas oficiais de OpenAPI, AsyncAPI, npm, PyPA, Gradle e GitHub Actions. fileciteturn0file0 citeturn11view0turn11view5turn8view1turn9view1turn10view2turn7view6turn7view7turn7view8

Área	Sintoma típico no fluxo SDD	Refatoração recomendada	Ganho esperado
Arquitetura	Features acessam infra e pares lateralmente sem fronteira clara	Separar domínio, contratos, adapters e app composition	Menor acoplamento e melhor paralelismo entre agentes
Modularização	Módulos empacotam lógica, contratos e build config no mesmo lugar	Extrair módulos por responsabilidade e centralizar build logic	DRY real e isolamento de dependências
Contratos e specs	Spec Markdown e contrato técnico divergem	Manter spec aprovada + contrato executável derivado	Menos deriva entre intenção e API/evento
Testes	Testes espelham implementação, não critérios de aceitação	Organizar suites por propósito e por requisito	Evidência rastreável por AC/REQ
CI/CD	Pipeline copia e cola jobs, secrets e comandos	Reusable workflows + matrix + artifacts + permissões mínimas	Menos duplicação, mais segurança e auditoria
Versionamento	Versões declaradas em múltiplos manifests ou submódulos	Version catalogs, lockfiles, metadata única	Builds reproduzíveis e upgrades controlados

Do ponto de vista arquitetural, o antipadrão mais comum é o “SDD no papel, monólito no código”: a spec decompõe requisitos, mas a base continua organizada por framework ou camada técnica, sem fronteiras de módulo nem contratos internos explícitos. Em Gradle, a própria documentação de multi-project builds parte da ideia de quebrar sistemas crescentes em módulos menores, focados e logicamente isolados; em OpenAPI/AsyncAPI, a noção de contrato formal reforça a necessidade de fronteiras nítidas entre o que é interface estável e o que é implementação. citeturn10view4turn10view5turn11view0turn11view5

Na modularização, vale um alerta importante: centralizar dependências não é o mesmo que centralizar tudo num único arquivo monolítico. Em npm, workspaces existem justamente para administrar múltiplos pacotes a partir de um pacote-raiz com linking automatizado; em Gradle, version catalogs centralizam coordenadas e versões; em Python, o pyproject.toml separa [build-system], [project] e [tool], o que ajuda a impedir mistura entre metadata de pacote e configuração de ferramentas. O fluxo SDD ideal usa essa centralização para controlar variação, e não para criar um “arquivo deus”. citeturn8view1turn8view5turn10view2turn10view3turn9view0turn9view1

Nos contratos/specs, a refatoração mais valiosa é promover a spec aprovada para um conjunto de fontes coesas: uma spec humana e versionável, mais um ou mais contratos executáveis quando fizer sentido. OpenAPI explicita reutilização com components e $ref; AsyncAPI trata o documento como contrato de comunicação entre emissores e receptores; e Swagger/OpenAPI Generator demonstram que um contrato bem definido pode dirigir geração de stubs, SDKs, documentação e testes. Isso casa perfeitamente com a sua SPEC_TRACEABILITY_MATRIX, que hoje já descreve a direção certa, mas pode ser reforçada por artefatos gerados e validados automaticamente. citeturn11view0turn11view2turn11view4turn11view5 fileciteturn0file0

Em testes, a modernização mais útil é sair da dicotomia “unitário ou integração” como mera convenção de pasta e passar a modelar suites pelo propósito de validação. Gradle já formaliza isso no JVM Test Suite Plugin, que permite agrupar suites com dependências e frameworks distintos; o seu fluxo atual, por sua vez, já distingue evidência executada, bloqueada e não executada, o que é excelente para auditoria. O que falta é mapear cada requisito prioritário para a suite mais adequada e para um comando canônico inequívoco. citeturn10view7 fileciteturn0file0

Em CI/CD, o refactor mais recorrente é substituir YAMLs duplicados por um pipeline pequeno no topo chamando workflows reutilizáveis com workflow_call, inputs e secrets, além de usar matrix strategy e artefatos de evidência. GitHub documenta explicitamente que reusable workflows ficam em .github/workflows, usam workflow_call, aceitam inputs/secrets, podem ser combinados com matriz, e podem publicar artefatos nomeados. Isso é particularmente útil para um fluxo SDD porque o resultado relevante não é só “buildou”; é também qual spec foi validada, qual contrato foi gerado, qual evidência foi publicada e qual gap bloqueou a promoção. citeturn7view6turn7view7turn7view8

Por fim, em versionamento e supply chain, a refatoração moderna precisa tratar versionamento funcional e versionamento de dependências como assuntos relacionados, não separados. package-lock.json existe para fixar a árvore exata e é destinado a ser commitado; Gradle recomenda locking para builds reproduzíveis; e CycloneDX fornece um padrão de BOM/SBOM voltado à redução de risco da cadeia de suprimentos. Em um fluxo SDD atualizado, o versionamento não termina no Git tag: ele inclui também a fotografia das dependências que sustentam a spec implementada. citeturn8view2turn8view3turn10view1turn16view0turn16view1

Nova arquitetura de fluxo SDD com sub-agentes, interfaces e isolamento de dependências

A forma mais robusta de atualizar o seu fluxo é tratá-lo como uma arquitetura em três planos.

O plano de governança contém AGENTS.md, PROJECT_CONTRACT.md, SDD_CONSTITUTION.md, ACTIVE_SPEC.md e os critérios de Ready/Done. O plano de contrato contém a spec humana, os contratos executáveis derivados quando existirem, os manifests de dependência e os locks/version catalogs. O plano de execução contém orquestração, work orders, handoffs, ci workflows e evidence artifacts. Isso preserva a filosofia do kit atual, mas torna explícito o que hoje está difuso entre documentação, build e pipeline. fileciteturn0file0 citeturn10view2turn8view2turn9view1turn7view6turn7view8

A atualização mais útil na camada de sub-agentes é separar “entender dependências” de “desenhar arquitetura”. Hoje o fluxo já possui sdd-context-scout, sdd-architect, sdd-engineer, sdd-reviewer, auditores de contrato, teste e segurança. Minha recomendação é manter essa base, mas explicitar um nono papel lógico — que pode virar agente separado ou responsabilidade formal do context scout — chamado dependency-cartographer. Ele é o agente que confirma manifests, locks, versões, módulos, geradores oficiais e ordem de build antes de qualquer implementação. Essa inclusão reduz um problema clássico de fluxos multiagentes: o engenheiro descobrir tarde demais que a spec estava correta, mas o grafo de dependências não estava. fileciteturn0file0 citeturn10view1turn10view2turn8view2turn9view0

Diagrama do fluxo proposto

flowchart TD
    A[Spec aprovada] --> B[Meta Runner Orchestrator]
    B --> C[Context Scout]
    B --> D[Dependency Cartographer]
    B --> E[Spec Architect]
    C --> F[Context Pack]
    D --> G[Dependency Graph]
    E --> H[Contract Bundle]
    F --> I[Task Graph]
    G --> I
    H --> I
    I --> J[Work Orders]
    J --> K[Engineer Slice A]
    J --> L[Engineer Slice B]
    J --> M[Contract Steward]
    K --> N[Review Bundle]
    L --> N
    M --> N
    N --> O[Reviewer]
    N --> P[Test Auditor]
    N --> Q[Security Auditor]
    O --> R[Evidence Ledger]
    P --> R
    Q --> R
    R --> S[Final Report]

Loading

O ponto decisivo aqui é que a comunicação entre agentes não deve depender do histórico do chat, e nisso o seu material já está certíssimo. O aprimoramento recomendado é complementar os WORK_ORDER.md com um envelope de handoff estruturado, por exemplo handoff.json, contendo run_id, agent, input_refs, write_scope, expected_outputs, status, gaps_opened e evidence_refs. Essa estrutura é uma extensão natural da sua FILE_OWNERSHIP, GAP_MATRIX e EVIDENCE_LEDGER: ela transforma convenções em interface estável entre sub-agentes. fileciteturn0file0

Sub-agentes recomendados

Sub-agente	Responsabilidade principal	Entradas formais	Saídas formais	Pode escrever	Dependências permitidas
Meta Runner Orchestrator	Abrir/retomar run, distribuir waves, consolidar estado	Spec/plan, contrato do projeto, estado da run	Run docs, work orders, prompts, status	Somente artefatos de run	Nenhuma dependência de app
Context Scout	Mapear código, docs, risco e arquivos relevantes	Context pack, spec ativa	Mapa de arquivos e riscos	Não	Leitura ampla, sem build
Dependency Cartographer	Validar manifests, módulos, geradores e ordem de build	Context pack, manifests, lockfiles	Dependency graph, lock policy, build order	Somente docs/build metadata autorizados	Manifests e tooling
Spec Architect	Refinar spec sem implementar	Spec base, gaps, contratos	Spec aprovada e critérios observáveis	Somente specs/docs	Sem dependência de app
Contract Steward	Materializar/validar OpenAPI, AsyncAPI, JSON Schema, codegen	Spec aprovada, contratos existentes	Contratos versionados, artefatos gerados	Contratos e gerados	Geradores oficiais בלבד
Engineer	Implementar apenas slices aprovadas	Work order, ownership, grafo e contratos	Código, testes, docs do slice	Somente paths do slice	Apenas dependências públicas aprovadas
Reviewer	Comparar diff com spec e regras	Diff, traceability, contrato	Findings por severidade	Não	Leitura de diff e docs
Test Auditor	Mapear critérios e validações	Spec, task graph, test plan	Cobertura mínima e evidência esperada	Não	Suites e comandos
Security Auditor	Validar secrets, paths protegidos, permissões e supply chain	Diff, workflow, manifests	Findings de segurança	Não	Workflow, manifests, SBOM

Essa organização alinha muito bem com as capacidades das ferramentas oficiais. Em OpenAPI e AsyncAPI, a existência de contrato primário e partes reutilizáveis favorece a separação entre contract steward e engineer; em Gradle, npm e PyPA, a centralização de coordenadas, locks e metadata dá base concreta ao papel do dependency cartographer; e em GitHub Actions, reusable workflows, inputs, matrix e artifacts formam a infraestrutura ideal para materializar evidências e gates por wave. citeturn11view0turn11view5turn10view1turn10view2turn8view1turn8view2turn9view0turn9view1turn7view6turn7view7turn7view8

O isolamento de dependências deve ser aplicado em quatro níveis. Primeiro, isolamento de escrita, que o seu fluxo já possui por FILE_OWNERSHIP. Segundo, isolamento de manifest, em que apenas o agente/dono do slice pode alterar o manifest daquele módulo, nunca o repositório inteiro sem work order explícita. Terceiro, isolamento de build, em que gerados só podem ser alterados via gerador oficial. Quarto, isolamento de pipeline, em que cada wave publica seu resultado como artefato, com permissões mínimas e sem segredos em texto claro. Isso amplia, sem contradizer, a constituição que você já enviou. fileciteturn0file0 citeturn16view2turn16view3turn7view8

Mudanças concretas em setup e build

Abaixo está a parte mais aplicável da proposta: como tornar o fluxo realmente DRY, dependency-first e spec-driven em ambientes Node.js, Python e Java/Gradle. A ideia é manter uma camada comum de orquestração e variar apenas os manifests e tasks específicos de stack. Isso evita tanto o erro de overfitting numa linguagem quanto o antipadrão de manter três pipelines conceitualmente distintos para a mesma metodologia. citeturn8view1turn9view1turn10view2turn7view6

Camada comum de orquestração

Uma camada comum simples e poderosa é um Makefile raiz que normalize nomes de tarefas. O objetivo não é substituir npm, pip ou Gradle, mas dar ao fluxo SDD um vocabulário único: sdd-spec-lint, sdd-contracts, sdd-build, sdd-test, sdd-evidence, sdd-sbom.

SHELL := /usr/bin/env bash

.PHONY: sdd-spec-lint sdd-contracts sdd-build sdd-test sdd-evidence sdd-sbom

sdd-spec-lint:
	@echo "Lintando specs e contratos..."
	@if [ -f package.json ]; then npm run spec:lint; fi
	@if [ -f pyproject.toml ]; then python -m pytest -q tests/spec || true; fi
	@if [ -f gradlew ]; then ./gradlew contractCheck || true; fi

sdd-contracts:
	@echo "Gerando/validando contratos..."
	@if [ -f package.json ]; then npm run contracts:generate; fi
	@if [ -f pyproject.toml ]; then python scripts/contracts_generate.py; fi
	@if [ -f gradlew ]; then ./gradlew openApiGenerate; fi

sdd-build:
	@if [ -f package.json ]; then npm run build; fi
	@if [ -f pyproject.toml ]; then python -m build; fi
	@if [ -f gradlew ]; then ./gradlew build; fi

sdd-test:
	@if [ -f package.json ]; then npm run test:ci; fi
	@if [ -f pyproject.toml ]; then python -m pytest; fi
	@if [ -f gradlew ]; then ./gradlew test; fi

sdd-evidence:
	@mkdir -p docs/sdd/reviews docs/sdd/handoffs .artifacts
	@echo "Colete aqui relatórios, traces e resumos sanitizados."

sdd-sbom:
	@echo "Gerar SBOM via ferramenta da stack escolhida."

A lógica por trás desse Makefile é DRY: os nomes canônicos do fluxo ficam em um lugar, enquanto a implementação concreta continua na toolchain da stack. Isso reduz duplicação de comandos entre PROJECT_CONTRACT.md, CI, README e work orders. A orientação é coerente com a formulação original do DRY aplicada inclusive a builds e scripts, e também com o seu PROJECT_CONTRACT, que já prevê comandos canônicos por propósito. citeturn12search1 fileciteturn0file0

Node.js e npm

No ecossistema Node, a atualização principal é modularizar por workspaces, fixar a árvore com package-lock.json, centralizar scripts e usar overrides apenas como mecanismo explícito de patch/controle, nunca como gambiarra invisível. npm documenta que workspaces administram múltiplos pacotes a partir de um pacote-raiz e automatizam o linking local; documenta também que package-lock.json descreve a árvore exata e deve ser commitado para garantir instalações idênticas. citeturn8view1turn8view2turn8view3

{
  "name": "acme-sdd-root",
  "private": true,
  "packageManager": "npm@11.18.0",
  "workspaces": ["packages/*", "services/*"],
  "scripts": {
    "spec:lint": "node ./tools/spec-lint.mjs",
    "contracts:generate": "node ./tools/contracts-generate.mjs",
    "build": "npm run -ws build",
    "test:unit": "npm run -ws test:unit --if-present",
    "test:contract": "npm run -ws test:contract --if-present",
    "test:ci": "npm run test:unit && npm run test:contract",
    "sdd:verify": "npm run spec:lint && npm run contracts:generate && npm run test:ci"
  },
  "overrides": {
    "vulnerable-dep": "1.2.3"
  }
}

# .npmrc
foreground-scripts=true
engine-strict=true

O foreground-scripts=true é uma escolha pragmática quando você tem pacotes interdependentes, porque o npm registra que scripts prepare em workspaces podem rodar concorrentemente; isso é ótimo para velocidade, mas perigoso para pipelines que dependem de ordem estável. Quando a ordem entre pacotes importa, é melhor serializar o comportamento ou reformular o build para não depender desse acoplamento implícito. citeturn8view7

Uma estrutura de pacote alinhada ao fluxo proposto ficaria assim:

packages/
  contracts/
  domain/
  application/
  adapters-http/
  adapters-queue/
services/
  api/
tools/
  spec-lint.mjs
  contracts-generate.mjs

O ponto-chave é que contracts/ e domain/ não devem depender de adapters-*; a composição acontece em application/ ou services/api/. Isso é dependency-first em forma de árvore de pacote, e não apenas princípio abstrato. A própria semântica de workspaces e linking local torna esse desenho especialmente adequado para sub-agentes independentes. citeturn8view1turn8view5

Python com pyproject.toml

No ecossistema Python, a atualização mais importante é mover o centro de gravidade de setup.py/arquivos soltos para pyproject.toml. O guia da PyPA recomenda que novos projetos usem a tabela [project] e mantenham setup.py apenas quando houver necessidade programática específica; também estabelece que [build-system] deve estar sempre presente. Além disso, a especificação de Dependency Groups já permite separar grupos como test e docs, embora a interface de instalação continue dependente da ferramenta. citeturn9view0turn9view1turn9view2turn9view3

[build-system]
requires = ["setuptools>=77.0.3"]
build-backend = "setuptools.build_meta"

[project]
name = "acme-sdd"
version = "0.1.0"
description = "Projeto com fluxo spec-driven"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
  "pydantic>=2.8,<3",
  "fastapi>=0.116,<1"
]

[project.optional-dependencies]
test = [
  "pytest>=8,<9",
  "pytest-cov>=5,<6"
]
contract = [
  "jsonschema>=4.23,<5"
]

[dependency-groups]
docs = ["mkdocs>=1.6,<2"]
dev = ["ruff>=0.6,<1", "mypy>=1.11,<2"]

Essa escolha resolve três problemas de uma vez. Primeiro, concentra metadata e dependências do projeto em um ponto autoritativo. Segundo, separa dependências opcionais de tooling e docs. Terceiro, reduz a tendência de espalhar configuração por requirements.txt, setup.cfg, setup.py, tox.ini e arquivos avulsos sem ownership claro. Ainda assim, para compatibilidade ampla, vale manter extras em [project.optional-dependencies]; os dependency groups são excelentes para organização local e tooling, mas a própria especificação deixa claro que eles não fazem parte da interface de instalação padronizada de pacotes construídos. citeturn9view1turn9view3

Para ações de dependency-first, uma prática útil é explicitar restrições cedo quando o resolvedor começar a retroceder demais. A documentação do pip explica que o backtracking ocorre quando várias versões precisam ser tentadas e recomenda adicionar constraints para reduzir o espaço de busca. Isso é útil no fluxo SDD porque evita que um engenheiro “descubra em runtime” um desacordo que o dependency cartographer poderia ter bloqueado antes. citeturn9view5turn9view6

python -m pip install -e ".[test,contract]"
python -m pytest
python -m build

Java com Gradle

No mundo Java, a melhor atualização é usar uma estrutura multi-módulo com settings.gradle.kts, libs.versions.toml, dependency locking e suites de teste separadas por propósito. O Gradle documenta explicitamente que projetos maiores costumam ser quebrados em módulos menores, focados e logicamente isolados; também mostra que settings.gradle(.kts) é o lugar para declarar os subprojetos; e recomenda locking para builds reproduzíveis. citeturn10view4turn10view5turn10view1

// settings.gradle.kts
rootProject.name = "acme-sdd"
include("contracts:api", "domain", "application", "adapters:http", "service")

# gradle/libs.versions.toml
[versions]
spring = "6.2.12"
junit = "5.12.0"

[libraries]
spring-web = { module = "org.springframework:spring-web", version.ref = "spring" }
junit-bom = { module = "org.junit:junit-bom", version.ref = "junit" }

// build.gradle.kts
plugins {
    java
    `jvm-test-suite`
}

dependencyLocking {
    lockAllConfigurations()
}

subprojects {
    repositories {
        mavenCentral()
    }
}

testing {
    suites {
        val test by getting(JvmTestSuite::class) {
            useJUnitJupiter()
        }

        register<JvmTestSuite>("integrationTest") {
            useJUnitJupiter()
            dependencies {
                implementation(project())
            }
        }
    }
}

Esse trio faz muita diferença. libs.versions.toml centraliza coordenadas e versões; o próprio Gradle destaca como vantagens os accessors tipados, a visibilidade global no build e a separação entre coordenadas e versões. Ao mesmo tempo, ele avisa que version catalogs não impõem versões sozinhos; por isso, em um fluxo dependency-first, os catalogs devem vir acompanhados de locking, constraints ou plataformas conforme o caso. E o jvm-test-suite permite separar unitário de integração com dependências e requisitos distintos, o que casa perfeitamente com critérios de aceitação rastreáveis do SDD. citeturn10view2turn10view3turn10view7

CI/CD com reusable workflows, matrix e artifacts

Independentemente da stack, a sua CI deveria refletir a mesma decomposição que a run SDD usa. GitHub documenta reusable workflows com workflow_call, entradas e segredos definidos formalmente, execução por matriz e publicação de artefatos; também recomenda privilégios mínimos e GITHUB_TOKEN com permissão padrão de leitura para conteúdos do repositório. citeturn7view6turn7view7turn7view8turn16view2turn16view3

# .github/workflows/sdd-verify.yml
name: sdd-verify

on:
  workflow_call:
    inputs:
      stack:
        required: true
        type: string
    secrets: {}

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        phase: [spec, contracts, build, test]
    steps:
      - uses: actions/checkout@v4

      - name: Run phase
        shell: bash
        run: |
          case "${{ matrix.phase }}" in
            spec) make sdd-spec-lint ;;
            contracts) make sdd-contracts ;;
            build) make sdd-build ;;
            test) make sdd-test ;;
          esac

      - name: Upload evidence
        uses: actions/upload-artifact@v4
        with:
          name: "evidence-${{ inputs.stack }}-${{ matrix.phase }}"
          path: |
            docs/sdd/reviews/**
            docs/sdd/handoffs/**
            .artifacts/**

E o chamador fica pequeno:

# .github/workflows/ci.yml
name: ci

on:
  pull_request:
  push:
    branches: [main]

jobs:
  node:
    uses: ./.github/workflows/sdd-verify.yml
    with:
      stack: node

  python:
    uses: ./.github/workflows/sdd-verify.yml
    with:
      stack: python

  java:
    uses: ./.github/workflows/sdd-verify.yml
    with:
      stack: java

Se você quiser elevar o nível de governança da cadeia de dependências, vale acrescentar geração de SBOM como artefato do pipeline. CycloneDX se apresenta como padrão BOM/SBOM voltado a capacidades avançadas de supply chain e redução de risco, o que harmoniza bem com a existência de EVIDENCE_LEDGER e com o papel do auditor de segurança. citeturn16view0turn16view1

Comparativo antes e depois

O comparativo abaixo resume a diferença entre o fluxo atual e a arquitetura recomendada.

Aspecto	Antes	Depois
Fonte de verdade	Spec aprovada + artefatos de run	Spec aprovada + contratos executáveis + manifests centrais
Dependency-first	Regra metodológica implícita	Grafo de dependências, locks e manifests auditáveis
Sub-agentes	Papéis bem definidos, mas interface majoritariamente documental	Papéis bem definidos + envelope formal de handoff e escopo de dependência
Build	Comandos canônicos descritos no contrato	Comandos canônicos + build logic modular + locks/version catalogs
Testes	Evidência e gaps já previstos	Suites por propósito e por requisito, com comandos inequívocos
CI/CD	Não formalizado no kit	Reusable workflows, matrix, artifacts, permissões mínimas, SBOM

Esse “depois” não substitui o seu kit; ele o torna mais executável e menos sujeito a deriva entre prompt, documento, código e pipeline. fileciteturn0file0 citeturn10view1turn10view2turn8view2turn7view6turn7view7turn7view8

Renomeação dos arquivos de setup e build e rationale

Como você pediu explicitamente a lógica de renomeação, a melhor prática é despromover os arquivos monolíticos de setup/build para o papel de documentação de bootstrap ou referência histórica, e promover os arquivos atômicos e canônicos para o papel de fonte operacional. Isso é muito mais alinhado ao DRY do que continuar centralizando tudo em SDD_SETUP.md e SDD_BUILD.md. O seu próprio material já indica essa decomposição ao listar PROJECT_CONTRACT, SDD_CONSTITUTION, ACTIVE_SPEC, templates, skills e agentes como peças independentes. fileciteturn0file0 fileciteturn0file1

Mapeamento recomendado para os documentos legados

Legado	Novo nome recomendado	Papel após a migração	Rationale
SDD_SETUP.md	docs/sdd/BOOTSTRAP_GUIDE.md	Guia humano de instalação/configuração	“Setup” deixa de ser fonte normativa e vira guia de adoção
SDD_BUILD.md	docs/sdd/PORTABLE_KIT_REFERENCE.md	Referência/copypasta do kit	“Build” deixa de fingir ser build executável e vira documentação de referência
Regras operacionais misturadas no legado	docs/sdd/SDD_CONSTITUTION.md	Norma do método	Fonte única para precedência, lifecycle e stop conditions
Stack/comandos misturados no legado	docs/sdd/PROJECT_CONTRACT.md	Norma do projeto	Fonte única para stack, comandos, gerados e paths protegidos
Status da spec embutido no legado	docs/sdd/ACTIVE_SPEC.md	Ponte entre sessões/runs	Fonte única do que está aprovado
Templates embutidos no legado	docs/sdd/templates/*	Artefatos gerados por run	Evita copiar/colar blocos longos em documentação

Essa renomeação é importante porque nomes importam. BOOTSTRAP_GUIDE.md comunica que o documento ensina a instalar/adotar, mas não define o estado vivo do projeto. PORTABLE_KIT_REFERENCE.md comunica que o conteúdo é um kit de referência, não o local onde a run atual vive. Já PROJECT_CONTRACT.md, SDD_CONSTITUTION.md e ACTIVE_SPEC.md recebem nomes que refletem precisamente sua autoridade semântica. Isso reduz ambiguidade para humanos e para agentes. fileciteturn0file0 fileciteturn0file1

Renomeações complementares por stack

Além dos documentos SDD, há renomeações estruturais que valem muito a pena por stack:

Situação atual	Renomeação/migração recomendada	Motivo
Python com setup.py como centro	pyproject.toml como centro; setup.py só se realmente necessário	A PyPA recomenda [project] para novos projetos e [build-system] sempre presente
Gradle com versões espalhadas em vários build.gradle	gradle/libs.versions.toml + locking	Centraliza coordenadas/versionamento e reduz duplicação
Node com scripts dispersos por pacotes sem raiz canônica	package.json raiz com workspaces e scripts SDD padronizados	Mantém topologia de monorepo e reduz drift de comandos

Isso encaixa diretamente nas recomendações oficiais atuais de PyPA, Gradle e npm. citeturn9view0turn9view1turn10view2turn8view1turn8view5

Checklists de verificação e plano de migração

Checklists de conformidade

Os checklists abaixo foram desenhados para funcionar como gates práticos. A ideia não é aumentar burocracia, e sim impedir que “conformidade SDD” vire uma percepção subjetiva. Eles derivam da sua constituição atual, do uso de contratos formais, da centralização de dependências e das práticas oficiais de CI, packaging e locking. fileciteturn0file0 citeturn11view5turn10view1turn8view2turn16view3

Checklist de DRY

• Existe uma única fonte autoritativa para cada um destes itens: spec ativa, contrato de API/evento, comandos canônicos, ownership de arquivos, paths protegidos, versões centrais e artefatos gerados. fileciteturn0file0
• Regras do projeto não estão duplicadas em AGENTS.md, CI, README e work orders com redações divergentes. fileciteturn0file0
• O contrato técnico reutiliza referências ($ref, components, traits ou equivalente) em vez de repetir schemas. citeturn11view0turn11view5
• O build não exige replicar a mesma versão em vários submódulos sem catálogo/lock central. citeturn10view2turn10view3turn8view2
• Artefatos gerados não são editados manualmente. fileciteturn0file0

Checklist de dependency-first

• Cada requirement do TASK_GRAPH possui dependências explícitas de módulo, contrato, dados e validação. fileciteturn0file0
• Existe uma política clara de lock/version catalog/lockfile para a stack usada. citeturn10view1turn8view2turn9view0
• Nenhum sub-agente implementador altera dependências fora do escopo do seu slice sem work order dedicada. fileciteturn0file0
• O contrato é validado antes do código consumidor/servidor ser considerado pronto. citeturn11view2turn11view4turn11view5
• O pipeline executa em ordem coerente com o grafo: spec/contrato → build → testes → evidência. citeturn7view6turn7view7turn7view8

Checklist de SDD/spec-driven

• ACTIVE_SPEC.md aponta para uma spec aprovada, não apenas para um plano. fileciteturn0file0
• Todo comportamento alterado no diff aponta para seção da spec e requirement na matriz de rastreabilidade. fileciteturn0file0
• Não há implementação de requisito “inventado” pelo agente. fileciteturn0file0
• Cada critério de aceitação P0/P1 possui evidência executada, bloqueada ou explicitamente não executada com justificativa. fileciteturn0file0
• A run não fecha com gap P0/P1 aberto. fileciteturn0file0

Plano de migração passo a passo

A migração abaixo assume um repositório “sem restrição de linguagem”, mas com adoção gradual. Ela foi desenhada para minimizar retrabalho e preservar compatibilidade enquanto o fluxo evolui.

Passo inicial: congelar a semântica atual. Antes de mexer em build ou CI, mova o legado para a condição de referência e estabeleça a nova autoridade documental: PROJECT_CONTRACT.md, SDD_CONSTITUTION.md e ACTIVE_SPEC.md. Isso evita que a equipe continue consultando o arquivo antigo como se fosse a verdade viva. fileciteturn0file0 fileciteturn0file1

Passo seguinte: explicitar o grafo de dependências. Identifique módulos, contratos, geradores, comandos e manifestos. Em Gradle, isso normalmente leva à adoção de multi-project + version catalog + locking; em npm, a workspaces + lockfile + scripts raiz; em Python, a pyproject.toml + extras/dependency groups + convenção clara de instalação e teste. citeturn10view4turn10view2turn10view1turn8view1turn8view2turn9view0turn9view1turn9view3

Depois: separar contrato de implementação. Se houver APIs síncronas, introduza OpenAPI; se houver eventos, AsyncAPI; se houver ambos, trate-os como artefatos irmãos ligados à mesma spec de produto. A documentação oficial de ambos reforça precisamente esse uso como documento primário/contrato comunicável e reutilizável. citeturn11view0turn11view5turn11view2turn11view4

Então: formalizar interfaces de sub-agente. Mantenha os WORK_ORDER.md, mas acrescente handoff.json por agente/wave. Esse é o momento de introduzir o dependency cartographer e de endurecer write scopes. fileciteturn0file0

Por fim: automatizar a evidência em CI. Crie um reusable workflow, com matriz por phase ou por stack, permissões mínimas, publicação de artefatos e eventual geração de SBOM. Isso transforma a auditoria da run em parte do pipeline, em vez de pós-processamento manual. citeturn7view6turn7view7turn7view8turn16view3turn16view1

Comandos e scripts de automação sugeridos

Comandos agnósticos de stack

mkdir -p docs/sdd/{specs,templates,reviews,handoffs,runs}
mkdir -p .agents/skills/sdd-meta-runner/references
mkdir -p .codex/agents
mkdir -p tools/sdd

git ls-files | grep -E 'AGENTS|SDD|workflow|package|pyproject|requirements|gradle|pom|Makefile'

Node.js

npm pkg set private=true
npm pkg set packageManager="npm@11.18.0"
npm pkg set workspaces[0]="packages/*"
npm pkg set workspaces[1]="services/*"
npm install
npm run sdd:verify

Python

python -m pip install -e ".[test,contract]"
python -m pytest
python -m build

Gradle

./gradlew projects
./gradlew dependencies --write-locks
./gradlew test
./gradlew build

Esses comandos não são “a metodologia”; eles apenas materializam a metodologia numa trilha operacional mínima por stack. O critério correto é que todos eles possam ser referenciados de forma consistente no contrato do projeto, nos work orders e no CI. citeturn8view2turn9view1turn10view1turn7view6

Sequência de adoção recomendada

Fase	Objetivo	Mudança principal	Critério de saída
Governança	Congelar autoridade documental	Renomear legado e promover arquivos canônicos	Equipe e agentes consultam só os novos arquivos normativos
Dependências	Tornar o build dependency-first	Locks, catalogs, workspaces, pyproject	Build reproduzível ou ao menos centralizado
Contratos	Tornar a spec executável	OpenAPI/AsyncAPI/JSON Schema	Spec e contrato já não divergem manualmente
Sub-agentes	Reduzir acoplamento operacional	Handoff formal + dependency cartographer	Paralelismo seguro por ownership
CI/CD	Automatizar evidência e gates	Reusable workflows, matrix, artifacts, permissões mínimas	Evidência pública/sanitizada por run ou PR
Supply chain	Fechar cadeia de dependência	SBOM e auditoria	Dependências relevantes rastreáveis por artefato

A síntese final é esta: o seu fluxo atual já tem a constituição certa; o que falta é transformar dependency-first e DRY em propriedades verificáveis do repositório e do pipeline. Se você fizer apenas uma mudança estrutural, faça esta: coloque specs, contratos, manifests e evidências sob a mesma lógica de rastreabilidade. A partir daí, os sub-agentes deixam de ser “papéis que colaboram” e passam a ser “componentes de um sistema de entrega dirigido por especificação”. fileciteturn0file0 citeturn11view0turn11view5turn10view1turn8view2turn7view8

SDD_BUILD.md

SDD Framework Build Kit

Este documento e o kit canonico para instalar um fluxo SDD em qualquer projeto. Ele deve ser copiavel, versionavel e suficiente para orientar agentes humanos e subagentes sem depender do historico do chat.

O fluxo combina Specification-Driven Development, DRY, Dependency First, KISS, SOLID, composicao em vez de heranca, arquitetura orientada a capacidades, rastreabilidade fim a fim e evidencia real. A cadeia de entrega esperada e:

approved spec -> contracts -> dependencies -> task graph -> work orders -> code -> tests -> evidence

Purpose

O Que É o Fluxo SDD

O fluxo SDD e um processo de entrega em que a especificacao aprovada governa planejamento, contratos, dependencias, implementacao, testes, auditorias e evidencias. Ele transforma uma intencao de produto em requisitos atomicos, work orders, ownership de arquivos e validacoes rastreaveis.

Problemas Que Ele Resolve

O SDD Framework resolve problemas recorrentes em entregas assistidas por agentes:

• implementacao baseada em interpretacao livre em vez de especificacao aprovada;
• drift entre requisito, plano, codigo, testes, contratos e documentacao;
• agentes editando arquivos sem ownership claro;
• duplicacao de regras em AGENTS.md, README, CI, prompts e documentos soltos;
• dependencia descoberta tarde demais, durante a implementacao;
• fechamento de tarefa baseado em suposicao, nao em evidencia real;
• handoffs perdidos no historico do chat;
• runs impossiveis de retomar com seguranca.

O framework torna cada decisao rastreavel em artefatos persistentes dentro de docs/sdd/runs/<run_id>/. O chat pode iniciar ou orientar uma execucao, mas o estado real da run vive no repositorio.

Core Principles

1. Specification first. A especificacao aprovada e a fonte primaria da verdade. PLAN_PATH, task graph e work orders derivam dela; nenhum deles substitui a spec.
2. DRY. Cada regra, versao, comando, contrato, ownership e evidencia deve ter uma fonte autoritativa. Nao duplique conhecimento editavel em varios lugares.
3. Dependency First. Antes de implementar, mapeie modulos, manifests, locks, contratos, geradores, ordem de build e validacoes.
4. KISS. Prefira o menor desenho que satisfaca a spec sem atalhos opacos.
5. SOLID. Proteja fronteiras de responsabilidade, injecao de dependencias e inversao de dependencia conforme os padroes do projeto.
6. Composition over inheritance. Reuse capacidades por composicao explicita, adapters e servicos existentes antes de criar hierarquias rigidas.
7. Capability-oriented architecture. Organize slices por capacidade de negocio e contrato observavel, nao apenas por camada tecnica.
8. Traceability always. Todo comportamento implementado precisa ligar spec, requirement, work order, arquivo, validacao e evidencia.
9. Evidence over assumption. Uma entrega so esta completa quando ha comando, diff inspecionado, teste, artefato gerado, verificacao manual registrada ou bloqueio documentado.
10. Controlled autonomy. Agentes podem descobrir, decompor, implementar e revisar, mas apenas dentro de escopo persistido.
11. Context isolation. Subagentes recebem contexto minimo, formal e persistido; eles nao dependem de memoria implicita do chat principal.
12. No invented requirements. Agentes podem registrar gaps, mas nao podem criar requisito, contrato, endpoint, campo, migracao, schema ou regra de negocio sem fonte na spec ou aprovacao explicita.

Methodological Rules

Order of Precedence

Quando houver conflito, siga esta ordem:

1. instrucao explicita do usuario no turno atual;
2. AGENTS.md;
3. docs/sdd/PROJECT_CONTRACT.md;
4. docs/sdd/SDD_CONSTITUTION.md;
5. docs/sdd/ACTIVE_SPEC.md;
6. artefatos da run em docs/sdd/runs/<run_id>/;
7. instrucao de skill ou subagente.

Input Paths

Entrada	Funcao	Pode implementar?
SPEC_PATH	inicia uma run a partir de uma especificacao aprovada	somente apos Definition of Ready
PLAN_PATH	inicia descoberta ou planejamento a partir de um plano	nao substitui spec aprovada
RUN_DIR	retoma uma run existente pelo estado persistido	somente se gates permitirem

PLAN_PATH congela um plano em PLAN_SOURCE.md e ajuda a construir a spec, mas nao autoriza implementacao por si so. Se a run nasce de PLAN_PATH, ela deve derivar ou apontar uma spec aprovada antes de qualquer edicao de codigo.

Definition of Ready

Implementacao so pode comecar quando:

• a spec aprovada esta identificada em ACTIVE_SPEC.md ou SPEC_SOURCE.md;
• todos os requisitos P0/P1 tem criterio de aceitacao observavel;
• TASK_GRAPH.md decompoe requisitos, dependencias e ordem de execucao;
• SPEC_TRACEABILITY_MATRIX.md liga spec sections a requirements;
• FILE_OWNERSHIP.md define um unico write owner por arquivo na wave;
• contratos, schemas, eventos e generated artifacts afetados estao mapeados;
• comandos canonicos de validacao estao conhecidos;
• nao ha gap P0/P1 aberto sem aceite explicito do usuario.

Definition of Done

Uma run so pode fechar quando:

• todos os P0/P1 estao completos ou bloqueados com razao objetiva;
• todo comportamento alterado tem traceabilidade ate evidencia;
• contratos, docs, schemas, eventos e generated artifacts estao consistentes;
• validacoes foram executadas, bloqueadas ou marcadas not run com justificativa;
• GAP_MATRIX.md nao tem P0/P1 aberto;
• EVIDENCE_LEDGER.md registra evidencia sanitizada;
• FINAL_REPORT.md contem resumo, arquivos, validacoes, gaps e prompt de retomada.

Dependency-First Development

Dependency First e uma regra executavel, nao apenas uma preferencia arquitetural. Antes de escrever codigo, a run deve produzir ou atualizar um mapa de dependencias.

Dependency Cartography

O mapeamento deve responder:

• quais capacidades de negocio ou modulos serao afetados;
• quais contratos publicos ou internos sao fonte de verdade;
• quais manifests e lockfiles governam versoes;
• quais geradores oficiais produzem artifacts;
• qual ordem de build/teste respeita dependencias reais;
• quais dependencias sao runtime, dev, test, docs ou contract tooling;
• quais packages, schemas, migrations, events ou clients nao podem mudar sem review.

O papel de dependency-cartographer pode ser um subagente dedicado ou uma responsabilidade formal do sdd-context-scout. Em ambos os casos, ele e read-only por padrao e deve registrar resultado no CONTEXT_PACK.md, TASK_GRAPH.md e FILE_OWNERSHIP.md.

Stack Policies

• Node.js: prefira workspaces, package-lock.json commitado, scripts raiz e overrides apenas quando documentado.
• Python: prefira pyproject.toml com [build-system], [project], dependencias opcionais e grupos de tooling quando aplicavel.
• Gradle/JVM: prefira multi-project build, libs.versions.toml, dependency locking e test suites por proposito.
• APIs sincronas: use OpenAPI ou contrato equivalente como artefato primario.
• Eventos: use AsyncAPI, JSON Schema ou contrato equivalente.
• Generated artifacts: nunca edite manualmente quando houver gerador oficial.
• Supply chain: quando o risco justificar, produza SBOM como evidencia.

DRY and Reuse Rules

O fluxo deve evitar duplicacao de conhecimento editavel.

Conhecimento	Fonte autoritativa
regras permanentes do projeto	AGENTS.md e PROJECT_CONTRACT.md
metodologia SDD	SDD_CONSTITUTION.md
spec aprovada	ACTIVE_SPEC.md e arquivo em docs/sdd/specs/
requisitos da run	TASK_GRAPH.md
rastreabilidade	SPEC_TRACEABILITY_MATRIX.md
ownership de escrita	FILE_OWNERSHIP.md
gaps	GAP_MATRIX.md
evidencia	EVIDENCE_LEDGER.md
comandos canonicos	PROJECT_CONTRACT.md e CI
generated artifacts	PROJECT_CONTRACT.md + gerador oficial

Regras:

• Se uma informacao aparece em varios documentos, um deles deve apontar para a fonte autoritativa em vez de repetir conteudo divergente.
• Contratos tecnicos devem usar $ref, components, traits ou mecanismo equivalente quando disponivel.
• Scripts e pipelines devem chamar comandos canonicos em vez de reimplementar a mesma logica em YAML, README e work orders.
• Reuse servicos, schemas, fixtures, helpers e test utilities existentes antes de criar novos.
• Novo abstraidor so e aceitavel se reduzir duplicacao real ou alinhar uma fronteira arquitetural ja existente.

Agent Governance

Subagentes nao sao assistentes genericos. Cada um e um componente de entrega com missao, permissao, leitura obrigatoria, ownership, formato de saida e criterio de parada.

Subagente	Fase	Permissao	Deve ler	Pode escrever	Saida esperada
sdd-meta-runner	all	orquestracao	contrato, constituicao, active spec, run	artefatos da run	run consistente e gates aplicados
sdd-context-scout	discovery	read-only	projeto vivo, contratos, manifests, work order	nada ou notas da run autorizadas	mapa de contexto e riscos
sdd-architect	spec/clarify	docs-only	spec, gaps, contexto, contrato	specs e gaps autorizados	spec implementavel
sdd-engineer	implementation	scoped write	work order, task graph, traceability	paths do work order	codigo/testes/docs no escopo
sdd-reviewer	review	read-only	diff, spec, traceability	findings/reviews	bugs e regressions por severidade
sdd-contract-auditor	review	read-only	contratos, schemas, generated artifacts	reviews/gaps	drift contratual
sdd-test-auditor	review	read-only	testes, ACs, comandos	reviews/gaps	cobertura e evidencia esperada
sdd-security-auditor	review	read-only	diff, protected paths, auth, manifests	reviews/gaps	riscos de seguranca

Todos os subagentes devem:

• manter relacao explicita com SPEC_TRACEABILITY_MATRIX.md;
• registrar ou solicitar evidencia para EVIDENCE_LEDGER.md;
• parar quando o escopo exigir arquivo fora do work order;
• parar quando precisarem assumir outro papel;
• parar quando a spec nao sustentar a implementacao;
• nunca reverter trabalho do usuario ou de outro agente sem ordem explicita.

Subagent Creation Rules

Todo subagente so pode ser criado ou acionado a partir de um work order persistido em:

docs/sdd/runs/<run_id>/WORK_ORDERS/

O prompt real enviado ao agente deve ser salvo antes ou no mesmo momento em:

docs/sdd/runs/<run_id>/AGENT_PROMPTS/

Cada work order deve conter:

• nome do subagente;
• missao;
• fase;
• permissoes;
• arquivos que deve ler;
• arquivos que pode escrever;
• arquivos que nao pode escrever;
• criterios de parada;
• formato de saida esperado;
• relacao com SPEC_TRACEABILITY_MATRIX.md;
• relacao com EVIDENCE_LEDGER.md;
• regra contra assumir outro papel;
• regra contra inventar requisito;
• regra contra editar fora do work order;
• regra contra reverter trabalho de usuario ou outro agente.

Agentes de auditoria (sdd-reviewer, sdd-contract-auditor, sdd-test-auditor, sdd-security-auditor) sao read-only por padrao. Eles podem propor correcoes e abrir gaps, mas nao devem implementar sem novo work order explicito e ownership atualizado.

Context Isolation Rules

Subagentes recebem apenas o contexto persistido e o escopo do work order. O orquestrador nao deve depender de frases soltas do chat para orientar agentes.

O envelope minimo de handoff e:

{
  "run_id": "<run_id>",
  "work_order_id": "WO-001",
  "agent": "sdd-engineer",
  "phase": "implementation",
  "input_refs": [
    "docs/sdd/runs/<run_id>/RUN_STATE.md",
    "docs/sdd/runs/<run_id>/TASK_GRAPH.md"
  ],
  "write_scope": ["<path>"],
  "expected_outputs": ["summary", "changed_files", "evidence_refs", "gaps_opened"],
  "status": "pending",
  "gaps_opened": [],
  "evidence_refs": []
}

Salve esse envelope como handoff.json quando a run exigir coordenacao mais formal entre agentes ou retomada por outro operador.

File Ownership Rules

• Um arquivo so pode ter um write owner por wave.
• Read-only agents podem ler arquivos permitidos, mas nao editar.
• Generated artifacts so mudam por gerador oficial.
• Arquivos protegidos exigem autorizacao explicita do usuario.
• Mudanca externa em arquivo owned exige reconciliacao antes de continuar.
• Work orders devem listar May edit e Must not edit.
• Ownership amplo como src/** so e aceitavel quando o risco for baixo e a wave nao tiver agentes paralelos escrevendo.

SDD Lifecycle

1. intake: receber SPEC_PATH, PLAN_PATH ou RUN_DIR.
2. specify: identificar ou criar a spec humana.
3. clarify: registrar ambiguidades em GAP_MATRIX.md.
4. approve: apontar a spec aprovada em ACTIVE_SPEC.md.
5. dependency-map: mapear manifests, locks, contratos, geradores e ordem.
6. plan: derivar requisitos e dependencias em TASK_GRAPH.md.
7. trace: criar SPEC_TRACEABILITY_MATRIX.md.
8. task: gerar work orders e ownership.
9. discover: rodar agentes read-only para contexto, arquitetura, contrato, testes e seguranca.
10. implement: editar somente apos Definition of Ready.
11. review: auditar diff contra spec, contrato, testes, seguranca e arquitetura.
12. verify: registrar evidencia real.
13. gap-closure: fechar ou bloquear gaps P0/P1.
14. report: fechar em FINAL_REPORT.md ou deixar retomada segura.

Run Creation

Ao receber SPEC_PATH ou PLAN_PATH:

1. valide existencia do arquivo;
2. crie run_id como YYYY-MM-DD-<source-slug>;
3. crie docs/sdd/runs/<run_id>/;
4. copie a fonte para SPEC_SOURCE.md ou PLAN_SOURCE.md;
5. crie artefatos a partir dos templates;
6. crie WORK_ORDERS/, AGENT_PROMPTS/, RESULTS/, REVIEWS/ e PATCH_NOTES/;
7. pare antes de implementar se MODE=supervised ou se Ready falhar.

Run Resume

Ao receber RUN_DIR:

1. leia RUN_STATE.md;
2. leia CONTEXT_PACK.md;
3. leia TASK_GRAPH.md;
4. leia SPEC_TRACEABILITY_MATRIX.md;
5. leia GAP_MATRIX.md;
6. siga Next Action;
7. nao ignore bloqueios registrados.

Required Repository Structure

.codex/
  agents/
    sdd-meta-runner.toml
    sdd-context-scout.toml
    sdd-architect.toml
    sdd-engineer.toml
    sdd-reviewer.toml
    sdd-contract-auditor.toml
    sdd-test-auditor.toml
    sdd-security-auditor.toml
.agents/
  skills/
    sdd-meta-runner/
      SKILL.md
      references/
        meta-runner-checklist.md
    sdd-architect/
      SKILL.md
    sdd-engineer/
      SKILL.md
    sdd-reviewer/
      SKILL.md
docs/
  sdd/
    PROJECT_CONTRACT.md
    SDD_CONSTITUTION.md
    ACTIVE_SPEC.md
    specs/
    reviews/
    handoffs/
    runs/
    templates/
      RUN_STATE_TEMPLATE.md
      SPEC_TEMPLATE.md
      CONTEXT_PACK_TEMPLATE.md
      TASK_GRAPH_TEMPLATE.md
      SPEC_TRACEABILITY_MATRIX_TEMPLATE.md
      AGENT_ROSTER_TEMPLATE.md
      FILE_OWNERSHIP_TEMPLATE.md
      GAP_MATRIX_TEMPLATE.md
      EVIDENCE_LEDGER_TEMPLATE.md
      FINAL_REPORT_TEMPLATE.md
      WORK_ORDER_TEMPLATE.md

Required Persistent Artifacts

Artifact	Purpose
RUN_STATE.md	estado atual, gates, next action e prompt de retomada
SPEC_SOURCE.md	copia congelada da spec fornecida
PLAN_SOURCE.md	copia congelada do plano fornecido
CONTEXT_PACK.md	contexto real do projeto para agentes
TASK_GRAPH.md	requisitos atomicos, dependencias e slices
SPEC_TRACEABILITY_MATRIX.md	ligacao spec -> requirement -> files -> validation -> evidence
AGENT_ROSTER.md	papeis e status dos agentes
FILE_OWNERSHIP.md	ownership por arquivo e wave
GAP_MATRIX.md	gaps, severidade, dono e status
EVIDENCE_LEDGER.md	comandos, checks e evidencias sanitizadas
WORK_ORDERS/	escopo persistido de cada subagente
AGENT_PROMPTS/	prompt real enviado a cada subagente
REVIEWS/	findings de review, contrato, teste e seguranca
FINAL_REPORT.md	fechamento ou bloqueio documentado

AGENTS.md Appendix

## SDD Meta Runner

Este projeto usa um fluxo Specification-Driven Development com runs persistidas
em `docs/sdd/runs/`.

Regras obrigatorias:

- Leia `AGENTS.md` antes de editar arquivos.
- Leia `docs/sdd/PROJECT_CONTRACT.md` antes de decidir stack, comandos,
  contratos, dependencias ou paths protegidos.
- Leia `docs/sdd/SDD_CONSTITUTION.md` antes de iniciar ou retomar uma run SDD.
- Trate a especificacao aprovada como fonte primaria.
- `PLAN_PATH` pode iniciar descoberta, mas nao substitui spec aprovada.
- Use `SPEC_PATH` para iniciar a partir de spec aprovada.
- Use `PLAN_PATH` para iniciar planejamento rastreavel.
- Use `RUN_DIR` para retomar uma run existente.
- Nao implemente sem Definition of Ready.
- Nao feche run sem Definition of Done ou bloqueio documentado.
- Mantenha `SPEC_TRACEABILITY_MATRIX.md` atualizado.
- Registre validacoes em `EVIDENCE_LEDGER.md`.
- Nao permita dois agentes escrevendo o mesmo arquivo na mesma wave.
- Salve work orders em `WORK_ORDERS/` e prompts reais em `AGENT_PROMPTS/`.
- Agentes de auditoria sao read-only por padrao.
- Nao edite segredos, dumps, logs sensiveis, caches ou paths protegidos.
- Nao faca commit, stage, push ou PR sem pedido explicito.
- Codigo estrutural deve usar nomes em Ingles.
- Comunicacao com o usuario deve seguir `PROJECT_CONTRACT.md`.

PROJECT_CONTRACT.md Template

# Project Contract

Status: draft
Owner: project-maintainer

## Project Identity

- Project name: `<project-name>`
- Domain: `<domain>`
- Primary users: `<users>`
- Default human language: Portuguese-BR
- Structural code language: English

## Stack

| Area | Tooling |
| --- | --- |
| Backend | `<framework/runtime>` |
| Frontend | `<framework/runtime>` |
| Database | `<database>` |
| Queue/cache | `<queue/cache>` |
| Package manager | `<npm/pnpm/composer/pip/gradle/etc>` |
| Runtime policy | `<docker/local/cloud/etc>` |

## Capability Boundaries

| Capability | Owns | Must not depend on | Public contract |
| --- | --- | --- | --- |
| `<capability>` | `<paths>` | `<paths/modules>` | `<contract>` |

## Dependency Policy

| Ecosystem | Manifest | Lockfile/catalog | Rule |
| --- | --- | --- | --- |
| Node.js | `package.json` | `package-lock.json` | commit lockfile |
| Python | `pyproject.toml` | `<lock/constraints>` | pin or constrain risky deps |
| Gradle | `settings.gradle.kts` | `libs.versions.toml` | use locking when available |

## Canonical Commands

| Purpose | Command |
| --- | --- |
| Install | `<command>` |
| Build | `<command>` |
| Lint | `<command>` |
| Unit tests | `<command>` |
| Integration/e2e tests | `<command>` |
| Typecheck | `<command>` |
| Generate contracts | `<command or not applicable>` |
| Generate SBOM | `<command or not applicable>` |

## Canonical References

| Area | Files |
| --- | --- |
| Architecture | `<path>` |
| API contract | `<path>` |
| Event contract | `<path>` |
| Generated docs | `<path>` |
| Test strategy | `<path>` |
| Deployment | `<path>` |

## Generated Artifacts

| Artifact | Generator | Manual edits allowed |
| --- | --- | --- |
| `<path>` | `<command>` | no |

## Protected Paths

Agents must not read, print, edit, stage or commit these paths unless the user explicitly authorizes it:

- `.env`
- `.env.*`
- `**/secrets/**`
- `**/storage/**`
- `**/logs/**`
- `**/dump/**`
- `<project-specific-sensitive-path>`

## Ownership Rules

- One write owner per file per implementation wave.
- Audit agents are read-only by default.
- Generated artifacts must be changed through the official generator.
- If a task needs a protected path, stop and ask the user.

## Quality Gates

- P0/P1 gaps must be closed before final report.
- Tests must be run or explicitly marked `blocked`/`not run` with reason.
- Contract changes require docs and generated artifacts.
- Security-sensitive changes require security review.
- Dependency changes require manifest/lock evidence.

## Definition of Ready

- Approved spec identified.
- P0/P1 gaps closed or explicitly accepted by the user.
- Requirements decomposed in `TASK_GRAPH.md`.
- Dependencies and build order mapped.
- Traceability matrix initialized.
- File ownership clear.
- Required validation commands known.

## Definition of Done

- Every P0/P1 requirement satisfied or explicitly blocked.
- Acceptance criteria mapped to evidence.
- Contracts, docs and generated artifacts consistent.
- Tests executed, blocked or marked `not run` with reason.
- `FINAL_REPORT.md` includes changed files, validations, gaps and resume prompt.

## Domain Rules

- `<rule-1>`
- `<rule-2>`

SDD_CONSTITUTION.md Template

# SDD Constitution

Status: active
Owner: project-maintainer

## Core Principles

1. Specification first.
2. Traceability always.
3. Dependency First.
4. DRY.
5. Evidence over assumption.
6. Controlled autonomy.
7. Context isolation.
8. No invented requirements.

## Lifecycle

1. `specify`
2. `clarify`
3. `approve`
4. `dependency-map`
5. `plan`
6. `task`
7. `implement`
8. `review`
9. `verify`
10. `report`

## Order of Precedence

1. Explicit user instruction in the current turn.
2. Repository `AGENTS.md`.
3. `docs/sdd/PROJECT_CONTRACT.md`.
4. This constitution.
5. Active spec and run artifacts.
6. Agent role instructions.

## Stop Conditions

Stop and record a P0/P1 gap when:

- the spec lacks a business rule, contract, data rule or acceptance criterion;
- implementation would touch a protected path;
- two agents need write ownership of the same file in the same wave;
- generated artifacts would need manual edits;
- validation commands are unknown for a risky change;
- security, authorization or sensitive data behavior is ambiguous;
- live verification is required but unavailable.

ACTIVE_SPEC.md Template

# Active SDD Spec

Status: none
Spec: none
Spec version: none
Owner: none
Approved by: none
Approved at: none
Related run: none

## Objective

No active spec.

## Approval State

- Ready for planning: no
- Ready for implementation: no
- Ready for final report: no

## Required Links

- Spec file: none
- Traceability matrix: none
- Task graph: none
- Evidence ledger: none

## Change Log

| Date | Change | Owner | Reason |
| --- | --- | --- | --- |

## Continuity Notes

- Use `SPEC_PATH` to start from an approved specification.
- Use `PLAN_PATH` to start discovery or planning.
- Use `RUN_DIR` to resume an existing run.

Skill: sdd-meta-runner

---
name: sdd-meta-runner
description: Execute approved SDD specs or plans with traceable runs, work orders, gap closure and evidence.
---

# SDD Meta Runner

Use this skill when the user provides `SPEC_PATH`, `PLAN_PATH`, `RUN_DIR`,
mentions SDD Meta Runner, or asks to execute an approved spec through agents.

## Inputs

- `SPEC_PATH="<path>"`: start from an approved specification.
- `PLAN_PATH="<path>"`: start discovery/planning, not implementation authority.
- `RUN_DIR="<path>"`: resume an existing run.
- `MODE=supervised`: default; stop before code edits.
- `MODE=auto`: may implement only after Definition of Ready.
- `MODE=plan-only`: produce run artifacts without implementation.

## Procedure

1. Read `AGENTS.md`, `PROJECT_CONTRACT.md`, `SDD_CONSTITUTION.md` and `ACTIVE_SPEC.md`.
2. Validate exactly one of `SPEC_PATH`, `PLAN_PATH` or `RUN_DIR`.
3. Create or resume `docs/sdd/runs/<run_id>/`.
4. Build `CONTEXT_PACK.md` from current repo evidence.
5. Build `TASK_GRAPH.md`, dependency map and traceability matrix.
6. Open P0/P1 gaps for ambiguity, missing contracts, unknown commands or ownership conflicts.
7. Create work orders in `WORK_ORDERS/`.
8. Save real prompts in `AGENT_PROMPTS/`.
9. Use read-only discovery and auditors before implementation.
10. Implement only after Ready.
11. Register evidence.
12. Close with `FINAL_REPORT.md` or blocked state.

## Safety Contract

- Never rely only on chat history.
- Never invent requirements.
- Never edit outside file ownership.
- Never manually edit generated artifacts.
- Never touch protected paths without explicit permission.
- Never commit, stage, push or open PR unless explicitly asked.

Skill: sdd-architect

---
name: sdd-architect
description: Create or refine SDD specifications before implementation.
---

# SDD Architect

Mission: transform ideas, plans or gaps into implementable approved specs.

Rules:

- Read `AGENTS.md`, `PROJECT_CONTRACT.md`, `SDD_CONSTITUTION.md` and `ACTIVE_SPEC.md`.
- Do not implement application code.
- Write only specs, gap notes or approved run docs.
- Make acceptance criteria observable.
- Include dependencies, contracts, generated artifacts and validation strategy.
- Stop when P0/P1 business, data, contract or security ambiguity remains.

Skill: sdd-engineer

---
name: sdd-engineer
description: Implement only approved SDD specs or scoped work orders.
---

# SDD Engineer

Mission: implement the assigned work order after Ready is satisfied.

Rules:

- Read the work order and all required run artifacts before editing.
- Write only files listed in `May edit`.
- Do not invent behavior outside the traceability matrix.
- Apply DRY, KISS, Dependency First, SOLID and composition.
- Prefer existing project abstractions and dependency injection patterns.
- Update tests, docs and contracts only when required by the spec.
- Register validations and gaps for the evidence ledger.

Skill: sdd-reviewer

---
name: sdd-reviewer
description: Review real diffs against approved SDD scope and evidence.
---

# SDD Reviewer

Mission: audit implementation against spec, task graph, ownership and gates.

Rules:

- Read spec, task graph, traceability matrix, diff and evidence ledger.
- Be read-only by default.
- Start with findings by severity.
- Check invented requirements, missing tests, contract drift, generated artifacts,
  duplication, coupling, naming and protected path risks.
- Say clearly when no relevant findings remain.

Agent Config: sdd-meta-runner

name = "sdd-meta-runner"
description = "Orchestrates SDD runs from SPEC_PATH, PLAN_PATH or RUN_DIR with persistent artifacts and gates."
model = "gpt-5.5"
model_reasoning_effort = "high"
nickname_candidates = ["Meta Runner", "SDD Orchestrator"]

developer_instructions = """
You are the SDD Meta Runner.
Read AGENTS.md, PROJECT_CONTRACT.md, SDD_CONSTITUTION.md and ACTIVE_SPEC.md.
Treat the approved spec as source of truth.
PLAN_PATH is not implementation authority.
Create work orders before subagents and save real prompts in AGENT_PROMPTS.
Maintain traceability, gaps, ownership and evidence.
Stop on missing Ready, open P0/P1 gaps, protected paths, ownership conflicts or unknown validation commands.
"""

Agent Config: sdd-context-scout

name = "sdd-context-scout"
description = "Read-only mapper for code, docs, contracts, manifests, dependencies and risks."
model = "gpt-5.5"
model_reasoning_effort = "medium"
nickname_candidates = ["Context Scout", "Dependency Cartographer"]

developer_instructions = """
You are the SDD Context Scout.
You are read-only by default.
Map real project state, architecture boundaries, dependency manifests, lockfiles, generators, protected paths and validation commands.
Do not implement code.
Return files inspected, risks, dependency graph notes and gaps.
"""

Agent Config: sdd-architect

name = "sdd-architect"
description = "Turns ideas, plans and gaps into implementable SDD specs."
model = "gpt-5.5"
model_reasoning_effort = "high"
nickname_candidates = ["SDD Architect", "Spec Architect"]

developer_instructions = """
You are the SDD Architect.
Do not implement code.
Create or refine specs with objective, scope, dependencies, contracts, acceptance criteria, test plan, Ready and Done.
Stop when P0/P1 ambiguity remains.
"""

Agent Config: sdd-engineer

name = "sdd-engineer"
description = "Implements only approved specs or scoped SDD work orders."
model = "gpt-5.5"
model_reasoning_effort = "high"
nickname_candidates = ["SDD Engineer", "Implementation Lead"]

developer_instructions = """
You are the SDD Engineer.
Read your work order before editing.
Write only authorized paths.
Do not invent requirements or edit generated artifacts manually.
Do not revert user or other-agent changes.
Return changed files, requirement mapping, validations, evidence refs and gaps.
"""

Agent Config: sdd-reviewer

name = "sdd-reviewer"
description = "Reviews real implementation diffs against approved SDD scope."
model = "gpt-5.5"
model_reasoning_effort = "high"
nickname_candidates = ["SDD Reviewer", "Spec Auditor"]

developer_instructions = """
You are the SDD Reviewer.
Read the approved spec, run artifacts and real diff.
Be read-only by default.
Prioritize findings by severity.
Verify traceability, tests, contracts, generated artifacts, naming, coupling and protected path risks.
"""

Agent Config: sdd-contract-auditor

name = "sdd-contract-auditor"
description = "Audits API, schema, event, documentation and generated artifact contracts."
model = "gpt-5.5"
model_reasoning_effort = "high"
nickname_candidates = ["Contract Auditor", "API Gatekeeper"]

developer_instructions = """
You are the SDD Contract Auditor.
You are read-only by default.
Audit OpenAPI, AsyncAPI, JSON Schema, event contracts, docs, migrations and generated artifacts.
Require official generators for generated outputs.
Open gaps for contract drift.
"""

Agent Config: sdd-test-auditor

name = "sdd-test-auditor"
description = "Audits acceptance coverage, regression risk, validation commands and evidence."
model = "gpt-5.5"
model_reasoning_effort = "high"
nickname_candidates = ["Test Auditor", "Evidence Reviewer"]

developer_instructions = """
You are the SDD Test Auditor.
You are read-only by default.
Map acceptance criteria to existing or required tests.
Distinguish passed, failed, blocked and not run.
Register expected evidence for EVIDENCE_LEDGER.
"""

Agent Config: sdd-security-auditor

name = "sdd-security-auditor"
description = "Audits security, sensitive data, authorization, protected paths and supply chain risk."
model = "gpt-5.5"
model_reasoning_effort = "high"
nickname_candidates = ["Security Auditor", "Hardening Reviewer"]

developer_instructions = """
You are the SDD Security Auditor.
You are read-only by default.
Check secrets, sensitive logs, dumps, caches, authorization, input validation, permissions, dependency changes and protected paths.
Open P0/P1 gaps for unsafe or ambiguous behavior.
"""

Templates

RUN_STATE_TEMPLATE.md

# Run State

Run ID: `<run_id>`
Status: intake
Source type: `<SPEC_PATH|PLAN_PATH|RUN_DIR>`
Source path: `<path>`
Active spec: `<path|none>`
Spec approval: `<approved|draft|blocked|none>`
Mode: `<MODE>`
Owner: sdd-meta-runner

## Current Stage

- [ ] intake
- [ ] specify
- [ ] clarify
- [ ] approve
- [ ] dependency-map
- [ ] context-pack
- [ ] task-graph
- [ ] traceability
- [ ] work-orders
- [ ] discovery
- [ ] implementation
- [ ] review
- [ ] evidence
- [ ] gap-closure
- [ ] final-report

## Decision Log

| Time | Decision | Reason | Owner |
| --- | --- | --- | --- |

## Definition of Ready

- [ ] Approved spec identified.
- [ ] P0/P1 gaps closed or accepted.
- [ ] Requirements decomposed.
- [ ] Dependencies mapped.
- [ ] Traceability initialized.
- [ ] File ownership clear.
- [ ] Validation commands known.

## Definition of Done

- [ ] P0/P1 requirements satisfied or blocked.
- [ ] Evidence mapped to acceptance criteria.
- [ ] Contracts/docs/generated artifacts consistent.
- [ ] Validations executed, blocked or not-run with reason.
- [ ] Final report written.

## Next Action

`<next atomic action>`

## Resume Prompt

```text
Utilize o meta runner com RUN_DIR="docs/sdd/runs/<run_id>"
Leia RUN_STATE.md, CONTEXT_PACK.md, TASK_GRAPH.md e GAP_MATRIX.md.
Continue a partir de "Next Action".
```

SPEC_TEMPLATE.md

# SDD Spec: `<feature-name>`

Status: draft
Version: 0.1
Owner: `<owner>`
Approved by: none
Approved at: none

## Objective

`<observable outcome>`

## Scope

- `<in scope>`

## Out of Scope

- `<out of scope>`

## Current Context

- `<existing behavior, docs, code areas and constraints>`

## Capability and Architecture Impact

| Capability | Impact | Boundary |
| --- | --- | --- |

## Dependencies

| Dependency | Type | Reason | Status |
| --- | --- | --- | --- |

## API, Events, Schemas and Generated Artifacts

| Contract/artifact | Change | Generator | Compatibility risk |
| --- | --- | --- | --- |

## Acceptance Criteria

| ID | Criteria | Priority | Validation |
| --- | --- | --- | --- |
| AC-001 | `<observable criteria>` | P1 | `<command/check>` |

## Test Plan

| Layer | Required validation | Command |
| --- | --- | --- |

## Risks and Open Questions

| ID | Severity | Question or risk | Owner | Status |
| --- | --- | --- | --- | --- |

## Definition of Ready

- [ ] No open P0/P1 question.
- [ ] Acceptance criteria observable.
- [ ] Dependencies and contracts explicit.
- [ ] Required validations known.
- [ ] Generated artifacts and protected paths mapped.

## Definition of Done

- [ ] P0/P1 ACs satisfied or blocked with reason.
- [ ] Evidence linked to each AC.
- [ ] Docs/contracts/generated artifacts updated when required.
- [ ] Remaining gaps documented.

CONTEXT_PACK_TEMPLATE.md

# Context Pack

Run ID: `<run_id>`
Source path: `<path>`
Active spec: `<path|none>`

## Project Rules

| Source | Key rules |
| --- | --- |
| `AGENTS.md` | `<summary>` |
| `PROJECT_CONTRACT.md` | `<summary>` |
| `SDD_CONSTITUTION.md` | `<summary>` |

## Dependency Map

| Area | Manifest/contract | Lock/generator | Notes |
| --- | --- | --- | --- |

## Relevant Files

| Area | Files | Reason |
| --- | --- | --- |

## Protected Paths

- `<path>`

## Validation Commands

| Purpose | Command | Known? |
| --- | --- | --- |

## Open Questions

- `<question>`

TASK_GRAPH_TEMPLATE.md

# Task Graph

Run ID: `<run_id>`
Source spec: `<path>`

## Requirements

| ID | Requirement | Source section | Priority | Status | Acceptance |
| --- | --- | --- | --- | --- | --- |
| REQ-001 | `<description>` | `<section>` | P1 | pending | AC-001 |

## Dependency Graph

| Requirement | Depends on | Blocks | Notes |
| --- | --- | --- | --- |

## Work Slices

| Slice | Requirements | Suggested agent | Write ownership | Parallel safe |
| --- | --- | --- | --- | --- |

## Readiness Checks

- [ ] Every P0/P1 has acceptance criteria.
- [ ] Every P0/P1 has validation type.
- [ ] Every slice has ownership.
- [ ] Open gaps are in `GAP_MATRIX.md`.

SPEC_TRACEABILITY_MATRIX_TEMPLATE.md

# Spec Traceability Matrix

Run ID: `<run_id>`
Source spec: `<path>`

| Spec Section | Requirement | Work Order | Files | Validation | Evidence | Gap |
| --- | --- | --- | --- | --- | --- | --- |
| `<section>` | REQ-001 | WO-001 | `<path>` | `<command/check>` | EVD-001 | none |

## Orphan Checks

- [ ] No P0/P1 spec section without requirement.
- [ ] No P0/P1 requirement without AC.
- [ ] No changed behavior without requirement.
- [ ] No validation claim without evidence.

AGENT_ROSTER_TEMPLATE.md

# Agent Roster

Run ID: `<run_id>`

| Agent | Mission | Phase | Permission | Writes allowed | Status |
| --- | --- | --- | --- | --- | --- |
| sdd-meta-runner | orchestrate run | all | run docs | run artifacts | active |
| sdd-context-scout | map context/dependencies | discovery | read-only | no | pending |
| sdd-architect | refine spec/gaps | clarify | docs-only | specs/gaps | pending |
| sdd-engineer | implement scope | implementation | scoped write | work order paths | pending |
| sdd-reviewer | review diff | review | read-only | no | pending |
| sdd-contract-auditor | audit contracts | review | read-only | no | pending |
| sdd-test-auditor | audit tests/evidence | review | read-only | no | pending |
| sdd-security-auditor | audit security | review | read-only | no | pending |

FILE_OWNERSHIP_TEMPLATE.md

# File Ownership

Run ID: `<run_id>`

| Path | Write Owner | Wave | Reason | Status |
| --- | --- | --- | --- | --- |
| `<path>` | `<agent>` | implementation-1 | `<reason>` | planned |

## Rules

- One write owner per file per wave.
- Audit agents are read-only.
- Generated artifacts require official generator.
- Protected paths require explicit authorization.
- Unexpected external changes must be reconciled before edit.

GAP_MATRIX_TEMPLATE.md

# Gap Matrix

Run ID: `<run_id>`

| Gap ID | Requirement | Severity | Category | Description | Owner | Status | Evidence |
| --- | --- | --- | --- | --- | --- | --- | --- |
| GAP-001 | REQ-001 | P1 | tests | `<description>` | sdd-test-auditor | open | `<link>` |

## Severity

- P0: blocks execution or critical safety/security/contract risk.
- P1: incomplete essential requirement or likely regression.
- P2: important but not blocking.
- P3: cleanup or optional improvement.

## Closure Rule

The run cannot be finalized with open P0 or P1 gaps.

EVIDENCE_LEDGER_TEMPLATE.md

# Evidence Ledger

Run ID: `<run_id>`

| Evidence ID | Time | Requirement | Command or Check | Environment | Result | Artifact | Sanitized | Notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| EVD-001 | `<YYYY-MM-DD HH:mm>` | REQ-001 | `<command/check>` | `<local/docker/ci>` | pending | `<path>` | yes | `<notes>` |

## Result Values

- `pending`
- `passed`
- `failed`
- `blocked`
- `not run`

## Policy

- Register real commands and checks.
- Do not paste secrets or sensitive logs.
- Link artifacts instead of copying large raw output.

FINAL_REPORT_TEMPLATE.md

# Final Report

Run ID: `<run_id>`
Source path: `<SPEC_PATH|PLAN_PATH>`
Active spec: `<path|none>`
Status: `<complete|blocked|partial>`

## Summary

`<summary>`

## Requirements

| Requirement | Status | Evidence |
| --- | --- | --- |

## Traceability

| Spec Section | Requirement | Files | Evidence | Gap |
| --- | --- | --- | --- | --- |

## Files Changed

- `<path>`

## Validations

| Command or Check | Result |
| --- | --- |

## Remaining Gaps

| Gap | Severity | Reason |
| --- | --- | --- |

## Resume Prompt

```text
Utilize o meta runner com RUN_DIR="docs/sdd/runs/<run_id>"
Continue a partir de RUN_STATE.md.
```

WORK_ORDER_TEMPLATE.md

# Work Order

Work Order ID: `<WO-ID>`
Run ID: `<run_id>`
Assigned agent: `<agent-name>`
Mission: `<mission>`
Phase: `<phase>`
Status: pending
Source requirement: `<REQ-ID>`
Source spec section: `<section>`

## Identity Lock

You are `<agent-name>`.
Do not assume another role.

## Required Reading

1. `AGENTS.md`
2. `docs/sdd/PROJECT_CONTRACT.md`
3. `docs/sdd/SDD_CONSTITUTION.md`
4. `docs/sdd/runs/<run_id>/RUN_STATE.md`
5. `docs/sdd/runs/<run_id>/CONTEXT_PACK.md`
6. `docs/sdd/runs/<run_id>/TASK_GRAPH.md`
7. `docs/sdd/runs/<run_id>/SPEC_TRACEABILITY_MATRIX.md`
8. This work order

## Permissions

- May read: `<paths>`
- May write: `<paths or none>`
- Must not write: `<paths>`

## Traceability

| Requirement | Acceptance Criteria | Required Evidence |
| --- | --- | --- |

## Scope

In scope:

- `<item>`

Out of scope:

- `<item>`

## Validation Plan

| Command or Check | Required | Blocking |
| --- | --- | --- |

## Stop Conditions

- Scope requires a file outside ownership.
- Spec or acceptance criteria are ambiguous.
- Requirement is not in traceability matrix.
- Protected path, secret, dump or sensitive log is needed.
- Generated artifact would require manual edit.
- Validation command is missing for risky change.
- User or another agent changed an owned file unexpectedly.

## Output Format

- Summary
- Files inspected
- Files changed, if allowed
- Traceability updates needed
- Evidence refs
- Gaps opened
- Suggested next work order

Operational Examples

Start from approved spec:

Utilize o meta runner com SPEC_PATH="docs/sdd/specs/minha-feature.md" MODE=supervised

Start discovery from a plan:

Utilize o meta runner com PLAN_PATH="docs/plans/minha-sprint.md" MODE=supervised

Allow auto implementation only after gates:

Utilize o meta runner com SPEC_PATH="docs/sdd/specs/minha-feature.md" MODE=auto

Resume:

Utilize o meta runner com RUN_DIR="docs/sdd/runs/YYYY-MM-DD-minha-feature"
Leia RUN_STATE.md, CONTEXT_PACK.md, TASK_GRAPH.md e GAP_MATRIX.md.
Continue a partir de "Next Action".

Final Quality Gates

Antes de declarar conclusao:

• ACTIVE_SPEC.md aponta para uma spec aprovada ou a run esta bloqueada.
• TASK_GRAPH.md contem todos os P0/P1 da spec.
• SPEC_TRACEABILITY_MATRIX.md nao tem orfaos P0/P1.
• FILE_OWNERSHIP.md nao mostra conflito de escrita.
• GAP_MATRIX.md nao tem P0/P1 aberto.
• EVIDENCE_LEDGER.md registra evidencias reais, bloqueadas ou not-run com razao.
• Contratos, schemas, eventos, docs e generated artifacts estao consistentes.
• Dependencias e locks foram atualizados quando necessario.
• Auditores read-only revisaram contrato, testes e seguranca quando o risco exigir.
• FINAL_REPORT.md contem resumo, arquivos alterados, validacoes, gaps e prompt de retomada.