@mu-crew/mu 3.2.1 → 3.4.0

package/AGENTS.md

@@ -169,7 +169,7 @@ is one atomic call. Keep the tmux workaround out of herdr.
 
 ## Orchestrating on this repo
 
-Follow the loop in [skills/mu/SKILL.md](skills/mu/SKILL.md). Repo specifics:
+Follow [skills/mu/recipes/orchestrator-loop.md](skills/mu/recipes/orchestrator-loop.md). Repo specifics:
 
 - Each workspace runs `npm install` into its own `node_modules`. Never
   symlink main's.
@@ -188,15 +188,20 @@ Follow the loop in [skills/mu/SKILL.md](skills/mu/SKILL.md). Repo specifics:
 ## Skill files are context, not documentation
 
 `skills/mu/SKILL.md` loads into every orchestrator's context, and
-`skills/mu/REMOTE_WORKERS.md` on demand. Every word competes with the
-user's work. Read the `writing-for-agents` skill before you edit
-either one.
+the recipes in `skills/mu/recipes/` on demand. Every word competes with the
+user's work. The recipes are written for an agent with no context;
+[recipes/brief.md](skills/mu/recipes/brief.md) holds the rules, and
+they apply to the skill files too.
 
 - Leave verb lists, flags, and option tables to `--help`. The skill
   carries only what `--help` cannot: the gotcha, the reason, the trap.
 - Say each thing once, next to where it applies.
 - SKILL.md holds the trigger and the rule. Detail that only some
-  branches need goes in REMOTE_WORKERS.md.
+  branches need goes in a recipe under `skills/mu/recipes/`, with a
+  row in SKILL.md's recipe index. Recipes reference only mu, never
+  skills outside this repo.
+- `docs/guide/` pages stay terse for humans and link to the recipe
+  instead of restating it.
 - Delete sentences the model obeys by default. State the target
   behaviour.
 

package/README.md

@@ -20,9 +20,9 @@ in-progress, and blocked tasks, the log tail, workspaces, and doctor.*
   socket inside each agent, so send, state, wait, and abort are exact,
   locally and over ssh. The pane stays pi's normal TUI.
 
