Flussi di lavoro

Questa guida copre i modelli di flusso di lavoro comuni per OpenSpec e quando utilizzarli. Per la configurazione di base, consulta Per iniziare. Per il riferimento ai comandi, consulta Comandi.

Filosofia: Azioni, non fasi

I flussi di lavoro tradizionali ti obbligano a passare attraverso fasi: pianificazione, poi implementazione, poi completamento. Ma il lavoro reale non si adatta perfettamente a compartimenti stagni.

OPSX adotta un approccio diverso:

text

Tradizionale (bloccato per fasi):

  PIANIFICAZIONE ────────► IMPLEMENTAZIONE ────────► COMPLETATO
      │                    │
      │   "Non puoi tornare indietro"  │
      └────────────────────┘

OPSX (azioni fluide):

  proposta ──► specifiche ──► progettazione ──► compiti ──► implementazione

Principi chiave:

Azioni, non fasi - I comandi sono cose che puoi fare, non stadi in cui sei bloccato
Le dipendenze sono abilitatori - Mostrano cosa è possibile, non cosa è richiesto obbligatoriamente

Personalizzazione: I flussi di lavoro OPSX sono guidati da schemi che definiscono sequenze di artefatti. Consulta Personalizzazione per dettagli sulla creazione di schemi personalizzati.

Flusso di lavoro in sintesi

Il flusso di lavoro predefinito rimane fluido: esplorazione e verifica sono facoltative, e puoi aggiornare gli artefatti di pianificazione ogni volta che l'implementazione rivela qualcosa di nuovo.

mermaid

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

L'assistente AI guida il flusso di lavoro, mentre la CLI fornisce impalcatura deterministica, stato e istruzioni sugli artefatti:

mermaid

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

Due modalità

Percorso rapido predefinito (profilo `core`)

Le nuove installazioni impostano di default core, che fornisce:

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

Flusso tipico:

text

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

