Schema-Driven Workflow System (OPSX-based)

[kanfil]

Summary

Implement schema-driven workflow system based on OPSX concepts from OpenSpec. Schemas extend the extension mechanism to define artifact dependencies, command prefixes, and framework options.

Background

• Current workflow is linear and phase-locked
• Need to support customizable schemas with artifact dependencies
• Schemas should be packaged as extensions (addresses [Feature Request] Convert architect commands to extension #36)
• Framework options (tdd, contracts, etc.) should be schema-defined (addresses Add TDD Extension: Strict RED→GREEN→REFACTOR Vertical Slicing #48)

Reference: OPSX Workflow

Proposal

Schema = Extension + Artifacts

Extend extension.yml format with schema: section:

schema_version: "1.0"

extension:
  id: "spec-driven"
  name: "Spec-Driven Workflow"
  version: "1.0.0"
  # ...

schema:
  prefix: "spec"  # Command prefix
  
  options:
    - id: tdd
      default: true
      description: "Enable TDD workflow"
    - id: contracts
      default: true
      description: "Generate API contracts"
    - id: data_models
      default: true
    - id: risk_tests
      default: true
    - id: architecture
      default: false
  
  artifacts:
    - id: spec
      file: spec.md
      requires: []
      
    - id: plan
      file: plan.md
      requires: [spec]
      conditional_outputs:
        - when: contracts
          generates: contracts/
        - when: data_models
          generates: data-model.md
      
    - id: tasks
      file: tasks.md
      requires: [plan]

provides:
  commands:
    - name: "spec.specify"
      file: "commands/specify.md"
      type: workflow
    - name: "spec.clarify"
      file: "commands/clarify.md"
      type: workflow
    - name: "spec.analyze"
      file: "commands/analyze.md"
      type: system

Built-in Schemas

Schema	Prefix	Artifacts
system	/spec.*	None (system commands only)
spec-driven	/spec.*	spec.md → plan.md → tasks.md
spec-driven-build	/spec.*	spec.md → plan.md → tasks.md (lightweight)
architect	/architect.*	adr.md → AD.md

Command Classification

Type	Commands	Description
Workflow (schema-defined)	/spec.specify, /spec.plan, /spec.tasks, /spec.implement, /spec.trace, /spec.clarify, /architect.*	Create artifacts
System (always available)	/spec.analyze, /spec.checklist, /spec.constitution, /spec.levelup	Analyze/manage

Directory Structure

specify/schemas/
├── registry.yaml
├── system/                    # System commands (always loaded)
│   ├── schema.yaml
│   └── commands/
│       ├── analyze.md
│       ├── checklist.md
│       ├── constitution.md
│       └── levelup.md
├── spec-driven/
│   ├── schema.yaml
│   ├── commands/
│   │   ├── specify.md
│   │   ├── plan.md
│   │   ├── tasks.md
│   │   ├── implement.md
│   │   ├── trace.md
│   │   └── clarify.md
│   └── templates/
├── spec-driven-build/
│   └── ...
└── architect/
    ├── schema.yaml
    ├── commands/
    └── templates/

Implementation Phases

Phase	Deliverable
1	Schema YAML format (extends extension.yml with schema: section)
2	Schema engine (src/specify_cli/schemas.py - follows skills pattern)
3	CLI commands (specify schema list|use|validate)
4	Migrate built-in commands to schema structure
5	Configuration (project + user config)

Acceptance Criteria

• Schema YAML format defined and documented
• Schema engine loads schemas from project, user, and built-in locations
• Artifact state detection (READY/BLOCKED/DONE)
• CLI commands for schema management
• Built-in schemas packaged following extension pattern
• Framework options defined per-schema (not global flags)
• Commands auto-suggest next action based on schema state

Blocked By

None (foundational work)

Blocks

• [Feature Request] Convert architect commands to extension #36 (Convert architect commands to extension)
• Add TDD Extension: Strict RED→GREEN→REFACTOR Vertical Slicing #48 (TDD Extension - for option hooks)