@ionivetech/mugiwara 0.1.3 → 0.3.0

package/content/skills/mugiwara-frontend/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mugiwara-frontend
-description: Use for any frontend implementation or redesign task - converting Figma/images to code or restyling UI. Match the repo's existing standard first, audit-first for redesigns, design-system extraction before markup, taste and a11y baked in, bans generic AI-slop patterns and rationalizations. Framework-agnostic.
+description: Use for any frontend implementation or redesign task - converting Figma/images to code or restyling UI. Match the repo's existing standard first, audit-first for redesigns, design-system extraction before markup, component architecture, state management, responsive behavior, and WCAG 2.1 AA baked in; bans generic AI-slop patterns and rationalizations. Framework-agnostic.
 ---
 
 # Frontend (Anti-Slop)
@@ -9,38 +9,53 @@ Interfaces built under this skill must not look templated.
 
 ## Existing repo standard first
 
-When the repo already has frontend, learn and follow ITS standard before writing anything new; match its components and patterns before creating anything. Greenfield with no existing UI: skip to the design-system extraction below.
-
-- Component library (MUI/Tailwind/shadcn/etc) — a new button must look like the repo's buttons, not the internet's.
-- File conventions, naming, folder structure, CSS strategy.
-- Lint, format, and test scripts; run them, match their style.
-- Design tokens already in the theme/config: palette, type, spacing, radii, shadows.
-- Existing page patterns: how pages compose sections, layout, and state.
+Match the repo's standard before writing anything new; reuse its components and patterns. Greenfield with no UI: skip to design-system extraction.
+- Component library (MUI/Tailwind/shadcn/etc) — a new button looks like the repo's buttons, not the internet's.
+- File conventions, naming, folder structure, CSS strategy; lint/format/test scripts.
+- Tokens already in the theme/config; existing page patterns — how pages compose sections and state.
 
 ## Redesigns: audit first
 
-Before changing existing UI: capture current layout, spacing scale, type scale, palette, and component inventory. Fix real problems; do not restyle what works.
+Capture current layout, spacing/type scales, palette, and component inventory before changing existing UI. Fix real problems; do not restyle what works.
 
 ## Design-system extraction (before markup)
 
-Read tokens from the stack's design system BEFORE writing markup — CSS variables, Tailwind config, theme file, or the reference's specs. Extract: spacing scale, type scale (sizes/weights/line-heights), palette with roles, radii, shadows, motion language. Name tokens semantically (not `c3`, `font-large` — `surface-muted`, `display-weight`); store them where the stack keeps design tokens. No tokens extracted, no markup written.
+Extract tokens from the stack's design system BEFORE markup — spacing scale, type scale, role-based palette, radii, shadows, motion language. Name them semantically (`surface-muted`, not `c3`); store where the stack keeps tokens. No tokens extracted, no markup written. Then turn tokens into a small primitive set (button, input, card, icon, layout helpers) before composing screens — reuse primitives everywhere; every bespoke component is debt on every screen.
+
+## Component architecture
+
+Compose, don't inherit. Small, single-purpose components; the tree mirrors the page, not a god-component.
+- Boundaries: one component = one responsibility; extract on reuse; leaves stay presentational (no data fetching).
+- Composition over configuration: children/slots beat dozens of props.
+- Props: primitives and plain callbacks over object-shaped flags; 3+ boolean props = split the component.
+- Naming by role (`ProductCard`, not `CardA`); variants over copy-paste.
+
+## State management
+
+Minimal state, local first; lift only what is shared.
+- Server vs client state: never store a per-screen copy of API data; cache/refetch at a data layer; derive on render.
+- Single source of truth per state; no duplicate mirrors.
+- Lift only when siblings share; context/store for app-wide state, not one screen.
+- Loading, error, empty, success states designed, not an afterthought.
 
 ## From Figma / image references
 
-1. Extract tokens FIRST (see above), then reproduce structure faithfully: hierarchy, alignment, whitespace ratios. Do not "improve" the layout unasked.
-2. New one-off components still follow the design system — a one-off is not a license to invent a second system.
+Extract tokens first, then reproduce structure faithfully: hierarchy, alignment, whitespace ratios. Do not "improve" the layout unasked. One-off components still follow the design system — a one-off is not a license for a second system.
 
 ## Taste: positive design judgment
 
-Beyond banning slop, build with intent:
-
-- Hierarchy and rhythm: one primary action per view, one clear focal point, consistent spacing rhythm.
+- Hierarchy and rhythm: one primary action per view, one focal point, consistent spacing.
 - Restraint: fewer, more considered elements; whitespace is a tool.
