mixer-system 0.1.17

MixerSystem workflow engine package

Mixer System

Overview

Mixer System is an AI workflow engine for software development. The core idea is to split work into five discrete steps — task, plan, work, update, and upgrade — with each step backed by its own customizable workflow.

Each workflow is powered by a chain of specialized agents — builders, reviewers, testers, routers, formatters — that use the project's documentation (doc.md) and rule files (.mixer/rules/) for context.

All work happens inside work folders, where artifacts are created for each step - task.md, plan.md, work.md, update.md, upgrade.md. One folder = one unit of work. Work folder holds all artifacts + logging for all agent actions. Workflows can run in 5-step sequence, or skip steps, or run individually in a fresh folder.

Docs and rules are scoped to modules so that agents only receive context relevant to the modules a task targets. A module is any folder in your project that contains a doc.md file. Optionally, you can add rule files - .mixer/rules/<workflow_type>/<module>.md - to control how each workflow's agents behave.

Workflows are called using mixer <workflow> CLI command, which opens an interactive TUI form with pre-filled fields. Workflows can also be called via Claude Code skill through agent conversation.

How to Use

Run any workflow with mixer <workflow>. Add the work folder where you are currently working — if omitted, a new folder is generated automatically.

Each workflow reads the project's docs and rules for context, but also looks at what already exists inside the work folder. If other artifacts are present (typically from the previous steps), the workflow uses them.

Running a workflow when its artifact already exists is a revision - the workflow treats it as an update rather than a fresh build.

No artifacts are required to run a workflow. You can call any workflow on its own — spin up a new work folder and jump straight to building code, or update docs, or upgrade rules.

You can also pass --instructions="..." to any workflow to give the agents additional guidance for that run. You can run each workflow in test mode with mock=true. Each workflow supports different providers such as Claude, Gemini, Codex, or random (picks one at runtime).

It is recommended to commit before running a workflow, so you have a clean checkpoint to revert to. It is also recommended to create a new git branch for each work folder — one branch per task.

Workflows

Task workflow:

• Create a task from description, or load task from Linear, or work on an existing task - produces task.md. The work folder name is used as the task ID (e.g. tasks/SYS-42 → task ID is SYS-42).
  • If the folder name matches the configured Linear prefix, fetches the issue from Linear automatically instead of using a description.
• A router agent auto-resolves which project modules are relevant. Pass --modules=api,web or --modules=all to skip the router and set modules manually.
• --sync=true pushes local tasks to Linear (creates a new issue and renames the work folder to the Linear ID) or overwrites existing Linear issues.
• --instructions passes guidance to the builder agent.

Plan workflow:

• Reads task.md (and/or direct user instructions) , produces plan.md.
• Builder drafts → two reviewers (rules checker + completeness checker) → failed reviews loop back to builder.
• --max_revisions controls how many review cycles (default 2, set to 0 to skip review entirely).
• If plan.md already exists, the builder revises it instead of starting from scratch.
• --branch_count=N (N >= 2) runs N builders in parallel, a merger synthesizes, then the builder writes the final plan from that.
• --plan_builder_provider selects Claude, Gemini, Codex, or random. With branches + random, each branch picks independently.
• Formatter agent standardizes the final output to match the template.

Work workflow:

• Reads plan.md (and/or direct user instructions), produces work.md.
• Builder implements code → tester validates → failed tests loop back.
• --max_test_iterations controls build-test cycles (default 5, set to 0 to skip testing entirely).
• If work.md already exists, the builder revises it.
• Writes a Build Status block at the top of work.md: build succeeded/failed, tests succeeded/failed, iteration count, last test feedback.
• --work_builder_provider selects Claude, Gemini, Codex, or random.
• --instructions is passed to the initial build.

Update workflow:

• Reads work.md (and/or direct user instructions), and edits doc.md files directly. update.md is a report of what changed.
• If update.md already exists, the builder revises it.
• Single agent call, no loops, for now.

Upgrade workflow:

• Reads agent logs (agent_trace.log, agent_raw.log) (and/or direct user instructions), and edits/creates rule files directly. upgrade.md is a report of what changed.
  • Looks for: reviewer rejections, test failure patterns, builder self-corrections, repeated patterns across agents.
• If upgrade.md already exists, the builder revises it.
• Single agent call, no loops, for now.

Setup

Install the package:

pip install mixer-system[tui]

Place doc.md files (with a name field in YAML frontmatter) in any folder you want to declare as a module. Then run sync to register everything:

mixersystem sync

This scans for doc.md files, builds the module tree into .mixer/settings.json, and syncs the coordinator skill to .claude/skills/mixer/SKILL.md. Re-run sync after upgrading the package.

Linear integration (optional): Set LINEAR_API_KEY in your .env and configure team_prefix and team_id in .mixer/settings.json.