docs: update workflow docs and mark schema commands as experimental

[TabishB]

Summary

• Update workflow documentation to reflect implemented schema management features (PR feat(resolver): add project-local schema support #522, feat(cli): add schema management commands #525)
• Mark schema commands as experimental with help text annotation and runtime warning

Changes

• Document schema CLI commands (which, validate, fork, init)
• Update gap summary to show completed phases
• Improve custom schema examples with actual CLI usage
• Add [experimental] tag and runtime warning to schema commands

Test plan

• Verify docs render correctly
• Run openspec schema --help to see [experimental] tag
• Run openspec schema which --all to see runtime warning

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@TabishB has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 4 minutes and 56 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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.

📥 Commits

Reviewing files that changed from the base of the PR and between 3cdcdfc and 2c1fd3f.

📒 Files selected for processing (3)

• docs/experimental-workflow.md
• docs/schema-workflow-gaps.md
• src/commands/schema.ts

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

Updated documentation to reflect implemented schema management features from PRs #522 and #525, and marked schema commands as experimental with [experimental] tag in help text and runtime warning.

• Updated docs/experimental-workflow.md with concrete CLI examples for schema which, validate, fork, and init commands
• Updated docs/schema-workflow-gaps.md to mark Phase 2 (project-local schemas) and Phase 3 (schema management CLI) as complete
• Added [experimental] annotation to schema command description in src/commands/schema.ts:293
• Implemented preAction hook in src/commands/schema.ts:296-298 to display runtime warning when any schema subcommand is invoked
• Marked all 47 tasks as completed in openspec/changes/schema-management-cli/tasks.md
• Registered schema command group in main CLI (src/cli/index.ts:19)
• Added shell completion support for schema commands in src/core/completions/command-registry.ts and new schema-name positional type in src/core/completions/types.ts

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Documentation updates accurately reflect implemented features, experimental markers are properly applied, all tasks completed, comprehensive test coverage (467 lines), and changes are non-breaking additions
• No files require special attention

Important Files Changed

Filename	Overview
docs/experimental-workflow.md	Updated to document schema CLI commands (which, validate, fork, init) with examples and better structure
src/cli/index.ts	Added registration of schema command group to main CLI
src/commands/schema.ts	New file implementing schema management commands with experimental warning, validation, fork, init, and which subcommands
test/commands/schema.test.ts	Comprehensive test suite with 467 lines covering all schema subcommands, edge cases, and error scenarios

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI
    participant SchemaCmd
    participant Resolver
    participant FileSystem

    User->>CLI: openspec schema <subcommand>
    CLI->>SchemaCmd: registerSchemaCommand()
    SchemaCmd->>SchemaCmd: preAction hook
    SchemaCmd-->>User: "Schema commands are experimental"

    alt schema which [name]
        User->>SchemaCmd: which spec-driven
        SchemaCmd->>Resolver: getSchemaDir(name, projectRoot)
        Resolver->>FileSystem: Check project/openspec/schemas/
        Resolver->>FileSystem: Check ~/.local/share/openspec/schemas/
        Resolver->>FileSystem: Check package schemas/
        FileSystem-->>Resolver: Return paths and existence
        Resolver-->>SchemaCmd: First existing location
        SchemaCmd-->>User: Display source and path
    else schema which --all
        User->>SchemaCmd: which --all
        SchemaCmd->>Resolver: listSchemas(projectRoot)
        Resolver->>FileSystem: Read all schema directories
        FileSystem-->>Resolver: All schema names
        SchemaCmd->>SchemaCmd: checkAllLocations for each
        SchemaCmd-->>User: List by source (project, user, package)
    else schema validate [name]
        User->>SchemaCmd: validate my-workflow
        SchemaCmd->>Resolver: getSchemaDir(name, projectRoot)
        Resolver-->>SchemaCmd: Schema directory path
        SchemaCmd->>FileSystem: Read schema.yaml
        FileSystem-->>SchemaCmd: Schema YAML content
        SchemaCmd->>SchemaCmd: parseSchema()
        SchemaCmd->>SchemaCmd: Check template files exist
        SchemaCmd->>SchemaCmd: Validate dependency graph (cycles)
        SchemaCmd-->>User: Validation result
    else schema fork <source> [name]
        User->>SchemaCmd: fork spec-driven my-workflow
        SchemaCmd->>Resolver: getSchemaDir(source, projectRoot)
        Resolver-->>SchemaCmd: Source directory
        SchemaCmd->>FileSystem: Check if destination exists
        alt Destination exists
            SchemaCmd-->>User: Error or confirm overwrite
        else Destination available
            SchemaCmd->>FileSystem: Copy directory recursively
            SchemaCmd->>FileSystem: Update name in schema.yaml
            FileSystem-->>SchemaCmd: Success
            SchemaCmd-->>User: Forked schema created
        end
    else schema init <name>
        User->>SchemaCmd: init my-workflow
        SchemaCmd->>SchemaCmd: Validate name (kebab-case)
        SchemaCmd->>FileSystem: Check if schema exists
        alt Schema exists
            SchemaCmd-->>User: Error or confirm overwrite
        else New schema
            SchemaCmd->>User: Prompt for description
            User-->>SchemaCmd: Enter description
            SchemaCmd->>User: Prompt for artifacts (multi-select)
            User-->>SchemaCmd: Select artifacts
            SchemaCmd->>FileSystem: Create openspec/schemas/<name>/
            SchemaCmd->>FileSystem: Write schema.yaml
            SchemaCmd->>FileSystem: Create template files
            FileSystem-->>SchemaCmd: Success
            SchemaCmd-->>User: Schema initialized
        end
    end

Loading

[vibe-kanban-cloud]

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.