OpenSpec

Stores (beta) ​

Planeje mudanças que abrangem repositórios: um store, muitos repositórios.

O OpenSpec normalmente fica dentro de um repositório: uma pasta openspec/ ao lado do código que ele planeja. Um store move essa pasta para um repositório próprio, e vários repositórios de código podem compartilhá-lo.

Após uma configuração única em cada máquina, comandos como status, new change e archive podem funcionar no store a partir de qualquer diretório.

         team-plans  (um store: OpenSpec em seu próprio repositório)
         ├── .openspec-store/store.yaml   o nome do store
         └── openspec/
             ├── specs/
             └── changes/
                   ▲
                   │ configurado uma vez em cada máquina,
                   │ compartilhado por push e clone como qualquer repositório
     ┌─────────────┼─────────────┐
     │             │             │
 web-app       api-server     mobile-app
(repositório de código) (repositório de código) (repositório de código)

Você compartilha um store com o git, da mesma forma que compartilha código: faça commit, push, pull e revise-o você mesmo. As especificações e as mudanças recebem branches e pull requests da mesma forma que o código.

Quando você precisa de um ​

Dois motivos comuns para usar um store:

  • Frontend e backend em repositórios separados: uma funcionalidade envolve ambos, e o plano precisa de um único local em vez de duas metades.

          shop-plans  (store)
      └── openspec/changes/add-discounts/    um plano para a funcionalidade
                ▲
      ┌─────────┴─────────┐
      │                   │
  storefront             api
(repositório frontend)  (repositório backend)

  • Um produto, vários repositórios de clientes: Android, iOS e web são entregues a partir de seus próprios repositórios, mas compartilham um único comportamento esperado. Uma especificação descreve comportamento, não implementação, então uma única especificação atende aos três.

            product-specs  (store)
        └── openspec/specs/checkout/spec.md    o comportamento esperado
                  ▲
    ┌─────────────┼─────────────┐
    │             │             │
android-app    ios-app       web-app
(repositório de código) (repositório de código) (repositório de código)

Você pode ter mais de um store, embora recomendemos manter a quantidade baixa.

Configurar um store ​

Uma pessoa cria o store, depois todos os outros se juntam a ele.

  1. Criar o store (uma pessoa, uma vez por equipe). Execute openspec store setup e responda às perguntas:

    bash
    # run from anywhere; it asks what to create and where
openspec store setup

    Ele faz três perguntas:

    • Nome do store: team-plans
    • Onde este store deve ficar?: pré-preenchido com ~/openspec/<name>, pressione Enter para aceitar ou digite outro caminho
    • Criar este store?: mostra o que está prestes a criar, responda Yes

    Depois ele relata o que criou:

    yaml
    Store ready: team-plans
Location: ~/openspec/team-plans
OpenSpec root: ready
Registry: registered

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-plans
Share this store by committing and pushing it like any Git repo.

  2. Envie para seu host de git. Crie um repositório vazio team-plans em seu host primeiro. O setup não adiciona um remote git, então conecte o store a esse repositório e depois faça push:

    bash
    # connect the store to the empty repo on your git host
cd ~/openspec/team-plans
git remote add origin git@github.com:acme/team-plans.git

# publish it
git push -u origin main

  3. Entrar no store (cada colega de equipe, uma vez por máquina):

    bash
    # get the store onto your machine
git clone git@github.com:acme/team-plans.git ~/openspec/team-plans

# tell OpenSpec where it lives
openspec store register ~/openspec/team-plans
    yaml
    Store registered: team-plans
Location: /Users/you/openspec/team-plans
OpenSpec root: ready
Registry: registered

    Registrar informa à sua máquina onde este store fica. O nome do store já está commitado dentro dele, em .openspec-store/store.yaml. O setup registrou a cópia do criador, então apenas cópias clonadas precisam desta etapa.

  4. Confirme que funcionou, a partir de qualquer diretório:

    bash
    # any OpenSpec command reaches the store by name
openspec status --store team-plans
    yaml
    Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
No active changes. Create one with: openspec new change <name> --store team-plans

Tipos de configurações ​

OpenSpec tem três configurações. O resto desta página usa estes nomes:

  • repo-local: OpenSpec dentro do seu repositório, sem store. O padrão.
  • store-only: seu repositório não mantém specs ou mudanças próprias. Tudo fica no store.
  • store-optional: seu projeto tem sua própria pasta openspec/ e também acessa um store quando você solicita.

O padrão: OpenSpec dentro do seu repositório (repo-local) ​

openspec init coloca uma pasta openspec/ ao lado do seu código, e os specs e mudanças daquele repositório ficam lá. Nenhum store está envolvido. Esta é a configuração que Configurar seu projeto ensina, e a maioria dos projetos nunca precisa de outra.

