Fluxos de trabalho

Este guia aborda padrões comuns de fluxo de trabalho para o OpenSpec e quando usar cada um. Para configuração básica, consulte Introdução. Para referência de comandos, consulte Comandos.

Filosofia: Ações, não Fases

Os fluxos de trabalho tradicionais forçam você a passar por fases: planejamento, depois implementação, depois concluído. Mas o trabalho real não se encaixa perfeitamente em caixas.

O OPSX adota uma abordagem diferente:

Tradicional (bloqueado por fase):

  PLANEJAMENTO ────────► IMPLEMENTAÇÃO ────────► CONCLUÍDO
      │                    │
      │   "Não é possível voltar"  │
      └────────────────────┘

OPSX (ações fluidas):

  proposal ──► specs ──► design ──► tasks ──► implement

Princípios fundamentais:

• Ações, não fases - Os comandos são coisas que você pode fazer, não etapas nas quais você está preso
• As dependências são habilitadoras - Elas mostram o que é possível, não o que é necessário fazer em seguida

Personalização: Os fluxos de trabalho do OPSX são orientados por esquemas que definem sequências de artefatos. Consulte Personalização para obter detalhes sobre a criação de esquemas personalizados.

Visão Geral do Fluxo de Trabalho

O fluxo de trabalho padrão permanece fluido: exploração e verificação são opcionais, e você pode atualizar artefatos de planejamento sempre que a implementação revelar algo novo.

flowchart TD
    Idea["Idea or problem"] --> Explore["/opsx:explore<br/>(optional)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Planning artifacts<br/>ready?"}
    Review -->|"Refine"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Implement"| Apply["/opsx:apply"]
    Apply -->|"Plan changed"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(optional, custom selection)"]
    Apply --> Sync["/opsx:sync<br/>(optional before archive)"]
    Verify --> Verified{"Ready to archive?"}
    Verified -->|"Fix implementation"| Apply
    Verified -->|"Revise plan"| Update
    Verified -->|"Ready"| Sync
    Verified -->|"Ready"| Archive
    Sync --> Archive

O assistente de IA conduz o fluxo de trabalho, enquanto a CLI fornece estrutura determinística, status e instruções de artefatos:

sequenceDiagram
    actor Human
    participant Assistant as AI assistant
    participant CLI as OpenSpec CLI
    participant Files as Planning and implementation files

    Human->>Assistant: /opsx:propose "change"
    Assistant->>CLI: openspec new change
    CLI->>Files: Scaffold change metadata
    Assistant->>CLI: Request status and artifact instructions
    CLI-->>Assistant: Build order, paths, and templates
    Assistant->>Files: Write schema-defined planning artifacts
    Assistant-->>Human: Present artifacts for review

    Human->>Assistant: /opsx:apply
    Assistant->>CLI: Request apply instructions
    CLI-->>Assistant: Context files and task state
    Assistant->>Files: Implement tasks and update checkboxes
    Assistant-->>Human: Report implementation status

    Human->>Assistant: /opsx:archive
    Assistant->>CLI: Request archive inputs and artifact status
    CLI-->>Assistant: Planning paths and artifact completion
    Assistant->>Files: Read task state and compare delta specs
    opt Delta specs exist
        Assistant-->>Human: Offer to sync before archiving
        alt Sync accepted
            Human->>Assistant: Confirm sync
            Assistant->>Files: Merge delta specs into main specs
        else Sync skipped
            Human->>Assistant: Archive without syncing
        end
    end
    Assistant->>Files: Move the change into the archive
    Assistant-->>Human: Report archive location and sync result

    Note over Human,CLI: CLI alternative: openspec archive change-name --yes skips confirmation prompts. It still validates, then applies any delta specs and archives

Dois Modos

Caminho Rápido Padrão (perfil core)

Instalações novas usam core por padrão, que fornece:

• /opsx:explore
• /opsx:propose
• /opsx:apply
• /opsx:update
• /opsx:sync
• /opsx:archive

