OpenSDD

OpenSDD e uma evolucao do OpenSpec focada em memoria operacional, planejamento rastreavel e handoff entre agentes.

O objetivo nao e apenas criar specs. O objetivo e permitir que um projeto grande continue compreensivel ao longo do tempo, mesmo quando:

• novas ideias aparecem no meio da implementacao;
• existem varios agentes trabalhando em paralelo;
• o frontend fica defasado em relacao ao backend;
• um agente novo entra no repositorio sem contexto previo;
• o sistema ja existe e precisa ser absorvido sem reler todo o codigo.

O que o OpenSDD faz

O OpenSDD organiza o desenvolvimento em 4 camadas:

1. Descoberta

• INSIGHT: ideia bruta
• DEBATE: discussao estruturada
• RADAR: ideia aprovada para futuro planejamento
• DISCARDED: ideia rejeitada com motivo registrado

2. Planejamento

• RAD pode ser quebrado em FEATs
• FEAT vira unidade executavel
• o backlog registra dependencias, bloqueios e paralelizacao

3. Execucao

• cada FEAT ganha um workspace proprio em .sdd/active/FEAT-###/
• esse workspace tem spec, plan, tasks e changelog

4. Memoria operacional

• .sdd/state/*.yaml e a fonte canonica
• .sdd/core/*.md sao views operacionais geradas a partir do estado
• README.md, AGENTS.md, AGENT.md e .sdd/AGENT.md orientam humanos e agentes

O que fica instalado no projeto

Depois do bootstrap, o projeto passa a ter:

• README.md
• AGENTS.md
• AGENT.md
• .sdd/
• .sdd/state/
• .sdd/core/
• .sdd/discovery/
• .sdd/pendencias/
• .sdd/active/
• .sdd/templates/
• .sdd/skills/curated/
• .sdd/deposito/
• openspec/changes/

Dentro de .sdd/ ficam:

• memoria operacional do projeto
• backlog executavel
• debates e radar
• gaps e decisoes de frontend
• skills curadas
• documentacao viva do sistema

Instalacao global

Requer:

• Node.js 20.19.0 ou superior
• npm

Instalacao global oficial via npm:

npm install -g @gfmozzer/opensdd

Depois confira:

opensdd --version

Se voce estiver desenvolvendo este fork localmente:

pnpm install
pnpm run build
npm install -g .

Como iniciar em um projeto novo

Entre no repositorio onde voce quer usar o sistema e rode:

opensdd install --tools none

Se quiser integrar ferramentas suportadas no bootstrap:

opensdd install --tools all

Ou somente algumas:

opensdd install --tools codex,cursor,claude

Esse comando instala de uma vez:

• a base do runtime
• openspec/config.yaml
• .sdd/
• skills curadas
• templates
• estados YAML canonicos
• documentos iniciais do projeto

Se voce nao quiser habilitar frontend no bootstrap:

opensdd install --tools none --no-frontend

Como absorver um projeto que ja existe

Se o projeto ja esta em andamento, o primeiro passo depois do install e inicializar o contexto:

opensdd sdd init-context
opensdd sdd check --render
opensdd sdd onboard system

O init-context serve para:

• inspecionar a base existente
• preencher contexto inicial de arquitetura, stack, servicos e mapa do repositorio
• gerar a memoria inicial do sistema
• preparar onboarding para agentes novos

Em projetos grandes, esse bootstrap inicial nao substitui consolidacao progressiva. Ele cria uma base inicial para que o processo passe a evoluir de forma rastreavel.

Como usar no dia a dia

Fluxo principal:

1. Ver o sistema como um todo

opensdd sdd onboard system

2. Ver o que pode comecar agora

opensdd sdd next

3. Iniciar uma feature

opensdd sdd start FEAT-001

4. Ler o contexto da feature

opensdd sdd context FEAT-001

5. Implementar

6. Consolidar memoria ao final

opensdd sdd finalize --ref FEAT-001

Regra operacional central:

uma feature so esta realmente concluida quando a documentacao afetada foi atualizada antes do finalize.

Isso inclui, quando houver impacto:

• README.md
• AGENTS.md
• AGENT.md
• .sdd/README.md
• .sdd/AGENT.md
• .sdd/core/*.md
• gaps e decisoes de frontend

Como lidar com ideias novas durante a implementacao

Quando surgir uma ideia no meio do desenvolvimento:

opensdd sdd insight "descricao da ideia"
opensdd sdd debate INS-001
opensdd sdd decide DEB-001 --outcome radar
opensdd sdd breakdown RAD-001 --mode graph --incremental

Esse fluxo serve para nao enfiar no backlog algo que ainda nao foi pensado.

Como lidar com PRD, wireframe, HTML e material bruto

O OpenSDD separa descoberta de ingestao de documentos consolidados.

Se voce ja possui:

• PRD
• RFC
• historias do usuario
• wireframes
• imagens
• html mockado
• referencias visuais

esses materiais devem ir para:

.sdd/deposito/

Estrutura:

.sdd/deposito/
├── prds/
├── rfcs/
├── historias/
├── wireframes/
├── html-mocks/
├── referencias-visuais/
├── entrevistas/
├── anexos/
└── legado/

Depois disso, o sistema usa o indice de fontes e as skills curadas para transformar esse material em:

• contexto canonico
• radar
• features
• gaps e decisoes de frontend
• insights apenas quando houver ambiguidade real

Skills incluidas no bootstrap

O bootstrap do SDD instala curadoria local em:

.sdd/skills/curated/

Entre elas:

• repo-context-bootstrap
• source-intake-sdd
• business-extractor-sdd
• frontend-extractor-sdd
• planning-normalizer-sdd

Tambem sao instaladas skills curadas de apoio para execucao e planejamento.

Arquivos importantes para onboarding

Um agente novo deve seguir esta ordem:

1. README.md
2. .sdd/AGENT.md
3. .sdd/core/index.md
4. .sdd/core/arquitetura.md
5. .sdd/core/servicos.md
6. .sdd/core/spec-tecnologica.md
7. .sdd/core/repo-map.md
8. .sdd/core/fontes.md
9. .sdd/core/frontend-decisions.md

Comandos principais

Bootstrap:

• opensdd install --tools none
• opensdd install --tools all
• opensdd sdd init-context
• opensdd sdd check --render

Onboarding e operacao:

• opensdd sdd onboard system
• opensdd sdd next
• opensdd sdd start FEAT-###
• opensdd sdd context FEAT-###
• opensdd sdd finalize --ref FEAT-###

Descoberta:

• opensdd sdd insight "..."
• opensdd sdd debate INS-###
• opensdd sdd decide DEB-### --outcome radar|discard
• opensdd sdd breakdown RAD-### --mode graph --incremental

Documentacao

Guia detalhado em portugues:

• Manual SDD PT-BR
• Release e Rollback
• Kit estatico do SDD

Guia interno do sistema:

• .sdd/README.md
• .sdd/AGENT.md

Desenvolvimento local

pnpm install
pnpm run build
pnpm test

Loop local do CLI:

pnpm run dev:cli

Estado atual da distribuicao

O comando global oficial deste fork e:

opensdd

O caminho de distribuicao oficial deste repositorio e npm:

npm install -g @gfmozzer/opensdd

Fallback suportado:

• instalacao por tarball (npm pack + npm install -g ./gfmozzer-opensdd-<versao>.tgz)

Licenca

MIT

Onboarding SDD

Ordem de leitura para qualquer agente novo:

1. README.md (este bloco)
2. .sdd/AGENT.md
3. .sdd/core/index.md
4. .sdd/core/arquitetura.md
5. .sdd/core/servicos.md
6. .sdd/core/spec-tecnologica.md
7. .sdd/core/repo-map.md
8. .sdd/core/fontes.md
9. .sdd/core/frontend-decisions.md (quando frontend estiver ativado)

Comandos essenciais:

• opensdd sdd onboard system
• opensdd sdd next
• opensdd sdd context FEAT-###
• opensdd sdd finalize --ref FEAT-###