# MixerSystem

MixerSystem is a Python package that runs AI-powered workflows for task creation, planning, implementation, documentation, and rule improvement — driven by the context you define in a central `.mixer/` folder in your project.

The workflows are built around agentic tools such as Claude Code, Gemini CLI, and Codex CLI.



## How It Works

You configure your project's `.mixer/` folder with docs and rules that shape how each workflow behaves. You run workflows from the terminal — either interactively via `mixer <workflow>` (a form appears with pre-filled fields) or headlessly via `mixer run <workflow> --work_folder=<path> [--key=value...]`.

Everything operates on a **work folder** basis. One work folder = one task = one focused unit of work. The folder name is the task ID — for example, `tasks/SYS-42` means the task ID is `SYS-42`. If the folder doesn't exist, it's created automatically. Each workflow reads from and writes to this folder, producing a single primary artifact (`task.md`, `plan.md`, `work.md`, `update.md`, `upgrade.md`).

```bash
mixer task      # interactive form
mixer plan
mixer work
mixer update
mixer upgrade
```

## Workflows

The core delivery sequence is **task → plan → work → update → upgrade**. Each step feeds into the next, forming a self-correcting loop — update improves the docs, upgrade improves the rules.

All workflows accept an optional `--instructions` parameter for passing ad-hoc guidance to the builder agent at runtime (e.g., `--instructions="Focus on performance"`).

### Task

Creates `task.md` — the starting point for any work item. You provide a work folder and description. A router agent resolves which project modules are relevant (or you specify modules explicitly). Supports syncing tasks to and from Linear.

### Plan

Produces `plan.md`. A builder drafts the plan, then review agents (rules checker and completeness checker) evaluate it. Failed reviews feed back to the builder for revision, up to `max_revisions` times. A formatter standardizes the final output.

Supports parallel branch planning — multiple builders draft independently, a merger synthesizes their work, and the builder writes the final plan from that. You can choose which provider runs the builder (Claude, Gemini, or Codex).

A plan can also be created without a task — in that case the completeness checker is skipped since there's nothing to check against.

### Work

Implements the plan, producing `work.md`. A builder writes the code, then a tester validates it. If tests fail, feedback goes back to the builder. This build-test loop repeats up to `max_test_iterations` times (default 5).

### Update

Produces `update.md` — analyzes completed work against existing `doc.md` files, applies documentation updates directly, and reports what changed.

### Upgrade

Produces `upgrade.md` — mines agent logs (`agent_trace.log`, `agent_raw.log`) for generalizable lessons, applies rule improvements directly, and reports what changed.

## `.mixer/` Configuration

### Docs

Each module in your codebase carries a `doc.md` file with a `name` field in its YAML frontmatter — this is the module's identity anchor. Running `mixersystem sync` scans for these files and builds the module tree into `.mixer/settings.json`. Workflows resolve context by walking the module's ancestor chain, collecting relevant docs along the way.

### Rules

Rules live under `.mixer/rules/`, grouped by action type, with one file per module:

Rules are optional — they give you per-module, per-action control over how builders behave.

## Optional: Linear Integration

Set `LINEAR_API_KEY` in your project `.env` and configure `.mixer/settings.json`:

```json
{ "linear": { "team_prefix": "SYS", "team_id": "" } }
```

Tasks can be fetched from Linear by ID, or pushed/updated in Linear after creation.

A Claude Code skill is also synced to `.claude/skills/mixer/SKILL.md` — it lets you call workflows through an agent conversation, useful for remote sessions.


## Setup

```bash
pip install mixer-system[tui]
mixersystem sync
```

To target a different project: `mixersystem sync --project_root=/path/to/project`

After upgrading (`pip install -U mixer-system`), re-run `mixersystem sync` to refresh generated files.

`sync` scans your project for `doc.md` files, builds the module tree into `.mixer/settings.json`, and syncs the coordinator skill to `.claude/skills/mixer/SKILL.md`.