@ionivetech/mugiwara 0.4.0 → 0.5.0

package/content/skills/mugiwara-dynamic-workflow/SKILL.md

@@ -1,90 +0,0 @@
----
-name: mugiwara-dynamic-workflow
-description: Use when a mission or subproblem has many independent subtasks, needs comparison, or risks agent bias - pick the right dynamic workflow pattern - fan-out-and-synthesize, tournament, loop-until-done, classify-and-act, generate-and-filter.
----
-
-# Dynamic Workflow Patterns (Luffy)
-
-## Skip when
-
-- One linear pass suffices: <3 independent subtasks, no comparison, no known agent bias.
-- Standard wave pipeline already covers the work without pattern selection.
-
-Six primitives for missions too big or too biased for one linear pass. Choose the pattern BEFORE executing; record the choice in the decision log (.mugiwara/logs/). A mission may chain patterns (e.g. classify, then fan out, then tournament the outputs).
-
-## Classify-and-act
-
-1. Sort inputs into intent categories first, THEN route each category to its handler.
-2. Never act before classifying — Luffy's Wave 0 triage is this pattern applied to the mission.
-3. Unknown category → hold for judgment; never guess-assign.
-
-## Fan-out-and-synthesize
-
-1. Split work into independent tasks; run each in a parallel worker subagent (this is the one case that legitimately dispatches — parallel batches, never sequential work).
-2. Prove disjointness first: each task touches distinct files or interfaces. No shared writes, no shared state.
-3. A synthesizer merges results into ONE output with source attribution per part.
-4. Conflicts resolve by evidence (re-run, inspect), never by vote count.
-
-## Tournament / pairwise judgment
-
-1. Ranking or selecting (options, designs, PRs) → compare in PAIRS, not all-at-once.
-2. Fresh judge per match; match verdict only, no absolute scoring.
-3. Winner advances; keep runner-up reasoning in the report.
-4. Counters self-preferential bias: no judge argues for its own entry.
-
-## Loop-until-done
-
-1. Repeat one unit until a stopping criterion with evidence: test pass, threshold reached, user sign-off.
-2. Bound the loop: max N (default 3). Exceeding N → escalate, never loop forever.
-3. Record every iteration's evidence in `.mugiwara/results/`.
-
-## Generate-and-filter
-
-1. Produce many candidates first — no filtering during generation.
-2. Filter against HARD constraints, then rank survivors.
-3. Never filter before generating; never rank on soft preference before hard constraints.
-
-## Adversarial verification
-
-1. Every output gets a skeptic pass (dispatch `skeptic-verifier`): find what is wrong, do NOT validate.
-2. Counters agentic laziness, self-preferential bias, goal drift.
-3. Findings classified; loop bounded at 3 cycles.
-
-## Selection guide
-
-- One route, unknown intent → classify-and-act
-- Many independent tasks, merge later → fan-out-and-synthesize
-- Rank or select among peers → tournament
-- Repetition with a stopping rule → loop-until-done
-- Many candidates, hard bar → generate-and-filter
-- Any high-stakes output about to ship → adversarial verification
-
-## Failure modes fixed
-
-- Agentic laziness: generate-and-filter + adversarial verification
-- Self-preferential bias: tournament + adversarial verification
-- Goal drift: loop bounds + adversarial verification
-- Conflated judgments / order effects: tournament pairs
-- Premature filtering / culled solutions: generate-and-filter
-
-## Pattern table
-
-| Pattern | Use when | Output |
-|---------|----------|--------|
-| classify-and-act | intent unknown, routes diverse | category → handler map + actions |
-| fan-out-and-synthesize | independent subtasks | one merged output, source-attributed |
-| tournament | rank / select peers | champion + runner-up reasoning |
-| loop-until-done | repeat until criterion | iterations + final evidence |
-| generate-and-filter | candidates + hard bar | ranked survivors |
-| adversarial verification | output / verdict ships | findings report, bounded |
-
-## Red flags
-
-- Fan-out without a disjointness proof.
-- A synthesizer merging by vote instead of evidence.
-- A judge scoring absolutely instead of pairwise.
-- An unbounded loop.
-- Filtering before generating.
-- A skeptic pass that "validates" instead of doubting.
-
-All mean: stop, re-pick the pattern, record the change in the decision log.

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