web-app  (code repo)
└── openspec/
    ├── specs/
    └── changes/

OpenSpec fora do seu repositório, em um store (store-only) ​

O repositório não mantém specs ou mudanças próprias. Tudo o que planeja fica no store, e uma linha na configuração do repositório conecta os dois.

Comum quando uma equipe constrói todos os repositórios e planeja em um só lugar. Os exemplos acima todos têm essa forma.

team-plans  (store)
└── openspec/
    ├── specs/       the repo's specs live here
    └── changes/     its changes too
          ▲
          │ store: team-plans   (the connecting line)
web-app  (code repo)
└── openspec/
    └── config.yaml    nothing else

OpenSpec no seu repositório e em um store (store-optional) ​

O repositório permanece repo-local para seu próprio trabalho, enquanto o store mantém os specs e mudanças compartilhados. Dentro do repositório, OpenSpec usa a pasta openspec/ do seu projeto, e acessa o store apenas quando você passa --store.

Comum quando um repositório usava OpenSpec antes de o store existir, ou quando um repositório majoritariamente independente ocasionalmente toca em trabalho compartilhado.

team-plans  (store)
└── openspec/          the shared specs and changes
          ▲
          │ only when you pass --store team-plans
web-app  (code repo)
└── openspec/          this repo's own
    ├── config.yaml
    ├── specs/
    └── changes/

Um repositório pode começar repo-local e mover seus specs e mudanças para o store depois. Mover specs e mudanças de um repositório para o store mostra como.

Onde os artefatos são criados ao usar stores ​

Quando você usa um store, OpenSpec também precisa decidir onde os artefatos são criados. Depende da sua configuração:

  • store-only (seu projeto só escreve no store): todo artefato é criado no store. A linha store: abaixo registra isso.
  • store-optional (seu projeto tem sua própria pasta openspec/ e também usa um store): artefatos são criados no seu projeto, a menos que você nomeie o store na sua solicitação ou passe --store para aquela mudança. Seu agente então carrega a flag pelo restante do fluxo de trabalho.

OpenSpec grava artefatos em um de dois lugares: a pasta openspec/ do seu projeto, ou o store. Ele escolhe nesta ordem, e a primeira opção que se aplica vence:

  1. --store <id> em um comando. Sempre vence, a partir de qualquer diretório.
  2. A pasta openspec/ do seu projeto. Se seu projeto tem suas próprias pastas specs/ ou changes/, OpenSpec as usa.
  3. A linha store: no seu projeto. Como um projeto store-only registra seu store.
  4. defaultStore na sua máquina. O fallback quando nenhuma das anteriores se aplica.

Se nenhuma destas se aplica e você tem stores registrados, o comando falha e os lista. Quando o id de um store corresponde ao nome do seu repositório no remote origin, o erro nomeia aquele store e a linha store: que o seleciona. OpenSpec nunca escolhe um store pelo nome por conta própria, porque repositórios em diferentes organizações podem compartilhar um nome.

Quando OpenSpec seleciona um store, ele imprime Using OpenSpec root: ... antes da saída do comando.

A linha store: (projetos store-only) ​

Adicione uma linha ao openspec/config.yaml do seu projeto:

yaml
# web-app/openspec/config.yaml
store: team-plans

Tudo o que você ou seu agente executam dentro do seu projeto agora usa o store, sem flag para digitar:

bash
# inside web-app, connected
openspec status
yaml
Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
No active changes. Create one with: openspec new change <name> --store team-plans
  • Sem a linha: execute um comando simples em um projeto store-only e OpenSpec para com um erro listando seus stores registrados.
  • Commitar: colegas de equipe que clonam seu projeto recebem a linha também. Eles ainda precisam do store registrado em sua máquina (etapa 3 de Configurar um store), ou OpenSpec erra e diz a eles para registrá-lo.
  • Ao lado de pastas reais: se seu projeto também tem pastas specs/ ou changes/, OpenSpec as usa e ignora a linha, com um aviso.

Instalar integrações em um repositório store-only ​

Execute init a partir da raiz do repositório de código para instalar arquivos de integração de ferramentas de IA sem mover o planejamento de volta para esse repositório:

bash
# inside web-app, at the repository root
openspec init --tools claude
  • Arquivos de integração: gravados no repositório de código.
  • openspec/config.yaml: preservado byte a byte, incluindo a linha store:.
  • openspec/specs/ e openspec/changes/: não criados no repositório de código.

OpenSpec recusa este comando a partir de um subdiretório do repositório de código. Execute-o a partir da raiz do repositório.

