Fluxo de Trabalho OPSX
Feedbacks são bem-vindos no Discord.
O que é?
O OPSX agora é o fluxo de trabalho padrão para o OpenSpec.
É um fluxo de trabalho fluido e iterativo para alterações no OpenSpec. Sem mais fases rígidas — apenas ações que você pode realizar a qualquer momento.
Por que isso existe
O fluxo de trabalho legado do OpenSpec funciona, mas é bloqueado:
- Instruções são codificadas — enterradas em TypeScript, você não pode alterá-las
- Tudo ou nada — um grande comando cria tudo, não pode testar peças individuais
- Estrutura fixa — mesmo fluxo para todos, sem personalização
- Caixa preta — quando a saída da IA é ruim, você não pode ajustar os prompts
OPSX abre isso. Agora qualquer um pode:
- Experimentar com instruções — edite um template, veja se a IA obtém melhores resultados
- Testar granularmente — valide as instruções de cada artefato independentemente
- Personalizar fluxos de trabalho — defina seus próprios artefatos e dependências
- Iterar rapidamente — altere um template, teste imediatamente, sem recompilação
Fluxo de trabalho legado: OPSX:
┌────────────────────────┐ ┌────────────────────────┐
│ Codificado no pacote │ │ schema.yaml │◄── Você edita isso
│ (não pode alterar) │ │ templates/*.md │◄── Ou isso
│ ↓ │ │ ↓ │
│ Aguardar novo release │ │ Efeito imediato │
│ ↓ │ │ ↓ │
│ Esperar melhorar │ │ Teste você mesmo │
└────────────────────────┘ └────────────────────────┘Isso é para todos:
- Equipes — crie fluxos de trabalho que correspondam à forma como você realmente trabalha
- Usuários avançados — ajuste prompts para obter melhores saídas da IA para seu código
- Contribuidores do OpenSpec — experimente novas abordagens sem releases
Todos ainda estamos aprendendo o que funciona melhor. OPSX nos permite aprender juntos.
A Experiência do Usuário
O problema com fluxos de trabalho lineares: Você está "na fase de planejamento", depois "na fase de implementação", e então "concluído". Mas o trabalho real não funciona assim. Você implementa algo, percebe que seu design estava errado, precisa atualizar as especificações, continua implementando. Fases lineares lutam contra a forma como o trabalho realmente acontece.
Abordagem OPSX:
- Ações, não fases — criar, implementar, atualizar, arquivar — faça qualquer uma delas a qualquer momento
- Dependências são habilitadores — elas mostram o que é possível, não o que é obrigatório a seguir
proposal ──→ specs ──→ design ──→ tasks ──→ implementConfiguração
# Certifique-se de ter o openspec instalado — as skills são geradas automaticamente
openspec initIsso cria skills em .claude/skills/ (ou equivalente) que os assistentes de codificação de IA detectam automaticamente.
Por padrão, o OpenSpec usa o perfil de fluxo de trabalho core (propose, explore, apply, update, sync, archive). Se você quiser os comandos expandidos do fluxo de trabalho (new, continue, ff, verify, bulk-archive, onboard), configure-os com openspec config profile e aplique com openspec update.
Durante a configuração, você será solicitado a criar um config do projeto (openspec/config.yaml). Isso é opcional, mas recomendado.
Configuração do Projeto
O config do projeto permite definir padrões e injetar contexto específico do projeto em todos os artefatos.
Criando Config
O config é criado durante openspec init, ou manualmente:
# openspec/config.yaml
schema: spec-driven
context: |
Pilha de tecnologias: TypeScript, React, Node.js
Convenções de API: RESTful, respostas JSON
Testes: Vitest para testes unitários, Playwright para e2e
Estilo: ESLint com Prettier, TypeScript estrito
rules:
proposal:
- Incluir plano de rollback
- Identificar equipes afetadas
specs:
- Usar formato Dado/Quando/Então para cenários
design:
- Incluir diagramas de sequência para fluxos complexosCampos do Config
| Campo | Tipo | Descrição |
|---|---|---|
schema | string | Schema padrão para novas mudanças (ex.: spec-driven) |
context | string | Contexto do projeto injetado em todas as instruções de artefatos |
rules | objeto | Regras por artefato, identificadas pelo ID do artefato |
Como Funciona
Precedência do schema (maior para menor):
- Flag da CLI (
--schema <nome>) - Metadados da mudança (
.openspec.yamlno diretório da mudança) - Config do projeto (
openspec/config.yaml) - Padrão (
spec-driven)
Injeção de contexto:
- O contexto é adicionado ao início das instruções de cada artefato
- Envolvido em tags
<context>...</context> - Ajuda a IA a entender as convenções do seu projeto
Injeção de regras:
- As regras são injetadas apenas para artefatos correspondentes
- Envolvidas em tags
<rules>...</rules> - Aparecem após o contexto, antes do template
IDs de Artefatos por Schema
spec-driven (padrão):
proposal— Proposta de mudançaspecs— Especificaçõesdesign— Design técnicotasks— Tarefas de implementação
Validação do Config
- IDs de artefato desconhecidos em
rulesgeram avisos - Nomes de schema são validados contra os schemas disponíveis
- O contexto tem um limite de tamanho de 50KB
- YAML inválido é reportado com números de linha
Solução de Problemas
"ID de artefato desconhecido em rules: X"
- Verifique se os IDs dos artefatos correspondem ao seu schema (veja a lista acima)
- Execute
openspec schemas --jsonpara ver os IDs de artefatos de cada schema
Config não sendo aplicado:
- Certifique-se de que o arquivo está em
openspec/config.yaml(não.yml) - Verifique a sintaxe YAML com um validador
- As alterações de config têm efeito imediato (não é necessário reiniciar)
Contexto muito grande:
- O contexto é limitado a 50KB
- Resuma ou vincule a documentação externa em vez disso
Comandos
| Comando | O que faz |
|---|---|
/opsx:propose | Cria uma mudança e gera artefatos de planejamento em uma etapa (caminho rápido padrão) |
/opsx:explore | Pense em ideias, investigue problemas, esclareça requisitos |
/opsx:new | Inicia um novo esqueleto de mudança (fluxo de trabalho expandido) |
/opsx:continue | Cria o próximo artefato (fluxo de trabalho expandido) |
/opsx:ff | Avança rapidamente os artefatos de planejamento (fluxo de trabalho expandido) |
/opsx:apply | Implementa tarefas, atualizando artefatos conforme necessário |
/opsx:update | Revisa os artefatos de planejamento de uma mudança e os mantém coerentes |
/opsx:verify | Valida a implementação em relação aos artefatos (fluxo de trabalho expandido) |
/opsx:sync | Mescla as specs delta nas specs principais (opcional) |
/opsx:archive | Arquiva quando concluído |
/opsx:bulk-archive | Arquiva várias mudanças concluídas (fluxo de trabalho expandido) |
/opsx:onboard | Orientação guiada de uma mudança de ponta a ponta (fluxo de trabalho expandido) |
Uso
Explore uma ideia
/opsx:explorePense em ideias, investigue problemas, compare opções. Nenhuma estrutura necessária — apenas um parceiro de pensamento. Quando insights cristalizarem, transicione para /opsx:propose (padrão) ou /opsx:new//opsx:ff (expandido).
Inicie uma nova mudança
/opsx:proposeCria a mudança e gera os artefatos de planejamento necessários antes da implementação.
Se você habilitou os fluxos de trabalho expandidos, pode usar em vez disso:
/opsx:new # apenas esqueleto
/opsx:continue # cria um artefato por vez
/opsx:ff # cria todos os artefatos de planejamento de uma vezCrie artefatos
/opsx:continueMostra o que está pronto para ser criado com base nas dependências, depois cria um artefato. Use repetidamente para construir sua mudança incrementalmente.
/opsx:ff add-dark-modeCria todos os artefatos de planejamento de uma vez. Use quando você tem uma imagem clara do que está construindo.
Implemente (a parte fluida)
/opsx:applyTrabalha nas tarefas, marcando-as conforme avança. Se você está gerenciando várias mudanças, pode executar /opsx:apply <nome>; caso contrário, deve inferir a partir da conversa e solicitar que você escolha se não conseguir identificar.
Atualizando uma mudança
/opsx:update add-dark-mode - estamos armazenando o tema em um cookie agoraRevisa os artefatos de planejamento existentes da mudança e os mantém coerentes — em qualquer direção (uma edição de design pode refletir de volta na proposta). Apenas artefatos de planejamento: nunca edita código e nunca cria artefatos ausentes (isso é /opsx:continue). Cada edição é confirmada com você primeiro. Se a mudança já foi implementada, ele recomenda /opsx:apply para que o código se alinhe ao plano revisado. Se sua revisão alterar a intenção da mudança, comece do zero — veja Quando Atualizar vs. Começar do Zero.
Sincronize as specs delta
/opsx:syncMescla as specs delta da mudança atual em suas openspec/specs/ principais sem arquivar — a mudança permanece ativa. Aplica todo o delta: um requisito sob ## REMOVED é excluído da spec principal e um renomeado é retitulado no lugar, enquanto o conteúdo que o delta não menciona é deixado intacto. A sincronização é opcional — o arquivamento solicita que você sincronize primeiro se ainda não tiver feito. Use-a quando quiser que as specs principais sejam atualizadas antes do arquivamento, quando uma mudança paralela precisar construir sobre specs que esta acabou de adicionar, ou quando quiser revisar a spec principal mesclada antes do arquivamento.
Finalize
/opsx:archive # Move para arquivamento quando concluído (solicita sincronização de specs se necessário)Quando Atualizar vs. Começar do Zero
Você sempre pode editar sua proposta ou specs antes da implementação. Mas quando refinar se torna "este é um trabalho diferente"?
O que uma Proposta Captura
Uma proposta define três coisas:
- Intenção — Qual problema você está resolvendo?
- Escopo — O que está dentro/fora dos limites?
- Abordagem — Como você vai resolver?
A questão é: qual mudou, e quanto?
Atualize a Mudança Existente Quando:
Mesma intenção, execução refinada
- Você descobre casos de borda que não considerou
- A abordagem precisa de ajustes, mas o objetivo é inalterado
- A implementação revela que o design estava ligeiramente errado
O escopo reduz
- Você percebe que o escopo completo é grande demais, quer lançar o MVP primeiro
- "Adicionar modo escuro" → "Adicionar alternância de modo escuro (preferência do sistema na v2)"
Correções orientadas por aprendizado
- O codebase não está estruturado como você pensava
- Uma dependência não funciona como esperado
- "Usar variáveis CSS" → "Usar o prefixo
dark:do Tailwind em vez disso"
Comece uma Nova Mudança Quando:
Intenção fundamentalmente mudou
- O problema em si é diferente agora
- "Adicionar modo escuro" → "Adicionar sistema abrangente de tema com cores, fontes e espaçamento personalizados"
Escopo explodiu
- A mudança cresceu tanto que é essencialmente um trabalho diferente
- A proposta original seria irreconhecível após as atualizações
- "Corrigir bug de login" → "Reescrever sistema de autenticação"
O original é concluível
- A mudança original pode ser marcada como "concluída"
- O novo trabalho é independente, não um refinamento
- Completar "Adicionar modo escuro MVP" → Arquivar → Nova mudança "Melhorar modo escuro"
As Heurísticas
┌─────────────────────────────────────┐
│ É o mesmo trabalho? │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
Mesma intenção? >50% sobreposição? O original pode
Mesmo problema? Mesmo escopo? ser "concluído" sem
│ │ essas mudanças?
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
SIM NÃO SIM NÃO NÃO SIM
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
ATUALIZAR NOVO ATUALIZAR NOVO ATUALIZAR NOVO| Teste | Atualizar | Nova Mudança |
|---|---|---|
| Identidade | "Mesma coisa, refinada" | "Trabalho diferente" |
| Sobreposição de escopo | >50% sobrepõe | <50% sobrepõe |
| Conclusão | Não pode ser "concluído" sem mudanças | Pode terminar o original, novo trabalho é independente |
| História | Cadeia de atualizações conta uma história coerente | Correções confundiriam mais do que esclareceriam |
O Princípio
Atualizar preserva contexto. Nova mudança fornece clareza.
Escolha atualizar quando a história do seu pensamento é valiosa. Escolha novo quando começar do zero seria mais claro do que corrigir.
Pense nisso como branches no git:
- Continue commitando enquanto trabalha no mesmo recurso
- Inicie um novo branch quando for genuinamente um trabalho novo
- Às vezes, mescle um recurso parcial e comece do zero para a fase 2
O que mudou?
Legado (/openspec:proposal) | OPSX (/opsx:*) | |
|---|---|---|
| Estrutura | Um único documento grande de proposta | Artefatos discretos com dependências |
| Fluxo de trabalho | Fases lineares: planejar → implementar → arquivar | Ações fluidas — faça qualquer coisa a qualquer momento |
| Iteração | Difícil voltar atrás | Atualize os artefatos conforme você aprende |
| Personalização | Estrutura fixa | Baseada em esquema (defina seus próprios artefatos) |
A principal ideia: o trabalho não é linear. O OPSX deixa de fingir que é.
Aprofundamento na Arquitetura
Esta seção explica como o OPSX funciona por baixo dos panos e como ele se compara ao fluxo de trabalho legado. Os exemplos desta seção usam o conjunto de comandos expandido (new, continue, etc.); usuários padrão do core podem mapear o mesmo fluxo para propose → apply → sync → archive.
Filosofia: Fases vs Ações
┌─────────────────────────────────────────────────────────────────────────────┐
│ LEGACY WORKFLOW │
│ (Phase-Locked, All-or-Nothing) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PLANNING │ ───► │ IMPLEMENTING │ ───► │ ARCHIVING │ │
│ │ PHASE │ │ PHASE │ │ PHASE │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ /openspec:proposal /openspec:apply /openspec:archive │
│ │
│ • Creates ALL artifacts at once │
│ • Can't go back to update specs during implementation │
│ • Phase gates enforce linear progression │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX WORKFLOW │
│ (Fluid Actions, Iterative) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ ACTIONS (not phases) │ │
│ │ │ │
│ │ new ◄──► continue ◄──► apply ◄──► archive │ │
│ │ │ │ │ │ │ │
│ │ └──────────┴───────────┴───────────┘ │ │
│ │ any order │ │
│ └────────────────────────────────────────────┘ │
│ │
│ • Create artifacts one at a time OR fast-forward │
│ • Update specs/design/tasks during implementation │
│ • Dependencies enable progress, phases don't exist │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Arquitetura de Componentes
O fluxo de trabalho legado usa modelos codificados em TypeScript:
┌─────────────────────────────────────────────────────────────────────────────┐
│ LEGACY WORKFLOW COMPONENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Hardcoded Templates (TypeScript strings) │
│ │ │
│ ▼ │
│ Tool-specific configurators/adapters │
│ │ │
│ ▼ │
│ Generated Command Files (.claude/commands/openspec/*.md) │
│ │
│ • Fixed structure, no artifact awareness │
│ • Change requires code modification + rebuild │
│ │
└─────────────────────────────────────────────────────────────────────────────┘O OPSX usa esquemas externos e um motor de grafo de dependências:
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX COMPONENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Schema Definitions (YAML) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ name: spec-driven │ │
│ │ artifacts: │ │
│ │ - id: proposal │ │
│ │ generates: proposal.md │ │
│ │ requires: [] ◄── Dependencies │ │
│ │ - id: specs │ │
│ │ generates: specs/**/*.md ◄── Glob patterns │ │
│ │ requires: [proposal] ◄── Enables after proposal │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Artifact Graph Engine │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • Topological sort (dependency ordering) │ │
│ │ • State detection (filesystem existence) │ │
│ │ • Rich instruction generation (templates + context) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Skill Files (.claude/skills/openspec-*/SKILL.md) │
│ │
│ • Cross-editor compatible (Claude Code, Cursor, Devin) │
│ • Skills query CLI for structured data │
│ • Fully customizable via schema files │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Modelo de Grafo de Dependências
Os artefatos formam um grafo acíclico direcionado (DAG). As dependências são habilitadores, não portões:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)
│
▼
┌──────────────┐
│ APPLY PHASE │
│ (requires: │
│ tasks) │
└──────────────┘Transições de estado:
BLOCKED ────────────────► READY ────────────────► DONE
│ │ │
Missing All deps File exists
dependencies are DONE on filesystemFluxo de Informações
Fluxo de trabalho legado — o agente recebe instruções estáticas:
User: "/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ Static instructions: │
│ • Create proposal.md │
│ • Create tasks.md │
│ • Create design.md │
│ • Create delta spec files │
│ │
│ No awareness of what exists or │
│ dependencies between artifacts │
└─────────────────────────────────────────┘
│
▼
Agent creates ALL artifacts in one goOPSX — o agente consulta por contexto rico:
User: "/opsx:continue"
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Step 1: Query current state │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec status --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "artifacts": [ │ │
│ │ {"id": "proposal", "status": "done"}, │ │
│ │ {"id": "specs", "status": "ready"}, ◄── First ready │ │
│ │ {"id": "design", "status": "ready"}, │ │
│ │ {"id": "tasks", "status": "blocked", │ │
│ │ "missingDeps": ["specs", "design"]} │ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 2: Get rich instructions for ready artifact │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec instructions specs --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "template": "# Specification\n\n## ADDED Requirements...", │ │
│ │ "dependencies": [{"id": "proposal", "path": "...", "done": true}│ │
│ │ "unlocks": ["tasks"] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 3: Read dependencies → Create ONE artifact → Show what's unlocked │
└──────────────────────────────────────────────────────────────────────────┘Modelo de Iteração
Fluxo de trabalho legado — iterar é complicado:
┌─────────┐ ┌─────────┐ ┌─────────┐
│/proposal│ ──► │ /apply │ ──► │/archive │
└─────────┘ └─────────┘ └─────────┘
│ │
│ ├── "Wait, the design is wrong"
│ │
│ ├── Options:
│ │ • Edit files manually (breaks context)
│ │ • Abandon and start over
│ │ • Push through and fix later
│ │
│ └── No official "go back" mechanism
│
└── Creates ALL artifacts at onceOPSX — iteração natural:
/opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
│ │ │
│ │ ├── "The design is wrong"
│ │ │
│ │ ▼
│ │ Just edit design.md
│ │ and continue!
│ │ │
│ │ ▼
│ │ /opsx:apply picks up
│ │ where you left off
│ │
│ └── Creates ONE artifact, shows what's unlocked
│
└── Scaffolds change, waits for directionEsquemas Personalizados
Crie fluxos de trabalho personalizados usando os comandos de gerenciamento de esquemas:
# Create a new schema from scratch (interactive)
openspec schema init my-workflow
# Or fork an existing schema as a starting point
openspec schema fork spec-driven my-workflow
# Validate your schema structure
openspec schema validate my-workflow
# See where a schema resolves from (useful for debugging)
openspec schema which my-workflowOs esquemas são armazenados em openspec/schemas/ (local ao projeto, controlados por versão) ou ~/.local/share/openspec/schemas/ (global do usuário).
Estrutura do esquema:
openspec/schemas/research-first/
├── schema.yaml
└── templates/
├── research.md
├── proposal.md
└── tasks.mdExemplo de schema.yaml:
name: research-first
artifacts:
- id: research # Added before proposal
generates: research.md
requires: []
- id: proposal
generates: proposal.md
requires: [research] # Now depends on research
- id: tasks
generates: tasks.md
requires: [proposal]Grafo de Dependências:
research ──► proposal ──► tasksResumo
| Aspecto | Legado | OPSX |
|---|---|---|
| Modelos | TypeScript codificado | YAML externo + Markdown |
| Dependências | Nenhuma (tudo de uma vez) | DAG com ordenação topológica |
| Estado | Modelo mental baseado em fases | Existência no sistema de arquivos |
| Personalização | Editar código-fonte, recompilar | Criar schema.yaml |
| Iteração | Bloqueado por fase | Fluida, edite qualquer coisa |
| Suporte a Editores | Configuradores/adaptadores específicos por ferramenta | Diretório único de skills |
Esquemas
Esquemas definem quais artefatos existem e suas dependências. Atualmente disponíveis:
- spec-driven (padrão): proposta → especificações → design → tarefas
# Listar esquemas disponíveis
openspec schemas
# Ver todos os esquemas com suas fontes de resolução
openspec schema which --all
# Criar um novo esquema interativamente
openspec schema init my-workflow
# Criar um fork de um esquema existente para personalização
openspec schema fork spec-driven my-workflow
# Validar a estrutura do esquema antes do uso
openspec schema validate my-workflowDicas
- Use
/opsx:explorepara pensar em uma ideia antes de se comprometer com uma mudança /opsx:ffquando você sabe o que quer,/opsx:continuequando estiver explorando- Durante
/opsx:apply, se algo estiver errado — corrija o artefato e continue - As tarefas acompanham o progresso por meio de caixas de seleção em
tasks.md - Verifique o status a qualquer momento:
openspec status --change "name"
Feedback
Isto é um rascunho. Isso é intencional — estamos aprendendo o que funciona.
Encontrou um bug? Tem ideias? Junte-se a nós no Discord ou abra uma issue no GitHub.