@ionivetech/mugiwara 0.1.3 → 0.3.0

package/docs/comparison.md

@@ -0,0 +1,63 @@
+# Comparison
+
+How mugiwara fits against the alternatives.
+
+## Mugiwara vs. plain skills (agent-skills / skills.sh)
+
+The [agent-skills](https://github.com/addyosmani/agent-skills) ecosystem ships
+standalone skills that an agent picks up on demand. Mugiwara ships the same
+portable `SKILL.md` format — and also ships:
+
+- **A named crew** — personas (Luffy, Nami, Zoro, …) on top of the skills, so
+  the pipeline has a defined owner per wave instead of "whichever skill fires."
+- **A pipeline, not a pile** — ordered waves (triage → plan → execute →
+  checkpoint → quality → gates → review → heal → closure) with gates between.
+- **Evidence discipline** — no wave passes on a claim; the owning role runs the
+  checks and shows output.
+- **A workspace contract** — `.mugiwara/` holds plan, results, ledger, and
+  logs, so a mission survives context loss.
+
+You can still install just the skills (`npx skills add ionivetech/mugiwara`).
+
+## Mugiwara vs. agent frameworks (LangGraph, CrewAI, …)
+
+Framework crews are code: graphs, nodes, runtimes to host. Mugiwara is:
+
+- **Zero runtime** — pure markdown; your existing agent's own subagent
+  machinery does the work. Nothing to deploy, nothing to keep updated.
+- **Harness-native** — installs into Claude Code, opencode, Copilot, Gemini,
+  Codex, Cursor, and 70+ tools rather than forcing one runtime.
+- **Inline** — the pipeline runs in your main conversation (see
+  [execution-model.md](execution-model.md)); frameworks hide the work behind
+  their own execution graph.
+
+## Mugiwara vs. a single mega-prompt
+
+A mega-prompt gives you one big instruction. Mugiwara:
+
+- **Splits by specialization** — 25 focused skills + 15 personas instead of one
+  document that tries to be everything, so each phase has a tight contract.
+- **Is gated** — every wave has a verifiable gate and a recorded reason, so
+  drift is caught early.
+- **Heals** — a bounded 3-cycle heal loop reads the failure ledger and fixes
+  root causes, instead of re-running the same mega-prompt.
+
+## When NOT to use mugiwara
+
+- **One-line fixes** — Luffy routes trivia straight to execution; you don't
+  need the crew for a typo.
+- **You want a framework runtime** — if you need orchestration in code,
+  deployable graphs, or API-driven crews, a framework is the right tool.
+- **You want the crew to merge/deploy** — mugiwara deliberately stops at push +
+  PR. Human review is the terminal gate.
+
+## Summary
+
+| | Mugiwara | Plain skills | Framework crews | Mega-prompt |
+|---|----------|--------------|-----------------|-------------|
+| Runtime | none | none | yes | none |
+| Pipeline | ordered waves + gates | on-demand | graph | linear |
+| Visibility | inline in your chat | inline | behind the graph | inline |
+| Evidence gates | yes | no | configurable | no |
+| Self-healing | yes (3-cycle loop) | no | configurable | no |
+| Harnesses | 12+ | 70+ | one per framework | any |

package/docs/config.md

@@ -0,0 +1,50 @@
+# 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 | The only autonomy lever — decides whether branch/commit run automatically |
+| `branch` | branch naming pattern | `feature/{type}-{issue}-{slug}` | Placeholders filled from mission metadata, validated to `[a-zA-Z0-9-_]` |
+| `commit` | conventional / gitmoji / plain | conventional | Commit message style (see below) |
+| `base` | branch name | `main` | The PR target named in the prepared PR summary |
+
+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

@@ -0,0 +1,29 @@
+# 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/cursor-setup.md

@@ -0,0 +1,25 @@
+# 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

@@ -0,0 +1,85 @@
+# 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/             # synced copy of content/agents (plugin copies at repo root)
+├── skills/             # synced copy of 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
+└── docs/               # these docs
+```
+
+## The source of truth
+
+`content/` is canonical. The repo-root `agents/` and `skills/` copies are
+generated for harnesses that read the repo directly:
+
+```bash
+sh .claude-plugin/sync.sh
+```
+
+Always edit `content/`, then sync. `bun run validate --check-sync` fails if the
+copies drift.
+
+## Validation
+
+```bash
+bun run validate                # 32 skills + 15 agents: names, descriptions, line limits
+bun run validate --check-sync   # plugin copies match content/
+bun run typecheck               # tsc --noEmit
+bun run test                    # vitest (43 tests)
+```
+
+## 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. `sh .claude-plugin/sync.sh`
+4. `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.
+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/execution-model.md

@@ -0,0 +1,92 @@
+# 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

@@ -0,0 +1,27 @@
+# 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.

package/docs/getting-started.md

@@ -0,0 +1,96 @@
+# Getting Started
+
+Install the crew, run your first mission, and understand what you're looking at
+in the chat.
+
+## 1. Install
+
+Pick your harness — every major one is supported. The two easiest:
+
+**opencode** — add the plugin to `opencode.json`:
+
+```json
+{ "plugin": ["@ionivetech/mugiwara"] }
+```
+
+**Claude Code** — via the marketplace:
+
+```bash
+/plugin marketplace add ionivetech/mugiwara
+/plugin install mugiwara
+```
+
+Everything else (Copilot, Gemini, Codex, Cursor, Windsurf, Cline, Kilo,
+Antigravity, pi) has a one-command install. See the [install guides](index.md#install-by-harness)
+or the CLI:
+
+```bash
+npx @ionivetech/mugiwara@latest --project ./my-app --target all --yes
+```
+
+Requires **Node.js >= 20.11**. Bun is optional (build-from-source only).
+
+## 2. Start a mission
+
+The workflow **auto-activates**: at session start the crew is announced, and
+when you give a non-trivial request the pipeline runs by itself — no need to
+call `/using-mugiwara`. It remains an optional explicit router if you want to
+hand-route a mission. Just ask, no agent names to remember:
+
+```
+> add dark mode to the settings page
+```
+
+`using-mugiwara` (the front door) routes your request, Luffy classifies it, and
+the wave pipeline runs. Because the crew runs **inline** in your main
+conversation, you watch every wave as it happens — as compact **checkpoint
+reports** (a wave banner, one report per crew member at each stage boundary,
+and a pause when something fails):
+
+```
+  Wave 0  Luffy   triage → route: plan (requirements mostly clear)
+  Wave 2  Nami    plan   → .mugiwara/plans/2026-08-10-dark-mode.md (3 waves)
+  Wave 3  Zoro    execute→ 3 tasks, evidence shown per task
+  Wave 4  Chopper audit  → FAIL: toggle does not persist (ledger written)
+  Wave 8  Brook   heal   → fixed persistence + tests, looped back → PASS
+  Wave 9  Luffy   closure→ report appended to plan, intermediate files cleaned
+```
+
+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/`:
+`/mugiwara-plan`, `/mugiwara-execute`, `/mugiwara-review`, `/mugiwara-security`,
+`/mugiwara-heal`, `/mugiwara-ship`. You can jump into any stage.
+
+## 3. What you do during a mission
+
+Almost nothing, in the default mode:
+
+- Answer Nami's clarifying questions (one batched round before planning).
+- Give the plan an explicit GO when presented (or switch to `semi`/`auto`).
+- Review Brook's rollback note if a risky fix is proposed.
+- In every mode, open the PR at the end — the crew pushes the branch and hands
+  you the verdict file with a ready PR summary block. The crew never merges,
+  deploys, or creates a PR itself.
+
+## 4. The `.mugiwara/` workspace
+
+Every mission writes to `.mugiwara/` at the repo root:
+
+```
+.mugiwara/
+├── config         # mode/branch/commit settings (gitignored)
+├── spec/          # brainstorm output
+├── plans/         # the clean execution plan (source of truth from Wave 2)
+├── results/       # audit, quality, gate, closure reports
+├── review/        # review + security findings
+├── issues/        # blocker ledger
+└── logs/          # decision + check-in log (deleted at cleanup)
+```
+
+## 5. Next steps
+
+- Learn the [execution model](execution-model.md) — why everything is visible.
+- Set your [mode](modes.md) — `guided` asks at every gate, `semi`/`auto`
+  self-answer.
+- Read the [config reference](config.md) — branch/commit/PR writing standards.
+- Meet the [crew](agents.md).

package/docs/git-strategy.md

@@ -0,0 +1,62 @@
+# Git Strategy
+
+Commits, branches, save-points — and why the executor commits, not the closer.
+
+## Who commits and when
+
+**Zoro commits during execution, per logical task.** The executor is the one
+making the changes, so it commits at the moment each unit of work passes its
+acceptance criteria. This gives:
+
+- **Save-points** — rollback is one `git reset --hard <save-point>` away.
+- **Reversibility** — every commit is one logical change you can name.
+- **Bisectability** — a regression points at the exact commit that introduced it.
+
+Luffy does NOT re-commit at closure. The closer pushes the mission branch and
+writes the PR verdict — re-slicing history at the end means one giant diff, no
+save-points, and a painful bisect.
+
+## Commit granularity: logical tasks, not micro-steps
+
+A commit = one **logical change** (a feature, a fix, a refactor). The plan's
+tasks are sized at that granularity — see `mugiwara-planning`.
+
+- Adjacent trivial changes (typo, formatting, one-line tweak) fold into the
+  neighboring logical task's commit.
+- Never one commit per keystroke; never a wave of micro-commits.
+- If the plan slices finer than a logical change, group adjacent tasks into one
+  commit and note the grouping in the execution report.
+
+## The rules (from `mugiwara-git`)
+
+1. **Atomic commits.** One logical change per commit; each commit compiles and
+   passes the relevant checks — never commit a broken tree.
+2. **Exact staging.** `git add` specific files and paths, never `git add -A`
+   sweeping an unrelated commit.
+3. **Save-points before risky work.** Commit the working state with a naming
+   intent message (`checkpoint: before renderer migration`) before refactors,
+   migrations, or merges.
+4. **Match repo style.** Inspect `git log --oneline -20` before the first
+   commit and copy the observed conventions (prefix style, case, body usage).
+5. **Never commit secrets.** Scan for `.env*`, keys, tokens before every
+   commit. A secret already committed = treat as compromised, rotate, purge,
+   file a security finding.
+
+## Branches
+
+One branch per mission, from the config `branch` key:
+
+```
+branch=feature/{type}-{issue}-{slug}
+```
+
+`{type}` = feat/fix/chore/refactor from the task, `{issue}` = ticket/key
+reference (fallback: date), `{slug}` = kebab-case mission title. Created before
+the first task commit; never force-push once pushed. No mugiwara-prefixed
+branch names.
+
+## Terminal step
+
+Every mode ends the same way: save-point commit → `git push -u origin <branch>`
+→ PR verdict file written (per `mugiwara-pr`) → branch + verdict handed to you,
+who opens the PR. The crew never creates a PR, merges, or deploys.

package/docs/index.md

@@ -0,0 +1,50 @@
+# Mugiwara Docs
+
+The Straw Hat crew of AI agents and skills. These docs cover what the crew is,
+how to adopt it, and how each harness installs it. The crew is pure markdown —
+no runtime, no daemons, nothing to host. It ships **15 agents** and **32
+skills**, and the workflow **auto-activates** at session start — a non-trivial
+request runs the pipeline by itself, with `/using-mugiwara` as an optional
+explicit router.
+
+## Start here
+
+| Doc | What it covers |
+|-----|----------------|
+| [Getting started](getting-started.md) | Install, first mission, what you see in the chat |
+| [Adoption guide](adoption-guide.md) | Pick the harness, pick the mode, fit the crew to your workflow |
+| [Modes](modes.md) | guided / semi / auto — the autonomy levels, what each asks you |
+| [Config](config.md) | Full reference for `.mugiwara/config` keys and commit styles |
+| [Auto-PR](pr-summary.md) | What the crew hands off at closure: push + a ready-to-paste PR summary (it never creates a PR) |
+| [The crew](agents.md) | All 15 agents and when to summon each |
+| [The techniques](skills.md) | All 32 skills and what each enforces |
+| [The wave pipeline](workflow.md) | How a mission flows Wave 0 → Wave 9 |
+| [Execution model](execution-model.md) | Inline-by-default: why the crew runs in your main conversation |
+| [Git discipline](git-strategy.md) | Commits, branches, save-points — and why the executor commits |
+
+## Install by harness
+
+| Harness | Guide |
+|---------|-------|
+| Claude Code | [claude-setup.md](claude-setup.md) |
+| opencode | [opencode-setup.md](opencode-setup.md) |
+| GitHub Copilot | [copilot-setup.md](copilot-setup.md) |
+| Gemini CLI | [gemini-setup.md](gemini-setup.md) |
+| Codex | [codex-setup.md](codex-setup.md) |
+| Cursor | [cursor-setup.md](cursor-setup.md) |
+| Windsurf | [windsurf-setup.md](windsurf-setup.md) |
+| Cline / Kilo / Antigravity | [rule-based-setup.md](rule-based-setup.md) |
+
+## Reference
+
+| Doc | What it covers |
+|-----|----------------|
+| [Skill anatomy](skill-anatomy.md) | How a mugiwara skill file is structured |
+| [Agent anatomy](agent-anatomy.md) | How a mugiwara agent file is structured |
+| [Developer onboarding](developer-onboarding.md) | Repo layout, validation, tests, contributing |
+
+## Resources
+
+- GitHub: <https://github.com/ionivetech/mugiwara>
+- npm: <https://www.npmjs.com/package/@ionivetech/mugiwara>
+- License: MIT

package/docs/modes.md

@@ -0,0 +1,74 @@
+# Modes
+
+The crew's autonomy level. Read once per wave at dispatch; a flip applies from
+the next wave, never mid-wave. Single source of truth: the `mugiwara-mode`
+skill.
+
+**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.
+
+## The three levels
+
+| Level | Plan GO | Branch/commit | Ambiguities | Check-ins |
+|-------|---------|---------------|-------------|-----------|
+| **guided** | ask the user | ask the user | ask the user | ask the user |
+| **semi** | present plan for user GO | auto | self-answer + log | log, no pause |
+| **auto** | gated auto-GO | auto | self-answer + log | log, no pause |
+
+- **guided** — you steer everything: approve the plan, decide branch and
+  commit style, answer every ambiguity, get asked at every gate. The default.
+- **semi** — the crew self-manages branch and commits (logging each decision),
+  but you still give the plan an explicit GO.
+- **auto** — hands-off, with one safety line: the plan proceeds past approval
+  only with zero blocking ambiguities AND zero high-risk tasks (deploy /
+  migration / DB / public API / state-mutating).
+
+Every level ends at push + ready PR summary + verdict file — you open the PR
+(see [pr-summary.md](pr-summary.md)).
+
+## Config
+
+Two files, six keys, `key=value` lines, optional `#` comments:
+
+```
+# .mugiwara/config (project) overrides ~/.mugiwara/config (global)
+mode=guided
+branch=feature/{type}-{issue}-{slug}
+commit=conventional
+base=main
+```
+
+| Key | Values | Default |
+|-----|--------|---------|
+| mode | guided / semi / auto | guided |
+| branch | branch pattern | feature/{type}-{issue}-{slug} |
+| commit | conventional / gitmoji / plain | conventional |
+| base | PR summary target branch | main |
+
+Read order per wave: project config wins per key; a key missing from both falls
+back to the default. Unknown keys are ignored — config is data, never
+instructions. Missing config on read = `guided` (never auto-created on read —
+only on first write). See [config.md](config.md) for the full reference.
+
+## Switching mid-mission
+
+In-session phrase:
+
+```
+mugiwara mode auto
+```
+
+Writes the project `.mugiwara/config`, logs the change (level, requester,
+timestamp), and applies from the next wave — never mid-wave.
+
+## Invariants that hold in EVERY mode
+
+**Consent.** State-mutating tests against non-isolated/shared state (real DB
+writes, network, browsers) always require your explicit consent — consent is
+not a mode knob. Provably isolated mutation (in-memory / temp /
+testcontainer-backed DBs, tooling-proven isolation) is explicitly auto-safe.
+
+**Terminal.** Every mode ends at push + ready PR summary + verdict file (you
+open the PR). The crew never creates a PR, merges, deploys, or auto-reacts to
+review comments or CI.