diff --git a/README.md b/README.md
index 7b6c7354..7e9b406e 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,10 @@
Follow @0xTab on X for updates Β· Join the OpenSpec Discord for help and questions.
+
+ π§ͺ New: Experimental Workflow (OPSX) β schema-driven, hackable, fluid. Iterate on workflows without code changes.
+
+
# OpenSpec
OpenSpec aligns humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. **No API keys required.**
@@ -368,6 +372,44 @@ Run `openspec update` whenever someone switches tools so your agents pick up the
2. **Refresh agent instructions**
- Run `openspec update` inside each project to regenerate AI guidance and ensure the latest slash commands are active.
+## Experimental Features
+
+
+π§ͺ OPSX: Fluid, Iterative Workflow (Claude Code only)
+
+**Why this exists:**
+- Standard workflow is locked down β you can't tweak instructions or customize
+- When AI output is bad, you can't improve the prompts yourself
+- Same workflow for everyone, no way to match how your team works
+
+**What's different:**
+- **Hackable** β edit templates and schemas yourself, test immediately, no rebuild
+- **Granular** β each artifact has its own instructions, test and tweak individually
+- **Customizable** β define your own workflows, artifacts, and dependencies
+- **Fluid** β no phase gates, update any artifact anytime
+
+```
+You can always go back:
+
+ proposal βββ specs βββ design βββ tasks βββ implement
+ β² β² β² β
+ βββββββββββββ΄βββββββββββ΄βββββββββββββββββββββ
+```
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:new` | Start a new change |
+| `/opsx:continue` | Create the next artifact (based on what's ready) |
+| `/opsx:ff` | Fast-forward (all planning artifacts at once) |
+| `/opsx:apply` | Implement tasks, updating artifacts as needed |
+| `/opsx:archive` | Archive when done |
+
+**Setup:** `openspec artifact-experimental-setup`
+
+[Full documentation β](docs/experimental-workflow.md)
+
+
+
## Contributing
- Install dependencies: `pnpm install`
diff --git a/docs/experimental-workflow.md b/docs/experimental-workflow.md
index 10b0b7e4..11404664 100644
--- a/docs/experimental-workflow.md
+++ b/docs/experimental-workflow.md
@@ -6,13 +6,65 @@
## What Is It?
-OPSX is a new way to work with OpenSpec changes. Instead of one big proposal, you build **artifacts** step-by-step:
+OPSX is a **fluid, iterative workflow** for OpenSpec changes. No more rigid phases β just actions you can take anytime.
+## Why This Exists
+
+The standard OpenSpec workflow works, but it's **locked down**:
+
+- **Instructions are hardcoded** β buried in TypeScript, you can't change them
+- **All-or-nothing** β one big command creates everything, can't test individual pieces
+- **Fixed structure** β same workflow for everyone, no customization
+- **Black box** β when AI output is bad, you can't tweak the prompts
+
+**OPSX opens it up.** Now anyone can:
+
+1. **Experiment with instructions** β edit a template, see if the AI does better
+2. **Test granularly** β validate each artifact's instructions independently
+3. **Customize workflows** β define your own artifacts and dependencies
+4. **Iterate quickly** β change a template, test immediately, no rebuild
+
+```
+Standard workflow: OPSX:
+ββββββββββββββββββββββββββ ββββββββββββββββββββββββββ
+β Hardcoded in package β β schema.yaml ββββ You edit this
+β (can't change) β β templates/*.md ββββ Or this
+β β β β β β
+β Wait for new release β β Instant effect β
+β β β β β β
+β Hope it's better β β Test it yourself β
+ββββββββββββββββββββββββββ ββββββββββββββββββββββββββ
```
-proposal β specs β design β tasks β implementation β archive
+
+**This is for everyone:**
+- **Teams** β create workflows that match how you actually work
+- **Power users** β tweak prompts to get better AI outputs for your codebase
+- **OpenSpec contributors** β experiment with new approaches without releases
+
+We're all still learning what works best. OPSX lets us learn together.
+
+## The User Experience
+
+**The problem with linear workflows:**
+You're "in planning phase", then "in implementation phase", then "done". But real work doesn't work that way. You implement something, realize your design was wrong, need to update specs, continue implementing. Linear phases fight against how work actually happens.
+
+**OPSX approach:**
+- **Actions, not phases** β create, implement, update, archive β do any of them anytime
+- **Dependencies are enablers** β they show what's possible, not what's required next
+- **Update as you learn** β halfway through implementation? Go back and fix the design. That's normal.
+
```
+You can always go back:
-Each artifact has dependencies. Can't write tasks until you have specs. Can't implement until you have tasks. The system tracks what's ready and what's blocked.
+ ββββββββββββββββββββββββββββββββββββββ
+ β β
+ βΌ β
+ proposal βββ specs βββ design βββ tasks βββ implement
+ β² β² β² β
+ β β β β
+ βββββββββββββ΄βββββββββββ΄ββββββββββββββββ
+ update as you learn
+```
## Setup
@@ -31,9 +83,9 @@ This creates skills in `.claude/skills/` that Claude Code auto-detects.
| Command | What it does |
|---------|--------------|
| `/opsx:new` | Start a new change |
-| `/opsx:continue` | Create the next artifact |
-| `/opsx:ff` | Fast-forward (create all artifacts at once) |
-| `/opsx:apply` | Implement the tasks |
+| `/opsx:continue` | Create the next artifact (based on what's ready) |
+| `/opsx:ff` | Fast-forward β create all planning artifacts at once |
+| `/opsx:apply` | Implement tasks, updating artifacts as needed |
| `/opsx:sync` | Sync delta specs to main specs |
| `/opsx:archive` | Archive when done |
@@ -45,44 +97,417 @@ This creates skills in `.claude/skills/` that Claude Code auto-detects.
```
You'll be asked what you want to build and which workflow schema to use.
-### Build artifacts step-by-step
+### Create artifacts
```
/opsx:continue
```
-Creates one artifact at a time. Good for reviewing each step.
+Shows what's ready to create based on dependencies, then creates one artifact. Use repeatedly to build up your change incrementally.
-### Or fast-forward
```
/opsx:ff add-dark-mode
```
-Creates all artifacts in one go. Good when you know what you want.
+Creates all planning artifacts at once. Use when you have a clear picture of what you're building.
-### Implement
+### Implement (the fluid part)
```
/opsx:apply
```
-Works through tasks, checking them off as you go.
+Works through tasks, checking them off as you go. **Key difference:** if you discover issues during implementation, you can update your specs, design, or tasks β then continue. No phase gates.
-### Sync specs and archive
+### Finish up
```
/opsx:sync # Update main specs with your delta specs
/opsx:archive # Move to archive when done
```
+## When to Update vs. Start Fresh
+
+OPSX lets you update artifacts anytime. But when does "update as you learn" become "this is different work"?
+
+### What a Proposal Captures
+
+A proposal defines three things:
+1. **Intent** β What problem are you solving?
+2. **Scope** β What's in/out of bounds?
+3. **Approach** β How will you solve it?
+
+The question is: which changed, and by how much?
+
+### Update the Existing Change When:
+
+**Same intent, refined execution**
+- You discover edge cases you didn't consider
+- The approach needs tweaking but the goal is unchanged
+- Implementation reveals the design was slightly off
+
+**Scope narrows**
+- You realize full scope is too big, want to ship MVP first
+- "Add dark mode" β "Add dark mode toggle (system preference in v2)"
+
+**Learning-driven corrections**
+- Codebase isn't structured how you thought
+- A dependency doesn't work as expected
+- "Use CSS variables" β "Use Tailwind's dark: prefix instead"
+
+### Start a New Change When:
+
+**Intent fundamentally changed**
+- The problem itself is different now
+- "Add dark mode" β "Add comprehensive theme system with custom colors, fonts, spacing"
+
+**Scope exploded**
+- Change grew so much it's essentially different work
+- Original proposal would be unrecognizable after updates
+- "Fix login bug" β "Rewrite auth system"
+
+**Original is completable**
+- The original change can be marked "done"
+- New work stands alone, not a refinement
+- Complete "Add dark mode MVP" β Archive β New change "Enhance dark mode"
+
+### The Heuristics
+
+```
+ βββββββββββββββββββββββββββββββββββββββ
+ β 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
+```
+
+| Test | Update | New Change |
+|------|--------|------------|
+| **Identity** | "Same thing, refined" | "Different work" |
+| **Scope overlap** | >50% overlaps | <50% overlaps |
+| **Completion** | Can't be "done" without changes | Can finish original, new work stands alone |
+| **Story** | Update chain tells coherent story | Patches would confuse more than clarify |
+
+### The Principle
+
+> **Update preserves context. New change provides clarity.**
+>
+> Choose update when the history of your thinking is valuable.
+> Choose new when starting fresh would be clearer than patching.
+
+Think of it like git branches:
+- Keep committing while working on the same feature
+- Start a new branch when it's genuinely new work
+- Sometimes merge a partial feature and start fresh for phase 2
+
## What's Different?
-**Standard workflow** (`/openspec:proposal`):
-- One big proposal document
-- Linear phases: plan β implement β archive
-- All-or-nothing artifact creation
+| | Standard (`/openspec:proposal`) | Experimental (`/opsx:*`) |
+|---|---|---|
+| **Structure** | One big proposal document | Discrete artifacts with dependencies |
+| **Workflow** | Linear phases: plan β implement β archive | Fluid actions β do anything anytime |
+| **Iteration** | Awkward to go back | Update artifacts as you learn |
+| **Customization** | Fixed structure | Schema-driven (define your own artifacts) |
+
+**The key insight:** work isn't linear. OPSX stops pretending it is.
+
+## Architecture Deep Dive
+
+This section explains how OPSX works under the hood and how it compares to the standard workflow.
+
+### Philosophy: Phases vs Actions
+
+```
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β STANDARD 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 ββββΊ sync β β
+β β β β β β β β
+β β ββββββββββββ΄ββββββββββββ΄βββββββββββ β β
+β β any order β β
+β ββββββββββββββββββββββββββββββββββββββββββββββ β
+β β
+β β’ Create artifacts one at a time OR fast-forward β
+β β’ Update specs/design/tasks during implementation β
+β β’ Dependencies enable progress, phases don't exist β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+```
+
+### Component Architecture
+
+**Standard workflow** uses hardcoded templates in TypeScript:
+
+```
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β STANDARD WORKFLOW COMPONENTS β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β β
+β Hardcoded Templates (TypeScript strings) β
+β β β
+β βΌ β
+β Configurators (18+ classes, one per editor) β
+β β β
+β βΌ β
+β Generated Command Files (.claude/commands/openspec/*.md) β
+β β
+β β’ Fixed structure, no artifact awareness β
+β β’ Change requires code modification + rebuild β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+```
+
+**OPSX** uses external schemas and a dependency graph engine:
+
+```
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β 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, Windsurf) β
+β β’ Skills query CLI for structured data β
+β β’ Fully customizable via schema files β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+```
+
+### Dependency Graph Model
+
+Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, not gates:
+
+```
+ proposal
+ (root node)
+ β
+ βββββββββββββββ΄ββββββββββββββ
+ β β
+ βΌ βΌ
+ specs design
+ (requires: (requires:
+ proposal) proposal)
+ β β
+ βββββββββββββββ¬ββββββββββββββ
+ β
+ βΌ
+ tasks
+ (requires:
+ specs, design)
+ β
+ βΌ
+ ββββββββββββββββ
+ β APPLY PHASE β
+ β (requires: β
+ β tasks) β
+ ββββββββββββββββ
+```
+
+**State transitions:**
+
+```
+ BLOCKED βββββββββββββββββΊ READY βββββββββββββββββΊ DONE
+ β β β
+ Missing All deps File exists
+ dependencies are DONE on filesystem
+```
+
+### Information Flow
+
+**Standard workflow** β agent receives static instructions:
+
+```
+ User: "/openspec:proposal"
+ β
+ βΌ
+ βββββββββββββββββββββββββββββββββββββββββββ
+ β Static instructions: β
+ β β’ Create proposal.md β
+ β β’ Create tasks.md β
+ β β’ Create design.md β
+ β β’ Create specs/*.md β
+ β β
+ β No awareness of what exists or β
+ β dependencies between artifacts β
+ βββββββββββββββββββββββββββββββββββββββββββ
+ β
+ βΌ
+ Agent creates ALL artifacts in one go
+```
+
+**OPSX** β agent queries for rich context:
+
+```
+ 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"]}β β
+ β β ] β β
+ β β } β β
+ β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
+ β β
+ β 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 β
+ ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+```
+
+### Iteration Model
+
+**Standard workflow** β awkward to iterate:
+
+```
+ βββββββββββ βββββββββββ βββββββββββ
+ β/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 once
+```
+
+**OPSX** β natural iteration:
+
+```
+ /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 direction
+```
+
+### Custom Schemas
+
+Create your own workflow by adding a schema to `~/.local/share/openspec/schemas/`:
+
+```
+~/.local/share/openspec/schemas/research-first/
+βββ schema.yaml
+βββ templates/
+ βββ research.md
+ βββ proposal.md
+ βββ tasks.md
+
+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] β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+Dependency Graph:
+
+ research βββΊ proposal βββΊ tasks
+```
-**Experimental workflow** (`/opsx:*`):
-- Discrete artifacts with dependencies
-- Fluid actions (not phases) - update artifacts anytime
-- Step-by-step or fast-forward
-- Schema-driven (can customize the workflow)
+### Summary
-The key insight: work isn't linear. You implement, realize the design is wrong, update it, continue. OPSX supports this.
+| Aspect | Standard | OPSX |
+|--------|----------|------|
+| **Templates** | Hardcoded TypeScript | External YAML + Markdown |
+| **Dependencies** | None (all at once) | DAG with topological sort |
+| **State** | Phase-based mental model | Filesystem existence |
+| **Customization** | Edit source, rebuild | Create schema.yaml |
+| **Iteration** | Phase-locked | Fluid, edit anything |
+| **Editor Support** | 18+ configurator classes | Single skills directory |
## Schemas
@@ -95,13 +520,13 @@ Run `openspec schemas` to see available schemas.
## Tips
-- Use `/opsx:ff` when you have a clear idea, `/opsx:continue` when exploring
+- `/opsx:ff` when you know what you want, `/opsx:continue` when exploring
+- During `/opsx:apply`, if something's wrong β fix the artifact, then continue
- Tasks track progress via checkboxes in `tasks.md`
-- Delta specs (in `specs/`) get synced to main specs with `/opsx:sync`
-- If you get stuck, the status command shows what's blocked: `openspec status --change "name"`
+- Check status anytime: `openspec status --change "name"`
## Feedback
-This is rough. That's intentional - we're learning what works.
+This is rough. That's intentional β we're learning what works.
Found a bug? Have ideas? Join us on [Discord](https://discord.gg/BYjPaKbqMt) or open an issue on [GitHub](https://github.com/Fission-AI/openspec/issues).