@ionivetech/mugiwara 0.5.4 → 0.6.0

package/docs/codex-setup.md

@@ -1,26 +0,0 @@
-# Codex Setup
-
-## Install
-
-```bash
-codex plugin marketplace add ionivetech/mugiwara
-codex plugin add mugiwara@mugiwara
-```
-
-Or via the CLI:
-
-```bash
-npx @ionivetech/mugiwara@latest --project ./my-app --target codex --yes
-```
-
-**Update** — `codex plugin update mugiwara`. **Uninstall** — `codex plugin remove mugiwara`.
-
-## What you get
-
-- 32 skills as markdown rules in `.codex/mugiwara/`.
-- An `AGENTS.md` bootstrap pointer (created if missing).
-
-## Notes
-
-Codex is a **project-only** target. Agents are skills-only here — the crew
-pipeline runs through the rule files.

package/docs/comparison.md

@@ -1,58 +0,0 @@
-# Positioning
-
-What mugiwara is and when to use something else.
-
-## What mugiwara is
-
-**Mugiwara is the governance layer for AI-assisted engineering work.** Every
-change carries a human-reviewable trail — which wave, what evidence, approved
-by whom — and the cost of the process scales to the size of the work.
-
-- **Lane sizing** — process scales from zero waves (typo) to nine (auth
-  migration), computed from the diff by `scripts/lane.sh`, not guessed.
-- **Evidence trail** — every wave boundary writes computed state to
-  `state.json`. No wave passes on a spoken claim. `scripts/evidence.sh` wraps
-  check commands and captures output.
-- **Resume from disk** — lose context mid-mission and the crew rebuilds from
-  `.mugiwara/` instead of restarting.
-- **15 named agents** in a 9-wave gated pipeline — each wave has a defined
-  owner, handoff, and verification gate.
-- **26 skills** with skip gates on all of them, progressive disclosure into
-  `references/`, and deterministic tooling for lane, evidence, and state.
-
-## What mugiwara refuses
-
-- **A runtime or daemon.** Orchestration stays in the harness. Pure markdown.
-- **Auto-merge or auto-deploy.** Human review at the PR is the terminal gate.
-- **Unattended marathon mode.** Mugiwara runs inline by default — you watch
-  every wave. Subagents only for parallel work.
-- **Skill-count growth.** 26 is the ceiling; a new skill replaces an old one.
-- **Head-to-head feature scorecards.** The compliance matrix replaces them.
-
-## When to use something else
-
-- **Deep autonomous marathon runs.** If you want an agent to disappear for
-  hours on subagent-driven builds with minimal visibility, superpowers'
-  `subagent-driven-development` is built for exactly that.
-- **Reference-encyclopedia depth.** agent-skills carries richer per-skill
-  engineering references (Hyrum's Law, test pyramid, Chesterton's Fence).
-- **A runtime service.** If you need API-driven, deployable agent crews, use a
-  framework (LangGraph, CrewAI).
-- **A single mega-prompt.** If you want one instruction with no ceremony,
-  mugiwara's pipeline is overkill for you.
-
-## Reproducible facts
-
-Generated from `content/` and `scripts/validate-content.ts`:
-
-| Metric | Value |
-|--------|:-----:|
-| Skills | 26 |
-| Agents | 15 |
-| Index (all descriptions) | ~10k chars (~2.5k tokens) |
-| Avg skill size | ~1.2k tokens |
-| Skills with skip gate | 26/26 |
-| References/ files | growing |
-| Evals | 11 cases |
-
-*Figures from Aug 2026. Recalculate with `bun scripts/validate-content.ts --check-manifest`.*

package/docs/compliance-matrix.md

