@serranolabs.io/munchkins 0.1.0 → 0.1.3

package/agents/_shared/presets.ts

@@ -1,6 +1,6 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Prompt } from "@serranolabs.io/munchkins-core";
+import { type OptionSchema, Prompt } from "@serranolabs.io/munchkins-core";
 
 export function getAgentPromptsDir(importUrl: string): string {
   return join(dirname(fileURLToPath(importUrl)), "prompts");
@@ -15,12 +15,21 @@ export const SUMMARY_WRITER_PATH = join(SHARED_PROMPTS, "summary-writer.md");
 export const TEST_WRITER_PATH = join(SHARED_PROMPTS, "test-writer.md");
 
 export const DEFAULT_CHECKS: readonly string[] = [
+  "bun run lint:fix",
   "bun run lint",
   "bun run typecheck",
   "bun run scenario",
   "bun test --pass-with-no-tests",
 ];
 
+// Shared --branch-prefix declaration for the default agents. Director dispatch
+// passes this through to child runs to scope their branches under `director/*`.
+export const BRANCH_PREFIX_OPTION: OptionSchema = {
+  type: "string",
+  required: false,
+  description: "Branch namespace prefix; defaults to 'agent'",
+};
+
 export function defaultFixer(): Prompt {
   return new Prompt(DETERMINISTIC_FIXER_PATH);
 }

package/agents/bugfix/bugfix-agent.ts

@@ -1,24 +1,22 @@
-import { join } from "node:path";
 import { AgentBuilder, gitWorktreeSandbox, Prompt, registry } from "@serranolabs.io/munchkins-core";
 import {
+  BRANCH_PREFIX_OPTION,
   DEFAULT_CHECKS,
   defaultFixer,
   defaultSummaryWriter,
   GUIDELINES_PATH,
-  getAgentPromptsDir,
   REFACTORER_PATH,
 } from "../_shared/presets.js";
 
-const PROMPTS = getAgentPromptsDir(import.meta.url);
-
 const builder = new AgentBuilder(
   "bug-fix",
   "Fix a bug described in a markdown user-message file.",
   gitWorktreeSandbox(),
 )
+  .option("branchPrefix", BRANCH_PREFIX_OPTION)
   .add(
     new Prompt(GUIDELINES_PATH)
-      .withSystem(join(PROMPTS, "bug-fix.md"))
+      .withSkill("munchkins:bug-fix")
       .withUserMessageFromOption("userMessage", {
         required: true,
         description: "Path to a markdown file describing the bug",

package/agents/director/director-agent.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { registry } from "@serranolabs.io/munchkins-core";
+import { $ } from "bun";
+import "./director-agent.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, "../../../..");
+const SCRIPTS = join(HERE, "scripts");
+
+const TEST_GIT_IDENTITY = {
+  GIT_AUTHOR_NAME: "t",
+  GIT_AUTHOR_EMAIL: "t@t",
+  GIT_COMMITTER_NAME: "t",
+  GIT_COMMITTER_EMAIL: "t@t",
+};
+
+interface Repo {
+  path: string;
+  cleanup: () => void;
+}
+
+async function createBareRepo(): Promise<Repo> {
+  const path = mkdtempSync(join(tmpdir(), "munchkins-director-test-"));
+  const env = { ...process.env, ...TEST_GIT_IDENTITY };
+  await $`git init -b main`.cwd(path).env(env).quiet();
+  await $`git config user.email t@t`.cwd(path).env(env).quiet();
+  await $`git config user.name t`.cwd(path).env(env).quiet();
+  await Bun.write(join(path, "seed.ts"), "export const seed = 1;\n");
+  await $`git add -A`.cwd(path).env(env).quiet();
+  await $`git commit -m seed`.cwd(path).env(env).quiet();
+  return {
+    path,
+    cleanup: () => {
+      try {
+        rmSync(path, { recursive: true, force: true });
+      } catch {
+        // best-effort
+      }
+    },
+  };
+}
+
+describe("director registration", () => {
+  test("director is registered under name 'director' after side-effect import", () => {
+    expect(registry.get("director")).toBeDefined();
+    expect(registry.get("director")?.name).toBe("director");
+  });
+
+  test("cron config is every 10 minutes, thinking verbosity, userMessage 'tick'", () => {
+    const builder = registry.get("director");
+    expect(builder?.getCron()).toEqual({
+      spec: "*/10 * * * *",
+      userMessage: "tick",
+      verbosity: "thinking",
+    });
+  });
+
+  test("step count is 7: 3 deterministic + 3 agent + 1 trailing post-checks", () => {
+    // The director's main pipeline is 6 steps (steps 1–6); the trailing
+    // .addDeterministic(DEFAULT_CHECKS, defaultFixer) is the 7th, kept for
+    // parity with other munchkins so the integration phase has a gate to run.
+    expect(registry.get("director")?.getStepCount()).toBe(7);
+  });
+
+  test("director opts out of the framework's --dry-run short-circuit", () => {
+    expect(registry.get("director")?.getHandlesDryRun()).toBe(true);
+  });
+});
+
+describe("director scripts", () => {
+  let repo: Repo;
+
+  beforeEach(async () => {
+    repo = await createBareRepo();
+    // The scripts read $WORKTREE and $REPO_ROOT from the env; for these
+    // tests both point at the same temp repo (one-checkout fixture).
+  });
+
+  afterEach(() => {
+    repo.cleanup();
+  });
+
+  test("repo-survey.sh exits non-zero with the expected error when PURPOSE.md is absent", async () => {
+    const env = {
+      ...process.env,
+      ...TEST_GIT_IDENTITY,
+      WORKTREE: repo.path,
+      REPO_ROOT: repo.path,
+      PATH: process.env.PATH ?? "",
+    };
+    // Seed the .director/current sentinel; the script checks PURPOSE.md
+    // before reading it, so the failure path doesn't depend on this — but
+    // having it present rules out "missing sentinel" as the failure mode.
+    await $`mkdir -p ${repo.path}/.director`.quiet();
+    await Bun.write(join(repo.path, ".director", "current"), "fake-run");
+    const r = await $`bash ${join(SCRIPTS, "repo-survey.sh")}`.env(env).nothrow().quiet();
+    expect(r.exitCode).not.toBe(0);
+    const combined = r.stdout.toString() + r.stderr.toString();
+    expect(combined).toContain("PURPOSE.md not found at repo root");
+    expect(combined).toContain("docs/pages/agents/director.md");
+  });
+
+  test("inflight-survey.sh in a repo with no director/* branches writes inflight.json with empty branches and worktrees", async () => {
+    // Stub `gh` to fail so the PR inventory falls back to '[]'.
+    const stubDir = mkdtempSync(join(tmpdir(), "munchkins-director-stub-"));
+    try {
+      await Bun.write(join(stubDir, "gh"), "#!/usr/bin/env bash\nexit 1\n");
+      await $`chmod +x ${join(stubDir, "gh")}`.quiet();
+
+      const env = {
+        ...process.env,
+        ...TEST_GIT_IDENTITY,
+        WORKTREE: repo.path,
+        REPO_ROOT: repo.path,
+        PATH: `${stubDir}:${process.env.PATH ?? ""}`,
+      };
+      const r = await $`bash ${join(SCRIPTS, "inflight-survey.sh")}`.env(env).nothrow().quiet();
+      expect(r.exitCode).toBe(0);
+
+      const runId = (await Bun.file(join(repo.path, ".director", "current")).text()).trim();
+      expect(runId).toMatch(/^\d{8}T\d{6}-/);
+
+      const inflightPath = join(repo.path, ".director", runId, "inflight.json");
+      const inflight = JSON.parse(await Bun.file(inflightPath).text());
+      expect(inflight.branches).toEqual([]);
+      expect(inflight.worktrees).toEqual([]);
+      // gh stub fails, so prs falls back to '[]' (empty array).
+      expect(inflight.prs).toEqual([]);
+    } finally {
+      rmSync(stubDir, { recursive: true, force: true });
+    }
+  });
+});
+
+// Smoke check that the director skill symlink resolves to the package source.
+// Important because every agent step loads the skill via withSkill("director")
+// and a stale symlink would surface as a runtime "skill not found".
+describe("director skill availability", () => {
+  test(".claude/skills/director points at packages/munchkins/skills/director", async () => {
+    const skillPath = join(REPO_ROOT, ".claude/skills/director/SKILL.md");
+    const content = await Bun.file(skillPath).text();
+    expect(content).toContain("name: director");
+    expect(content).toContain("Vertical-slice rule");
+  });
+});

package/agents/director/director-agent.ts

@@ -0,0 +1,45 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AgentBuilder, gitWorktreeSandbox, Prompt, registry } from "@serranolabs.io/munchkins-core";
+import {
+  DEFAULT_CHECKS,
+  defaultFixer,
+  defaultSummaryWriter,
+  GUIDELINES_PATH,
+} from "../_shared/presets.js";
+
+const AGENT_DIR = dirname(fileURLToPath(import.meta.url));
+const PROMPTS = join(AGENT_DIR, "prompts");
+const SCRIPTS = join(AGENT_DIR, "scripts");
+
+const builder = new AgentBuilder(
+  "director",
+  "Cron-driven orchestrator that triages, plans, and dispatches work via other munchkins.",
+  gitWorktreeSandbox(),
+)
+  // userMessage is the cron tick payload; the daemon also passes it via env.
+  // No prompt step reads it directly — the agent's source of truth is
+  // PURPOSE.md plus the in-flight survey, not a per-tick user message.
+  .option("userMessage", {
+    type: "string",
+    required: false,
+    description:
+      "Per-tick payload (default 'tick'); unused by the pipeline but required by the CLI surface.",
+    default: "tick",
+  })
+  .addDeterministic([`bash ${join(SCRIPTS, "inflight-survey.sh")}`])
+  .addDeterministic([`bash ${join(SCRIPTS, "repo-survey.sh")}`])
+  .add(new Prompt(GUIDELINES_PATH).withSkill("director").withSystem(join(PROMPTS, "triage.md")))
+  .add(new Prompt(GUIDELINES_PATH).withSkill("director").withSystem(join(PROMPTS, "spec.md")))
+  .add(new Prompt(GUIDELINES_PATH).withSkill("director").withSystem(join(PROMPTS, "plan.md")))
+  .addDeterministic([`bash ${join(SCRIPTS, "dispatch.sh")}`])
+  .addDeterministic([...DEFAULT_CHECKS], {
+    loop: { maxIterations: 3, fixer: defaultFixer() },
+  })
+  .summaryWriter(defaultSummaryWriter())
+  .handlesDryRun()
+  .cron("*/10 * * * *", { userMessage: "tick", verbosity: "thinking" });
+
+registry.register(builder);
+
+export { builder };

package/agents/director/prompts/plan.md

@@ -0,0 +1,81 @@
+# Director step 5 — Plan
+
+You are the **Plan** step of the director pipeline. Pipeline position: step 5 of 6.
+
+## Early-exit on upstream idle
+
+Read `.director/<run>/spec.md` first (discover `<run>` via `.director/current`). If the file's first non-empty line contains `"idle": true`, write the following to `.director/<run>/plan.md` and exit immediately:
+
+```
+{"idle": true, "reason": "upstream idle"}
+```
+
+Do not run any other step.
+
+## Input artifacts
+
+- `.director/<run>/spec.md` — the thinnest viable slice from the Spec step.
+
+## What to do
+
+Two passes, in the same conversation:
+
+### Pass A — Design tree
+
+Read the spec. Enumerate every concrete decision point or ambiguity a downstream implementer would have to resolve. Examples:
+
+- "Which file owns the new helper?"
+- "Sync or async API shape?"
+- "New test file or extend an existing one?"
+- "Does this need a feature flag?"
+
+Be exhaustive. If a decision is genuinely trivial, name it and mark it `trivial`. If it's load-bearing, name it and leave it open.
+
+### Pass B — Architect resolution
+
+For each non-trivial item in Pass A, make an opinionated call. Cite the reason in one sentence. Apply these tiebreakers in order:
+
+1. **Match the repo's existing patterns.** Read the relevant code; copy the shape that's already there.
+2. **Smaller change wins.** Prefer extension over new modules; prefer composition over abstraction.
+3. **Reversibility.** When two options have similar surface, pick the one easier to undo.
+
+If after one pass an ambiguity remains genuinely unresolvable (the spec is too vague, both options are equally load-bearing, the architect doesn't have enough context), **idle the tick**. Don't ship a half-resolved plan.
+
+## Output
+
+Write exactly one file: `.director/<run>/plan.md`.
+
+Non-idle format — a user-message-ready markdown brief that the downstream munchkin can consume directly:
+
+```markdown
+# <slice title from spec.md>
+
+## Goal
+<one paragraph>
+
+## Files to modify
+- `<path>` — <what changes>
+- ...
+
+## Implementation plan
+<numbered steps; each step names files and the resolved design decision behind it>
+
+## Acceptance criteria
+- <runnable checks>
+- ...
+
+## Out of scope
+- <explicit non-changes>
+```
+
+Idle format:
+
+```json
+{"idle": true, "reason": "<short — e.g. 'architect could not resolve sync-vs-async ambiguity'>"}
+```
+
+## Rules
+
+- Touch no other files. Your only side effect is writing `plan.md`.
+- The non-idle plan must be self-contained — the downstream munchkin will receive it as `--user-message` and won't have context for anything you leave implicit.
+- Idle is valid. Better to idle than to ship a half-resolved plan.

package/agents/director/prompts/spec.md

@@ -0,0 +1,65 @@
+# Director step 4 — Spec
+
+You are the **Spec** step of the director pipeline. Pipeline position: step 4 of 6.
+
+## Early-exit on upstream idle
+
+Read `.director/<run>/triage.json` first (discover `<run>` via `.director/current`). If it contains `"idle": true`, write the following to `.director/<run>/spec.md` and exit immediately:
+
+```
+{"idle": true, "reason": "upstream idle"}
+```
+
+Do not run any other step.
+
+## Input artifacts
+
+- `.director/<run>/triage.json` — non-idle: `{ work_type, justification, independence_argument, goal }`.
+- `PURPOSE.md` — for tone-matching the slice against the repo's success criteria.
+
+## What to do
+
+Two passes, in the same conversation:
+
+### Pass A — Ambitious draft
+
+Produce the most ambitious version of the slice that is still consistent with the `work_type`. Name the files, the new public surfaces, the user-visible behavior, the acceptance criteria. Don't trim yet — this pass exists so the next pass has something concrete to cut.
+
+### Pass B — Less-is-more cut
+
+Re-read Pass A. Cut everything that isn't load-bearing for the slice's stated `goal`. Apply ruthlessly:
+
+- Remove "nice to have" sub-features.
+- Collapse multiple acceptance criteria into one if they test the same thing.
+- Strip any "we should also" expansions — they belong in a future tick.
+- Prefer extending existing files over creating new ones.
+
+The result is the **thinnest viable slice**.
+
+## Output
+
+Write exactly one file: `.director/<run>/spec.md`. It must contain only the post-cut spec — *not* Pass A. Structure:
+
+```markdown
+# <short slice title>
+
+## Goal
+<one paragraph from triage.json, refined>
+
+## Files in scope
+- `<path>` — <one-line reason>
+- ...
+
+## Acceptance criteria
+- <observable, runnable check>
+- ...
+
+## Out of scope
+- <explicit cuts from Pass A>
+```
+
+## Rules
+
+- Touch no other files. Your only side effect is writing `spec.md`.
+- The spec must be small enough that the downstream munchkin (`feat-small` / `bug-fix` / `refactor`) can ship it in one run without expanding scope.
+- If during Pass B you realize the slice is actually two slices, keep one and put the other in "Out of scope".

package/agents/director/prompts/triage.md

@@ -0,0 +1,49 @@
+# Director step 3 — Triage
+
+You are the **Triage** step of the director pipeline. Pipeline position: step 3 of 6.
+
+## Input artifacts (in the worktree)
+
+- `PURPOSE.md` — the repo's north star. Source of truth for what counts as "advancing the project".
+- `.director/<run>/inflight.json` — array of in-flight `director/*` work (PRs, branches, worktrees) with file scope and goal. May be `[]`.
+- `.director/<run>/survey.md` — repo state: recent `git log`, open PRs (all), lint/typecheck status.
+
+Discover the current run directory by reading `.director/current` from the worktree root.
+
+## What to do
+
+1. Read all three input artifacts.
+2. Brainstorm candidate slices that would advance an unmet `PURPOSE.md` success criterion. Be ambitious about *what* matters; be specific about file scope.
+3. For each candidate, apply the **vertical-slice rule** (disjoint file scope / no upstream dep / no downstream coupling) against every entry in `inflight.json`.
+4. Among candidates that pass the rule, apply the **"less is more" tiebreakers** (cheaper work type wins; fewer files / fewer concepts wins; don't refactor newly shipped features).
+5. Pick exactly one candidate. If no candidate qualifies, idle.
+
+## Output
+
+Write exactly one file: `.director/<run>/triage.json`.
+
+Schema (non-idle):
+
+```json
+{
+  "work_type": "feature" | "bug-fix" | "refactor" | "performance",
+  "justification": "<2-4 sentences: why this slice now, citing which PURPOSE.md bullet it advances>",
+  "independence_argument": "<for each inflight entry, a sentence explaining why the three vertical-slice criteria pass>",
+  "goal": "<one paragraph describing the slice — what changes, in which files, observable outcome>"
+}
+```
+
+Schema (idle):
+
+```json
+{
+  "idle": true,
+  "reason": "<short — e.g. 'all candidates depend on PR #42' or 'PURPOSE.md success criteria all satisfied'>"
+}
+```
+
+## Rules
+
+- Touch no other files. Do **not** modify code, commit, or open PRs. Your only side effect is writing `triage.json`.
+- The `goal` field must be specific enough that the Spec step (next) can turn it into a thinnest-viable-slice without re-deriving intent.
+- Idle is valid. Better to idle than to ship a slice that violates the vertical-slice rule.

package/agents/director/scripts/dispatch.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Step 6 — Dispatch. Reads triage.json + plan.md, derives the target munchkin
+# from work_type, then runs the child as a foreground subprocess. Early-exits
+# on upstream idle and short-circuits to a print-only path when
+# $__MUNCHKINS_OPT_dryRun is "true".
+
+set -euo pipefail
+
+WORKDIR="${WORKTREE:-$PWD}"
+REPO="${REPO_ROOT:-$WORKDIR}"
+
+RUN_ID="$(cat "$WORKDIR/.director/current" 2>/dev/null || true)"
+if [ -z "$RUN_ID" ]; then
+  echo "[director] dispatch: .director/current missing — pipeline did not initialize" >&2
+  exit 1
+fi
+
+RUN_DIR="$WORKDIR/.director/$RUN_ID"
+TRIAGE="$RUN_DIR/triage.json"
+PLAN="$RUN_DIR/plan.md"
+
+# Upstream-idle guard: if any upstream artifact says idle, exit 0.
+if [ -f "$TRIAGE" ] && grep -qE '"idle"[[:space:]]*:[[:space:]]*true' "$TRIAGE"; then
+  echo "[director] dispatch: triage idle — nothing to do"
+  exit 0
+fi
+if [ -f "$PLAN" ] && head -n 5 "$PLAN" | grep -qE '"idle"[[:space:]]*:[[:space:]]*true'; then
+  echo "[director] dispatch: plan idle — nothing to do"
+  exit 0
+fi
+
+if [ ! -f "$TRIAGE" ] || [ ! -f "$PLAN" ]; then
+  echo "[director] dispatch: missing triage.json or plan.md in $RUN_DIR" >&2
+  exit 1
+fi
+
+# Extract work_type. Use a Bun one-liner so we don't ship a shell JSON parser.
+work_type="$(bun -e '
+  const t = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf-8"));
+  process.stdout.write(String(t.work_type ?? ""));
+' "$TRIAGE")"
+
+case "$work_type" in
+  feature) target="feat-small" ;;
+  bug-fix) target="bug-fix" ;;
+  refactor) target="refactor" ;;
+  performance) target="refactor" ;; # Phase 1 mapping; replaced by `performance` in Phase 2.
+  *)
+    echo "[director] dispatch: unknown work_type \"$work_type\" in $TRIAGE" >&2
+    exit 1
+    ;;
+esac
+
+cmd=(bun run munchkins "$target" "--user-message=$PLAN" "--branch-prefix=director")
+
+if [ "${__MUNCHKINS_OPT_dryRun:-}" = "true" ]; then
+  echo "[director] dispatch (dry-run): ${cmd[*]}"
+  exit 0
+fi
+
+echo "[director] dispatch: ${cmd[*]}"
+cd "$REPO"
+exec "${cmd[@]}"

