From 10e91cf77e2d37a7c1fd037f1ed79c956be347dc Mon Sep 17 00:00:00 2001
From: Tabish Bidiwale <tabishbidiwale@gmail.com>
Date: Thu, 8 Jan 2026 17:48:51 -0800
Subject: [PATCH 1/6] docs: add OPSX experimental workflow visibility to README

Add a subtle banner near the top and an Experimental Features section
before Contributing to draw attention to the new OPSX workflow.
---
 README.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/README.md b/README.md
index 7b6c7354d..691bc332c 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,10 @@
   Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">OpenSpec Discord</a> for help and questions.
 </p>
 
+<p align="center">
+  <sub>🧪 <strong>New:</strong> Try the <a href="docs/experimental-workflow.md">Experimental Workflow (OPSX)</a> — step-by-step artifact creation for Claude Code</sub>
+</p>
+
 # 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,31 @@ 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
+
+<details>
+<summary><strong>🧪 OPSX: Artifact-Driven Workflow</strong> (Claude Code only)</summary>
+
+A new way to build changes step-by-step:
+
+```
+proposal → specs → design → tasks → implementation → archive
+```
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:new` | Start a new change |
+| `/opsx:continue` | Create the next artifact |
+| `/opsx:ff` | Fast-forward (all artifacts at once) |
+| `/opsx:apply` | Implement the tasks |
+| `/opsx:archive` | Archive when done |
+
+**Setup:** `openspec artifact-experimental-setup`
+
+[Full documentation →](docs/experimental-workflow.md)
+
+</details>
+
 ## Contributing
 
 - Install dependencies: `pnpm install`

From 12ef8ef3578d03c9f1ca20faa156ccd10ffd4101 Mon Sep 17 00:00:00 2001
From: Tabish Bidiwale <tabishbidiwale@gmail.com>
Date: Thu, 8 Jan 2026 17:59:53 -0800
Subject: [PATCH 2/6] docs: reframe OPSX messaging around fluid iteration

Update messaging to emphasize the core value proposition:
- No phases, just actions
- Dependencies are enablers, not gates
- Update artifacts as you learn during implementation

The previous "step-by-step artifact creation" framing incorrectly
suggested more bureaucracy. OPSX is about less rigidity, not more.
---
 README.md                     | 20 +++++++----
 docs/experimental-workflow.md | 68 ++++++++++++++++++++---------------
 2 files changed, 52 insertions(+), 36 deletions(-)

diff --git a/README.md b/README.md
index 691bc332c..932aab1ef 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@
 </p>
 
 <p align="center">
-  <sub>🧪 <strong>New:</strong> Try the <a href="docs/experimental-workflow.md">Experimental Workflow (OPSX)</a> — step-by-step artifact creation for Claude Code</sub>
+  <sub>🧪 <strong>New:</strong> <a href="docs/experimental-workflow.md">Experimental Workflow (OPSX)</a> — fluid, iterative changes. No phases, just actions.</sub>
 </p>
 
 # OpenSpec
@@ -375,20 +375,26 @@ Run `openspec update` whenever someone switches tools so your agents pick up the
 ## Experimental Features
 
 <details>
-<summary><strong>🧪 OPSX: Artifact-Driven Workflow</strong> (Claude Code only)</summary>
+<summary><strong>🧪 OPSX: Fluid, Iterative Workflow</strong> (Claude Code only)</summary>
 
-A new way to build changes step-by-step:
+**The problem:** Linear phases (plan → implement → archive) fight against how work actually happens. You implement, realize the design is wrong, need to update it, continue.
+
+**OPSX approach:** No phases, just actions. Create artifacts, implement tasks, update as you learn — in any order.
 
 ```
