feat(cli): add schema management commands #525
Merged
+1,594
−48
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 `openspec schema` command group with subcommands for managing workflow schemas: - `schema which [name]` - Show where a schema resolves from with shadow detection across project/user/package locations - `schema validate [name]` - Validate schema structure, templates, and dependency graph - `schema fork <source> [name]` - Copy an existing schema to project for customization - `schema init <name>` - Create a new project-local schema with interactive or CLI-driven configuration All commands support `--json` output for scripting. The init command supports interactive prompts for description and artifact selection. Implements the schema-management-cli change proposal.
Contributor
📝 WalkthroughWalkthroughThis PR introduces a comprehensive schema management CLI command module with subcommands for discovering, validating, forking, and initializing schemas. It includes schema resolution utilities, validation logic, template handling, directory operations, and extensive test coverage. Task documentation is marked complete. Changes
Sequence DiagramssequenceDiagram
actor User
participant CLI as CLI (index.ts)
participant SchemaCmd as Schema Command
participant Resolver as Schema Resolver
participant Parser as YAML Parser
participant FS as Filesystem
User->>CLI: schema validate my-schema
CLI->>SchemaCmd: registerSchemaCommand()
SchemaCmd->>Resolver: resolveSchema('my-schema')
Resolver->>FS: search project/user/package dirs
FS-->>Resolver: schema.yaml path
Resolver-->>SchemaCmd: SchemaInfo
SchemaCmd->>Parser: parse schema.yaml
Parser-->>SchemaCmd: parsed schema object
SchemaCmd->>SchemaCmd: validate dependencies
SchemaCmd->>FS: check template existence
FS-->>SchemaCmd: template status
SchemaCmd->>CLI: return validation results
CLI-->>User: display results (JSON/human)
sequenceDiagram
actor User
participant CLI as CLI (index.ts)
participant SchemaCmd as Schema Command
participant Resolver as Schema Resolver
participant FS as Filesystem
participant Config as Config File
User->>CLI: schema init --description "My Schema"
CLI->>SchemaCmd: registerSchemaCommand()
SchemaCmd->>SchemaCmd: prompt for schema name (if interactive)
SchemaCmd->>SchemaCmd: validate name (kebab-case)
SchemaCmd->>Resolver: getProjectSchemasDir()
Resolver-->>SchemaCmd: project schema directory
SchemaCmd->>FS: check destination exists
FS-->>SchemaCmd: exists/not exists
User->>SchemaCmd: select artifacts
SchemaCmd->>SchemaCmd: wire artifact dependencies
SchemaCmd->>FS: create schema directory
SchemaCmd->>FS: write schema.yaml with metadata
SchemaCmd->>FS: generate default templates
alt Set as Default
SchemaCmd->>Config: update config (if --default flag)
end
SchemaCmd->>CLI: return init results
CLI-->>User: display results (JSON/human)
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 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. ✨ Finishing touches
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 markdownlint-cli2 (0.18.1)openspec/changes/schema-management-cli/tasks.mdmarkdownlint-cli2 v0.18.1 (markdownlint v0.38.0) 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 comprehensive schema management CLI with four subcommands for inspecting, validating, forking, and creating workflow schemas. Key Changes:
Implementation Quality:
Confidence Score: 5/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant User
participant CLI as CLI (index.ts)
participant SchemaCmd as Schema Command
participant Resolver as resolver.ts
participant Parser as schema.ts
participant FS as File System
Note over User,FS: Schema Which Command
User->>CLI: openspec schema which <name>
CLI->>SchemaCmd: Execute which action
SchemaCmd->>Resolver: checkAllLocations(name, projectRoot)
Resolver->>FS: Check project/schemas/<name>/schema.yaml
FS-->>Resolver: exists/not exists
Resolver->>FS: Check user/schemas/<name>/schema.yaml
FS-->>Resolver: exists/not exists
Resolver->>FS: Check package/schemas/<name>/schema.yaml
FS-->>Resolver: exists/not exists
Resolver-->>SchemaCmd: Return locations array
SchemaCmd->>SchemaCmd: Build resolution with shadow info
SchemaCmd-->>User: Display source, path, shadows
Note over User,FS: Schema Validate Command
User->>CLI: openspec schema validate <name>
CLI->>SchemaCmd: Execute validate action
SchemaCmd->>Resolver: getSchemaDir(name, projectRoot)
Resolver-->>SchemaCmd: Return schema directory path
SchemaCmd->>FS: Read schema.yaml
FS-->>SchemaCmd: YAML content
SchemaCmd->>Parser: parseSchema(content)
Parser->>Parser: Validate structure & dependencies
Parser-->>SchemaCmd: Schema object or throw error
SchemaCmd->>FS: Check template files exist
FS-->>SchemaCmd: exists/not exists for each
SchemaCmd->>SchemaCmd: Collect validation issues
SchemaCmd-->>User: Display valid/invalid with issues
Note over User,FS: Schema Fork Command
User->>CLI: openspec schema fork <source> [name]
CLI->>SchemaCmd: Execute fork action
SchemaCmd->>SchemaCmd: Validate destination name (kebab-case)
SchemaCmd->>Resolver: getSchemaDir(source, projectRoot)
Resolver-->>SchemaCmd: Source schema directory
SchemaCmd->>FS: Check destination exists
FS-->>SchemaCmd: exists check result
alt Destination exists and --force
SchemaCmd->>FS: Remove existing destination
end
SchemaCmd->>FS: Copy directory recursively
SchemaCmd->>FS: Read copied schema.yaml
FS-->>SchemaCmd: Schema content
SchemaCmd->>Parser: parseSchema(content)
Parser-->>SchemaCmd: Schema object
SchemaCmd->>SchemaCmd: Update name field
SchemaCmd->>FS: Write updated schema.yaml
SchemaCmd-->>User: Display source and destination paths
Note over User,FS: Schema Init Command
User->>CLI: openspec schema init <name>
CLI->>SchemaCmd: Execute init action
SchemaCmd->>SchemaCmd: Validate name (kebab-case)
alt Interactive mode
SchemaCmd->>User: Prompt for description
User-->>SchemaCmd: Enter description
SchemaCmd->>User: Prompt for artifacts (multi-select)
User-->>SchemaCmd: Select artifacts
SchemaCmd->>User: Set as default schema?
User-->>SchemaCmd: Yes/No
end
SchemaCmd->>SchemaCmd: Build schema with dependencies
SchemaCmd->>FS: Create schema directory
SchemaCmd->>FS: Write schema.yaml
SchemaCmd->>FS: Create template files in templates/
alt Set as default
SchemaCmd->>FS: Update openspec/config.yaml
end
SchemaCmd-->>User: Display created path and next steps
|
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: 2
🤖 Fix all issues with AI agents
In `@src/commands/schema.ts`:
- Around line 986-992: The returned template in the switch case 'tasks'
currently uses plain bullet entries; update the returned multi-line string in
the case 'tasks' (the return that begins with "## Implementation Tasks") to use
the numbered checklist format required for tasks.md by replacing each "- [ ]
Task X" line with "- [ ] X.Y Description" entries (e.g., "- [ ] 1.1 …", "- [ ]
1.2 …", "- [ ] 1.3 …") so the checklist follows the X.Y numeric pattern while
preserving the header and overall string return in that case branch.
- Around line 459-464: When outputting JSON in the validation flow (the branch
that checks options?.json and the other JSON branch around the later block), set
process.exitCode = 1 when anyInvalid is true so callers can detect failures;
update the blocks that currently console.log(JSON.stringify({ valid:
!anyInvalid, schemas: schemaResults }, null, 2)) to also set process.exitCode =
1 when anyInvalid is truthy, keeping the same JSON payload and existing control
flow for valid cases.
Comment on lines
+459
to
+464
| if (options?.json) { | ||
| console.log(JSON.stringify({ | ||
| valid: !anyInvalid, | ||
| schemas: schemaResults, | ||
| }, null, 2)); | ||
| } else { |
Contributor
There was a problem hiding this comment.
Set non‑zero exit codes on validation failures even with --json.
Right now the JSON branches return without setting process.exitCode, so scripted usage can’t detect invalid schemas by exit status.
✅ Proposed fix
if (options?.json) {
console.log(JSON.stringify({
valid: !anyInvalid,
schemas: schemaResults,
}, null, 2));
+ if (anyInvalid) {
+ process.exitCode = 1;
+ }
} else { if (options?.json) {
console.log(JSON.stringify({
name,
path: schemaDir,
valid: result.valid,
issues: result.issues,
}, null, 2));
+ if (!result.valid) {
+ process.exitCode = 1;
+ }
} else {Also applies to: 511-517
🤖 Prompt for AI Agents
In `@src/commands/schema.ts` around lines 459 - 464, When outputting JSON in the
validation flow (the branch that checks options?.json and the other JSON branch
around the later block), set process.exitCode = 1 when anyInvalid is true so
callers can detect failures; update the blocks that currently
console.log(JSON.stringify({ valid: !anyInvalid, schemas: schemaResults }, null,
2)) to also set process.exitCode = 1 when anyInvalid is truthy, keeping the same
JSON payload and existing control flow for valid cases.
Comment on lines
+986
to
+992
| case 'tasks': | ||
| return `## Implementation Tasks | ||
| - [ ] Task 1 | ||
| - [ ] Task 2 | ||
| - [ ] Task 3 | ||
| `; |
Contributor
There was a problem hiding this comment.
Align the default tasks template with the required numbered checklist format.
The template currently uses generic bullet tasks, which conflicts with the required “X.Y” checkbox format for tasks.md.
✅ Proposed fix
case 'tasks':
- return `## Implementation Tasks
-
-- [ ] Task 1
-- [ ] Task 2
-- [ ] Task 3
-`;
+ return `## 1. Implementation Tasks
+
+- [ ] 1.1 Task description
+- [ ] 1.2 Task description
+- [ ] 1.3 Task description
+`;As per coding guidelines, tasks.md should use numbered - [ ] X.Y entries.
🤖 Prompt for AI Agents
In `@src/commands/schema.ts` around lines 986 - 992, The returned template in the
switch case 'tasks' currently uses plain bullet entries; update the returned
multi-line string in the case 'tasks' (the return that begins with "##
Implementation Tasks") to use the numbered checklist format required for
tasks.md by replacing each "- [ ] Task X" line with "- [ ] X.Y Description"
entries (e.g., "- [ ] 1.1 …", "- [ ] 1.2 …", "- [ ] 1.3 …") so the checklist
follows the X.Y numeric pattern while preserving the header and overall string
return in that case branch.
3 tasks
TabishB
added a commit
that referenced
this pull request
Jan 20, 2026
…526) * docs: update workflow docs for schema management CLI Update documentation to reflect implemented schema management features: - Document schema CLI commands (which, validate, fork, init) - Update gap summary to show completed phases (PR #522, #525) - Improve custom schema examples with actual CLI usage - Update resolution order documentation * feat(cli): mark schema commands as experimental Add [experimental] tag to help description and runtime warning for schema management commands to indicate they may change.
StrayDragon
pushed a commit
to StrayDragon/OpenSpec
that referenced
this pull request
Jan 20, 2026
Add `openspec schema` command group with subcommands for managing workflow schemas: - `schema which [name]` - Show where a schema resolves from with shadow detection across project/user/package locations - `schema validate [name]` - Validate schema structure, templates, and dependency graph - `schema fork <source> [name]` - Copy an existing schema to project for customization - `schema init <name>` - Create a new project-local schema with interactive or CLI-driven configuration All commands support `--json` output for scripting. The init command supports interactive prompts for description and artifact selection. Implements the schema-management-cli change proposal.
StrayDragon
pushed a commit
to StrayDragon/OpenSpec
that referenced
this pull request
Jan 20, 2026
…ission-AI#526) * docs: update workflow docs for schema management CLI Update documentation to reflect implemented schema management features: - Document schema CLI commands (which, validate, fork, init) - Update gap summary to show completed phases (PR Fission-AI#522, Fission-AI#525) - Improve custom schema examples with actual CLI usage - Update resolution order documentation * feat(cli): mark schema commands as experimental Add [experimental] tag to help description and runtime warning for schema management commands to indicate they may change.
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 for managing workflow schemasschema whichshows where a schema resolves from with shadow detectionschema validatevalidates schema structure, templates, and dependency graphschema forkcopies an existing schema to project for customizationschema initcreates a new project-local schema with interactive or CLI-driven configurationImplements the schema-management-cli change proposal.
Test plan
schema-namepositional type🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes
New Features
Tests
✏️ Tip: You can customize this high-level summary in your review settings.