Workflow Definition Schema

Workflow Definition Schema

Machine-readable YAML definitions for workflow commands and the workflow manifest.

Per-Command YAML Schema

Each command has a co-located .yaml file describing its interface.

Annotated Example

# Unique command identifier: {phase}:{action}
command: "discovery:create"

# Workflow phase this command belongs to
phase: discovery

# Relative path to the command's .md implementation file
path: commands/project/discovery/create-epic-discovery.md

# Relative path to the human-readable overview in docs/workflow/
description: docs/workflow/discovery-create.md

# Ordered list of inputs the command accepts
inputs:
  - name: epic-key
    type: string
    required: true
    description: Jira epic key (e.g., CC-60)

# Ordered list of outputs the command produces
outputs:
  - name: discovery-document
    type: url
    path: "/epics/Discovery/{epic-key}/"
    description: Published Confluence discovery document

# Backend capabilities this command depends on
# Valid values: ticketing, documentation, or empty list
requires:
  - ticketing
  - documentation

# Command lifecycle status (default: existing)
status: existing

# CLI syntax hint shown in help text
argument-hint: "<epic-key>"

# Whether this command is invoked multiple times per epic (default: false)
repeat: false

Field Reference

Input Types

Output Types

Workflow Manifest Schema

The manifest at commands/workflow-manifest.yaml defines the phase DAG and command ordering.

Annotated Example

# Manifest schema version
version: "1.0"

# Ordered phases forming the workflow DAG
phases:
  intake:
    # Relative path to the phase overview markdown
    description: docs/workflow/intake-phase.md

    # Phase dependencies (empty = entry point)
    depends_on: []

    # Whether this phase runs once per project (vs. per-epic)
    run_once: true

    # Ordered list of commands in this phase
    commands:
      - command: "intake:document-codebase"
        definition: commands/intake/document-codebase.yaml
      - command: "intake:capture-behavior"
        definition: commands/intake/capture-behavior.yaml
      - command: "intake:create-system-description"
        definition: commands/intake/create-system-description.yaml

  discovery:
    description: docs/workflow/discovery-phase.md
    depends_on:
      - phase: intake
        strength: recommended  # Not strictly required, but recommended
    optional: true             # Phase can be skipped entirely
    external_skills:
      - skill: feature-forge
        role: prerequisite     # Feature-forge identifies unknowns that trigger discovery
    commands:
      - command: "discovery:create"
        definition: commands/project/discovery/create.yaml
      - command: "discovery:synthesize"
        definition: commands/project/discovery/synthesize.yaml
      - command: "discovery:approve"
        definition: commands/project/discovery/approve.yaml

# Utility commands not tied to a specific phase
utilities:
  - command: common-ground
    definition: commands/common-ground/common-ground.yaml
    invocation: on-demand      # Can be invoked at any point

Manifest Field Reference

Validation Rules

1. No cycles: The depends_on graph must be a DAG. A phase cannot transitively depend on itself.
2. Command uniqueness: Every command value across all phases and utilities must be unique.
3. Path resolution: All definition and description paths must resolve to existing files.
4. Phase reference validity: Every depends_on[].phase must reference a phase defined in the manifest.
5. Definition consistency: Each commands[].command must match the command field inside the referenced YAML definition file.
6. Status gating: Commands with status: planned should be flagged as unavailable when the manifest is consumed at runtime.