@ionivetech/mugiwara 0.1.3 → 0.3.0

package/docs/opencode-setup.md

@@ -0,0 +1,54 @@
+# 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
+```
+
+**Update** — bump the package version in the `plugin` array (or `mugiwara update`).
+
+**Uninstall** — remove the entry from the array.
+
+## What you get
+
+- 32 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
+
+The workflow **auto-activates** — at session start the crew is announced, and a
+non-trivial request runs the pipeline by itself. `/using-mugiwara` is an
+optional explicit router if you want to hand-route a mission:
+
+```
+> 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/pr-summary.md

@@ -0,0 +1,54 @@
+# PR summary (closure handoff)
+
+At the end of a mission the crew pushes the branch and **stops** — it never
+creates a PR, in any mode. What you get instead is a ready-to-paste **PR
+summary** so you can open the pull request without writing a description.
+
+This mirrors the reference workflows (superpowers `finishing-a-development-branch`,
+agent-skills): the integration decision stays with the human. Mugiwara's
+addition is that the PR description is already written.
+
+## What happens at the terminal
+
+1. Save-point commit → push the mission branch with plain `git push -u origin <branch>`.
+2. Write `.mugiwara/results/YYYY-MM-DD-<mission>-pr-verdict.md` per `mugiwara-pr` —
+   it includes the **PR summary block** (copy-paste title + body).
+3. Hand the branch + verdict file to you. You open the PR and paste the block.
+
+No `gh` CLI, no PR API calls, no auto-reaction to review comments or CI.
+
+## The PR summary block
+
+The verdict file's PR summary is shaped by `.mugiwara/config` (project) /
+`~/.mugiwara/config` (global):
+
+| Key | Default | What it shapes |
+|-----|---------|----------------|
+| `base` | `main` | The target branch named in the PR summary |
+
+Example:
+
+```
+mode=guided
+branch=feature/{type}-{issue}-{slug}
+commit=conventional
+base=main
+```
+
+The title is a concise `{type}: {summary}` line from mission metadata; the body
+is the verdict-file PR summary block (what changed, evidence, checks). The
+summary is **material, never posted** — the crew's job ends at push.
+
+## Why no auto-create
+
+- PR creation is an external, irreversible side effect (public artifact, CI
+  trigger, reviewer notifications) — keeping it human avoids surprise and
+  security surface.
+- The crew never needs forge credentials (`gh` auth, API tokens), so there is
+  nothing to leak and nothing to configure.
+- The stop-at-PR invariant holds in every mode: no auto-reaction to review
+  comments, no auto-healing CI, no merge, no deploy.
+
+See [`mugiwara-pr`](../content/skills/mugiwara-pr/SKILL.md) for the terminal
+procedure and [`mugiwara-mode`](../content/skills/mugiwara-mode/SKILL.md) for
+the mode contract.

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,78 @@
+# 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
+skills/<skill-name>/references/<topic>.md   # optional: overflow detail, linked from the body
+```
+
+```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.
+- **Progressive disclosure.** Keep the trigger-scannable description and the
+  decision tree in the body; when a section exceeds roughly 15–20 lines, move
+  the detail to a `references/<topic>.md` file and drop a one-line pointer in
+  the body saying what to read and why.
+
+## 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).

package/docs/skills.md

