@gavin-hu/my-pi-agent 0.17.0 → 0.18.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.

package/skills/next/SKILL.md

@@ -1,20 +1,24 @@
 ---
 name: next
-description: "Decide what to do next from a project's real state, or from the current conversation: loose work in the tree, commits since the last tag, unreleased changelog entries, roadmap or plan items still open, and the project's check command. Returns a short ranked list with the evidence for each item and the command that starts it; read-only, it never edits, commits, or begins the work. Use when asked what to do next, where to pick up, what is left, or what to work on now."
+description: "Decide what to do next from the current conversation when it has work in it, or from the project's real state when it is empty: loose work, commits since the last tag, unreleased changelog entries, roadmap or plan items still open, and the project's check command. Returns a short list of suggested next todos in priority order, with the evidence for each and the command that starts it; read-only, it never edits, commits, or begins the work. Use when asked what to do next, where to pick up, what is left, or what to work on now."
 ---
 
-# Decide what to do next
+# Suggest the next todos, by priority
 
-This is a triage, not a work session. The deliverable is a short ranked list with
-evidence; do not edit, commit, tag, or start the top item. The skill is
-model-invoked when a request matches the description; `/skill:next` is the
-explicit fallback. Read the project's own instructions first; where they disagree
-with this skill, the project wins.
+This is a triage, not a work session. The deliverable is a short list of
+suggested next todos in priority order, each with the evidence for it; do not
+edit, commit, tag, or start the first one. The skill is model-invoked when a
+request matches the description; `/skill:next` is the explicit fallback. Read the
+project's own instructions first; where they disagree with this skill, the
+project wins.
 
-Two sibling skills own a narrower question: an audit of *where to refactor* is
-`refactor`, and *what the last tag owes the changelog* is `changelog`. When the
-request is already scoped to one of those, name the skill that answers it and
-hand over, instead of returning a generic list.
+The conversation decides where the candidates come from (section 3); the request
+decides only what to ask and where to look.
+
+Two sibling skills, where they are installed, own a narrower question: an audit
+of *where to refactor* is `refactor`, and *what the last tag owes the changelog*
+is `changelog`. When the request is already scoped to one of those, name the
+skill that answers it and hand over, instead of returning a generic list.
 
 A next-steps block that the host draws itself is not this skill's output: that is
 the reply's suggested follow-up, a turn-level hint. This skill inspects state, so
@@ -24,15 +28,12 @@ its list survives the conversation that produced it.
 
 The host appends the text after the command to these instructions as the request.
 It is `<prompt>` in `/skill:next <prompt>`, it comes before any reading, and it
-carries up to three parts:
+carries up to two parts:
 
 ```text
-/skill:next [session] [what you want] [@path ...]
+/skill:next [what you want] [@path ...]
 ```
 
-- **`session`, first word** — session mode (section 3). The rest of the prompt
-  keeps its own meaning: `/skill:next session what is left?` is session mode with
-  a filter, not a filter of `session`.
 - **What you want** — a question, a goal, or a topic: "what is left before
   0.17?", "plan file outline". It chooses what the shortlist is about and keeps
   only the sources that can answer it; say which ones you kept. A named release,
@@ -48,7 +49,9 @@ carries up to three parts:
 - **An imperative** — "fix the failing test" names one piece of work, and the
   prompt is not approval for it. Answer with that item alone — evidence, starting
   command, effort — and ask before starting, instead of producing a list.
-- **No prompt** — triage of the current project.
+- **No prompt** — the source rule in section 3 still decides: an empty
+  conversation is triaged from the project, and one that has done work is read
+  for what it left open.
 - **Anything unreadable** — triage anyway, and say in one clause how you read the
   prompt, so a misreading is visible in the report rather than silently narrowing
   the list.
@@ -66,40 +69,56 @@ With the request read, find:
 - the release path: what a tag, a version bump, or an unreleased entry owes;
 - the VCS, its branch model, and the last tag if there is one.
 
