change(schema-management-cli): proposal for schema management commands #523
+525
−0
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
…mands Propose new CLI commands to improve the UX of creating and managing project schemas: - `openspec schema init <name>` - Interactive wizard to scaffold new schemas - `openspec schema fork <source> [name]` - Copy existing schema for customization - `openspec schema validate [name]` - Validate schema structure before runtime - `openspec schema which <name>` - Debug schema resolution path
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. 📝 WalkthroughWalkthroughAdds a schema-management CLI feature proposal and supporting docs: a metadata file plus design, specs, and task checklist describing four new subcommands (init, fork, validate, which) and their interactive/non-interactive behaviors, resolution rules, outputs, and validation requirements. Changes
Sequence Diagram(s)sequenceDiagram
participant User as User (CLI)
participant CLI as openspec CLI
participant Resolver as Schema Resolver
participant FS as Filesystem / Package Store
participant Config as Config Manager
User->>CLI: run "openspec schema <command> [args]"
CLI->>Resolver: resolve schema name / location (project → user → package)
Resolver->>FS: read schema files / templates
alt command == init
CLI->>User: prompt interactive inputs (description, artifacts, default?)
User-->>CLI: answers
CLI->>FS: create `openspec/schemas/<name>/` and write `schema.yaml` & templates
CLI->>Config: optionally set defaultSchema
else command == fork
CLI->>Resolver: locate source schema
Resolver->>FS: copy source dir -> destination (check overwrite/--force)
else command == validate
CLI->>FS: read schema.yaml and templates
CLI->>Resolver: compute dependency graph
CLI->>CLI: run validation checks (YAML, templates, DAG)
else command == which
CLI->>Resolver: compute resolution and shadows
end
CLI->>User: print text or JSON result / exit code
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 SummaryProposes adding Issues Found:
Next Steps:
Confidence Score: 1/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant User
participant CLI as openspec CLI
participant Resolver as Schema Resolver
participant FS as File System
participant Templates as Template Manager
Note over User,Templates: Schema Init Flow
User->>CLI: openspec schema init my-schema
CLI->>User: Prompt for description
User->>CLI: Provide description
CLI->>User: Select artifacts to include
User->>CLI: Select artifacts
CLI->>Templates: Get schema templates
Templates-->>CLI: Return template files
CLI->>FS: Create openspec/schemas/my-schema/
CLI->>FS: Write schema.yaml with metadata
CLI->>FS: Write artifact template files
CLI->>User: Set as project default?
User->>CLI: Yes
CLI->>FS: Update openspec/config.yaml
CLI-->>User: Schema created successfully
Note over User,Templates: Schema Fork Flow
User->>CLI: openspec schema fork spec-driven
CLI->>Resolver: Resolve source schema location
Resolver-->>CLI: Return schema path
CLI->>FS: Copy schema to project
CLI->>FS: Rename to spec-driven-custom
CLI-->>User: Schema forked successfully
Note over User,Templates: Schema Validate Flow
User->>CLI: openspec schema validate my-schema
CLI->>FS: Read openspec/schemas/my-schema/schema.yaml
FS-->>CLI: Return schema config
CLI->>CLI: Validate schema.yaml structure
CLI->>FS: Check template file references
FS-->>CLI: Report missing/malformed files
CLI-->>User: Validation results
Note over User,Templates: Schema Which Flow
User->>CLI: openspec schema which my-schema
CLI->>Resolver: Resolve schema location
Resolver->>FS: Check project schemas
Resolver->>FS: Check user overrides
Resolver->>Templates: Check package built-ins
Resolver-->>CLI: Return resolution path
CLI-->>User: Schema resolves from: project
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Additional Comments (1)
-
openspec/changes/schema-management-cli/proposal.md, line 1-56 (link)logic: Missing required
tasks.mdfile. According toopenspec/AGENTS.md:198-205, every change proposal needs atasks.mdwith implementation steps formatted as a checklist (e.g.,- [ ] 1.1 Task description).See
openspec/changes/add-feedback-command/tasks.mdfor reference structure.
2 files reviewed, 2 comments
Comment on lines
+40
to
+45
|
|
||
| ### New Capabilities | ||
| - `schema-init-command`: Interactive wizard for creating new project schemas with guided prompts | ||
| - `schema-fork-command`: Copy existing schemas to project for customization | ||
| - `schema-validate-command`: Validate schema structure and report errors before runtime | ||
| - `schema-which-command`: Debug schema resolution by showing which location is used |
There was a problem hiding this comment.
logic: Missing required specs/ directory with delta files. Since new capabilities are being added (schema-init-command, schema-fork-command, schema-validate-command, schema-which-command), you must create spec deltas under openspec/changes/schema-management-cli/specs/<capability-name>/spec.md with ## ADDED Requirements sections per openspec/AGENTS.md:177-195.
Each capability needs:
- At least one requirement with
### Requirement:header - At least one scenario per requirement with
#### Scenario:header (4 hashtags) - WHEN/THEN format for scenarios
See openspec/changes/add-feedback-command/specs/cli-feedback/spec.md for reference.
Prompt To Fix With AI
This is a comment left during a code review.
Path: openspec/changes/schema-management-cli/proposal.md
Line: 40:45
Comment:
**logic:** Missing required `specs/` directory with delta files. Since new capabilities are being added (`schema-init-command`, `schema-fork-command`, `schema-validate-command`, `schema-which-command`), you must create spec deltas under `openspec/changes/schema-management-cli/specs/<capability-name>/spec.md` with `## ADDED Requirements` sections per `openspec/AGENTS.md:177-195`.
Each capability needs:
- At least one requirement with `### Requirement:` header
- At least one scenario per requirement with `#### Scenario:` header (4 hashtags)
- WHEN/THEN format for scenarios
See `openspec/changes/add-feedback-command/specs/cli-feedback/spec.md` for reference.
How can I resolve this? If you propose a fix, please make it concise.![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 `@openspec/changes/schema-management-cli/proposal.md`:
- Around line 11-55: The change set is missing required artifacts—add a tasks.md
and the required delta spec files under the same change folder as proposal.md
(i.e., openspec/changes/<id>/tasks.md and openspec/changes/<id>/delta-*.yaml),
and optionally include design.md; ensure .openspec.yaml remains and that
tasks.md lists actionable tasks for implementing the new openspec schema
commands (schema init, fork, validate, which) and references the proposal.md and
any delta specs so the change folder is complete for the release process.
🧹 Nitpick comments (1)
openspec/changes/schema-management-cli/proposal.md (1)
52-54: Use direct file references with line numbers in Impact.
Guidelines require explicit references likefile.ts:42(and specs likespecs/auth/spec.md). Please replace broad paths likesrc/commands/andopenspec/config.yamlwith concrete file:line references. As per coding guidelines.
Comment on lines
+11
to
+55
| ## What Changes | ||
|
|
||
| Add a new `openspec schema` command group with subcommands for creating, forking, validating, and inspecting schemas. | ||
|
|
||
| ### Commands | ||
|
|
||
| 1. **`openspec schema init <name>`** - Interactive wizard to scaffold a new project schema | ||
| - Prompts for schema description | ||
| - Prompts for artifacts to include (with explanations) | ||
| - Creates valid directory structure with `schema.yaml` and template files | ||
| - Optionally sets as project default in `openspec/config.yaml` | ||
|
|
||
| 2. **`openspec schema fork <source> [name]`** - Copy an existing schema as a starting point | ||
| - Copies from user override or package built-in | ||
| - Allows renaming (defaults to `<source>-custom`) | ||
| - Preserves all templates and configuration | ||
|
|
||
| 3. **`openspec schema validate [name]`** - Validate schema structure and templates | ||
| - Checks `schema.yaml` is valid | ||
| - Verifies all referenced templates exist | ||
| - Reports missing or malformed files | ||
| - Run without name to validate all project schemas | ||
|
|
||
| 4. **`openspec schema which <name>`** - Show schema resolution path | ||
| - Displays which location the schema resolves from (project/user/package) | ||
| - Shows full path to schema directory | ||
| - Useful for debugging shadowing issues | ||
|
|
||
| ## Capabilities | ||
|
|
||
| ### New Capabilities | ||
| - `schema-init-command`: Interactive wizard for creating new project schemas with guided prompts | ||
| - `schema-fork-command`: Copy existing schemas to project for customization | ||
| - `schema-validate-command`: Validate schema structure and report errors before runtime | ||
| - `schema-which-command`: Debug schema resolution by showing which location is used | ||
|
|
||
| ### Modified Capabilities | ||
| <!-- None - these are additive commands --> | ||
|
|
||
| ## Impact | ||
|
|
||
| - **Code**: New command implementations in `src/commands/` using existing resolver infrastructure | ||
| - **CLI**: New `schema` command group with 4 subcommands | ||
| - **Dependencies**: May use `enquirer` or similar for interactive prompts in `schema init` | ||
| - **Documentation**: Need to update CLI reference and schema customization guide |
Contributor
There was a problem hiding this comment.
Add required change artifacts (tasks.md and any required delta specs).
This change folder only shows proposal.md and .openspec.yaml, but the process expects openspec/changes/<id>/tasks.md (and delta specs; design.md optional). Please add the missing artifacts. As per learnings, scaffold proposal.md, tasks.md, optional design.md, and delta specs under openspec/changes/<id>/.
🤖 Prompt for AI Agents
In `@openspec/changes/schema-management-cli/proposal.md` around lines 11 - 55, The
change set is missing required artifacts—add a tasks.md and the required delta
spec files under the same change folder as proposal.md (i.e.,
openspec/changes/<id>/tasks.md and openspec/changes/<id>/delta-*.yaml), and
optionally include design.md; ensure .openspec.yaml remains and that tasks.md
lists actionable tasks for implementing the new openspec schema commands (schema
init, fork, validate, which) and references the proposal.md and any delta specs
so the change folder is complete for the release process.
Add implementation artifacts for the schema management CLI feature: - Design document with decisions and rationale - Task breakdown for implementation - Specs for schema init, fork, validate, and which commands
5 tasks
StrayDragon
pushed a commit
to StrayDragon/OpenSpec
that referenced
this pull request
Jan 20, 2026
Fission-AI#523) * change(schema-management-cli): add proposal for schema management commands Propose new CLI commands to improve the UX of creating and managing project schemas: - `openspec schema init <name>` - Interactive wizard to scaffold new schemas - `openspec schema fork <source> [name]` - Copy existing schema for customization - `openspec schema validate [name]` - Validate schema structure before runtime - `openspec schema which <name>` - Debug schema resolution path * change(schema-management-cli): add design, tasks, and specs artifacts Add implementation artifacts for the schema management CLI feature: - Design document with decisions and rationale - Task breakdown for implementation - Specs for schema init, fork, validate, and which commands
harikrishnan83
added a commit
to intent-driven-dev/OpenSpec
that referenced
this pull request
Jan 21, 2026
# By Tabish Bidiwale (57) and others # Via GitHub * main: (67 commits) fix(ci): use workflow_dispatch for polish release notes (Fission-AI#533) fix(changelog): convert markdown headers to bold text for proper formatting (Fission-AI#532) Version Packages (Fission-AI#531) Add changeset for project config and schema commands (Fission-AI#530) fix(config): handle null rules field in project config (Fission-AI#529) docs: update workflow docs and mark schema commands as experimental (Fission-AI#526) feat(cli): add schema management commands (Fission-AI#525) fix: Windows path compatibility in resolver tests (Fission-AI#524) change(schema-management-cli): proposal for schema management commands (Fission-AI#523) feat(resolver): add project-local schema support (Fission-AI#522) docs: add project-config demo guide (Fission-AI#521) feat(config): add project-level configuration via openspec/config.yaml (Fission-AI#499) fix: auto-trigger polish release notes on release publish (Fission-AI#519) perf: add path filtering to Nix validation CI job (Fission-AI#518) Version Packages (Fission-AI#517) Add changeset for v0.21 release (Fission-AI#516) fix: prevent implementation during explore mode (Fission-AI#515) OPSX apply: infer target change (Fission-AI#513) Refine opsx archive sync assessment (Fission-AI#514) feat: add nix flake support (sorry for this duplicate) (Fission-AI#459) ... # Conflicts: # src/core/templates/slash-command-templates.ts
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
openspec schemacommand group to improve schema management UXinit,fork,validate,whichProposed Commands
openspec schema init <name>openspec schema fork <source> [name]openspec schema validate [name]openspec schema which <name>Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.