feat: onboarding skill and comprehensive documentation overhaul #574
Conversation
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
Add a new onboard skill that walks users through their first complete OpenSpec workflow cycle. The skill provides interactive guidance through task selection, change creation, artifact building, implementation, and archiving. Also includes: - New README with updated branding and workflow examples - Documentation structure placeholders - Change artifacts for the onboard skill feature
Contributor
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. 📝 WalkthroughWalkthroughThis PR adds extensive new documentation, removes several outdated docs, introduces an OPSX onboarding skill and command templates (with registration and tests), updates README layout, and removes a CI workflow for polishing release notes. No public APIs beyond template exports were changed. Changes
Sequence Diagram(s)sequenceDiagram
participant CLI as "CLI (openspec)"
participant Registry as "Template Registry\n(src/core/shared)"
participant Templates as "Skill Templates\n(src/core/templates)"
participant FS as "File System / Project"
participant Tests as "Unit Tests"
CLI->>Registry: request templates (init/update)
Registry->>Templates: include getOnboardSkillTemplate / getOpsxOnboardCommandTemplate
Templates-->>Registry: template objects (with onboarding instructions)
Registry->>FS: generate files from selected templates
FS-->>CLI: project files created (skill/command)
Tests->>Registry: load templates for assertions
Registry-->>Tests: template list includes 'openspec-onboard' / 'onboard'
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 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 |
Greptile SummaryAdds a comprehensive Key additions:
Issues found:
Confidence Score: 4/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant User
participant Agent
participant CLI as OpenSpec CLI
participant Codebase
User->>Agent: /opsx:onboard
Agent->>CLI: openspec status --json
CLI-->>Agent: initialized status
alt Not Initialized
Agent->>User: Run openspec init first
else Initialized
Agent->>User: Welcome message + workflow overview
Agent->>Codebase: Scan for TODO/FIXME/type issues
Agent->>CLI: git log --oneline -10
Agent->>User: Present 3-4 task suggestions
User->>Agent: Select task
Agent->>Codebase: Brief exploration (read files)
Agent->>User: Explain explore mode
User->>Agent: Acknowledge
Agent->>CLI: openspec new change "name"
CLI-->>Agent: Change directory created
Agent->>User: Show folder structure
Agent->>User: Draft proposal (Why/What/Impact)
User->>Agent: Approve
Agent->>Codebase: Write proposal.md
Agent->>User: Draft specs (Requirements/Scenarios)
Agent->>Codebase: Write specs/capability/spec.md
Agent->>User: Draft design (How/Decisions)
Agent->>Codebase: Write design.md
Agent->>User: Generate tasks checklist
User->>Agent: Ready to implement
Agent->>Codebase: Write tasks.md
loop For each task
Agent->>Codebase: Implement code changes
Agent->>Codebase: Mark task complete in tasks.md
Agent->>User: Task N complete
end
Agent->>User: All tasks done
User->>Agent: Acknowledge
Agent->>CLI: openspec archive "name"
CLI-->>Agent: Archived to openspec/archive/YYYY-MM-DD--name/
Agent->>User: Archive complete + command reference
Agent->>User: Recap workflow + next steps
end
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
README_NEW.md
Outdated
| ``` | ||
|
|
||
| > [!TIP] | ||
| > **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow. Run `/opsx:onboard` to get started. → [Learn more here](#) |
There was a problem hiding this comment.
syntax: broken anchor link - should either point to a specific section or be removed
Suggested change
| > **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow. Run `/opsx:onboard` to get started. → [Learn more here](#) | |
| > **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow. Run `/opsx:onboard` to get started. |
Prompt To Fix With AI
This is a comment left during a code review.
Path: README_NEW.md
Line: 30:30
Comment:
**syntax:** broken anchor link - should either point to a specific section or be removed
```suggestion
> **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow. Run `/opsx:onboard` to get started.
```
How can I resolve this? If you propose a fix, please make it concise.
README_NEW.md
Outdated
Comment on lines
89
to
102
| > Not sure if your tool is supported? [View the full list](link) – we support 20+ tools and growing. | ||
|
|
||
| > [!NOTE] | ||
| > Also works with pnpm, yarn, bun, and nix. [See installation options](link). | ||
|
|
||
| ## Docs | ||
|
|
||
| → **[Getting Started](link)**: first steps<br> | ||
| → **[Workflows](link)**: combo's and patterns<br> | ||
| → **[Commands](link)**: slash commands & skills<br> | ||
| → **[CLI](link)**: terminal reference<br> | ||
| → **[Concepts](link)**: how it all fits<br> | ||
| → **[i18n](link)**: multi-language support<br> | ||
| → **[Customization](link)**: make it yours |
There was a problem hiding this comment.
logic: all documentation links use placeholder "link" text instead of actual URLs - these will not work when clicked
Prompt To Fix With AI
This is a comment left during a code review.
Path: README_NEW.md
Line: 89:102
Comment:
**logic:** all documentation links use placeholder "link" text instead of actual URLs - these will not work when clicked
How can I resolve this? If you propose a fix, please make it concise.
README_NEW.md
Outdated
| ## Docs | ||
|
|
||
| → **[Getting Started](link)**: first steps<br> | ||
| → **[Workflows](link)**: combo's and patterns<br> |
There was a problem hiding this comment.
syntax: incorrect apostrophe usage - "combo's" should be "combos"
Suggested change
| → **[Workflows](link)**: combo's and patterns<br> | |
| → **[Workflows](link)**: combos and patterns<br> |
Prompt To Fix With AI
This is a comment left during a code review.
Path: README_NEW.md
Line: 97:97
Comment:
**syntax:** incorrect apostrophe usage - "combo's" should be "combos"
```suggestion
→ **[Workflows](link)**: combos and patterns<br>
```
How can I resolve this? If you propose a fix, please make it concise.
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}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@README_NEW.md`:
- Around line 29-102: Replace all placeholder href targets ('#' and 'link') in
README_NEW.md with real documentation URLs or remove the anchor if the page
doesn't exist: update the "Learn more here" link, the "View the full list"
tooling link, the "See installation options" link, and each Docs bullet (Getting
Started, Workflows, Commands, CLI, Concepts, i18n, Customization) to point to
their actual doc paths or relative routes (or convert them to plain text until
the docs are available) so the rendered README contains valid, non-broken links.
🧹 Nitpick comments (6)
README_NEW.md (1)
40-40: Track or remove the TODO before release.The inline TODO is fine for draft docs, but consider converting it to an issue or removing it for release-ready docs.
Do you want me to open a tracking issue and draft a GIF brief?
openspec/changes/add-opsx-onboard-skill/design.md (1)
79-93: Add a language hint to the fenced block.Markdownlint flags this; consider using ```text to keep it readable.
✍️ Suggested tweak
-``` +```text - Preflight checks (init status) - Phase 1: Welcome & Setup - Phase 2: Task Selection (with codebase analysis instructions) - Phase 3: Explore Demo (brief) - Phase 4: Change Creation - Phase 5: Proposal - Phase 6: Specs - Phase 7: Design - Phase 8: Tasks - Phase 9: Apply (Implementation) - Phase 10: Archive - Phase 11: Recap & Next Steps - Edge cases & graceful exits -``` +```docs/README_RENEWAL_PROMPTS.md (1)
9-542: Add language identifiers to fenced blocks for markdownlint/readability.This file is heavy on code fences; using
text ormarkdown will silence MD040 and improve legibility.docs/i18n.md (1)
1-2: Consider adding a brief “coming soon” stub.An empty doc can feel broken if linked; a short placeholder note helps set expectations.
✍️ Suggested stub
# i18n + +> Coming soon. This page will cover language support, localization plans, and workarounds.docs/cli.md (1)
1-2: Consider adding a brief placeholder.If README links here, a short stub avoids a blank page experience.
✍️ Suggested stub
# CLI + +> Coming soon. This page will document the OpenSpec CLI commands and usage.openspec/changes/add-opsx-onboard-skill/specs/opsx-onboard-skill/spec.md (1)
150-153: Vary the repeated phrasing for clarity.“User indicates they want to stop” repeats nearby; consider a small wording tweak for readability.
Update test expectations from 9 to 10 skills after adding opsx:onboard.
- Replace placeholder links in README_NEW.md with actual doc paths - Add documentation cleanup checklist to README_RENEWAL_PROMPTS.md
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@docs/README_RENEWAL_PROMPTS.md`:
- Line 46: Several fenced code blocks in the markdown use plain ``` without a
language tag which violates markdownlint MD040; update every triple-backtick
fenced block (the ones shown as ``` in the diff) to include an appropriate
language identifier (e.g., ```text for prose, ```bash for shell examples,
```yaml for YAML snippets) and apply the same pattern consistently throughout
the document so all fenced blocks include a language tag.
In `@README_NEW.md`:
- Around line 88-92: Remove the extra blank line between the two blockquote NOTE
blocks so the markdownlint MD028 warning is resolved; edit the README_NEW.md
content where the two lines "[!NOTE] Not sure if your tool is supported? [View
the full list](docs/getting-started.md#supported-tools) – we support 20+ tools
and growing." and "[!NOTE] Also works with pnpm, yarn, bun, and nix. [See
installation options](docs/cli.md#installation)." appear and place them directly
adjacent with no empty line in between.
- Around line 21-27: Add a language tag to the fenced code block containing the
philosophy lines to satisfy markdownlint MD040: change the opening backticks to
include a language (for example use "text") so the block becomes ```text,
leaving the block contents unchanged and the closing backticks as-is; target the
fenced block that starts with "→ fluid not rigid" in README_NEW.md.
♻️ Duplicate comments (1)
README_NEW.md (1)
29-30: Replace the empty anchor target.The “Learn more here” link still points to
#, which renders as a broken link.✅ Proposed fix
-> **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow. Run `/opsx:onboard` to get started. → [Learn more here](#) +> **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow. Run `/opsx:onboard` to get started. → [Learn more here](docs/workflows.md)
… customization guides - Rewrite workflows.md with action-based philosophy and workflow patterns - Rewrite getting-started.md with clearer onboarding flow - Rewrite customization.md with schema customization guidance - Add cross-references between docs (Commands, Customization links) - Remove obsolete docs: artifact_poc, experimental-release-plan, project-config-demo, schema-customization, schema-workflow-gaps - Update README_RENEWAL_PROMPTS.md checklist
…cturing - Expand cli.md, commands.md, and concepts.md with comprehensive content - Add installation.md, multi-language.md, and supported-tools.md - Rename experimental-workflow.md to opsx.md - Remove i18n.md (replaced by multi-language.md) - Update README links and cleanup prompts
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Fix all issues with AI agents
In `@docs/commands.md`:
- Around line 442-462: Add a language identifier to the fenced code block that
contains the example conversation (the block beginning with "You: /opsx:archive"
and the AI responses) by changing the opening fence from ``` to ```text so the
snippet is marked as plain text; update the single fenced block in that section
accordingly.
- Around line 385-401: The fenced code block in the example conversation lacks a
language tag; update the triple-backtick fence that wraps the snippet starting
with "You: /opsx:sync" and "AI: Syncing add-dark-mode delta specs..." to
include a language identifier (e.g., ```text) so the block is properly tagged;
ensure you only modify the opening fence to ```text and leave the inner content
(the commands and sync output lines) unchanged.
- Around line 656-661: Update the troubleshooting text to stop recommending the
deprecated `openspec experimental` command: replace the `openspec experimental`
entry with `openspec init` (or explicitly note that `openspec experimental` is a
hidden, deprecated alias of `openspec init`), and keep the surrounding guidance
about verifying the `.claude/skills/` directory and restarting the AI tool;
ensure the docs mention the deprecation so users are directed to use `openspec
init` going forward.
- Around line 49-70: The fenced code block containing the example conversation
(the block starting with "You: /opsx:explore" and the AI/user dialogue) is
missing a language tag; update the opening triple-backtick to include a language
identifier (for example change ``` to ```text or ```console) so the block
renders correctly, keeping the closing triple-backtick unchanged and ensuring
the conversation content (You: /opsx:explore ... AI: Ready when you are. Run
/opsx:new add-jwt-auth to begin.) remains intact.
In `@docs/supported-tools.md`:
- Around line 57-71: The docs list 9 OPSX skills but the code now exposes 10;
update docs/supported-tools.md to reflect the new count and add the missing
skill row for `openspec-onboard` in the skills table alongside the existing
entries (e.g., `openspec-explore`, `openspec-new-change`,
`openspec-apply-change`, etc.), and ensure the introductory sentence now states
"10 skill files" and any mention of slash commands includes `/opsx:onboard`
where appropriate.
♻️ Duplicate comments (3)
README_NEW.md (3)
21-27: Add language tag to philosophy code block.The fenced code block is missing a language specifier, triggering markdownlint MD040. Add
textafter the opening backticks.✅ Proposed fix
-``` +```text → fluid not rigid → iterative not waterfall → easy not complex → built for brownfield not just greenfield → scalable from personal projects to enterprises</details> --- `44-67`: **Add language tag to demo code block.** The demo block is missing a language specifier. Add `text` or `console` after the opening backticks to satisfy markdownlint MD040. <details> <summary>✅ Proposed fix</summary> ```diff -``` +```text You: /opsx:new add-dark-mode AI: Created openspec/changes/add-dark-mode/ Ready to create: proposal
88-92: Remove blank line between NOTE blocks.The blank line on line 90 between the two NOTE blockquotes triggers markdownlint MD028.
✅ Proposed fix
> [!NOTE] > Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 20+ tools and growing. - > [!NOTE] > Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
🧹 Nitpick comments (7)
README_NEW.md (2)
40-40: TODO: Add GIF demo.A visual demonstration would enhance the onboarding experience.
Would you like me to open an issue to track this task?
117-117: Consider capitalizing "Markdown" as a proper noun."Markdown" is the name of the markup language and is typically capitalized.
♻️ Proposed fix
-**vs. [Spec Kit](https://github.com/github/spec-kit)** (GitHub) — Thorough but heavyweight. Rigid phase gates, lots of markdown, Python setup. OpenSpec is lighter and lets you iterate freely. +**vs. [Spec Kit](https://github.com/github/spec-kit)** (GitHub) — Thorough but heavyweight. Rigid phase gates, lots of Markdown, Python setup. OpenSpec is lighter and lets you iterate freely.docs/concepts.md (2)
9-14: Add language identifiers to fenced blocks to satisfy markdownlint (MD040).
Multiple fences are missing a language tag; markdownlint will flag the whole doc. Considertext,markdown,bash, oryamlas appropriate and apply consistently.♻️ Example (apply similarly across the file)
-``` +```text ┌─────────────────────────────────────────────────────────────────┐ │ openspec/ │ ... └─────────────────────────────────────────────────────────────────┘</details> Also applies to: 30-44, 58-68, 142-151, 176-186, 262-268, 395-412, 422-436, 477-509, 529-566 --- `428-436`: **Use a real heading instead of bold text (MD036).** `**tdd**` reads like a heading; prefer a heading level for consistency and linting. <details> <summary>♻️ Example</summary> ```diff -**tdd** +#### tdddocs/opsx.md (1)
25-35: Add language identifiers to fenced blocks to satisfy markdownlint (MD040).
There are multiple untyped fences; addtext,bash, oryamlto prevent lint failures.♻️ Example
-``` +```text Standard workflow: OPSX: ┌────────────────────────┐ ┌────────────────────────┐ ... └────────────────────────┘ └────────────────────────┘</details> Also applies to: 54-65, 186-218, 267-286, 323-363, 369-423, 429-453, 458-521, 528-562, 568-615, 634-649 </blockquote></details> <details> <summary>docs/cli.md (1)</summary><blockquote> `70-120`: **Add language identifiers to fenced blocks to satisfy markdownlint (MD040).** A large number of fences are untyped; add `bash`, `text`, or `json` as appropriate. <details> <summary>♻️ Example</summary> ```diff -``` +```bash openspec init [path] [options]</details> Also applies to: 127-149, 159-183, 187-192, 199-204, 211-257, 267-340, 350-383, 401-455, 463-497, 512-547, 554-587, 598-642, 650-673, 681-706, 714-743, 759-801, 811-834, 842-871 </blockquote></details> <details> <summary>docs/README_RENEWAL_PROMPTS.md (1)</summary><blockquote> `1-42`: **Reconsider committing temporary scaffolding file.** This file is marked as a temporary artifact (Line 38: "Delete this file... after all docs are generated") and most checklist items are already complete, suggesting the documentation generation is done. Consider whether this internal scaffolding should be committed to the main branch or if it would be better suited for: - A separate documentation branch - Issue/PR description - Project wiki/notes - Deletion per its own instructions If the intent is to document the documentation process for future reference, consider renaming it to clarify its archival purpose (e.g., `DOCS_GENERATION_GUIDE.md`). </blockquote></details> </blockquote></details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Comment on lines
656
to
661
| **Solutions:** | ||
| - Ensure OpenSpec is initialized: `openspec init` | ||
| - Run skill generation: `openspec experimental` | ||
| - Check that `.claude/skills/` directory exists (for Claude Code) | ||
| - Restart your AI tool to pick up new skills | ||
|
|
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for CLI command definitions and skill generation commands
# Look for command definitions - check common CLI library patterns
rg -n "experimental" --type=ts --type=js -B2 -A2
# Search for skill generation related code
rg -n "skill.*generat|generat.*skill" --type=ts --type=js -B2 -A2
# Check for command-line interface definitions
fd -type f -name "*.ts" -o -name "*.js" | xargs rg -l "command|CLI|cmd" | head -5Repository: Fission-AI/OpenSpec
Length of output: 19780
🏁 Script executed:
#!/bin/bash
# Look for the main entry point and command handler
find . -type f \( -name "index.ts" -o -name "main.ts" -o -name "cli.ts" -o -name "commands.ts" \) | head -20
# Search for where 'experimental' might be defined
rg -n "experimental" -i --type=ts --type=js -A5 | head -100Repository: Fission-AI/OpenSpec
Length of output: 7041
🏁 Script executed:
#!/bin/bash
# Check the docs/commands.md file directly to understand context
cat -n docs/commands.md | sed -n '650,670p'Repository: Fission-AI/OpenSpec
Length of output: 891
Update documentation to use openspec init instead of the deprecated openspec experimental command.
Line 658 references openspec experimental for skill generation, but this command is deprecated. The codebase shows it's a hidden alias to openspec init with an explicit deprecation warning. Update the troubleshooting section to recommend openspec init instead, or note that experimental is deprecated.
🤖 Prompt for AI Agents
In `@docs/commands.md` around lines 656 - 661, Update the troubleshooting text to
stop recommending the deprecated `openspec experimental` command: replace the
`openspec experimental` entry with `openspec init` (or explicitly note that
`openspec experimental` is a hidden, deprecated alias of `openspec init`), and
keep the surrounding guidance about verifying the `.claude/skills/` directory
and restarting the AI tool; ensure the docs mention the deprecation so users are
directed to use `openspec init` going forward.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@README_NEW.md`:
- Around line 44-67: The fenced demo code block starting with ``` and showing
the sample interaction (lines beginning "You: /opsx:new add-dark-mode" and "AI:
Created openspec/changes/add-dark-mode/") needs a language tag to satisfy MD040;
update that opening fence from ``` to ```text (or ```console) so the block is
explicitly labeled and the linter warning is resolved.
♻️ Duplicate comments (2)
README_NEW.md (2)
21-27: Add language tag to the fenced code block.The philosophy block needs a language identifier to satisfy markdownlint MD040.
📝 Proposed fix
-``` +```text → fluid not rigid → iterative not waterfall → easy not complex → built for brownfield not just greenfield → scalable from personal projects to enterprises</details> --- `88-92`: **Remove blank line between blockquotes.** The empty line at line 90 between the two NOTE blocks violates MD028. <details> <summary>📝 Proposed fix</summary> ```diff > [!NOTE] > Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 20+ tools and growing. - > [!NOTE] > Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
🧹 Nitpick comments (1)
README_NEW.md (1)
117-117: Capitalize "Markdown" as a proper noun.The markup language name should be capitalized for accuracy.
📝 Proposed fix
-**vs. [Spec Kit](https://github.com/github/spec-kit)** (GitHub) — Thorough but heavyweight. Rigid phase gates, lots of markdown, Python setup. OpenSpec is lighter and lets you iterate freely. +**vs. [Spec Kit](https://github.com/github/spec-kit)** (GitHub) — Thorough but heavyweight. Rigid phase gates, lots of Markdown, Python setup. OpenSpec is lighter and lets you iterate freely.
TabishB
changed the title
…lines - Update Discord badge to show member count - Add collapsible section with stars/downloads/contributors badges - Add OpenSpec Dashboard preview section - Add usage notes for model selection and context hygiene - Expand contributing section with guidelines for small/large changes - Clarify AI-generated code policy
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@README_NEW.md`:
- Line 135: The sentence comparing Spec Kit uses a lowercase "markdown"; update
that to the proper noun "Markdown" in the line starting with "**vs. [Spec
Kit](https://github.com/github/spec-kit)**" so it reads "...Rigid phase gates,
lots of Markdown, Python setup..." preserving the rest of the wording and
punctuation.
♻️ Duplicate comments (3)
README_NEW.md (3)
28-34: Add a language tag to the philosophy code block.MD040 is triggered. Please label the fenced block (e.g.,
text).🧩 Proposed fix
-``` +```text → fluid not rigid → iterative not waterfall → easy not complex → built for brownfield not just greenfield → scalable from personal projects to enterprises</details> --- `53-76`: **Add a language tag to the demo interaction block.** MD040 is triggered. Label the fence (e.g., `text` or `console`). <details> <summary>🧩 Proposed fix</summary> ```diff -``` +```text You: /opsx:new add-dark-mode AI: Created openspec/changes/add-dark-mode/ Ready to create: proposal @@ You: /opsx:archive AI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/ Specs updated. Ready for the next feature.</details> --- `106-110`: **Remove the blank line inside the NOTE blockquote.** MD028 is triggered by the empty line between the NOTE blocks. <details> <summary>🧩 Proposed fix</summary> ```diff > [!NOTE] > Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 20+ tools and growing. - > [!NOTE] > Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
🧹 Nitpick comments (1)
README_NEW.md (1)
143-151: Use headings instead of bold-only lines.MD036 flags “Upgrade the package” and “Refresh agent instructions” as emphasis-as-heading. Consider proper subheadings.
🧩 Proposed fix
-**Upgrade the package** +### Upgrade the package @@ -**Refresh agent instructions** +### Refresh agent instructions
The documentation claimed users could edit artifacts mid-implementation and seamlessly continue, but no such mechanism exists. This removes: - "Mid-Flight Correction" section from workflows.md - Feedback arrows and "update as you learn" from all diagrams - Mid-flight claims from commands.md, opsx.md, concepts.md - Example blocks showing edit-then-continue workflow Also adds a proposal for future artifact regeneration support that would actually make this workflow possible.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/opsx.md (2)
346-352: Docs still promise mid‑flight artifact updates.These sections say “Update specs/design/tasks during implementation” and “Just edit design.md and continue,” which reintroduces the mid‑flight behavior that the PR summary says was removed as unsupported. Please remove or clearly mark as future/experimental until implemented.
Also applies to: 534-549
59-65: Update documentation to useopenspec initinstead of the deprecatedopenspec experimentalcommand.The
openspec experimentalcommand is a hidden, deprecated alias foropenspec init. Although it still functions with a deprecation notice, the documentation should direct users to the supported command instead.Current documentation (lines 59-65, 77-78)
# 1. Make sure you have openspec installed and initialized openspec init # 2. Generate the experimental skills openspec experimentalReplace
openspec experimentalwithopenspec initto match the current CLI guidance.
🤖 Fix all issues with AI agents
In `@docs/workflows.md`:
- Around line 11-23: Fenced code blocks in the workflows document (e.g., the
blocks starting with "Traditional (phase-locked):" and "OPSX (fluid actions):"
and the other blocks called out in the review) are missing language tags which
triggers markdownlint MD040; update each triple-backtick fence to include an
appropriate language identifier—use text for diagrams/conversational blocks and
bash for CLI snippets—so replace ``` with ```text or ```bash as appropriate for
the blocks containing the examples referenced in the comment.
In `@openspec/changes/add-artifact-regeneration-support/proposal.md`:
- Around line 126-129: The dependency name `fix-midlight-update-docs` in the
Dependencies section is a typo; update it to the intended
`fix-midflight-update-docs` wherever referenced (the exact string in the
proposal text) to avoid broken cross-references or phantom dependencies and
ensure consistency across the document.
♻️ Duplicate comments (2)
docs/README_RENEWAL_PROMPTS.md (1)
46-46: Add language tags to fenced code blocks.MD040 violation repeated across multiple fences. Apply language identifiers consistently (e.g.,
text,bash,yaml) for all triple‑backtick blocks.Also applies to: 92-92, 109-109, 151-151, 178-178, 213-213, 279-279, 308-308, 337-337, 390-390, 419-419, 533-533
docs/commands.md (1)
640-643: Docs still recommend deprecatedopenspec experimental.This was already raised in a prior review; keeping visible here.
🧹 Nitpick comments (3)
docs/migration-guide.md (3)
97-126: Add language tags to fenced code blocks (markdownlint MD040).These fenced blocks are missing language identifiers. Please tag them (e.g.,
text,bash,yaml,markdown) to satisfy linting and improve readability.Also applies to: 259-270, 303-306, 309-312, 322-330, 334-343, 349-366, 374-379, 383-390, 402-405, 410-413, 538-552, 563-569
223-227: Use a heading instead of bold-only line (markdownlint MD036).Convert the emphasized line to a proper heading for consistent structure.
Proposed change
-**Leave out entirely** +#### Leave out entirely
54-54: Tighten phrasing: “originally created” → “created.”Avoid redundancy for crisper documentation.
Proposed change
-The removal list may seem long, but these are all files that OpenSpec originally created. +The removal list may seem long, but these are all files that OpenSpec created.
- Add language tags to fenced code blocks (MD040) - Remove blank line between blockquotes (MD028) - Capitalize "Markdown" as proper noun - Update deprecated command reference (experimental -> update) - Update skill count from 9 to 10, add openspec-onboard - Fix typo: fix-midlight -> fix-midflight
Replaced with local /polish-release skill. The claude-code-action doesn't work well with repository_dispatch triggers (no PR context).
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@docs/supported-tools.md`:
- Around line 14-36: Update the command directory paths for the five tools in
the table so they match the adapter implementations: change Antigravity's
commands from `.agent/commands/` to `.agent/workflows/`, Codex's commands from
`.codex/commands/` to `.codex/prompts/`, Crush's commands from
`.crush/commands/` to `.crush/commands/opsx/`, OpenCode's commands from
`.opencode/prompts/` to `.opencode/command/`, and Qoder's commands from
`.qoder/workflows/` to `.qoder/commands/opsx/`; ensure you modify the
corresponding rows for the tools named "Antigravity", "Codex", "Crush",
"OpenCode", and "Qoder" in the table so documentation aligns with the adapters
under src/core/command-generation/adapters/.
In `@openspec/changes/add-artifact-regeneration-support/proposal.md`:
- Around line 33-115: The markdown in proposal.md contains untyped fenced code
blocks; update each fence to include a language identifier: add ```text to the
chat transcript block starting with "You: /opsx:apply", add ```bash to the shell
snippet that begins "# Option A: Flag on continue" (the /opsx:continue example),
add ```json to the metadata block that begins with `{ "tasks.md": {`, and add
```markdown to the frontmatter block that begins with `--- generated_at:` so all
fenced blocks are explicitly typed for linting and consistent rendering.
In `@README_NEW.md`:
- Around line 142-148: Replace bolded lines used as section titles (e.g.,
"**Upgrade the package**" and "**Refresh agent instructions**") with proper
markdown headings (e.g., "## Upgrade the package" or "### Upgrade the package"
depending on desired hierarchy) so they are recognized as headings by
markdownlint MD036; update both occurrences in the snippet to use the
appropriate '#' heading syntax and preserve the following code block and
content.
♻️ Duplicate comments (1)
docs/commands.md (1)
30-39: Add language tags and blank lines around tables (markdownlint compliance).This section still has an untagged fenced block and a table without surrounding blank lines. Please apply the same fix pattern throughout the file.
🧹 Example fix (apply consistently elsewhere)
**Syntax:** -``` +```text /opsx:explore [topic]Arguments:
+
Argument Required Description topicNo What you want to explore or investigate
</details> </blockquote></details> </blockquote></details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Comment on lines
+33
to
+115
| ``` | ||
| You: /opsx:apply | ||
|
|
||
| AI: Working through tasks... | ||
| ✓ Task 1.1: Created caching layer | ||
| ✓ Task 1.2: Added cache invalidation | ||
|
|
||
| Working on 1.3: Implement TTL... | ||
| I noticed the design assumes Redis, but your project uses | ||
| in-memory caching. Should I update the design? | ||
|
|
||
| You: Yes, update it to use the existing cache module. | ||
|
|
||
| AI: Updated design.md to use CacheManager from src/cache/ | ||
| Updated tasks.md with revised implementation steps | ||
| Continuing implementation... | ||
| ✓ Task 1.3: Implemented TTL using CacheManager | ||
| ... | ||
| ``` | ||
|
|
||
| **No restart needed.** Just update the artifact and continue. | ||
|
|
||
| ### Staleness Warning UX | ||
|
|
||
| When user manually edits an upstream artifact: | ||
|
|
||
| ``` | ||
| $ /opsx:apply | ||
|
|
||
| ⚠️ Detected changes to upstream artifacts: | ||
| - design.md modified 5 minutes ago (after tasks.md was generated) | ||
|
|
||
| Options: | ||
| 1. Regenerate tasks (recommended) | ||
| 2. Continue anyway with current tasks | ||
| 3. Cancel | ||
|
|
||
| > | ||
| ``` | ||
|
|
||
| ### Part 2: Regeneration Capability | ||
|
|
||
| Add a way to regenerate specific artifacts: | ||
|
|
||
| ```bash | ||
| # Option A: Flag on continue | ||
| /opsx:continue --regenerate tasks | ||
|
|
||
| # Option B: Separate command | ||
| /opsx:regenerate tasks | ||
|
|
||
| # Option C: Interactive prompt when staleness detected | ||
| /opsx:apply | ||
| # "Design changed. Regenerate tasks? [y/N]" | ||
| ``` | ||
|
|
||
| ## Technical Approach | ||
|
|
||
| ### Option A: Metadata File | ||
| Store `.openspec-meta.json` in change directory: | ||
| ```json | ||
| { | ||
| "tasks.md": { | ||
| "generated_at": "2025-01-24T10:00:00Z", | ||
| "dependencies": { | ||
| "design.md": "2025-01-24T09:55:00Z", | ||
| "specs/feature/spec.md": "2025-01-24T09:50:00Z" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Option B: Frontmatter | ||
| Add YAML frontmatter to generated artifacts: | ||
| ```markdown | ||
| --- | ||
| generated_at: 2025-01-24T10:00:00Z | ||
| depends_on: | ||
| - design.md@2025-01-24T09:55:00Z | ||
| --- | ||
| # Tasks | ||
| ... | ||
| ``` |
Contributor
There was a problem hiding this comment.
Add language identifiers to fenced blocks for lint compliance.
Several fenced blocks are untyped; add language tags (text/json/markdown/bash) for consistent rendering.
🧹 Suggested updates
-```
+```text
You: /opsx:apply
@@
-```bash
+```bash
# Option A: Flag on continue
/opsx:continue --regenerate tasks
@@
-```json
+```json
{
"tasks.md": {
@@
-```markdown
+```markdown
---
generated_at: 2025-01-24T10:00:00Z
depends_on:
- design.md@2025-01-24T09:55:00Z
---
# Tasks
...🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
92-92: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
109-109: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@openspec/changes/add-artifact-regeneration-support/proposal.md` around lines
33 - 115, The markdown in proposal.md contains untyped fenced code blocks;
update each fence to include a language identifier: add ```text to the chat
transcript block starting with "You: /opsx:apply", add ```bash to the shell
snippet that begins "# Option A: Flag on continue" (the /opsx:continue example),
add ```json to the metadata block that begins with `{ "tasks.md": {`, and add
```markdown to the frontmatter block that begins with `--- generated_at:` so all
fenced blocks are explicitly typed for linting and consistent rendering.
README_NEW.md
Outdated
Comment on lines
142
to
148
| **Upgrade the package** | ||
|
|
||
| ```bash | ||
| npm install -g @fission-ai/openspec@latest | ||
| ``` | ||
|
|
||
| **Refresh agent instructions** |
Contributor
There was a problem hiding this comment.
Use headings instead of bold lines for section structure.
Markdownlint MD036 flags bold text used as headings; convert these to actual headings for consistency.
🧹 Suggested tweak
-**Upgrade the package**
+### Upgrade the package
@@
-**Refresh agent instructions**
+### Refresh agent instructions📝 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
| **Upgrade the package** | |
| ```bash | |
| npm install -g @fission-ai/openspec@latest | |
| ``` | |
| **Refresh agent instructions** | |
| ### Upgrade the package | |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
142-142: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
148-148: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In `@README_NEW.md` around lines 142 - 148, Replace bolded lines used as section
titles (e.g., "**Upgrade the package**" and "**Refresh agent instructions**")
with proper markdown headings (e.g., "## Upgrade the package" or "### Upgrade
the package" depending on desired hierarchy) so they are recognized as headings
by markdownlint MD036; update both occurrences in the snippet to use the
appropriate '#' heading syntax and preserve the following code block and
content.
Remove sync from main workflow flows and diagrams since archive already prompts to sync when needed. Most users will never need to call sync directly. - Remove sync from completion flow diagrams - Remove "Sync Specs Regularly" best practice section - Update command descriptions to note it's optional - Update "When to sync" to "When to use manually"
- Simplify badges and logo presentation - Add collapsible "most loved" section - Replace detailed explanation with concise philosophy - Add prominent /opsx:onboard callout for new workflow - Remove README_NEW.md (content merged into README.md) - Remove renewal prompts documentation
Correct commands locations for Antigravity, Codex, Crush, OpenCode, and Qoder in the supported tools table.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@README_OLD.md`:
- Line 200: Fix the typo in the README sentence "You'll be prompted to pick any
natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode,
Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub" by
inserting a space after the comma before "etc." so it reads "Qoder, etc.";
update that exact sentence in README_OLD.md to preserve spacing and punctuation.
🧹 Nitpick comments (1)
README_OLD.md (1)
58-58: Consider adding language specifiers to fenced code blocks.The fenced code blocks at lines 58, 302, and 427 would render more predictably with language specifiers (e.g., ```text for ASCII diagrams).
♻️ Suggested improvements
Line 58 (workflow diagram):
-``` +```text ┌────────────────────┐ │ Draft Change │Line 302 (file tree):
-``` +```text openspec/ ├── specs/Line 427 (workflow diagram):
-``` +```text You can always go back:Also applies to: 302-302, 427-427
| ``` | ||
|
|
||
| **What happens during initialization:** | ||
| - You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub |
Contributor
There was a problem hiding this comment.
Fix typo: missing space before "etc."
There's a missing space between "Qoder," and "etc."
📝 Proposed fix
-- Primary AI tools can trigger `/openspec` workflows without additional configuration
+- Primary AI tools can trigger `/openspec` workflows without additional configuration
- so a fresh launch ensures they appear
+ so a fresh launch ensures they appearWait, let me correct this:
-- You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub
+- You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder, etc.); other assistants always rely on the shared `AGENTS.md` stub📝 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
| - You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub | |
| - You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder, etc.); other assistants always rely on the shared `AGENTS.md` stub |
🤖 Prompt for AI Agents
In `@README_OLD.md` at line 200, Fix the typo in the README sentence "You'll be
prompted to pick any natively supported AI tools (Claude Code, CodeBuddy,
Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared
`AGENTS.md` stub" by inserting a space after the comma before "etc." so it reads
"Qoder, etc."; update that exact sentence in README_OLD.md to preserve spacing
and punctuation.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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
This PR introduces the
/opsx:onboardskill and delivers a comprehensive documentation overhaul.New Feature: Onboarding Skill
/opsx:onboardskill that guides users through their first complete OpenSpec workflowDocumentation Overhaul
Added 9 comprehensive guides:
Removed 5 obsolete planning docs:
Other Changes
Test plan
pnpm test/opsx:onboardin a fresh project🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
Chores
Tests
✏️ Tip: You can customize this high-level summary in your review settings.