# muda

> muda (無駄, Japanese for "waste") finds delivery waste in GitHub Actions
> pipelines, and a coding agent fixes it. It is one Go binary that reads the
> pipeline from GitHub, plus five agent skills (muda, muda-measure,
> muda-diagnose, muda-fix, muda-verify) that walk the agent through measure,
> diagnose, fix and verify, stopping at a checkpoint for a human at each step.
> Every claim cites a run, a job, a step, a log line or a file. A fix never
> weakens a merge or deploy gate. muda never changes repository
> settings, and merges only when you say so.
>
> License: MIT.

## Docs

- [muda.tools](https://muda.tools/): landing page: the problem, the loop in four lines, the install command, and the demo video.
- [muda.tools/loop/](https://muda.tools/loop/): measure, diagnose, fix and verify in full, with each checkpoint and what lands in `.muda/`.
- [muda.tools/waste/](https://muda.tools/waste/): the ten waste classes, the eleven recipes and which classes each one fixes, and how to read them from the binary.
- [muda.tools/proof/](https://muda.tools/proof/): measured vs suspected, missing data, the four gate results, exemptions, and what muda never does.
- [muda.tools/docs/](https://muda.tools/docs/): requirements, setup, the command list and what muda writes.
- [github.com/subaud-tools/muda](https://github.com/subaud-tools/muda): source repository.
- [docs/validation](https://github.com/subaud-tools/muda/tree/main/docs/validation): validation receipts.
- [install.sh](https://muda.tools/install.sh): shell installer for the prebuilt binary (`curl -fsSL https://muda.tools/install.sh | sh`).

## The loop

- measure: `muda measure` reports where the delivery time goes over a window
  (per workflow: run count, p50 and p90 duration, queue time, success rate,
  re-runs, per-job and per-step durations, critical path; the top time sinks).
  `muda gates` inventories the candidate merge and deploy gates. The human
  confirms workflow roles, stacks, window and gates; that is recorded as the
  baseline in `.muda/`.
- diagnose: the agent works through the time sinks and the signals from
  `muda scan` and `muda notices`, reads every matching recipe and runs its
  Detect steps against real logs. Each finding has a waste class, a location,
  cited evidence, a basis (measured or suspected), an estimate and a risk. The
  human approves which to fix and in what order.
- fix: one finding, one branch, one pull request. The agent presents the plan
  (files, expected effect, risk, gates touched), the human approves it, the
  agent opens the PR, and the human merges.
- verify: `muda compare` checks the change on the PR's real pipeline and again
  after merge: before and after timings with the runs cited, plus fail-closed
  gate proof. The receipt is recorded in `.muda/`.

## Proof rules

- A finding is measured when cited runs, log lines or files show the waste;
  otherwise it is suspected and names the evidence that would settle it.
- A suspected finding is approved only as an experiment with pass criteria,
  and never feeds a claimed saving.
- Missing data is unavailable, with a reason; never zero builds, zero warnings
  or no gates.
- `muda compare --gates` reports VERIFIED, EXEMPTED, WEAKENED or UNVERIFIED.
  A finding is never marked fixed on WEAKENED or UNVERIFIED.
- Kept waste is an exemption with waste, location, reason, agreed-by, date and
  review-by. An expired exemption is raised again.

## Waste classes

- W1 No-op not a no-op: an unchanged deploy updates stacks or builds images.
- W2 Unpinned toolchain: floating versions let the same tree produce different
  outputs.
- W3 Emulated builds: images build under CPU emulation instead of natively.
- W4 Uncached work: unchanged installs or layers are recomputed.
- W5 Serial where it could be parallel: independent work runs serially, or
  expensive computation is duplicated.
- W6 Re-verification: proven equivalent checks run more than once on the same
  tested tree.
- W7 Chain stalls: automated hand-offs fail or stall with no visible outcome.
- W8 Silent runner-plane failure: jobs queue because the runner plane cannot
  accept work, without alerting.
- W9 Rebuilt artifact: identical inputs are built again across stages.
- W10 Ignored advance notice: CI warnings about platform or toolchain changes
  go unread.

Recipes R1 to R11 give the fixes, for the stacks github-actions, cdk, docker,
python, node and go. `muda recipes` lists them; `muda recipe <ID> --stack <S>`
reads one; `muda standard [W-number]` reads the standard.

## Results

- One adopter's production CDK pipeline: deploy 27 min to 6 min; merge to prod
  about 64 min to about 18 min.
- Blind replay of a known 30-day window, read-only: a fresh agent with only the
  skills found all five target wastes with cited evidence and no false
  positives (the first run found four of five; the skills and recipes were
  fixed and the rerun passed).
- Full loop on two unseen Go repositories: a cache that never warms, fixed in
  one or two lines. One CI step about 110 s to about 22 s on a same-commit
  re-run; the other repository's total CI about 289 s to about 104 s. Gate
  inventory unchanged in both.
- A public Python project, read-only: about 230 test runs over 30 days; every
  finding reviewed and agreed real; no false positives.

## Commands

- `measure`: where the delivery time goes, with evidence.
- `gates`: candidate delivery gates and security settings.
- `scan`: static workflow signals (floating-ref, floating-runner,
  floating-toolchain, emulation, uncached-install, serial-independent-jobs,
  duplicate-check-set, no-concurrency, no-path-filter, toolchain-drift).
- `notices`: advance notices grouped with source evidence.
- `logs <run-id>`: final-attempt jobs, or a job's log filtered by `--step` or
  `--grep`.
- `compare`: before/after timings and fail-closed gate proof.
- `recipes`, `recipe ID`: list or read the fix recipes.
- `standard [W-number]`: read the delivery-waste standard.
- `record`: the reviewed local record under `.muda/` (init, baseline,
  finding add/set, exempt, gates set, receipt, show, check).
- `skills install [--agent claude|pi|codex] [--scope user|project]`: install
  the bundled skills.
- `update`, `version`, `commands [--json]`, `help <command>`, `man`.

Most commands take `--repo OWNER/NAME`, `--since`, `--until` and
`--format json|md`. GitHub is read with GH_TOKEN, then GITHUB_TOKEN, then the
gh login.

## Install

- `curl -fsSL https://muda.tools/install.sh | sh` downloads muda for your
  platform and verifies its checksum. `muda update` self-updates.
- `muda skills install --agent claude --scope user` installs the five skills.
  Agents are claude, pi or codex; scopes are user (default) or project.
- Then, in a GitHub repository, ask the agent to start with muda.

## The family

- https://galley.tools: document review for agent-driven development
- https://muster.tools: local multi-agent coordination bus
- https://channels.tools: reach a running pi session through its channels
- https://hail.tools: reach a running pi session from your phone (coming soon)
- https://kempt.tools: declarative machine setup you can read before you run
- https://tackle.tools: small command-line tools for your terminal
- https://casebook.tools: a decision for every repo, PR, issue, branch and worktree
- https://subaud.tools: the family landing page