@@ -0,0 +1,73 @@
+# The Techniques — 32 Skills
+
+Each skill is a portable markdown playbook — the "how to" the crew follows when
+it embodies a role. Skills are the actual content; agents are the personas.
+
+## Core pipeline
+
+| Skill | Enforces |
+|-------|----------|
+| `mugiwara-workflow` | The harness entry point: inline execution model, gateway triage, wave pipeline, workspace layout, blocker protocol, cleanup |
+| `mugiwara-orchestration` | Luffy's captain behavior: 5-way classifier, check-ins, work splitting, decision log, closure |
+| `mugiwara-brainstorm` | Usopp's critical sparring: interrogate, research facts, cut over-engineering, recommend |
+| `mugiwara-planning` | Interview-first, full-context scan, wave plans with parallel/sequential markers + anti-patterns |
+| `mugiwara-execution` | Todo list, sequential tasks inline + parallel worker batches, 6-field delegation for parallel work, one commit per logical task |
+| `mugiwara-checkpoint` | Verify-everything audit — deduped and scoped to the wave's diff; failure rows to the blocker ledger |
+| `mugiwara-quality` | Discover the project's real tooling; formatter, linter, unit tests under the consent matrix |
+| `mugiwara-gates` | Coverage ≥90% new / ≥80% modified, build validation, Definition of Done |
+| `mugiwara-review` | Doubt-driven review: breaking-change analysis, five-axis, severity-tagged findings |
+| `mugiwara-security` | STRIDE-first security review, OWASP Top 10 mapping, authn/authz, secrets, dependency audit, untrusted-data doctrine |
+| `mugiwara-healing` | Reads the ledger, Stop-the-Line + Prove-It root-cause fixes, rollback prep |
+
+## Mission control
+
+| Skill | Enforces |
+|-------|----------|
+| `mugiwara-mode` | Runtime levels guided / semi / auto: mode owns autonomy, config owns writing standards, consent invariants, gated auto-GO, push + ready-PR terminal |
+| `mugiwara-git` | Atomic commits, save-points, multi-commit splitting, bisect/blame debugging |
+| `mugiwara-testcases` | User-test intake (ATDD): immutable-gold rule, declarative-AC routing, consent, failure adjudication |
+| `mugiwara-pr` | Terminal: push + verdict file with a ready PR summary block; never creates a PR, stop-at-PR invariant |
+| `mugiwara-ship` | GO/NO-GO ship gate: pre-launch checklist, feature flags, rollback plan |
+| `mugiwara-deprecation` | Sunset & migration discipline: keep-or-retire gate, cutover playbooks, safe schema changes |
+| `mugiwara-resume` | Session resume: rebuild state from `.mugiwara/` after compaction/loss; never restart |
+| `mugiwara-lessons` | Cross-mission memory: actionable lessons ledger, read at triage, written at closure |
+| `mugiwara-observability` | Trace the crew: structured logs, OTel-compatible spans, session correlation, end-of-mission summary |
+
+## Engineering practice
+
+| Skill | Enforces |
+|-------|----------|
+| `mugiwara-writing-skills` | Meta-skill: how mugiwara authors skills — anatomy, ≤120-line rule, progressive disclosure, anti-rationalization |
+| `mugiwara-systematic-debugging` | 4-phase root-cause discipline: reproduce → localize → reduce → fix + guard; stop-the-line, prove-it first |
+| `mugiwara-test-driven-development` | RED-GREEN-REFACTOR, proof-of-when, test pyramid, one test = one behavior |
+| `mugiwara-api-and-interface-design` | Contract-first design, error semantics, boundary validation, backward compatibility, versioning |
+| `mugiwara-doubt-driven-development` | Adversarial fresh-context verification of in-flight decisions: claim → extract → doubt → reconcile → stop |
+| `mugiwara-git-worktrees` | Isolated parallel branches via `git worktree`, branch hygiene, safe cleanup |
+| `mugiwara-context-engineering` | Token/context management: feed selectively, trust-sort sources, progressive disclosure, rules files |
+
+## Domain & advanced
+
+| Skill | Enforces |
+|-------|----------|
+| `mugiwara-frontend` | Anti-slop frontend: audit-first redesigns, design-system extraction, slop list |
+| `mugiwara-backend` | Backend/server code: repo standards first, API design, data integrity, error handling, security |
+| `mugiwara-agent-security` | Secure the agent layer: prompt injection, memory poisoning, excessive agency, secrets, sandboxing |
+| `mugiwara-dynamic-workflow` | Runtime workflow patterns: fan-out-and-synthesize, tournament, loop-until-done, classify-and-act |
+| `mugiwara-eval` | Test the harness itself: task suites, judge-agent rubric comparison, pass/fail per case |
+
+## Anatomy of a skill
+
+Every skill is a single `SKILL.md` with frontmatter + a playbook body:
+
+```markdown
+---
+name: mugiwara-checkpoint
+description: Use after an execution wave to audit results against the plan. ...
+---
+
+# Checkpoint (Chopper)
+
+<playbook: protocol, rules, red flags, iron law>
+```
+
+See [skill-anatomy.md](skill-anatomy.md) for the details.

package/docs/windsurf-setup.md

@@ -0,0 +1,18 @@
+# Windsurf Setup
+
+## Install
+
+```bash
+npx @ionivetech/mugiwara@latest --project ./my-app --target windsurf --yes
+```
+
+**Update** — `mugiwara update`. **Uninstall** — `mugiwara uninstall`.
+
+## What you get
+
+- 32 skills as rules files in `.devin/rules`.
+
+## Notes
+
+Windsurf is a **project-only** target. Skills-only — the crew pipeline runs
+through the rule files.

package/docs/workflow.md