-mu persists state and coordinates handoffs. It does not choose models,
-run your tests, or pass messages between agents. Every read path has
-`--json`, and every change goes through a typed CLI verb.
+mu persists state and coordinates handoffs. Every read path has
+`--json`, and every change goes through a typed CLI verb. See
+[What mu is not](#what-mu-is-not).
 
 ## Install
 
@@ -71,23 +71,83 @@ For one helper, ask pi to delegate (`mu_delegate` ships with `mu link
 pi`), or spawn into the reserved `scratch` workstream:
 `mu agent spawn scout-1 -w scratch`.
 
-## mu delegates vs hidden subagents
-
-Claude Code, Codex, and pi-subagents delegate to a hidden child process
-and return only its result. A mu delegate is an ordinary agent in a
-pane.
-
-|                         | Hidden subagent          | mu delegate |
-| ----------------------- | ------------------------ | ----------- |
-| Visibility              | none while it runs       | a pane; attach and watch |
-| Steer mid-run           | no                       | `mu agent send`; stop with `mu agent abort` |
-| Keep talking after it answers | no                 | yes, with `keep: true` |
-| Transcript              | collapses into a result  | a normal pi session log |
-| If the work grows       | re-brief a new agent     | same task DAG and workspaces |
-| Cost                    | light                    | one pane and one pi process |
-
-For many tiny calls, a hidden subagent is lighter. mu bets that seeing
-and steering agent work is worth a pane.
+## Ultrathink, the mu way
+
+Long agent runs fail in two ways: the agent stops at 35 of 50 items and
+calls it done, and it grades its own work generously. The fix is to
+take the plan out of the agent's head, fan the work out to fresh
+agents, and have other agents try to refute each result before it
+counts. Claude Code's ultracode does this with a hidden script. mu does
+it in the open:
+
+- **The plan is the DAG.** Every unit, review gate, finding and round
+  is a task before an agent spawns. `mu state` shows 35 of 50 done, so
+  nobody can declare victory early.
+- **Findings are tasks.** A reviewer records each problem as a task in
+  triage ([findings](skills/mu/recipes/findings.md)), and it blocks the
+  review until someone accepts it as work or closes it rejected or
+  duplicate. The graph holds the whole review.
+- **Checks are calls.** Refuters, claim checkers and judges are
+  [delegate calls](skills/mu/recipes/tasks-or-calls.md): fresh agents,
+  ideally on another model, whose verdicts land on the task they
+  judged. A 50-unit run adds about 50 units, 50 review gates and the
+  findings that survive, not a task per check.
+- **Every agent is a pane.** Attach to any worker, reviewer, or judge
+  mid-run and steer it.
+- **Nothing lives only in a context window.** Verdicts, evidence, and
+  stop rules are task notes. The run survives compaction, crashes, and
+  a new orchestrator.
+
+Not every review needs a record. Reviewing someone's PR or a doc runs
+as delegates only: findings come back in their answers, and nothing
+lands in the ops log.
+
+Ask your orchestrator to *ultrathink* a job, and it follows
+[skills/mu/recipes/ultrathink.md](skills/mu/recipes/ultrathink.md).
+That recipe composes smaller ones you can also use on their own:
+
+| Recipe | Shape |
+| ------ | ----- |
+| [fan-out](skills/mu/recipes/fan-out.md) | one task per unit, merged as each closes |
+| [adversarial-review](skills/mu/recipes/adversarial-review.md) | a review gate per unit: a fresh agent tries to reject it before it ships |
+| [refute](skills/mu/recipes/refute.md) | finders record findings, one refuter call per finding, report from the graph |
+| [hypothesis-panel](skills/mu/recipes/hypothesis-panel.md) | independent theories from separate evidence, each attacked |
+| [tournament](skills/mu/recipes/tournament.md) | competing attempts, judged in pairs |
+| [loop-until-done](skills/mu/recipes/loop-until-done.md) | rounds until a stop rule written up front holds |
+| [backlog-triage](skills/mu/recipes/backlog-triage.md) | quarantined readers classify, a trusted actor acts |
+| [deep-research](skills/mu/recipes/deep-research.md) | searchers by angle, one checker per claim, a cited report |
+| [review-panel](skills/mu/recipes/review-panel.md) | one reviewer per angle on a diff; delegates by default, tasks when fixes follow |
+| [rules-audit](skills/mu/recipes/rules-audit.md) | one checker per AGENTS.md rule plus a skeptic; or mine repeated corrections into new rules |
+
+In pi, `mu link pi` adds them as commands: `/ultrathink <job>`,
+`/mu-research <question>`, `/mu-review [target]`, `/mu-refute <scope>`,
+`/mu-tournament <task>`, `/mu-rules-audit [check <target> | mine]`,
+`/mu-debug <symptom>`, `/mu-sweep <change>`, and `/mu-until <stop rule>`.
+
+All recipes, including the orchestrator loop and remote workers, are
+in [skills/mu/recipes/](skills/mu/recipes/).
+
+## What mu is not
+
+- **Not a hidden subagent.** Every agent, including a one-off
+  `mu_delegate` helper, is an ordinary agent in a pane: attach, steer,
+  abort, or keep talking to it. That costs a pane and a pi process per
+  agent; for many tiny calls a hidden subagent is lighter. See
+  [the comparison](docs/guide/delegate.md#delegates-vs-hidden-subagents).
+- **Not a workflow engine.** No DSL, no hidden plan, no script runner.
+  The plan is the task DAG; recipes are instructions an agent follows,
+  and every step is a CLI verb.
+- **Not a model router.** mu does not pick models, thinking levels, or
+  tools. Pass them in the spawn command (`--cli pi_big`).
+- **Not a chat bus.** Agents coordinate through task notes, claims, and
+  the ops log, not messages to each other.
+- **Not a daemon or a service.** No background process, config file, web
+  UI, or RPC. State is one SQLite file; sync rides on ordinary commands.
+- **Not a test runner or a judge.** `--evidence` records what an agent
+  observed; checking it is the orchestrator's job, and the recipes say how.
+
+The full list, with reasons: [VISION § What it is not](docs/VISION.md#what-it-is-not)
+and [ROADMAP § Anti-feature pledges](docs/ROADMAP.md#anti-feature-pledges).
 
 ## Documentation
 
@@ -96,8 +156,9 @@ and steering agent work is worth a pane.
 - [User guide](docs/guide/README.md): how-tos for dispatch, remote
   workers, sync, recovery, and the dashboard.
 - [skills/mu/SKILL.md](skills/mu/SKILL.md): what an orchestrating
-  agent reads. [REMOTE_WORKERS.md](skills/mu/REMOTE_WORKERS.md) covers
-  agents on other machines.
+  agent reads. [skills/mu/recipes/](skills/mu/recipes/) holds the
+  recipes it points to, such as
+  [remote workers](skills/mu/recipes/remote-workers.md).
 - [ARCHITECTURE.md](docs/ARCHITECTURE.md) and
   [docs/architecture/](docs/architecture/): the module map and deep
   dives.