pi-plans 0.1.0

package/references/state-and-config.md

@@ -0,0 +1,137 @@
+# State And Config
+
+pi-plans stores all planning preferences and run state in the target workspace's git directory as `<git-common-dir>/pi_plans/` — in an ordinary repository this is simply `.git/pi_plans/` — resolving the git common dir with `git rev-parse --git-common-dir` from the workspace. Because the state lives inside the git dir, git never tracks it and no `.gitignore` entries are needed. The target workspace is the current working directory unless the user explicitly names another repository.
+
+Do not store pi-plans preferences in Pi's own settings (`~/.pi/agent/settings.json`); pi-plans uses `.git/pi_plans/config.json` for its state.
+
+## State Root Resolution
+
+- Git runs with `GIT_DIR`, `GIT_COMMON_DIR`, and `GIT_WORK_TREE` scrubbed from the environment, so leaked env vars cannot misdirect state into an unrelated repository. Relative results (`.git`, `../.git`) resolve against the workdir.
+- Granularity is **per enclosing repository**: running from a subdirectory uses the enclosing repo's git dir (a one-line notice names that repo). Linked worktrees share one common dir; run directories are unique, but `active.json` may race across concurrent worktrees.
+- State does not travel with clones: a fresh clone starts with empty state while committed `./docs/pi-plans/` artifacts persist in the repository.
+
+## Auto Git Init
+
+When a mutating state action (`init`, `set-language`, `set-role`, `start-run`, record-*) runs in a workdir that is not a git repository, the helper auto-runs `git init` there (with a one-line notice) and then creates the state dir. It never creates commits. Auto-init runs only when ALL of the following hold:
+
+- the workdir has no `.git` entry (a pre-existing `.git` file or directory that git cannot resolve is a fatal error, never a silent reinit);
+- the workdir is not inside any git work tree (a subdirectory of a repo uses the enclosing repo instead);
+- the workdir is neither the user's home directory nor the filesystem root.
+
+Bare repositories are refused with a clear error. A missing `git` executable is a clear error. The `show` action is strictly read-only: it never auto-inits or writes.
+
+## Directory Layout
+
+```text
+<git-common-dir>/pi_plans/
+  config.json
+  active.json
+  runs/
+    <run-id>/
+      run.json
+      decisions.jsonl
+      subagents.jsonl
+      refs.jsonl
+  tmp/
+  cache/
+```
+
+`config.json` is stable workspace preference state. `active.json` and `runs/` are run state. Large external references stay outside the repository by default under `~/.cache/pi-plans/refs/`, with metadata recorded in the run state and public artifacts.
+
+## Config Schema
+
+The default config is:
+
+```json
+{
+  "schema": 1,
+  "language": { "tag": null, "source": "unset", "updated_at": null },
+  "reviewer": {
+    "mode": "delegated-subagent",
+    "model_selector": null,
+    "name_prefix": "pi-plans-reviewer",
+    "confirmed_at": null
+  },
+  "criticizer": {
+    "mode": "delegated-subagent",
+    "model_selector": null,
+    "name_prefix": "pi-plans-criticizer",
+    "confirmed_at": null
+  },
+  "artifact_root": "./docs/pi-plans",
+  "artifact_root_source": "unset",
+  "artifact_root_updated_at": null
+}
+```
+
+Rules:
+
+- `schema` must be `1`.
+- `language.tag` is a BCP47-style tag such as `zh-Hans`, `en`, or `zh-Hant`, or `null` before selection; `language.source` is `user`, `auto`, or `unset`.
+- `reviewer.mode` and `criticizer.mode` are `delegated-subagent` or `current-session`.
+- `model_selector` is `null` to inherit the dispatching session's model, or an exact `provider/model` selector matching Pi's model registry.
+- `confirmed_at` is `null` until the user has confirmed the role's model at first use; see below.
+- `artifact_root` is relative to the target workspace unless absolute.
+- `artifact_root_source` is `user`, `auto`, or `unset`.
+- `artifact_root_updated_at` is the selection timestamp or `null` before confirmation.
+- There is intentionally no `effort` field: subagents inherit the dispatching session's model and thinking level unless an exact selector is stored. The real lever is the main session's thinking level at refine time.
+
+## Language Setting
+
+Before the first product planning question, check the persisted config (`plans` action `show`). If `language.tag` is missing or invalid, ask exactly one `ask_choice` question:
+
+1. `zh-Hans` — recommended when more than 60 percent of the user's planning request is Simplified Chinese.
+2. `en` — recommended when the request is mostly English or mixed without a Chinese majority.
+3. `zh-Hant` — Traditional Chinese.
+4. `Other` — user provides a BCP47 tag.
+5. `Auto-complete` — select the recommended language.
+
+Persist with `plans` (`set-language`, `languageSource: "user"`). Use the selected language for visible questions, choices, review summaries, criticizer questions, and Markdown artifacts. Keep IDs, file paths, command names, JSON keys, and protocol labels stable in English.
+
+## Planning Docs Location
+
+Before the first product planning question, check the persisted config again. If `artifact_root_source` is missing or `unset`, ask exactly one `ask_choice` question:
+
+1. `./docs/pi-plans` — recommended; planning docs live in the repository and are public.
+2. `./.git/pi_plans/plans` — private to the repository; not published.
+3. `Other` — user provides a custom path.
+4. `Auto-complete` — select the recommended path.
+
+Persist with `plans` (`set-artifact-root`, `artifactRoot: <selected path>`, `artifactRootSource: "user"` or `"auto"`). Use the selected path for the run's artifact directory root. This question does not count against the planning-question limit.
+
+
+Before running a `refine` round, read the role setting from the persisted config.
+
+If the role's `mode` is missing or invalid, ask exactly one `ask_choice` question and persist:
+
+1. `Delegated subagent` — recommended; read-only `pi` subprocess with isolated context.
+2. `Current session` — run the read-only pass in the current foreground session.
+3. `Other` / 4. `Auto-complete` — select the recommended delegated subagent.
+
+Independently, each role's **model** is confirmed once, at that role's first actual use: when `confirmed_at` is `null` and a `refine` round is about to run, ask exactly one `ask_choice` question:
+
+1. `Inherit the main agent's model` — recommended; stores `model_selector: null`.
+2. `Choose a model` — pick from the models available in this Pi install (check `/model` or `ctx.scopedModels`); persist the exact `provider/model` selector; do not invent model names.
+3. `Other` / 4. `Auto-complete` — select inherit.
+
+Persist with `plans` (`set-role`, `confirmed: true`, `modelSelector: <selector or "inherit">`). `confirmed_at` is set only by this confirmation flow; a mode-only edit never forges or discards a confirmation, and a confirmed inherit (`model_selector: null` plus a stamp) is distinguishable from never-confirmed.
+
+If a spawn later fails because the stored selector is unavailable, reset the marker (`set-role`, `resetConfirmation: true`) and re-ask the confirmation question.
+
+## Subagent Spawning
+
+When `mode` is `delegated-subagent`, the `refine` tool spawns a read-only `pi` subprocess (`--mode json -p --no-session --tools read,grep,find,ls`) whose system prompt comes from `agents/reviewer.md` or `agents/criticizer.md`. The subagent:
+
+- performs read-only analysis and never edits files;
+- receives the full plan text and a review/criticism brief;
+- returns its findings as the tool result (recorded in `subagents.jsonl` with name and model).
+
+The main agent consolidates the results, records dispositions, revises the plan, and asks the next refinement-mode question — all in the same turn.
+
+## Run State
+
+One run directory per planning request: `<git-common-dir>/pi_plans/runs/<YYYYMMDDTHHMMSSZ-topic>/` (second-precision; `-2`, `-3` suffixes on collision).
+
+`run.json` includes: run ID; skill name; original request; target workspace; artifact directory; language tag; status (`planning` → `accepted` → `executing` → `done`, with `stopped`/`abandoned` as exits); timestamps.
+
+`decisions.jsonl` is appended automatically by `ask_choice` (question, options, answer, answer source). `subagents.jsonl` records reviewer/criticizer spawns. `refs.jsonl` records reference metadata via `plans` (`record-ref`).