OpenSpec também recusa --language aqui porque o idioma pertence à configuração do store externo. Execute init na raiz do store ou edite essa configuração diretamente.

defaultStore na sua máquina ​

Defina uma vez se todos os projetos em que você trabalha usam o mesmo store. OpenSpec recorre a ele quando não encontra flag, pasta openspec/ local, e nem linha store::

bash
# use team-plans whenever nothing else names a store
openspec config set defaultStore team-plans

# undo it
openspec config unset defaultStore

Comandos que permanecem locais. init, update, templates, schemas, e os subcomandos openspec schema agem apenas no diretório atual e não aceitam --store.

Mover specs e mudanças de um repositório para o store ​

Para levar um repositório de repo-local para store-only:

  1. Mova tudo nas pastas openspec/specs/ e openspec/changes/ do repositório para as mesmas pastas no store.
  2. Delete as pastas agora vazias, para que a pasta openspec/ do repositório contenha apenas config.yaml.
  3. Adicione a linha store: a esse config.yaml.

openspec status dentro do repositório agora começa com Using OpenSpec root: team-plans.

Trabalhar no store ​

Os fluxos de trabalho não mudam, para você ou para seu agente. Propor, aplicar e arquivar funcionam como sempre funcionaram. A única diferença é onde os artefatos são criados, e a seção acima cobre isso.

Crie uma mudança a partir de um repositório store-only e ela cai no store:

bash
# inside web-app; the store: line routes this to team-plans
openspec new change add-login
yaml
Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
Created change 'add-login' at /Users/you/openspec/team-plans/openspec/changes/add-login/
Schema: spec-driven
Next: openspec status --change add-login --store team-plans
  • Onde foi parar: no repositório do store, não ao lado do seu código.
  • Compartilhando: a mudança existe apenas no seu checkout até você commitar e fazer push do repositório do store. Colegas de equipe a veem quando fazem pull. O mesmo vale para cada artefato que os fluxos de trabalho gravam.
  • Caminhos na documentação: onde quer que a documentação mostre um caminho openspec/, em uma configuração store essa pasta é a do store.

Quando artefatos são criados em algum lugar que você não esperava, openspec doctor verifica sua configuração sem alterar nada e imprime uma correção para cada achado:

bash
# check the current root and its stores
openspec doctor
yaml
Doctor

Root
  Location: /Users/you/openspec/team-plans
  OpenSpec root: ok
  Store: team-plans (metadata ok)

References
  (none declared)

openspec context lista a raiz e os stores com os quais seu diretório atual trabalha, quando você quer o mesmo panorama sem as verificações.

Para abrir o store e um repositório em uma janela do editor, para que seu agente possa ler ambos, veja Worksets (beta).

Ler specs de outro store ​

Seu repositório pode manter sua própria pasta openspec/ e ainda assim permitir que seu agente leia as specs de outro store. Declare esse store em references: no openspec/config.yaml do repositório:

yaml
# api-server/openspec/config.yaml
references:
  - team-plans

As referências são somente leitura. Seu trabalho permanece no seu repositório, e a referência altera apenas o que é informado ao seu agente.

Quando um fluxo de trabalho cria um artefato, suas instruções ganham um índice das specs do store referenciado, cada uma com um resumo de uma linha e o comando exato para buscá-la:

xml
<referenced_stores>
<!-- Contexto upstream somente leitura. Busque o que precisar; cite o que usar. -->
Store team-plans (/Users/you/openspec/team-plans):
  - payments: Rules for charging and refunding customers.
  Fetch: openspec show <spec-id> --type spec --store team-plans
</referenced_stores>

Uma referência também pode incluir a URL de clone do store, para máquinas que ainda não têm esse store:

yaml
references:
  - team-plans
  - { id: design-system, remote: "git@github.com:acme/design-system.git" }

Com a URL declarada, o openspec doctor transforma um store ausente em uma correção pronta para colar:

yaml
# saída ajustada para caber
References
  - team-plans: ok (/Users/you/openspec/team-plans)
  - design-system: Referenced store 'design-system' is not registered on this machine.
    Fix: git clone -- git@github.com:acme/design-system.git '/Users/you/openspec/design-system' &&
         openspec store register '/Users/you/openspec/design-system' --id design-system

Limitações do beta ​

  • O formato pode mudar: nomes de comandos, flags e formatos de arquivo podem mudar entre versões. Releia esta página após atualizar.
  • Sem sincronização, por design: o OpenSpec nunca clona, faz pull nem push. Um checkout desatualizado mostra specs desatualizadas até você fazer pull, e as referências são lidas a partir do que estiver no disco.
  • Um checkout por nome de store: registrar uma segunda pasta com um nome que já está registrado falha, com uma dica para executar openspec store unregister primeiro.