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

Changes from 1 commit
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
29 changes: 29 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> 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.**
Expand Down Expand Up @@ -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
```
Comment on lines +391 to +397

@coderabbitai coderabbitai Bot Jan 9, 2026

Copy link
Copy Markdown
Contributor

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 |
| `/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`
Expand Down
Loading