> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codemachine.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Examples

> Complete workflow examples for each orchestration pattern.

Learn from complete workflow examples. Each example shows the logical flow and technical implementation for a specific [orchestration pattern](/core-concepts/workflow/orchestration-patterns).

***

## Interactive: Technical Design Review

You respond at every step. Each agent asks questions, gathers insights, and produces output for the next agent.

<Tabs>
  <Tab title="Logical Flow">
    <Steps>
      <Step title="Architect">
        Asks you about requirements, constraints, and tradeoffs.

        <Card title="Input" icon="file-import">
          User Answers + Project context
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Deep-dive analysis through Q\&A → User → Complete system architecture design
        </Card>

        <Card title="Output" icon="file-export">
          `architecture.md` = `{architecture}`
        </Card>
      </Step>

      <Step title="User">
        Review the architecture analysis. Answer follow-up questions.
      </Step>

      <Step title="Security Expert">
        Asks you about security concerns and compliance needs.

        <Card title="Input" icon="file-import">
          `{architecture}`
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Threat modeling and attack surface analysis → User → Security controls and mitigation strategy
        </Card>

        <Card title="Output" icon="file-export">
          `security-review.md` = `{security_review}`
        </Card>
      </Step>

      <Step title="User">
        Review the security assessment. Answer follow-up questions.
      </Step>

      <Step title="Senior Engineer">
        Asks you about implementation preferences and team constraints.

        <Card title="Input" icon="file-import">
          `{architecture}` + `{security_review}`
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Feasibility analysis → User → Final design incorporating all feedback
        </Card>

        <Card title="Output" icon="file-export">
          `final-design.md`
        </Card>
      </Step>

      <Step title="User">
        Review the final design. Confirm everything looks good or request changes.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Technical Implementation">
    ```javascript technical-design-review.workflow.js theme={null}
    export default {
      name: 'Technical Design Review',
      autonomousMode: 'never',

      steps: [
        separator('Architecture'),
        resolveStep('architect', { interactive: true }),

        separator('Security Review'),
        resolveStep('security-expert', { interactive: true }),

        separator('Final Design'),
        resolveStep('senior-engineer', { interactive: true }),
      ],
    };
    ```

    **Key patterns:**

    * `autonomousMode: 'never'` - User controls every step, can't toggle to auto
    * `interactive: true` - Each agent waits for user input before proceeding

    <Note>
      `interactive: true` is the default. If not specified, steps are interactive automatically.
    </Note>
  </Tab>
</Tabs>

***

## Autonomous: Greenfield Project Build

Controller agent runs agents on your behalf. You brief the controller, then review results instead of managing the process.

<Warning>
  Autonomous mode is in beta. Behavior may change as we refine controller-agent coordination.
</Warning>

