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

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.13.1",
-  "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,12 +115,14 @@
     "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",
     "bench:render": "bun run scripts/render-bench.ts",
+    "screenshot:file-browse": "bun run scripts/file-browse-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",

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.

package/skills/refactor/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: refactor
+description: "Find and rank refactoring opportunities in a project or path: duplication, oversized modules, coupling, drift, and high-churn code with weak tests. Use when asked what to refactor, where the code is tangled, or for a refactor audit; discovery is read-only and returns an evidence-based shortlist."
+---
+
+# Find refactoring opportunities
+
+This is an audit, not an edit session. The deliverable is a ranked shortlist with
+evidence; do not modify files while discovering. The skill is model-invoked when
+a request matches the description; `/skill:refactor` is the explicit fallback.
+
+A refactor changes structure without changing behavior. If the request changes
+behavior, call it a behavior change and report it separately. Read the
+repository's own instructions first; they win over this skill.
+
+## 1. Resolve the scope
+
+The text after `/skill:refactor` is the task. It may contain a path (`@src`,
+`src`, `packages/api`, or a path inside a sentence), a question, or both.
+
+- Resolve each path from the working directory. A directory is the audit scope;
+  a file is the initial target. Audit multiple paths separately and report them
+  together.
+- No path means the current project. If the project is large, propose a scope
+  from the documented layout instead of scanning everything blindly.
+- If a path does not exist, say so and ask for a real one. Do not guess. Do not
+  leave the working directory unless the user explicitly supplied an outside
+  path.
+- State the resolved scope and the number of files examined in the report.
+
+## 2. Learn the project's standards
+
+- Read the repository's instruction files, contributor guide, architecture
+  notes, shared-helper documentation, and CI configuration.
+- Record the languages, layout, test framework, documented check commands, size
+  or complexity thresholds, and ignore rules.
+- Do not import an external style guide, install a tool, or apply a threshold the
+  project never stated. If there is no stated threshold, compare against the rest
+  of the scope and say that is the basis.
+- Note the available evidence: tests, coverage, type checking, linting, git
+  history, and any scanner already installed.
+
+## 3. Inventory the scope
+
+- Map source files, tests, exports, imports, and entry points. Mark public
+  surface versus internal modules.
+- Measure cheap facts: file and function sizes, nesting depth, parameter counts,
+  export counts, fan-in and fan-out, and the distance to the nearest test.
+- Read git history for churn (`git log --numstat`) inside the scope. Churn is
+  context, not a verdict: a frequently changed, tangled file is a stronger
+  candidate than a stable, isolated oddity.
+- Skip version-control metadata, dependencies, build output, generated files,
+  vendored trees, and secrets unless the user explicitly includes them. Respect
+  the project's ignore files.
+- For a large scope, delegate a read-only survey to a read-only helper if the
+  host provides one. Keep the filtering and ranking in the main session.
+
+## 4. Detect signals
+
+For every signal, point at a file and line and explain why it matters here.
+
+| Signal | What to look for | Evidence to cite |
+|---|---|---|
+| Duplication | The same body or a near-identical block in several places; copy-paste with tiny edits; a helper that already exists in a shared location | Paths and line ranges of each copy; the shared location it should use |
+| Size and responsibility | A module or function past the project's limit, or a relative outlier; unrelated exports; deep nesting; long parameter lists | Measured size or responsibility list; the seams where it could split |
+| Coupling | Circular or layer-crossing imports, high fan-in or fan-out, feature envy, repeated type switches | The import edge or repeated branch, with both sides named |
+| Cohesion and drift | A grab-bag utility module; a name that no longer matches behavior; dead exports; commented-out code; two implementations of one concept | The mismatch or unused export, with its callers |
+| Change pressure | High recent churn combined with complexity or weak tests | Churn count over a stated window plus the complexity or test gap |
+| Test friction | Behavior with no direct test; tests that mock the unit heavily or assert internals; duplicated setup that hides a missing seam | The test path and the missing or brittle assertion |
+| Boundary erosion | Leaking internal types, unchecked casts, mode-selecting boolean parameters, null-heavy returns | The boundary location and the caller that must know the internals |
+
+## 5. Verify and filter
+
+A signal is not a candidate until it is confirmed.
+
+- Read the callers and tests, not just the definition. Duplication may be
+  intentional for a protocol version; a large module may be cohesive; an
+  "unused" export may be public API.
+- Require one concrete artifact: a path with line numbers, a counted duplicate, a
+  measured size, a dependency edge, or a test gap. If you cannot point at it,
+  drop it.
+- Keep pure refactors separate from behavior changes and bugs. Report a bug as a
+  bug; do not smuggle it into the refactor list.
+- Prefer candidates with an existing test that catches a regression. If the
+  behavior is untested, mark the candidate "tests first".
+- Reject weak candidates explicitly. A short "not worth it" list proves the
+  audit was selective rather than a tour of everything unfamiliar.
+
+## 6. Rank
+
+Use three tiers:
+
+- **Do next:** safe, contained blast radius, high leverage, small or medium
+  effort, and a fast verification command.
+- **Worth planning:** high leverage but more risk or effort, a public surface, or
+  missing tests.
+- **Leave it:** low confidence, little leverage, or not worth the churn.
+
+Within a tier, order by leverage first, then safety, then cost. Do not invent a
+numeric score; the reasons must be readable.
+
+## 7. Report
+
+Keep the report scannable. Use this shape:
+
+- **Scope and method:** path, file count, tools used, and what was not examined.
+- **Top three to five opportunities**, each with a title, tier, evidence at
+  `path:line`, the proposed structural change, expected benefit, risk and blast
+  radius, effort (S/M/L), and the narrow plus full verification command.
+- **Rejected signals:** one line each with the reason it did not qualify.
+- **Next step:** ask which candidate to take. Do not start editing.
+
+## 8. Stop conditions
+
+- No worthwhile opportunities: say so with the evidence that was checked instead
+  of inventing work.
+- The request is a specific refactor rather than an audit: skip the shortlist,
+  but use the handoff below.
+- The request changes behavior or asks for a rewrite: treat it as an approved
+  design change, not this audit.
+- The scope cannot be read (missing path, secrets, binary or generated files, or
+  an inaccessible tree): report the limitation.
+
+## After selection: safe handoff
+
+If the user chooses a candidate, execution follows these rules:
+
+- State the behavior contract and run the project's documented check to get a
+  baseline. Record pre-existing failures.
+- If the behavior is untested, add characterization tests first.
+- Enter plan mode when the host provides it and the change spans files, changes a
+  public surface, or has an unknown step list. Otherwise track the steps in a
+  todo list or a short written sequence.
+- Make one structural change per step and verify each step. Never mix in
+  formatting, bug fixes, or unrelated cleanup.
+- Finish with the full project check and report the diff, results, and remaining
+  risk. Do not commit unless the user asks.
+
+The audit is done when the scope is stated, every candidate has `path:line`
+evidence and a verification command, the shortlist is capped, rejected signals
+are explained, and no files were modified.