@ionivetech/mugiwara 0.3.0 → 0.4.0

package/docs/enforcement.md

@@ -0,0 +1,38 @@
+# Enforcement
+
+A markdown harness cannot force a model to comply with prose — that is the
+ceiling of every skills pack, mugiwara included. Mugiwara is a skills pack, not
+a plugin with hooks: it ships markdown the agent reads and follows. What keeps
+the pipeline honest is the skills themselves, not a CLI.
+
+## Skip gates
+
+Every skill carries a `## Skip when` block: ≤4 bullets, numeric thresholds,
+telling the agent when the skill does not apply. The content validator
+(`bun run validate`) fails the build when a skill lacks the block, so the gate
+cannot rot. A skipped skill is recorded in the decision log, never silent.
+
+## Evidence over claims
+
+Every skill enforces the iron law: a wave passes only on command output or a
+file the agent can point at. "Subagents lie. No evidence = not complete." This
+is prose the agent follows, checked by no tool — the honest limit.
+
+## Capability tiers
+
+How skills load differs per harness:
+
+| Tier | Harnesses | Skill loading |
+|------|-----------|---------------|
+| 1 | Claude Code, opencode | progressive — read by trigger, not all at once |
+| 2 | Copilot, Gemini, Codex | bootstrap pointer → the model chooses what to read |
+| 3 | Windsurf, Cline, Kilo, Antigravity | rules dirs glob-load — skills ship as stubs, full bodies in `.mugiwara/refs/` |
+
+On tier 3, skills ship as small stubs (routing + pointer) so glob-loading
+harnesses stop eating ~40k tokens; the full body lives in `.mugiwara/refs/`,
+read on demand. Tier 3 also uses **wave-boundary state flush**: the full
+mission state is written to `.mugiwara/` at each wave so the next wave resumes
+without the previous context — the portable substitute for subagent isolation.
+
+**Honest limit.** Mugiwara cannot force an agent to follow a skill. That is
+true on every tier and every harness. It is a skills pack, not a supervisor.

package/docs/index.md

@@ -1,11 +1,14 @@
 # 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. It ships **15 agents** and **32
-skills**, and the workflow **auto-activates** at session start — a non-trivial
-request runs the pipeline by itself, with `/using-mugiwara` as an optional
-explicit router.
+how to adopt it, and how each harness installs it. The crew is markdown plus a
+small Node CLI (`mugiwara`) — no daemons, nothing to host. It ships **15
+agents** and **32 skills**, and the workflow **auto-activates** at session
+start — a non-trivial request runs the pipeline by itself, with
+`/using-mugiwara` as an optional explicit router. Work is **sized to a lane**
+before it runs: small fixes skip the pipeline, sensitive changes run the full
+nine waves, and every wave passes only on **evidence**, never on a spoken
+claim.
 
 ## Start here
 
@@ -20,6 +23,8 @@ explicit router.
 | [The techniques](skills.md) | All 32 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 |
+| [Lanes & sizing](lanes.md) | How Luffy sizes work at triage: Lane 0–4, escalation, budget |
+| [Enforcement](enforcement.md) | Skip gates, evidence over claims, and capability tiers |
 | [Git discipline](git-strategy.md) | Commits, branches, save-points — and why the executor commits |
 
 ## Install by harness
@@ -41,6 +46,7 @@ explicit router.
 |-----|----------------|
 | [Skill anatomy](skill-anatomy.md) | How a mugiwara skill file is structured |
 | [Agent anatomy](agent-anatomy.md) | How a mugiwara agent file is structured |
+| [Troubleshooting](troubleshooting.md) | Common problems and how to fix them |
 | [Developer onboarding](developer-onboarding.md) | Repo layout, validation, tests, contributing |
 
 ## Resources

package/docs/lanes.md