@@ -0,0 +1,80 @@
+# The Wave Pipeline
+
+A mission runs as ten waves (plus one optional adversarial pass). Each wave is
+owned by one crew member and runs **inline** in the main conversation.
+
+| Wave | Owner | Skill | Output |
+|------|-------|-------|--------|
+| 0 Triage | Luffy | `mugiwara-orchestration` | 5-way route decision + reason |
+| 1 Brainstorm | Usopp | `mugiwara-brainstorm` | refined direction, options, recommendation |
+| 2 Planning | Nami | `mugiwara-planning` | plan doc: waves, tasks, acceptance criteria |
+| 3 Execution | Zoro | `mugiwara-execution` | implemented tasks with evidence |
+| 4 Checkpoint | Chopper | `mugiwara-checkpoint` | audit report + failure ledger |
+| 4.5 Adversarial | Skeptic | `mugiwara-dynamic-workflow` | findings report (optional) |
+| 5 Quality | Sanji | `mugiwara-quality` | formatter/linter/test results |
+| 6 Gates | Franky | `mugiwara-gates` | coverage + build verdict |
+| 7 Review | Robin ∥ Jinbe | `mugiwara-review` + `mugiwara-security` | severity-tagged findings |
+| 8 Healing | Brook | `mugiwara-healing` | fixes; loops back to Wave 4, max 3 cycles |
+| 9 Closure | Luffy | `mugiwara-orchestration` | closure report + push + PR verdict handed to you |
+
+## Wave 0 — Triage
+
+Every mission starts at the Luffy gateway, which classifies the request 5 ways:
+
+| Class | Signal | Route |
+|-------|--------|-------|
+| Trivial | one obvious small change, no ambiguity | Wave 2 directly |
+| Explicit | clear requirements, written spec exists | Wave 2 directly |
+| Exploratory | needs direction, options, research | Wave 1 first |
+| Open-ended | broad goal, undefined scope | Wave 1 first |
+| Ambiguous | requirements, APIs, scope unclear | Wave 1 first |
+
+The decision + reason is logged in `.mugiwara/logs/`. Risk (money/security/
+data/public API) always triggers the full pipeline.
+
+## Wave 4 — Checkpoint (Chopper)
+
+The verify-everything gate. After execution, Chopper re-runs every acceptance
+criterion — but efficiently:
+
+- **Deduped**: each unique check command runs once per wave, scoped to the
+  files this wave changed. No running `npm test` once per task.
+- **Scoped by diff**: `git diff --name-only <wave-base>..HEAD` decides what
+  actually needs re-verification.
+- **Commit hygiene**: one `git log --stat` pass, not per-commit.
+- Failures land in the blocker ledger `.mugiwara/issues/` with honest
+  code-vs-env classification.
+
+## Wave 7 — Review
+
+Robin (doubt-driven review) and Jinbe (security) run in parallel. Robin maps
+breaking changes to callers before reading the diff; Jinbe runs STRIDE + OWASP.
+Findings are severity-tagged with path:line.
+
+## Wave 8 — Healing
+
+Brook reads the blocker ledger and fixes root causes, proving each fix by
+re-running the failed check. The loop returns to Wave 4 — max 3 cycles, then
+escalation to you.
+
+## Wave 9 — Closure
+
+Luffy runs the ship gate, writes the closure report, deletes superseded
+intermediate files, then the terminal step in every mode: **save-point commit →
+push the mission branch → write the PR verdict file → hand branch + verdict to
+you**, who opens the PR. The crew never creates a PR, merges, or deploys.
+
+## The two rules that hold it together
+
+1. **Evidence over claims.** No wave passes on assertion — the owning agent
+   runs the checks and shows output. "Subagents lie. No evidence = not
+   complete."
+2. **The plan is the source of truth.** From Wave 2 on, the plan doc in
+   `.mugiwara/plans/` holds the clean execution plan; the decision log holds the
+   who-and-why trace. No wave is skipped without the reason recorded.
+
+## Blocker protocol
+
+Any agent that hits a blocker appends a row
+(`wave | task | symptom | attempted | help-needed`) to the ledger and escalates.
+Never a silent workaround. Brook heals what the ledger lists.