package/scripts/run-tests.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const testDir = resolve("tests");
+if (!existsSync(testDir)) {
+  console.error(`Missing test directory: ${testDir}`);
+  process.exit(1);
+}
+
+const tests = readdirSync(testDir)
+  .filter((entry) => entry.endsWith(".test.ts"))
+  .sort()
+  .map((entry) => join(testDir, entry));
+
+if (tests.length === 0) {
+  console.error(`No test files found in ${testDir}`);
+  process.exit(1);
+}
+
+const result = spawnSync(process.execPath, ["--experimental-strip-types", "--test", ...tests], {
+  stdio: "inherit",
+});
+
+if (result.error) {
+  throw result.error;
+}
+
+process.exit(result.status ?? 1);

package/scripts/validate.ts

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/** Validate the pi-plans extension structure. */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as url from "node:url";
+
+const ROOT = path.dirname(path.dirname(url.fileURLToPath(import.meta.url)));
+const SKILL_ROOT = path.join(ROOT, "skills");
+const EXPECTED_SKILLS = new Set([
+	"planning",
+	"plan-small",
+	"plan-normal",
+	"plan-big",
+	"plan-with-refs",
+	"debug-and-plan",
+]);
+const REQUIRED_REFERENCES = ["pi-planning-workflow.md", "plan-artifact-template.md", "state-and-config.md"];
+const REQUIRED_AGENTS = ["reviewer.md", "criticizer.md"];
+const REQUIRED_TOOL_FILES = [
+	"tools/plans.ts",
+	"tools/ask-choice.ts",
+	"tools/refine.ts",
+	"tools/execute-plan.ts",
+	"src/state.ts",
+	"src/guard.ts",
+	"src/plan.ts",
+	"src/subagent.ts",
+	"src/exec.ts",
+];
+
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function fail(message: string): never {
+	console.error(message);
+	process.exit(1);
+}
+
+function parseFrontmatter(text: string, file: string): Map<string, string> {
+	if (!text.startsWith("---\n")) fail(`${file}: missing opening frontmatter`);
+	const end = text.indexOf("\n---\n", 3);
+	if (end < 0) fail(`${file}: missing closing frontmatter`);
+	const data = new Map<string, string>();
+	for (const line of text.slice(4, end).split("\n")) {
+		if (!line.trim()) continue;
+		const sep = line.indexOf(":");
+		if (sep < 0) fail(`${file}: invalid frontmatter line ${line!}`);
+		data.set(line.slice(0, sep).trim(), line.slice(sep + 1).trim());
+	}
+	return data;
+}
+
+function validateSkill(dir: string): void {
+	const file = path.join(dir, "SKILL.md");
+	if (!fs.existsSync(file)) fail(`missing ${file}`);
+	const text = fs.readFileSync(file, "utf8");
+	const frontmatter = parseFrontmatter(text, file);
+	const name = frontmatter.get("name") ?? "";
+	const description = frontmatter.get("description") ?? "";
+
+	if (name !== path.basename(dir)) fail(`${file}: name ${name!} must match directory ${path.basename(dir)}`);
+	if (!NAME_RE.test(name) || name.length > 64) fail(`${file}: invalid skill name`);
+	if (!description || description.length > 1024) fail(`${file}: invalid description length`);
+	if (!/Use|MUST USE/.test(description)) fail(`${file}: description should include routing language`);
+
+	const requiredPhrases = ["Auto-complete", "ask_choice", "refine", "language", "reviewer", "criticizer", ".git/pi_plans"];
+	for (const phrase of requiredPhrases) {
+		if (!text.includes(phrase)) fail(`${file}: missing required phrase ${phrase!}`);
+	}
+}
+
+function validateDefaultConfig(): void {
+	const source = fs.readFileSync(path.join(ROOT, "src", "state.ts"), "utf8");
+	if (!source.includes('"pi-plans-reviewer"') || !source.includes('"pi-plans-criticizer"')) {
+		fail("src/state.ts: name_prefix defaults missing");
+	}
+	if (source.includes("effort")) fail("src/state.ts: per-role effort must not exist");
+	if (!source.includes('"delegated-subagent"')) fail("src/state.ts: delegated-subagent default missing");
+	if (!source.includes('artifact_root: DEFAULT_ARTIFACT_ROOT')) fail("src/state.ts: artifact_root default missing");
+	if (!source.includes('artifact_root_source: "unset"')) fail("src/state.ts: artifact_root_source default missing");
+	if (!source.includes('artifact_root_updated_at: null')) fail("src/state.ts: artifact_root_updated_at default missing");
+}
+
+interface PackageJson {
+	private?: boolean;
+	keywords?: unknown[];
+	publishConfig?: { access?: string };
+	pi?: { extensions?: unknown[]; skills?: unknown[] };
+	files?: unknown[];
+	engines?: { node?: string };
+	scripts?: { test?: string; prepack?: string };
+	license?: string;
+}
+
+function normalizePackageEntry(value: unknown): string {
+	return String(value).replace(/\/$/, "");
+}
+
+function validatePlansTool(): void {
+	const source = fs.readFileSync(path.join(ROOT, "tools", "plans.ts"), "utf8");
+	if (!source.includes('"set-artifact-root"')) fail("tools/plans.ts: set-artifact-root action missing");
+	if (!source.includes("artifactRootSource")) fail("tools/plans.ts: artifactRootSource parameter missing");
+}
+
+function validatePackageMetadata(): void {
+	const pkgPath = path.join(ROOT, "package.json");
+	let pkg: PackageJson;
+	try {
+		pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as PackageJson;
+	} catch (error) {
+		fail(`package.json: invalid JSON: ${(error as Error).message}`);
+	}
+
+	if (pkg.private === true) fail("package.json: private must be removed or false for npm publish");
+	if (pkg.license !== "MIT") fail("package.json: license must be MIT");
+	if (pkg.publishConfig?.access !== "public") fail("package.json: publishConfig.access must be public");
+	if (!Array.isArray(pkg.keywords) || !pkg.keywords.map(String).includes("pi-package")) {
+		fail("package.json: missing pi-package keyword");
+	}
+
+	const pi = pkg.pi ?? {};
+	const extensions = new Set((pi.extensions ?? []).map(normalizePackageEntry));
+	const skills = new Set((pi.skills ?? []).map(normalizePackageEntry));
+	if (!extensions.has("./index.ts")) fail("package.json: pi.extensions must include ./index.ts");
+	if (!skills.has("./skills")) fail("package.json: pi.skills must include ./skills");
+
+	const files = new Set((pkg.files ?? []).map(normalizePackageEntry));
+	for (const required of ["README.md", "LICENSE", "index.ts", "agents", "references", "scripts", "skills", "src", "tests", "tools"]) {
+		if (!files.has(required)) fail(`package.json: files must include ${required}`);
+	}
+
+	if (pkg.engines?.node !== ">=22.6") fail("package.json: engines.node must be >=22.6");
+	if (pkg.scripts?.test !== "node --experimental-strip-types scripts/run-tests.ts") {
+		fail("package.json: test script must use scripts/run-tests.ts");
+	}
+	if (pkg.scripts?.prepack !== "npm run validate && npm test") {
+		fail("package.json: prepack must run validate and test");
+	}
+}
+
+function main(): void {
+	const found = new Set(
+		fs
+			.readdirSync(SKILL_ROOT, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => entry.name),
+	);
+	const missing = [...EXPECTED_SKILLS].filter((skill) => !found.has(skill));
+	const extra = [...found].filter((skill) => !EXPECTED_SKILLS.has(skill));
+	if (missing.length || extra.length) {
+		fail(`skill set mismatch; missing=${missing.join(",")} extra=${extra.join(",")}`);
+	}
+	for (const skill of [...EXPECTED_SKILLS].sort()) {
+		validateSkill(path.join(SKILL_ROOT, skill));
+	}
+
+	for (const ref of REQUIRED_REFERENCES) {
+		const file = path.join(ROOT, "references", ref);
+		if (!fs.existsSync(file)) fail(`missing reference ${ref}`);
+		if (!fs.readFileSync(file, "utf8").includes(".git/pi_plans")) {
+			fail(`${ref}: missing .git/pi_plans state location`);
+		}
+	}
+
+	for (const agent of REQUIRED_AGENTS) {
+		const file = path.join(ROOT, "agents", agent);
+		if (!fs.existsSync(file)) fail(`missing agent ${agent}`);
+		const text = fs.readFileSync(file, "utf8");
+		if (!/tools:\s*read/.test(text)) fail(`${agent}: must declare read-only tools`);
+		if (!text.includes("read-only")) fail(`${agent}: must state read-only contract`);
+	}
+
+	for (const tool of REQUIRED_TOOL_FILES) {
+		if (!fs.existsSync(path.join(ROOT, tool))) fail(`missing ${tool}`);
+	}
+
+	if (!fs.existsSync(path.join(ROOT, "index.ts"))) fail("missing index.ts");
+
+	validateDefaultConfig();
+	validatePlansTool();
+	validatePackageMetadata();
+	console.log(`validated ${EXPECTED_SKILLS.size} skills, ${REQUIRED_REFERENCES.length} references, ${REQUIRED_AGENTS.length} agents, ${REQUIRED_TOOL_FILES.length} tools`);
+}
+
+main();

