docs: comprehensive overhaul — discoverability, explore-first, and closing recurring doc-request issues#1237
Open
clay-good wants to merge 3 commits into
Open
Conversation
…nd location, FAQ, glossary, troubleshooting, recipes) Addresses Fission-AI#1228 (docs are fragmented and hard to discover). Additive, docs-only. The single sharpest gap from the issue thread was that nobody explains where slash commands run, hence the new "How Commands Work" page. New docs: - docs/README.md documentation home / index that maps every doc - docs/how-commands-work.md where /opsx:* (chat) vs openspec (terminal) run; "interactive mode" answered - docs/overview.md core concepts at a glance, one page - docs/faq.md consolidated common questions - docs/glossary.md every term in one place - docs/troubleshooting.md concrete fixes for concrete failures - docs/examples.md real changes start to finish (recipes) Small additive edits: - docs/getting-started.md "where do I type this?" callout + first-five-minutes + richer Next Steps - README.md Docs list points at the new home and key new pages Voice: warm, plain, bottom-line-up-front; no em-dashes in prose. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
📝 WalkthroughWalkthroughAdds seven new documentation pages establishing core concepts, command model, examples, and troubleshooting guidance. Updates README.md and getting-started.md to surface the explore-first workflow entry point, and updates command reference pages to emphasize exploration as the default starting point for uncertain work. ChangesOpenSpec Documentation Expansion and Navigation Redesign
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related issues
Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/faq.md (1)
43-43: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick winFix awkward grammar in the skill/command explanation.
Line 43: "OpenSpec installs whichever your tool uses" is grammatically incomplete. "Whichever" requires an object noun.
Suggested revision: "OpenSpec installs whichever commands your tool needs."
Proposed wording fix
- Both are files OpenSpec writes so your assistant can run the workflow. Skills (`.../skills/openspec-*/SKILL.md`) are the newer cross-tool standard; commands (`.../commands/opsx-*`) are the older per-tool slash files. You don't need to pick. You just type the slash command, and OpenSpec installs whichever your tool uses. + Both are files OpenSpec writes so your assistant can run the workflow. Skills (`.../skills/openspec-*/SKILL.md`) are the newer cross-tool standard; commands (`.../commands/opsx-*`) are the older per-tool slash files. You don't need to pick. You just type the slash command, and OpenSpec installs whichever commands your tool needs.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/faq.md` at line 43, The sentence in the skill/command explanation contains a grammar error where "whichever" lacks a noun object, leaving the statement incomplete. Revise the phrase "OpenSpec installs whichever your tool uses" by adding an appropriate noun after "whichever" to complete the grammatical structure, such as "OpenSpec installs whichever commands your tool needs" or similar phrasing that provides the missing object noun.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/faq.md`:
- Line 43: The sentence in the skill/command explanation contains a grammar
error where "whichever" lacks a noun object, leaving the statement incomplete.
Revise the phrase "OpenSpec installs whichever your tool uses" by adding an
appropriate noun after "whichever" to complete the grammatical structure, such
as "OpenSpec installs whichever commands your tool needs" or similar phrasing
that provides the missing object noun.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 858bb264-a68f-4ba5-a534-677f25c9ade1
📒 Files selected for processing (9)
README.mddocs/README.mddocs/examples.mddocs/faq.mddocs/getting-started.mddocs/glossary.mddocs/how-commands-work.mddocs/overview.mddocs/troubleshooting.md
Per maintainer feedback (Tabish): "the docs in general need some work, alongside making the explore option a lot more front and center." explore ships in the default core profile but every doc led with propose and treated explore as a footnote for "unclear requirements." This reframes the canonical loop as explore -> propose -> apply -> archive and gives explore real prominence. - docs/explore.md (new): dedicated "Explore First" guide. When to use it, what it does/doesn't, a full transcript, handoff to propose, tradeoffs. - getting-started.md: explore added to the flow and first-five-minutes, with a featured callout and Next Steps entry. - overview.md: explore featured in the loop and next-links. - docs/README.md: explore in the opening, pick-your-path, 30-second version, and the doc map. - how-commands-work.md: explore leads the command list with a "good rhythm" note and an optional step in the clean-first-run example. - workflows.md: new first-class "Start by exploring" pattern in the default section (was buried under expanded mode); quick-reference row strengthened. - commands.md / faq.md / glossary.md: explore featured as the place to start. - examples.md: top callout pointing at the explore recipe. - README.md: explore opens the "See it in action" demo and Quick Start, and is added to the Docs list. Docs-only and additive. No em-dashes in prose; links verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Collaborator
Author
|
Pushed a follow-up commit acting on the feedback that the docs need more work and that
Still docs-only and additive. No em-dashes in prose; relative links verified. Happy to keep iterating, and as before I can split this into smaller PRs if that's easier to review. |
…tall, context limits) + sync tool list Sweep of open issues and discussions surfaced several questions good docs should answer but didn't. This adds the missing guides and fixes a stale list. New guides: - docs/existing-projects.md: adopting OpenSpec on a large brownfield codebase without documenting everything up front (addresses Fission-AI#510, Fission-AI#1100, Fission-AI#176). Delta-first framing, first-change walkthrough, onboard, importing existing requirements docs, domain organization, monorepo/workspace pointers. - docs/editing-changes.md: how to edit any artifact, update a proposal/spec after starting, go back after implementing, and reconcile manual code edits (addresses Fission-AI#684, Fission-AI#976, Fission-AI#355, Fission-AI#1188, Fission-AI#169, Fission-AI#1206). Enhancements: - installation.md: Updating + Uninstalling sections (addresses Fission-AI#308). - faq.md: new entries for existing codebases, editing artifacts, going back, reconciling manual edits, context limits / long sessions, and uninstalling (addresses Fission-AI#257 among others). - cli.md: --tools list now includes `vibe` and matches AI_TOOLS in src/core/config.ts, with a note pointing at the source (fixes Fission-AI#1213). - Wired the new guides into the docs home, getting-started, and the README. Docs-only and additive. No em-dashes in prose; links and section anchors verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
clay-good
changed the title
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
docs/existing-projects.md (2)
27-35: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick winReduce repetition of "exactly" in nearby sentences.
Lines 31 and 33 both use "exactly" within close proximity ("This is exactly what brownfield work needs" and "which is exactly when you want it thorough"). Consider rephrasing one of them using alternatives like "precisely," "this," or restructuring the sentence.
Proposed fix
-This is exactly what brownfield work needs. You're rarely building from nothing. You're adding a field, fixing a redirect, tightening a timeout. A delta lets you specify that one change precisely without first writing a 40-page spec of everything around it. +This is what brownfield work needs. You're rarely building from nothing. You're adding a field, fixing a redirect, tightening a timeout. A delta lets you specify that one change precisely without first writing a 40-page spec of everything around it.And:
-The spec for `auth/` becomes thorough only after you've made several auth changes, which is exactly when you want it thorough. +The spec for `auth/` becomes thorough only after you've made several auth changes, which is when you want it thorough.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/existing-projects.md` around lines 27 - 35, The section "Why delta-first is the whole trick" uses the word "exactly" twice in close proximity: once in the phrase "This is exactly what brownfield work needs" and again in "which is exactly when you want it thorough". To reduce repetition, rephrase one of these instances by replacing "exactly" with an alternative word like "precisely" or "this," or by restructuring the sentence to convey the same meaning without repeating the word.
11-14: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick winBash command blocks need either output or no dollar signs (MD014).
Lines 12–13 and 74–75 show
$prefixes without subsequent command output. Either remove the$or add placeholder output like# output:or> openspec init installed.Proposed fix (remove `$` prefixes)
-$ cd your-existing-project -$ openspec init # adds openspec/ and your AI tool's commands +cd your-existing-project +openspec init # adds openspec/ and your AI tool's commandsSimilarly for lines 74–75:
-$ openspec config profile # select the expanded workflows -$ openspec update # apply them to this project +openspec config profile # select the expanded workflows +openspec update # apply them to this projectAlso applies to: 73-76
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/existing-projects.md` around lines 11 - 14, The bash code blocks at lines 12-13 and 74-75 contain dollar sign ($) command prompts but do not include any subsequent output or results, which violates the MD014 markdown linting rule. Remove the dollar sign prefixes from these bash command blocks in the existing-projects.md file so that the commands appear without prompts. This applies to both the cd and openspec init commands in the first block and the corresponding commands in the second block referenced at lines 73-76.docs/explore.md (1)
9-11: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick winConsider alternative to "right first step" to improve word variety.
Line 11 ("Explore is the right first step more often than people expect") uses "right" where the phrase could also leverage "best," "ideal," or restructure slightly. If "right" appears elsewhere in nearby context, this will feel repetitive.
Proposed alternatives
-Explore is the right first step more often than people expect. +Explore is the best first step more often than people expect.Or:
-Explore is the right first step more often than people expect. +In most cases, explore is the right first move more often than people expect.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/explore.md` around lines 9 - 11, In the sentence "Explore is the right first step more often than people expect", replace the word "right" with a more varied alternative such as "best" or "ideal" to improve word variety and avoid repetition if "right" appears elsewhere in the nearby context. Alternatively, consider restructuring the sentence entirely to convey the same meaning while improving readability and vocabulary diversity.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/cli.md`:
- Line 110: The supported tool IDs list is out of order and does not match the
AI_TOOLS array in src/core/config.ts. Reorder the tools in the Supported tool
IDs list so that vibe appears immediately after lingma and before opencode,
instead of appearing near the end between trae and windsurf. This will ensure
the documentation accurately mirrors the source-of-truth configuration as
claimed.
---
Nitpick comments:
In `@docs/existing-projects.md`:
- Around line 27-35: The section "Why delta-first is the whole trick" uses the
word "exactly" twice in close proximity: once in the phrase "This is exactly
what brownfield work needs" and again in "which is exactly when you want it
thorough". To reduce repetition, rephrase one of these instances by replacing
"exactly" with an alternative word like "precisely" or "this," or by
restructuring the sentence to convey the same meaning without repeating the
word.
- Around line 11-14: The bash code blocks at lines 12-13 and 74-75 contain
dollar sign ($) command prompts but do not include any subsequent output or
results, which violates the MD014 markdown linting rule. Remove the dollar sign
prefixes from these bash command blocks in the existing-projects.md file so that
the commands appear without prompts. This applies to both the cd and openspec
init commands in the first block and the corresponding commands in the second
block referenced at lines 73-76.
In `@docs/explore.md`:
- Around line 9-11: In the sentence "Explore is the right first step more often
than people expect", replace the word "right" with a more varied alternative
such as "best" or "ideal" to improve word variety and avoid repetition if
"right" appears elsewhere in the nearby context. Alternatively, consider
restructuring the sentence entirely to convey the same meaning while improving
readability and vocabulary diversity.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: c8793466-d8d9-45dc-9112-16af284ba5d6
📒 Files selected for processing (15)
README.mddocs/README.mddocs/cli.mddocs/commands.mddocs/editing-changes.mddocs/examples.mddocs/existing-projects.mddocs/explore.mddocs/faq.mddocs/getting-started.mddocs/glossary.mddocs/how-commands-work.mddocs/installation.mddocs/overview.mddocs/workflows.md
✅ Files skipped from review due to trivial changes (8)
- docs/overview.md
- docs/README.md
- docs/how-commands-work.md
- README.md
- docs/glossary.md
- docs/workflows.md
- docs/getting-started.md
- docs/examples.md
| `--profile custom` uses whatever workflows are currently selected in global config (`openspec config profile`). | ||
|
|
||
| **Supported tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `opencode`, `pi`, `qoder`, `lingma`, `qwen`, `roocode`, `trae`, `windsurf` | ||
| **Supported tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `vibe`, `windsurf` |
Contributor
There was a problem hiding this comment.
Tool ID list is out of order—vibe should precede opencode.
Line 110 lists supported tool IDs, claiming (line 112) that the list "mirrors AI_TOOLS in src/core/config.ts." However, the documented order places vibe near the end (between trae and windsurf), whereas the AI_TOOLS array shows vibe immediately after lingma and before opencode.
Current order in docs: lingma, opencode, pi, qoder, qwen, roocode, trae, vibe, windsurf
Correct order (per AI_TOOLS): lingma, vibe, opencode, pi, qoder, qwen, roocode, trae, windsurf
This inconsistency undermines the documentation's claim to be an accurate mirror of the source-of-truth configuration.
Fix tool ID ordering to match AI_TOOLS
-**Supported tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `vibe`, `windsurf`
+**Supported tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `vibe`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `windsurf`📝 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
| **Supported tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `vibe`, `windsurf` | |
| **Supported tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `vibe`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `windsurf` |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/cli.md` at line 110, The supported tool IDs list is out of order and
does not match the AI_TOOLS array in src/core/config.ts. Reorder the tools in
the Supported tool IDs list so that vibe appears immediately after lingma and
before opencode, instead of appearing near the end between trae and windsurf.
This will ensure the documentation accurately mirrors the source-of-truth
configuration as claimed.
|
Hi! Thanks for creating the PR for my issue. One thing I wanted to bring up: wouldn't it be nice to add this information to the main website, just like other library docs? I assume those .md doc files are meant for agents, right? |
Collaborator
Author
Hi @lorenzoceglia, yes these are for the repo (humans and agents alike). Pinging @TabishB about the website copy. |
|
@clay-good Let me know if I can help :) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A comprehensive, documentation-only overhaul addressing #1228 ("the docs are fragmented and, in practice, almost nonexistent") and the broader maintainer feedback that the docs in general need work, and
/opsx:exploreshould be a lot more front and center.The existing reference docs were actually fairly thorough, so the real problems were discoverability, a missing new-user mental model, explore being undersold, and a set of recurring questions that good docs should answer but didn't. This PR fixes all of that while staying additive (new pages plus small surgical edits; no reference doc was rewritten wholesale).
What's new
Orientation and mental model
docs/README.md— a documentation home / index that maps every doc and offers "pick your path" routes (the direct fix for "fragmented").docs/how-commands-work.md— the single biggest gap from the issue thread:/opsx:*runs in your AI chat,openspecruns in your terminal, what "interactive mode" really means, per-tool syntax, and how to confirm install. (Answers the "how do I start interactive mode?" comments directly.)docs/overview.md— core concepts on one page.docs/glossary.md— every term in one place.Explore, front and center
docs/explore.md— a dedicated "Explore First" guide. The canonical loop is reframed as explore → propose → apply → archive, and explore now leads the README demo, Quick Start, docs home, getting-started, overview, how-commands-work, and workflows (promoted out of "expanded mode," since it ships in the default profile).Closing recurring doc-request issues
docs/existing-projects.md— adopting OpenSpec on a large brownfield codebase without documenting everything up front (How can I use OpenSpec in a large existing project，what is the first step I should do? #510, if i have tla+ and srs docs, how can i create project with openspec? #1100, Question: Best practices for scaling OpenSpec in a large monorepo? #176).docs/editing-changes.md— editing any artifact, updating a proposal/spec after starting, going back after implementing, reconciling manual code edits (How to update specifications during the apply phase? #684, how to update the existing change,such as propose.md #976, How to return to the Review phase after Implement Tasks? #355, Add a command to update proposal ,design and task #1188, How should manual code edits be reconciled with OpenSpec? #169, Is there a good solution for refine proposal now? #1206).docs/faq.md,docs/troubleshooting.md— consolidated answers, including context limits / long sessions (How to use OpenSpec when context exceeds limits or requirements change after implementation？ #257) and uninstalling (How to uninstall OpenSpec #308).docs/examples.md— seven real changes, start to finish.Accuracy and surgical edits
installation.md— added Updating and Uninstalling sections (How to uninstall OpenSpec #308).cli.md—--toolslist now includesvibeand matchesAI_TOOLSinsrc/core/config.ts, with a pointer to the source (docs/cli.md tool ID list out of sync with src/core/config.ts #1213).getting-started.md,commands.md,workflows.md,README.md— small additive edits: a "where do I type this?" callout, a first-five-minutes path, explore prominence, and updated docs lists.Issues addressed
Primary: #1228. Also closes or substantially answers the doc-shaped parts of: #510, #1100, #176, #684, #976, #355, #1188, #169, #1206, #257, #308, #1213. Complements (no overlap with) the open #1146 beginner-workflow guide.
Validation
git diffis limited todocs/andREADME.md; no code changed.Note to maintainers
Opened from a fork as a collaborator. Happy to split this into smaller PRs (for example, land the docs home +
how-commands-work.mdfirst) if that's easier to review. Feedback very welcome.🤖 Generated with Claude Code
Summary by CodeRabbit
/opsx:exploreas the recommended first step.