diff --git a/docs/experimental-workflow.md b/docs/experimental-workflow.md index d60415b3a..33c72acbe 100644 --- a/docs/experimental-workflow.md +++ b/docs/experimental-workflow.md @@ -565,35 +565,53 @@ Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, no ### Custom Schemas -Create your own workflow by adding a schema to `~/.local/share/openspec/schemas/`: +Create custom workflows using the schema management commands: +```bash +# Create a new schema from scratch (interactive) +openspec schema init my-workflow + +# Or fork an existing schema as a starting point +openspec schema fork spec-driven my-workflow + +# Validate your schema structure +openspec schema validate my-workflow + +# See where a schema resolves from (useful for debugging) +openspec schema which my-workflow +``` + +Schemas are stored in `openspec/schemas/` (project-local, version controlled) or `~/.local/share/openspec/schemas/` (user global). + +**Schema structure:** ``` -~/.local/share/openspec/schemas/research-first/ +openspec/schemas/research-first/ ├── schema.yaml └── templates/ ├── research.md ├── proposal.md └── tasks.md +``` + +**Example schema.yaml:** +```yaml +name: research-first +artifacts: + - id: research # Added before proposal + generates: research.md + requires: [] -schema.yaml: -┌─────────────────────────────────────────────────────────────────┐ -│ name: research-first │ -│ artifacts: │ -│ - id: research # Added before proposal │ -│ generates: research.md │ -│ requires: [] │ -│ │ -│ - id: proposal │ -│ generates: proposal.md │ -│ requires: [research] # Now depends on research │ -│ │ -│ - id: tasks │ -│ generates: tasks.md │ -│ requires: [proposal] │ -└─────────────────────────────────────────────────────────────────┘ - -Dependency Graph: + - id: proposal + generates: proposal.md + requires: [research] # Now depends on research + - id: tasks + generates: tasks.md + requires: [proposal] +``` + +**Dependency Graph:** +``` research ──► proposal ──► tasks ``` @@ -615,7 +633,22 @@ Schemas define what artifacts exist and their dependencies. Currently available: - **spec-driven** (default): proposal → specs → design → tasks - **tdd**: tests → implementation → docs -Run `openspec schemas` to see available schemas. +```bash +# List available schemas +openspec schemas + +# See all schemas with their resolution sources +openspec schema which --all + +# Create a new schema interactively +openspec schema init my-workflow + +# Fork an existing schema for customization +openspec schema fork spec-driven my-workflow + +# Validate schema structure before use +openspec schema validate my-workflow +``` ## Tips diff --git a/docs/schema-workflow-gaps.md b/docs/schema-workflow-gaps.md index d32778b62..27d76b1f4 100644 --- a/docs/schema-workflow-gaps.md +++ b/docs/schema-workflow-gaps.md @@ -10,18 +10,18 @@ This document analyzes the complete user journey for working with schemas in Ope | Component | Status | |-----------|--------| -| Schema resolution (XDG) | 2-level: user override → package built-in | +| Schema resolution | 3-level: project → user → package (PR #522) | | Built-in schemas | `spec-driven`, `tdd` | | Artifact workflow commands | `status`, `next`, `instructions`, `templates` with `--schema` flag | | Change creation | `openspec new change ` — no schema binding | +| Project-local schemas | ✅ Supported via `openspec/schemas/` (PR #522) | +| Schema management CLI | ✅ `schema which`, `validate`, `fork`, `init` (PR #525) | ### What's Missing | Component | Status | |-----------|--------| | Schema bound to change | Not stored — must pass `--schema` every time | -| Project-local schemas | Not supported — can't version control with repo | -| Schema management CLI | None — manual path discovery required | | Project default schema | None — hardcoded to `spec-driven` | --- @@ -114,13 +114,13 @@ cp -r /schemas/spec-driven/* \ ## Gap Summary -| Gap | Impact | Workaround | -|-----|--------|------------| -| Schema not bound to change | Wrong results, forgotten context | Remember to pass `--schema` | -| No project-local schemas | Can't share via repo | Manual XDG setup per machine | -| No schema management CLI | Manual path hunting | Know XDG + find npm package | -| No project default schema | Must specify every time | Always pass `--schema` | -| No init-time schema selection | Missed setup opportunity | Manual config | +| Gap | Impact | Status | +|-----|--------|--------| +| Schema not bound to change | Wrong results, forgotten context | ⏳ Pending (Phase 1) | +| No project-local schemas | Can't share via repo | ✅ Fixed (PR #522) | +| No schema management CLI | Manual path hunting | ✅ Fixed (PR #525) | +| No project default schema | Must specify every time | ⏳ Pending (Phase 4) | +| No init-time schema selection | Missed setup opportunity | ⏳ Pending (Phase 4) | --- @@ -296,18 +296,17 @@ created: 2025-01-15T10:30:00Z ### Phase 2: Project-Local Schemas -**Priority:** High +**Status:** ✅ Complete (PR #522) **Solves:** Team sharing, version control, no XDG knowledge needed -**Scope:** -- Add `./openspec/schemas/` to resolution order (first priority) -- `openspec schema copy [new-name]` creates in project by default -- `--global` flag for user-level XDG directory +**Implemented:** +- `./openspec/schemas/` added to resolution order (first priority) +- `openspec schema fork [new-name]` creates in project by default - Teams can commit `openspec/schemas/` to repo **Resolution order:** ``` -1. ./openspec/schemas// # Project-local (NEW) +1. ./openspec/schemas// # Project-local 2. ~/.local/share/openspec/schemas// # User global 3. /schemas// # Built-in ``` @@ -316,19 +315,21 @@ created: 2025-01-15T10:30:00Z ### Phase 3: Schema Management CLI -**Priority:** Medium +**Status:** ✅ Complete (PR #525) **Solves:** Path discovery, scaffolding, debugging -**Commands:** +**Implemented Commands:** ```bash -openspec schema list # Show available schemas with sources -openspec schema which # Show resolution path -openspec schema copy [to] # Copy for customization -openspec schema diff # Compare with built-in -openspec schema reset # Remove override -openspec schema validate # Validate schema.yaml structure +openspec schema which [name] # Show resolution path, --all for all schemas +openspec schema validate [name] # Validate schema structure and templates +openspec schema fork [name] # Copy existing schema for customization +openspec schema init # Create new project-local schema (interactive) ``` +**Not implemented (may add later):** +- `schema diff` — Compare override with built-in +- `schema reset` — Remove override, revert to built-in + --- ### Phase 4: Project Config + Init Enhancement diff --git a/src/commands/schema.ts b/src/commands/schema.ts index d80aae151..7f8d0b788 100644 --- a/src/commands/schema.ts +++ b/src/commands/schema.ts @@ -290,7 +290,12 @@ const DEFAULT_ARTIFACTS: Array<{ export function registerSchemaCommand(program: Command): void { const schemaCmd = program .command('schema') - .description('Manage workflow schemas'); + .description('Manage workflow schemas [experimental]'); + + // Experimental warning + schemaCmd.hook('preAction', () => { + console.error('Note: Schema commands are experimental and may change.'); + }); // schema which schemaCmd