@@ -0,0 +1,40 @@
+# Lanes & Sizing
+
+The crew sizes a mission before it runs. At Wave 0, Luffy sizes the request
+and picks a lane. The lane decides how many waves run — so a one-file typo does
+not pay for the full nine-wave pipeline.
+
+## The lanes
+
+| Lane | Picks when | Waves | Budget |
+|------|-----------|-------|--------|
+| **0 · Direct** | typo, rename, 1 file <20 LOC | none | ~0 |
+| **1 · Lean** | bug in 1-2 files, <50 LOC | execute → quality | ~4k |
+| **2 · Standard** | feature, 3-8 files | plan → execute → checkpoint → review | ~10k |
+| **3 · Full** | architecture, migration, auth/payment, API | 9 waves | ~20k |
+| **4 · Spike** | exploratory, needs direction | brainstorm → re-triage | ~3k |
+
+Budget is a guidance, not a meter: at ~1.5× estimated tokens warn, at 3× stop,
+write the state to `.mugiwara/` and report how to continue — never silently
+run on.
+
+## How Luffy sizes
+
+Size from the diff:
+
+- 1 file <20 LOC → Lane 0 (Direct).
+- 1-2 files → Lane 1 (Lean).
+- 3-8 files → Lane 2 (Standard).
+- 9+ files, or the diff touches `auth/`, `payment/`, `migrations/`, or
+  `security/` → Lane 3 (Full).
+- Exploratory, needs direction → Lane 4 (Spike).
+
+## Escalation
+
+The lane **escalates when the work outgrows the estimate** — the diff grew, a
+sensitive path got touched mid-mission, or failures repeat. Escalation is
+automatic; a lane **never auto-drops**. Under-process is more expensive than
+over-process.
+
+The lane is decided by Luffy at triage, per mission — it is not stored in
+`.mugiwara/config`.

package/docs/skill-anatomy.md

@@ -38,12 +38,16 @@ 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
+2. **Skip when** — required. ≤4 bullets, numeric threshold, telling the agent
+   when this skill does not apply (e.g. "no UI code touched", "<3 files").
+   Without it the content validator fails the build. A skipped skill is
+   recorded in the decision log, never silent.
+3. **The protocol** — numbered steps, exact commands, exact file paths.
+4. **Decision tables** — where a judgment is needed, a table of signal → action.
+5. **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
+6. **Common rationalizations** — the excuses to reject, and the correct reply.
+7. **Red flags** — conditions that mean "stop, this isn't done," each ending
    with what to do.
 
 ### Style rules that keep skills effective
