mixer-system 0.1.11

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.

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 scans your project for doc.md files, builds the module tree into .mixer/settings.json, syncs the coordinator skill to .claude/skills/mixer/SKILL.md, and registers Claude Code hooks in .claude/settings.json.

How It Works

You configure your project's .mixer/ folder with docs and rules that shape how each workflow behaves. After running mixersystem sync, a Claude Code skill is wired to your project. You interact with that skill (the coordinator) to run workflows — it knows what each workflow needs, what parameters to pass, and how to dispatch them. All actual work happens inside the workflows.

Everything operates on a work folder basis. One work folder = one task = one focused unit of work. Each workflow reads from and writes to this folder, producing a single primary artifact (task.md, plan.md, work.md, update.md, upgrade.md).

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 task ID, title, 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 and suggests concrete documentation updates.

Upgrade

Produces upgrade.md — mines agent logs (agent_trace.log, agent_raw.log, conversation.log) for generalizable lessons and suggests improvements to project rules.

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

Hooks

A Claude Code hook (conversation_logger.py) runs on every prompt submit and stop event during a session. It logs timestamped conversation turns to logs/conversation.log in the active work folder. This log is one of the inputs the upgrade workflow uses to mine for lessons.

Optional: Linear Integration

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

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

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