Skip to content

docs: add OPSX experimental workflow visibility to README #460

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TabishB merged 9 commits into from
Jan 10, 2026
Merged

docs: add OPSX experimental workflow visibility to README #460

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
10e91cf
docs: add OPSX experimental workflow visibility to README
TabishB Jan 9, 2026
12ef8ef
docs: reframe OPSX messaging around fluid iteration
TabishB Jan 9, 2026
4af1a11
docs: add architecture deep dive with ASCII diagrams
TabishB Jan 9, 2026
b8b4abb
docs: emphasize hackability and experimentation rationale
TabishB Jan 9, 2026
787de67
docs: reframe hackability as user benefit, not just internal
TabishB Jan 9, 2026
482a4e0
Merge branch 'main' into docs/readme-opsx-visibility
TabishB Jan 9, 2026
7cf2545
docs: add guidance on when to update vs. start fresh
TabishB Jan 9, 2026
384e1a0
Merge branch 'main' into docs/readme-opsx-visibility
TabishB Jan 9, 2026
c2b8027
Merge branch 'main' into docs/readme-opsx-visibility
TabishB Jan 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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> <a href="docs/experimental-workflow.md">Experimental Workflow (OPSX)</a> — fluid, iterative changes. No phases, just actions.</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.**
Expand Down Expand Up @@ -368,6 +372,37 @@ 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: 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.

**OPSX approach:** No phases, just actions. Create artifacts, implement tasks, update as you learn — in any order.

```
You can always go back:

proposal ──→ specs ──→ design ──→ tasks ──→ implement
▲ ▲ ▲ │
└───────────┴──────────┴────────────────────┘
```
Comment on lines +391 to +397
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language specifier to ASCII diagram fenced code block.

The fenced code block containing the workflow diagram is missing a language identifier. Per markdownlint (MD040), specify the language or use text/plaintext for ASCII diagrams.

📝 Proposed fix 
  You can always go back:

- ```
+ ```text
  proposal ──→ specs ──→ design ──→ tasks ──→ implement
     ▲           ▲          ▲                    │
     └───────────┴──────────┴────────────────────┘
</details>

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.18.1)</summary>

391-391: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

In @README.md around lines 391 - 397, The fenced ASCII diagram block is missing
a language specifier (violates MD040); update the triple-backtick fence that
wraps the diagram (the block starting with the ASCII workflow "proposal ──→
specs ──→ design...") to include a language identifier such as text or plaintext
(e.g., change totext) so the diagram is treated as plain text by
markdown linters and renderers.


</details>

<!-- fingerprinting:phantom:triton:mongoose -->

<!-- This is an auto-generated comment by CodeRabbit -->


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

</details>

## Contributing

- Install dependencies: `pnpm install`
Expand Down
68 changes: 39 additions & 29 deletions docs/experimental-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 |

Expand All @@ -45,44 +60,39 @@ 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
```

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

Expand All @@ -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).
Loading