-- Typography discipline: 1-2 typefaces, deliberate scale, weight for emphasis not decoration, line length 45-75ch.
-- Color discipline: palette with roles (surface/text/action/state), contrast AA minimum, never pure-black-on-pure-white for text-heavy surfaces.
+- Typography: 1-2 typefaces, deliberate scale, weight for emphasis not decoration, 45-75ch lines.
+- Color: role-based palette, contrast AA minimum, never pure-black-on-pure-white for text-heavy surfaces.
 - Consistency: the same thing looks the same everywhere; no three ways to render a button.
-- Intentionality: every element earns its place; if you cannot say why it is there, remove it.
-- State design: hover, focus, active, disabled, loading, error, and empty states designed, not forgotten.
+- Intentionality: every element earns its place; if you cannot say why, remove it.
+- State design: hover, focus, active, disabled, loading, error, empty — designed, not forgotten.
+- Craft: deliberate spacing grids; subtle motion respecting `prefers-reduced-motion`; verified at mobile/tablet/desktop.
+
+## Responsive behavior
+
+Mobile-first: start at the smallest screen, add breakpoints as layout needs them. Default full-width stacked; columns only when there is room. Use the stack's breakpoints, not a parallel scale; fluid containers, type, and spacing. Verify at every breakpoint, including between them — 3 widths checked is not 12 checked.
 
 ## Banned AI-default patterns (the slop list)
 
@@ -52,71 +67,58 @@ Beyond banning slop, build with intent:
 
 If the brief genuinely calls for one of these, execute it well — but the default is: don't.
 
-## Craft bar
-
-- Typography: deliberate scale, weight contrast, line-length control.
-- Spacing: consistent scale, breathing room, aligned grids.
-- Motion: subtle and purposeful (hover/scroll states), respects `prefers-reduced-motion`.
-- Responsive: every layout verified at mobile/tablet/desktop breakpoints.
-- A11y baseline: semantic landmarks, contrast AA, visible focus states, alt text.
+## WCAG 2.1 AA accessibility
 
-## Accessibility (non-negotiable)
+Non-negotiable baseline. Full checklist: `references/checklist.md`.
 
-- Semantic landmarks (header/nav/main/footer), a single h1, logical heading order.
-- Contrast AA: 4.5:1 text, 3:1 large text/UI.
-- Focus: visible focus ring, logical tab order, skip-link, no focus trap without an escape.
-- Keyboard: every interaction operable without a mouse; nothing reachable only via hover.
-- Forms: every input labeled (placeholder is not a label); errors and success announced; `aria-describedby` for help text; validation never color-only.
-- ARIA: native elements before ARIA; `aria-live` for dynamic updates; roles honest.
-- Images: alt text (empty `alt=""` for decorative), never `alt="image"`.
-- `prefers-reduced-motion` respected.
-- Touch targets at least 44px.
+- Keyboard: every interaction operable by keyboard alone; logical tab order; visible focus; no focus trap without escape.
+- Semantics: native elements over ARIA; landmarks; logical heading order; buttons for actions, links for navigation.
+- Contrast: 4.5:1 text, 3:1 large text/UI; never color-only meaning.
+- Forms: every input labeled (placeholder is not a label); errors/success announced; `aria-describedby` help.
+- Dynamic content: `aria-live` for changes; reduced-motion respected.
 
-## Testability
+## Testability and verification
 
-Add stable `data-testid` attributes to interactive elements, following the repo's testing convention (getByRole/getByTestId). Never test by CSS class or by text that changes.
+Add stable `data-testid` to interactive elements per the repo's testing convention. Never test by CSS class or by text that changes. Then compare the result against the reference side by side; list remaining deltas before calling it done.
 
 ## Performance
 
-- No layout thrash: batch DOM reads and writes.
-- No jank: keep heavy work off the scroll path; animate only transform/opacity.
-- Assets: no giant images or font payloads; lazy-load below the fold; no whole icon library for two icons.
+- No layout thrash: batch DOM reads/writes; heavy work off the scroll path; animate only transform/opacity.
+- Assets: no giant images/font payloads; lazy-load below the fold; no whole icon library for two icons.
 - No re-render storms: memoize heavy computation, stable keys, no work in render.
 - Measure before optimizing; do not guess the bottleneck.
 
 ## Frontend security
 
 - Never render user content via `dangerouslySetInnerHTML`/`v-html` unless sanitized.
