openspec-schema-authoring

name	openspec-schema-authoring
description	Create or customize OpenSpec workflow schemas in this repository using `openspec schema init` and `openspec schema fork`. Use when the user wants to add, fork, or validate a schema under `openspec/schemas/`.
license	MIT
compatibility	Requires openspec CLI.
metadata	{"author":"openspec","version":"1.0","generatedBy":"1.0.0"}

Create or customize an OpenSpec workflow schema in this repository.

Goal: produce a repository-local schema folder under openspec/schemas/<schema-name>/ containing schema.yaml and templates/.

Steps

1. Decide whether to initialize or fork

   • Use init for a brand-new schema.
   • Use fork to customize an existing schema (preferred when starting from a known workflow).

2. Discover available schemas to fork

   openspec schemas --json
   

3. Option A: Initialize a new schema

   openspec schema init <schema-name>
   

   Common flags:

   • --description "..." to describe the workflow
   • --artifacts "proposal,specs,design,tasks" to set artifact IDs
   • --default to set as project default
   • --no-default to skip the interactive default prompt

   Expected result: openspec/schemas/<schema-name>/schema.yaml and openspec/schemas/<schema-name>/templates/.

4. Option B: Fork an existing schema

   openspec schema fork <source> [new-schema-name]
   

   Sources can be:

   • Repository-local schemas
   • Built-in upstream schemas provided by the CLI

   Expected result: openspec/schemas/<new-schema-name>/schema.yaml and openspec/schemas/<new-schema-name>/templates/.

5. Edit schema internals

   Ensure:

   • artifacts[].id matches intended workflow sequence
   • artifacts[].requires matches dependencies
   • artifacts[].generates matches artifact output paths
   • Template files exist in openspec/schemas/<schema-name>/templates/ for each artifact

6. Validate changed schemas (required)

   openspec schema validate <schema-name>
   

   This is the supported schema quality gate for OpenSpec CLI 1.3.1. Do not use openspec schema review; that command is not available in this CLI.

7. Debug schema resolution if behavior is unexpected

   openspec schema which <schema-name>
   

Done Criteria

• Schema exists under openspec/schemas/<schema-name>/.
• schema.yaml and templates/ are both present.
• openspec schema validate <schema-name> passes.

Guardrails

• Prefer openspec schema fork over manual copying.
• Keep schemas repository-local under openspec/schemas/.
• Do not skip validation before considering work complete.