@ionivetech/mugiwara 0.1.2 → 0.2.0

package/docs/copilot-setup.md

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

package/docs/cursor-setup.md

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

package/docs/developer-onboarding.md

@@ -0,0 +1,85 @@
+# Developer Onboarding
+
+Set up, validate, and contribute to the mugiwara repo.
+
+## Requirements
+
+| Dependency | Required for | Version |
+|------------|--------------|---------|
+| Node.js | running the CLI and the built artifact | >= 20.11 |
+| Bun | building from source, running tests | optional (preferred) |
+
+```bash
+bun install
+```
+
+## Repo layout
+
+```
+mugiwara/
+├── content/            # single source of truth: skills/ + agents/ markdown
+├── agents/             # synced copy of content/agents (plugin copies at repo root)
+├── skills/             # synced copy of content/skills
+├── src/                # CLI, installer, targets, frontmatter parser
+├── scripts/            # validate-content, sync-version, run-evals, install scripts
+├── test/               # vitest suite
+├── .opencode/plugins/  # opencode plugin (registers crew at config load)
+├── .claude-plugin/     # Claude Code marketplace + sync.sh
+└── docs/               # these docs
+```
+
+## The source of truth
+
+`content/` is canonical. The repo-root `agents/` and `skills/` copies are
+generated for harnesses that read the repo directly:
+
+```bash
+sh .claude-plugin/sync.sh
+```
+
+Always edit `content/`, then sync. `bun run validate --check-sync` fails if the
+copies drift.
+
+## Validation
+
+```bash
+bun run validate                # 25 skills + 15 agents: names, descriptions, line limits
+bun run validate --check-sync   # plugin copies match content/
+bun run typecheck               # tsc --noEmit
+bun run test                    # vitest (43 tests)
+```
+
+## Editing a skill or agent
+
+1. Edit `content/skills/<name>/SKILL.md` or `content/agents/<name>.md`.
+2. Respect the house style (see [skill-anatomy.md](skill-anatomy.md) and
+   [agent-anatomy.md](agent-anatomy.md)): evidence over claims, exact commands,
+   red flags, ≤120-line skill bodies.
+3. `sh .claude-plugin/sync.sh`
+4. `bun run validate && bun run typecheck && bun run test`
+
+## Adding a new skill or agent
+
+1. Create the content file following the anatomy docs.
+2. If it's an agent, list its held skills in frontmatter; give it a
+   `description` ≥20 chars.
+3. If it's a skill, pick a folder name that matches `name`; description 20–500
+   chars; body ≤120 lines.
+4. Update the crew/technique tables in `README.md` and the docs (`agents.md`,
+   `skills.md`).
+5. Sync + validate + test.
+
+## Building and publishing
+
+```bash
+bun run build          # dist/mugiwara.js
+bun run sync-version   # sync version from package.json into manifests
+bun prepack            # build + sync-version
+```
+
+Version numbers in the manifests sync from `package.json` via `sync-version`
+(runs automatically on publish).
+
+## Contributing
+
+Open an issue or pull request on GitHub: <https://github.com/ionivetech/mugiwara>.

package/docs/execution-model.md

@@ -0,0 +1,59 @@
+# Execution Model
+
+Why the crew runs in your main conversation — and when subagents are actually
+used.
+
+## Inline by default
+
+The crew runs **inline**. The main thread embodies each crew role using that
+member's skill, so every wave plays out in your main conversation and you watch
+it happen:
+
+- Luffy's triage, Nami's planning, Zoro's execution, Chopper's audit, Sanji's
+  quality, Franky's gates, Robin/Jinbe's review, Brook's healing, Luffy's
+  closure — all performed in the main thread.
+- Evidence is written to `.mugiwara/` files; the conversation carries terse
+  verdicts and evidence pointers.
+
+## When subagents ARE used
+
+Subagents exist to parallelize, never to hide work:
+
+1. **`[PARALLEL]` task batches** — independent tasks that touch no shared files
+   or interfaces run concurrently, one per worker subagent. This is the only
+   place Zoro delegates.
+2. **Parallel fixes** — Brook spawns workers for independent heal fixes.
+3. **Background / long-running checks** — work that would stall the
+   conversation.
+4. **Check subagents** — Chopper, Robin, and Jinbe may spawn subagents for
+   independent re-runs or diff passes.
+
+Worker results return as reports; the main thread summarizes them inline with
+evidence pointers.
+
+## Why not dispatch every wave to a subagent?
+
+Every harness — Claude Code, opencode, Codex, Cursor, Gemini — hides subagent
+internals behind a click or a side panel. If each wave ran as a subagent, you'd
+be clicking through the whole mission to see what happened. Running the crew in
+the main conversation is the only way the process is genuinely visible.
+
+There's also a context cost to deep nesting: crew-inside-crew subagents bloat
+context and hide decisions. Inline keeps the user in the loop and the story
+linear.
+
+## Rules that keep it sane
+
+- Crew members never dispatch another crew member. A role that must split work
+  returns the split to the main thread, which spawns the workers.
+- Escalation = "blocked" + ledger row returned to the main thread.
+- Sequential work never takes a subagent round-trip — no skipping, no hidden
+  reordering, plan order is plan order.
+
+## Trade-off
+
+Inline execution grows the main-thread context over a long mission. The crew
+mitigates this: evidence goes to `.mugiwara/` files, reports are terse, and
+subagents isolate the genuinely heavy parallel work. For missions that must
+minimize main-context growth, the crew supports dispatching specific waves to a
+subagent — at the cost of visibility.

