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 all 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
42 changes: 42 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> — schema-driven, hackable, fluid. Iterate on workflows without code changes.</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,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

<details>
<summary><strong>🧪 OPSX: Fluid, Iterative Workflow</strong> (Claude Code only)</summary>

**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
▲ ▲ ▲ │
└───────────┴──────────┴────────────────────┘
```
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
Loading
Loading