package/skills/debug-and-plan/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: debug-and-plan
+description: Diagnose failures before creating a Pi plan. MUST USE for bugs, CI failures, test failures, regressions, incidents, broken behavior, root cause, RCA, or debug-why requests before deciding whether to plan; preserve language, reviewer, and criticizer settings in `.git/pi_plans/config.json`; exclude ordinary feature planning, direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
+---
+
+# Debug And Plan
+
+Use this skill for problem or failure inputs that need diagnosis before planning.
+
+## Pi Setup
+
+Read `../../references/pi-planning-workflow.md` and `../../references/state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer/criticizer rules. Initialize workspace state with the `plans` tool (`action: "init"`); state lives in `.git/pi_plans/`. Ask every question with the `ask_choice` tool; run refinement rounds with the `refine` tool.
+
+## Diagnostic Workflow
+
+1. Inspect available evidence first: repository files, logs, tests, command output, stack traces, recent diffs, CI output, environment details, and user-provided symptoms.
+2. Produce an in-message RCA summary before asking whether to plan. Use at most 5 Whys. Stop with `unknown` when evidence is insufficient; do not invent a cause.
+3. Ask one `ask_choice` question in the configured language whose preamble includes the RCA summary, with these options:
+   1. `Create the scoped fix plan` — recommended when evidence supports a planning path.
+   2. `Stop after RCA` — keep the diagnosis only.
+   3. `Other` / 4. `Auto-complete` are added by the tool.
+4. On opt-out, stop after the summary; do not write `PROBLEM_ANALYSIS.md`.
+5. On opt-in (or `Auto-complete` choosing the recommendation), select the smallest fitting planning skill and follow that skill exactly: first-turn planning question, final scope confirmation, `PLAN_v1.md`, refinement, and the execution handoff (ask_choice with `autoComplete: false`, then the `execute_plan` tool).
+
+## Level Selection
+
+- `plan-small`: clear root cause, obvious fix shape, few local files, limited risk.
+- `plan-normal`: multi-file fix, external API or dependency behavior, compatibility concerns, or research needed.
+- `plan-big`: cross-system failure, unclear root cause, redesign pressure, or high safety/recoverability risk.
+
+Do not ask the user to choose the level unless the evidence supports two materially different planning depths and the tradeoff cannot be resolved from the repo.
+
+## PROBLEM_ANALYSIS.md
+
+After opt-in, create the selected planning run's `.git/pi_plans` state and public artifact directory (`plans` action `start-run`), then write `PROBLEM_ANALYSIS.md` before `PLAN_v1.md`. Include: original problem; symptoms and reproduction status; evidence inspected; RCA summary and 5 Whys (ending early with `unknown` when evidence stops); suspected root cause and confidence; planning skill selected and why; language, reviewer, and criticizer settings used; open diagnostic gaps the plan must address. Pass the original problem, RCA summary, evidence, and `PROBLEM_ANALYSIS.md` path into the selected planning skill.

package/skills/plan-big/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: plan-big
+description: Create a large Pi plan before implementation. Use for open-ended or high-risk repo efforts needing 10 or more planning questions, web research, concurrent reviewer or criticizer refinement, and refinement until convergence; exclude direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
+---
+
+# Plan Big
+
+Use this skill when the user wants a large, high-risk, or open-ended plan before a repository change.
+
+## Pi Setup
+
+Read `../../references/pi-planning-workflow.md` and `../../references/state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer/criticizer rules. Initialize workspace state with the `plans` tool (`action: "init"`); state lives in `.git/pi_plans/`. Ask every question with the `ask_choice` tool; run refinement rounds with the `refine` tool.
+
+## Depth Contract
+
+- Inspect the target Git repo read-only before the first product question.
+- Ask at least 10 planning questions, one at a time; no maximum — stop only when the decision tree is genuinely resolved. Each via `ask_choice` (recommended option first; the tool adds `Other` second-last and `Auto-complete` last).
+- Use web research during both brainstorming and refinement when outside facts, patterns, or ecosystem constraints matter, and cite sources in the plan.
+- Ask the final scope confirmation, then write `PLAN_v1.md` per `../../references/plan-artifact-template.md`.
+- After each plan version, ask the refinement-mode question via `ask_choice` — never run `refine` unless the user or `Auto-complete` selected it at that question. Default sequence: one `Reviewer` round as three concurrent independent reviewers (`refine` with `reviewers: 3`, consolidated by the main agent per the shared workflow), then one `Criticizer` round; afterwards the recommended option is `Accept plan for tracked execution`. Beyond the default sequence, refine until convergence on high-priority findings, unresolved questions, or evidence gaps; surface at most five per round. Then the execution handoff (ask_choice with `autoComplete: false`, then the `execute_plan` tool).
+
+## Fit
+
+New systems, large feature surfaces, cross-repository or cross-service work, open-ended architecture, safety-sensitive changes, unclear user workflows, or plans whose shape is not yet known. Use `plan-with-refs` instead when external projects, papers, articles, or documentation must be downloaded and studied before planning choices are safe.

