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

Each of the six steps (task, plan, work, update, upgrade, report) is implemented as a workflow. A workflow is a folder containing:

- **Orchestrator** (`create_*.py`) — the control flow. Calls agents, manages loops, handles branching.
- **Builder** (`builder.py`) — the main agent that does the primary LLM work. Every workflow has one.
- **Sub-agents** (`agents/`) — optional specialized agents for reviewing, routing, formatting, testing, or merging.

All workflows operate inside a `session_folder`. If the folder doesn't exist, it's created automatically. They read inputs from it and write their primary artifact into it — one markdown file per step (`task.md`, `plan.md`, `work.md`, `update.md`, `upgrade.md`, `report.md`). Some workflows create intermediate outputs (branch drafts, revision history) but at the end of the day they all produce one file in the session folder.

Each workflow has a markdown template (`*-template.md`) that defines the structure of its output artifact. Every agent returns its response using `[RESULT]` and `[NOTES]` blocks — the orchestrator parses these to determine the outcome and extract feedback.

Each agent declares a model tier — S (small), M (medium), or L (large) — which gets mapped to the corresponding model of the provider (e.g., L maps to Opus for Claude). In test mode, all agents downgrade to S.

Workflows are invoked via CLI (`python3 -m mixersystem run <step> --session_folder=<path>`) and dispatched by the coordinator skill. The `push` command is a programmatic utility (not a workflow) that scans for `report.md` files, git commits, archives sessions, and pushes.

## Session ID

Every builder returns a `session_id`. Builders with revision loops expose `run_resume(feedback, session_id)` to continue the same session.

## Context Injection

Every builder receives three inputs resolved from the session folder and project settings:

- **Artifacts** — existing `.md` files already in the session folder (e.g., task.md when building a plan).
- **Docs** — the project's `doc.md` files, scoped to the modules the task targets.
- **Rules** — action-specific rule files (e.g., `plan.md` rules when building a plan), also module-scoped.
- **Instructions** — optional free-text guidance passed at runtime via `--instructions`. When provided, injected into the builder's prompt. Gives per-run control without modifying rule files.

This is how agents know about the project and what constraints to follow.

## How Each Workflow Works

**Task** (`create_task`) — Takes a session folder and produces `task.md` from instructions. A router agent (called as a pre-flight check by the Studio start endpoint) examines the project's modules and decides which ones are relevant to the task.

**Plan** (`create_plan`) — Reads `task.md` and produces `plan.md`. The builder writes a draft plan. Two review agents (rules checker and completeness checker) evaluate it in parallel. If either returns NEEDS_WORK, their feedback goes back to the builder for revision. This build-review loop repeats up to `max_revisions` times. A formatter agent standardizes the final output. Optionally, multiple builders can work in parallel branches — a merger agent synthesizes their drafts into feedback, and the builder writes the final plan from that.

**Work** (`create_work`) — Reads `plan.md` and produces `work.md`. The builder implements code according to the plan. A tester agent runs tests to validate. If tests fail, the failure output goes back to the builder. This build-test loop repeats up to `max_test_iterations` times. Supports multiple LLM providers (Claude, Gemini, Codex).

**Update** (`create_update`) — Reads `work.md` and the project's existing `doc.md` files, applies documentation updates directly, then produces `update.md` as a report of what was changed.

**Upgrade** (`create_upgrade`) — Reads all logs from the session folder (`agent_trace.log`, `agent_raw.log`) and the project's existing rules, applies rule improvements directly, then produces `upgrade.md` as a report of what was changed.

**Report** (`create_report`) — Reads all session artifacts (task.md, plan.md, work.md, update.md, upgrade.md) and synthesizes a concise report. Produces `report.md`. Single builder call, no loops.