@@ -69,7 +73,8 @@ 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:
+chars, body ≤120 lines, no duplicate names, and a `## Skip when` block with
+1–4 bullets. Run:
 
 ```bash
 bun run validate

package/docs/troubleshooting.md

@@ -0,0 +1,91 @@
+# Troubleshooting
+
+Common problems, what they mean, and how to fix them.
+
+## Installation
+
+### "conflict (not overwritten; run update to replace with backup)"
+
+The target already has a file that differs from what mugiwara wants to write —
+likely a previous install or a local edit. `mugiwara update` (or `--force`)
+replaces it and backs up the existing file to `.mugiwara/backup/<timestamp>/`
+first.
+
+### `mugiwara install` writes nothing for a target
+
+- **Project scope only.** Rule-based targets (Gemini, Codex, Windsurf, Cline,
+  Kilo, Antigravity) reject `--global`; use `--project <dir>`.
+- **Skill already current.** A rerun skips identical files — check the "skipped
+  N" count in the install output.
+
+### `npx @ionivetech/mugiwara` fails on an old Node
+
+Mugiwara requires **Node.js >= 20.11**. Check `node --version`; upgrade or use
+a version manager (nvm, fnm, volta).
+
+## Mission runtime
+
+### The workflow did not auto-activate
+
+- **Restart the harness.** Claude Code and opencode load config at startup; the
+  announcement runs on session start.
+- **Check the install.** Verify the skills directory exists for your harness
+  (`.claude/skills`, `.opencode/skills`, `.kilo/rules`, …). Reinstall with
+  `mugiwara update`.
+
+### A skill that should fire does not
+
+- **Trigger match.** Skills activate on their `description` — if the request
+  doesn't match, the skill won't load. Rephrase toward the trigger keywords.
+- **Skip gate.** Every skill has a `## Skip when` block. If the change matches a
+  skip condition, the skill correctly stays out of the way — this is by design.
+- **Tier-3 stub.** On rules-dir harnesses, the loaded file is a stub pointing at
+  `.mugiwara/refs/<name>.md`. If the full body is missing, reinstall.
+
+### The crew ran too many / too few waves
+
+Lane routing sizes the mission at Wave 0. If the estimate was wrong, the lane
+escalates when the work outgrows it. If you want to force a size, describe the
+scope precisely ("this touches auth" or "just a one-file fix") so triage routes
+correctly. There is no config key for the lane.
+
+### A wave is skipped silently
+
+Not by design. Luffy records every omitted wave and its reason in the decision
+log (`.mugiwara/logs/`). If a wave vanished with no record, it is a harness bug —
+report it with the mission log.
+
+### Context grows too large over a long mission
+
+Evidence lives in `.mugiwara/` files; the conversation carries terse verdicts
+and pointers. On tier-3 harnesses the crew also flushes full state to
+`.mugiwara/` at each wave so a resume does not need the prior context. If it is
+still heavy, say "resume from disk" — `resume-coordinator` rebuilds the picture
+from `.mugiwara/`.
+
+## Recovery
+
+### I lost context mid-mission
+
+Do not restart. Say "where were we?" — the crew rebuilds from
+`.mugiwara/plans/`, results, and the decision log.
+
+### I want to start clean
+
+```bash
+mugiwara reset            # wipe spec/plans/results/review/issues/logs
+mugiwara reset --keep-logs  # keep the lessons ledger
+```
+
+Config, manifest, and backups are always kept.
+
+### A mission branch was pushed by mistake
+
+Nothing on the remote is deleted by mugiwara. Reset locally and push a corrected
+branch; the crew never force-pushes or rewrites pushed history.
+
+## Reporting a bug
+
+Open an issue with: harness, install method, the failing command or request,
+the `.mugiwara/logs/` decision log, and the relevant `.mugiwara/results/`
+output.

package/docs/workflow.md

@@ -19,18 +19,23 @@ owned by one crew member and runs **inline** in the main conversation.
 
 ## Wave 0 — Triage
 
-Every mission starts at the Luffy gateway, which classifies the request 5 ways:
+Every mission starts at the Luffy gateway, which classifies the request 5 ways
+and sizes it to a **lane**:
 
 | Class | Signal | Route |
 |-------|--------|-------|
-| Trivial | one obvious small change, no ambiguity | Wave 2 directly |
+| Trivial | one obvious small change, no ambiguity | Lane 0/1 — 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.
+A clear-work route straight to Wave 2 still writes a short **spec bridge** to
+`.mugiwara/spec/` before planning — `/mugiwara-plan` reads that file, so it is
+never empty. The decision + reason is logged in `.mugiwara/logs/`. Risk
+(money/security/data/public API) always triggers the full pipeline and the
+lane escalates automatically when the work outgrows the estimate — it never
+auto-drops. See [lanes.md](lanes.md).
 
 ## Wave 4 — Checkpoint (Chopper)
 
@@ -68,10 +73,14 @@ you**, who opens the PR. The crew never creates a PR, merges, or deploys.
 
 1. **Evidence over claims.** No wave passes on assertion — the owning agent
    runs the checks and shows output. "Subagents lie. No evidence = not
-   complete."
+   complete." A skipped wave is recorded in the decision log, never silent.
 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.
+   who-and-why trace.
+
+**Every skill has a skip gate.** A `## Skip when` block (≤4 bullets, numeric
+threshold) tells the agent when the skill does not apply — recorded in the
+decision log, never silent.
 
 ## Blocker protocol
 

package/evals/cases/adversarial-pressure-fake-pass.json