-proposal → specs → design → tasks → implementation → archive
+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 |
-| `/opsx:ff` | Fast-forward (all artifacts at once) |
-| `/opsx:apply` | Implement the tasks |
+| `/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`
diff --git a/docs/experimental-workflow.md b/docs/experimental-workflow.md
index 10b0b7e4c..1716e9a1e 100644
--- a/docs/experimental-workflow.md
+++ b/docs/experimental-workflow.md
@@ -6,14 +6,29 @@
 
 ## 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.
+
+**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.
 
 ```
-proposal → specs → design → tasks → implementation → archive
+You can always go back:
+
+     ┌────────────────────────────────────┐
+     │                                    │
+     ▼                                    │
+  proposal ──→ specs ──→ design ──→ tasks ──→ implement
+     ▲           ▲          ▲               │
+     │           │          │               │
+     └───────────┴──────────┴───────────────┘
+              update as you learn
 ```
 
-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.
-
 ## Setup
 
 ```bash
@@ -31,9 +46,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,25 +60,24 @@ 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
@@ -71,18 +85,14 @@ Works through tasks, checking them off as you go.
 
 ## What's Different?
 
-**Standard workflow** (`/openspec:proposal`):
-- One big proposal document
-- Linear phases: plan → implement → archive
-- All-or-nothing artifact creation
-
-**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)
+| | 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. You implement, realize the design is wrong, update it, continue. OPSX supports this.
+**The key insight:** work isn't linear. OPSX stops pretending it is.
 
 ## Schemas
 
@@ -95,13 +105,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).

From 4af1a111bff8caf9b2e8d6d9d05982ab96184fe0 Mon Sep 17 00:00:00 2001
From: Tabish Bidiwale <tabishbidiwale@gmail.com>
Date: Thu, 8 Jan 2026 18:17:17 -0800
Subject: [PATCH 3/6] docs: add architecture deep dive with ASCII diagrams

Add comprehensive comparison of standard vs OPSX workflow architecture:
- Philosophy: phases vs actions
- Component architecture diagrams
- Dependency graph model
- Information flow comparison
- Iteration model comparison
- Custom schema example
---
 docs/experimental-workflow.md | 292 ++++++++++++++++++++++++++++++++++
 1 file changed, 292 insertions(+)

diff --git a/docs/experimental-workflow.md b/docs/experimental-workflow.md
index 1716e9a1e..9e0c0431c 100644
--- a/docs/experimental-workflow.md
+++ b/docs/experimental-workflow.md
@@ -94,6 +94,298 @@ Works through tasks, checking them off as you go. **Key difference:** if you dis
 
 **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
+```
+
+### Summary
+
+| 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
 
 Schemas define what artifacts exist and their dependencies. Currently available:

From b8b4abbd3494860eed950ff3b1c03e1c8560aba9 Mon Sep 17 00:00:00 2001
From: Tabish Bidiwale <tabishbidiwale@gmail.com>
Date: Thu, 8 Jan 2026 18:21:46 -0800
Subject: [PATCH 4/6] docs: emphasize hackability and experimentation rationale

Add "Why We Built This" section explaining the meta-level motivation:
- Instructions were hardcoded, hard to improve
- Needed granular, testable artifacts
- Wanted to experiment with different workflows without code changes
- OPSX makes the instruction system itself hackable

Update README banner and experimental features section to highlight
schema-driven, hackable nature alongside fluid iteration benefits.
---
 README.md                     | 12 +++++++++---
 docs/experimental-workflow.md | 36 +++++++++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 932aab1ef..305735cd9 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@
 </p>
 
 <p align="center">
-  <sub>🧪 <strong>New:</strong> <a href="docs/experimental-workflow.md">Experimental Workflow (OPSX)</a> — fluid, iterative changes. No phases, just actions.</sub>
+  <sub>🧪 <strong>New:</strong> <a href="docs/experimental-workflow.md">Experimental Workflow (OPSX)</a> — schema-driven, hackable, fluid. Iterate on workflows without code changes.</sub>
 </p>
 
 # OpenSpec