@@ -1,81 +0,0 @@
-# Compliance Matrix
-
-For each model + harness + tier combination, how well mugiwara's rules hold.
-Published with failures — the first pack to admit where it breaks.
-
-## How to read
-
-- ✅ Rule holds ≥90% of the time
-- ⚠️ Rule holds 60-89% of the time — use guided mode, or expect model to miss it
-- ❌ Rule holds <60% of the time — not reliable, document the gap
-
-## Rules under test
-
-| # | Rule | Mechanism | Pillar |
-|---|------|-----------|--------|
-| R1 | Lane sizing | `scripts/lane.sh` | 2 |
-| R2 | Skip gates respected | Skill prose | 1 |
-| R3 | Evidence over claims | Chopper re-verification | 1 |
-| R4 | Wave boundaries (banner + report) | Workflow skill | 2 |
-| R5 | Heal loop bound (≤3 cycles) | Orchestration skill | 2 |
-| R6 | DoD verified (5 axes) | `references/definition-of-done.md` | 1 |
-| R7 | State written at wave boundary | `scripts/savepoint.sh` | 2 |
-| R8 | Source-backed code (no hallucinated APIs) | `references/source-grounding.md` | 4 |
-| R9 | Blocker ledger written on failure | Agent discipline | 1 |
-| R10 | Mission report at closure | `scripts/savepoint.sh` | 1 |
-
-## Results by model
-
-### Claude Sonnet 4 — opencode (Tier 1)
-
-| Rule | Verdict | Notes |
-|------|---------|-------|
-| R1 | ✅ | Lane computed by script |
-| R2 | ⚠️ | Occasionally skips on low-signal tasks |
-| R3 | ✅ | Chopper re-runs checks reliably |
-| R4 | ✅ | Banners + reports consistent |
-| R5 | ✅ | Heal loop bound respected |
-| R6 | ✅ | DoD axes checked |
-| R7 | ✅ | Savepoint script runs |
-| R8 | ⚠️ | Hallucinates APIs ~8% of the time without source-grounding |
-| R9 | ✅ | Ledger entries reliable |
-| R10 | ✅ | Closure report written |
-
-### Gemini — Gemini CLI (Tier 2)
-
-| Rule | Verdict | Notes |
-|------|---------|-------|
-| R1 | ✅ | Lane computed by script |
-| R2 | ⚠️~ | Skip gates respected ~65% |
-| R3 | ⚠️ | Evidence checks sometimes skipped |
-| R4 | ⚠️ | Wave banners inconsistent |
-| R5 | ⚠️ | Heal loop may exceed 3 cycles |
-| R6 | ⚠️ | DoD enforcement weaker |
-| R7 | ✅ | Savepoint script runs |
-| R8 | ❌ | Hallucinated APIs frequent without source-grounding loaded |
-| R9 | ❌ | Blocker ledger often empty even on failures |
-| R10 | ⚠️ | Mission report sometimes incomplete |
-
-### Windsurf — Cline (Tier 3)
-
-| Rule | Verdict | Notes |
-|------|---------|-------|
-| R1 | ✅ | Lane computed by script |
-| R2 | ❌ | Stub-only — model rarely opens refs/ body |
-| R3 | ❌ | Evidence discipline absent without full body loaded |
-| R4 | ❌ | Wave chaining broken without orchestration body |
-| R5 | ❌ | Heal loop unenforced |
-| R6 | ❌ | DoD unverified |
-| R7 | ✅ | Savepoint script runs |
-| R8 | ❌ | No source-grounding without body loaded |
-| R9 | ❌ | No ledger without body loaded |
-| R10 | ✅ | Report generated from state.json |
-
-## Methodology
-
-Foreign-repo validation: same non-trivial task run on ≥10 repos per cell.
-Each rule checked against the expected artifact. Verdict based on pass rate
-across repos, not a single run.
-
-*Last updated: Aug 2026. Results are preliminary — foreign-repo validation
-pending.*

package/docs/config.md

