---
name: workflows
---
# Workflows Layer

This file documents the workflows orchestration layer.

## Scope

This layer owns control flow:

- workflow sequencing
- retries and revision loops
- branching and merge orchestration
- handoff between workflow steps and agents

It does not own shared runtime internals (see data-layer docs).

## Current Workflow Features

- `task`: task creation/sync and module routing
- `plan`: plan build/review/format and branch merge
- `work`: build/test loop and work report maintenance
- `update`: doc update suggestions from completed work
- `upgrade`: rule improvement suggestions mined from agent logs

## Orchestrators and Agents

Each workflow feature folder contains:

- orchestrator files (control logic)
- `builder.py` (main builder agent, sits flat in the workflow folder)
- `agents/` subfolder (specialized LLM workers: checkers, formatters, routers, etc.)

All builders return `str` (session_id) from both `run()` and `run_resume()`. The response text is logged by `call_agent` — builders don't pass it up. Orchestrators use the session_id to thread revision loops; single-shot workflows ignore it.

Examples:

- `create_task` orchestrates task flow
- `create_plan` orchestrates build/review/format
- `create_work` orchestrates build/test loop
- `create_update` orchestrates doc update suggestions
- `create_upgrade` orchestrates rule upgrade suggestions

<!-- SKILL_SYNC_WORKFLOW_GUIDE_START -->
<workflows>

create_task — `python3 -m mixersystem run task`
Required: `work_folder`, `task_id`
Optional: `description` (required if task.md doesn't exist yet), `title` (default: "New Task"), `modules` (default: router resolves; accepts "all" or comma-separated names), `size` (default: "M"), `task_prefix`, `sync` / `sync_to_linear`, `api_key`, `team_id`
Produces `task.md`. If `task_id` matches the Linear prefix in settings, fetches from Linear. If `sync=true`, syncs to Linear.

create_plan — `python3 -m mixersystem run plan`
Required: `work_folder` (must contain `task.md`)
Optional: `size` (default: "M"), `plan_builder_provider` (default: "claude"; allowed: claude, gemini, codex), `branch_count` (default: 1), `max_revisions` (default: 2; 0 skips review)
Produces `plan.md`. Runs build → review loop → formatter. If `branch_count` >= 2, runs parallel branch builders, then a merger reviews all branches and passes synthesis feedback to the builder, who writes the final plan.

create_work — `python3 -m mixersystem run work`
Required: `work_folder` (must contain `plan.md`)
Optional: `size` (default: "M"), `max_test_iterations` (default: 5), `auto_commit` (default: true), `auto_merge` (default: false)
Produces `work.md`. Runs build → test loop. On failure, writes failure status and raises. On success with `auto_merge=true`, commits and pushes.

create_update — `python3 -m mixersystem run update`
Required: `work_folder` (must contain `work.md`)
Optional: `size` (default: "M")
Produces `update.md`. Reads work.md and existing doc.md files, suggests documentation updates.

create_upgrade — `python3 -m mixersystem run upgrade`
Required: `work_folder` (must contain `agent_logs/`)
Optional: `size` (default: "M")
Produces `upgrade.md`. Reads all agent log files and existing rules, suggests rule improvements based on generalizable lessons found in logs.

</workflows>
<!-- SKILL_SYNC_WORKFLOW_GUIDE_END -->
