mixer-system 0.1.7

MixerSystem workflow engine package

MixerSystem

MixerSystem is a Python package that runs AI-powered workflows for task creation, planning, implementation, rule updates, and documentation — 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.

You configure your project's .mixer/ folder with instructions that shape how each workflow behaves, run mixersystem sync, and MixerSystem generates runtime config and a Claude Code skill wired to your project context. From there, you can use the wired Mixer skill in Claude Code to start running these workflows.

See the details of provided workflows at the bottom of this doc.

Setup

pip install mixer-system
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 generates: .mixer/settings.json, .mixer/README.md, .claude/skills/mixer/SKILL.md, and Claude Code hooks in .claude/settings.json

Optional: Linear Integration

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

{ "linear": { "team_prefix": "IOSAI", "team_id": "" } }

Workflows

MixerSystem provides five workflows built around fundamental actions. The core delivery sequence is task → plan → work → update → upgrade. Each action produces a primary artifact in the task's work folder.

Task

Creates and configures task.md — the starting point for any work item. You provide a task ID, title, and description. MixerSystem routes the task to the right modules based on your project context (or you specify modules explicitly). Supports syncing tasks to and from Linear.

Plan

Produces plan.md from the task. An agentic builder drafts the plan using your project context, then a review cycle (completeness, rules) checks and revises it. Supports parallel branch planning — multiple builders draft independently, then a merger reviews and synthesizes feedback for the builder to write the final plan. You can choose which provider runs the builder (Claude, Gemini, or Codex).

Work

Implements the plan. A builder agent writes the code, then a tester agent validates it in a build/test loop (up to a configurable number of iterations). The loop continues until tests pass or the iteration limit is reached. Produces work.md with build status. Supports auto-commit and auto-merge when running inside a git repo.

Update

Produces update.md — analyzes completed work and suggests documentation updates to existing doc.md files.

Upgrade

Produces upgrade.md — mines agent logs for generalizable lessons and suggests improvements to project rules.

.mixer/ Configuration

Module-specific instructions live under .mixer/modules/, with one folder per module:

.mixer/
  modules/
    cli/
      plan.md       # how to create plans for this module
      work.md       # how to build work for this module
    generator/
      work.md       # how to build work for this module

Each module in the codebase carries a doc.md with a name field in its frontmatter — the stable identity anchor. The folder name in .mixer/modules/ matches the module name.

Workflows resolve context by walking the module's ancestor chain in the settings tree, collecting doc and rules files along the way.