# MixerSystem

MixerSystem is a Python package that runs AI-powered workflows for task creation, planning, and implementation — driven by the context you define in lightweight `.mix` guidance files throughout your project.

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

You add `.mix` files (`doc.md`, `rules.md`, `structure.md`, `test.md`) to modules in your project, 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

```bash
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`

## Optional: Linear Integration

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

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

## Workflows

MixerSystem provides three workflows that run in sequence: **task → plan → module**. Each stage 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 `.mix` 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 multi-agent review cycle (architecture, completeness, rules) checks and revises it. Supports parallel branch planning — multiple builders draft independently, then a merger combines the best parts. You can choose which provider runs the builder (Claude, Gemini, or Codex).

### Module

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 `module.md` with build status. Supports auto-commit and auto-merge when running inside a git repo.

## `.mix` Configuration

Each module in your project can contain a `.mix/` folder with any of these files:

| File | Purpose |
|---|---|
| `doc.md` | Module documentation and context |
| `rules.md` | Coding rules and constraints |
| `structure.md` | Expected file/folder structure |
| `test.md` | Testing instructions and expectations |

Workflows resolve context based on which modules the task targets — specific modules get local + inherited context, `modules: all` gets broad project context.
