Metadata-Version: 2.4
Name: mixer-system
Version: 0.1.11
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, 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

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

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

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