feat: add agent schema selection to experimental artifact workflow #445
Conversation
- Add `openspec schemas` CLI command with `--json` option for agents - Add `listSchemasWithInfo()` helper to get schema metadata (name, description, artifacts) - Update `openspec-new-change` skill to prompt for schema selection - Update `openspec-continue-change` skill to read schema dynamically from status - Update `openspec-apply-change` skill to use schema-specific context files - Update all slash commands (/opsx:new, /opsx:continue, /opsx:apply) to be schema-agnostic - Add documentation for when to use each schema (spec-driven vs tdd) Agents can now create changes with different workflow schemas and the skills dynamically adapt based on the selected schema's artifact sequence.
📝 WalkthroughWalkthroughThis PR introduces schema-aware workflow selection and discovery. It adds a new Schemas CLI command that lists available schemas with metadata, implements schema information retrieval via Changes
Sequence DiagramsequenceDiagram
participant User as User/CLI
participant CLI as artifact-workflow.ts
participant Resolver as artifact-graph/resolver
participant Templates as skill-templates.ts
User->>CLI: Run schemas command
CLI->>Resolver: listSchemasWithInfo()
Resolver->>Resolver: Read user override schemas
Resolver->>Resolver: Read package schemas (schema.yaml)
Resolver-->>CLI: Return SchemaInfo[]
CLI-->>User: Display schemas (name, description, artifacts)
User->>Templates: Create new change workflow
Templates->>User: Prompt for schema selection
User-->>Templates: Choose schema (e.g., spec-driven)
Templates->>Templates: Retrieve schema-specific artifact sequence
Templates->>Templates: Set schema context in status/instructions
Templates-->>User: Show workflow with selected schema
Templates->>Templates: Guide artifact creation per schema sequence
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
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. |
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
src/core/artifact-graph/resolver.ts (1)
174-226: Implementation correctly handles schema precedence and error cases.The function properly:
- Processes user schemas first to establish precedence
- Uses
seenNamesSet to prevent duplicates- Silently skips invalid schemas (appropriate for discovery APIs)
- Returns consistently sorted results
The implementation shares iteration logic with
listSchemas(). Consider extracting a shared helper if this pattern grows, but this is optional given the current scope.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
openspec/changes/add-agent-schema-selection/tasks.mdsrc/commands/artifact-workflow.tssrc/core/artifact-graph/index.tssrc/core/artifact-graph/resolver.tssrc/core/templates/skill-templates.ts
🧰 Additional context used
📓 Path-based instructions (2)
openspec/changes/**/*.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Scaffold proposal using
proposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/
Files:
openspec/changes/add-agent-schema-selection/tasks.md
openspec/changes/*/tasks.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
tasks.mdcontains implementation checklist with numbered sections and checkbox items
Files:
openspec/changes/add-agent-schema-selection/tasks.md
🧠 Learnings (12)
📓 Common learnings
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
openspec/changes/add-agent-schema-selection/tasks.mdsrc/core/templates/skill-templates.ts
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
openspec/changes/add-agent-schema-selection/tasks.mdsrc/core/templates/skill-templates.ts
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
openspec/changes/add-agent-schema-selection/tasks.mdsrc/core/templates/skill-templates.ts
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Include at least one `#### Scenario:` per requirement in spec delta files
Applied to files:
openspec/changes/add-agent-schema-selection/tasks.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
openspec/changes/add-agent-schema-selection/tasks.mdsrc/core/templates/skill-templates.ts
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
openspec/changes/add-agent-schema-selection/tasks.mdsrc/core/templates/skill-templates.ts
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
openspec/changes/add-agent-schema-selection/tasks.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Run `openspec validate [change-id] --strict` before requesting approval
Applied to files:
src/core/templates/skill-templates.ts
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
src/core/templates/skill-templates.ts
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes
Applied to files:
src/core/templates/skill-templates.ts
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Search existing work using `openspec spec list --long`, `openspec list` for enumerating changes; use `rg` only for full-text search
Applied to files:
src/core/templates/skill-templates.ts
🧬 Code graph analysis (2)
src/core/artifact-graph/resolver.ts (2)
src/core/artifact-graph/index.ts (5)
SchemaInfo(29-29)listSchemasWithInfo(24-24)getUserSchemasDir(27-27)parseSchema(12-12)getPackageSchemasDir(26-26)src/core/artifact-graph/schema.ts (1)
parseSchema(23-45)
src/commands/artifact-workflow.ts (2)
src/core/artifact-graph/index.ts (1)
listSchemasWithInfo(24-24)src/core/artifact-graph/resolver.ts (1)
listSchemasWithInfo(174-226)
🔇 Additional comments (12)
openspec/changes/add-agent-schema-selection/tasks.md (1)
1-32: Well-structured task checklist.The file correctly follows the required format with numbered sections and checkbox items. All implementation tasks for schema selection are marked complete, aligning with the PR's code changes. Based on coding guidelines, this file meets the
tasks.mdrequirements.src/core/templates/skill-templates.ts (6)
40-87: Schema selection workflow is well-integrated.The template correctly introduces schema selection as a discrete step, uses
openspec schemas --jsonfor discovery, defaults tospec-driven, and propagates the selection toopenspec new change --schema. The guardrail at line 87 ensures the schema choice is preserved.
123-201: Schema-aware continue workflow is comprehensive.The template correctly parses
schemaNamefrom status JSON, documents multiple schema patterns (spec-driven, tdd), and includes a sensible fallback for custom schemas. The new guardrails (lines 200-201) properly avoid hardcoded artifact assumptions.
229-352: Apply workflow properly handles schema-specific context.The template correctly reads schema from status JSON, uses dynamic
contextFilesfrom apply instructions, and consistently displays the schema in all output states. The guardrails at lines 346 and 352 appropriately avoid hardcoded file assumptions.
399-445: Slash command template is consistent with skill template.The
/opsx:newcommand template correctly mirrors the skill template's schema selection workflow, with appropriate slash command-specific messaging (e.g., referencing/opsx:continue).
470-560: Continue slash command properly mirrors skill template.Schema-aware updates are consistent with
getContinueChangeSkillTemplate. The artifact patterns and guardrails align correctly.
583-719: Apply slash command is consistent with skill template.All schema-aware updates mirror the corresponding
getApplyChangeSkillTemplatefunction correctly.src/core/artifact-graph/index.ts (1)
21-30: Clean API surface expansion.The new exports
listSchemasWithInfoandtype SchemaInfofollow the existing export pattern and correctly expose the new schema metadata functionality fromresolver.ts.src/commands/artifact-workflow.ts (3)
17-29: Imports correctly added.The new imports
listSchemasWithInfoandtype SchemaInfoare properly imported from the artifact-graph module.
833-851: Schema listing command is well-implemented.The command correctly uses
listSchemasWithInfo()to fetch schema metadata and provides both JSON and human-readable output formats. The formatting clearly shows schema name, source (user override vs package), description, and artifact sequence.Note: The function is marked
asyncbut doesn't useawait. This is harmless and consistent with other command handlers in this file that may need async operations in the future.
917-930: Command registration follows established patterns.The
schemassubcommand is properly registered with the[Experimental]tag,--jsonoption, and error handling consistent with other commands in this file.src/core/artifact-graph/resolver.ts (1)
159-168: Well-designed interface.
SchemaInfoprovides a clean API surface with appropriate typing. Thesourceunion type provides type safety for distinguishing user overrides from package built-ins.
Summary
openspec schemasCLI command with--jsonoption for agents to list available workflow schemasopenspec-new-changeskill to prompt users for schema selection (spec-driven, tdd, etc.)openspec status --json/opsx:new,/opsx:continue,/opsx:apply) to work with any schemaChanges
CLI
openspec schemascommand lists schemas with descriptions and artifact sequenceslistSchemasWithInfo()helper function for programmatic accessSkill Templates
openspec-new-change: Now prompts for schema selection before creating a changeopenspec-continue-change: Reads schema from status output, provides schema-specific guidanceopenspec-apply-change: Uses dynamic context files based on schemaSlash Commands
/opsx:*commands updated to support schema selection and dynamic artifact handlingTest plan
openspec schemasand verify it lists spec-driven and tdd schemasopenspec schemas --jsonand verify JSON output includes name, description, artifactsopenspec artifact-experimental-setupand verify updated skills are generated🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes
schemascommand displays available workflow schemas with descriptions and metadata.✏️ Tip: You can customize this high-level summary in your review settings.