# MixerSystem Overview

MixerSystem is a workflow engine for AI-assisted software delivery. It has one standard flow made of six steps — task, plan, work, update, upgrade, report — that form a self-correcting loop.

- **Task** — define what needs to be done.
- **Plan** — produce an implementation plan.
- **Work** — implement code and validate with tests.
- **Update** — update documentation based on what was built.
- **Upgrade** — improve the rules that guide how each step runs, feeding lessons learned back into the system.
- **Report** — synthesize a concise report summarizing session artifacts.

Each step is powered by its own workflow — an agentic pipeline built on top of AI agent SDKs. Each workflow has a main create_artifact.py file, an artifact builder agent, and specialized sub-agents that collaborate to produce a single primary artifact. The system's knowledge comes from two sources: **docs** (`_name.md` files placed throughout the project), and **rules** (action-specific rule files) defined in the project root `.mixer` folder that guide how each workflow's builder agent should behave. Each `_name.md` file declares a module, thus making docs module-based so that the agents working on a certain module only fetch information relevant to working on that specific module.

The update step improves the docs; the upgrade step improves the rules. This is the self-correcting nature of the loop.

These workflows are orchestrated by a coordinator agent — a Claude Code skill that knows what each workflow needs, what parameters to pass, and how to run them. The coordinator dispatches work but never does the implementation itself. All actual work happens inside the workflows. The skill for the Claude Code is defined in SKILL.md and during the sync to the project gets the description and the contracts of the workflows appended to it.

Everything operates on a per-session-folder basis. One session folder = one task = one focused unit of work. The session folder is where all artifacts (5 of them), logs, and intermediate outputs live.

The five steps, and what powers them:

1. **Task** (`create_task`) — Establish `task.md` from instructions. Defines what needs to be done. A router agent resolves which project modules are relevant.
2. **Plan** (`create_plan`) — Produce `plan.md`. Generates an implementation plan from the task. Runs an artifact-builder-reviewer loop with optional parallel branching (multiple plan drafts merged into one). Supports multiple LLM providers (Claude, Gemini, Codex).
3. **Work** (`create_work`) — Implement and test, producing `work.md`. Runs a build-test loop: the artifact builder implements, tests validate, failures feed back into the artifact builder.
4. **Update** (`create_update`) — Analyze completed work and apply documentation updates, producing `update.md` as a report. Reads the work artifact and existing module doc files, then edits them directly.
5. **Upgrade** (`create_upgrade`) — Mine agent logs for generalizable lessons and apply rule improvements, producing `upgrade.md` as a report. Reads all log files (`agent_trace.log`, `agent_raw.log`) and existing rules, then edits or creates rule files directly.
6. **Report** (`create_report`) — Synthesize a concise report from session artifacts, producing `report.md`. Reads all available artifacts (task.md through upgrade.md) and writes a summary formatted as a conventional commit message.

## Knowledge Model

Projects place `_name.md` files in modules. The sync step scans for these files and generates `.mixer/settings.json` for context resolution.

Context is module-targeted:

- `modules: all` -> broad project context
- specific modules -> local + inherited context

Context resolution uses dedicated methods on the runtime context:

- `resolve_artifacts()` -> existing `.md` files in the session folder
- `resolve_docs()` -> project module doc files (`_name.md`)
- `resolve_rules(action)` -> action-specific rules files

Rules live in `.mixer/rules/<action>/<module>.md` — grouped by action type (task, plan, work, update, upgrade), with one file per module. Rules are optional.

## Push

The `push` command (`mixersystem push`) scans `.mixer/sessions/` for folders containing `report.md`, extracts commit messages, combines them, runs `git add . && git commit`, archives committed session folders to `.mixer/sessions/.archive/`, and runs `git push`. This is a programmatic command like `sync` — not a workflow.

## Sync

The `sync` command (`mixersystem sync`) wires MixerSystem into a project. It scans the project for `_*.md` module doc files, builds the module tree to put into project's `.mixer/settings.json`. It syncs the coordinator skill (`SKILL.md` file) to `.claude/skills/mixer/SKILL.md` (injecting the workflow registry).

## Linear Integration

Linear import/export is available as a Studio UI capability. When configured (via `LINEAR_API_KEY` env var and `linear.team_prefix` in `.mixer/settings.json`), users can import Linear issues into sessions and export task.md back to Linear directly from the Studio interface.