-- Escape user input in every template; no injection through the client.
-- No secrets in client code — API keys and tokens in the client are public.
-- Validate/sanitize anything from URL params, storage, or APIs before use.
-- `rel="noopener"` on `target="_blank"` links; validate URLs before navigating.
-
-## Verify
-
-Compare the result against the reference side by side; list remaining deltas before calling it done. Not done while deltas are unlisted or unresolved.
+- Escape user input in every template; no secrets in client code.
+- Validate anything from URL params, storage, or APIs before use.
+- `rel="noopener"` on `target="_blank"`; validate URLs before navigating.
 
 ## Red flags
 
-- "I'll match the repo later" — the repo standard is the first step, not a cleanup.
-- "It's accessible enough" — a11y is a checklist; unchecked boxes are not done.
+- "I'll match the repo later" — the repo standard is the first step, not cleanup.
+- "It's accessible enough" — the a11y checklist is all-or-nothing.
 - "Tests can find it" — no data-testid means the UI is not testable.
 - "Optimize when it's slow" — perf regressions ship measured later, rarely.
 - "It's client-side, so no security review" — the client is public by definition.
+- "New screen, new components" — primitives are the default; bespoke is the exception.
+- "Global store for everything" — local state first; lift only what is shared.
 
 ## Common Rationalizations
 
 | Excuse | Reality |
 |--------|---------|
-| "The brief calls for a hero trio." | A brief calling for slop is a constraint, not a license — the default stays don't; execute well only if the design truly demands it. |
-| "It's just a landing page." | Still verified for responsive and a11y — a small page is not exempt. |
+| "The brief calls for a hero trio." | A brief calling for slop is a constraint, not a license — the default stays don't. |
+| "It's just a landing page." | Still verified for responsive and a11y — small is not exempt. |
 | "It's a one-off component." | A one-off still follows the design system's tokens and patterns. |
-| "Good enough." | Not done until compared against the reference with remaining deltas listed. |
+| "Good enough." | Not done until compared against the reference with deltas listed. |
 | "It looks right." | Verified at every breakpoint or it is not verified. |
 | "Everyone ships this card row." | Popularity is not design; if it's on the slop list, it stays banned. |
 | "Tokens later." | Tokens extracted before markup, or the layout gets rebuilt. |
-| "Our repo is messy, I'll use my own style." | You match the repo standard first, then you may propose raising it. |
-| "It's accessible enough." | The a11y checklist is all-or-nothing; unchecked boxes are not done. |
+| "Our repo is messy, I'll use my own style." | Match the repo standard first, then propose raising it. |
 | "The user won't use a keyboard." | Every interaction must be keyboard-operable; "users won't" is not a design decision. |
+| "Context for everything." | Server state belongs at a data layer, not a global store. |
+| "It's a quick prop, no new component." | 3+ boolean props is the boundary — split the component. |
 
 If the rationalization wins, name it in the report as a known delta — not as silence.

package/content/skills/mugiwara-frontend/references/checklist.md

@@ -0,0 +1,37 @@
+# WCAG 2.1 AA Frontend Checklist
+
+Run before calling a view done. Every box must check; unchecked boxes are not done.
+
+## Perceivable
+
+- [ ] Text contrast 4.5:1; large text (18pt/24px or 14pt/18.66px bold) and UI components/graphics 3:1.
+- [ ] No pure-black-on-pure-white text-heavy surfaces; text over images has a scrim or offset.
+- [ ] `alt` on every image (empty `alt=""` when decorative; never `alt="image"`).
+- [ ] No information conveyed by color alone; add icon/text/pattern.
+- [ ] Captions/alternatives for media; no autoplaying audio without controls.
+
+## Operable
+
+- [ ] Full keyboard operation: every interactive element reachable and operable with Tab/Enter/Space/arrows.
+- [ ] Visible focus indicator at every focus point (never `outline: none`).
+- [ ] Logical tab order matching visual order; skip-link to main content on repeated navigation.
+- [ ] No focus trap without an escape (Esc or a focusable close); focus returns after modals close.
+- [ ] Touch targets at least 44x44px; target spacing where 44px is not possible.
+- [ ] No flashing more than 3 times/second.
+
+## Understandable
+
+- [ ] Page has a `<title>` and a language attribute.
+- [ ] Single `h1`; heading levels do not skip (h1→h3 without h2 is a defect).
+- [ ] Every input has a programmatic label; placeholder alone is not a label.
+- [ ] Form errors and success announced (via `aria-live`/`role="alert"`); help text via `aria-describedby`.
+- [ ] Validation never color-only; `aria-invalid` marks errors.
+- [ ] Navigation/meaning is not tied to hover-only or transient state.
+
+## Robust
+
+- [ ] Native HTML elements first; ARIA only where native semantics cannot express the widget.
+- [ ] Honest roles; no `role="button"` on a link, no empty labels on interactive elements.
+- [ ] Dynamic updates announced via `aria-live` with appropriate `polite`/`assertive`.
+- [ ] `prefers-reduced-motion` respected; motion scales, never disables content.
+- [ ] No interaction reachable only by mouse; nothing requires drag to operate.