package/skills/plan-normal/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: plan-normal
+description: Create a researched Pi plan before implementation. Use for broad or risky repo changes needing 5 to 10 planning questions, web research, reviewer or criticizer refinement, and bounded refinement; exclude direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
+---
+
+# Plan Normal
+
+Use this skill when the user wants a substantive plan before a repository change.
+
+## Pi Setup
+
+Read `../../references/pi-planning-workflow.md` and `../../references/state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer/criticizer rules. Initialize workspace state with the `plans` tool (`action: "init"`); state lives in `.git/pi_plans/`. Ask every question with the `ask_choice` tool; run refinement rounds with the `refine` tool.
+
+## Depth Contract
+
+- Inspect the target Git repo read-only before the first product question.
+- Ask 5 to 10 planning questions, one at a time, each via `ask_choice` (recommended option first; the tool adds `Other` second-last and `Auto-complete` last).
+- Use web research whenever outside library behavior, ecosystem precedent, UX convention, protocol semantics, or compatibility affects the recommendation (websearch skill when installed; otherwise `curl`/`gh` via bash), and cite sources in the plan.
+- Ask the final scope confirmation, then write `PLAN_v1.md` per `../../references/plan-artifact-template.md`.
+- After each plan version, ask the refinement-mode question via `ask_choice` — never run `refine` unless the user or `Auto-complete` selected it at that question. Default sequence: one `Reviewer` round, then one `Criticizer` round; afterwards the recommended option is `Accept plan for tracked execution`. Up to five rounds total, continuing only for high-priority findings or unresolved criticizer questions; surface at most five per round. Then the execution handoff (ask_choice with `autoComplete: false`, then the `execute_plan` tool).
+
+## Fit
+
+Multi-file changes, architecture boundaries, user-facing workflows, external APIs, dependency upgrades, compatibility risk, or web-evidence-shaped plans. Escalate to `plan-big` when open-ended, cross-system, strategically ambiguous, or likely beyond ten planning decisions.

package/skills/plan-small/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: plan-small
+description: Create a small Pi plan before implementation. Use for small scoped repo changes needing 1 to 3 planning questions and one criticizer refinement pass; exclude direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
+---
+
+# Plan Small
+
+Use this skill when the user wants a compact plan before a repository change.
+
+## Pi Setup
+
+Read `../../references/pi-planning-workflow.md` and `../../references/state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer/criticizer rules. Initialize workspace state with the `plans` tool (`action: "init"`); state lives in `.git/pi_plans/`. Ask every question with the `ask_choice` tool; run the refinement round with the `refine` tool.
+
+## Depth Contract
+
+- Inspect the target Git repo read-only before the first product question.
+- Ask 1 to 3 planning questions, one at a time, each via `ask_choice` (recommended option first; the tool adds `Other` second-last and `Auto-complete` last).
+- Ask the final scope confirmation, then write `PLAN_v1.md` under the artifact root (normally the configured workspace root, default `./docs/pi-plans/YYYY-MM-DD-topic/`) per `../../references/plan-artifact-template.md`.
+- After each plan version, ask the refinement-mode question via `ask_choice` — never run `refine` unless the user or `Auto-complete` selected it at that question. Default: exactly one round, recommended mode `Criticizer`; afterwards the recommended option is `Accept plan for tracked execution`, then the execution handoff (ask_choice with `autoComplete: false`, then the `execute_plan` tool).
+
+## Fit
+
+A few local files, clear ownership, low risk, focused verification. Escalate to `plan-normal` for external API semantics, dependency behavior, compatibility research, cross-module design, or more than three meaningful decisions.

