Skip to content

docs: add experimental workflow (OPSX) user guide #456

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 2 commits into from
Jan 7, 2026
+107 −0
Merged

docs: add experimental workflow (OPSX) user guide #456

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
586ef61
docs: add experimental workflow (OPSX) user guide
TabishB Jan 7, 2026
675941a
Merge branch 'main' into docs/experimental-workflow-guide
TabishB Jan 7, 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
107 changes: 107 additions & 0 deletions docs/experimental-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
# Experimental Workflow (OPSX)

> **Status:** Experimental. Things might break. Feedback welcome on [Discord](https://discord.gg/BYjPaKbqMt).
>
> **Compatibility:** Claude Code only (for now)

## What Is It?

OPSX is a new way to work with OpenSpec changes. Instead of one big proposal, you build **artifacts** step-by-step:

```
proposal → specs → design → tasks → implementation → archive
```
Comment on lines +11 to +13
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 7, 2026

Choose a reason for hiding this comment

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

🛠️ Refactor suggestion | 🟠 Major

Add language specification to code blocks.

Fenced code blocks should specify a language tag for consistency and accessibility. Lines 11, 43, 49, 55, 61, and 67 are missing language specifications.

🔧 Proposed fix for code block language tags

Line 11-13: Change text diagram to specify language

-```
+```text
 proposal → specs → design → tasks → implementation → archive
-```
+```

Line 43-45: Specify bash for command

-```
+```bash
 /opsx:new
-```
+```

Line 49-52: Specify bash for command

-```
+```bash
 /opsx:continue
-```
+```

Line 55-58: Specify bash for command

-```
+```bash
 /opsx:ff add-dark-mode
-```
+```

Line 61-64: Specify bash for command

-```
+```bash
 /opsx:apply
-```
+```

Line 67-70: Specify bash for commands

-```
+```bash
 /opsx:sync      # Update main specs with your delta specs
 /opsx:archive   # Move to archive when done
-```
+```
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
```
proposal → specs → design → tasks → implementation → archive
```
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

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

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In @docs/experimental-workflow.md around lines 11 - 13, Add explicit language
tags to the fenced code blocks in docs/experimental-workflow.md: change the
diagram block to ```text and the command blocks containing /opsx:new,
/opsx:continue, /opsx:ff add-dark-mode, /opsx:apply and the paired /opsx:sync
and /opsx:archive examples to ```bash so each fenced block includes the
appropriate language tag for consistency and accessibility.


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
# 1. Make sure you have openspec installed and initialized
openspec init

# 2. Generate the experimental skills
openspec artifact-experimental-setup
```

This creates skills in `.claude/skills/` that Claude Code auto-detects.

## Commands

| 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:sync` | Sync delta specs to main specs |
| `/opsx:archive` | Archive when done |

## Usage

### Start a new change
```
/opsx:new
```
You'll be asked what you want to build and which workflow schema to use.

### Build artifacts step-by-step
```
/opsx:continue
```
Creates one artifact at a time. Good for reviewing each step.

### Or fast-forward
```
/opsx:ff add-dark-mode
```
Creates all artifacts in one go. Good when you know what you want.

### Implement
```
/opsx:apply
```
Works through tasks, checking them off as you go.

### Sync specs and archive
```
/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)

The key insight: work isn't linear. You implement, realize the design is wrong, update it, continue. OPSX supports this.

## Schemas

Schemas define what artifacts exist and their dependencies. Currently available:

- **spec-driven** (default): proposal → specs → design → tasks
- **tdd**: tests → implementation → docs

Run `openspec schemas` to see available schemas.

## Tips

- Use `/opsx:ff` when you have a clear idea, `/opsx:continue` when exploring
- 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"`

## Feedback

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