package/agents/director/scripts/inflight-survey.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Step 1 — Inflight-survey. Inventories all director-spawned work currently
+# in flight: open director/* PRs (when `gh` is available + authed), local
+# director/* branches, and director-namespaced worktrees.
+
+set -euo pipefail
+
+WORKDIR="${WORKTREE:-$PWD}"
+DIRECTOR_ROOT="$WORKDIR/.director"
+
+# Derive a stable, sortable run id and remember it for downstream steps.
+RUN_ID="$(date -u +%Y%m%dT%H%M%S)-${RANDOM}${RANDOM}"
+RUN_DIR="$DIRECTOR_ROOT/$RUN_ID"
+mkdir -p "$RUN_DIR"
+printf '%s' "$RUN_ID" > "$DIRECTOR_ROOT/current"
+
+OUT="$RUN_DIR/inflight.json"
+
+# Branch inventory (always available).
+branches=()
+while IFS= read -r br; do
+  br="${br#"${br%%[![:space:]]*}"}"
+  [ -n "$br" ] && branches+=("$br")
+done < <(git -C "$WORKDIR" branch --list 'director/*' --format='%(refname:short)' 2>/dev/null || true)
+
+# Worktree inventory (filter porcelain output for director-namespaced branches).
+worktrees=()
+if git -C "$WORKDIR" worktree list --porcelain >/dev/null 2>&1; then
+  current_path=""
+  while IFS= read -r line; do
+    case "$line" in
+      "worktree "*) current_path="${line#worktree }" ;;
+      "branch refs/heads/director/"*)
+        wbranch="${line#branch refs/heads/}"
+        worktrees+=("$current_path|$wbranch")
+        ;;
+      "")
+        current_path=""
+        ;;
+    esac
+  done < <(git -C "$WORKDIR" worktree list --porcelain)
+fi
+
+# Open PRs against director/* heads. Best-effort: skip silently if `gh` is
+# missing or unauthenticated — the local inventory is still useful.
+pr_json="[]"
+if command -v gh >/dev/null 2>&1; then
+  if pr_json_raw="$(gh pr list --head 'director/*' --state open \
+      --json number,title,headRefName,files 2>/dev/null)"; then
+    pr_json="$pr_json_raw"
+  fi
+fi
+
+# Compose final JSON. Branches and worktrees are flat string arrays; PRs is
+# whatever `gh` emitted (already JSON). Idle case is the empty triplet — the
+# triage step treats it as "nothing in flight".
+{
+  printf '{\n'
+  printf '  "branches": ['
+  if [ "${#branches[@]}" -gt 0 ]; then
+    sep=""
+    for b in "${branches[@]}"; do
+      esc="${b//\\/\\\\}"
+      esc="${esc//\"/\\\"}"
+      printf '%s"%s"' "$sep" "$esc"
+      sep=", "
+    done
+  fi
+  printf '],\n'
+  printf '  "worktrees": ['
+  if [ "${#worktrees[@]}" -gt 0 ]; then
+    sep=""
+    for w in "${worktrees[@]}"; do
+      p="${w%%|*}"
+      bv="${w##*|}"
+      printf '%s{"path": "%s", "branch": "%s"}' "$sep" "${p//\"/\\\"}" "${bv//\"/\\\"}"
+      sep=", "
+    done
+  fi
+  printf '],\n'
+  printf '  "prs": %s\n' "$pr_json"
+  printf '}\n'
+} > "$OUT"
+
+echo "[director] inflight-survey wrote $OUT (run-id=$RUN_ID)"

