@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/lib/web/tokens.ts

@@ -21,8 +21,8 @@ interface ThemeJson {
 const DARK = darkTheme as unknown as ThemeJson;
 const LIGHT = lightTheme as unknown as ThemeJson;
 
-/** Web custom property -> Bytefly theme var. `--accent-soft`, `--on-accent`, `--scrim`,
- * and `--shadow` are derived, so no appearance-only colour enters the kit. */
+/** Web custom property -> Bytefly theme var. `--accent-soft`, `--raised`, `--on-accent`,
+ * `--scrim`, and `--shadow` are derived, so no appearance-only colour enters the kit. */
 const VAR_TOKENS: ReadonlyArray<readonly [string, string]> = [
 	["--canvas", "canvas"],
 	["--surface", "canvasSubtle"],
@@ -73,6 +73,16 @@ function resolve(theme: ThemeJson, value: string | number): string {
 	return theme.vars[value] ?? value;
 }
 
+/** `#rrggbb` mixed toward another colour: `t` of the way from `a` to `b`. */
+function mix(a: string, b: string, t: number): string {
+	const channel = (hex: string, at: number): number => Number.parseInt(hex.replace("#", "").slice(at, at + 2), 16);
+	const between = (x: number, y: number): number => Math.round(x + (y - x) * t);
+	const r = between(channel(a, 0), channel(b, 0));
+	const g = between(channel(a, 2), channel(b, 2));
+	const bl = between(channel(a, 4), channel(b, 4));
+	return `#${[r, g, bl].map((value) => value.toString(16).padStart(2, "0")).join("")}`;
+}
+
 /** `#rrggbb` (or `#rgb`) plus alpha -> `rgba(r,g,b,a)`. */
 function rgba(hex: string, alpha: number): string {
 	const raw = hex.replace("#", "");
@@ -94,6 +104,15 @@ function rgba(hex: string, alpha: number): string {
  * lifts a panel off it, so each appearance needs its own alpha rather than the
  * theme's colours.
  */
+/**
+ * How far `--raised` sits above `--surface`: enough to see, not enough to shout.
+ *
+ * The light theme takes a smaller step because its accent is darker: at the dark
+ * step, `--accent` on `--raised` falls to 4.34:1 and the owner chips on a raised row
+ * stop being readable.
+ */
+const RAISED_STEP: Record<"dark" | "light", number> = { dark: 0.06, light: 0.03 };
+
 const OVERLAYS: Record<"dark" | "light", { scrim: string; shadow: string }> = {
 	dark: { scrim: "rgba(0,0,0,.5)", shadow: "0 8px 24px rgba(0,0,0,.4)" },
 	light: { scrim: "rgba(15,23,42,.3)", shadow: "0 8px 24px rgba(15,23,42,.14)" },
@@ -104,6 +123,10 @@ function paletteOf(theme: ThemeJson, appearance: "dark" | "light", accentAlpha:
 	const palette: Record<string, string> = {};
 	for (const [token, name] of VAR_TOKENS) palette[token] = theme.vars[name];
 	palette["--accent-soft"] = rgba(palette["--accent"] ?? "#000000", accentAlpha);
+	// One step above `--surface`, for a block that must read as a plane rather than an
+	// outline: the theme offers only two neutral fills, and a surface one hairline
+	// lighter than the page is what made a dashboard look like a wireframe.
+	palette["--raised"] = mix(palette["--surface"] ?? "#000000", palette["--text"] ?? "#ffffff", RAISED_STEP[appearance]);
 	// A label on the accent fill is the canvas colour: a light blue button takes dark
 	// text, and the same derivation gives white on the light theme's darker blue.
 	palette["--on-accent"] = palette["--canvas"];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.17.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, file-read, check, memory, context, wechat, and bytefly.",
+  "version": "0.19.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, file-read, check, memory, context, session-bus, board, team, wechat, and bytefly.",
   "keywords": [
     "pi-package",
     "pi",
@@ -49,6 +49,12 @@
     "excel",
     "read_doc",
     "memory",
+    "board",
+    "cards",
+    "backlog",
+    "team",
+    "handoff",
+    "assign",
     "cross-session",
     "context",
     "compaction",
@@ -74,6 +80,7 @@
   },
   "files": [
     "extensions/**",
+    "docs/extensions/**",
     "lib/**",
     "skills/**",
     "themes/**",
@@ -101,6 +108,9 @@
       "./extensions/file-open/index.ts",
       "./extensions/memory/index.ts",
       "./extensions/context/index.ts",
+      "./extensions/board/index.ts",
+      "./extensions/team/index.ts",
+      "./extensions/session-bus/index.ts",
       "./extensions/wechat/index.ts",
       "./extensions/bytefly/index.ts"
     ],
@@ -110,7 +120,7 @@
     "themes": [
       "./themes/*.json"
     ],
-    "image": "https://raw.githubusercontent.com/gavin-hu/my-pi-agent/main/assets/chrome.png"
+    "image": "https://raw.githubusercontent.com/gavin-hu/my-pi-agent/main/assets/screens/chrome.png"
   },
   "scripts": {
     "test": "bun test --parallel=4 --timeout 30000",
@@ -126,12 +136,15 @@
     "config:migrate": "bun run scripts/migrate-config.ts",
     "compat:versions": "bun run scripts/peer-versions.ts",
     "bench:render": "bun run scripts/render-bench.ts",
-    "screenshot:file-browse": "bun run scripts/file-browse-shot.ts",
-    "screenshot:plan-flow": "bun run scripts/plan-flow-shot.ts",
-    "screenshot:plan": "bun run scripts/plan-review-shot.ts",
-    "screenshot:tools": "bun run scripts/tool-renderings.ts gallery assets/tool-renderings.png",
-    "screenshot:tool-pngs": "bun run scripts/tool-renderings.ts tools assets/tools",
-    "screenshots": "bun run scripts/screenshots.ts"
+    "screenshot:board": "bun run scripts/shots/board.ts",
+    "screenshot:cards": "bun run scripts/shots/cards.ts",
+    "screenshot:file-browse": "bun run scripts/shots/file-browse.ts",
+    "screenshot:plan": "bun run scripts/shots/plan-review.ts",
+    "screenshot:tools": "bun run tools:render gallery assets/screens/tool-renderings.png",
+    "screenshot:tool-pngs": "bun run tools:render tools assets/tools",
+    "probe:wechat": "bun run scripts/wechat-poll.ts",
+    "screenshots": "bun run scripts/screenshots.ts",
+    "tools:render": "bun run scripts/tools/index.ts"
   },
   "dependencies": {
     "exceljs": "^4.4.0",
@@ -152,15 +165,15 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",
-    "@earendil-works/pi-agent-core": "^1.0.4",
-    "@earendil-works/pi-ai": "^1.0.4",
-    "@earendil-works/pi-coding-agent": "^1.0.4",
-    "@earendil-works/pi-tui": "^1.0.4",
+    "@earendil-works/pi-agent-core": "^1.4.0",
+    "@earendil-works/pi-ai": "^1.4.0",
+    "@earendil-works/pi-coding-agent": "^1.4.0",
+    "@earendil-works/pi-tui": "^1.4.0",
     "@types/bun": "latest",
     "@types/qrcode": "^1.5.5",
     "get-east-asian-width": "^1.6.0",
     "playwright-core": "^1.64.1",
-    "typebox": "^1.3.27",
+    "typebox": "^1.4.3",
     "typescript": "^5.6.0"
   }
 }

package/skills/init/SKILL.md

@@ -1,34 +1,37 @@
 ---
 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."
+description: "Initialize or refresh a project's agent instructions (AGENTS.md, or AGENTS.override.md when it shadows AGENTS.md) through a built-in interactive interview and a reviewed plan. Run /skill:init to start it."
 disable-model-invocation: true
 ---
 
-# Initialize AGENTS.md
+# Initialize agent instructions
 
-Goal: create or update **`AGENTS.md` at the project root** by combining repository
+Goal: create or update the instruction file Pi reads at the **project root** —
+`AGENTS.md`, or `AGENTS.override.md` when one shadows it — 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.
+review in that order; do not write the file early to save a step. A declined plan
+mode ends the skill: stop and explain, rather than writing directly.
 
 ## Workflow
 
 ```text
 /skill:init
   └─> plan mode (read-only)
-        └─> recon: manifests, docs, CI, tests, existing instructions
-        └─> interview: one built-in question call (at most 4)
+        └─> recon: effective instruction file, sourced evidence, existing instructions
+        └─> interview: one built-in question call (at most 4), minus resolved facts
               ├─ answers ───────────────> reconcile with evidence
               └─ unavailable/cancelled ─> evidence + recorded assumptions
         └─> draft: new file, exact edits, or an honest no-op
         └─> quality gate
+        └─> plan outline with ## Steps and ## Verification
         └─> write_plan ──> exit_plan_mode
                              ├─ not approved ──> refine the same plan
-                             └─ approved ──────> write/edit AGENTS.md
+                             └─ approved ──────> write/edit the target
                                                  └─ read back + quality gate
 ```
 
@@ -37,35 +40,34 @@ before the interview. Read
 [`references/agents-md-quality.md`](./references/agents-md-quality.md) before
 drafting and again before writing the plan.
 
-## Repository states
+## Default question sets
 
-| 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.
+The bank's deterministic default sets, in
+[`references/interview-questions.md`](./references/interview-questions.md), decide
+the first call for each repository state. They are the only copy; do not restate
+them here. Drop a question the evidence sheet already answers.
 
 ## 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.
+- Resolve the instruction file Pi reads in this directory first. A root
+  `AGENTS.override.md` replaces `AGENTS.md` and `CLAUDE.md` in the same directory —
+  it still applies below — so it is the target; a new `AGENTS.md` beside it would
+  be dead text. Report an override above the project root or in the agent
+  directory, but never edit outside the project.
+- Read the remaining instruction files (`CLAUDE.md`, nested `AGENTS.md` and
+  overrides) and 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
+- Build a sourced evidence sheet: stack and package manager from the manifest and
+  lockfile; every install/test/lint/typecheck command with the file that defines
+  it; generated, vendored, and build-output paths from `.gitignore` and the tree;
+  workspace packages and boundaries; purpose and audience from the README lead or
+  manifest description; validation gates, release path, and existing rules. Mark
+  each field `resolved` or `unknown`.
+- The unknown fields are the interview gaps. 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
@@ -74,14 +76,19 @@ exhaust.
 ## 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.
+Choose the bank's deterministic default set for the repository state, then drop
+every question the evidence sheet already answers: `Purpose` only when README and
+manifest are silent, `Verify` only when detected commands are missing or conflict,
+`Sensitive` only when generated-path evidence leaves a boundary unclear. Ask the
+bank's `Target` question when a root override exists.
 
 - 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.
+  manager, the real instruction file names. Four options at most, and never one of
+  them for a free-form escape: the tool always adds Other, so an "Other" or "None of
+  these" label spends a real answer's slot.
 - 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
@@ -103,15 +110,23 @@ Treat answers and evidence as different kinds of fact:
 - 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.
+- A command, path, or package with no source in the evidence sheet stays out or is
+  asked; it is never inferred from convention.
+
+The target is the effective file from recon. If a root `AGENTS.override.md`
+exists, edit it. Never write an `AGENTS.md` that the override shadows; if the user
+chooses to consolidate into `AGENTS.md`, the plan removes or renames the override
+in the same step and preserves its instructions.
 
 Then choose the outcome:
 
-- **No `AGENTS.md`** — draft the smallest useful file. Use the sections this
+- **No instruction file** — 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.
+- **Existing instruction file** — preserve correct instructions and propose exact
+  edits for the rest, shown as a fenced before/after diff. If the user chose to
+  rewrite, the plan must still list what is being removed.
+- **Accurate instruction file** — 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.
@@ -132,31 +147,51 @@ 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
+- Save the proposal with `write_plan` in the documented outline. The plan must
+  include:
+  - `## Goal` — the outcome for the instruction file;
+  - `## Context` — the sourced evidence sheet, the effective-file finding, and the
+    questions asked with how each answer was used;
+  - `## Approach` — the full draft for a new file, or a fenced before/after diff
+    for edits;
+  - `## Steps` — one top-level bullet per apply action: write or edit the target,
+    read it back, run the check. Without this heading approval seeds the
+    shallowest list anywhere, which is the draft rather than the actions;
+  - `## Risks` — assumptions, conflicts, and gaps from a cancelled or unavailable
     interview;
-  - a verification step that reads the written file back against the checklist.
+  - `## Verification` — the project's own check when it declares one (`run_check`,
+    or the narrower docs or structure test that guards the instruction file), then
+    reading 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.
+- No write to the target 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.
+- Create a new file with `write`, or update the target with `edit`.
+- Change only the instruction files the approved plan names: the target, and an
+  override the plan removes or renames while consolidating. 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.
+- Run the plan's verification step. A check that fails on the written file is the
+  report's follow-up, not a success; a check that fails for something the
+  instruction file cannot cause is named as an unrelated failure rather than
+  blamed on the draft.
 - 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.
+- One target for the instructions: the instruction file Pi reads at the project
+  root — `AGENTS.override.md` when one exists, otherwise `AGENTS.md`, as selected
+  in the plan.
+- A consolidation edits the file it absorbs only when the approved plan names it;
+  otherwise the other file is left alone.
+- Never leave a written `AGENTS.md` shadowed by a root override, and never edit an
+  override outside the project root.
 - 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

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

@@ -9,6 +9,8 @@ invented command.
 
 - [ ] The first call used the deterministic default set for the repository state.
 - [ ] At most four questions were asked in the call.
+- [ ] No question offered more than four options, and none spent one on a free-form
+      escape the tool already provides.
 - [ ] Options were filled from evidence where the bank names commands, files, or
       instruction documents.
 - [ ] No question duplicated a fact the recon already answered.
@@ -27,12 +29,24 @@ invented command.
       plan, with the chosen resolution.
 - [ ] The plan names which questions were asked and what the user answered.
 
+## Target file
+
+- [ ] The plan names the instruction file Pi reads in the target directory.
+- [ ] A root `AGENTS.override.md` is the target, or the plan removes or renames it
+      while consolidating its instructions into `AGENTS.md`.
+- [ ] The written file is not an `AGENTS.md` that a root override shadows.
+- [ ] An override above the project root or in the agent directory is reported,
+      not edited.
+
 ## Evidence accuracy
 
-- [ ] Every command is copied from a manifest, script, Makefile, CI file, or docs
-      page that defines it. No command is guessed.
+- [ ] Every command is paired with the file that defines it in the evidence sheet.
 - [ ] Every path and package name exists in the repository as written.
 - [ ] Every claimed convention is visible in the code or contributor docs.
+- [ ] Generated and vendored exclusions name paths that exist and are backed by
+      `.gitignore` or build output.
+- [ ] Purpose came from the README lead or manifest description, or was asked.
+- [ ] No field marked `resolved` was asked again in the interview.
 - [ ] 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
@@ -76,12 +90,20 @@ invented command.
       `AGENTS.md`; the relationship is stated instead.
 - [ ] Two sections do not give the same instruction.
 
+## Plan and review
+
+- [ ] The plan uses `## Steps` and `## Verification`.
+- [ ] Each top-level step is an apply action, not a bullet from the draft.
+- [ ] An existing-file change is shown as a before/after diff, not prose edits.
+
 ## 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.
+- [ ] An override that is consolidated is removed or renamed in the same step, and
+      its instructions are preserved.
 - [ ] A rewrite records what is being removed and why.
 - [ ] A genuinely accurate file produces a no-op plan instead of churn.
 
@@ -97,6 +119,8 @@ invented command.
 ## Final read-back
 
 - [ ] The written file matches the approved plan.
+- [ ] The project's own check passed against the written file, or the report names the
+      failure it returned.
 - [ ] 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

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

@@ -5,6 +5,13 @@ The `init` skill selects from this bank. It is a menu, not a checklist: one
 call is allowed only for a material ambiguity. Never ask for secrets,
 credentials, tokens, environment values, or personal data.
 
+Every select question lists its options inside `Shape`, separated by `;`, between
+two and four of them. Anything after ` — ` is a note rather than an option, and
+the tool's free-form **Other** is never listed as one: it is always offered, so a
+label spent on it costs a real answer. In this package, `test/skill-bank.test.ts`
+holds these tables to that convention, so an over-long list fails the check rather
+than the interview.
+
 ## Consolidation rules
 
 The bank merges questions that would otherwise create two copies of the same
@@ -14,7 +21,11 @@ answer:
   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.
+- **Sensitive** is the fallback for generated, vendored, and secret-bearing
+  boundaries that `.gitignore` and build-output evidence cannot settle.
+- **Target** settles which file is written when a root `AGENTS.override.md`
+  exists; Related docs still covers `CLAUDE.md` and nested files once the target
+  is fixed.
 - **External changes** absorbs dependency and network policy.
 - **Commits** absorbs branch naming.
 - **Scope** and **Related docs** stay separate because they decide where the file
@@ -26,25 +37,29 @@ 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, no `AGENTS.md` | Purpose (only if README and manifest are silent; otherwise Priorities), Verify (only if commands are missing or conflict; otherwise Done), 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 |
+| Related instruction files present | Target first when a root override exists; otherwise 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 |
 
+A field the evidence sheet resolves is dropped, and the parenthesised fallback
+keeps the call at four questions only when the field is unknown. A root
+`AGENTS.override.md` adds `Target` before any other state question.
+
 ## 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. |
+| Verify | Which commands should an agent trust to verify a change? | Multi-select: the detected full check; the detected test command; one file's test command; no reliable command yet — Other takes a command the recon missed | 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. |
+| Done | What must be true before a task is done, on top of the landing rule? | Multi-select: Tests pass; Lint and typecheck pass; Docs and changelog updated; Diff self-reviewed — the pull request belongs to Isolation or Commits | 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 | Generated-path evidence leaves a boundary unclear, or a workflow boundary is not visible in the files. |
 | 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. |
+| Existing file | How should the `init` skill handle the current instruction file? | Single-select: Review and update in place; Keep it and only append missing guidance; Rewrite it from this interview | The target instruction file already exists. |
 
 ## State questions
 
@@ -52,18 +67,19 @@ Use the first matching row. Fill option labels with evidence before asking.
 |---|---|---|---|
 | 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. |
+| Target | Which instruction file should `init` maintain? | Single-select: Edit `AGENTS.override.md`; Consolidate into `AGENTS.md` and remove the override — the first keeps Pi's effective file, the second unshadows `AGENTS.md` | A root `AGENTS.override.md` exists. |
+| Related docs | How should the target instruction file relate to existing instruction files? | Single-select: Link to them and add only gaps; Consolidate them into the target file; Leave them alone | `CLAUDE.md` or a nested `AGENTS.md` exists. |
+| Preserve | Which current instructions must stay? | Free-form | The target instruction file exists and its authoritative sections are unclear. |
+| Scope | Where should the instruction file 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. |
+| Priorities | What should agents optimize for here? | Multi-select: Correctness and safety; Small, reviewable changes; Fast iteration; Match existing style — test coverage belongs to Done | No instruction file 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. |
+| Release | What release or versioning process must an agent follow? | Single-select: Maintainer handles releases; Follow documented release steps; No release process — Other takes a process this list misses | 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. |
@@ -72,9 +88,15 @@ Use the first matching row. Fill option labels with evidence before asking.
 
 - Ask at most four questions in one call, ordered by impact: state-specific
   question first, then command verification, then conventions and limits.
+- Offer at most four options per question, filled from evidence, and never spend one
+  on a free-form escape the tool already provides.
 - 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.
+- Never ask for something the evidence sheet already resolved, and never ask for a
+  secret or credential.
+- `Purpose`, `Verify`, and `Sensitive` are fallbacks: ask each only when the
+  evidence sheet cannot answer it.
+- When a root `AGENTS.override.md` exists, ask `Target` before drafting; a target
+  that keeps the override is edited in place, and a consolidation removes it.
 - 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.