mixer-system 0.1.16

MixerSystem workflow engine package

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).

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:

{ "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

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.