Metadata-Version: 2.1
Name: mixer-system
Version: 0.1.6
Summary: MixerSystem workflow engine package
License: Proprietary
Keywords: ai,workflow,automation,developer-tools
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: python-dotenv
Requires-Dist: claude-agent-sdk
Provides-Extra: release
Requires-Dist: build>=1.2.2; extra == "release"
Requires-Dist: twine>=5.1.1; extra == "release"

# 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

```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": "IOSAI", "team_id": "" } }
```

## Workflows

MixerSystem provides five workflows built around fundamental actions. The core delivery sequence is **task → plan → output → update → lesson** 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 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).

### Output

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.

### Update

Creates or updates `doc.md` — project documentation. Like rules, docs are self-referential: there are docs for how to create docs.

### Lesson

Creates or updates `rule.md` — the rules that govern how builders work. Rules are self-referential: there are rules for how to create rules. The system governs itself using the same mechanisms it exposes to the user.


## `.mixer/` Configuration

Project-level instructions live in the `.mixer/` folder at the project root. Module-specific instructions live under `.mixer/modules/`, with one folder per module:

```
.mixer/
  modules/
    cli-a1b2c3/
      task.md       # how to create tasks for this module
      plan.md       # how to create plans for this module
      module.md     # how to build modules for this module
      rule.md       # how to create/update rules for this module
      doc.md        # how to create/update docs for this module
    generator-d4e5f6/
      ...
```

Each module in the codebase carries a `doc.md` with a UUID in its frontmatter — the stable identity anchor. The folder name in `.mixer/modules/` is `<name>-<uuid>`. Modules can be renamed or moved without breaking their configuration.

Workflows resolve context by combining project-level instructions with module-specific instructions matched by UUID.