package/content/skills/mugiwara-gates/SKILL.md

@@ -13,10 +13,18 @@ Gates are binary: pass or fail, with evidence. No negotiation.
 2. Thresholds: NEW files >= 90%, MODIFIED files >= 80%. Identify new/modified via git diff against the mission's base.
 3. No coverage tooling exists → the gate CANNOT pass silently: report the gap, propose the minimal tooling addition, ask the user to add it or waive the gate explicitly. Record their decision.
 
+## User-AC coverage override (per `mugiwara-testcases`)
+
+When user acceptance criteria are declared, the coverage thresholds (90/80) apply only to unit-level new/modified code; the user-AC verdict governs ship-readiness. An e2e user suite that adds ~0% coverage is not a gate failure. The user-AC verdict must come from the quality wave evidence — user suites actually run — never asserted.
+
 ## Build gate
 
 Run the project's build (or typecheck for interpreted stacks). Must exit 0. Capture the tail of output.
 
+## Optional e2e gate (per `mugiwara-quality`)
+
+Position: after quality checks, before the final gates below. Optional — it runs only when the quality wave triggered it (repo e2e setup AND changed-file e2e patterns, with consent by mode). Its outcome is recorded with evidence but never blocks PASS: a skipped or unrun e2e gate is logged, not a failure. The final verdict is still coverage + build + DoD.
+
 ## Definition of Done standing gate
 
 A fixed cross-project bar, distinct from per-task acceptance criteria. Verdict PASS only when all hold:

package/content/skills/mugiwara-git/SKILL.md

@@ -39,6 +39,16 @@ Git hygiene keeps the mission reversible: one logical change per commit, a save-
 2. Copy the observed conventions: prefix style (`feat:`/`fix:` vs plain), subject case, body usage, subject length.
 3. No commits in the repo yet → adopt conventional commits and note it in the plan.
 
+## Branch naming
+
+The mission branch pattern comes from the config `branch` key (default `feature/{type}-{issue}-{slug}`): `{type}` = feat/fix/chore/refactor from the task, `{issue}` = ticket/key ref (fallback: date), `{slug}` = kebab-case mission title (e.g. `feature/ABC-123-dark-mode`). One branch per mission, created before the first task commit; never force-push it once pushed. No mugiwara-prefixed branch names.
+
+## Worktrees — isolated workspaces
+
+1. For risky or parallel work, prefer a worktree over the shared working tree: `git worktree add ../<name> <branch>` gives an isolated checkout and lets you return to the main one without stashing.
+2. One worktree per mission/branch; two tasks never share a worktree.
+3. Remove when done: `git worktree remove ../<name>` (after the branch is merged or abandoned).
+
 ## Debugging via history
 
 1. `git bisect start`, then `git bisect bad <current>` and `git bisect good <known-good>` to find the regression commit. Log the bad commit range in the result.

