@gavin-hu/my-pi-agent 0.14.0 → 0.15.0

package/lib/tui/tool.ts

@@ -19,7 +19,7 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, truncateToWidth } from "@earendil-works/pi-tui";
 import { formatDuration, sanitizeLine, stripControlChars } from "../format.ts";
-import { clipMiddle } from "./columns.ts";
+import { clip, clipMiddle } from "./columns.ts";
 import { expandHint, SEPARATORS } from "./glyphs.ts";
 import { paint } from "./tokens.ts";
 
@@ -134,6 +134,64 @@ export function moreHint(theme: Theme, hidden: number, noun = "lines"): string {
 	return `${paint(theme, "faint", `… ${hidden} more ${noun}`)} ${expandHint(theme)}`;
 }
 
+/** `… N more` and the expand affordance, for a list whose rows are items. */
+export function overflowHint(theme: Theme, hidden: number): string {
+	return `${paint(theme, "faint", `… ${hidden} more`)} ${expandHint(theme)}`;
+}
+
+/** `… N earlier <label>` and the expand affordance, for a bounded tail. */
+export function earlierHint(theme: Theme, hidden: number, label: string): string {
+	return `${paint(theme, "faint", `… ${hidden} earlier ${label}`)} ${expandHint(theme)}`;
+}
+
+/** The row renderer a {@link TailResult} list uses: the extension's row grammar at a width. */
+export type TailRowLine<Row> = (row: Row, width: number, theme: Theme) => string;
+
+/** What a {@link TailResult} draws: the caller's rows plus a hidden count, or a bounded tail. */
+export type TailResultInput<Row> =
+	| { kind: "list"; rows: readonly Row[]; more: number; rowLine: TailRowLine<Row> }
+	| { kind: "lines"; lines: readonly string[]; earlier: number; earlierLabel: string };
+
+/**
+ * The transcript result block a tool that lists rows or tails output shares.
+ *
+ * One leading blank line per the block grammar, then either the caller's rows
+ * (already ordered and capped) with a "more" note, or the themed tail with an
+ * "earlier" note. The caller owns the row renderer, so the extension's own row
+ * grammar — a peer-session tag, a status glyph — stays with its vocabulary.
+ */
+export class TailResult<Row> implements Component {
+	private input: TailResultInput<Row>;
+	private theme: Theme;
+
+	constructor(input: TailResultInput<Row>, theme: Theme) {
+		this.input = input;
+		this.theme = theme;
+	}
+
+	/** Update in place so the transcript can reuse this component across renders. */
+	setInput(input: TailResultInput<Row>, theme: Theme): void {
+		this.input = input;
+		this.theme = theme;
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const w = Math.max(1, width);
+		const lines: string[] = [""];
+		const input = this.input;
+		if (input.kind === "list") {
+			for (const row of input.rows) lines.push(input.rowLine(row, w, this.theme));
+			if (input.more > 0) lines.push(clip(`  ${overflowHint(this.theme, input.more)}`, w));
+			return lines;
+		}
+		if (input.earlier > 0) lines.push(clip(earlierHint(this.theme, input.earlier, input.earlierLabel), w));
+		for (const line of input.lines) lines.push(this.theme.fg("toolOutput", clip(line, w)));
+		return lines;
+	}
+}
+
 /** The render context fields the elapsed timer needs. */
 export interface ToolRenderClock {
 	/** Pi's per-call render state, opaque here: this module only ever casts it. */

package/lib/web/components.ts

@@ -59,6 +59,12 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .bf-dialog__option{padding:var(--space-1) var(--space-4);font:var(--fs-sm) var(--font-mono);cursor:pointer;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
 .bf-dialog__option[aria-selected="true"]{background:var(--accent-soft);color:var(--accent)}
 .bf-dialog mark{background:transparent;color:var(--warn);font-weight:var(--fw-semibold)}
+.bf-dialog__head{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-3) var(--space-4);border-bottom:1px solid var(--border)}
+.bf-dialog__head h2{margin:0;font-size:var(--fs-lg)}
+.bf-keys{display:grid;grid-template-columns:auto 1fr;gap:8px var(--space-4);margin:0;padding:var(--space-4)}
+.bf-keys dt{white-space:nowrap}
+.bf-keys dd{margin:0;color:var(--muted);font-size:var(--fs-sm)}
+.bf-kbd{display:inline-block;min-width:20px;padding:1px 6px;border:1px solid var(--border);border-bottom-width:2px;border-radius:var(--radius-sm);background:var(--surface);color:var(--text);font:var(--fs-xs) var(--font-mono);text-align:center}
 .bf-tree{font-family:var(--font-mono);font-size:var(--fs-sm);overflow-x:auto}
 .bf-tree ul{list-style:none;margin:0;padding-left:14px}
 .bf-tree>ul{padding-left:0}
@@ -114,8 +120,13 @@ th[aria-sort="descending"] .bf-sort::after{content:" \\25BC";font-size:9px;color
 .bf-md pre code{background:none;border:0;padding:0}
 .bf-md blockquote{margin-left:0;padding:0 1em;border-left:3px solid var(--border);color:var(--muted)}
 .bf-md li.task{list-style:none;margin-left:-1.4em}
-.bf-md .md-check{color:var(--success)}
+/* The boxes are drawn rather than left native: a disabled native checkbox is UA
+   gray in both themes, so the done state could not carry the success colour. */
+.bf-md .md-check{appearance:none;-webkit-appearance:none;width:13px;height:13px;margin:0 5px 0 0;border:1px solid var(--border-strong);border-radius:3px;background:var(--canvas);vertical-align:-2px}
+.bf-md .md-check:checked{border-color:var(--success);background:var(--success) url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M3.5 8.5l3 3 6-7' fill='none' stroke='%23fff' stroke-width='2.4' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center/11px 11px no-repeat}
+.bf-md .md-check:disabled{opacity:1}
 .bf-md table{margin:0;border-collapse:collapse;table-layout:auto;width:auto;font-size:var(--fs-sm)}
+.bf-md .md-table-frame{position:relative}
 .bf-md .md-table-wrap{overflow-x:auto;margin:0 0 1em}
 .bf-md th,.bf-md td{border:1px solid var(--border);padding:6px 10px;text-align:left;vertical-align:top;overflow-wrap:break-word}
 .bf-md th{white-space:nowrap}
@@ -126,6 +137,14 @@ th[aria-sort="descending"] .bf-sort::after{content:" \\25BC";font-size:9px;color
 .bf-md .md-right{text-align:right}
 .bf-md img{max-width:100%;height:auto;border-radius:var(--radius-sm)}
 .bf-md hr{border:0;border-top:1px solid var(--border);margin:1.4em 0}
+.bf-md details{margin:0 0 1em}
+.bf-md summary{cursor:pointer;font-weight:var(--fw-medium)}
+.bf-md figure{margin:0 0 1em}
+.bf-md figcaption{color:var(--muted);font-size:var(--fs-sm)}
+.bf-md kbd{font-family:var(--font-mono);font-size:.85em;background:var(--canvas);border:1px solid var(--border);border-bottom-width:2px;border-radius:var(--radius-sm);padding:.1em .35em}
+.bf-md mark{background:var(--accent-soft);color:inherit;padding:0 .1em}
+.bf-md abbr[title]{text-decoration:underline dotted;cursor:help}
+.bf-md sub,.bf-md sup{font-size:.75em;line-height:0}
 .bf-comment{padding:var(--space-3) var(--space-4);background:var(--surface);border:1px solid var(--border);border-left:3px solid var(--warn);border-radius:var(--radius-md)}
 .bf-comment__quote{margin-bottom:var(--space-1);color:var(--muted);font-size:var(--fs-xs);overflow-wrap:anywhere}
 .bf-comment__body{white-space:pre-wrap;overflow-wrap:anywhere}

package/lib/web/markup.ts

@@ -97,3 +97,35 @@ export function button(options: ButtonOptions): string {
 	const rendered = attrs.map(([key, value]) => ` ${key}="${escapeHtml(value)}"`).join("");
 	return `<button type="button" class="${classes}"${rendered}>${escapeHtml(options.label)}</button>`;
 }
+
+/** One row of the keyboard sheet: the key or chord, and what it does. */
+export interface KeyHint {
+	/** The key or chord, one `<kbd>` per entry; a single string is one key, chord, or alias run. */
+	keys: string | readonly string[];
+	/** What the key does. */
+	label: string;
+}
+
+/**
+ * The `?` keyboard sheet: the dialog of key/label rows both pages share, hidden
+ * until the client opens it.
+ *
+ * The ids are the contract with `keysDialogScript` in `runtime.ts` — `#keys-dialog`
+ * for the sheet, `#keys-close` for its own close button — and the trigger button
+ * is the page's own concern, since the two pages name it differently.
+ */
+export function keysSheet(rows: readonly KeyHint[]): string {
+	const kbd = (key: string): string => `<kbd class="bf-kbd">${escapeHtml(key)}</kbd>`;
+	const body = rows
+		.map((row) => {
+			const keys = typeof row.keys === "string" ? kbd(row.keys) : row.keys.map(kbd).join(" ");
+			return `<div><dt>${keys}</dt><dd>${escapeHtml(row.label)}</dd></div>`;
+		})
+		.join("\n");
+	return `<div class="bf-dialog" id="keys-dialog" hidden>
+<div class="bf-dialog__panel" role="dialog" aria-modal="true" aria-labelledby="keys-title">
+<div class="bf-dialog__head"><h2 id="keys-title">Keyboard shortcuts</h2><span class="bf-spacer"></span><button type="button" class="bf-btn" id="keys-close">Close</button></div>
+<dl class="bf-keys">${body}</dl>
+</div>
+</div>`;
+}

package/lib/web/runtime.ts

@@ -66,3 +66,53 @@ export const THEME_TOGGLE_JS = String.raw`(function () {
     else if (query.addListener) query.addListener(sync);
   }
 })();`;
+
+/**
+ * The `?` keyboard sheet's wiring, shared by both clients.
+ *
+ * It owns the sheet's pointer behavior — the page's trigger button, the sheet's
+ * own close button, and a click on the backdrop — and nothing else: each page
+ * keeps its own keyboard policy in its keydown handler, because the two differ
+ * (the review peels `Esc` through a composer first), and calls in through
+ * `window.bfKeys`.
+ *
+ * `triggerId` is the page's own shortcut button, since browse opens the sheet
+ * from `#keys-open` and review from `#shortcuts`. The sheet's ids are the fixed
+ * contract in `keysSheet` (`lib/web/markup.ts`).
+ *
+ * Value-only: the open state is the dialog's own `hidden` attribute, so this
+ * module holds nothing.
+ */
+export function keysDialogScript(triggerId: string): string {
+	return `(function () {
+  "use strict";
+  var dialog = document.getElementById("keys-dialog");
+  if (!dialog) return;
+
+  function isOpen() {
+    return !dialog.hidden;
+  }
+  function toggle(force) {
+    var open = force === undefined ? dialog.hidden : force;
+    dialog.hidden = !open;
+    if (open) {
+      var close = document.getElementById("keys-close");
+      if (close && close.focus) close.focus();
+    }
+  }
+
+  var trigger = document.getElementById("${triggerId}");
+  if (trigger) trigger.addEventListener("click", function () { toggle(); });
+  var closer = document.getElementById("keys-close");
+  if (closer) closer.addEventListener("click", function () { toggle(false); });
+  dialog.addEventListener("click", function (event) {
+    if (event.target === dialog) toggle(false);
+  });
+
+  window.bfKeys = {
+    toggle: toggle,
+    close: function () { toggle(false); },
+    isOpen: isOpen
+  };
+})();`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.14.0",
-  "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, document, memory, wechat, and bytefly.",
+  "version": "0.15.0",
+  "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, document, check, memory, wechat, and bytefly.",
   "keywords": [
     "pi-package",
     "pi",
@@ -11,6 +11,11 @@
     "goal",
     "objective",
     "plan",
+    "question",
+    "init",
+    "agents-md",
+    "refactor",
+    "skill",
     "subagent",
     "agents",
     "delegation",
@@ -45,11 +50,17 @@
     "read_doc",
     "memory",
     "cross-session",
+    "wechat",
     "web-access",
     "bytefly",
     "footer",
     "separator",
-    "transcript"
+    "transcript",
+    "check",
+    "test",
+    "lint",
+    "typecheck",
+    "verification"
   ],
   "type": "module",
   "license": "MIT",
@@ -61,6 +72,7 @@
   "files": [
     "extensions/**",
     "lib/**",
+    "skills/**",
     "themes/**",
     "!**/*.test.ts"
   ],
@@ -76,6 +88,7 @@
       "./extensions/todo/index.ts",
       "./extensions/goal/index.ts",
       "./extensions/plan/index.ts",
+      "./extensions/check/index.ts",
       "./extensions/subagent/index.ts",
       "./extensions/job/index.ts",
       "./extensions/watch/index.ts",
@@ -87,6 +100,9 @@
       "./extensions/wechat/index.ts",
       "./extensions/bytefly/index.ts"
     ],
+    "skills": [
+      "./skills"
+    ],
     "themes": [
       "./themes/*.json"
     ],
@@ -99,8 +115,9 @@
     "typecheck": "tsc --noEmit",
     "format": "biome format --write .",
     "format:check": "biome format .",
-    "check": "bun run format:check && bun run typecheck && bun run test",
-    "check:serial": "bun run format:check && bun run typecheck && bun run test:serial",
+    "check:static": "bun run format:check && bun run typecheck",
+    "check": "bun run check:static && bun run test",
+    "check:serial": "bun run check:static && bun run test:serial",
     "release:notes": "bun run scripts/release-notes.ts",
     "config:migrate": "bun run scripts/migrate-config.ts",
     "compat:versions": "bun run scripts/peer-versions.ts",

package/skills/init/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: init
+description: "Initialize or refresh AGENTS.md through a built-in interactive interview and a reviewed plan. Use when the user runs /skill:init or asks to set up project agent instructions."
+disable-model-invocation: true
+---
+
+# Initialize AGENTS.md
+
+Goal: create or update **`AGENTS.md` at the project root** by combining repository
+evidence with a short, built-in interview. The interview captures intent the code
+cannot show; the repository supplies every command, path, and convention that can
+be verified. Plan mode is the review gate: no write happens before approval.
+
+`/skill:init` loads this skill. If plan mode is not active, call
+`enter_plan_mode` and wait for confirmation. Keep the interview and the plan
+review in that order; do not write the file early to save a step.
+
+## Workflow
+
+```text
+/skill:init
+  └─> plan mode (read-only)
+        └─> recon: manifests, docs, CI, tests, existing instructions
+        └─> interview: one built-in question call (at most 4)
+              ├─ answers ───────────────> reconcile with evidence
+              └─ unavailable/cancelled ─> evidence + recorded assumptions
+        └─> draft: new file, exact edits, or an honest no-op
+        └─> quality gate
+        └─> write_plan ──> exit_plan_mode
+                             ├─ not approved ──> refine the same plan
+                             └─ approved ──────> write/edit AGENTS.md
+                                                 └─ read back + quality gate
+```
+
+Read [`references/interview-questions.md`](./references/interview-questions.md)
+before the interview. Read
+[`references/agents-md-quality.md`](./references/agents-md-quality.md) before
+drafting and again before writing the plan.
+
+## Repository states
+
+| State | Interview | Outcome |
+|---|---|---|
+| Existing project, no `AGENTS.md` | Purpose (only if unclear; otherwise Priorities), Verify, Rules, Isolation | New smallest-useful file. |
+| Existing `AGENTS.md` | Existing file, Preserve (only if sections are unclear), Priorities (only if stale), Rules | Exact edits that preserve correct instructions, or a no-op. |
+| Empty or near-empty repository | Stack, Commands, Purpose, Priorities | Honest minimal file from the answers and known facts only. |
+| Related instruction files exist | Swap Related docs in for Preserve or Rules | Describe the relationship; do not duplicate the other file. |
+| Git repository with no guidance | Isolation, Verify, Done, External changes | Prefer this set over a generic workflow question. |
+| No UI, inactive tool, or cancelled interview | Skip the call; record the gaps as assumptions | Evidence-based draft; the plan review remains the place to correct it. |
+
+The full bank, selectable alternatives, and option wording live in
+`references/interview-questions.md`. The table above is the default, not a menu to
+exhaust.
+
+## 1. Recon
+
+- Read existing instruction files first: `AGENTS.md`, `AGENTS.override.md`,
+  `CLAUDE.md`, and nested `AGENTS.md` files. Note how they relate; do not silently
+  absorb or replace one.
+- Read the files that define the project: manifests, lockfiles, README, docs
+  index, source layout, tests, CI, formatter and linter configuration.
+- Build a short evidence sheet: stack, layout, install/test/lint/typecheck
+  commands, validation gates, release path, and existing rules.
+- List the gaps the interview must fill. Stop the first pass once the shape is
+  clear; do not investigate the whole repository before asking.
+- In an empty or near-empty repository, record that evidence is absent. Never
+  invent a command from a language's usual tooling.
+- Check that any command you plan to record is copied from a file that defines it.
+- Use `read`, `grep`, `find`, and `ls`. For a large repository, delegate a
+  read-only survey to the `explorer` or `reviewer` subagent.
+- Do not read or copy secrets, credentials, tokens, or private environment
+  values. If a file looks like a secret store, stop reading it.
+
+## 2. Interview
+
+Use `ask_user_question` once with at most four questions from the built-in bank.
+Choose the deterministic default set for the repository state.
+
+- One call is the default. Make a second call only when an answer leaves a
+  material ambiguity that changes what the file says; do not ask a second round
+  merely to collect preferences.
+- Fill option labels with evidence: the detected test command, the actual package
+  manager, the real instruction file names. Keep a free-form escape on every
+  question whose answer cannot be enumerated.
+- Ask only what the evidence cannot answer. Do not ask for the stack when a
+  manifest states it, or for a command already documented in CI.
+- Never ask for secrets, credentials, tokens, environment values, or personal
+  data.
+- If the answers contradict the repository, keep the conflict visible in the plan
+  instead of silently choosing a side.
+- If the user cancels or the tool is unavailable, continue from evidence and
+  record each unanswered gap under assumptions in the plan. In an empty
+  repository this means an explicit skeleton that says it is newly initialized,
+  with no guessed commands.
+- A follow-up question that is cancelled keeps the first round's answers.
+
+## 3. Reconcile and draft
+
+Treat answers and evidence as different kinds of fact:
+
+- Commands, paths, package names, and existing behavior come from the repository.
+- Purpose, priorities, scope, workflow, and preferences come from the user.
+- If they conflict, record the conflict, what the draft uses, and the alternative
+  in the plan. Do not quietly rewrite the user's intent or invent a command to
+  match it.
+
+Then choose the outcome:
+
+- **No `AGENTS.md`** — draft the smallest useful file. Use the sections this
+  repository needs; omit empty ones.
+- **Existing `AGENTS.md`** — preserve correct instructions and propose exact
+  edits for the rest. If the user chose to rewrite, the plan must still list what
+  is being removed.
+- **Accurate `AGENTS.md`** — propose no edits and explain the no-op with evidence.
+- **Empty or near-empty repository** — say plainly that it is newly initialized,
+  record the interview facts, and omit commands and architecture that do not
+  exist yet.
+- **Related instruction files** — state the relationship and link them instead of
+  copying their content.
+
+Prefer short rules over prose. One instruction should have one job. Link deep
+documentation rather than restating it.
+
+## 4. Pass the quality gate
+
+Read `references/agents-md-quality.md` before drafting and again before saving the
+plan. Revise a draft that fails the checklist rather than shipping it.
+
+For a large or unfamiliar repository, optionally ask the read-only `reviewer`
+subagent to critique the draft against the checklist. Use its findings as
+evidence, not as a replacement for reading the repository.
+
+## 5. Plan and review
+
+- Save the proposal with `write_plan`. The plan must include:
+  - the recon summary and the evidence that supports the draft;
+  - the questions asked, the answers, and how each answer was used;
+  - the full draft for a new file, or the exact edits for an existing one;
+  - assumptions, conflicts, and unanswered gaps from a cancelled or unavailable
+    interview;
+  - a verification step that reads the written file back against the checklist.
+- Call `exit_plan_mode` with the returned path.
+- If the user refines or rejects the plan, stay in plan mode, rewrite the same
+  plan file with `write_plan` (`plan_path`), and present it again.
+- No `AGENTS.md` write may happen before approval.
+
+## 6. Apply and verify
+
+- Create a new file with `write`, or update an existing one with `edit`.
+- Change only `AGENTS.md`. Do not touch unrelated files.
+- Read the result back from disk and rerun the quality checklist against what is
+  actually there, not what you intended to write.
+- Report the path, what the file covers, whether the interview was answered or
+  fell back to assumptions, and any real follow-up. Name a missing fact instead of
+  inventing it.
+
+## Boundaries
+
+- One target: `AGENTS.md` at the project root selected in the plan.
+- Plan mode is mandatory. If it is unavailable, stop and explain why instead of
+  writing directly.
+- The built-in bank is the default; one custom gap question is allowed only when
+  no entry covers a material fact, and it counts toward the four-question cap.
+- Reviewing an existing file never means silently accepting it, and rewriting one
+  never means discarding its correct instructions without saying so.

package/skills/init/references/agents-md-quality.md

@@ -0,0 +1,103 @@
+# AGENTS.md quality checklist
+
+Use this before drafting and again after writing the file. A draft fails when any
+applicable answer is no. The interview and the written file are checked together:
+an answered question that never reaches the file is as much a defect as an
+invented command.
+
+## Question-bank use
+
+- [ ] The first call used the deterministic default set for the repository state.
+- [ ] At most four questions were asked in the call.
+- [ ] Options were filled from evidence where the bank names commands, files, or
+      instruction documents.
+- [ ] No question duplicated a fact the recon already answered.
+- [ ] No question asked for a secret, credential, token, environment value, or
+      personal data.
+- [ ] A second call happened only for a material ambiguity, not to collect extra
+      preferences.
+
+## Interview quality
+
+- [ ] Every answer is reflected in the draft, or the plan states why it was not
+      adopted.
+- [ ] A cancelled or unavailable interview left explicit assumptions instead of
+      guessed facts.
+- [ ] A conflict between an answer and repository evidence is visible in the
+      plan, with the chosen resolution.
+- [ ] The plan names which questions were asked and what the user answered.
+
+## Evidence accuracy
+
+- [ ] Every command is copied from a manifest, script, Makefile, CI file, or docs
+      page that defines it. No command is guessed.
+- [ ] Every path and package name exists in the repository as written.
+- [ ] Every claimed convention is visible in the code or contributor docs.
+- [ ] Unknown facts are omitted or named as unknown. They are never filled with
+      plausible-sounding placeholders.
+- [ ] An answer that contradicts the code is treated as intent, not as evidence
+      that the code is wrong.
+
+## Specificity
+
+- [ ] The file tells an agent something it could not learn from a quick look.
+- [ ] It names the actual test, lint, typecheck, and single-test commands.
+- [ ] It names the real architecture boundaries and the traps that matter here.
+- [ ] Isolation, verification, and completion rules say what to do, not just what
+      to value.
+- [ ] Generic advice that would fit any repository is removed.
+
+## Concision
+
+- [ ] Every section earns its place; empty sections are deleted.
+- [ ] Rules are short, imperative, and one job each.
+- [ ] Deep material is linked, not copied.
+- [ ] The file is the smallest version that still prevents likely mistakes.
+
+## Actionability
+
+- [ ] Each instruction says what to do, where, or in what order.
+- [ ] Commands include their working directory when it is not the root.
+- [ ] Invariants name the failure they prevent.
+- [ ] There is no advice that cannot be followed.
+- [ ] Dependency, network, and off-limits rules name the boundary an agent must
+      respect.
+
+## Stability
+
+- [ ] The file avoids volatile file lists, line numbers, and transient counts.
+- [ ] It favours stable paths, package names, and commands.
+- [ ] It will still be mostly correct after ordinary refactoring.
+
+## Non-duplication
+
+- [ ] It does not restate the README or contributor guide.
+- [ ] It does not duplicate `AGENTS.override.md`, `CLAUDE.md`, or a nested
+      `AGENTS.md`; the relationship is stated instead.
+- [ ] Two sections do not give the same instruction.
+
+## Existing files
+
+- [ ] Correct existing instructions are preserved.
+- [ ] Stale instructions are changed only when the replacement is supported by
+      repository evidence or an explicit answer.
+- [ ] The plan lists exact edits, not a wholesale rewrite.
+- [ ] A rewrite records what is being removed and why.
+- [ ] A genuinely accurate file produces a no-op plan instead of churn.
+
+## Empty repository
+
+- [ ] No commands, architecture, or conventions are invented.
+- [ ] The file says the repository is newly initialized.
+- [ ] Only known facts and interview answers are recorded.
+- [ ] Empty sections are omitted.
+- [ ] Missing commands are named as missing, not replaced with a framework
+      default.
+
+## Final read-back
+
+- [ ] The written file matches the approved plan.
+- [ ] The file was read back from disk, not recalled from memory.
+- [ ] Only `AGENTS.md` changed.
+- [ ] The report names the path, whether the interview was answered or fell back
+      to assumptions, and any real follow-up.

package/skills/init/references/interview-questions.md

@@ -0,0 +1,81 @@
+# Built-in init questions
+
+The `init` skill selects from this bank. It is a menu, not a checklist: one
+`ask_user_question` call with at most four entries is the default, and a second
+call is allowed only for a material ambiguity. Never ask for secrets,
+credentials, tokens, environment values, or personal data.
+
+## Consolidation rules
+
+The bank merges questions that would otherwise create two copies of the same
+answer:
+
+- **Isolation** absorbs the workflow question: worktree, branch, or direct is the
+  first decision an agent makes.
+- **Done** absorbs testing and documentation expectations: both define when a
+  task is complete.
+- **Sensitive** absorbs generated, vendored, and secret-bearing paths.
+- **External changes** absorbs dependency and network policy.
+- **Commits** absorbs branch naming.
+- **Scope** and **Related docs** stay separate because they decide where the file
+  applies and how it relates to another instruction file.
+
+## Deterministic default sets
+
+Use the first matching row. Fill option labels with evidence before asking.
+
+| Repository state | First four questions |
+|---|---|
+| Existing project, no `AGENTS.md` | Purpose (only if unclear; otherwise Priorities), Verify, Rules, Isolation |
+| Existing project, `AGENTS.md` present | Existing file, Preserve (only if sections are unclear), Priorities (only if stale), Rules |
+| Empty or near-empty repository | Stack, Commands, Purpose, Priorities |
+| Related instruction files present | Swap Related docs in for Preserve or Rules |
+| Git repository with no guidance | Isolation, Verify, Done, External changes |
+| No UI, inactive tool, or cancelled interview | No call; record the gaps as assumptions |
+
+## Core questions
+
+| Header | Question | Shape | Selected when |
+|---|---|---|---|
+| Purpose | What is this project, and who will agents work on it for? | Free-form | README and manifest do not state the purpose and audience, or the repository is empty/near-empty. |
+| Verify | Which commands should an agent trust to verify a change? | Multi-select: detected install, build, test, lint, and typecheck commands, plus No reliable command yet; free-form Other for a missing command | Detected commands conflict or are ambiguous, or no command was found. |
+| Rules | What should an agent know that is not obvious from the code? | Free-form | No explicit conventions, invariants, style rules, or traps are found in the source, docs, or contributor files. |
+| Isolation | How should agents isolate and land work? | Single-select: Worktree per task, then PR; Branch in the current checkout, then PR; Commit directly; Follow repository instructions | The project is a Git repository with no stated isolation or branch rule. |
+| Done | What must be true before a task is done? | Multi-select: Tests pass; Lint and typecheck pass; Docs and changelog updated; Diff self-reviewed; Pull request opened | No contributor guide defines done, test level, or documentation expectations. |
+| Sensitive | Are any files, directories, or workflows off-limits for agents? | Free-form, including generated, vendored, and secret-bearing paths | Access boundaries are unclear, or generated, vendored, or secret-bearing paths need explicit exclusion. |
+| External changes | May an agent add dependencies or use the network? | Single-select: Yes, when needed; Ask first; Offline and no new dependencies | A manifest exists and dependency, package-install, or network rules are unclear. |
+| Existing file | How should the `init` skill handle the current `AGENTS.md`? | Single-select: Review and update in place; Keep it and only append missing guidance; Rewrite it from this interview | `AGENTS.md` already exists. |
+
+## State questions
+
+| Header | Question | Shape | Selected when |
+|---|---|---|---|
+| Stack | What are you building, and with which language or framework? | Free-form | The repository is empty/near-empty, or no manifest or README states the stack. |
+| Commands | What install, build, test, lint, and typecheck commands do you intend to use? | Free-form, with None yet accepted | The repository is empty/near-empty and no real command exists to copy. |
+| Related docs | How should `AGENTS.md` relate to existing instruction files? | Single-select: Link to them and add only gaps; Consolidate them into `AGENTS.md`; Leave them alone | `CLAUDE.md`, `AGENTS.override.md`, or a nested `AGENTS.md` exists. |
+| Preserve | Which current instructions must stay? | Free-form | `AGENTS.md` exists and its authoritative sections are unclear. |
+| Scope | Where should `AGENTS.md` apply? | Single-select: Repository root only; Root plus package-level files; Follow an existing instruction file | The repository is a monorepo, has nested packages, or already has a related instruction file. |
+
+## Optional follow-ups
+
+| Header | Question | Shape | Selected when |
+|---|---|---|---|
+| Priorities | What should agents optimize for here? | Multi-select: Correctness and safety; Small, reviewable changes; Fast iteration; Test coverage; Match existing style | No `AGENTS.md` yet, or the current priorities are absent or ambiguous. |
+| Planning | When should an agent plan before acting? | Single-select: Non-trivial or multi-file work; Every task; Only when asked; Never | No plan-mode or workflow guidance exists. |
+| Commits | What commit convention and branch naming should agents follow? | Single-select: Conventional Commits with type/scope; Plain descriptive messages; Repository-defined convention; No preference | No commit or branch guidance exists in docs or CI. |
+| Release | What release or versioning process must an agent follow? | Single-select: Maintainer handles releases; Follow documented release steps; No release process; free-form Other | The project is published or versioned and the process is unclear. |
+| Performance | Are there performance budgets or hot paths to protect? | Free-form | The project exposes performance-sensitive code or has benchmarks. |
+| Environment | What local services or setup steps does an agent need? | Free-form, no secrets | Setup requires services, databases, or environment configuration that is not documented. |
+| Finish | Anything else the next agent should know? | Free-form | Always optional, at most once. |
+
+## Selection rules
+
+- Ask at most four questions in one call, ordered by impact: state-specific
+  question first, then command verification, then conventions and limits.
+- Use the deterministic default set for the state. Do not pick a random subset.
+- Never ask for something the recon already answered, and never ask for a secret
+  or credential.
+- One custom gap question is allowed only when no bank entry covers a material
+  fact. It counts toward the four-question cap.
+- One follow-up call is allowed only when an answer creates a material ambiguity.
+  Cancel it cleanly if the user stops; the first round's answers stay valid.