@ionivetech/mugiwara 0.2.0 → 0.3.0

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/skill-anatomy.md

@@ -9,6 +9,7 @@ via the agentskills.io layout.
 
 ```
 skills/<skill-name>/SKILL.md
+skills/<skill-name>/references/<topic>.md   # optional: overflow detail, linked from the body
 ```
 
 ```markdown
@@ -53,6 +54,10 @@ style:
 - **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
 

package/docs/skills.md

@@ -1,4 +1,4 @@
-# The Techniques — 25 Skills
+# 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.
@@ -16,22 +16,34 @@ it embodies a role. Skills are the actual content; agents are the personas.
 | `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` | OWASP-driven security review, untrusted-data doctrine, severity by exploitability × impact |
+| `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, consent invariants, gated auto-GO, push + ready-PR terminal |
+| `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` | CI/CD loop terminal: one verdict file + push via plain git; stop-at-PR invariant |
+| `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 |
+| `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
 

package/docs/windsurf-setup.md

@@ -6,9 +6,11 @@
 npx @ionivetech/mugiwara@latest --project ./my-app --target windsurf --yes
 ```
 
+**Update** — `mugiwara update`. **Uninstall** — `mugiwara uninstall`.
+
 ## What you get
 
-- 25 skills as rules files in `.devin/rules`.
+- 32 skills as rules files in `.devin/rules`.
 
 ## Notes
 

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,6 +1,6 @@
 {
   "name": "@ionivetech/mugiwara",
-  "version": "0.2.0",
+  "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",
@@ -19,6 +19,7 @@
     "content",
     "docs",
     ".opencode",
+    "hooks",
     "scripts/install.sh",
     "scripts/install.ps1",
     "README.md",

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.',
 });