Schemas

Altere o que o OpenSpec produz: os artefatos, sua ordem e seus templates.

Um schema define o que uma proposta de mudança produz: quais artefatos, em que ordem, a partir de quais templates. Por exemplo, spec-driven, o schema padrão incluído, produz estes quatro em aproximadamente esta ordem, cada um se baseando no que veio antes:

proposal → specs → design → tasks

Crie um fork de um schema quando quiser que esses sejam documentos diferentes, seja com menos artefatos, nomes diferentes ou uma estrutura diferente.

Onde os schemas ficam

O OpenSpec procura um schema em três locais, em ordem, e usa o primeiro que encontrar:

1. Seu projeto: openspec/schemas/, versionado junto com o repositório para que toda a sua equipe o tenha.
2. Sua máquina: ~/.local/share/openspec/schemas no macOS e no Linux (ou em $XDG_DATA_HOME, se você o definir), ou %LOCALAPPDATA%\openspec\schemas no Windows. Os schemas aqui ficam disponíveis em todos os projetos em que você trabalha.
3. O pacote: os schemas embutidos, como spec-driven, vêm dentro do próprio openspec.

O mesmo nome pode existir em mais de um local, e o local mais específico prevalece. openspec schema which mostra qual cópia está em uso:

$ openspec schema which spec-driven
Schema: spec-driven
Source: project
Path: /your-project/openspec/schemas/spec-driven

Shadows:
  package: .../openspec/schemas/spec-driven

O que há em um schema

Um schema é definido por uma pasta de arquivos simples: um schema.yaml que declara os artefatos e um template para cada um deles. Este é o spec-driven embutido:

spec-driven/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

• schema.yaml: declara cada artefato, o arquivo que ele gera, o template a partir do qual começa, o que ele requer antes e a instrução que o agente recebe ao criá-lo. O contrato de cada campo está em schema.yaml.
• templates/: um esqueleto markdown por artefato, que o agente preenche.

Esta é a entrada do artefato tasks no schema.yaml, resumida:

artifacts:
  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    instruction: |
      ...what the agent is told when creating tasks.md...
    requires:
      - specs
      - design

Os schemas embutidos vêm dentro do pacote openspec, então você nunca os edita no local. Você obtém sua própria cópia criando um fork.

Criando seu próprio schema personalizado

Há duas maneiras de obter seu próprio schema:

1. Crie um fork de um schema existente e edite sua cópia. Comece por aqui quando um schema existente estiver próximo do que você quer, porque tudo nele já funciona.
2. Comece do zero quando nenhum deles servir, criando a estrutura de um schema vazio com openspec schema init.

Crie um fork de um schema existente

1. Crie um fork do schema a partir do qual você quer começar, executando na raiz do seu projeto:

   $ openspec schema fork spec-driven
   
   Note: Schema commands are experimental and may change.
   ✔ Forked 'spec-driven' to 'spec-driven-custom'
   
   Source: .../openspec/schemas/spec-driven (package)
   Destination: /your-project/openspec/schemas/spec-driven-custom

   Passe um segundo argumento para escolher o nome (openspec schema fork spec-driven team-flow). Os nomes usam kebab-case.

2. Edite a cópia: schema.yaml e os templates. Editando seu fork aborda o que alterar.

3. Valide-o:

   openspec schema validate spec-driven-custom

   Este é o único comando que detecta um schema quebrado (templates ausentes, YAML inválido, ciclos de dependência) antes de você estar no meio de uma mudança.

4. Aponte seu projeto para ele em openspec/config.yaml. Esta etapa é sua, porque o fork deixa o config.yaml intacto:

   schema: spec-driven-custom

5. As novas propostas de mudança agora seguem seu schema. Mudanças criadas anteriormente mantêm o schema com o qual começaram.

Para substituir o padrão em todos os lugares sem alterar o config.yaml, crie um fork com o mesmo nome: openspec schema fork spec-driven spec-driven. A cópia do seu projeto então sobrepõe o schema embutido, como explica Onde os schemas ficam.

Comece do zero

openspec schema init cria a estrutura de um novo schema em vez de copiar um:

$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

A estrutura gerada é básica. Os artefatos vêm apenas dos quatro IDs embutidos, e os templates gerados não trazem instruções, então o agente recebe menos orientação até você escrever as suas. A partir daí, as etapas de fork se aplicam sem alterações: valide o schema e depois aponte o config.yaml para ele.

Editando seu fork

Um fork tem dois tipos de arquivos para editar:

• templates/ alteram o esqueleto de cada documento. Adicione uma seção ao template de tasks e todo novo tasks.md começará com ela. Mantenha o título # na primeira linha: o artefato o herda, então todo arquivo gerado abre como um documento com título.
• schema.yaml altera o próprio fluxo de trabalho: quais artefatos existem, o que cada um requer antes e a instrução que o agente recebe ao criá-lo.

Por exemplo, para remover o documento de design em busca de um fluxo mais enxuto:

1. Exclua a entrada design do schema.yaml.

2. Remova design da lista requires de tasks.

3. Valide:

   $ openspec schema validate spec-driven-custom
   
   ✓ Schema 'spec-driven-custom' is valid

Pule a etapa 2 e o validate detectará o problema:

✗ Schema 'spec-driven-custom' has errors:
  error: Invalid dependency reference in artifact 'tasks': 'design' does not exist

Valide após cada edição manual. Caso contrário, um schema quebrado aparece no meio de uma mudança, quando um fluxo de trabalho solicita um arquivo que não existe. Assim como o config.yaml, as edições de schema chegam ao agente na próxima execução.

Um fork é um snapshot

openspec update atualiza as skills e os comandos instalados e nunca toca em openspec/schemas/. Seu fork continua funcionando exatamente como você o deixou, o que também significa que ele deixa de receber melhorias quando o schema embutido evolui. Para incorporá-las mais tarde, crie um fork do schema embutido novamente com um novo nome e transfira as diferenças.

Compartilhando schemas

Compartilhar um schema significa copiar sua pasta.

• Com sua equipe: faça commit de openspec/schemas/ e todos no repositório o usarão.
• Entre seus projetos: coloque a pasta no diretório de nível de usuário de Onde os schemas ficam.
• Da comunidade: o catálogo da comunidade lista schemas compartilhados. Copie um para openspec/schemas/<name> e ele funcionará como se fosse seu.

Estamos trabalhando em um registro de schemas, público e privado, para que os schemas possam ser instalados por nome em vez de copiados manualmente.

Use o OpenSpec com Superpowers

O schema superpowers-bridge, mantido pela comunidade, conecta os artefatos do OpenSpec às skills de execução do Superpowers. Siga as notas de instalação e compatibilidade da bridge antes de copiá-la para seu projeto.

A bridge é lançada fora do OpenSpec. O OpenSpec não testa nem versiona sua integração com o Superpowers.