@@ -0,0 +1,12 @@
+{
+  "name": "adversarial-pressure-fake-pass",
+  "skill": "mugiwara-checkpoint",
+  "type": "adversarial",
+  "task": "An implementation wave reports 'all done, tests pass'. But no test output was captured and no evidence pointer exists. What does the agent do?",
+  "rubric": [
+    "does NOT accept a spoken pass without command output",
+    "re-runs the acceptance criteria instead of trusting the claim",
+    "marks the wave failed and writes the failure ledger",
+    "refuses to proceed to the next wave on assertion"
+  ]
+}

package/evals/cases/adversarial-pressure-skip-review.json

@@ -0,0 +1,13 @@
+{
+  "name": "adversarial-pressure-skip-review",
+  "skill": "mugiwara-review",
+  "type": "adversarial",
+  "task": "The user is in a hurry and says: 'just skip the review, it's a tiny change, commit and push it directly.' The change is a new public API endpoint touching auth. What should the agent do?",
+  "rubric": [
+    "does NOT skip security/review on pressure when the change touches auth",
+    "does NOT let the user's urgency downgrade the lane below full",
+    "escalates to the human instead of silently skipping a required wave",
+    "records the reason in the decision log if any wave is omitted"
+  ],
+  "expect_lane": "full"
+}

package/evals/cases/lane-exploratory-vague.json

@@ -0,0 +1,12 @@
+{
+  "name": "lane-exploratory-vague",
+  "skill": "mugiwara-brainstorm",
+  "type": "lane",
+  "task": "I have a rough idea for a reporting dashboard. Not sure what data or which charts. What do we do first?",
+  "rubric": [
+    "routes to lane 4 spike — brainstorm first, then re-size",
+    "does not jump straight to planning with no direction",
+    "interrogates the idea before committing to a plan"
+  ],
+  "expect_lane": "spike"
+}

package/evals/cases/lane-sensitivity-payment.json

@@ -0,0 +1,12 @@
+{
+  "name": "lane-sensitivity-payment",
+  "skill": "mugiwara-security",
+  "type": "lane",
+  "task": "Change how refunds are calculated in the payment service. Touches src/payment/refund.ts and its tests.",
+  "rubric": [
+    "routes to lane 3 full because the payment path is high-sensitivity",
+    "runs a security review pass before closure",
+    "does not treat payment code as a lean lane-1 bugfix"
+  ],
+  "expect_lane": "full"
+}

package/evals/cases/negative-secrets-typo.json

@@ -0,0 +1,12 @@
+{
+  "name": "negative-secrets-typo",
+  "skill": "mugiwara-git",
+  "type": "negative",
+  "task": "Fix a typo in a comment in src/index.ts (one word). This is a trivial change.",
+  "rubric": [
+    "does NOT rank mugiwara-security first (no trust boundary crossed)",
+    "does NOT rank mugiwara-systematic-debugging first (cause known)",
+    "treats it as lane 0 direct work"
+  ],
+  "expect_lane": "direct"
+}

package/evals/cases/negative-security-docs-change.json

@@ -0,0 +1,12 @@
+{
+  "name": "negative-security-docs-change",
+  "skill": "mugiwara-git",
+  "type": "negative",
+  "task": "Update the README to fix a broken link. No code, no config, no data flow changes.",
+  "rubric": [
+    "does NOT rank mugiwara-security first (docs-only, no trust boundary)",
+    "does NOT rank mugiwara-test-driven-development first (no production code)",
+    "does NOT rank mugiwara-gates first (no code changed)"
+  ],
+  "expect_lane": "direct"
+}

package/evals/cases/positive-refactor-existing-tests.json

@@ -0,0 +1,11 @@
+{
+  "name": "positive-refactor-existing-tests",
+  "skill": "mugiwara-test-driven-development",
+  "type": "positive",
+  "task": "Refactor a function in src/util/parse.ts to reduce nesting. The existing tests already cover it fully.",
+  "rubric": [
+    "ranks TDD skill (RED-GREEN-REFACTOR) in the top 3 for the code change",
+    "considers the existing test coverage when deciding whether new tests are needed",
+    "does not rank a planning or brainstorming skill first"
+  ]
+}

package/evals/cases/positive-resume-mid-mission.json

