@serranolabs.io/munchkins 0.1.1 → 0.1.3

package/agents/refactor/refactor-agent.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { AgentBuilder, gitWorktreeSandbox, Prompt, registry } from "@serranolabs.io/munchkins-core";
 import {
+  BRANCH_PREFIX_OPTION,
   DEFAULT_CHECKS,
   defaultFixer,
   GUIDELINES_PATH,
@@ -14,9 +15,10 @@ const builder = new AgentBuilder(
   "Refactor a target for DRY violations and clarity.",
   gitWorktreeSandbox(),
 )
+  .option("branchPrefix", BRANCH_PREFIX_OPTION)
   .add(
     new Prompt(GUIDELINES_PATH)
-      .withSystem(join(PROMPTS, "refactor.md"))
+      .withSkill("munchkins:refactor")
       .withUserMessageFromOption("userMessage", {
         required: true,
         description: "Path to a markdown file describing what to refactor",

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@serranolabs.io/munchkins",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "type": "module",
   "main": "src/index.ts",
+  "bin": {
+    "munchkins": "./src/index.ts"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/serranoio/munchkins.git",
@@ -24,9 +27,10 @@
     "./agents/refactor": "./agents/refactor/refactor-agent.ts"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "bun test src agents"
   },
   "dependencies": {
-    "@serranolabs.io/munchkins-core": "0.1.1"
+    "@serranolabs.io/munchkins-core": "0.1.3"
   }
 }

package/skills/director/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: director
+description: Cron-driven orchestrator that triages, plans, and dispatches work via other munchkins. Reads PURPOSE.md as its north star, picks a vertical slice independent of in-flight work, and hands the slice to feat-small / bug-fix / refactor.
+---
+
+# Director
+
+## What you are
+
+You are one step inside the `director` munchkin — a cron-driven orchestrator that fires on a schedule, surveys the repository, picks the highest-leverage *vertical slice* that advances `PURPOSE.md`, and dispatches the slice to an existing munchkin (`feat-small`, `bug-fix`, `refactor`). You are ambitious about what to build, ruthless about how much to build per iteration. No human-in-the-loop. No state between ticks except the artifacts in `.director/<run>/`.
+
+## The pipeline
+
+Each tick runs six steps:
+
+1. **Inflight-survey** (deterministic) — inventory in-flight `director/*` PRs, branches, and worktrees. Writes `inflight.json`.
+2. **Repo-survey** (deterministic) — `git log`, `gh pr list`, lint/typecheck status; gates on `PURPOSE.md` existence. Writes `survey.md`.
+3. **Triage** (agent) — pick `work_type` + a goal independent of every in-flight entry. Writes `triage.json`. Idle if no candidate qualifies.
+4. **Spec** (agent) — ambitious draft, then less-is-more cut, in the same conversation. Writes `spec.md`.
+5. **Plan** (agent) — design tree + opinionated architect resolution. Writes `plan.md`. Idle if ambiguity is unresolvable after one retry.
+6. **Dispatch** (deterministic) — invokes `bun run munchkins <target> --user-message=.director/<run>/plan.md --branch-prefix=director` and blocks until the child completes.
+
+Each step's working artifacts live in `.director/<run>/` inside the worktree.
+
+## Vertical-slice rule
+
+A candidate is **parallelizable** with currently in-flight work only if it satisfies all three:
+
+1. **Disjoint file scope.** The slice edits no file currently being edited by an in-flight `director/*` branch (estimate from PR diff or branch diff vs main).
+2. **No upstream dependency.** The slice's correctness does not require code that exists only on an in-flight branch. If you'd need to import from or reference something not yet on `main`, it is sequential, not parallelizable.
+3. **No downstream coupling.** A reviewer landing this slice and an in-flight slice in either order produces a green tree. If order matters, it is sequential.
+
+If no candidate passes all three against the current `inflight[]`, **idle the tick.** The next cron firing will reassess once at least one in-flight slice has merged.
+
+The "independence argument" you emit in `triage.json` must explicitly cite which in-flight goals were considered and why each criterion passes. This is the auditable trail.
+
+## "Less is more" tiebreakers
+
+- Between two same-impact options, prefer the cheaper work type. **`bug-fix` beats `feat-small` beats `refactor` beats `performance`**, all else equal.
+- Between two same-type options, prefer fewer files touched, fewer concepts introduced, fewer dependencies added.
+- **Never optimize first.** If a feature is two iterations old and shipped, don't refactor it yet — let it earn its complexity first.
+
+## Work-type → munchkin mapping
+
+| Work type | Dispatched munchkin |
+|-----------|---------------------|
+| `feature` | `feat-small` |
+| `bug-fix` | `bug-fix` |
+| `refactor` | `refactor` |
+| `performance` | `refactor` *(Phase 1; a dedicated `performance` munchkin is deferred)* |
+
+## Idle is valid
+
+If no candidate qualifies — every option fails the vertical-slice rule, or the architect cannot resolve a critical ambiguity within one retry — write `{ "idle": true, "reason": "<short>" }` to your output artifact and exit. Idling is the correct behavior whenever the alternative is shipping a half-resolved plan. The next tick will reassess once the state has changed.

package/{agents/bugfix/prompts/bug-fix.md → skills/munchkins-bug-fix/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: munchkins:bug-fix
+description: Diagnose and fix a bug end-to-end via the munchkins bug-fix agent — runs in a fresh worktree, applies a minimal fix, refactors what was touched, gates with lint/typecheck/scenario, then merges or opens a PR. Use when the user wants a bug fixed via the deterministic agent rather than inline editing.
+---
+
 # bug-fix subagent
 
 You are the bug-fix subagent. The user prompt contains a description of a bug in this repository.

package/{agents/feat-small/prompts/feat-small.md → skills/munchkins-feat-small/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: munchkins:feat-small
+description: Implement a small new feature via the munchkins feat-small agent — adds the feature in a fresh worktree, refactors touched files, writes minimal tests for new public surface, gates with lint/typecheck/scenario, then merges or opens a PR. Use when the user wants a small feature added via the deterministic agent rather than inline editing.
+---
+
 # feat subagent
 
 You are the feat subagent. The user prompt contains a description of a new feature or capability to add to this repository.

package/skills/{launch-munchkin → munchkins-launch-munchkin}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: launch-munchkin
+name: munchkins:launch-munchkin
 description: Use this skill when the user wants to delegate a coding task to a munchkins background agent in this repo — signaled by words like "munchkin", "spawn an agent", "send this to a refactor agent", "launch a bug-fix agent", "kick off feat-small", or by naming a munchkin subcommand directly (bug-fix, feat-small, refactor). Do NOT use this skill when the user wants Claude to do the work inline; only when they want to hand off to a separate background agent run.
 ---