Workflow

The workflow section defines the development pipeline that the orchestrator agent follows. Each step calls one or more specialized agents in order.

Schema

workflow:
  task_folder: "./tasks/{task_id}/"
  pipeline:
    - step: refinement
      agent: refinement
      output: refinement.md

    - step: coding
      agents:
        - agent: coding-backend
          output: code-backend.md
          when: repos_include(api, backend)
        - agent: coding-frontend
          output: code-frontend.md
          when: repos_include(frontend)
      parallel: true

    - step: review
      agent: code-reviewer
      output: code-review.md

    - step: qa
      agents: [qa-backend, qa-frontend]
      parallel: true
      tools: [playwright]

    - step: deliver
      actions: [create-pr, notify-slack, update-linear]

Pipeline Steps

Field	Type	Required	Description
`step`	string	Yes	Step name (used as section header)
`agent`	string	No	Single agent to execute
`agents`	array	No	Multiple agents (string names or objects)
`parallel`	boolean	No	Run agents in parallel (default: sequential)
`output`	string	No	Document filename for agent output
`tools`	string[]	No	MCP tools available to this step
`when`	string	No	Condition for executing this step
`actions`	string[]	No	Built-in actions to execute

Task Folder

All task documents are stored in the task_folder. Default: ./tasks/{task_id}/

./tasks/ENG-123/
├── refinement.md
├── code-backend.md
├── code-frontend.md
├── code-review.md
├── qa-backend.md
└── qa-frontend.md

Agent Steps

Single Agent

- step: refinement
  agent: refinement
  output: refinement.md

Multiple Agents (Parallel)

- step: coding
  agents: [coding-backend, coding-frontend]
  parallel: true

Multiple Agents (with conditions)

- step: coding
  agents:
    - agent: coding-backend
      output: code-backend.md
      when: repos_include(api)
    - agent: coding-frontend
      output: code-frontend.md
      when: repos_include(frontend)
  parallel: true

Delivery Actions

The actions field triggers built-in delivery behaviors:

Action	Description
`create-pr`	Create pull requests for each repo with changes
`notify-slack`	Send notification to the configured Slack channel
`notify-slack-prs`	Send PR links to the Slack PRs channel
`update-linear`	Update the Linear task status
`update-linear-status`	Update the Linear task to Review status

- step: deliver
  actions: [create-pr, notify-slack-prs, update-linear-status]

How It Runs

hub generate reads the pipeline and produces orchestrator instructions
You open the project in your AI editor
The orchestrator agent reads the generated rule and follows the pipeline
Each step calls a sub-agent (via the editor’s agent mode)
Agents write output documents to the task folder
The orchestrator validates between steps — asking the user for approval when needed

The editor is the runtime. No daemon, no server, no separate process.

Enforcing the Pipeline

By default, the orchestrator follows the pipeline but may occasionally take shortcuts for simple tasks. Set enforce_workflow: true to add strict enforcement rules to the generated prompt:

workflow:
  enforce_workflow: true
  pipeline:
    - step: refinement
      agent: refinement
    # ...

When enabled, the orchestrator will:

Never skip a step, even for small or “obvious” changes
Always execute steps in order — no reordering, merging, or ad-hoc parallelization
Always delegate to the designated agent instead of attempting the work itself
Always validate outputs before moving to the next step
Ask for confirmation if the user explicitly requests skipping a step

This is recommended for teams that want a consistent, auditable development process on every task.

Prompt Customization

You can inject custom content into the generated orchestrator prompt using the prompt field. This lets you add company-specific instructions, guidelines, or context without editing generated files.

workflow:
  prompt:
    prepend: |
      Always respond in Portuguese.
      Follow the coding standards documented at docs/standards.md.
    append: |
      When in doubt, ask the user before proceeding.
    sections:
      after_repositories: |
        The API uses a custom auth middleware. See api/docs/auth.md for details.
      after_pipeline: |
        Always run linting before committing changes.
      coding_guidelines: |
        Use functional programming patterns where possible.
        Prefer composition over inheritance.

Field	Description
`prepend`	Injected right after the orchestrator introduction
`append`	Added at the very end of the generated prompt
`sections.after_repositories`	Injected after the repositories list
`sections.after_pipeline`	Injected after the pipeline section
`sections.after_delivery`	Injected after the delivery section
`sections.<custom_name>`	Any other key becomes a new `## Section Name` at the end

Custom section keys are converted to title case (e.g., coding_guidelines becomes ## Coding Guidelines).

Validation Flow

Between steps, the orchestrator:

Reads the output document from the previous step
Checks for unanswered questions — asks the user one at a time
Validates completeness — ensures all required sections are filled
Gets user approval before proceeding to the next step

If any validation agent (review, QA) leaves comments, the orchestrator calls the relevant coding agents again to address them before proceeding.

Hooks — Automate workflows with editor lifecycle hooks (format on save, block dangerous commands, session init)
Commands — Create reusable slash commands for your AI editor