<Tabs>
  <Tab title="Logical Flow">
    <Steps>
      <Step title="User → Controller">
        Brief the controller with your project idea, constraints, goals, and the full workflow structure.
      </Step>

      <Step title="PM">
        Refines requirements and creates product specification.

        <Card title="Input" icon="file-import">
          Controller's project brief + Constraints
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Requirements gathering → Controller → Product specification
        </Card>

        <Card title="Output" icon="file-export">
          `prd.md` = `{prd}`
        </Card>
      </Step>

      <Step title="Controller">
        Reviews PRD. Proceeds or adjusts.
      </Step>

      <Step title="Architect">
        Designs system architecture based on requirements.

        <Card title="Input" icon="file-import">
          `{prd}` + Controller's Instructions
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          System design → Controller → Architecture decisions
        </Card>

        <Card title="Output" icon="file-export">
          `architecture.md` = `{architecture}`
        </Card>
      </Step>

      <Step title="Controller">
        Reviews architecture. Proceeds or adjusts.
      </Step>

      <Step title="Developer">
        Implements the code based on architecture.

        <Card title="Input" icon="file-import">
          `{prd}` + `{architecture}` + Controller's Instructions
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Implementation → Controller → Code review
        </Card>

        <Card title="Output" icon="file-export">
          `src/*`
        </Card>
      </Step>

      <Step title="Controller">
        Reviews implementation. Proceeds or adjusts.
      </Step>

      <Step title="Tester">
        Writes tests for the implementation. Examines codebase using tools.

        <Card title="Input" icon="file-import">
          `{prd}` + `{architecture}`
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Test planning → Controller → Test implementation
        </Card>

        <Card title="Output" icon="file-export">
          `tests/*`
        </Card>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Technical Implementation">
    ```javascript greenfield-project.workflow.js theme={null}
    export default {
      name: 'Greenfield Project Build',
      controller: controller('project-controller'),
      autonomousMode: 'always',

      steps: [
        separator('Requirements'),
        resolveStep('pm', { interactive: false }),

        separator('Architecture'),
        resolveStep('architect', { interactive: false }),

        separator('Implementation'),
        resolveStep('developer', { interactive: false }),

        separator('Testing'),
        resolveStep('tester', { interactive: false }),
      ],
    };
    ```

    **Key patterns:**

    * `controller()` - Defines the controller agent that orchestrates the workflow
    * `autonomousMode: 'always'` - Controller drives everything, user can't toggle to manual
    * All steps are `interactive: false` - Controller approves transitions, not user

    <Warning>
      Both controller and step agents must have MCP configured for `workflow-signals`. Step agents propose completion, controller approves or rejects.
    </Warning>

    **Agent MCP configuration:**

    ```javascript main.agents.js theme={null}
    module.exports = [
      // Controller - Approves/rejects step transitions
      {
        id: 'project-controller',
        name: 'Project Controller',
        role: 'controller',
        promptPath: path.join(promptsDir, 'controller', 'main.md'),
        mcp: [
          {
            server: 'workflow-signals',
            only: ['approve_step_transition', 'get_pending_proposal'],
          },
        ],
      },

      // Step agents - Propose completion
      {
        id: 'pm',
        name: 'Product Manager',
        promptPath: path.join(promptsDir, 'pm', 'main.md'),
        mcp: [
          {
            server: 'workflow-signals',
            only: ['propose_step_completion'],
          },
        ],
      },

      // ... other step agents with same MCP config
    ];
    ```
  </Tab>
</Tabs>

***

## Continuous: Adding APIs

Auto-advance with zero interaction. You provide a specification file upfront, then agents run to completion.

<Tabs>
  <Tab title="Logical Flow">
    <Steps>
      <Step title="Specification File">
        Define the APIs you need: endpoints, methods, schemas, validation rules.

        <Note>
          Workflows with `specification: true` won't start until this file is provided.
        </Note>

        <Card title="Input" icon="file-import">
          `specification.md` = `{specification}`
        </Card>
      </Step>

      <Step title="API Designer">
        Designs endpoint contracts and schemas from spec.

        <Card title="Input" icon="file-import">
          `{specification}`
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Parse spec → Design contracts → Generate schemas
        </Card>

        <Card title="Output" icon="file-export">
          `api-design.md` = `{api_design}`
        </Card>
      </Step>

      <Step title="Developer">
        Implements the API endpoints. Examines codebase using tools.

        <Card title="Input" icon="file-import">
          `{specification}` + `{api_design}`
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Implement endpoints → Add validation → Wire routes
        </Card>

        <Card title="Output" icon="file-export">
          `src/api/*`
        </Card>
      </Step>

      <Step title="Tester">
        Writes tests for the API. Examines codebase using tools.

        <Card title="Input" icon="file-import">
          `{specification}` + `{api_design}`
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Test planning → Write unit tests → Write integration tests
        </Card>

        <Card title="Output" icon="file-export">
          `tests/api/*`
        </Card>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Technical Implementation">
    ```javascript api-forge.workflow.js theme={null}
    export default {
      name: 'API Forge',
      specification: true,
      autonomousMode: true,

      steps: [
        separator('Design'),
        resolveStep('api-designer', { interactive: false }),

        separator('Implementation'),
        resolveStep('developer', { interactive: false }),

        separator('Testing'),
        resolveStep('tester', { interactive: false }),
      ],
    };
    ```

    **Key patterns:**

    * `specification: true` - Requires a spec file before starting
    * `autonomousMode: true` - Defaults to auto, but user can toggle to manual with `Shift+Tab`
    * All steps are `interactive: false` - Auto-advances through all steps
    * No controller needed - spec file provides all the context
  </Tab>