-State the profile in one or two lines. Do not invent a source the project does
-not have; a project with no roadmap is triaged from git and the check alone.
+Do not invent a source the project does not have; a project with no roadmap is
+triaged from version control and the check alone. These profile facts decide
+which evidence rows apply, and section 7's report states them.
+
+## 3. Choose the source
+
+There are two sources, and the conversation picks one:
+
+- **This conversation** — the source once it has done work. Read its own record:
+  the todo list, the goal, the approved plan and its ticked steps, what subagents
+  and jobs returned, the paths it recorded, and the diff it produced. The
+  candidates are the loose ends it left: uncommitted files, an unapproved plan, a
+  check that was never run, a documented behavior that changed without a doc or
+  changelog edit.
+- **The project's real state** — only when the conversation is empty. Read git,
+  the changelog, the roadmap or issues, and the plans directory; the candidates
+  are the project's loose work, broken promises, and unfinished ones.
 
-## 3. Choose the mode
+Empty means the conversation has done no work yet, not that it has no messages:
+there is no todo list, no goal, no approved plan or ticked step, no subagent or
+job result, no path it recorded, and no edit or commit from this session. The
+request itself never counts, or `/skill:next` could never reach the tree.
 
-- **Triage** — what the tree says. Use git, the changelog, the roadmap or issues,
-  and the plans directory. This is the default.
-- **Session** — what this conversation left open. Read the conversation's own
-  record: the todo list, the goal, the approved plan and its ticked steps, what
-  subagents and jobs returned, and the diff this session produced. Then list the
-  loose ends it left: uncommitted files, an unapproved plan, a claim that was
-  never run, a documented behavior that changed without a doc or changelog edit.
-- When both apply, run triage and read the session for context; the tree wins,
-  because it is where the work actually is.
+The tree is evidence in both sources. Verify every candidate against the code
+before recommending it, and read the tree's status, the session's diff, the
+changelog's unreleased section where the project has one, and the last check
+result whichever source chose the candidates. A conversation that ended cleanly
+has an empty list; do not fall back to the tree to fill it.
 
-Mode and scope are independent: session mode still honours a path, and triage
-with a path reads the whole tree's evidence before narrowing. State the mode, the
-scope, and the prompt as read, at the top of the report.
+Scope is independent of the source: a path narrows either one, and a topic keeps
+only the sources that can answer it. State the source, the scope, and the prompt
+as read, at the top of the report.
 
 ## 4. Gather evidence
 
 Read only; nothing in this stage writes. Follow the project's own tool
-discipline, and say what you could not read.
+discipline, and say what you could not read. The commands below are git's — use
+the project's VCS for a project that is not on git — and read the rows its
+profile says exist.
 
 | Source | What it proves |
 |---|---|
 | `git status --short`, `git diff --stat` | Work in flight, and whose it is |
-| `git log --oneline <last-tag>..HEAD` | What has landed unreleased |
+| `git log --oneline <last-tag>..HEAD` | What has landed unreleased, if the project tags |
 | `git worktree list`, `git branch --no-merged` | An isolated tree left behind, a branch never merged |
-| The changelog's `[Unreleased]` | Whether a landed change is recorded, and whether the window is empty |
+| The changelog's unreleased section (`[Unreleased]` under Keep a Changelog) | Whether a landed change is recorded, and whether the window is empty |
 | The roadmap, issue tracker, or `TODO` docs | The project's stated priorities, and which are already done |