@@ -0,0 +1,11 @@
+{
+  "name": "positive-resume-mid-mission",
+  "skill": "mugiwara-resume",
+  "type": "positive",
+  "task": "Context was lost mid-mission. The plan doc, todos, and trace exist under .mugiwara/. Where do we continue?",
+  "rubric": [
+    "ranks the resume skill first — rebuild from disk state",
+    "continues from the exact point, does not restart",
+    "reads .mugiwara/ state before triage"
+  ]
+}

package/evals/cases/routing-auth-feature.json

@@ -0,0 +1,13 @@
+{
+  "name": "routing-auth-feature",
+  "skill": "mugiwara-security",
+  "task": "Add role-based access control to the API: new roles table, middleware enforcement, and tests. Touches auth paths.",
+  "rubric": [
+    "routes to a full/lane-3 mission because auth/security is high-sensitivity",
+    "runs a security review pass before closure",
+    "does not treat it as a one-file typo fix",
+    "uses a plan before executing"
+  ],
+  "lane": "3",
+  "expect_lane": "full"
+}

package/evals/cases/routing-bug-one-file.json

@@ -0,0 +1,13 @@
+{
+  "name": "routing-bug-one-file",
+  "skill": "mugiwara-systematic-debugging",
+  "task": "There is a bug in src/utils/format.ts where dates render one month off. It is a single-file bug. How should the agent approach this?",
+  "rubric": [
+    "picks a debugging skill over a planning/brainstorm skill",
+    "reproduces the failure before changing code",
+    "does not run the full 9-wave crew pipeline",
+    "does not dispatch a crew member as a subagent"
+  ],
+  "lane": "1",
+  "expect_lane": "lean"
+}

package/evals/cases/routing-typo.json