</Tabs>

***

## Hybrid: Bug Fix Pipeline

Mix interactive and auto-advance agents in the same workflow. Key decisions need you, routine steps don't.

<Tabs>
  <Tab title="Logical Flow">
    <Steps>
      <Step title="Triage (Interactive)">
        Asks you about the bug: What's the issue? Which device? Steps to reproduce?

        <Card title="Input" icon="file-import">
          User Answers
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Gather symptoms → User → Reproduction steps → User → Environment details
        </Card>

        <Card title="Output" icon="file-export">
          `bug-report.md` = `{bug_report}`
        </Card>
      </Step>

      <Step title="User">
        Review bug report. Confirm details are correct.
      </Step>

      <Step title="Reproducer (Auto)">
        Reproduces the bug with gathered insights. Examines codebase using tools.

        <Card title="Input" icon="file-import">
          `{bug_report}`
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Set up environment → Reproduce steps → Confirm bug exists
        </Card>

        <Card title="Output" icon="file-export">
          `reproduction.md` = `{reproduction}`
        </Card>
      </Step>

      <Step title="Investigator (Auto)">
        Finds root cause. Examines codebase using tools.

        <Card title="Input" icon="file-import">
          `{bug_report}` + `{reproduction}`
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Trace execution → Identify root cause → Document findings
        </Card>

        <Card title="Output" icon="file-export">
          `investigation.md` = `{investigation}`
        </Card>
      </Step>

      <Step title="Discuss & Plan (Interactive)">
        Discusses findings with you. Plans the fix together.

        <Card title="Input" icon="file-import">
          `{bug_report}` + `{reproduction}` + `{investigation}`
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Present findings → User → Discuss options → User → Agree on approach
        </Card>

        <Card title="Output" icon="file-export">
          `fix-plan.md` = `{fix_plan}`
        </Card>
      </Step>

      <Step title="User">
        Review the plan. Approve or request changes.
      </Step>

      <Step title="Developer (Auto)">
        Implements the fix. Examines codebase using tools.

        <Card title="Input" icon="file-import">
          `{investigation}` + `{fix_plan}`
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Implement fix → Self-review → Refine
        </Card>

        <Card title="Output" icon="file-export">
          `src/*`
        </Card>
      </Step>

      <Step title="Tester (Auto)">
        Writes tests for the fix. Examines codebase using tools.

        <Card title="Input" icon="file-import">
          `{bug_report}` + `{fix_plan}`
        </Card>

        <Card title="Steps (Chained Prompts)" icon="list-check">
          Write regression test → Write edge case tests → Verify fix
        </Card>

        <Card title="Output" icon="file-export">
          `tests/*`
        </Card>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Technical Implementation">
    ```javascript bug-fix-pipeline.workflow.js theme={null}
    export default {
      name: 'Bug Fix Pipeline',
      autonomousMode: true,

      steps: [
        separator('Triage'),
        resolveStep('triage'),  // Interactive - gathers bug details

        separator('Investigation'),
        resolveStep('reproducer', { interactive: false }),
        resolveStep('investigator', { interactive: false }),

        separator('Planning'),
        resolveStep('planner'),  // Interactive - discuss fix approach

        separator('Implementation'),
        resolveStep('developer', { interactive: false }),
        resolveStep('tester', { interactive: false }),
      ],
    };
    ```

    **Key patterns:**

    * `autonomousMode: true` - Defaults to auto, but user can toggle to manual with `Shift+Tab`
    * Mix of interactive and non-interactive steps
    * Interactive steps: `triage`, `planner` - where decisions matter
    * Auto steps: `reproducer`, `investigator`, `developer`, `tester` - routine work
    * User can take control anytime by toggling to manual mode
  </Tab>
</Tabs>

***

## Sub-Agents: Blueprint Orchestration

Main agents can delegate specialized tasks to sub-agents. The orchestrator coordinates multiple sub-agents to build a complete solution.

