@ionivetech/mugiwara 0.2.0 → 0.4.0

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

@@ -1,46 +1,65 @@
 ---
 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)
 
+## Skip when
+
+- Diff touches no UI code: backend, docs, config, or CLI-only change.
+- No visual change, markup, styling, or frontend behavior in the mission.
+
 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. 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 all breakpoints.
+
+## 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 +71,54 @@ 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
+## WCAG 2.1 AA accessibility
 
-- 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.
+Non-negotiable baseline. Full checklist: `references/checklist.md`.
 
-## Accessibility (non-negotiable)
+- 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.
 
-- 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.
+## Testability and verification
 
-## Testability
-
-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 URL params/storage/API input.
+- `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. |
-| "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. |
-| "It looks right." | Verified at every breakpoint or it is not verified. |
+| "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." / "It's a one-off component." | Still verified for responsive and a11y; still follows the design system's tokens and patterns. |
+| "Good enough." / "It looks right." | Not done until compared against the reference with deltas listed, at every breakpoint. |
 | "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. |
-| "The user won't use a keyboard." | Every interaction must be keyboard-operable; "users won't" is not a design decision. |
+| "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." / "Context for everything." | Every interaction keyboard-operable; 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

@@ -5,6 +5,11 @@ description: Use after quality checks to enforce the quality gates - coverage (n
 
 # Gates (Franky)
 
+## Skip when
+
+- No code changed: docs-only or README-only diff with zero production surface.
+- Repo has no coverage tooling AND no test suite detected — record the skip, don't fake a verdict.
+
 Gates are binary: pass or fail, with evidence. No negotiation.
 
 ## Coverage gate
@@ -21,6 +26,10 @@ When user acceptance criteria are declared, the coverage thresholds (90/80) appl
 
 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

@@ -5,6 +5,11 @@ description: Use when committing, splitting commits, or debugging via git histor
 
 # Git Discipline (Zoro, Brook)
 
+## Skip when
+
+- No commits to make this wave — nothing staged, nothing to split or amend.
+- User handles version control manually for this mission.
+
 Git hygiene keeps the mission reversible: one logical change per commit, a save-point before risky work, and history you can bisect.
 
 ## Atomic commits

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

@@ -0,0 +1,67 @@
+---
+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
+
+## Skip when
+
+- Single-branch sequential work: no parallel branches running at once.
+- Working tree stays clean and review happens on the current branch.
+
+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

@@ -5,6 +5,11 @@ description: Use when earlier waves produced failures - test failures, gate fail
 
 # Healing (Brook)
 
+## Skip when
+
+- No failures recorded: blocker ledger empty, all gates and reviews passed.
+- User explicitly accepts a failure as-is and recorded the decision.
+
 Fix what failed, minimally, and prove it. One clean retry per cycle.
 
 ## Read the ledger first
@@ -50,6 +55,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).

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

@@ -5,6 +5,11 @@ description: Use at mission end or before starting work in a repo the crew has w
 
 # Lessons (Mission Memory)
 
+## Skip when
+
+- Fresh repo, zero prior missions: no ledger exists and nothing to surface.
+- Nothing learned worth keeping — no new lesson, no repeated failure pattern.
+
 The crew's institutional memory. Every mission writes what it learned so the next mission starts ahead of it.
 
 ## The ledger

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

@@ -5,6 +5,11 @@ description: Use when reading or changing the runtime mode (guided / semi / auto
 
 # Mode (guided / semi / auto)
 
+## Skip when
+
+- Mode unchanged this session: no config read or flip requested.
+- Lane 0 direct work where autonomy level is irrelevant to the change.
+
 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
@@ -15,17 +20,18 @@ The crew's autonomy level. Read once per wave at dispatch; a flip takes effect f
 | 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 crew never merges or deploys.
+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, three keys, `key=value` lines, optional `#` comments:
+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) |
@@ -33,6 +39,14 @@ commit=conventional
 | 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.
 
@@ -52,7 +66,7 @@ The plan proceeds past approval in `auto` ONLY with zero blocking ambiguities AN
 
 ## Terminal invariant
 
-Every mode ends at: push the mission branch (per the `branch` key) → write the PR verdict file per `mugiwara-pr` → 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.
+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
 
@@ -60,4 +74,4 @@ Every mode ends at: push the mission branch (per the `branch` key) → write the
 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.
+5. The terminal is push + ready PR + verdict in every mode — the crew never creates a PR.

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

@@ -5,6 +5,11 @@ description: Use when instrumenting, tracing, or debugging how the mugiwara crew
 
 # Observability (Trace the Crew)
 
+## Skip when
+
+- Lane 0 direct work: no waves, no dispatches, nothing to trace.
+- User explicitly declined tracing for this mission.
+
 Make every mission replayable: one trace file, one line per dispatch, so you can see who ran what, how long, and where it failed.
 
 ## Trace log

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

@@ -5,6 +5,11 @@ description: Use to triage a new mission at the gateway, classify requests 5 way
 
 # Orchestration (Luffy)
 
+## Skip when
+
+- No new mission to route: mid-wave continuation with the route already recorded.
+- User drives the pipeline by hand via explicit stage commands.
+
 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
@@ -31,6 +36,14 @@ Classify every incoming request:
 
 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.
 
+## Lane routing (Wave 0, size before process)
+
+Alongside the 5-way class, size the mission and pick a lane: Lane 0 (Direct) skips the pipeline entirely; Lane 1 (Lean) runs execute → quality; Lane 2 (Standard) runs plan → execute → checkpoint → review; Lane 3 (Full) runs all 9 waves; Lane 4 (Spike) runs brainstorm then re-sizes. Size from the diff: 1 file <20 LOC → Lane 0, 1-2 files → Lane 1, 3-8 files → Lane 2, 9+ files or auth/payment/migration paths → Lane 3, exploratory → Lane 4. Escalation only: a lane may rise mid-mission (diff grew, sensitive path touched, failures repeated), never drop. Record the chosen lane and its signal in the decision log.
+
+## Spec bridge (Wave 0 → Wave 2)
+
+Wave 1 (Usopp) writes the brainstorm output to `.mugiwara/spec/YYYY-MM-DD-<mission>.md` — the bridge Nami reads. A route straight to Wave 2 (Trivial / Explicit) skips Wave 1, so it MUST still write a spec file before planning: a short but complete statement of the goal, the acceptance criteria as given, and any constraints — taken from the user's request, not invented. Never start Wave 2 with `.mugiwara/spec/` empty: if no spec exists, write one from the request first (the `/mugiwara-plan` command reads this file). The spec is input to Nami, never the plan itself.
+
 ## 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 decision log so the harness stays coherent. Direct calls do not skip check-ins.
@@ -48,6 +61,10 @@ By mode (per `mugiwara-mode`): `guided` checks in with the user as today; `semi`
 
 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 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.
@@ -64,7 +81,21 @@ Recognize the in-session phrase `mugiwara mode <guided|semi|auto>`: write the pr
 
 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.
 
-Terminal step (every 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 copy-paste PR description block) → hand the branch + verdict file to the user, who opens the PR. The crew never creates a PR, never merges, never deploys. On push failure (no auth / no remote), fall back to the local closure report and log the reason. Never auto-react to review comments or CI in any mode.
+### 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 embody memory-keeper inline to append this mission's lessons to `.mugiwara/logs/lessons.md` — one row per real lesson, append-only, never overwrite.