package/skills/plan-with-refs/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: plan-with-refs
+description: Research references before creating a Pi plan. Use when repo-change planning needs downloaded projects, articles, papers, docs, per-reference analysis, adoption questions, language settings, and reviewer or criticizer refinement; exclude direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.
+---
+
+# Plan With Refs
+
+Use this skill when external references must shape the plan before implementation.
+
+## Pi Setup
+
+Read `../../references/pi-planning-workflow.md` and `../../references/state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer/criticizer rules. Initialize workspace state with the `plans` tool (`action: "init"`); state lives in `.git/pi_plans/`. Ask every question with the `ask_choice` tool; run refinement rounds with the `refine` tool.
+
+## Required Reference Flow
+
+1. Inspect the target Git repo read-only before external research so search terms match the actual codebase and constraints.
+2. Create the `.git/pi_plans` run state and planning artifact directory once the topic is clear (`plans` action `start-run`).
+3. Search proactively for related projects, articles, papers, docs, and prior art. Prefer a websearch skill when installed; otherwise use bash tools such as `curl` or `gh` when already available.
+4. Download or clone at least 3 credible references before writing `PLAN_v1.md`; store large downloads outside the target repo under `~/.cache/pi-plans/refs/<repo-slug>/<topic>/`. Landing pages, README-only snapshots, abstracts, package metadata, or curl-only fragments do not count when deeper source material is available.
+5. For every reference, record source metadata and local path in `REF_ANALYSIS.md` and in the run's `refs.jsonl` (via `plans` action `record-ref`): title, URL, kind, retrieval method, date accessed, local path, coverage, and evidence gaps.
+6. For every reference, produce a structured analysis artifact (manual structured read recorded in `REF_ANALYSIS.md`) before asking adoption questions.
+7. For every reference after analysis, ask at least 3 ref-specific adoption questions via `ask_choice` before using its ideas in `PLAN_v1.md`; each based on downloaded content, recommended option first, `Other` second-last, `Auto-complete` last (the tool appends both).
+8. Block rather than pad if fewer than 3 credible references exist, unless the user explicitly narrows the topic or waives the minimum. `Auto-complete` cannot grant this waiver.
+9. Continue with big-plan depth: at least 10 planning questions, required web research during brainstorming and refinement (`refine` `reviewers: 3` reviewer round, then a criticizer round), no refinement limit, at most five high-priority comments or questions per refinement round. Then the execution handoff (ask_choice with `autoComplete: false`, then the `execute_plan` tool).
+
+## REF_ANALYSIS.md
+
+Include: original request and repo evidence that shaped the search; attempted queries and selection criteria; references selected and rejected; local download paths; structured analysis summaries; adoption questions and recorded answers; accepted ideas, rejected ideas, and reasons; evidence gaps and user-granted waivers; language, reviewer, and criticizer settings used.
+
+Reference ideas are not eligible for `PLAN_v1.md` until their adoption question answers are recorded.

package/skills/planning/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: planning
+description: General planning router for pi-plans. Use when the user asks for planning and you need to choose the narrowest specialist skill among plan-small, plan-normal, plan-big, debug-and-plan, and plan-with-refs.
+---
+
+# Planning Router
+
+Use this skill when a task is planning-related but the right specialist is not obvious yet.
+
+## Routing
+
+1. If the request is a bug, CI failure, regression, incident, or debug-why case, route to `debug-and-plan`.
+2. If the plan depends on external projects, articles, papers, or docs, route to `plan-with-refs`.
+3. If the work is open-ended, cross-system, high-risk, or likely beyond ten decisions, route to `plan-big`.
+4. If the work is broad or risky but bounded, route to `plan-normal`.
+5. Otherwise route to `plan-small`.
+6. If multiple skills fit, choose the smallest one that still covers the risk.
+7. Then follow that skill's instructions exactly.
+
+## Pi Setup
+
+Use the same language, `ask_choice`, `refine`, reviewer, criticizer, Auto-complete, and `.git/pi_plans` rules as the selected specialist skill and the shared workflow.