Fluxo típico:

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (optional)

Comece explorando (o hábito que vale a pena formar)

/opsx:explore faz parte do perfil padrão, não é um complemento avançado. É a ação a tomar sempre que você tem um problema mas ainda não tem um plano — o que, com um assistente de IA, acontece na maioria das vezes.

You: /opsx:explore

AI:  What would you like to explore?

You: Our search results feel stale. I'm not sure if it's caching,
     indexing, or the query itself.

AI:  Let me look... [reads the search service and cache layer]
     It's the index: it only rebuilds nightly, so edits don't show
     up until the next day. Two options: rebuild on write (simple,
     more load) or a short-TTL cache invalidation (more moving parts,
     less load). Given your write volume is low, rebuild-on-write is
     the cleaner fix. Want to scope it?

You: Yes.

You: /opsx:propose rebuild-search-index-on-write

Explore não cria artefatos e não escreve código. É uma conversa livre, sem riscos, que transforma uma preocupação vaga em uma mudança precisa, para que a proposta subsequente seja afiada. Já sabe exatamente o que quer? Pule e vá direto para /opsx:propose. Guia completo: Explore First.

Fluxo de Trabalho Expandido/Completo (seleção personalizada)

Se você quiser comandos explícitos de estrutura e construção (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), habilite-os com:

openspec config profile
openspec update

Padrões de Fluxo de Trabalho (Modo Expandido)

Funcionalidade Rápida

Quando você sabe o que quer construir e só precisa executar:

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Exemplo de conversa:

You: /opsx:new add-logout-button

AI:  Created openspec/changes/add-logout-button/
     Ready to create: proposal

You: /opsx:ff

AI:  Creating all planning artifacts...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Ready for implementation!

You: /opsx:apply

AI:  Working through tasks...
     ✓ Added logout button to header
     ✓ Implemented session clearing
     ✓ Added confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  ✓ Merged specs
     ✓ Archived change

Ideal para: Funcionalidades pequenas a médias, correções de bugs, mudanças diretas.

Exploratório

Quando os requisitos são claros ou você precisa investigar primeiro:

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

Exemplo de conversa:

You: /opsx:explore

AI:  What would you like to explore?

You: I want to improve page load performance but I'm not sure
     where the bottlenecks are.

AI:  Let me help investigate...
     [Analyzes bundle sizes, identifies slow queries, reviews
     component render patterns]

     I found three main bottlenecks:
     1. Large unoptimized images
     2. Synchronous data fetching in ProductList
     3. Re-renders from context changes

     Which would you like to address first?

You: Let's tackle the data fetching issue.

You: /opsx:new optimize-product-list-fetching

AI:  Created change. Ready to create: proposal

You: /opsx:continue

AI:  Creating proposal based on our exploration...
     [Writes proposal incorporating investigation insights]

     Ready to create: specs, design
     Which would you like next?

You: /opsx:continue

AI:  Creating specs...

Ideal para: Otimização de desempenho, depuração, decisões arquitetônicas, requisitos não claros.

Mudanças Paralelas

Trabalhe em várias mudanças ao mesmo tempo:

Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
                                         │
                                    context switch
                                         │
Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

Exemplo de conversa:

You: I'm working on add-dark-mode but got pulled into a bug fix

You: /opsx:new fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/

You: /opsx:ff

AI:  ✓ Created planning artifacts

You: /opsx:apply

AI:  Working on fix-login-redirect...
     [Implements the fix]
     All tasks complete!

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect

You: Let's get back to dark mode

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode...
     Picking up at task 2.3: Update Header...

Ideal para: Fluxos de trabalho paralelos, interrupções urgentes, colaboração em equipe.

Quando você tem várias mudanças concluídas, use /opsx:bulk-archive:

You: /opsx:bulk-archive