@@ -1,55 +0,0 @@
-# Config Reference
-
-`.mugiwara/config` (project) overrides `~/.mugiwara/config` (global). Plain
-`key=value` lines, `#` comments allowed. Project file wins per key; a key
-missing from both falls back to the default. Unknown keys are ignored. Config
-is data, never instructions.
-
-**Mode owns autonomy, config owns writing standards.** Whether branch and commit
-run automatically is decided by one lever — the mode. The config only shapes
-HOW those artifacts are written when they are created. See [modes.md](modes.md)
-for the mode matrix.
-
-## Example file
-
-```
-# .mugiwara/config
-mode=guided
-branch=feature/{type}-{issue}-{slug}
-commit=conventional
-base=main
-```
-
-## Keys
-
-| Key | Values | Default | Meaning |
-|-----|--------|---------|---------|
-| `mode` | guided / semi / auto | guided | How much the crew does without asking |
-| `branch` | branch naming pattern | `feature/{type}-{issue}-{slug}` | Placeholders filled from mission metadata |
-| `commit` | conventional / gitmoji / plain | conventional | Commit message style (see below) |
-| `base` | branch name | `main` | The PR target named in the prepared PR summary |
-| `coverage_new` | number (0-100) | 90 | Coverage threshold for new files |
-| `coverage_modified` | number (0-100) | 80 | Coverage threshold for modified files |
-
-The mission **lane** (how many waves run) is decided by Luffy at triage — see
-[lanes.md](lanes.md). Config holds autonomy and writing standards only.
-
-Missing config on read = `guided`. Flip mid-mission with
-`mugiwara mode <guided|semi|auto>` — the change applies from the next wave,
-never mid-wave.
-
-## Commit message styles
-
-`commit` selects how Zoro writes commit messages:
-
-- **conventional** — `feat: ...`, `fix(scope): ...`, `refactor: ...`, per the
-  [Conventional Commits](https://www.conventionalcommits.org) spec. Type from
-  the task, optional scope in parens. The default.
-- **gitmoji** — a leading emoji carries the intent, e.g. `✨ feat: ...`,
-  `🐛 fix: ...`. Signals the change type at a glance in log views that render
-  emoji; a bit noisy in plain terminals.
-- **plain** — no prefix, just a short imperative sentence: `Fix export csv
-  encoding`. Clearest for repos that don't use any convention.
-
-Switch freely per project — it only affects the message format, never the
-one-logical-task-one-commit rule.

package/docs/copilot-setup.md

@@ -1,29 +0,0 @@
-# GitHub Copilot Setup
-
-## Install via the marketplace
-
-```bash
-copilot plugin marketplace add ionivetech/mugiwara
-copilot plugin install mugiwara
-```
-
-## Install via CLI
-
-```bash
-npx @ionivetech/mugiwara@latest --project ./my-app --target copilot --yes
-```
-
-**Update** — `copilot plugin update mugiwara`. **Uninstall** — `copilot plugin uninstall mugiwara`.
-
-## What you get
-
-- 32 skills as `.instructions.md` files in `.github/` (project) or
-  `~/.copilot/` (global).
-- Agents as markdown files in `instructions/` / `agents/`.
-
-## Copilot caveat
-
-Copilot CLI reads the Claude marketplace for skills, but the agents are
-Claude-native `.md` files and do not auto-discover in Copilot. Skills install
-and function; for full agent support use the CLI install path, which writes
-Copilot-native `.instructions.md` skills and `.md` agents.

package/docs/cost.md

@@ -1,45 +0,0 @@
-# Token Cost Model
-
-Three-layer token architecture. Every layer has a cost and a purpose.
-
-## The three layers
-
-| Layer | Loaded | Purpose | Current size |
-|-------|--------|---------|:---:|
-| **Index** — all `description` frontmatter | Every session, every harness | Retrieval — which skill fires | ~2.9k tokens |
-| **Body** — SKILL.md content | When the skill triggers | Capability — how well it performs | ~1.2k avg / skill |
-| **References** — `references/*.md` | On demand, when the agent opens them | Depth — worked examples, checklists | ~0 (to build) |
-
-Only the **index** is a recurring cost. Body and references pay only when used.
-
-## Index budget
-
-- **Target:** 1.2k tokens (descriptions + agent pointers)
-- **Gate:** 5k chars hard CI cap — any skill/agent description that pushes the total over fails validation
-- **Current:** 2.9k tokens, loaded on every session
-
-Reduction path:
-1. Prune 32 → 26 skills: ~2.5k
-2. Descriptions → trigger-only (~150 chars): ~1.8k
-3. Agent descriptions → pointer lines: ~1.2k
-
-## Cost per lane
-
-| Lane | Waves | Estimated tokens | Typical budget |
-|------|-------|:---:|:---:|
-| 0 Direct | none | ~0 | — |
-| 1 Lean | execute → quality | ~4k | warn at 6k, stop at 12k |
-| 2 Standard | plan → execute → audit → review | ~10k | warn at 15k, stop at 30k |
-| 3 Full | all 9 waves | ~20k | warn at 30k, stop at 60k |
-| 4 Spike | brainstorm → re-triage | ~3k | warn at 5k, stop at 9k |
-
-Budget guidance: ~1.5× warns, 3× stops. Write state to `.mugiwara/state.json` before stopping.
-
-## Per-mission cost
-
-`state.json` carries `tokens_est` — the estimated tokens consumed by this mission. At closure, the mission report surfaces:
-- Total tokens for the mission
-- Lane it ran on
-- Cost delta vs. lane budget
-
-This turns lane sizing from "process efficiency" into a number an engineering manager can act on. No other skills pack produces this because no other pack sizes work.

package/docs/cursor-setup.md

@@ -1,25 +0,0 @@
-# Cursor Setup
-
-## Install
-
-```
-/add-plugin mugiwara
-```
-
-Or via the CLI:
-
-```bash
-npx @ionivetech/mugiwara@latest --project ./my-app --target cursor --yes
-```
-
-**Update** — re-run `/add-plugin mugiwara`. **Uninstall** — `/remove-plugin mugiwara`.
-
-## What you get
-
-- 32 skills as markdown rule files.
-- The `.cursor-plugin/plugin.json` manifest.
-
-## Notes
-
-Cursor is a **project-only** target. Agents are skills-only here — the crew
-pipeline runs through the rule files.

package/docs/developer-onboarding.md

@@ -1,89 +0,0 @@
-# Developer Onboarding
-
-Set up, validate, and contribute to the mugiwara repo.
-
-## Requirements
-
-| Dependency | Required for | Version |
-|------------|--------------|---------|
-| Node.js | running the CLI and the built artifact | >= 20.11 |
-| Bun | building from source, running tests | optional (preferred) |
-
-```bash
-bun install
-```
-
-## Repo layout
-
-```
-mugiwara/
-├── content/            # single source of truth: skills/ + agents/ markdown
-├── agents/             # symlink → content/agents (Claude Code plugin reads plugin root)
-├── skills/             # symlink → content/skills
-├── src/                # CLI, installer, targets, frontmatter parser
-├── scripts/            # validate-content, sync-version, run-evals, install scripts
-├── test/               # vitest suite
-├── .opencode/plugins/  # opencode plugin (registers crew at config load)
-├── .claude-plugin/     # Claude Code marketplace + sync.sh (symlink guard)
-└── docs/               # these docs
-```
-
-## The source of truth
-
-`content/` is the only physical source. The repo-root `agents/` and `skills/`
-are **symlinks** into it, so harnesses that read the plugin root (Claude Code
-marketplace) see the same files — there is no copy to drift. On a fresh clone
-where the symlinks are missing, recreate them:
-
-```bash
-sh .claude-plugin/sync.sh
-```
-
-Always edit `content/`. `bun run validate --check-sync` verifies the symlinks
-resolve to `content/` and never diverge.
-
-## Validation
-
-```bash
-bun run validate                # 26 skills + 14 agents: names, descriptions, skip gates, line limits
-bun run validate --check-sync   # symlinks resolve to content/, never diverge
-bun run typecheck               # tsc --noEmit
-bun run test                    # vitest
-bun run evals                   # eval suite valid (structure + coverage gates)
-bun run evals --run             # optional: execute cases against a model CLI (MUGIWARA_EVAL_CMD)
-```
-
-## Editing a skill or agent
-
-1. Edit `content/skills/<name>/SKILL.md` or `content/agents/<name>.md`.
-2. Respect the house style (see [skill-anatomy.md](skill-anatomy.md) and
-   [agent-anatomy.md](agent-anatomy.md)): evidence over claims, exact commands,
-   red flags, ≤120-line skill bodies.
-3. `bun run validate && bun run typecheck && bun run test`
-
-## Adding a new skill or agent
-
-1. Create the content file following the anatomy docs.
-2. If it's an agent, list its held skills in frontmatter; give it a
-   `description` ≥20 chars.
-3. If it's a skill, pick a folder name that matches `name`; description 20–500
-   chars; body ≤120 lines; include a `## Skip when` block (1–4 bullets, numeric
-   thresholds) so the skill knows when it does not apply.
-4. Update the crew/technique tables in `README.md` and the docs (`agents.md`,
-   `skills.md`).
-5. Sync + validate + test.
-
-## Building and publishing
-
-```bash
-bun run build          # dist/mugiwara.js
-bun run sync-version   # sync version from package.json into manifests
-bun prepack            # build + sync-version
-```
-
-Version numbers in the manifests sync from `package.json` via `sync-version`
-(runs automatically on publish).
-
-## Contributing
-
-Open an issue or pull request on GitHub: <https://github.com/ionivetech/mugiwara>.

package/docs/enforcement.md

@@ -1,35 +0,0 @@
-# Enforcement
-
-A markdown harness cannot force a model to comply with prose — that is the
-ceiling of every skills pack, mugiwara included. What keeps the pipeline honest
-is a mix of mechanism and discipline.
-
-## Mechanisms (computed, no model)
-
-| Rule | Mechanism |
-|------|-----------|
-| Lane sizing | `scripts/lane.sh` computes lane from `git diff --name-only` |
-| State persistence | `scripts/savepoint.sh` writes `state.json` at every wave boundary |
-| Evidence capture | `scripts/evidence.sh <label> -- <cmd>` writes stdout/stderr to `.mugiwara/results/<hash>.log` |
-| Index budget | validator enforces 12k char ceiling on skill + agent descriptions |
-| Manifest sync | validator asserts manifest set-equals `content/`; CI blocks drift |
-| Skill format | validator checks name, description length, body ≤120 lines, skip gate, duplicate names |
-
-## Discipline (prose the model follows)
-
-| Rule | Enforced by |
-|------|------------|
-| Skip gates | Every skill declares `## Skip when` (1-4 bullets, numeric threshold). Validator fails build without it. |
-| Evidence over claims | Iron law in every skill: no wave passes on assertion. Checked by Chopper's re-verification. |
-| Wave boundaries | Every wave opens with `## Wave N — <crew>` banner, closes with checkpoint report. |
-| Heal loop bound | Max 3 cycles (Wave 8 → Wave 4). After 3, escalate to human. |
-| DoD canonical | `references/definition-of-done.md` — one bar, linked from checkpoint + gates. |
-
-## Honest limits
-
-Mugiwara cannot force an agent to follow a skill on any tier. Models can skip
-a skill, rush a wave, or pass on a claim. Mechanisms (savepoint, lane, evidence)
-leave a trace regardless of model cooperation. Discipline rules rely on the
-model reading and choosing to follow them.
-
-That is true on every tier and every harness. Mugiwara is a skills pack, not a supervisor.

package/docs/execution-model.md

@@ -1,92 +0,0 @@
-# Execution Model
-
-Why the crew runs in your main conversation — and when subagents are actually
-used.
-
-## Auto-activation
-
-The workflow **auto-activates.** At session start the crew is announced; when
-you give a non-trivial request, the pipeline runs by itself — you do not need
-to call `/using-mugiwara`. It remains an optional explicit router if you want
-to hand-route a mission.
-
-## Inline by default
-
-The crew runs **inline**. The main thread embodies each crew role using that
-member's skill, so every wave plays out in your main conversation and you watch
-it happen:
-
-- Luffy's triage, Nami's planning, Zoro's execution, Chopper's audit, Sanji's
-  quality, Franky's gates, Robin/Jinbe's review, Brook's healing, Luffy's
-  closure — all performed in the main thread.
-- Evidence is written to `.mugiwara/` files; the conversation carries terse
-  verdicts and evidence pointers.
-
-## When subagents ARE used
-
-Subagents exist to parallelize, never to hide work:
-
-1. **`[PARALLEL]` task batches** — independent tasks that touch no shared files
-   or interfaces run concurrently, one per worker subagent. This is the only
-   place Zoro delegates.
-2. **Parallel fixes** — Brook spawns workers for independent heal fixes.
-3. **Background / long-running checks** — work that would stall the
-   conversation.
-4. **Check subagents** — Chopper, Robin, and Jinbe may spawn subagents for
-   independent re-runs or diff passes.
-
-Worker results return as reports; the main thread summarizes them inline with
-evidence pointers.
-
-## Why not dispatch every wave to a subagent?
-
-Every harness — Claude Code, opencode, Codex, Cursor, Gemini — hides subagent
-internals behind a click or a side panel. If each wave ran as a subagent, you'd
-be clicking through the whole mission to see what happened. Running the crew in
-the main conversation is the only way the process is genuinely visible.
-
-There's also a context cost to deep nesting: crew-inside-crew subagents bloat
-context and hide decisions. Inline keeps the user in the loop and the story
-linear.
-
-## Rules that keep it sane
-
-- Crew members never dispatch another crew member. A role that must split work
-  returns the split to the main thread, which spawns the workers.
-- Escalation = "blocked" + ledger row returned to the main thread.
-- Sequential work never takes a subagent round-trip — no skipping, no hidden
-  reordering, plan order is plan order.
-
-## Checkpoint reports
-
-You see progress as **checkpoint reports**, not a firehose: a wave banner
-(`## Wave N — <crew> (<skill>)`), one compact report per crew member at each
-stage boundary (what ran / result / evidence pointer), a progress summary per
-wave, and a pause when something fails or gets risky. Subagents are used only
-where they genuinely help: independent `[PARALLEL]` task batches, Brook's
-reviewer/security re-verification workers, and background checks.
-
-## Manual stages
-
-Prefer to drive the stages yourself? Every stage has a slash command that loads
-the skill, runs the crew role inline, and bridges state from `.mugiwara/`:
-
-| Command | Runs | Reads state from |
-|---------|------|------------------|
-| `/mugiwara-plan` | Nami | `.mugiwara/spec/` |
-| `/mugiwara-execute` | Zoro | `.mugiwara/plans/` |
-| `/mugiwara-review` | Robin | `.mugiwara/results/` + diff |
-| `/mugiwara-security` | Jinbe | `.mugiwara/results/` + diff |
-| `/mugiwara-heal` | Brook | `.mugiwara/issues/` |
-| `/mugiwara-ship` | Luffy | plan + results |
-
-You can jump into any stage — e.g. run `/mugiwara-plan` first, then
-`/mugiwara-execute` later when you're ready.
-
-## Trade-off
-
-Inline execution grows the main-thread context over a long mission. The crew
-mitigates this: evidence goes to `.mugiwara/` files, reports are terse, and
-subagents isolate the genuinely heavy parallel work. For missions that must
-minimize main-context growth, the crew supports dispatching specific waves to a
-subagent — at the cost of visibility.

package/docs/gemini-setup.md

@@ -1,27 +0,0 @@
-# Gemini CLI Setup
-
-## Install
-
-```bash
-gemini extensions install https://github.com/ionivetech/mugiwara
-```
-
-Or via the CLI:
-
-```bash
-npx @ionivetech/mugiwara@latest --project ./my-app --target gemini --yes
-```
-
-**Update** — `gemini extensions update mugiwara`.
-**Uninstall** — `gemini extensions remove mugiwara`.
-
-## What you get
-
-- 32 skills as markdown rules in `.gemini/mugiwara/`.
-- A `GEMINI.md` bootstrap pointer (created if missing).
-
-## Notes
-
-Gemini is a **project-only** target — skipped (with a note) on `--global`
-installs. Agents are skills-only here (no native subagent registry); the crew
-pipeline runs through the rule files.