---
name: mixersystem
---
# MixerSystem Overview

MixerSystem is a workflow engine for AI-assisted software delivery. It has one standard flow made of five steps — task, plan, work, update, upgrade — 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.

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, a builder agent, and specialized sub-agents that collaborate to produce a single primary artifact. The system's knowledge comes from two sources: **docs** (`doc.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 doc.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-work-folder basis. One work folder = one task = one focused unit of work. The work 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`. Defines what needs to be done. Can pull from Linear via task ID, or be created from a description. A router agent resolves which project modules are relevant.
2. **Plan** (`create_plan`) — Produce `plan.md`. Generates an implementation plan from the task. Runs a 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 builder implements, tests validate, failures feed back into the builder.
4. **Update** (`create_update`) — Analyze completed work and apply documentation updates, producing `update.md` as a report. Reads the work artifact and existing `doc.md` 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.

## Knowledge Model

Projects place `doc.md` files (with `name` YAML frontmatter) 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 work folder
- `resolve_docs()` -> project doc.md files
- `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.

## Sync

The `sync` command (`mixersystem sync`) wires MixerSystem into a project. It scans the project for `doc.md` 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

The task workflow integrates with Linear (configured in user's project in `.mixer/settings.json`), the system fetches and uploads issues from and to Linear for tasks. Tasks can also be pushed to or updated in Linear after creation.

