Skip to content

change(schema-management-cli): proposal for schema management commands #523

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TabishB merged 3 commits into from
Jan 20, 2026
Merged

change(schema-management-cli): proposal for schema management commands #523

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
74ec59c
change(schema-management-cli): add proposal for schema management com…
TabishB Jan 20, 2026
b8e8849
Merge branch 'main' into change/schema-management-cli
TabishB Jan 20, 2026
c87c41d
change(schema-management-cli): add design, tasks, and specs artifacts
TabishB Jan 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions openspec/changes/schema-management-cli/.openspec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-01-20
55 changes: 55 additions & 0 deletions openspec/changes/schema-management-cli/proposal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
## Why

Creating and managing project-local schemas currently requires manual directory creation, copying files, and hoping the structure is correct. Users only discover structural errors at runtime when commands fail. This friction discourages schema customization and makes it harder to tailor OpenSpec workflows to specific project needs.

Key pain points:
- **Manual scaffolding**: Users must manually create `openspec/schemas/<name>/` with correct structure
- **No validation feedback**: Schema errors aren't caught until a command tries to use the schema
- **Starting from scratch is hard**: No easy way to base a custom schema on an existing one
- **Debugging resolution**: When a schema doesn't resolve as expected, there's no way to see the resolution path

## 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
Comment on lines +40 to +45
Copy link

@greptile-apps greptile-apps bot Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


### 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
Comment on lines +11 to +55
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

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.

Loading