docs: rewrite customization guide to document schema commands #582
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
Contributor
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 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 substantially rewrites Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 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. |
Greptile OverviewGreptile SummaryRewrote the customization guide to document the actual Major improvements:
Issues found:
Confidence Score: 4/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant User
participant CLI as openspec CLI
participant Resolver as Schema Resolver
participant Project as openspec/schemas/
participant UserDir as ~/.local/share/openspec/schemas/
participant Package as Built-in schemas/
Note over User,Package: Schema Fork Workflow
User->>CLI: openspec schema fork spec-driven my-workflow
CLI->>Resolver: Find source schema "spec-driven"
Resolver->>Project: Check project schemas
Project-->>Resolver: Not found
Resolver->>UserDir: Check user schemas
UserDir-->>Resolver: Not found
Resolver->>Package: Check package schemas
Package-->>Resolver: Found at schemas/spec-driven/
Resolver-->>CLI: Return source path
CLI->>Project: Copy to openspec/schemas/my-workflow/
CLI->>Project: Update schema.yaml name field
CLI-->>User: Schema forked successfully
Note over User,Package: Schema Resolution Workflow
User->>CLI: openspec new change feature --schema my-workflow
CLI->>Resolver: Resolve schema "my-workflow"
Resolver->>Project: Check openspec/schemas/my-workflow/
Project-->>Resolver: Found (highest priority)
Note over Resolver: Project wins over User and Package
Resolver-->>CLI: Return project schema path
CLI->>Project: Load schema.yaml and templates
CLI-->>User: Use my-workflow schema
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
docs/customization.md
Outdated
Comment on lines
252
to
254
| ``` | ||
| my-workflow resolves from: project | ||
| Source: /path/to/project/openspec/schemas/my-workflow |
There was a problem hiding this comment.
Output format doesn't match actual CLI. The actual output is:
Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow
Not "resolves from:"
Suggested change
| ``` | |
| my-workflow resolves from: project | |
| Source: /path/to/project/openspec/schemas/my-workflow | |
| my-workflow | |
| Source: project | |
| Path: /path/to/project/openspec/schemas/my-workflow |
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/customization.md
Line: 252:254
Comment:
Output format doesn't match actual CLI. The actual output is:
```
Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow
```
Not "resolves from:"
```suggestion
my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow
```
<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>
How can I resolve this? If you propose a fix, please make it concise.| | `src/core/artifact-graph/instruction-loader.ts` | Template loading | | ||
| | `src/core/global-config.ts` | XDG path helpers | | ||
| | `schemas/spec-driven/` | Default schema and templates | | ||
| - [CLI Reference: Schema Commands](cli.md#schema-commands) - Full command documentation |
There was a problem hiding this comment.
Broken link - schemas.md doesn't exist in the repo
Suggested change
| - [CLI Reference: Schema Commands](cli.md#schema-commands) - Full command documentation | |
| - [CLI Reference: Schema Commands](cli.md#schema-commands) - Full command documentation |
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/customization.md
Line: 358:358
Comment:
Broken link - `schemas.md` doesn't exist in the repo
```suggestion
- [CLI Reference: Schema Commands](cli.md#schema-commands) - Full command documentation
```
How can I resolve this? If you propose a fix, please make it concise.
TabishB
force-pushed
the
docs/fix-customization-guide
branch
2 times, most recently
from
a6b4972 to
b5cdb91
Compare
The old guide described a painful manual process for schema customization (mkdir, npm list, cp commands) and even listed "No scaffolding" as a limitation. But the `openspec schema` commands have existed for a while: - `schema fork` - copy existing schema to customize - `schema init` - create new schema from scratch - `schema validate` - check schema structure - `schema which` - debug resolution precedence Rewrote the guide to: - Lead with the actual CLI commands instead of manual steps - Remove the misleading "Current Limitations" section - Add practical examples (TDD workflow, adding review artifact) - Structure progressively: config → custom schemas → global overrides
TabishB
force-pushed
the
docs/fix-customization-guide
branch
from
b5cdb91 to
99acace
Compare
![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: 3
🤖 Fix all issues with AI agents
In `@docs/customization.md`:
- Around line 252-256: The fenced code block containing "Schema: my-workflow",
"Source: project", and "Path: /path/to/project/openspec/schemas/my-workflow" is
missing a language tag; update the block delimiter from ``` to ```text so the
block becomes a fenced "text" block (i.e., replace the opening ``` with ```text)
to satisfy MD040 and ensure proper syntax highlighting.
- Around line 110-118: Update the fenced code block that shows the directory
tree for "openspec/schemas/my-workflow/" by adding a language tag (e.g., text)
after the opening triple backticks so the block becomes a labeled code fence;
ensure the opening fence that currently reads ``` is changed to ```text to
satisfy MD040.
- Around line 110-117: The template filename in
openspec/schemas/my-workflow/templates is inconsistent (uses spec.md) while the
artifact name elsewhere is "specs"; rename spec.md to specs.md and update any
references to the template name (e.g., in schema.yaml or docs) so the template
filename matches the artifact identifier "specs" and aligns with built-in schema
conventions.
docs/customization.md
Outdated
Comment on lines
110
to
117
| ``` | ||
| openspec/schemas/my-workflow/ | ||
| ├── schema.yaml # Workflow definition | ||
| └── templates/ | ||
| ├── proposal.md # Template for proposal artifact | ||
| ├── spec.md # Template for specs | ||
| ├── design.md # Template for design | ||
| └── tasks.md # Template for tasks |
Contributor
There was a problem hiding this comment.
Template filename likely mismatched (spec.md vs specs.md).
Elsewhere the artifact is “specs”, and built-in schemas typically use specs.md. Consider aligning the filename to avoid confusion.
✏️ Proposed fix
- ├── spec.md # Template for specs
+ ├── specs.md # Template for specs🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
110-110: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In `@docs/customization.md` around lines 110 - 117, The template filename in
openspec/schemas/my-workflow/templates is inconsistent (uses spec.md) while the
artifact name elsewhere is "specs"; rename spec.md to specs.md and update any
references to the template name (e.g., in schema.yaml or docs) so the template
filename matches the artifact identifier "specs" and aligns with built-in schema
conventions.
Address review feedback from CodeRabbit: - Add 'text' language tag to directory tree code blocks - Satisfies MD040 markdown lint rule
StrayDragon
pushed a commit
to StrayDragon/OpenSpec
that referenced
this pull request
Jan 26, 2026
…n-AI#582) * docs: rewrite customization guide to document schema commands The old guide described a painful manual process for schema customization (mkdir, npm list, cp commands) and even listed "No scaffolding" as a limitation. But the `openspec schema` commands have existed for a while: - `schema fork` - copy existing schema to customize - `schema init` - create new schema from scratch - `schema validate` - check schema structure - `schema which` - debug resolution precedence Rewrote the guide to: - Lead with the actual CLI commands instead of manual steps - Remove the misleading "Current Limitations" section - Add practical examples (TDD workflow, adding review artifact) - Structure progressively: config → custom schemas → global overrides * docs: add language tags to code blocks in customization guide Address review feedback from CodeRabbit: - Add 'text' language tag to directory tree code blocks - Satisfies MD040 markdown lint rule
3 tasks
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
docs/customization.mdto document the actualopenspec schemaCLI commands instead of a manual processProblem
The old guide described a painful manual workflow:
And explicitly listed these as "Current Limitations":
But these commands have existed for a while:
openspec schema fork- automated scaffoldingopenspec schema init- create from scratchopenspec schema validate- verificationopenspec schema which- resolution debuggingTest plan
🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.