Millworks

A transparent, persona-driven workflow harness for AI coding agents. Millworks runs on two surfaces over one shared core — natively on pi.dev, and as a Claude Code plugin — so the same workflows, personas, and visible subagents work in either agent.

Millworks treats software work — bug fixing, refactoring, investigation, greenfield builds, audits, reviews — as shaped work running through pluggable workflows with competing personas and full human visibility into every subagent.

What Millworks is opinionated about

• No black-box subagents. Every dispatched agent runs in a real tmux pane the user can attach to, watch, steer, or close. Visibility is the premise, not an afterthought — on both surfaces (pi.dev spawns pi, Claude Code spawns claude, both into visible panes).
• Workflow-shape follows work-shape. Bug fixes, refactors, audits, and greenfield builds use different workflow templates from a shared library. The harness doesn't impose one shape.
• Database-source-of-truth for project state. Project tasks, dependencies, decisions, and — uniquely — workflow run state live in beads (Dolt-backed graph store). A run is reconstructed from beads and survives a restart: kill the host mid-run, relaunch, and it recovers the active run, reconciles step state against live panes, and resumes. Markdown views are derived, not hand-edited.
• Thin glue, heavy Rust CLIs. The surface adapters (pi.dev extensions, the Claude MCP server) are wrappers over CLI tools — tmux, bd, and our own Rust binaries. Real logic lives in independently testable command-line programs, so both surfaces share it byte-for-byte.
• Competing personas. Multiple agent files can claim the same role (debugger-systematic.md, debugger-bisect-first.md); the harness picks based on routing metadata and (eventually) historical performance.

Status

Phase 14 (the Claude Code surface) is complete. Millworks now ships on both surfaces at parity: beads is the canonical, restart-recoverable run store on each, and the persisted run-state schema is unified — a run started on either surface is recoverable by the other.

7 workflow templates, 20 personas, a shared Rust core (4 focused CLIs + the millworks unified CLI), 3 pi.dev extensions, and the Claude Code plugin (13 /millworks:* commands + a bundled MCP server). Dogfooded: the greenfield-compile workflow ran on a real project (lmcq — a Rust telemetry processing system).

Quick Start

Install once (builds the shared Rust core), then pick your surface.

pi.dev

# 1. Install (pi.dev surface)
curl -fsSL https://raw.githubusercontent.com/Liquescent-Development/millworks/main/install.sh | bash

# 2. Initialize a project
cd your-project
millworks init

# 3. Start coding with pi
pi

Inside pi:

• /workflow-list — browse available workflow templates
• /workflow-run bug-fix "login form returns 500" — run a workflow
• /prime — full beads project view

Claude Code

# 1. Install with the Claude Code plugin (adds --claude)
curl -fsSL https://raw.githubusercontent.com/Liquescent-Development/millworks/main/install.sh | bash -s -- --claude

The installer assembles the plugin and prints the one-time registration commands. In a Claude Code session (started inside tmux, so subagents are visible):

/plugin marketplace add ~/.local/share/millworks
/plugin install millworks@millworks

Then, in a project:

• /millworks:init — initialize the project for Millworks (beads + run-tracking types)
• /millworks:workflows — list the available workflows
• /millworks:run-workflow bug-fix "login form returns 500" — run one by name
• Or just describe the work ("fix this bug", "audit the dependencies") — a skill recommends the matching workflow and asks before running it

Gates surface as a native Approve / Reject / Skip menu (with /millworks:gate-* commands as a typed fallback).

Prerequisites

git, cargo (Rust toolchain), node + npm, tmux, and bd (beads) for both surfaces; plus pi for the pi.dev surface or claude (the Claude Code CLI) for the Claude surface. The installer checks for these and prints install instructions if any are missing.

Full install docs — including the manual path, the Claude registration details, and refreshing after a rebuild — are in docs/INSTALLING.md.

Repo layout

millworks/
├── README.md
├── LICENSE                  # AGPL-3.0
├── install.sh               # one-command installer (curl | bash; --claude for the plugin)
├── docs/                    # ADRs, design docs, INSTALLING.md
├── tools/                   # Rust CLI binaries (cargo workspace) — the shared core
│   ├── millworks/           # unified CLI (init, doctor, setup, dev-link, build-claude)
│   ├── workflow-parser/     # validates .workflow.md files
│   ├── workflow-scheduler/  # DAG resolver for workflow steps
│   ├── persona-picker/      # role → persona selection
│   └── context-pack-assembler/  # 80%-budget context bundles
├── content/                 # shared markdown content (used by both surfaces)
│   ├── agents/              # personas (incl. competing variants per role)
│   ├── workflows/           # workflow templates per work-shape
│   └── skills/              # skills
├── extensions/              # pi.dev surface — TypeScript extensions (npm workspace)
│   ├── tmux-subagent/
│   ├── workflow-runner/     # parses, schedules, dispatches, tracks runs in beads
│   └── beads-bridge/
├── surfaces/claude/         # Claude Code surface — the plugin
│   ├── .claude-plugin/      # plugin manifest
│   ├── mcp-server/          # the engine (TypeScript → single esbuild bundle)
│   ├── commands/            # /millworks:* slash commands
│   ├── agents/ personas/    # personas (generated + routing source)
│   └── skills/ workflows/ bin/  # symlinked from content/ + the built CLIs
└── recipes/                 # install + integration helpers

The two surfaces coordinate only through this repo (tools/, content/, the ADRs, and beads) — surfaces/claude/ never reimplements logic that lives in the shared Rust core.

License

GNU Affero General Public License v3.0.