@@ -377,9 +377,15 @@ Run `openspec update` whenever someone switches tools so your agents pick up the
 <details>
 <summary><strong>🧪 OPSX: Fluid, Iterative Workflow</strong> (Claude Code only)</summary>
 
-**The problem:** Linear phases (plan → implement → archive) fight against how work actually happens. You implement, realize the design is wrong, need to update it, continue.
+**Why we built this:**
+- Standard workflow instructions are hardcoded — hard to improve or customize
+- We needed granular, testable artifacts with their own instructions
+- We wanted to experiment with different workflows without code changes
 
-**OPSX approach:** No phases, just actions. Create artifacts, implement tasks, update as you learn — in any order.
+**What's different:**
+- **Schema-driven** — workflows defined in YAML, templates in Markdown (edit instantly, no rebuild)
+- **Granular artifacts** — each has its own instructions, dependencies, and templates
+- **Fluid iteration** — no phase gates, update any artifact anytime
 
 ```
 You can always go back:
diff --git a/docs/experimental-workflow.md b/docs/experimental-workflow.md
index 9e0c0431c..488ed5618 100644
--- a/docs/experimental-workflow.md
+++ b/docs/experimental-workflow.md
@@ -8,6 +8,42 @@
 
 OPSX is a **fluid, iterative workflow** for OpenSpec changes. No more rigid phases — just actions you can take anytime.
 
+## Why We Built This
+
+The standard OpenSpec workflow works, but it's **hard to improve**:
+
+- **Instructions are hardcoded** — buried in TypeScript strings, changing them requires code changes and a release
+- **All-or-nothing** — one big command creates everything, hard to test individual pieces
+- **Fixed structure** — same workflow for everyone, no way to customize for your team's needs
+- **Opaque failures** — when something goes wrong, hard to know which part of the instructions failed
+
+We needed a system where we could:
+
+1. **Experiment with instructions** — try different prompts, see what works better
+2. **Test granularly** — validate each artifact's instructions independently
+3. **Customize workflows** — let teams define their own artifacts and dependencies
+4. **Iterate quickly** — change a template, test it immediately, no rebuild needed
+
+**OPSX makes the instruction system itself hackable:**
+
+```
+Standard workflow:                    OPSX:
+┌────────────────────────┐           ┌────────────────────────┐
+│  Hardcoded TypeScript  │           │  schema.yaml           │◄── Edit this
+│  strings               │           │  templates/*.md        │◄── Or this
+│        ↓               │           │        ↓               │
+│  Rebuild package       │           │  Instant effect        │
+│        ↓               │           │        ↓               │
+│  Release new version   │           │  Test immediately      │
+│        ↓               │           │                        │
+│  Users upgrade         │           │  No release needed     │
+└────────────────────────┘           └────────────────────────┘
+```
+
+This matters because **we're still learning what works**. Different instruction styles, different artifact structures, different dependency graphs — we need to be able to try things quickly. OPSX is the foundation for that experimentation.
+
+## 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.
 

From 787de671ccaf5b772810ed5f23d6bf833d6ad6a7 Mon Sep 17 00:00:00 2001
From: Tabish Bidiwale <tabishbidiwale@gmail.com>
Date: Thu, 8 Jan 2026 18:23:26 -0800
Subject: [PATCH 5/6] docs: reframe hackability as user benefit, not just
 internal

OPSX isn't just for OpenSpec devs to experiment - it's for everyone:
- Teams can create workflows that match how they work
- Power users can tweak prompts to get better AI outputs
- Contributors can experiment without releases

Updated framing from "we needed" to "now anyone can".
---
 README.md                     | 15 +++++++-------
 docs/experimental-workflow.md | 39 ++++++++++++++++++-----------------
 2 files changed, 28 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 305735cd9..7e9b406e9 100644
--- a/README.md
+++ b/README.md
@@ -377,15 +377,16 @@ Run `openspec update` whenever someone switches tools so your agents pick up the
 <details>
 <summary><strong>🧪 OPSX: Fluid, Iterative Workflow</strong> (Claude Code only)</summary>
 
-**Why we built this:**
-- Standard workflow instructions are hardcoded — hard to improve or customize
-- We needed granular, testable artifacts with their own instructions
-- We wanted to experiment with different workflows without code changes
+**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:**
-- **Schema-driven** — workflows defined in YAML, templates in Markdown (edit instantly, no rebuild)
-- **Granular artifacts** — each has its own instructions, dependencies, and templates
-- **Fluid iteration** — no phase gates, update any artifact anytime
+- **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:
diff --git a/docs/experimental-workflow.md b/docs/experimental-workflow.md
index 488ed5618..4e9a2ef30 100644
--- a/docs/experimental-workflow.md
+++ b/docs/experimental-workflow.md
@@ -8,39 +8,40 @@
 
 OPSX is a **fluid, iterative workflow** for OpenSpec changes. No more rigid phases — just actions you can take anytime.
 
-## Why We Built This
+## Why This Exists
 
-The standard OpenSpec workflow works, but it's **hard to improve**:
+The standard OpenSpec workflow works, but it's **locked down**:
 
-- **Instructions are hardcoded** — buried in TypeScript strings, changing them requires code changes and a release
-- **All-or-nothing** — one big command creates everything, hard to test individual pieces
-- **Fixed structure** — same workflow for everyone, no way to customize for your team's needs
-- **Opaque failures** — when something goes wrong, hard to know which part of the instructions failed
+- **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
 
-We needed a system where we could:
+**OPSX opens it up.** Now anyone can:
 
-1. **Experiment with instructions** — try different prompts, see what works better
+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** — let teams define their own artifacts and dependencies
-4. **Iterate quickly** — change a template, test it immediately, no rebuild needed
-
-**OPSX makes the instruction system itself hackable:**
+3. **Customize workflows** — define your own artifacts and dependencies
+4. **Iterate quickly** — change a template, test immediately, no rebuild
 
 ```
 Standard workflow:                    OPSX:
 ┌────────────────────────┐           ┌────────────────────────┐
-│  Hardcoded TypeScript  │           │  schema.yaml           │◄── Edit this
-│  strings               │           │  templates/*.md        │◄── Or this
+│  Hardcoded in package  │           │  schema.yaml           │◄── You edit this
+│  (can't change)        │           │  templates/*.md        │◄── Or this
 │        ↓               │           │        ↓               │
-│  Rebuild package       │           │  Instant effect        │
+│  Wait for new release  │           │  Instant effect        │
 │        ↓               │           │        ↓               │
-│  Release new version   │           │  Test immediately      │
-│        ↓               │           │                        │
-│  Users upgrade         │           │  No release needed     │
+│  Hope it's better      │           │  Test it yourself      │
 └────────────────────────┘           └────────────────────────┘
 ```
 
-This matters because **we're still learning what works**. Different instruction styles, different artifact structures, different dependency graphs — we need to be able to try things quickly. OPSX is the foundation for that experimentation.
+**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
 

From 7cf2545a785a1cb10cf07185c652a1d1d83307b0 Mon Sep 17 00:00:00 2001
From: Tabish Bidiwale <tabishbidiwale@gmail.com>
Date: Fri, 9 Jan 2026 11:58:18 -0800
Subject: [PATCH 6/6] docs: add guidance on when to update vs. start fresh

Addresses a common question: when does "update as you learn" become
"this is different work"? Adds heuristics based on intent, scope
overlap, and completability to help users make the judgment call.
---
 docs/experimental-workflow.md | 86 +++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/docs/experimental-workflow.md b/docs/experimental-workflow.md
index 4e9a2ef30..114046648 100644
--- a/docs/experimental-workflow.md
+++ b/docs/experimental-workflow.md
@@ -120,6 +120,92 @@ Works through tasks, checking them off as you go. **Key difference:** if you dis
 /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 (`/openspec:proposal`) | Experimental (`/opsx:*`) |