openspec-schema-authoring

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/.

1. 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/.

2. 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

3. 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.

4. 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.