docs(readme): show what a spec actually looks like in "See it in action"#1365
docs(readme): show what a spec actually looks like in "See it in action"#1365clay-good wants to merge 1 commit into
Conversation
Answers discussion #1024: the README walkthrough showed the workflow creating specs/ but never the content of a spec. Add a collapsible example spec delta right after the transcript, plus links to this repo's own live openspec/specs and openspec/changes as real examples. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughREADME.md now includes a collapsible section explaining generated ChangesREADME documentation
Estimated code review effort: 1 (Trivial) | ~2 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@README.md`:
- Around line 82-85: Update the README guidance around the `specs/` folder and
the `## ADDED Requirements` example to explicitly identify it as a change delta
format for `openspec/changes/<name>/specs/`, and distinguish it from permanent
specs, which use `## Requirements`. Clarify that the delta format should not be
copied into archived or permanent specs.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| Plain Markdown — requirements with concrete scenarios, no special syntax to learn. Here's what goes in the `specs/` folder created above: | ||
|
|
||
| ```markdown | ||
| ## ADDED Requirements |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Clarify that this is a change delta, not a permanent spec.
The sample starts with ## ADDED Requirements, which is the format parsed from a change’s openspec/changes/<name>/specs/ directory. Permanent specs use ## Requirements; calling this simply the specs/ folder could lead readers to copy the delta format into archived specs and fail validation.
Proposed wording
-Plain Markdown — requirements with concrete scenarios, no special syntax to learn. Here's what goes in the `specs/` folder created above:
+Plain Markdown — requirements with concrete scenarios, no special syntax to learn. Here's what goes in the change's `specs/` folder created above:📝 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.
| Plain Markdown — requirements with concrete scenarios, no special syntax to learn. Here's what goes in the `specs/` folder created above: | |
| ```markdown | |
| ## ADDED Requirements | |
| Plain Markdown — requirements with concrete scenarios, no special syntax to learn. Here's what goes in the change's `specs/` folder created above: | |
🤖 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 `@README.md` around lines 82 - 85, Update the README guidance around the
`specs/` folder and the `## ADDED Requirements` example to explicitly identify
it as a change delta format for `openspec/changes/<name>/specs/`, and
distinguish it from permanent specs, which use `## Requirements`. Clarify that
the delta format should not be copied into archived or permanent specs.
1 participant
Status: Ready for review. Docs-only — 23 lines added to README.md, nothing else touched.
What was missing: The "See it in action" walkthrough shows
/opsx:proposecreating aspecs/folder, but the README never shows what a spec actually contains. That is the first thing a newcomer evaluating OpenSpec wants to see — and exactly what discussion #1024 (originally filed as #1022) asks for: "actual spec powering this example are not seen anywhere … maybe link specs of openspec if you use it on this repo?"What it does: Adds a collapsible "What do the specs actually look like?" block right after the walkthrough transcript, containing:
## ADDED Requirements→### Requirement:→#### Scenario:with WHEN/THEN), matching the real delta format used across this repo's own changesopenspec/specsandopenspec/changes, since OpenSpec is built with OpenSpec — real examples at scaleProof: The example format was checked against real artifacts in this repo (
openspec/changes/simplify-skill-installation/specs/propose-workflow/spec.md,openspec/specs/context-injection/spec.md). Collapsed by default, so the README's above-the-fold flow is unchanged.Notes: Answers discussion #1024. Written with Claude Code using Claude Fable 5 (claude-fable-5).
🤖 Generated with Claude Code
Summary by CodeRabbit
specs/folder.