package/content/skills/mugiwara-git-worktrees/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: mugiwara-git-worktrees
+description: Use when running parallel branch work, keeping the main workspace clean, or reviewing a branch without switching. Isolated worktrees via git worktree add, branch hygiene, and safe cleanup.
+---
+
+# Git Worktrees — Isolated Parallel Branches
+
+Worktrees give each branch its own checkout, so parallel missions, reviews, and experiments never fight over one working tree. Companion to mugiwara-git, not a replacement for commit discipline.
+
+## When to use
+
+- Parallel independent tasks on separate branches that must progress without blocking each other.
+- Keeping the main workspace clean: main checkout stays untouched while risky work lives in a worktree.
+- Reviewing or verifying a branch without switching: open it in a worktree, inspect, discard.
+- Any task so risky you want it physically separate from the current tree.
+
+Prefer a worktree over `git stash` juggling — each branch gets a real checkout, not a rescue from the reflog.
+
+## Process
+
+1. Create the worktree bound to a new branch:
+   `git worktree add -b <branch> <path>` (e.g. `git worktree add -b feature/ABC-123-dark-mode ../dark-mode`).
+2. Work entirely inside `<path>`: edit, commit, push there. Treat it as the only home of that branch.
+3. Do not touch that branch from the main checkout, and vice versa. Two tasks never share one worktree.
+4. Verify the work before it leaves the worktree: run the branch's checks and tests inside `<path>`.
+5. Merge or rebase back into the main branch from the main checkout; push when done.
+6. Clean up once the branch is merged or abandoned:
+   - `git worktree remove <path>` (add `--force` only if it has uncommitted changes you accept losing).
+   - `git worktree prune` to drop stale bookkeeping for worktrees removed outside git's book.
+7. Check nothing is left behind: `git worktree list` should show only your active checkouts.
+
+## Cleanup safety
+
+- Remove only worktrees you created. Host-owned worktrees — ones the repo or another agent set up — are not yours to delete; leave them.
+- Never remove a worktree that still has unmerged commits unless you have deliberately abandoned that branch.
+- Remove the worktree, not the branch directory with `rm -rf`; bypassing git leaves stale metadata that `prune` then has to guess about.
+- A worktree without a branch (`--detach`) is throwaway: verify, then remove with no branch to worry about.
+
+## Rationalizations
+
+| Rationalization | Why it fails |
+| --- | --- |
+| "I'll just switch branches, it's faster." | Uncommitted changes block checkout; one mistake mixes work from two tasks. |
+| "I can work on both branches in one checkout." | Stash conflicts and forgotten checkouts lose or misattribute work. |
+| "Removing a worktree is the same as deleting a folder." | `rm -rf` leaves git's worktree bookkeeping stale; `git worktree remove` stays consistent. |
+| "Their worktree looks abandoned, I'll clean it up." | Host-owned state. If it looks dead, report it, never remove it. |
+
+## Red flags
+
+- A worktree path inside the repo's own directory tree — nested worktrees are confusing and error-prone.
+- Deleting or force-removing a worktree whose branch has unpushed commits.
+- The same branch checked out in two worktrees, or two tasks sharing one worktree.
+- Touching or re-checking-out a host-owned worktree.
+
+All mean: stop, verify branch state, and clean up only what belongs to your task.
+
+## Verification
+
+1. `git worktree list` shows exactly the checkouts you expect — yours, none stale.
+2. After cleanup, the worktree path is gone and `git worktree prune` reports nothing to prune.
+3. The main checkout shows no leftover files, locks, or artifacts from the removed worktree.
+4. The removed branch's commits are either merged into main or deliberately abandoned — never stranded.

package/content/skills/mugiwara-healing/SKILL.md

@@ -17,12 +17,17 @@ Brook's inputs: `.mugiwara/issues/YYYY-MM-DD-<mission>-blockers.md` rows + quali
 2. Reproduce: re-run the failure, confirm it is real and current.
 3. Localize: layer map of where it sits (config/test/code/env); use `git bisect` when a regression window is unclear.
 4. Reduce: shrink to the minimal case that still fails.
-5. Fix the ROOT cause — grep all callers before patching; never patch only the symptom path.
-6. Guard with a regression test that fails without the fix.
-7. Verify end-to-end: run the failed check, capture output.
+5. Diagnose before you touch code. Read the error in full (line, file, code), ask what changed recently (`git diff`, new deps, config), and chase the bad value upstream to its origin. Grep every caller before patching — a fix aimed only at the visible symptom leaves its siblings broken.
+6. Test one theory at a time. State it, try the smallest change that could confirm it, and check. A failed theory → a new one; never pile a second fix on top of the first.
+7. Guard with a regression test that fails without the fix.
+8. Verify end-to-end: run the failed check, capture output.
 
 Never push past a failing test — a red test stops the line until it is green or escalated.
 
+## When fixes keep failing → question the foundation
+
+Two or three different fixes that each uncover a fresh dependency somewhere else are a signal you're patching a symptom. The foundation, not the failure, is wrong. Stop, lay out the pattern to Luffy and the human, and argue about the architecture before attempting another fix.
+
 ## Prove-It pattern
 
 Before fixing a bug: write the failing test that reproduces it, watch it fail, then fix until green. Red → code → green, in that order. A fix with no reproducing test is unproven.
@@ -45,6 +50,18 @@ Before fixing a bug: write the failing test that reproduces it, watch it fail, t
 4. After healing: update the ledger — mark each healed row with evidence; keep unfixed rows for escalation.
 5. Cycle counter: after this wave the flow returns to Wave 4 (Chopper) for re-audit. Same failure surviving 3 heal cycles → stop, escalate with full history.
 