@@ -1,87 +0,0 @@
----
-name: mugiwara-eval
-description: Use when verifying that a mugiwara skill, agent, or the whole crew actually works - write a task suite, run it with a judge agent, rubric-compare, and report pass/fail per case.
----
-
-# Eval (Self-Test)
-
-## Skip when
-
-- No skill, agent, or crew behavior changed — pure docs, installer, or packaging.
-- Change is a version bump or manifest edit with zero behavioral delta.
-
-Skills rot silently. A skill that was never tested is a claim, not a capability. This is the harness's own test harness: write a task suite, run each case, score with a fresh judge against a rubric, report pass/fail.
-
-## Why
-
-- Skill instructions drift from what agents actually do when followed.
-- Untested means unverified: "it reads fine" is not "it works".
-- The eval is the contract; the skill bends to it, never the reverse.
-
-## Task suite format
-
-One case per skill-behavior at `evals/cases/<skill>-<case>.json`:
-
-```json
-{
-  "name": "rubric-threshold-honesty",
-  "skill": "mugiwara-eval",
-  "task": "The prompt to run through the skill's workflow.",
-  "fixtures": ["evals/cases/fixtures/plan.md"],
-  "rubric": ["a pass threshold is stated before scoring", "a pass needs explicit evidence"],
-  "expected": "What pass looks like: all rubric items met, each with evidence."
-}
-```
-
-- `name` unique per suite; `skill` matches the skill directory name.
-- `task` is the prompt run as-is — no extra guidance bolted on.
-- `rubric` = checked items; `expected` = the shape of a pass. `fixtures` optional, repo-relative paths.
-
-## Judge-agent protocol
-
-Rubric comparison, not gold-answer matching (SWE-bench-style suites + rubric judges):
-
-1. Run the case: host executes `task` with the skill under test loaded.
-2. Dispatch a FRESH judge — never the implementer. Counters self-preferential bias.
-3. Judge scores each `rubric` item pass/fail with evidence; no absolute scores.
-4. Compare against the rubric's explicit pass threshold (all items, or ≥ N with none critical).
-5. Ranking or selection → pairwise/tournament judging (`mugiwara-dynamic-workflow`), not all-at-once.
-
-## Loop
-
-run → judge → fail → fix the SKILL (never the eval) → re-run.
-
-1. Write cases before trusting a skill or changing it.
-2. Run the suite; judge honestly.
-3. A failing case means the skill's instructions are wrong or incomplete. Fix the skill.
-4. A passing case gives no license to change the skill casually — re-run on change.
-5. Never weaken the eval to clear a failure; that falsifies the test.
-
-## Bound
-
-- Run the suite per release and on every skill change.
-- Report a pass/fail table to `.mugiwara/results/<mission>-eval.md`: case, judge, verdict, evidence, threshold.
-- Failing cases → rows in `.mugiwara/issues/YYYY-MM-DD-<mission>-blockers.md` (category `eval-fail`).
-- Keep the suite in sync with the skill dirs: at minimum one case per skill.
-
-## Scope
-
-Test the SKILL, not the host agent. Host behavior is the host's problem. The eval checks that the skill's instructions, when followed, produce the intended workflow. Never assert on agent behavior, model quirks, or tooling the skill does not own.
-
-## Common rationalizations
-
-- "I wrote it, it must work." → Fresh judge, always.
-- "The case passed last release." → Re-run; skills drift between runs.
-- "The eval is too strict." → Tighten the skill, never the rubric.
-- "It's an agent problem." → If following the skill causes it, it's the skill's.
-
-## Red flags
-
-- The implementer judging its own case's skill.
-- A rubric with no pass threshold.
-- A case whose `task` leaks the expected answer.
-- Fixing the eval instead of the skill to clear a failure.
-- A suite run with no pass/fail report written.
-- A suite that no longer matches the skill's current behavior.
-
-All mean: the run is not a valid check. Stop, re-run with a fresh judge, write the report.

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