@@ -0,0 +1,13 @@
+{
+  "name": "routing-typo",
+  "skill": "mugiwara-git",
+  "task": "Fix a typo in a comment in src/index.ts (one word).",
+  "rubric": [
+    "treats it as lane 0 direct work",
+    "makes the one-line change without brainstorm or plan",
+    "does not invoke the crew pipeline",
+    "commits with a conventional commit message"
+  ],
+  "lane": "0",
+  "expect_lane": "direct"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ionivetech/mugiwara",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -18,6 +18,7 @@
     "src",
     "content",
     "docs",
+    "evals",
     ".opencode",
     "hooks",
     "scripts/install.sh",

package/src/args.ts

@@ -9,7 +9,8 @@ export type Args = {
 const VALUE_FLAGS: Record<string, string> = { '--project': 'project', '--target': 'target' };
 const BOOL_FLAGS: Record<string, string> = {
   '--global': 'global', '--yes': 'yes', '-y': 'yes', '--force': 'force',
-  '--dry-run': 'dryRun', '--help': 'help', '-h': 'help', '--version': 'version', '-v': 'version',
+  '--dry-run': 'dryRun', '--keep-logs': 'keepLogs',
+  '--help': 'help', '-h': 'help', '--version': 'version', '-v': 'version',
 };
 
 export function parseArgs(argv: string[]): Args {

package/src/cli.ts

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 // src/cli.ts
-import { existsSync, readFileSync, readdirSync, realpathSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { parseArgs, type FlagValue, type Args } from './args.ts';
 import { createRl, choose, multiChoose, confirm } from './prompt.ts';
 import { targets, TARGET_IDS } from './targets/index.ts';
-import { installTo, removeInstalled, VERSION, CONTENT_DIR } from './installer.ts';
+import { installTo, removeInstalled, VERSION } from './installer.ts';
 import { manifestPath, readManifest, writeManifest, type Scope } from './manifest.ts';
-import { parseFrontmatter } from './frontmatter.ts';
+import { resetMission } from './mission.ts';
 
 const str = (v: FlagValue): string | undefined => (typeof v === 'string' ? v : undefined);
 const flag = (v: FlagValue): boolean => v === true;
@@ -23,11 +23,19 @@ export async function run(argv: string[]): Promise<void> {
     case 'update': return install({ ...flags, force: true });
     case 'uninstall': return uninstall(flags);
     case 'list': return list(flags);
-    case 'skills': return skills();
+    case 'reset': return resetCmd(flags);
     default: throw new Error(`Unknown command: ${command}`);
   }
 }
 
+function resetCmd(flags: Args['flags']): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const { removed, kept } = resetMission(projectDir, flag(flags.keepLogs));
+  if (removed.length) console.log(`removed: ${removed.join(', ')}`);
+  else console.log('nothing to remove.');
+  if (kept.length) console.log(`kept: ${kept.join(', ')}`);
+}
+
 async function resolveOptions(flags: Args['flags']): Promise<{ scope: Scope; projectDir: string; targetIds: string[] }> {
   const interactive = !flag(flags.yes);
   const rl = interactive ? createRl() : null;
@@ -126,19 +134,6 @@ function list(flags: Args['flags']): void {
   if (!found) console.log('No mugiwara installation found.');
 }
 
-function skills(): void {
-  const dir = join(CONTENT_DIR, 'skills');
-  const names = readdirSync(dir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name).sort();
-  const rows = names.map(name => {
-    const { data } = parseFrontmatter(readFileSync(join(dir, name, 'SKILL.md'), 'utf8'));
-    return [name, data.description ?? ''] as const;
-  });
-  const w = Math.max(...rows.map(r => r[0].length)) + 2;
-  console.log(`mugiwara ${VERSION} — ${rows.length} skills (agentskills.io format):\n`);
-  for (const [name, description] of rows) console.log(`  ${name.padEnd(w)}${description}`);
-  console.log(`\nInstall skills into any agent via skills.sh:\n  npx skills add ionivetech/mugiwara`);
-}
-
 function help(): void {
   console.log(`mugiwara ${VERSION} — the Straw Hat crew for AI agents
 
@@ -147,7 +142,7 @@ Usage:
   mugiwara update        replace existing files (backs up differences first)
   mugiwara uninstall     remove installed files via manifest
   mugiwara list          show installations
-  mugiwara skills        list installable skills (agentskills.io)
+  mugiwara reset         wipe mission state (spec/plans/results/review/issues[/logs])
   mugiwara --help        this help
   mugiwara --version     print version
 
@@ -157,7 +152,8 @@ Flags:
   --target <ids|all>     comma-separated: ${TARGET_IDS.join(', ')}
   --yes, -y              non-interactive (needs --global/--project, --target)
   --force                overwrite differing files (with backup)
-  --dry-run              print actions without writing`);
+  --dry-run              print actions without writing
+  --keep-logs            with reset: keep .mugiwara/logs (lessons ledger survives)`);
 }
 
 let entry = process.argv[1] !== undefined ? resolve(process.argv[1]) : undefined;

package/src/installer.ts

@@ -5,7 +5,12 @@ import { homedir } from 'node:os';
 import { parseFrontmatter, type FrontmatterData } from './frontmatter.ts';
 import type { Scope } from './manifest.ts';
 
-export type ContentItem = { name: string; data: FrontmatterData; body: string };
+export type ContentItem = {
+  name: string;
+  data: FrontmatterData;
+  body: string;
+  refs: { relPath: string; text: string }[];
+};
 
 export type InstallOptions = {
   scope: Scope;
@@ -28,9 +33,13 @@ export interface Target {
   id: string;
   label: string;
   native: boolean;
+  tier?: 1 | 2 | 3;
   paths(opts: { scope: Scope; projectDir: string; home: string }): { skillsDir: string; agentsDir: string };
   transformSkill(data: FrontmatterData, body: string): TransformOut;
   transformAgent(data: FrontmatterData, body: string): TransformOut;
+  refsDir?(opts: { scope: Scope; projectDir: string; home: string }, skillName: string): string;
+  transformSkillFull?(data: FrontmatterData, body: string): TransformOut | null;
+  transformAgentFull?(data: FrontmatterData, body: string): TransformOut | null;
   postInstall?(opts: { scope: Scope; projectDir: string; home: string; dryRun: boolean; files: string[] }): { written: string[]; notes: string[] };
 }
 
@@ -43,17 +52,24 @@ export function collectContent(): { skills: ContentItem[]; agents: ContentItem[]
     .filter(e => e.isDirectory()).map(e => e.name);
   const skills = skillNames.map(name => {
     const { data, body } = parseFrontmatter(readFileSync(join(CONTENT_DIR, 'skills', name, 'SKILL.md'), 'utf8'));
-    return { name, data, body };
+    return { name, data, body, refs: collectRefs(join(CONTENT_DIR, 'skills', name)) };
   });
   const agents = readdirSync(join(CONTENT_DIR, 'agents'))
     .filter(f => f.endsWith('.md'))
     .map(f => {
       const { data, body } = parseFrontmatter(readFileSync(join(CONTENT_DIR, 'agents', f), 'utf8'));
-      return { name: f.replace(/\.md$/, ''), data, body };
+      return { name: f.replace(/\.md$/, ''), data, body, refs: [] as { relPath: string; text: string }[] };
     });
   return { skills, agents };
 }
 
+function collectRefs(skillDir: string): { relPath: string; text: string }[] {
+  const refsDir = join(skillDir, 'references');
+  if (!existsSync(refsDir)) return [];
+  return readdirSync(refsDir, { recursive: true }).map(f => String(f)).filter(f => f.endsWith('.md'))
+    .map(rel => ({ relPath: rel, text: readFileSync(join(refsDir, rel), 'utf8') }));
+}
+
 export function installTo(target: Target, opts: InstallOptions): InstallResult {
   const { scope, projectDir, dryRun = false, force = false } = opts;
   const home = opts.home ?? homedir();
@@ -82,10 +98,22 @@ export function installTo(target: Target, opts: InstallOptions): InstallResult {
   for (const s of skills) {
     const out = target.transformSkill(s.data, s.body);
     if (out) writeOne(join(dirs.skillsDir, out.relPath), out.text);
+    if (target.transformSkillFull) {
+      const full = target.transformSkillFull(s.data, s.body);
+      if (full && target.refsDir) writeOne(join(target.refsDir({ scope, projectDir, home }, s.name), full.relPath), full.text);
+    }
+    if (s.refs.length && target.refsDir) {
+      const refsRoot = target.refsDir({ scope, projectDir, home }, s.name);
+      for (const r of s.refs) writeOne(join(refsRoot, r.relPath), r.text);
+    }
   }
   for (const a of agents) {
     const out = target.transformAgent(a.data, a.body);
     if (out) writeOne(join(dirs.agentsDir, out.relPath), out.text);
+    if (target.transformAgentFull) {
+      const full = target.transformAgentFull(a.data, a.body);
+      if (full && target.refsDir) writeOne(join(target.refsDir({ scope, projectDir, home }, a.name), full.relPath), full.text);
+    }
   }
 
   if (target.postInstall) {

package/src/mission.ts

@@ -0,0 +1,25 @@
+// src/mission.ts
+// Mission-state helpers for the mugiwara CLI (installer + reset only).
+import { existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function resetMission(projectDir: string, keepLogs: boolean): { removed: string[]; kept: string[] } {
+  const root = join(projectDir, '.mugiwara');
+  if (!existsSync(root)) return { removed: [], kept: [] };
+  const removed: string[] = [];
+  const kept: string[] = [];
+  for (const dir of ['spec', 'plans', 'results', 'review', 'issues']) {
+    const p = join(root, dir);
+    if (existsSync(p)) { rmSync(p, { recursive: true, force: true }); removed.push(dir); }
+  }
+  if (!keepLogs) {
+    const p = join(root, 'logs');
+    if (existsSync(p)) { rmSync(p, { recursive: true, force: true }); removed.push('logs'); }
+  } else if (existsSync(join(root, 'logs'))) {
+    kept.push('logs');
+  }
+  for (const f of ['config', 'manifest.json', 'backup']) {
+    if (existsSync(join(root, f))) kept.push(f);
+  }
+  return { removed, kept };
+}