<Tabs>
  <Tab title="Logical Flow">
    <Steps>
      <Step title="Analyst">
        Analyzes requirements and creates a specification.

        <Card title="Input" icon="file-import">
          User requirements + Project context
        </Card>

        <Card title="Output" icon="file-export">
          `specification.md` = `{specification}`
        </Card>
      </Step>

      <Step title="Blueprint Orchestrator">
        Coordinates sub-agents to design the architecture. Runs sub-agents in parallel for different domains.

        <Card title="Input" icon="file-import">
          `{specification}`
        </Card>

        <Card title="Sub-Agents" icon="share-nodes">
          `data-architect` → Database schema design

          `api-architect` → API contract design

          `ui-architect` → Component structure design
        </Card>

        <Card title="Output" icon="file-export">
          `blueprint.md` = `{blueprint}` (merged from all sub-agents)
        </Card>
      </Step>

      <Step title="Developer">
        Implements the code based on the blueprint.

        <Card title="Input" icon="file-import">
          `{specification}` + `{blueprint}`
        </Card>

        <Card title="Output" icon="file-export">
          `src/*`
        </Card>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Technical Implementation">
    **Workflow file:**

    ```javascript blueprint-orchestration.workflow.js theme={null}
    export default {
      name: 'Blueprint Orchestration',
      autonomousMode: true,

      steps: [
        separator('Analysis'),
        resolveStep('analyst', { interactive: true }),

        separator('Architecture'),
        resolveStep('blueprint-orchestrator', { interactive: false }),

        separator('Implementation'),
        resolveStep('developer', { interactive: false }),
      ],

      subAgentIds: [
        'data-architect',
        'api-architect',
        'ui-architect',
      ],
    };
    ```

    <Warning>
      Both `agent-coordination` MCP on the main agent and `subAgentIds` in the workflow must be configured for sub-agent orchestration to work.
    </Warning>

    **Main agent with agent-coordination MCP:**

    ```javascript main.agents.js theme={null}
    {
      id: 'blueprint-orchestrator',
      name: 'Blueprint Orchestrator',
      description: 'Coordinates architecture sub-agents',
      promptPath: path.join(promptsDir, 'orchestrator', 'main.md'),
      mcp: [
        {
          server: 'agent-coordination',
          only: ['run_agents', 'get_agent_status', 'list_available_agents'],
          targets: ['data-architect', 'api-architect', 'ui-architect'],
        },
      ],
    }
    ```

    **Sub-agents definition:**

    ```javascript sub.agents.js theme={null}
    module.exports = [
      {
        id: 'data-architect',
        name: 'Data Architect',
        description: 'Designs database schema and data models',
        mirrorPath: path.join(promptsDir, 'sub-agents', 'data-architect.md'),
      },
      {
        id: 'api-architect',
        name: 'API Architect',
        description: 'Designs API contracts and endpoints',
        mirrorPath: path.join(promptsDir, 'sub-agents', 'api-architect.md'),
      },
      {
        id: 'ui-architect',
        name: 'UI Architect',
        description: 'Designs component structure and UI patterns',
        mirrorPath: path.join(promptsDir, 'sub-agents', 'ui-architect.md'),
      },
    ];
    ```

    **Key patterns:**

    * `subAgentIds` in workflow - Declares which sub-agents are available
    * `agent-coordination` MCP - Enables the orchestrator to run sub-agents
    * `targets` - Restricts which sub-agents can be invoked (security)
    * `only` - Limits MCP tools available to the agent
    * Sub-agents run in parallel for faster execution
  </Tab>
</Tabs>

***

## Choosing a Pattern

| Pattern         | User Involvement                 | Best For                                  |
| --------------- | -------------------------------- | ----------------------------------------- |
| **Interactive** | Every step                       | Tasks needing judgment, exploration, Q\&A |
| **Autonomous**  | Brief controller, review results | Long-running tasks, clear objectives      |
| **Continuous**  | None (spec upfront)              | Repeatable, proven workflows              |
| **Hybrid**      | Key decisions only               | Most real-world workflows                 |

<Tip>
  Most workflows end up being **Hybrid** — you want control where it matters and speed everywhere else.
</Tip>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Build Your First Workflow" icon="hammer" href="./your-first-workflow">
    Start building with the basics
  </Card>

  <Card title="Advanced Workflows" icon="wand-magic-sparkles" href="./advanced-workflows">
    Add tracks, conditions, modules, and controllers
  </Card>
</CardGroup>