This guide covers common workflow patterns for OpenSpec and when to use each one. For basic setup, see Getting Started. For command reference, see Commands.
Traditional workflows force you through phases: planning, then implementation, then done. But real work doesn't fit neatly into boxes.
OPSX takes a different approach:
Traditional (phase-locked):
PLANNING ────────► IMPLEMENTING ────────► DONE
│ │
│ "Can't go back" │
└────────────────────┘
OPSX (fluid actions):
proposal ──► specs ──► design ──► plan ──► tasks ──► implement
Key principles:
- Actions, not phases - Commands are things you can do, not stages you're stuck in
- Dependencies are enablers - They show what's possible, not what's required next
Customization: OPSX workflows are driven by schemas that define artifact sequences. See Customization for details on creating custom schemas.
New installs default to core, which provides:
/opsx:explore/opsx:propose/opsx:modify/opsx:apply/opsx:sync/opsx:archive
Typical flow:
/opsx:explore ──► /opsx:propose ──► /opsx:modify ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
(optional) (optional, repeatable)
/opsx:explore is part of the default profile, not an advanced add-on. It's the move to make whenever you have a problem but not yet a plan, which, with an AI assistant, is most of the time.
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 creates no artifacts and writes no code. It's a free, no-stakes conversation that turns a vague worry into a precise change, so the proposal that follows is sharp. Already know exactly what you want? Skip it and go straight to /opsx:propose. Full guide: Explore First.
If you want explicit scaffold-and-build commands (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), enable them with:
openspec config profile
openspec updateWhen you know what you want to build and just need to execute:
/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive
Example conversation:
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
Best for: Small to medium features, bug fixes, straightforward changes.
When work maps to Jira tickets, OpenSpec separates work tracking from behavior specs:
| Layer | Naming | Example |
|---|---|---|
| Change folder | Optional ticket prefix + summary (kebab-case) | cw-1234-add-dark-mode |
| Proposal Impact | Ticket key for traceability | Jira: CW-1234 |
| Spec capability | Behavioral domain only | ui, user-auth |
Do not name spec folders after ticket keys (e.g., specs/cw-1234/). Jira acceptance criteria become requirements inside the appropriate capability spec (e.g., specs/ui/spec.md).
Typical flow:
You: /opsx:propose CW-1234 add dark mode
AI: Found CW-1234: 'Add dark mode'. Creating change from Jira ticket...
✓ proposal.md (Impact: Jira: CW-1234)
✓ specs/ui/spec.md (requirements from Jira ACs)
✓ design.md
✓ plan.md
✓ tasks.md
...
Multiple changes, same ticket: Safe. Create a new change folder for follow-up work (e.g., cw-1234-dark-mode-persistence) and reference the ticket again in Impact. Both changes delta the same capability spec; archive in order.
Parallel changes, different tickets, same capability: Also safe — e.g., cw-1234-add-dark-mode and cw-1235-fix-theme-bug both touch specs/ui/. Use bulk archive to merge in chronological order (see Parallel Changes below).
Requires the Atlassian MCP for automatic ticket import during /opsx:propose and enrichment during /opsx:apply. See MCP Setup for configuration.
Codewalla OpenSpec embeds MCP guidance in generated skills and slash commands. MCPs are optional — workflows skip unavailable servers gracefully.
| MCP | Command | What it does |
|---|---|---|
| Atlassian | /opsx:propose, /opsx:apply |
Import Jira tickets; enrich and cross-check ACs vs tasks |
| Context7 | /opsx:apply |
Fetch current library docs when tasks reference packages (max 3 calls/session) |
| Browser | /opsx:verify |
Screenshots, a11y snapshot, console errors when UI is affected |
Context7 during apply: When a task mentions a library by name or version-specific API, the agent calls resolve-library-id and query-docs before implementing. Pure business-logic tasks skip this step.
Browser during verify: Requires the expanded profile (openspec config profile → enable verify → openspec update). Apply explicitly does not run browser tests — use /opsx:verify afterward.
→ Full setup and troubleshooting: MCP Setup
When requirements are unclear or you need to investigate first:
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply
Example conversation:
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...
Best for: Performance optimization, debugging, architectural decisions, unclear requirements.
Work on multiple changes at once:
Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
│
context switch
│
Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply
Example conversation:
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...
Best for: Parallel work streams, urgent interrupts, team collaboration.
When you have multiple completed changes, 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
Bulk archive detects when multiple changes touch the same specs and resolves conflicts by checking what's actually implemented.
By default, /opsx:apply runs a three-option multiple-choice comprehension quiz on proposal, design, delta specs, plan, and pending tasks before any implementation (5–10 questions, scaled to change size). The CLI exposes comprehension.questionAllocation so plan receives the majority of questions when present. Questions test holistic understanding—motivation, design decisions, code map, requirements, and implementation approach—not task numbers or verbatim checkbox text. You need ≥ 80% to proceed. The CLI blocks openspec instructions apply until a pass is recorded; failed attempts get new questions. Editing plan.md after a pass requires retaking the quiz. You answer the quiz in chat—the agent presents one question at a time and waits; it must not answer for you.
Disable for a project in openspec/config.yaml:
comprehension:
enabled: falseThe recommended completion flow:
/opsx:apply ──► /opsx:verify ──► /opsx:archive
│ │
validates prompts to sync
implementation if needed
/opsx:verify validates implementation against your artifacts across three dimensions:
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
What verify checks:
| Dimension | What it validates |
|---|---|
| Completeness | All tasks done, all requirements implemented, scenarios covered |
| Correctness | Implementation matches spec intent, edge cases handled |
| Coherence | Design decisions reflected in code, patterns consistent |
Verify won't block archive, but it surfaces issues you might want to address first.
/opsx:archive completes the change and moves it to the archive:
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 will prompt if specs aren't synced. It won't block on incomplete tasks, but it will warn you.
| Situation | Use |
|---|---|
| Clear requirements, ready to build | /opsx:ff |
| Exploring, want to review each step | /opsx:continue |
| Want to iterate on proposal before specs | /opsx:continue |
| Time pressure, need to move fast | /opsx:ff |
| Complex change, want control | /opsx:continue |
Rule of thumb: If you can describe the full scope upfront, use /opsx:ff. If you're figuring it out as you go, use /opsx:continue.
A common question: when is updating an existing change okay, and when should you start a new one?
Update the existing change when:
- Same intent, refined execution
- Scope narrows (MVP first, rest later)
- Learning-driven corrections (codebase isn't what you expected)
- Design tweaks based on implementation discoveries
Start a new change when:
- Intent fundamentally changed
- Scope exploded to different work entirely
- Original change can be marked "done" standalone
- Patches would confuse more than clarify
┌─────────────────────────────────────┐
│ 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
Example: "Add dark mode"
- "Need to also support custom themes" → New change (scope exploded)
- "System preference detection is harder than expected" → Update (same intent)
- "Let's ship toggle first, add preferences later" → Update then archive, then new change
One logical unit of work per change. If you're doing "add feature X and also refactor Y", consider two separate changes.
Why it matters:
- Easier to review and understand
- Cleaner archive history
- Can ship independently
- Simpler rollback if needed
Before committing to a change, explore the problem space:
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?
Exploration clarifies thinking before you create artifacts.
Use /opsx:verify to check implementation matches artifacts:
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!
Catches mismatches before you close out the change.
Good names make openspec list useful:
Good: Avoid:
add-dark-mode feature-1
fix-login-redirect update
optimize-product-query changes
implement-2fa wip
For full command details and options, see Commands.
| Command | Purpose | When to Use |
|---|---|---|
/opsx:propose |
Create change + planning artifacts | Fast default path (core profile) |
/opsx:explore |
Think through ideas with the AI | Start here when unsure: unclear requirements, investigation, comparing options |
/opsx:modify |
Revise planning artifacts (pre-apply) | Update proposal, design, plan, tasks, or specs before implementation |
/opsx:new |
Start a change scaffold | Expanded mode, explicit artifact control |
/opsx:continue |
Create next artifact | Expanded mode, step-by-step artifact creation |
/opsx:ff |
Create all planning artifacts | Expanded mode, clear scope |
/opsx:apply |
Implement tasks | Ready to write code |
/opsx:verify |
Validate implementation | Expanded mode, before archiving |
/opsx:sync |
Merge delta specs | Expanded mode, optional |
/opsx:archive |
Complete the change | All work finished |
/opsx:bulk-archive |
Archive multiple changes | Expanded mode, parallel work |
- Commands - Full command reference with options
- MCP Setup - Atlassian, Context7, and browser MCP configuration
- Concepts - Deep dive into specs, artifacts, and schemas
- Customization - Create custom workflows