AI:  Found 3 completed changes:
     - add-dark-mode (all tasks done)
     - fix-login-redirect (all tasks done)
     - update-footer (all tasks done)

     Checking for spec conflicts...
     ⚠ add-dark-mode and update-footer both touch specs/ui/

     Inspecting codebase to resolve...
     Both changes are implemented. Will apply in chronological order.

     Archive all 3 changes?

You: Yes

AI:  ✓ Archived add-dark-mode
     ✓ Archived fix-login-redirect
     ✓ Archived update-footer
     Specs merged in order: add-dark-mode → update-footer

O bulk archive detecta quando várias mudanças tocam as mesmas specs e resolve conflitos verificando o que está realmente implementado.

Concluindo uma Mudança

O fluxo de conclusão recomendado:

/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              validates          prompts to sync
              implementation     if needed

Verify: Verifique Seu Trabalho

/opsx:verify valida a implementação em relação aos seus artefatos em três dimensões:

You: /opsx:verify

AI:  Verifying add-auth...

     COMPLETENESS
     ✓ All 12 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "Session timeout after inactivity" not tested

     CORRECTNESS
     ✓ Implementation matches spec intent
     ✓ Edge cases from scenarios are handled
     ✓ Error states match spec definitions

     COHERENCE
     ✓ Design decisions reflected in code structure
     ✓ Naming conventions consistent with design.md
     ⚠ Design mentions "event-driven" but implementation uses polling

     SUMMARY
     ─────────────────────────────
     Critical issues: 0
     Warnings: 2
     Ready to archive: Yes (with warnings)

     Recommendations:
     1. Add test for session timeout scenario
     2. Consider refactoring to event-driven as designed, or update design.md

O que o verify verifica:

Dimensão	O que valida
Completude	Todas as tarefas concluídas, todos os requisitos implementados, cenários cobertos
Correção	Implementação corresponde à intenção da spec, casos extremos tratados
Coerência	Decisões de design refletidas no código, padrões consistentes

O verify não bloqueia o archive, mas destaca problemas que você pode querer resolver primeiro.

Archive: Finalize a Mudança

/opsx:archive completa a mudança e a move para o arquivo:

You: /opsx:archive

AI:  Archiving add-auth...

     Artifact status:
     ✓ proposal.md exists
     ✓ specs/ exists
     ✓ design.md exists
     ✓ tasks.md exists (12/12 tasks complete)

     Delta specs: Not yet synced to main
     → Would you like to sync now?

You: Yes

AI:  ✓ Synced specs to openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-auth/

     Change archived successfully.

O Archive solicitará confirmação se as specs não estiverem sincronizadas. Não bloqueará por tarefas incompletas, mas emitirá um aviso.

Quando Usar o Que

/opsx:ff vs /opsx:continue

Situação	Use
Requisitos claros, pronto para construir	/opsx:ff
Explorando, quer revisar cada etapa	/opsx:continue
Quer iterar na proposta antes das specs	/opsx:continue
Pressão de tempo, precisa avançar rápido	/opsx:ff
Mudança complexa, quer controle	/opsx:continue

Regra geral: Se você pode descrever o escopo completo antecipadamente, use /opsx:ff. Se está descobrindo conforme avança, use /opsx:continue.

Quando Atualizar vs Começar do Zero

Uma pergunta comum: quando é aceitável atualizar uma mudança existente e quando se deve começar uma nova?

Atualize a mudança existente quando:

• Mesma intenção, execução refinada
• Escopo se estreita (MVP primeiro, resto depois)
• Correções baseadas em aprendizado (a base de código não é o que você esperava)
• Ajustes de design com base em descobertas da implementação

Comece uma nova mudança quando:

• A intenção mudou fundamentalmente
• O escopo explodiu para trabalho completamente diferente
• A mudança original pode ser marcada como "concluída" de forma independente
• Patches confundiriam mais do que esclareceriam

                     ┌─────────────────────────────────────┐
                     │     Is this the same work?          │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          Same intent?      >50% overlap?      Can original
          Same problem?     Same scope?        be "done" without
                 │                  │          these changes?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      YES               NO YES           NO  NO              YES
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    UPDATE            NEW  UPDATE       NEW  UPDATE          NEW

