OpenSpec

OpenSpec é um fluxo orientado a specs para desenvolvimento assistido por IA. O Motoko Base o usa para que os agentes planejem antes de programar — mudanças delimitadas em vez de diffs aleatórios pelo repositório.

Docs oficiais: openspec.dev

Por que OpenSpec?

O OpenSpec separa o planejamento (proposal, design, specs, tasks) da implementação (apply). Você revisa o plano antes de qualquer mudança de código de produto.

Estrutura de pastas

openspec/
├── config.yaml              # Project context + rules for AI artifacts
├── specs/                   # Durable requirements (main specs)
│   └── <capability>/
│       └── spec.md
└── changes/
    ├── <active-change>/     # Work in progress
    │   ├── .openspec.yaml
    │   ├── proposal.md
    │   ├── design.md
    │   ├── tasks.md
    │   └── specs/<capability>/spec.md   # delta spec
    └── archive/
        └── <date>-<change-name>/        # completed changes

As main specs (openspec/specs/) são memória de produto de longo prazo — o que o starter deve fazer por capacidade (links, billing, storage, etc.).

Os changes (openspec/changes/) são planos de curta duração para um resultado. Após o archive, os requisitos duráveis se fundem nas main specs.

Regras de IA específicas do projeto ficam em openspec/config.yaml (filosofia, stack, restrições de arquitetura, regras por artefato).

Criar uma proposal

Use o slash command do Cursor ou peça ao agente para executar o skill de propose:

/opsx-propose Add a bookmarks demo with user ownership

Isso cria openspec/changes/<name>/ e gera:

Apenas planejamento — nenhum código de produto até você executar apply.

Para pensar sem planejar: /opsx-explore. Para revisar após feedback: /opsx-update.

Design

design.md registra decisões arquiteturais do change:

• Quais padrões existentes reutilizar (src/features/links/ como template CRUD)
• Schema, rotas e pontos de contato em arquivos
• Trade-offs e non-goals no nível de design

Agentes leem proposal.md + o codebase existente antes de escrever o design. Mantenha curto — prefira reutilizar padrões do starter a inventar novas camadas.

Tasks

tasks.md é uma lista de checkboxes que o agente segue durante o apply:

- [ ] 1.1 Add schema in src/lib/db/schema/...
- [ ] 2.1 Create queries.ts with ownership filters
- [ ] 3.1 Wire dashboard route and nav item

As tarefas devem ser pequenas, ordenadas (schema → server → UI → wiring) e nomear caminhos de arquivo concretos quando conhecidos.

Apply

Quando o plano estiver bom:

/opsx-apply

O agente:

1. Lê proposal.md, delta specs, design.md e tasks.md
2. Implementa cada tarefa não marcada
3. Marca tarefas - [x] conforme conclui
4. Pausa se o escopo estiver obscuro ou o spec precisar de atualização

Você pode executar apply em várias sessões — o progresso é rastreado em tasks.md.

Archive

Quando todas as tarefas estiverem feitas e você tiver revisado o código:

/opsx-archive

Archive:

1. Opcionalmente sincroniza as delta specs em openspec/specs/<capability>/spec.md
2. Move a pasta do change para openspec/changes/archive/<date>-<name>/

As main specs passam a ser a fonte da verdade para futuras sessões de IA sobre aquela capacidade.

Comandos CLI úteis

openspec list                      # active changes
openspec status --change <name>    # artifact progress
openspec validate <name>           # check a change
openspec view                      # browse specs and changes

Instalação: OpenSpec installation

Comandos do Cursor

Skills ficam em .agents/skills/openspec-* e .cursor/skills/openspec-*.

Fluxo de desenvolvimento com IA — Fluxo ponta a ponta da ideia à revisão.

Cursor / AI Agents — AGENTS.md e dicas de prompting.