docs: add experimental workflow (OPSX) user guide #456
Conversation
Adds documentation for the experimental artifact-based workflow: - Setup instructions (Claude Code only for now) - Command reference for all /opsx:* commands - Usage examples and tips - Comparison with standard workflow - Feedback links to Discord and GitHub
📝 WalkthroughWalkthroughAdded a new documentation file describing the experimental OPSX workflow for OpenSpec. The document outlines the artifact-based progression model, setup instructions, available commands, usage examples, schema options, and workflow differences compared to standard procedures. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Review CompleteYour review story is ready! Comment !reviewfast on this PR to re-generate the story. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @docs/experimental-workflow.md:
- Around line 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.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/experimental-workflow.md
🧰 Additional context used
🧠 Learnings (7)
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
docs/experimental-workflow.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
docs/experimental-workflow.md
🪛 markdownlint-cli2 (0.18.1)
docs/experimental-workflow.md
11-11: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
43-43: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
49-49: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
55-55: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
61-61: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
67-67: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (8)
docs/experimental-workflow.md (8)
1-6: Status callout is clear and appropriately warns users.The experimental status and compatibility note are helpful.
17-27: Setup instructions are clear and well-formatted.The two-step setup process is straightforward, and the explanation of skill auto-detection is helpful.
29-38: Command table is well-organized and covers all six commands.Descriptions are concise.
Ensure the command descriptions (lines 33-38) match the actual implementation and available commands.
40-70: Usage examples are practical and demonstrate workflow progression.The examples effectively show different entry points (step-by-step vs. fast-forward) and the full workflow arc.
72-85: Workflow comparison effectively highlights the non-linear nature of OPSX.The side-by-side comparison and closing insight about iterative development clearly explain the design philosophy.
87-94: Schemas documentation provides useful examples and encourages discovery.The schema descriptions are clear.
Verify that the
openspec schemascommand (line 94) exists and accurately lists available schemas.
96-101: Tips section provides practical guidance for users.The advice about
/opsx:ffvs./opsx:continueand progress tracking is helpful.Verify that
openspec status --change "name"(line 101) is the correct command syntax for checking change status.
103-107: Feedback section is welcoming and provides clear channels for user input.The tone appropriately invites participation.
Verify that both the Discord link (https://discord.gg/BYjPaKbqMt, line 3 and 107) and GitHub issues link (https://github.com/Fission-AI/openspec/issues, line 107) are functional and point to active channels.
| ``` | ||
| proposal → specs → design → tasks → implementation → archive | ||
| ``` |
There was a problem hiding this comment.
🛠️ 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.
| ``` | |
| 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.
Summary
/opsx:*commands, usage examples, and what makes it differentTest plan
🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.