package/docs/gemini-setup.md

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

package/docs/getting-started.md

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

package/docs/git-strategy.md

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

package/docs/index.md

@@ -0,0 +1,45 @@
+# Mugiwara Docs
+
+The Straw Hat crew of AI agents and skills. These docs cover what the crew is,
+how to adopt it, and how each harness installs it. The crew is pure markdown —
+no runtime, no daemons, nothing to host.
+
+## Start here
+
+| Doc | What it covers |
+|-----|----------------|
+| [Getting started](getting-started.md) | Install, first mission, what you see in the chat |
+| [Adoption guide](adoption-guide.md) | Pick the harness, pick the mode, fit the crew to your workflow |
+| [Modes](modes.md) | guided / semi / auto — the autonomy levels, what each asks you |
+| [The crew](agents.md) | All 15 agents and when to summon each |
+| [The techniques](skills.md) | All 25 skills and what each enforces |
+| [The wave pipeline](workflow.md) | How a mission flows Wave 0 → Wave 9 |
+| [Execution model](execution-model.md) | Inline-by-default: why the crew runs in your main conversation |
+| [Git discipline](git-strategy.md) | Commits, branches, save-points — and why the executor commits |
+
+## Install by harness
+
+| Harness | Guide |
+|---------|-------|
+| Claude Code | [claude-setup.md](claude-setup.md) |
+| opencode | [opencode-setup.md](opencode-setup.md) |
+| GitHub Copilot | [copilot-setup.md](copilot-setup.md) |
+| Gemini CLI | [gemini-setup.md](gemini-setup.md) |
+| Codex | [codex-setup.md](codex-setup.md) |
+| Cursor | [cursor-setup.md](cursor-setup.md) |
+| Windsurf | [windsurf-setup.md](windsurf-setup.md) |
+| Cline / Kilo / Antigravity | [rule-based-setup.md](rule-based-setup.md) |
+
+## Reference
+
+| Doc | What it covers |
+|-----|----------------|
+| [Skill anatomy](skill-anatomy.md) | How a mugiwara skill file is structured |
+| [Agent anatomy](agent-anatomy.md) | How a mugiwara agent file is structured |
+| [Developer onboarding](developer-onboarding.md) | Repo layout, validation, tests, contributing |
+
+## Resources
+
+- GitHub: <https://github.com/ionivetech/mugiwara>
+- npm: <https://www.npmjs.com/package/@ionivetech/mugiwara>
+- License: MIT

package/docs/modes.md

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

package/docs/opencode-setup.md

@@ -0,0 +1,47 @@
+# opencode Setup
+
+opencode is a fully supported target — native skills + agents via the opencode
+plugin.
+
+## Install via the plugin
+
+Add to `opencode.json`:
+
+```json
+{ "plugin": ["@ionivetech/mugiwara"] }
+```
+
+Or from the git repo directly:
+
+```json
+{ "plugin": ["mugiwara@git+https://github.com/ionivetech/mugiwara.git"] }
+```
+
+## Install via CLI
+
+```bash
+# global install
+npx @ionivetech/mugiwara@latest --global --target opencode --yes
+
+# project install
+npx @ionivetech/mugiwara@latest --project ./my-app --target opencode --yes
+```
+
+## What you get
+
+- 25 skills in `.opencode/skills/` (project) or `~/.config/opencode/skills/`
+  (global).
+- 15 agents registered as subagents via the plugin.
+- The plugin announces the crew at session start and injects the inline
+  execution model into the system prompt.
+
+## Use it
+
+```
+> use mugiwara
+> add dark mode to the settings page
+```
+
+Restart opencode after installing — config is loaded once at startup. The crew
+runs inline in your main conversation; subagents only for `[PARALLEL]` batches
+and background checks. You never need to click into a subagent to see progress.

