---
name: mixersystem
---
# MixerSystem (General)

This is the top-level product overview for MixerSystem.

MixerSystem is a workflow engine for AI-assisted delivery with one standard flow:

1. `task` -> establish `task.md`
2. `plan` -> produce `plan.md`
3. `work` -> implement/test and maintain `work.md`
4. `update` -> analyze changes and suggest `update.md`
5. `upgrade` -> mine agent logs for generalizable rules and suggest `upgrade.md`

## Core Principles

- Work is anchored to a single `work_folder`.
- Each stage writes a primary artifact (`task.md`, `plan.md`, `work.md`, `update.md`, `upgrade.md`).
- `doc.md` files are the project knowledge source.

## Work Folder — The Unit of Work

Everything happens inside a single work folder. One work folder = one task = one focused unit of work. The work folder is the anchor for:

- All artifacts produced during a run (`task.md`, `plan.md`, `work.md`, etc.)
- All logs generated during execution (`agent_logs/`)
- All intermediate outputs (branch drafts, revision history)

## Knowledge Model

Projects place `doc.md` files (with `name` frontmatter) in modules. The sync step scans for these files and generates `.mixer/settings.json` for context resolution.

Context is module-targeted:

- `modules: all` -> broad project context
- specific modules -> local + inherited context

Context resolution uses dedicated methods on the runtime context:

- `resolve_artifacts()` -> existing `.md` files in the work folder
- `resolve_docs()` -> project doc.md files
- `resolve_rules(action)` -> action-specific rules files

Rules live centrally in `.mixer/modules/<name>/` with one file per action type (task.md, plan.md, work.md, update.md, upgrade.md).

## Persistent Runtime Context

Three kinds of persistent information accumulate during execution:

**1. Agent Logs** — The prompts sent to and responses received from each builder and sub-agent, logged into `agent_logs/` in the work folder (`trace.md`, `trace.log`, `raw.log`).

**2. Primary Conversation** — The conversation with the primary coordinating agent, captured via Claude Code hooks into `logs/conversation.log` in the active work folder during workflow execution.

**3. Git** — The state of the codebase — diffs, commit history, working tree status.

## Runtime Model

Runtime is package-based (no workflow/data code copy into projects).

- CLI: `python3 -m mixersystem ...`
- `sync` generates `.mixer/settings.json`, `.claude/skills/mixer/SKILL.md`, and Claude Code hooks in `.claude/settings.json`
- `init` currently runs `sync` and prints an initialization confirmation

## Framework Fixture Projects

For framework regression testing, use fixture projects under:

- `projects/project-a`

Copy a fixture to a temporary run directory before executing workflows.
