TOON Specification

imports:        # optional — external schemas, services, components, plugins, agents
name:           # required — workflow name
agents:         # optional — named agent declarations (not needed if agents are imported or steps use run/handler)
input:          # required — input schema
schemas:        # optional — reusable output schemas
components:     # optional — reusable step groups
steps:          # required — the workflow graph

name: bugfix-pipeline

input:
  ticketId: string
  description: string

input: TicketInput

agents:
  coder:
    type: claude-code
    subscription: true
    instructions: You are a senior software engineer.

  reviewer:
    type: codex
    fullAuto: true

  analyst:
    type: anthropic
    model: claude-opus-4-6
    instructions: You are a data analyst.

agents:
  custom-agent:
    type: api
    provider: anthropic
    model: claude-sonnet-4-20250514
    instructions: You are a helpful assistant.

schemas:
  Review:
    approved: boolean
    feedback: string

components:
  ReviewCycle:
    params:
      content: string
    steps[1]:
      - id: "{id}-review"
        prompt: Review {params.content}.
        output:
          approved: boolean

- id: analyze
  agent: coder
  prompt: Analyze the code.
  output: AnalysisOutput
  needs[2]: step-id-1,step-id-2
  maxAttempts: 3
  timeout: 5m
  skipIf: "expression"

- id: transform
  handler: ./handlers/transform.ts#processData
  output:
    result: string

- kind: sequence
  children[2]:
    - id: a
      ...
    - id: b
      ...

- kind: parallel
  maxConcurrency: 2       # optional — defaults to unlimited
  children[2]:
    - id: x
      ...
    - id: y
      ...

- kind: loop
  id: review-loop         # optional — loop identifier
  until: "expression"     # required — stop condition
  maxIterations: 5        # optional — safety limit (default: 5)
  onMaxReached: fail | return-last  # optional — default: return-last
  children[1]:
    - id: check
      ...

- kind: approval
  id: approve-deploy      # required — gate identifier
  needs[1]: build         # optional — dependencies
  request:                # required — approval request
    title: "Deploy?"
    summary: "Details..."
  onDeny: fail | continue | skip  # optional — default: fail

- kind: branch
  condition: "expression" # required — branch condition
  then[1]:                # required — steps if true
    - id: a
      ...
  else[1]:                # optional — steps if false
    - id: b
      ...

- kind: worktree
  path: ./feature         # required — worktree path
  children[1]:
    - id: implement
      ...

- kind: workflow
  id: run-tests            # required — step identifier
  use: testSuite           # required — workflow alias from imports
  input:                   # optional — input mapping
    repo: "{input.repoUrl}"
    branch: "{checkout.branch}"

- id: my-review           # required — caller id (used for ID interpolation)
  kind: component
  use: ReviewCycle         # required — component name
  with:                    # required — parameter values
    content: "{draft.content}"
    reviewer: "tech lead"

{expression}     — interpolate a value
{{               — literal {
}}               — literal }

imports:
  schemas[1]{from,use}:
    ./path.ts,TypeName

imports:
  services[1]{from,use}:
    ./path.ts,ServiceTag

imports:
  components[1]{from,use}:
    ./path.toon,ComponentName

imports:
  workflows[1]{from,as}:
    ./path.toon,aliasName

imports:
  plugins[1]:
    - from: package-name
      config:
        key: value