Skip to content

Commit bb9f6ce

Browse files
authored
docs: add OPSX experimental workflow visibility to README (#460)
* 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. * 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. * 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: 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. * 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". * 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.
1 parent ae85a72 commit bb9f6ce

File tree

2 files changed

+494
-27
lines changed

2 files changed

+494
-27
lines changed

README.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,10 @@
2626
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.
2727
</p>
2828

29+
<p align="center">
30+
<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>
31+
</p>
32+
2933
# OpenSpec
3034

3135
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
368372
2. **Refresh agent instructions**
369373
- Run `openspec update` inside each project to regenerate AI guidance and ensure the latest slash commands are active.
370374

375+
## Experimental Features
376+
377+
<details>
378+
<summary><strong>🧪 OPSX: Fluid, Iterative Workflow</strong> (Claude Code only)</summary>
379+
380+
**Why this exists:**
381+
- Standard workflow is locked down — you can't tweak instructions or customize
382+
- When AI output is bad, you can't improve the prompts yourself
383+
- Same workflow for everyone, no way to match how your team works
384+
385+
**What's different:**
386+
- **Hackable** — edit templates and schemas yourself, test immediately, no rebuild
387+
- **Granular** — each artifact has its own instructions, test and tweak individually
388+
- **Customizable** — define your own workflows, artifacts, and dependencies
389+
- **Fluid** — no phase gates, update any artifact anytime
390+
391+
```
392+
You can always go back:
393+
394+
proposal ──→ specs ──→ design ──→ tasks ──→ implement
395+
▲ ▲ ▲ │
396+
└───────────┴──────────┴────────────────────┘
397+
```
398+
399+
| Command | What it does |
400+
|---------|--------------|
401+
| `/opsx:new` | Start a new change |
402+
| `/opsx:continue` | Create the next artifact (based on what's ready) |
403+
| `/opsx:ff` | Fast-forward (all planning artifacts at once) |
404+
| `/opsx:apply` | Implement tasks, updating artifacts as needed |
405+
| `/opsx:archive` | Archive when done |
406+
407+
**Setup:** `openspec artifact-experimental-setup`
408+
409+
[Full documentation →](docs/experimental-workflow.md)
410+
411+
</details>
412+
371413
## Contributing
372414

373415
- Install dependencies: `pnpm install`

0 commit comments

Comments
 (0)