# 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.
- **Artifact Builder** (`shared/builder.py`) — a single shared artifact builder used by all six workflows. Receives a `stage` parameter and resolves everything from context, including the stage role from `{stage}-prompts.md`.
- **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, and a prompts file (`*-prompts.md`) that contains all stage-specific prompt text — the builder role and the question role. 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

The shared artifact builder returns a `session_id`. Orchestrators with revision loops call `builder.run_resume(stage, feedback, session_id)` to continue the same session with feedback applied.

## Context Injection

Every artifact builder call receives these inputs, resolved from the session folder and project settings:

- **Current artifact** — the existing output file for this stage, if it already exists (revision mode).
- **Artifacts** — other `.md` files already in the session folder (e.g., task.md when building a plan).
- **Docs** — the project's module doc files (`_name.md`), scoped to the modules the task targets.
- **Rules** — action-specific rule files (e.g., `plan` rules when building a plan), module-scoped.
- **Template** — the output template for this stage (`*-template.md`), resolved automatically by stage.
- **Questions** — answered, non-implemented questions for this stage from `<stage>_questions.json`.
- **Instructions** — optional free-text guidance passed at runtime via `--instructions`.

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 artifact builder writes a draft plan. A reviewer checks completeness, rule compliance, and architectural soundness. If it returns NEEDS_WORK, the feedback goes back to the artifact builder. This build-review loop repeats up to `max_revisions` times. Optionally, multiple artifact builders can work in parallel branches — a merger agent synthesizes their drafts into feedback, and the artifact builder writes the final plan from that.

**Work** (`create_work`) — Reads `plan.md` and produces `work.md`. The artifact builder implements code according to the plan. A tester agent runs tests to validate. If tests fail, the failure output goes back to the artifact 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 module doc files, applies documentation updates directly, then produces `update.md` as a report of what was changed. The builder decides how far up the module hierarchy a change needs to propagate, and whether new module docs need to be created.

**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 artifact builder call, no loops.
