skill-system-workflow

Skill System Workflow

skill-system-workflow is the planning layer for the skill system. It turns a goal into a DAG with Mermaid output, prefers reusable recipes when possible, and stays strictly read-only with respect to execution.

Ticket lifecycle operations are owned by skill-system-tkt. This skill now owns only planning, visualization, and recipe discovery.

Overview

• Input: a goal plus optional context
• Output: a DAG document and Mermaid flowchart TD
• Planning strategy: recipe match first, dynamic planning second
• Execution: out of scope; downstream skills consume the DAG

Core Operations

plan

Analyze a goal and produce a workflow DAG plus Mermaid visualization.

1. Read the available recipes/
2. Match goal against trigger_patterns
3. If a recipe matches, adapt it to the goal
4. Otherwise, use prompts/plan-workflow.md to generate a custom DAG
5. Render Mermaid from the DAG using the conventions below

Procedure: scripts/plan-and-visualize.md

visualize

Convert an existing DAG YAML into a Mermaid flowchart.

• Parse waves[*].tasks[*]
• Use one Mermaid subgraph per wave
• Add depends_on edges
• Apply status styling (pending, running, done, failed)

list-recipes

List available workflow recipes by reading recipes/ and returning each recipe's name and description.

File Layout

• prompts/plan-workflow.md: one-pass dynamic DAG planning prompt
• schema/workflow-dag.yaml: workflow DAG shape specification
• schema/recipe.yaml: recipe shape specification
• recipes/*.yaml: reusable workflow templates
• scripts/plan-and-visualize.md: human procedure for plan -> DAG -> Mermaid
• scripts/dispatch.sh: multi-agent dispatch engine (sends opencode run commands)
• scripts/chain.sh: step completion handler (auto-dispatches next step or notifies reviewer)
• schema/dispatch-order.yaml: dispatch order shape specification
• recipes/multi-agent-dispatch.yaml: recipe for cross-repo bundle dispatch

Recipe Format Reference

Recipes are small YAML documents that describe reusable waves and tasks.

• name: recipe identifier (must match the filename without extension)
• trigger_patterns: goal keywords/phrases that indicate the recipe is applicable
• waves: ordered execution waves
• waves[*].parallel: whether tasks in the wave can be performed simultaneously
• waves[*].tasks[*].depends_on: task ids from earlier waves that must complete first

See: schema/recipe.yaml

Mermaid Conventions

Diagram structure

• Graph direction: flowchart TD
• One subgraph per wave: subgraph waveN [Wave N: <description>]
• Each task is a node with id task_id
• Node label format: <agent_type>\n<task name>

Node shapes

• Task nodes: rounded rectangles: task_id(["<agent_type>\\n<name>"])
• Optional start/end anchors (if used): start((Start)), end((End))

Status styling

Use Mermaid classes based on each task's status:

pending: not started
running: in progress
done: completed successfully
failed: needs intervention

Configuration

Runtime settings are in config/workflow.yaml. Config is the single source of truth.

See: ../../config/workflow.yaml

Multi-Agent Dispatch

skill-system-workflow now also orchestrates cross-repo dispatch via opencode run. The TKT-000 integrator ticket pattern from skill-system-tkt serves as the coordination point.

dispatch

Dispatch a bundle's downstream work to multiple project coders.

1. Read the upstream bundle's downstream_bundles field
2. Build a dispatch-order.yaml with steps in dependency order
3. Execute scripts/dispatch.sh to send opencode run commands
4. Coders complete their work and call scripts/chain.sh
5. chain.sh auto-dispatches the next step or notifies the reviewer

Procedure: see recipe multi-agent-dispatch.yaml

Scripts:

• scripts/dispatch.sh <dispatch-order.yaml> — Send opencode run commands
• scripts/chain.sh <dispatch-order.yaml> <step-id> — Handle step completion
• Both support --dry-run for verification

Schema: schema/dispatch-order.yaml

Chain Protocol:

Reviewer → dispatch.sh → opencode run (coder A)
                             ↓ (coder A completes)
                         chain.sh → opencode run (coder B)
                                        ↓ (coder B completes)
                                    chain.sh → notify reviewer

Integration with TKT-000

The TKT-000 integrator ticket coordinates the bundle. When the dispatch chain completes:

1. Each coder marks their bundle as done
2. chain.sh updates the dispatch-order step status
3. On final step: writes .done file or notifies reviewer via claude CLI
4. Reviewer closes the upstream TKT-000

Migration Note

Ticket lifecycle operations are owned by skill-system-tkt. skill-system-workflow handles planning (3 ops: plan, visualize, list-recipes) and now also multi-agent dispatch (dispatch).

Operational Notes

• Keep waves small (2-6 tasks) so the diagram remains readable.
• Prefer parallelism inside a wave; use depends_on for cross-wave ordering.
• Every task should have a clear verification outcome.

{
  "schema_version": "2.0",
  "id": "skill-system-workflow",
  "version": "2.0.0",
  "capabilities": ["workflow-plan", "workflow-visualize", "workflow-list-recipes", "workflow-dispatch"],
  "effects": ["fs.read", "fs.write", "db.read", "proc.exec"],
  "operations": {
    "plan": {
      "description": "Analyze a goal and produce an execution plan as a DAG with Mermaid visualization.",
      "input": {
        "goal": {"type": "string", "required": true, "description": "User's goal or task description"},
        "context": {"type": "string", "required": false, "description": "Additional context (files, constraints)"}
      },
      "output": {
        "description": "Workflow DAG YAML plus Mermaid diagram",
        "fields": {"dag": "YAML", "mermaid": "string"}
      },
      "entrypoints": {
        "agent": "Follow scripts/plan-and-visualize.md procedure"
      }
    },
    "visualize": {
      "description": "Convert an existing DAG YAML to a Mermaid flowchart.",
      "input": {
        "dag_yaml": {"type": "string", "required": true, "description": "DAG YAML content"}
      },
      "output": {
        "description": "Mermaid flowchart string",
        "fields": {"mermaid": "string"}
      },
      "entrypoints": {
        "agent": "Apply Mermaid conventions from SKILL.md to the DAG"
      }
    },
    "list-recipes": {
      "description": "List available workflow recipes.",
      "input": {},
      "output": {
        "description": "Array of recipe names and descriptions",
        "fields": {"recipes": "array"}
      },
      "entrypoints": {
        "agent": "List files in recipes/ directory"
      }
    },
    "dispatch": {
      "description": "Dispatch a bundle's downstream work to multiple project coders via opencode run with automatic chaining.",
      "input": {
        "upstream_bundle": {"type": "string", "required": true, "description": "Path to the upstream bundle directory containing downstream_bundles"},
        "workspace_root": {"type": "string", "required": true, "description": "Absolute path to the workspace root"},
        "dry_run": {"type": "boolean", "required": false, "description": "If true, show commands without executing"}
      },
      "output": {
        "description": "Dispatch order YAML with step statuses",
        "fields": {"dispatch_order": "YAML", "steps_dispatched": "number"}
      },
      "entrypoints": {
        "agent": "Follow recipe multi-agent-dispatch.yaml: build dispatch-order.yaml from bundle, then run scripts/dispatch.sh",
        "cli": "scripts/dispatch.sh <dispatch-order.yaml> [--dry-run]"
      }
    }
  },
  "stdout_contract": {
    "last_line_json": false,
    "note": "Agent-executed procedures; output is DAG YAML and Mermaid text."
  }
}