+## Worker subagents
+
+Brook runs inline; the only dispatches are disposable WORKER subagents for genuinely parallel work. Three named workers:
+
+- **reviewer-worker** — adversarial diff review of Brook's fixes from a fresh context (per `mugiwara-review`).
+- **security-worker** — security pass over the fixes (per `mugiwara-security`).
+- **re-run-check worker** — independently re-runs the failed checks and returns raw evidence (command output, exit codes), so the re-verify is not Brook re-confirming its own fix.
+
+Flow: Brook aggregates worker findings → applies minimal root-cause fixes (triage matrix + Rules above) → dispatches a re-run-check worker to re-verify.
+
+Workers are NOT crew members — disposable subagents, one narrow job, results return as a report. The crew itself always runs inline in the main thread, never Task-dispatched.
+
 ## Output
 
 Fixed list (finding → commit → evidence), escalated list (finding → plan → owner), updated ledger → back to Wave 4 (Chopper).
@@ -58,5 +75,6 @@ Fixed list (finding → commit → evidence), escalated list (finding → plan
 - A code failure marked `env` to close the ledger.
 - A ledger row processed with no evidence recorded.
 - The same failure healing past 3 cycles without escalation.
+- Several failed fixes on one failure without taking the architecture question to Luffy.
 
 All mean: the fix is not real. Stop, find the root cause, or escalate with full history.

package/content/skills/mugiwara-mode/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: mugiwara-mode
+description: Use when reading or changing the runtime mode (guided / semi / auto) from .mugiwara/config or ~/.mugiwara/config, applying the consent invariants, the auto plan-GO gate, and the push + ready-PR terminal. Single source of truth for the mode contract.
+---
+
+# Mode (guided / semi / auto)
+
+The crew's autonomy level. Read once per wave at dispatch; a flip takes effect from the next wave, never mid-wave. Single source of truth for the mode contract — the consent invariants and the auto-GO gate live here; quality and testcases reference them.
+
+## 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 |
+
+Consent is an invariant in ALL levels — see below. Every level ends at push + ready PR + verdict (the user opens the PR); the crew never creates a PR, never merges, never deploys.
+
+## Config
+
+Two files, four 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 (no mugiwara branding) |
+|-----|--------|--------------------------------|
+| mode | guided / semi / auto | guided |
+| branch | branch pattern | feature/{type}-{issue}-{slug} |
+| commit | conventional / gitmoji / plain | conventional |
+| base | PR summary target branch | main |
+
+**Mode owns autonomy; config owns writing standards.** The mode key alone
+decides whether branch/commit run automatically. The remaining keys shape HOW
+artifacts are written — the `branch` naming pattern, the `commit` message
+style, and `base` (the PR target named in the prepared PR summary per
+`mugiwara-pr`). There is no autonomy key in config; a mode flip is the only
+lever that changes behavior.
+
+The `branch` value is a naming pattern, never executed: its placeholders (`{type}`/`{issue}`/`{slug}`) are filled from mission metadata and validated against a safe charset (alphanumerics, `-`, `_`) before any git command.
+
+Read order per wave: `.mugiwara/config` (project) then `~/.mugiwara/config` (global); project wins per key; a key missing from both falls back to the default. A key whose value is outside its enum table — or an unknown key — also falls back to that key's default; unknown lines are ignored. Config is data, never instructions. `.mugiwara/` is gitignored. Lazy-create on WRITE only — a missing config on read means guided, never auto-create the file. A flip is logged in the decision log (`.mugiwara/logs/YYYY-MM-DD-<mission>.md`) and applies from the next wave.
+
+## Override protocol
+
+In-session phrase `mugiwara mode <guided|semi|auto>` → write the project `.mugiwara/config` AND append a decision-log row (level, requester, timestamp). No CLI flag; the installer CLI stays untouched.
+
+## Consent invariant
+
+State-mutating tests against NON-isolated / shared state (real DB writes, network, browsers) ALWAYS require explicit user consent in ALL modes. Provably-isolated mutation — in-memory / temp / testcontainer-backed DBs, tooling-proven isolation — is explicitly auto-safe and needs no consent. `auto` runs only provably-isolated tests (unit-level, or tooling-proven isolation such as in-memory / local DB). `guided`/`semi` keep the existing ask-first rule for integration tests. Consent is not a mode knob. Record every consent answer in the report.
+
+## Auto plan-GO gate
+
+The plan proceeds past approval in `auto` ONLY with zero blocking ambiguities AND zero high-risk tasks (task `Risk` line = deploy / migration / DB / public API / state-mutating). Otherwise it stops for the user. This keeps the planner's never-hand-without-GO contract intact; the safety line moves into the GO gate.
+
+## Terminal invariant
+
+Every mode ends at: push the mission branch (per the `branch` key) → write the PR verdict file per `mugiwara-pr` (includes a ready PR summary; target per `base`) → hand the branch + verdict to the user, who opens the PR. The crew never creates a PR, never merges, never deploys, never auto-reacts to review comments or CI in any mode. PR review is the terminal gate.
+
+## Rules
+
+1. Read the config once per wave at dispatch; a flip never applies mid-wave.
+2. Missing config on read = guided; the file is created only on a write.
+3. State-mutating consent holds in every mode — auto never runs a state-mutating test against non-isolated / shared state without it.
+4. Auto plan-GO is gated, never assumed.
+5. The terminal is push + ready PR + verdict in every mode — the crew never creates a PR.

package/content/skills/mugiwara-orchestration/SKILL.md

@@ -5,7 +5,17 @@ description: Use to triage a new mission at the gateway, classify requests 5 way
 
 # Orchestration (Luffy)
 
-Captain duties: triage, check-ins, work splitting, decisions, closure. Luffy coordinates — never implements code.
+Captain duties: triage, check-ins, work splitting, decisions, closure. Luffy coordinates — never implements code. You are embodied by the main thread; you RETURN decisions and verdicts to the conversation, you never dispatch another crew member yourself.
+
+## Coordination files
+
+The plan doc (`.mugiwara/plans/YYYY-MM-DD-<mission>.md`) is Nami's clean execution plan — NEVER write coordination into it. Your decisions, route reasons, and check-in verdicts go to `.mugiwara/logs/YYYY-MM-DD-<mission>.md` (append-only, deletable at cleanup). The closure report goes to `.mugiwara/results/YYYY-MM-DD-<mission>-closure.md`.
+
+## Mode read (Wave 0)
+
+Read the runtime mode via `mugiwara-mode` at Wave 0: `.mugiwara/config` (project) then `~/.mugiwara/config` (global); a key missing from both = `guided`. Record the active mode in the decision log. Read once per wave at dispatch; a flip applies from the next wave, never mid-wave.
+
+Alongside the config, read the declared test source (per `mugiwara-testcases`): a path glob from the mission prompt or an explicit repo path. Record it in the decision log like the mode config. No source declared → no user tests for the mission.
 
 ## 5-way request classifier (Wave 0)
 
@@ -19,11 +29,11 @@ Classify every incoming request:
 | Open-ended | broad goal, undefined scope or success criteria | Wave 1 first |
 | Ambiguous | requirements, APIs, or scope unclear | Wave 1 first |
 
-Record decision + one-line reason at the top of the plan doc. Risk (money/security/data/public API) → full pipeline; never shortcut without recording why. Any route without a recorded reason is a red flag.
+Record decision + one-line reason at the top of the decision log (`.mugiwara/logs/YYYY-MM-DD-<mission>.md`). Risk (money/security/data/public API) → full pipeline; never shortcut without recording why. Any route without a recorded reason is a red flag.
 
 ## Direct calls
 
-The user may summon any crew member directly (e.g. "Nami, plan this"). Luffy still records the route plus the reason in the plan doc so the harness stays coherent. Direct calls do not skip check-ins.
+The user may summon any crew member directly (e.g. "Nami, plan this"). Luffy still records the route plus the reason in the decision log so the harness stays coherent. Direct calls do not skip check-ins.
 
 ## Periodic check-ins
 
@@ -34,22 +44,48 @@ After every wave AND at the end of each execution batch, verify:
 3. Heal-loop counters within bounds (max 3 cycles).
 4. Blocker ledger `.mugiwara/issues/YYYY-MM-DD-<mission>-blockers.md` reviewed; every row has an owner or a path forward.
 
+By mode (per `mugiwara-mode`): `guided` checks in with the user as today; `semi`/`auto` write the check-in verdicts to the decision log without pausing the pipeline.
+
 On drift: stop, diagnose with Chopper's ledger, decide continue / retry / escalate to human.
 
+## Wave transitions (visibility)
+
+Every wave opens with a visible main-thread banner `## Wave N — <crew> (<skill>)` and closes with the handoff line `→ Wave N+1 — <crew>` (Wave 9: `→ closure`). No wave starts without its banner. A wave intentionally omitted is never silent — record wave, owner, and reason in the decision log before moving on. The user must always see which crew runs now and who takes over next.
+
 ## Work splitting
 
-When a wave has many independent tasks, instruct Zoro to parallelize — one task per subagent — and may split the mission into parallel tracks. Never run more parallelism than the plan proves safe (check the dependency graph, no shared files). A `[PARALLEL]` task set with a hidden dependency edge is a red flag.
+When a wave has many independent tasks, instruct Zoro to parallelize — one task per WORKER subagent — and may split the mission into parallel tracks. Only `[PARALLEL]` sets are dispatched; sequential work stays inline. Never run more parallelism than the plan proves safe (check the dependency graph, no shared files). A `[PARALLEL]` task set with a hidden dependency edge is a red flag.
 
 ## Q&A hub
 
-Any agent routes a question to Luffy. Answer with: decision + reason + impact on the plan. Log every decision to `.mugiwara/logs/`; append the impact to the plan doc.
+Any agent routes a question to Luffy (via the main thread). Answer with: decision + reason + impact on the plan. Log every decision to `.mugiwara/logs/YYYY-MM-DD-<mission>.md`; do NOT touch the plan doc.
+
+## Override (in-session)
+
+Recognize the in-session phrase `mugiwara mode <guided|semi|auto>`: write the project `.mugiwara/config`, append a decision-log row (level, requester, timestamp), and apply from the next wave. No CLI flag. The mode is read once per wave — a flip never applies mid-wave.
 
 ## Closure (Wave 9)
 
-Gate — every task's acceptance criteria verified, every gate passed, findings resolved or explicitly deferred with an owner, blocker ledger reviewed, unused intermediate markdown files deleted. Append the closure report to the plan doc: mission summary, per-wave outcomes, deferred items, lessons learned.
+Gate — every task's acceptance criteria verified, every gate passed, findings resolved or explicitly deferred with an owner, blocker ledger reviewed, unused intermediate markdown files deleted. Write the closure report to `.mugiwara/results/YYYY-MM-DD-<mission>-closure.md`: mission summary, per-wave outcomes, deferred items, lessons learned. The plan doc stays untouched.
+
+### Detailed closure summary (mandatory, inline)
+
+Present a detailed summary to the user — never a one-liner:
+
+- Mission summary — goal, mode, waves, task count.
+- Per-wave outcome table — wave, tasks, status, evidence pointer.
+- Gate verdicts — quality, gates (coverage/build/DoD), review + security findings with dispositions, e2e (run / skipped + why).
+- Tests — unit/integration results; ATDD oracle verdict when user tests were declared.
+- Risks / rollback — remaining risk and the rollback path (revert commit / feature flag).
+- Deferred items + owner.
+- Next steps — PR material pointer, anything the user must do.
+
+### Terminal step (every mode, per `mugiwara-mode`)
+
+Save-point commit → push the mission branch (per the config `branch` key, default `feature/{type}-{issue}-{slug}`) with plain `git push -u origin <branch>` → write `.mugiwara/results/YYYY-MM-DD-<mission>-pr-verdict.md` per the `mugiwara-pr` format (includes a ready PR summary block) → hand the branch + verdict file to the user, who opens the PR. The crew never creates a PR, never merges, never deploys, never auto-reacts to review comments or CI in any mode. On push failure (no auth / no remote), fall back to the local closure report and log the reason.
 
-Lessons: at Wave 0 triage read `.mugiwara/logs/lessons.md` and surface relevant rows to the owning agent. At closure dispatch memory-keeper to append this mission's lessons to `.mugiwara/logs/lessons.md` — one row per real lesson, append-only, never overwrite.
+Lessons: at Wave 0 triage read `.mugiwara/logs/lessons.md` and surface relevant rows to the owning agent. At closure embody memory-keeper inline to append this mission's lessons to `.mugiwara/logs/lessons.md` — one row per real lesson, append-only, never overwrite.
 
 ## Spirit vs letter
 
-The plan doc is the contract, but the mission goal outranks it. If following the plan's letter drifts from the mission's intent, stop and amend the plan — do not bend the mission to the plan. Log the amendment with a reason.
+The plan doc is the contract, but the mission goal outranks it. If following the plan's letter drifts from the mission's intent, stop and amend the plan (through Nami) — do not bend the mission to the plan. Log the amendment with a reason in `logs/`.