Inizia esplorando (l'abitudine che vale la pena formare)

/opsx:explore fa parte del profilo predefinito, non è un componente aggiuntivo avanzato. È la mossa da fare ogni volta che hai un problema ma non ancora un piano, il che, con un assistente AI, è la maggior parte delle volte.

text

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 non crea artefatti e non scrive codice. È una conversazione libera, senza rischi, che trasforma un dubbio vago in una modifica precisa, così la proposta che segue è mirata. Sai già esattamente cosa vuoi? Saltalo e vai direttamente a /opsx:propose. Guida completa: Explore First.

Flusso di lavoro esteso/completo (selezione personalizzata)

Se desideri comandi espliciti di impalcatura e costruzione (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), abilitali con:

bash

openspec config profile
openspec update

Pattern di flusso di lavoro (modalità estesa)

Funzionalità rapida

Quando sai cosa vuoi costruire e devi solo eseguire:

text

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

Esempio di conversazione:

text

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

Ideale per: Funzionalità piccole o medie, correzioni di bug, modifiche semplici.

Esplorativo

Quando i requisiti non sono chiari o devi prima indagare:

text

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

Esempio di conversazione:

text

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...

Ideale per: Ottimizzazione delle prestazioni, debug, decisioni architetturali, requisiti non chiari.

Modifiche parallele

Lavora su più modifiche contemporaneamente:

text

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

Esempio di conversazione:

text

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...

Ideale per: Flussi di lavoro paralleli, interruzioni urgenti, collaborazione di squadra.

Quando hai più modifiche completate, usa /opsx:bulk-archive:

text

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

L'archiviazione in blocco rileva quando più modifiche toccano le stesse specifiche e risolve i conflitti verificando cosa è effettivamente implementato.

Completamento di una modifica

Il flusso di completamento consigliato:

text

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

Verify: controlla il tuo lavoro

/opsx:verify valida l'implementazione rispetto ai tuoi artefatti su tre dimensioni:

text

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

Cosa verifica:

Dimensione	Cosa valida
Completezza	Tutti i compiti completati, tutti i requisiti implementati, scenari coperti
Correttezza	L'implementazione corrisponde all'intento delle specifiche, casi limite gestiti
Coerenza	Le decisioni di design riflesse nel codice, pattern coerenti

Verify non blocca l'archiviazione, ma evidenzia problemi che potresti voler affrontare prima.

Archive: finalizza l'archiviazione

/opsx:archive completa la modifica e la sposta nell'archivio:

text

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.

Archive solleciterà se le specifiche non sono sincronizzate. Non blocca su compiti incompleti, ma ti avviserà.

Quando usare cosa

`/opsx:ff` vs `/opsx:continue`

Situazione	Usa
Requisiti chiari, pronto a costruire	`/opsx:ff`
Esplorazione, vuoi rivedere ogni passo	`/opsx:continue`
Vuoi iterare sulla proposta prima delle specifiche	`/opsx:continue`
Pressione di tempo, devi procedere in fretta	`/opsx:ff`
Modifica complessa, vuoi il controllo	`/opsx:continue`

Regola pratica: Se puoi descrivere l'intero ambito in anticipo, usa /opsx:ff. Se stai capendo le cose man mano che procedi, usa /opsx:continue.

Quando aggiornare vs iniziare da zero

Una domanda comune: quando è accettabile aggiornare una modifica esistente e quando dovresti iniziare una nuova?

Aggiorna l'esistente quando:

Stessa intenzione, esecuzione raffinata
L'ambito si restringe (prima MVP, il resto dopo)
Correzioni basate sull'apprendimento (il codice non è come ti aspettavi)
Ritocchi di design basati sulle scoperte dell'implementazione

Inizia una nuova modifica quando:

L'intenzione è cambiata fondamentalmente
L'ambito è esploso in lavoro completamente diverso
La modifica originale può essere marcata come "completata" in autonomia
Le patch confonderebbero più di quanto chiariscano

text

                     ┌─────────────────────────────────────┐
                     │     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

Esempio: "Aggiungi dark mode"

"Devo anche supportare temi personalizzati" → Nuova modifica (ambito esploso)
"Il rilevamento delle preferenze di sistema è più difficile del previsto" → Aggiornamento (stessa intenzione)
"Lasciamo prima il toggle, aggiungiamo le preferenze dopo" → Aggiornamento poi archiviazione, poi nuova modifica

Best Practices

Mantieni le modifiche focalizzate

Un'unità logica di lavoro per ogni modifica. Se stai facendo "aggiungi la funzionalità X e rifattorizza anche Y", considera due modifiche separate.

Perché è importante:

Più facile da revisionare e comprendere
Storico di archiviazione più pulito
Possibilità di rilasciare indipendentemente
Rollback più semplice se necessario

Usa `/opsx:explore` per requisiti non chiari

Prima di impegnarti in una modifica, esplora lo spazio del problema:

text

You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle rate limiting for our API?

AI:  Let me investigate your current setup and options...
     [Researches codebase, considers patterns]

     I see three approaches we could take:
     1. Middleware-based (simple, per-endpoint)
     2. Redis-backed (scalable, shared state)
     3. Token bucket per user (fair, complex)

     Your current stack suggests #1 or #2. What's your scale?

L'esplorazione chiarisce il ragionamento prima di creare artefatti.

Verifica prima di archiviare

Usa /opsx:verify per controllare che l'implementazione corrisponda agli artefatti:

text

You: /opsx:verify

AI:  Verifying add-dark-mode...

     ✓ All tasks in tasks.md are checked
     ✓ Requirements in specs have corresponding code
     ✓ Design decisions are reflected in implementation

     Ready to archive!

Rileva le discrepanze prima di chiudere la modifica.

Dai nomi chiari alle modifiche

Nomi ben scelti rendono openspec list utile:

text

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

Riferimento rapido dei comandi

Per i dettagli completi e le opzioni dei comandi, consulta Commands.

Comando	Scopo	Quando usarlo
`/opsx:propose`	Crea modifica + artefatti di pianificazione	Percorso predefinito rapido (profilo `core`)
`/opsx:explore`	Rifletti sulle idee con l'AI	Inizia qui quando sei incerto: requisiti non chiari, indagine, confronto tra opzioni
`/opsx:new`	Avvia lo scaffold di una modifica	Modalità espansa, controllo esplicito degli artefatti
`/opsx:continue`	Crea l'artefatto successivo	Modalità espansa, creazione degli artefatti passo dopo passo
`/opsx:ff`	Crea tutti gli artefatti di pianificazione	Modalità espansa, ambito chiaro
`/opsx:apply`	Implementa i task	Pronto a scrivere codice
`/opsx:verify`	Convalida l'implementazione	Modalità espansa, prima dell'archiviazione
`/opsx:sync`	Unisce le specifiche delta	Modalità espansa, facoltativo
`/opsx:archive`	Completa la modifica	Tutto il lavoro è terminato
`/opsx:bulk-archive`	Archivia più modifiche	Modalità espansa, lavoro parallelo

Prossimi passi

Writing Good Specs - Come appare un requisito e uno scenario solidi e come dimensionare correttamente una modifica
Reviewing a Change - La revisione di due minuti su un piano bozza prima di scrivere codice
OpenSpec on a Team - Come le modifiche si integrano con i rami e le pull request
Commands - Riferimento completo dei comandi con opzioni
Concepts - Approfondimento su specifiche, artefatti e schemi
Customization - Crea flussi di lavoro personalizzati

Flussi di lavoro ​

Filosofia: Azioni, non fasi ​

Flusso di lavoro in sintesi ​

Due modalità ​

Percorso rapido predefinito (profilo core) ​

Inizia esplorando (l'abitudine che vale la pena formare) ​

Flusso di lavoro esteso/completo (selezione personalizzata) ​

Pattern di flusso di lavoro (modalità estesa) ​

Funzionalità rapida ​

Esplorativo ​

Modifiche parallele ​

Completamento di una modifica ​

Verify: controlla il tuo lavoro ​

Archive: finalizza l'archiviazione ​

Quando usare cosa ​

/opsx:ff vs /opsx:continue ​

Quando aggiornare vs iniziare da zero ​

Best Practices ​

Mantieni le modifiche focalizzate ​

Usa /opsx:explore per requisiti non chiari ​

Verifica prima di archiviare ​

Dai nomi chiari alle modifiche ​

Riferimento rapido dei comandi ​

Prossimi passi ​

Flussi di lavoro

Filosofia: Azioni, non fasi

Flusso di lavoro in sintesi

Due modalità

Percorso rapido predefinito (profilo `core`)

Inizia esplorando (l'abitudine che vale la pena formare)

Flusso di lavoro esteso/completo (selezione personalizzata)

Pattern di flusso di lavoro (modalità estesa)

Funzionalità rapida

Esplorativo

Modifiche parallele

Completamento di una modifica

Verify: controlla il tuo lavoro

Archive: finalizza l'archiviazione

Quando usare cosa

`/opsx:ff` vs `/opsx:continue`

Quando aggiornare vs iniziare da zero

Best Practices

Mantieni le modifiche focalizzate

Usa `/opsx:explore` per requisiti non chiari

Verifica prima di archiviare

Dai nomi chiari alle modifiche

Riferimento rapido dei comandi

Prossimi passi