@@ -1,67 +0,0 @@
----
-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-mode/SKILL.md

@@ -1,77 +0,0 @@
----
-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)
-
-## 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
-
-| 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-observability/SKILL.md

@@ -1,59 +0,0 @@
----
-name: mugiwara-observability
-description: Use when instrumenting, tracing, or debugging how the mugiwara crew ran a mission - structured logs, OTel-compatible trace spans per wave/agent/tool, session correlation, and reading the traces to find where time and errors went.
----
-
-# 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
-
-Per mission, maintain `.mugiwara/results/YYYY-MM-DD-<mission>-trace.md` (fall back to the repo's log convention if `.mugiwara/` is absent). Append one entry per wave and per agent dispatch:
-
-- `event`: wave | agent | tool called | start/end time | duration ms | outcome (pass/fail/blocked) | evidence pointer | error excerpt.
-
-## Structured log lines
-
-Each event is one parseable line, ISO timestamps, no PII:
-
-```
-2026-08-10T09:14:02Z [wave:3][agent:zoro][tool:subagent][ms:1240][ok] task-2.1 helper theme
-2026-08-10T09:16:40Z [wave:3][agent:brook][tool:test][ms:9800][fail] e2e auth regressed — see .mugiwara/issues/2026-08-10-mission-blockers.md:7
-```
-
-Always include outcome; an event without an outcome is noise, not a trace.
-
-## OTel-aware enrichment
-
-If the host agent supports OTel GenAI spans, map each entry: `gen_ai.agent.*` for dispatches, `gen_ai.tool.*` for tool calls, span duration = entry duration; propagate trace context (`traceparent`) via MCP `_meta` when the tool is an MCP server. Recommend Langfuse or LangSmith as the viewer for spans/agent graphs. The FILE trace stays the source of truth — OTel is optional enrichment, never a replacement.
-
-## Session correlation
-
-Every entry carries the mission id `YYYY-MM-DD-<mission>` (same name as the plan doc). The id threads through trace, blockers ledger, and results so a full run can be replayed even after context compaction — grep the id across `.mugiwara/` to reconstruct the whole mission.
-
-## Reading traces to debug
-
-- Time: sort spans by duration — the longest spans are the wave/agent/tool to fix or parallelize.
-- Errors: cluster `fail`/`blocked` entries by agent/task — repeated failure at one spot is a plan or skill bug, not a one-off.
-- Utilization: which agents ran vs. never dispatched (over/under-use), heal-loop cost = sum of `[heal]` wave spans.
-- Fix the plan/skill, not the symptom: the trace tells you where, the plan tells you why.
-
-## End-of-mission summary
-
-Close the trace file with a mini report: total duration, waves run, agents used, failures, heal cycles, longest span. This is the closure evidence for the ship gate.
-
-## Red flags
-
-- Events without timestamps, duration, or outcome.
-- Entries missing the mission id.
-- PII in log lines.
-- Trace file absent at closure while waves ran.
-- Heal cycles with no trace of which failure they retried.
-
-All mean: the run is not reconstructable. Stop and record before moving on.

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

@@ -1,65 +0,0 @@
----
-name: mugiwara-writing-skills
-description: Use when authoring a new mugiwara skill or revising an existing one. Enforces the skill anatomy (name/description 20-500 chars, when-to-use, process, rationalizations, red flags, verification), the 120-line body ceiling, and progressive disclosure of detail into a references/ file. Meta-skill: governs the other skills.
----
-
-# Writing Mugiwara Skills
-
-## Skip when
-
-- Not authoring or revising a mugiwara skill — plain application code change.
-- Skill change is a one-line description fix with no anatomy impact.
-
-A skill is a process workflow the agent runs on cue, not a reference guide. If it reads like a wiki page, it fails. The description decides when the skill loads; the body decides what happens next. Both must justify their size.
-
-## Skill anatomy
-
-Every skill is a single `SKILL.md` at `content/skills/<name>/`, plus an optional `references/` folder for pulled-out detail. The name is the directory name; the validator checks that exact match.
-
-| Part | Requirement |
-|------|-------------|
-| name | equals the directory name, `mugiwara-<domain>` |
-| description | one "Use when..." sentence, 20-500 chars, loads the right skill and rejects the wrong ones |
-| body | `# title` + sections below, 120 lines max |
-| references/ | overflow detail, linked from the body |
-
-## When to use
-
-Use this skill the moment you start authoring a new skill file or restructuring an existing one. Skip it only for edits so small they cannot touch anatomy, limits, or wording.
-
-## Process
-
-1. **Confirm the niche.** Grep `content/skills/` for overlap; a new skill must not duplicate an existing one. Name it `mugiwara-<domain>`.
-2. **Write the description first.** One "Use when..." sentence naming the trigger, the behavior, and the boundary of what the skill is not for. Target 60-120 chars; the 500-char cap is a ceiling, not a goal.
-3. **Draft the body as a workflow.** Concrete numbered steps the agent executes, in order, with decisions and branches embedded. Name the skills it reads or dispatches. Use tables for excusable patterns and quick comparisons.
-4. **Cut to the ceiling.** Body must end at 120 lines or fewer. Section-by-section trim: merge subsections, kill throat-clearing, convert prose to tables. `ponytail` and `caveman` instincts apply — the body is command output, not a report.
-5. **Disclose progressively.** If a section exceeds roughly 15-20 lines, move it to `references/<topic>.md`, drop a one-line pointer in the body, and keep the pointer actionable (what to read and why).
-6. **Check the anatomy list.** Each required section present, in order: title, When to use, Process, Rationalizations, Red flags, Verification.
-7. **Validate.** Run `bun scripts/validate-content.ts --check content/skills/<name>/SKILL.md` and leave it exiting 0.
-
-## Rationalizations
-
-| Excuse | Rebuttal |
-|--------|----------|
-| "It's a guide, not a checklist" | A skill the agent cannot execute is decoration. Rewrite every paragraph as a step or a criterion. |
-| "The detail is essential" | Then move it to `references/` and keep the body a decision tree, not a dump. |
-| "More lines mean more coverage" | 120 lines enforce focus. Cover the decision, not the encyclopedia. |
-| "Long description catches more triggers" | A description that matches everything loads on nothing specific and trains the agent to ignore the skill. |
-| "Patterns are the same everywhere, I'll mirror another skill's text" | Wording must be original. Mirror the shape, never the sentences. |
-| "It's fine for now, I'll validate later" | Validation is the last step of the write, not a follow-up task. |
-
-## Red flags
-
-- Body over 120 lines or a description outside 20-500 chars.
-- No "Use when..." trigger sentence, or a description that names no boundary.
-- A section that reads as a lecture instead of steps the agent can run.
-- Required sections missing or out of order.
-- Text copied from another skill, superpowers, or agent-skills.
-- A `references/` file that is unreferenced, or a body so crammed it needed none.
-- An unvalidated file reported as done.
-
-Any of these: revise the skill, re-run validation, and confirm both before reporting.
-
-## Verification
-
-Evidence of a complete skill: the file passes `--check` with exit 0; `wc -l` on the body is at or under 120; the description triggers only its intended cases; every required section is present and original; and any overflow sits in a linked `references/` file.