package/agents/director/scripts/repo-survey.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Step 2 — Repo-survey. Captures `git log`, `gh pr list`, lint/typecheck status
+# into a markdown brief the triage step reads alongside PURPOSE.md.
+#
+# Gates the rest of the pipeline on PURPOSE.md being present at the repo root.
+
+set -euo pipefail
+
+WORKDIR="${WORKTREE:-$PWD}"
+REPO="${REPO_ROOT:-$WORKDIR}"
+
+if [ ! -f "$REPO/PURPOSE.md" ]; then
+  echo "PURPOSE.md not found at repo root. The director requires a written north star. See docs/pages/agents/director.md." >&2
+  exit 1
+fi
+
+RUN_ID="$(cat "$WORKDIR/.director/current" 2>/dev/null || true)"
+if [ -z "$RUN_ID" ]; then
+  echo "[director] repo-survey: .director/current missing — did inflight-survey run?" >&2
+  exit 1
+fi
+
+RUN_DIR="$WORKDIR/.director/$RUN_ID"
+mkdir -p "$RUN_DIR"
+OUT="$RUN_DIR/survey.md"
+
+{
+  echo "# Director repo survey — $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  echo
+  echo "## Recent commits (\`git log --oneline -30\`)"
+  echo
+  echo '```'
+  git -C "$REPO" log --oneline -30 2>&1 || true
+  echo '```'
+  echo
+  echo "## Open PRs (\`gh pr list\`)"
+  echo
+  if command -v gh >/dev/null 2>&1; then
+    echo '```'
+    gh pr list --limit 30 2>&1 || echo "(gh pr list failed — likely unauthenticated)"
+    echo '```'
+  else
+    echo "(\`gh\` not on PATH — open PRs unknown)"
+  fi
+  echo
+  echo "## Lint status (\`bun run lint\`)"
+  echo
+  if (cd "$REPO" && bun run lint >/dev/null 2>&1); then
+    echo "PASS"
+  else
+    echo "FAIL"
+  fi
+  echo
+  echo "## Typecheck status (\`bun run typecheck\`)"
+  echo
+  if (cd "$REPO" && bun run typecheck >/dev/null 2>&1); then
+    echo "PASS"
+  else
+    echo "FAIL"
+  fi
+} > "$OUT"
+
+echo "[director] repo-survey wrote $OUT"

package/agents/feat-small/feat-small-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,
@@ -16,9 +17,10 @@ const builder = new AgentBuilder(
   "Implement a new feature described in a markdown user-message file.",
   gitWorktreeSandbox(),
 )
+  .option("branchPrefix", BRANCH_PREFIX_OPTION)
   .add(
     new Prompt(GUIDELINES_PATH)
-      .withSystem(join(PROMPTS, "feat-small.md"))
+      .withSkill("munchkins:feat-small")
       .withUserMessageFromOption("userMessage", {
         required: true,
         description: "Path to a markdown file (or inline text) describing the feature",