Framework de engenharia de produto para agentes de IA
O Spec Framework é um método — e um CLI — que faz produto, especificação, planejamento, execução e auditoria funcionarem como um único pipeline rastreável, em vez de pedir a uma IA para "implementar uma feature" a partir de contexto solto. Cada mudança nasce de um problema real e chega ao código com rastreabilidade completa. O contrato canônico está em FRAMEWORK.md.
Método
Execução
design.md verificável — origem, maturidade, fontes visuais, Design System e UX Review.
Arquitetura
Fluxo de Engenharia
O Engineering System compartilhado e a dupla Proposal + Review: a solução técnica é descrita e revisada antes do plano.
Operação
Da task à entrega
O caminho operacional completo: Execution Scheduler, Delivery Orchestrator, leases, integração e release.
Prática
init ao validate: como operar o método sem depender de execução automática de agentes.
Escolha o comando do seu sistema operacional. Ele baixa e verifica a versão mais recente da CLI. Nenhum projeto será criado durante a instalação.
Windows (PowerShell)
irm https://raw.githubusercontent.com/JonatasFreireDev/spec-framework/master/scripts/install.ps1 | iexLinux / macOS
curl -fsSL https://raw.githubusercontent.com/JonatasFreireDev/spec-framework/master/scripts/install.sh | shDepois de instalar, execute spec-framework init somente no projeto que deseja preparar.
Execute o comando abaixo e responda às perguntas do wizard. Ele ajudará você a escolher a opção que melhor representa o que existe hoje.
spec-framework init ../meu-produtoO ponto de partida define como o produto entra no framework. Ele não aprova documentos automaticamente e não remove validações das etapas seguintes. Consulte a referência de starting points e o mapa modular de artifacts para ver a composição inicial.
Use quando ainda não existe um produto operando nem uma entrega bem delimitada. Você começará esclarecendo o problema, a visão e a estratégia antes de criar features.
Exemplo: uma equipe quer criar uma plataforma para nutricionistas e pacientes, mas ainda precisa definir o público, o problema principal, a experiência e as métricas de sucesso.
Atenção: uma ideia, pesquisa ou oportunidade inicial ajuda a escrever a fundação, mas não substitui sua revisão e aprovação.
Use quando o produto está em produção e há evidências como releases, métricas, suporte ou clientes. Primeiro registre a realidade atual; depois defina a direção futura.
Exemplo: um SaaS com clientes e releases frequentes, mas sem uma descrição confiável do público atual, das capacidades existentes e da estratégia.
Atenção: escolha esta opção pela existência de um produto em operação, não apenas porque existe um repositório com código.
Use para protótipos, projetos legados ou repositórios herdados sem evidência clara de operação. O código será analisado como evidência, não como verdade aprovada.
Exemplo: um repositório com backend, telas e banco de dados, mas sem certeza de lançamento, público ou comportamentos intencionais.
Atenção: o assessment registra o que o código demonstra e também o que não pode ser concluído a partir dele.
Use quando os documentos são a principal fonte disponível. A CLI cria um inventário e um mapeamento para revisão. Nada vira verdade do produto automaticamente.
Exemplo: visão e estratégia no Confluence, epics e critérios de aceitação no Jira, ou uma pasta com PRDs e documentos de arquitetura.
Atenção: uma epic nem sempre representa uma Feature e uma story nem sempre representa um Use Case. O mapeamento precisa de revisão humana.
Use quando o problema, o resultado esperado e os limites da entrega já estão claros. Esse caminho evita reconstruir toda a estratégia para uma mudança realmente proporcional.
Exemplo: adicionar pagamento via PIX ao checkout, com escopo, integração e métrica de sucesso conhecidos.
Atenção: não use quando a mudança envolve vários domínios, novo modelo de negócio ou uma alteração ampla de público e estratégia.
Use para diagnóstico ou consultoria sem autorização de escrita. Aprovações, imports, workspaces, movimentos e outras alterações ficam bloqueados.
Exemplo: uma avaliação de documentação, decisões, segurança e evidências de QA antes de autorizar qualquer mudança no produto.
Atenção: continuar dos achados para trabalho de produto exige uma mudança explícita do ponto de partida.
Depois do init, o arquivo product/BOOTSTRAP.md explica o caminho escolhido para o seu produto. Leia esse arquivo antes de preencher documentos ou executar outros comandos.
Se você não souber qual é o próximo passo, pergunte ao Framework Guide depois de ler o Bootstrap. Ele consulta o estado real do repositório antes de orientar.
Em vez de o agente decidir sozinho o que construir, tudo passa por uma cadeia explícita — do Problema à Tarefa — onde cada elo só existe porque o anterior o justifica. Cada caso de uso vira uma Especificação antes de qualquer linha de código, e toda a árvore vive num diretório product/ versionado como um grafo de conhecimento: estado, decisões e histórico navegáveis por máquina, não só uma pasta de documentos soltos.
Toda decisão técnica precisa manter rastreabilidade até uma necessidade real de produto.
Histórias de usuário servem para comunicação; quem governa a implementação é a Especificação.
Agentes propõem; mudanças de escopo, arquitetura, risco ou compromisso passam por aprovação humana explícita.
Cada artefato tem id, pais, filhos, dependências e consumidores — navegável por máquina, não só por humano.
Os treze elos da cadeia, na ordem em que um deriva do outro. Nenhum nasce sem o anterior.
Define a dor, a oportunidade e o contexto de mercado. É a raiz de justificativa do produto.
Define o produto que se quer construir, para quem, por que agora e quais princípios guiam as decisões.
Define posicionamento, segmentos, métricas, trade-offs, roadmap e critérios para avançar ou pausar.
Agrupa uma área coerente do negócio, como users, events ou payments. É o centro da documentação funcional — não existe pasta global de features.
O objetivo estável do usuário dentro de um domínio: "entrar em um evento", "encontrar pessoas". Substitui a noção genérica de "capacidade".
Solução concreta que atende a um objetivo. Features podem entrar, sair, evoluir, ser fatiadas ou substituídas.
Interação verificável da feature — o ponto onde produto e engenharia se encontram para gerar uma Especificação implementável.
Fonte de verdade para implementação: produto, fluxo, UI, APIs, dados, permissões, analytics, segurança, acessibilidade, erros, edge cases, observabilidade e aceite.
Traduz a Especificação em experiência verificável. Sem interface, usa o status estruturado not_applicable com justificativa real. Página própria →
A solução técnica pretendida, descrita e revisada de forma independente antes do plano — obrigatória em Tier L. Página própria →
Estratégia técnica: sequenciamento, fases, dependências, riscos, fatias, migrações, testes e rollout — sem escrever código.
As tarefas como um DAG: cada nó é uma unidade executável com dependências explícitas e um path para seu arquivo canônico.
Unidade executável derivada da Especificação e do Grafo — pequena o bastante para implementar, testar, revisar e reverter. Vive em arquivo próprio; tasks.md é só índice.
S — baixo risco: especificação, tasks e testes. M — fluxo normal: soma design, plano e grafo. L — crítico: soma Engineering Proposal + Review, analytics, auditoria, QA Evidence e Security Review. Auth, permissões, pagamento, PII, upload ou UGC disparam Tier L automaticamente; S e M sobem de exigência quando há um engineering_trigger estruturado.
Todo artefato com pasta própria declara slug imutável em context.md. IDs são únicos dentro do escopo do pai; mover um artefato exige spec-framework move, que reescreve links mecânicos e reporta menções em texto livre.
Produtos com fundações recorrentes podem declarar um Design System (tokens, componentes, padrões) e um Engineering System (arquitetura, ownership, qualidade) — ambos versionados, pinados por entrega e incapazes de aprovar qualquer coisa sozinhos. Veja os contratos de Engineering Systems e lifecycle e aprovações.
Mudanças de arquitetura, regra de negócio, segurança, permissões ou estratégia difícil de reverter viram registros DEC-* indexados em .product/decisions.json. Decisões de design ficam em design/decisions/, de engenharia em engineering/decisions/, e as transversais em knowledge/decisions/ — prosa de decisão nunca é executável.
Para CI e auditoria, use spec-framework decisions check --strict; --json gera findings estruturados e --fix-links apenas altera links mecanicamente resolvíveis quando combinado com --yes.
Um produto amadurece subindo degraus: cada nível só faz sentido apoiado no anterior. Um L5 brilhante em cima de um L1 que não fecha é um produto que não existe.
Crescimento, experimentos, personalização e otimização.
Operação, suporte, observabilidade, admin e escala.
Confiança, segurança, privacidade, moderação, acessibilidade.
Ciclo principal que gera valor recorrente para o usuário.
Menor fluxo ponta a ponta que prova o valor central.
Base sem a qual o produto ou o pipeline não sustentam entregas seguras.
Delivery Level não é promessa de data. Ele responde apenas "quando isto precisa existir", nunca "quando será entregue".
Priority só se compara dentro do mesmo nível. Um L3/P0 pode ser crítico para confiança, mas ainda não passa na frente de um L1 que fecha o walking skeleton.
Dependência pode puxar uma entrega para um nível anterior — desde que a rationale explique o porquê, campo obrigatório em Domínio, Objetivo, Feature, Caso de Uso, Especificação, Plano, Grafo e Tarefa.
Mudar level ou priority altera compromisso de entrega e precisa passar por um gate de aprovação — não é um campo livre para o agente reescrever.
Cada skill declara uma única responsibility, lê o AGENTS.framework.md, FRAMEWORK.md, os context.md relevantes e as decisões aprovadas antes de agir, e para diante de aprovação humana pendente, conflito ou limite de tentativas. Todas operam nos mesmos quatro modos:
Estabelecem por que o produto existe — antes de qualquer domínio ou feature.
Transformam objetivos de usuário em features, casos de uso e experiência verificável.
Convertem intenção em contratos: especificação, solução técnica, plano e DAG de tarefas.
engineering-system.md + .yaml): arquitetura estável, ownership de módulos e dados, padrões e qualidade.Implementam e verificam — cada verificador é independente de quem produziu o que ele verifica.
Analisam e reportam; não criam conteúdo de produto por padrão.
Camada de governança: controlam fluxo, ordem, gates e handoffs — nunca autoram artefato de especialista nem executam comando.
Design não é "fazer uma tela bonita" — é traduzir a Especificação aprovada numa experiência verificável, com origem e maturidade explícitas, fontes rastreadas por versão, e revisão independente antes do gate humano. Quando o caso de uso não tem interface, design.md ainda existe: registra Not applicable com a justificativa.
origin_mode — de onde vem
generate→criada do zero a partir da Especificaçãoevolve→uma interface existente é intencionalmente alteradaadopt→fonte externa versionada é autoritativa (Figma, Penpot, imagens)maturity — quão pronto está
contract→descrição textual dos estados e regras — o mínimo compatívelwireframe→estrutura de layout sem estilo finalmockup→visual quase final, ainda não interativoprototype→navegável, simula a experiência realUma fonte marcada visual_canonical só é autoritativa para apresentação e interação — decisões aprovadas e a Especificação continuam mandando em comportamento, segurança, privacidade e regra de negócio. O fluxo de Engenharia é o espelho técnico deste: mesmo modelo de origem, versão pinada e revisão independente.
Produtos com telas recorrentes podem declarar um Design System canônico em design/system/: um contrato humano (design-system.md) e uma fonte mecânica de tokens (tokens/tokens.json), versionados semanticamente. Ele documenta fundações, componentes (anatomia, variantes, estados, acessibilidade) e padrões — mas não substitui a Especificação nem aprova o Design de um caso de uso.
Todo Design que consome o sistema precisa pinar o id/versão aprovado e registrar quais tokens, componentes, padrões e desvios usou. Mudanças que quebram compatibilidade exigem impacto, migração, depreciação e plano de rollback documentados antes de remover algo aprovado.
design/
system/
context.md
design-system.md contrato humano
foundations/
tokens/
tokens.json fonte mecânica
themes.json
components/
patterns/
sources/
evidence/
Escolhe generate, evolve ou adopt — nunca promove uma referência a canônica por inferência. Toda fonte ganha autoridade, localização e versão ou hash imutável.
Compara telas e estados contra os identificadores estáveis REQ-*/AC-* da Especificação e, se houver, contra o Design System declarado.
Se o produto declara um sistema, o Design registra id/versão aprovados e os tokens, componentes e padrões consumidos — sem introduzir nada novo em silêncio.
Revisa identidade/autoridade/versão das fontes, cobertura de REQ/AC, estados (vazio, carregando, sucesso, erro, permissão negada), acessibilidade e fidelidade — nunca corrige nem aprova. Devolve approved, approved_with_notes ou blocked.
Uma revisão limpa segue para aprovação humana explícita. Achados blocked voltam para UX/UI AI.
Sem Design aprovado — ou com status estruturado not_applicable e justificativa — o fluxo não segue para Technical Discovery. Dali, quando aplicável, vêm Engineering Proposal e Engineering Review antes do Plano de Implementação.
Ferramentas e serviços de design são adapters — eles nunca substituem design.md nem o aprovam. Evidência importada ou gerada não é aprovação.
A gestão é supervisionada: adapters list/status/doctor são somente-leitura; adapters install exige versão explícita e --yes, mostra o comando exato do provedor antes de executar, e nunca reporta uma instalação falha como pronta. Nenhum adapter é obrigatório para a validação do framework.
Sem um contrato estável, cada entrega redescobre a arquitetura a partir do código — e agentes chegam ao plano de implementação sem ninguém revisar a solução técnica pretendida. O Engineering System compartilhado registra o conhecimento estável de como o produto é construído e operado, e cada entrega relevante passa por uma Engineering Proposal com Engineering Review independente antes do Plano de Implementação.
Vive em engineering/, é opcional e declara origin_mode (generate/evolve/adopt) e versão semântica — o mesmo modelo do Design System. engineering-system.md é o contrato humano; engineering-system.yaml, o catálogo mecânico que os validadores leem.
Cada área (contexto de sistema, módulos, dados, qualidade, runbooks) declara uma maturidade que descreve a evidência disponível — nunca concede aprovação. Decisões de produto continuam sendo registros DEC-*; o sistema referencia, não substitui. É o espelho técnico do fluxo de Design: mesmo modelo de origem, versão pinada e revisão independente.
A aprovação do sistema é composta: contexto, contrato humano, catálogo, arquitetura, padrões, qualidade, runbooks e evidência são hasheados em ordem determinística de caminho — mudar qualquer contrato compartilhado invalida a aprovação e exige reaprovação humana.
engineering/ context.md engineering-system.md contrato humano engineering-system.yaml catálogo mecânico architecture/ contexto, módulos standards/ quality/ modelo + fitness functions runbooks/ evidence/
Escala de maturidade por área — evidência, não aprovação
Liga os requisitos aplicáveis ao codebase real e ao conhecimento estável em engineering/. Estado atual, não solução.
Referencia uma decisão DEC-* aprovada, ou registra Not required com justificativa concreta.
engineering-proposal.md: fronteiras, ownership de dados, integrações, dependências, operação, testes, rollout e desvios do sistema pinado. Linka o conhecimento estável em vez de duplicá-lo; não sequencia tarefas. Pina a versão do Engineering System ou declara explicitamente que não há sistema configurado.
Avalia arquitetura, decisões, ownership, dependências, atributos de qualidade, operação e testabilidade. Não edita a Proposal, não aprova decisões de produto e não substitui Code Review, QA ou Security Review. O veredito registra o hash SHA-256 da Proposal atual — qualquer mudança a torna obsoleta.
Com a solução revisada, o plano sequencia fases, fatias e riscos — e o fluxo segue para Grafo, Tarefas e Code Runner.
context.md declara ao menos um engineering_trigger estruturadoLista fechada de triggers — a automação lê exatamente estes valores e nunca infere aplicabilidade a partir de prosa:
Produtos existentes continuam válidos até um caso de uso ser migrado ou cair na regra do Tier L — o upgrade nunca cria registros de aprovação nem sobrescreve conteúdo de engenharia do adotante.
materialized é um estado específico do Execution Graph: indica que os arquivos canônicos de tasks e o índice gerado já existem; não é um estado geral de artifacts.
O estado diz o que o artefato é; o que interessa é o que ele exige para avançar. Marcadores âmbar são os gates que mais bloqueiam.
Para virar proposed: estar completo o bastante para revisão. Não exige registro de aprovação, mas não avança se o gate do pai estiver incompleto.
Para virar approved: um humano aprova explicitamente — nasce um registro em .product/history/ com artifact_id, content_hash, approved_by e data. Daqui em diante, todo avanço exige registro.
Para virar in_progress: uma tarefa aprovada — ou uma exceção explícita de protótipo/rascunho.
Para virar implemented: evidência estruturada de working-tree — branch, base commit, changed paths, diff hash, testes e resultado dos gates. Commit ainda não é exigido.
Para virar validated: QA Evidence sem bloqueios, Code Review sem blocker/required_fix — ambos sobre o mesmo diff hash — e Security Review aprovado quando há código, dados, permissões ou risco de privacidade. Depois, Commit Crafter registra os commits.
Para virar released: Release Orchestrator, auditoria sem bloqueios, riscos residuais aceitos, e rollback/monitoramento definidos.
Fim de linha feliz. Os outros dois destinos possíveis: deprecated (não deve mais guiar implementações) e superseded (substituído por artefato mais recente).
Code Runner pode produzir código e evidência técnica, mas não commita, não faz push, não faz merge, não cria registro de aprovação e não aprova QA.
Para uma tarefa individual, Code Review e QA precisam aprovar o mesmo diff hash atual antes de validated — qualquer mudança no código invalida as duas aprovações.
Bug Fixer reproduz o defeito com um teste que falha antes de corrigir, corrige a causa raiz com mudança mínima e deixa um teste de regressão permanente.
Uma fonte visual canônica (visual_canonical) precisa de versão ou hash imutável; estados obrigatórios faltando, conflito não resolvido com a Especificação, ou desvio de fidelidade não revisado bloqueiam o Design de avançar.
Quando o produto declara um Design System, o Design de um caso de uso em proposed ou posterior precisa pinar seu id/versão aprovado e não pode introduzir token, componente ou padrão compartilhado silenciosamente.
Artefato inaplicável precisa do status estruturado not_applicable com justificativa real — "Not applicable" solto no texto nunca satisfaz o gate.
Engineering Review aprovada registra o hash SHA-256 da Proposal atual; qualquer mudança na Proposal torna a Review obsoleta. A aprovação do Engineering System é composta: mudar qualquer contrato compartilhado exige reaprovação humana.
Entregas com superfície visual exigem evidência visual proporcional — captura local ou artefato de CI — mais verificação básica de acessibilidade (role/label, foco, alvo de toque, contraste).
Registros de aprovação usam hash SHA-256 do arquivo inteiro, com conteúdo normalizado — garante auditabilidade e um gate mecânico, não prova criptográfica de aprovação humana.
Staleness é uma condição derivada pelo validador, não um status editável: se o artefato de origem muda, o artefato derivado fica obsoleto e não avança em nenhum gate até ser regenerado ou reaprovado.
Depois que o Grafo de Execução está approved, quem toca cada task até a entrega:
Calcula ondas paralelas determinísticas a partir do DAG, writeScope, sharedResources e leases ativas. Planeja; não spawna agentes.
Roteia o WORK-NNN entre os orquestradores permitidos usando estado persistido, handoffs e checkpoints. Nunca autoria artefato nem executa comando.
Reintegra localmente, em ordem de DAG, os commits de task já validados — e exige Integrated QA antes do release. Conflito para para humano.
A partir do DAG aprovado, writeScope, sharedResources e leases ativas, define quais tasks podem rodar em paralelo. Não spawna agentes.
Lê estado persistido, hashes, dono e tentativas; roteia o WORK-NNN para o próximo especialista autorizado. Nunca autoria artefato nem executa comando.
spec-framework lease claim --work WORK-001 --task TK-001 --agent codex --isolate — posse expirável, com heartbeat, opcionalmente em worktree Git isolado.
Uma task aprovada por vez, respeitando o writeScope declarado. Para se faltar gate, decisão ou especificação. Não commita.
implementedRegistra branch, base commit, changed paths, diff hash, testes e resultado dos gates — sem exigir commit ainda.
Code Review avalia completude, aderência e qualidade (somente leitura). QA revalida critérios de aceite, edge cases e evidência. Qualquer mudança de código invalida as duas aprovações.
Monta um plano de cherry-pick ordenado dos commits de task já validados, produz um diff hash integrado e exige uma rodada de Integrated QA. Conflito não se resolve sozinho — para para humano.
Separa por concern, segue knowledge/conventions/commits.md. Sem push.
Confere gates, QA Evidence, Code Review e Security Review; liga evidências ao PR. Sem merge.
Gaps, conflitos, docs, specs, design, tasks, testes, QA, review e security review antes de validated → released.
Depois de qualquer mudança de código, o fluxo reentra no QA — gate vermelho não se pula. Cada gate ou finding tem um teto de três tentativas automatizadas antes de escalar para um humano.
"Quero que as pessoas façam check-in num evento escaneando um QR code."
rigor_tier: L por lidar com dado sensível de presença.design.md com a tela de scanner, estados de sucesso/erro e acessibilidade.engineering-proposal.md (fronteiras, dados, integrações, rollout, pinando o Engineering System) e um veredito independente em engineering-review.md antes do plano.writeScope declarado — sem commitar.
Ninguém precisa decorar os comandos da referência. O Framework Guide é a porta de entrada conversacional: você descreve o objetivo em linguagem natural, ele inspeciona o estado mecânico real (via help, dashboard, status, guide, next, review, impact, gates, validate) e devolve o menor comando seguro que avança um gate válido — nunca autoria artefato, nunca infere uma aprovação, nunca pula um gate.
Antes de qualquer mutação, prefere inspeção somente-leitura. Só recomenda escrever algo depois de ler o context.md do escopo ativo, seus pais, aprovações e staleness.
Toda resposta guiada deixa claro o que lê, o que escreve, e qual gate/aprovação está em jogo — mostra o comando exato antes de qualquer mutação consequente.
Exige identidade e confirmação explícitas para comandos de aprovação. Nunca converte "concordância na conversa" em registro de aprovação de produto.
Fronteira de ativação: o Framework Guide só ativa rotas de produto quando o repositório contém um product/.product/framework.json válido, com versão concreta pinada e activation.mode: manifest-only. Mencionar "spec framework" numa conversa não ativa nada; sem manifest, as únicas rotas permitidas são explicar ou rodar o bootstrap/init pedido explicitamente. Após ativar, o dispatcher usa o Framework Guide por padrão e resolve skills especializadas do cache versionado via spec-framework skill path <skill>. Uma retomada por handoff ou checkpoint deve ser revalidada com dashboard, status, next ou guide antes do roteamento direto.
Roteia por intenção
scripts/install.ps1 / install.sh (pipe remoto é escolha explícita do usuário)init <caminho>init --starting-point existing-product → Product Baseline → Strategyinit --starting-point existing-feature → Feature Brief com Target Feature → workinit --starting-point existing-implementation → Assessment → Foundation completainit --starting-point audit-only → inspeção sem flags de escritadashboard · status · nextinit --starting-point existing-documents → import materializeapprove para um arquivo; approve-batch para Foundation, IDs ou etapa; approve-stage mantém o fluxo por workspacedesign init/import/register + UX/UI + UX Reviewadapters list/status/doctor → install --version ... --yesimpactgates → prontidão do Grafo → prontidão da Tarefavalidateupgrade --yesupdate --check / update --yes · uninstall / uninstall --purge --yesmigrate external-runtime --dry-run → revisar → --yes"Não sei o que fazer agora, só sei que preciso adicionar check-in por QR code no evento."
Framework Guide reformula em uma frase: criar uma feature nova dentro do domínio events.
Roda spec-framework dashboard --work WORK-001 (ou descobre que não há workspace e sugere work) para ver o gate ativo antes de recomendar qualquer coisa.
Como é uma feature nova, aponta para o New Feature Orchestrator: Feature AI → Use Case AI → Specification AI.
spec-framework work --feature FT-023 --domain events --goal manage-event --created-by "Product Owner"
Lê domains/events/context.md e o registro de features existentes. Escreve o workspace WORK-NNN — nenhum artefato de produto ainda.
Nenhum — é navegação, não precisa de aprovação.
Depois do comando, relê o estado real (não assume sucesso) e devolve o próximo passo seguro: spec-framework next --work WORK-001.
Mais exemplos
Não aceita a frase como aprovação. Roda spec-framework review --work WORK-001 --stage specification para checar se há bloqueio pendente.
Mostra o comando exato e pede identidade humana explícita: spec-framework approve --artifact ... --grant approved --approved-by "<seu nome>" --yes.
Explica o bloqueio real (ex.: contrato de segurança faltando) e roteia para a skill dona — não tenta contornar o gate.
Reconhece a intenção de migração e recomenda inspecionar antes de mutar: spec-framework decisions migrate --product-root product --dry-run.
Mostra o tipo e escopo inferidos por decisão, cria backup automático e nunca muda conteúdo ou status do DEC original.
Só grava depois de --interactive ou --yes explícitos — valores ambíguos ficam como item de revisão manual.
Lê o blocker real com spec-framework task readiness --graph ... --task TK-001 em vez de adivinhar a causa.
Segue a política fixa: defeito confirmado → Bug Fixer; teste faltando → volta pro dono do teste; ambiguidade de regra → Product Historian + humano.
Não tenta corrigir o código nem aprovar QA sozinho — isso é autoridade de outra skill.
Reconhece intenção de bootstrap a partir de documentos e recomenda spec-framework init --starting-point existing-documents --source-dir ../product-docs --yes.
Cria um inventário e um run de importação somente-análise em product/knowledge/imports/ — nenhum artefato canônico ainda.
Conflitos nunca são resolvidos em silêncio. Só depois de revisar o mapeamento: spec-framework import materialize --run IMPORT-001 --approved-by "<seu nome>" --yes.
Confirma que a Especificação está approved antes de sugerir Design — sem isso, o comando nem existe como rota válida.
Pergunta origin_mode e aponta spec-framework design init --use-case <path> --mode generate, ou design register se houver uma fonte Figma/Penpot autoritativa.
Depois de UX/UI AI produzir design.md, roteia para UX Review — Design só chega ao Implementation Planner com revisão limpa e aprovação humana.
1 · gerenciar a instalação e o runtime
# verificar e atualizar o CLI spec-framework update --check spec-framework update --yes # atualizar o framework usado por este produto spec-framework upgrade --yes # inspecionar remoção e migrações antes de executar spec-framework uninstall spec-framework uninstall --purge --yes spec-framework migrate external-runtime --dry-run spec-framework decisions migrate --product-root product --dry-run
2 · criar um produto novo a partir do starter
# adiciona apenas product/ ao repositório; o método fica no cache versionado do usuário spec-framework init ../meu-produto --agents codex --yes # a instalação do CLI é separada e não abre o wizard irm https://raw.githubusercontent.com/JonatasFreireDev/spec-framework/master/scripts/install.ps1 | iex
3 · navegar até uma feature e avançar sem "feature ativa global"
spec-framework work --feature FT-001 --domain events --goal manage-event --created-by "Product Owner" spec-framework status --work WORK-001 spec-framework next --work WORK-001
4 · aprovar um artefato explicitamente
spec-framework approve --artifact domains/events/context.md --grant approved --approved-by "Product Owner" --yes spec-framework gates
5 · revisar e aprovar um lote com escopo explícito
# preview: lista arquivos, hashes, ignorados, blockers e próximo gate spec-framework approve-batch --foundation spec-framework approve-batch --all-eligible --until specification --json spec-framework approve-batch --foundation --approved-by "Product Owner" --interactive # aplicar somente depois da confirmação humana explícita spec-framework approve-batch --ids PRB-001,VIS-001 --approved-by "Product Owner" --yes
6 · operar o grafo de execução e checar prontidão de uma tarefa
spec-framework graph ready --graph domains/events/.../execution-graph.json spec-framework graph materialize --graph domains/events/.../execution-graph.json --yes spec-framework task readiness --graph domains/events/.../execution-graph.json --task TK-001
7 · resumir, arrendar e agendar execução governada
spec-framework resume --work WORK-001 spec-framework lease claim --work WORK-001 --graph domains/events/.../execution-graph.json --task TK-001 --agent codex --isolate spec-framework schedule --work WORK-001 --graph domains/events/.../execution-graph.json --max-parallel 4
8 · revisar um estágio e medir o impacto de uma decisão
spec-framework review --work WORK-001 --stage tasks spec-framework approve-stage --work WORK-001 --stage tasks --approved-by "Product Owner" --yes spec-framework impact --decision DEC-021
9 · gerar, importar ou adotar Design; validar o Design System compartilhado
spec-framework design init --product-root product --use-case <path> --mode generate spec-framework design register --product-root product --use-case <path> --type figma --source <url> --version <version> --authority visual-canonical spec-framework design map --product-root product --use-case <path> --mappings mapping.json spec-framework design audit --product-root product --use-case <path> --write-report spec-framework design-system init --product-root product --mode generate spec-framework design-system validate --product-root product
10 · manter o Engineering System compartilhado
spec-framework engineering-system inspect --product-root product spec-framework engineering-system validate --product-root product spec-framework engineering-system triggers --product-root product spec-framework engineering-system migrate --product-root product --dry-run
11 · descobrir, diagnosticar e instalar adapters visuais opcionais
spec-framework adapters list spec-framework adapters status impeccable spec-framework adapters doctor impeccable --check-latest # sem --yes é só preview; "latest" resolve para uma versão concreta antes de executar spec-framework adapters install impeccable --version 2.3.2 spec-framework adapters install impeccable --version 2.3.2 --yes
12 · ver o estado consolidado do trabalho e migrar decisões antigas
spec-framework dashboard --work WORK-001 spec-framework status --work WORK-001 --graph --json spec-framework decisions migrate --product-root product --interactive
13 · planejar comandos governados por risco (R0/R1) e validar
spec-framework commands plan --work WORK-001 --task TK-001 --risk R0 -- go test ./... spec-framework validate
14 · bootstrap a partir de documentos existentes (epics, PRDs)
# cria um inventário e um run de importação, só análise spec-framework init ../meu-produto --agents codex --starting-point existing-documents --source-dir ../product-docs --yes # materializa artefatos de rascunho após aprovação humana explícita spec-framework import materialize --run IMPORT-001 --approved-by "Product Owner" --yes
15 · atualizar o runtime externo e migrar repositórios legados
# atualiza o cache versionado e o manifest pinado, preservando product/ spec-framework upgrade --yes # repositório antigo com .spec-framework/ local: preview antes de migrar spec-framework migrate external-runtime --dry-run # resolve o SKILL.md pinado de uma skill a partir do cache spec-framework skill path code-runner
16 · operar o runtime resumível e a integração local
spec-framework runtime spec-framework resume --work WORK-001 spec-framework checkpoint --work WORK-001 spec-framework handoff --work WORK-001 spec-framework integrate --work WORK-001
O CLI opera o método — cria workspaces, registra aprovações, materializa grafos, arrenda tasks — mas não invoca agentes automaticamente. Quem decide implementar continua sendo o agente (Codex, Claude, Cursor) lendo AGENTS.framework.md, FRAMEWORK.md e os context.md relevantes. A mecânica detalhada está em execution-runtime.md.