-| The plans directory (`.pi/plans` or the project's equivalent) | An approved plan whose steps remain |
+| The plan files the host's plan tool records (`~/.pi/agent/plans/<repo-key>` here) | An approved plan whose steps remain |
 | The todo list, the goal, job and subagent results | What the session promised and did not finish |
-| The check command | Whether the tree is green — cite the last known result, and make running it the item's starting command rather than running it here |
+| The check command | Whether the tree is green — cite the session's last result, and make running it the item's starting command rather than running it here |
 
 A roadmap, a changelog, and a plan all lag the tree. Verify a candidate against
 the code before recommending it, and drop one that is already done.
@@ -116,12 +135,14 @@ cannot point at it, drop it.
 - Prefer the candidate with a fast verification command.
 - Never invent work to fill the list. An empty list is a valid answer.
 
-## 6. Rank by cost of loss
+## 6. Rank by priority
 
-Order by what it would cost to lose, cheapest loss first:
+Priority is what it would cost to lose the work, cheapest loss first, so the
+order is the suggestion: the first item is the one to start, and a later item is
+not an alternative to an earlier one. Order by that cost:
 
 - **Loose work** — a dirty tree, an unapproved plan, a check that has not been
-  run, an unmerged branch, a worktree left behind, a stopped job.
+  run, an unmerged branch, a scratch tree or branch left behind, a stopped job.
 - **A broken promise** — a README, roadmap, or doc claim the code no longer
   meets, a released behavior with no test.
 - **An unfinished promise** — a stated roadmap item, the remaining steps of an
@@ -130,8 +151,8 @@ Order by what it would cost to lose, cheapest loss first:
 - **New reach** — a capability nobody has asked for comes last, and only when the
   three above are empty.
 
-Label each item with the ceremony it needs. The label is not a second ordering:
-cost of loss decides the order, and the label says how much work the item takes.
+Label each item with the ceremony it needs. The label says how much work the item
+takes, not where it ranks: the priority ladder decides the order.
 
 - **Do next** — cheap, safe, and unblocks the rest.
 - **Worth planning** — high value, but it spans files, changes a public surface,
@@ -139,17 +160,20 @@ cost of loss decides the order, and the label says how much work the item takes.
 - **Later** — real, but not now.
 
 Cap the list at three to five items, and let a tier be empty. A roadmap restated
-as ten suggestions is not a triage. Do not invent a numeric score; the reason
-must be readable.
+as ten suggestions is not a triage. Number the items: the number is the priority.
+Do not invent a score beyond that; the reason must be readable.
 
 ## 7. Report
 
-- **State** — one paragraph: the mode, the scope and how the prompt was read,
-  the branch or worktree, what is dirty, what is unreleased, and whether the
-  check passes. Name anything you could not read.
-- **The shortlist** — each item with its label, the action, the evidence at
-  `path:line` or the command output that proves it, the command that starts it,
-  and effort (S/M/L). Link the file the item lives in.
+- **State** — one paragraph: the source and why it was chosen (a conversation
+  with work in it, or an empty one), the scope and how the prompt was read, the
+  branch or tree, what is dirty, what is unreleased, whether the check passes,
+  and the profile facts the list rests on — VCS, check command, and where work
+  is tracked. Name anything you could not read.
+- **The list** — the suggested next todos, numbered in priority order, each with
+  its label, the action, the evidence at `path:line` or the command output that
+  proves it, the command that starts it, and effort (S/M/L). Link the file the
+  item lives in.
 - **Rejected or stale** — one line each, with the reason the roadmap, changelog,
   or plan entry no longer applies.
 - **Next step** — ask which item to start. Do not start it, and do not open with
@@ -174,11 +198,12 @@ When the user picks an item, the audit is over:
 - Nothing worth doing: say so, with what was checked, instead of inventing work.
 - The tree is mid-rebase, mid-merge, mid-bisect, or has a conflict: reconciling it
   is the only next item; nothing else is safe to suggest.
-- The project has no work tracking: say the list is derived from git and the check
-  only, and suggest recording the plan or roadmap the project is missing.
+- The project has no work tracking: say the list is derived from version control
+  and the check only, and suggest recording the plan or roadmap the project is
+  missing.
 - A candidate needs a destructive command (a branch delete, a worktree prune, a
   history rewrite) to start: name it as a decision for the user, not as a step.
 
-The triage is done when the mode is stated, every item has evidence and a
+The triage is done when the source is stated, every item has evidence and a
 starting command, the list is capped, rejected candidates are explained, and no
 file was modified.