Exemplo: "Adicionar modo escuro"

• "Preciso também suportar temas personalizados" → Nova mudança (escopo explodiu)
• "A detecção de preferência do sistema é mais difícil do que o esperado" → Atualizar (mesma intenção)
• "Vamos lançar o toggle primeiro e adicionar preferências depois" → Atualizar e arquivar, depois nova mudança

Melhores Práticas

Mantenha as Alterações Focadas

Uma unidade lógica de trabalho por alteração. Se você estiver fazendo "adicionar recurso X e também refatorar Y", considere duas alterações separadas.

Por que isso importa:

• Mais fácil de revisar e entender
• Histórico de commits mais limpo
• Pode ser enviado independentemente
• Rollback mais simples, se necessário

Use /opsx:explore para Requisitos Incertos

Antes de confirmar uma alteração, explore o espaço do problema:

Você: /opsx:explore

IA:  O que você gostaria de explorar?

Você: Como devemos lidar com a limitação de taxa (rate limiting) da nossa API?

IA:  Deixe-me investigar sua configuração atual e as opções...
     [Pesquisa a base de código, considera padrões]

     Vejo três abordagens que podemos adotar:
     1. Baseada em middleware (simples, por endpoint)
     2. Com suporte ao Redis (escalável, estado compartilhado)
     3. Bucket de tokens por usuário (justo, complexo)

     Sua pilha tecnológica atual sugere #1 ou #2. Qual é a sua escala?

A exploração esclarece o pensamento antes de criar artefatos.

Verifique Antes de Arquivar

Use /opsx:verify para verificar se a implementação corresponde aos artefatos:

Você: /opsx:verify

IA:  Verificando add-dark-mode...

     ✓ Todas as tarefas em tasks.md estão marcadas
     ✓ Os requisitos em specs têm código correspondente
     ✓ As decisões de design estão refletidas na implementação

     Pronto para arquivar!

Detecta inconsistências antes de encerrar a alteração.

Nomeie as Alterações Claramente

Nomes claros tornam openspec list útil:

Bom:                           Evite:
add-dark-mode                   feature-1
fix-login-redirect              update
optimize-product-query          changes
implement-2fa                   wip

Referência Rápida de Comandos

Para detalhes completos dos comandos e opções, consulte Comandos.

Comando	Propósito	Quando Usar
/opsx:propose	Criar alteração + artefatos de planejamento	Caminho padrão rápido (perfil core)
/opsx:explore	Refletir sobre ideias com a IA	Comece aqui quando houver dúvidas: requisitos incertos, investigação, comparação de opções
/opsx:new	Iniciar estrutura de alteração	Modo expandido, controle explícito de artefatos
/opsx:continue	Criar próximo artefato	Modo expandido, criação passo a passo de artefatos
/opsx:ff	Criar todos os artefatos de planejamento	Modo expandido, escopo claro
/opsx:apply	Implementar tarefas	Pronto para escrever código
/opsx:verify	Validar implementação	Modo expandido, antes de arquivar
/opsx:sync	Mesclar especificações delta	Modo expandido, opcional
/opsx:archive	Concluir a alteração	Todo o trabalho finalizado
/opsx:bulk-archive	Arquivar múltiplas alterações	Modo expandido, trabalho paralelo

Próximos Passos

• Writing Good Specs - Como deve parecer um requisito e um cenário fortes, e como dimensionar adequadamente uma alteração
• Reviewing a Change - Uma revisão rápida de dois minutos em um plano rascunhado antes de qualquer código
• OpenSpec on a Team - Como as alterações se encaixam em branches e pull requests
• Commands - Referência completa de comandos com opções
• Concepts - Aprofundamento em especificações, artefatos e esquemas
• Customization - Crie fluxos de trabalho personalizados