package/docs/rule-based-setup.md

@@ -0,0 +1,31 @@
+# Rule-Based Targets: Cline, Kilo, Antigravity, pi, Kimi
+
+These targets install the crew as markdown rule files your tool picks up from a
+conventions directory. Skills-only — the crew pipeline runs through the rules.
+
+## Install
+
+```bash
+# all rule-based targets in one go
+npx @ionivetech/mugiwara@latest --project ./my-app --target cline,kilo,antigravity --yes
+```
+
+| Harness | Target id | Installs as |
+|---------|-----------|-------------|
+| Cline | `cline` | Rules in `.clinerules` |
+| Kilo Code | `kilo` | Rules in `.kilo/rules` + `kilo.jsonc` pointer |
+| Antigravity | `antigravity` | Rules in `.agents/rules` |
+
+## pi and Kimi
+
+- **pi** — `pi install git:github.com/ionivetech/mugiwara` (declared via the
+  `"pi"` key in `package.json`).
+- **Kimi Code** — `/plugins install https://github.com/ionivetech/mugiwara`
+  (`.kimi-plugin/plugin.json`).
+
+## Notes
+
+All rule-based targets are **project-only** — skipped (with a note) on
+`--global` installs. Targets with a bootstrap file (Gemini, Codex, Kilo) create
+it if absent and otherwise tell you the line to add, so your tool points at the
+crew.

package/docs/skill-anatomy.md

@@ -0,0 +1,73 @@
+# Skill Anatomy
+
+Every mugiwara skill is a single portable `SKILL.md` file. No code, no runtime —
+just frontmatter plus a playbook the agent follows. This is the format skills
+ship in for Claude Code, opencode, Copilot, Cursor, Gemini, and 70+ other tools
+via the agentskills.io layout.
+
+## File structure
+
+```
+skills/<skill-name>/SKILL.md
+```
+
+```markdown
+---
+name: mugiwara-checkpoint
+description: Use after an execution wave to audit results against the plan. Runs every acceptance criterion as a command or file inspect, verifies commit hygiene and parallel-file safety, classifies failures honestly, appends ledger rows, and issues a Definition-of-Done verdict. Auditor only - never fixes code.
+---
+
+# Checkpoint (Chopper)
+
+<playbook body>
+```
+
+## Frontmatter
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name` | yes | lowercase, hyphen-separated, matches the folder name, ≤64 chars |
+| `description` | yes | 20–500 chars; what it does AND when to trigger. Front-load the trigger keywords. Skills without a description are filtered out. |
+| `license`, `compatibility`, `metadata` | no | optional extras |
+
+## The playbook body
+
+The body is the actual behavior. Well-formed mugiwara skills follow a house
+style:
+
+1. **Title + one-line identity** — `# Checkpoint (Chopper)`, then what the role
+   is and is not.
+2. **The protocol** — numbered steps, exact commands, exact file paths.
+3. **Decision tables** — where a judgment is needed, a table of signal → action.
+4. **The iron law** — one memorable line that states the non-negotiable
+   ("TRUST NOTHING; VERIFY EVERYTHING").
+5. **Common rationalizations** — the excuses to reject, and the correct reply.
+6. **Red flags** — conditions that mean "stop, this isn't done," each ending
+   with what to do.
+
+### Style rules that keep skills effective
+
+- **Evidence over claims.** A skill says what to run, never what to assume.
+- **Concrete, never aspirational.** Exact paths, exact commands; "works
+  correctly" is banned as an acceptance criterion.
+- **Boundaries are explicit.** Auditor skills say "never edit code"; executor
+  skills say "never report done without command output."
+- **≤120 lines.** Skills that grow past that get split, not stretched.
+
+## How skills reference each other
+
+Skills cross-reference by name: an agent's frontmatter lists its held skills
+(`skills: mugiwara-checkpoint`), and skills defer to each other (e.g.
+`mugiwara-quality` defers to `mugiwara-mode` for the consent contract). Content
+is the single source of truth; harnesses copy it verbatim.
+
+## Validation
+
+Every skill is validated on check-in: name matches folder, description 20–500
+chars, body ≤120 lines, no duplicate names. Run:
+
+```bash
+bun run validate
+```
+
+See [developer-onboarding.md](developer-onboarding.md).