package/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/session-start.ts",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-start.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+// hooks/session-start.ts — SessionStart hook: reminds the agent the crew is available.
+console.log(
+  JSON.stringify({
+    additionalContext:
+      "Mugiwara crew available. The workflow auto-activates for non-trivial requests (no need to call `/using-mugiwara` at session start; it is optional and routes to the right crew member). The crew runs inline in the main thread — Never Task-dispatch a crew member. Subagents only for [PARALLEL] task batches, concurrent review/security, and independent re-run checks. Checkpoint reports at wave/stage boundaries. Mode: guided / semi / auto (see .mugiwara/config). See skills/mugiwara-workflow."
+  })
+);

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@ionivetech/mugiwara",
-  "version": "0.1.3",
-  "description": "The Straw Hat crew of AI agents and skills: brainstorm, plan, execute, checkpoint, quality, gates, review, security, self-healing. Installs into Claude Code, opencode, Copilot, Gemini, Codex, Windsurf, Cline, Kilo, Antigravity.",
+  "version": "0.3.0",
+  "description": "The Straw Hat crew of AI agents and skills: brainstorm, plan, execute, checkpoint, quality, gates, review, security, self-healing. Installs into Claude Code, opencode, Copilot, Gemini, Codex, Cursor, Kimi, pi, Windsurf, Cline, Kilo, Antigravity.",
   "type": "module",
   "license": "MIT",
+  "main": "./.opencode/plugins/mugiwara.mjs",
+  "exports": {
+    ".": "./.opencode/plugins/mugiwara.mjs",
+    "./plugin": "./.opencode/plugins/mugiwara.mjs",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "mugiwara": "dist/mugiwara.js"
   },
@@ -11,11 +17,19 @@
     "dist",
     "src",
     "content",
+    "docs",
+    ".opencode",
+    "hooks",
     "scripts/install.sh",
     "scripts/install.ps1",
     "README.md",
     "LICENSE"
   ],
+  "pi": {
+    "skills": [
+      "./content/skills"
+    ]
+  },
   "engines": {
     "node": ">=20.11"
   },
@@ -35,9 +49,13 @@
     "skills",
     "claude-code",
     "opencode",
+    "opencode-plugin",
     "copilot",
     "gemini",
     "codex",
+    "cursor",
+    "kimi",
+    "pi",
     "windsurf",
     "cline",
     "multi-agent",

package/src/targets/claude.ts

@@ -1,8 +1,13 @@
 // src/targets/claude.ts
-import { join } from 'node:path';
+import { existsSync, readFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { stringifyFrontmatter, type FrontmatterData } from '../frontmatter.ts';
 import type { Target } from '../installer.ts';
 
+const here = dirname(fileURLToPath(import.meta.url));
+const HOOK_SRC = join(here, '..', '..', 'hooks', 'session-start.ts');
+
 export const target: Target = {
   id: 'claude',
   label: 'Claude Code',
@@ -22,4 +27,16 @@ export const target: Target = {
     if (data.tools) fm.tools = data.tools;
     return { relPath: `${data.name}.md`, text: stringifyFrontmatter(fm, body) };
   },
+  postInstall({ scope, projectDir, home, dryRun }) {
+    // Wire the SessionStart hook (inline doctrine) into the installed .claude dir.
+    const root = scope === 'global' ? join(home, '.claude') : join(projectDir, '.claude');
+    const hookFile = join(root, 'hooks', 'session-start.ts');
+    if (dryRun) return { written: [], notes: [] };
+    if (existsSync(HOOK_SRC) && !existsSync(hookFile)) {
+      mkdirSync(dirname(hookFile), { recursive: true });
+      copyFileSync(HOOK_SRC, hookFile);
+      return { written: [hookFile], notes: [] };
+    }
+    return { written: [], notes: [] };
+  },
 };

package/src/targets/codex.ts

@@ -6,5 +6,5 @@ export const target = makeGeneric({
   label: 'Codex',
   rulesDir: '.codex/mugiwara',
   bootstrapFile: 'AGENTS.md',
-  bootstrapPointer: 'Mugiwara crew installed in .codex/mugiwara/ — read .codex/mugiwara/mugiwara-workflow.md to run the pipeline.',
+  bootstrapPointer: 'Mugiwara crew installed in .codex/mugiwara/ — read .codex/mugiwara/mugiwara-workflow.md to run the pipeline inline in the main conversation.',
 });

package/src/targets/gemini.ts

@@ -6,5 +6,5 @@ export const target = makeGeneric({
   label: 'Gemini',
   rulesDir: '.gemini/mugiwara',
   bootstrapFile: 'GEMINI.md',
-  bootstrapPointer: 'Mugiwara crew installed in .gemini/mugiwara/ — read .gemini/mugiwara/mugiwara-workflow.md to run the pipeline.',
+  bootstrapPointer: 'Mugiwara crew installed in .gemini/mugiwara/ — read .gemini/mugiwara/mugiwara-workflow.md to run the pipeline inline in the main conversation.',
 });