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

Each of the five steps (task, plan, work, update, upgrade) 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 `work_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`). Some workflows create intermediate outputs (branch drafts, revision history) but at the end of the day they all produce one file in the work 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> --work_folder=<path>`) and dispatched by the coordinator skill.

## 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 work folder and project settings:

- **Artifacts** — existing `.md` files already in the work 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.

## Appendix Convention

Every artifact file can have an appendix section at the bottom, delimited by `<!-- appendix -->` followed by `<ignore>` tags. The appendix holds metadata useful to humans or specific workflows (brainstorming questions, planning session notes, decision rationale, debugging logs) but that downstream agents should not consume as input.

All agents are instructed (step 0 in quick-start + a constraint) to ignore content after `<!-- appendix -->` and inside `<ignore>` tags when reading files. This keeps agent context clean without requiring programmatic stripping — the convention is enforced via prompt instructions and the agents respect it.

## How Each Workflow Works

**Task** (`create_task`) — Takes a work folder and produces `task.md`. The folder name is used as the task ID. A router agent examines the project's modules and decides which ones are relevant to the task. If the folder name matches the project's Linear prefix (e.g. `tasks/SYS-42`), the orchestrator fetches the issue from Linear instead of building from a description.

**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 work 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.
