pi-dev 0.1.7 → 0.2.0

package/README.md

@@ -42,21 +42,34 @@ You ask. It classifies. It executes. It reports.
 Requires Node ≥ 20 and the [pi runtime](https://github.com/badlogic/pi).
 
 ```bash
-# Install the skills + seed your global preferences
+# Interactive: pick global vs project-local, then install + seed preferences
 npx pi-dev@latest install
 
-# Refresh skills only (keeps your preferences as-is)
+# Or be explicit:
+npx pi-dev@latest install --global    # ~/.pi/agent/skills/   (every repo)
+npx pi-dev@latest install --local     # ./.pi/skills/         (this repo only)
+
+# Refresh skills (auto-detects scope from disk; preferences are kept)
 npx pi-dev@latest update
 
-# See what's installed
+# See what's installed under each scope
 npx pi-dev list
 
-# Verify your environment
+# Verify the active scope's layout
 npx pi-dev doctor
 ```
 
-`install` copies the skill folders to `~/.pi/agent/skills/` (where the pi runtime looks) and seeds `~/.pi/agent/preferences.md` only if you don't already have one.
-`update` refreshes skill folders but leaves your preferences alone unless you pass `--include-prefs`.
+**Scope choice cheat-sheet:**
+
+| | global | local |
+| --- | --- | --- |
+| Skills | `~/.pi/agent/skills/` | `<repo>/.pi/skills/` |
+| Preferences | `~/.pi/agent/preferences.md` | `<repo>/.pi/preferences.md` |
+| Pi sessions see it from | every cwd | only this repo |
+| Goes in the repo's git? | no | yes (commit `.pi/skills/`, gitignore `.pi/sessions/`) |
+| Use when | the skills are part of *your* engineering taste | the skills are part of *the project's* contract |
+
+Non-interactive runs (CI, piped input) default to `--global` silently. Pass `-y` to skip the prompt and accept the default.
 
 ## How `/do` actually flows
 

package/dist/cli.js

@@ -9,20 +9,32 @@ function help() {
     console.log(`pi-dev — autonomous engineering skill framework for the pi runtime
 
 Usage:
-  pi-dev install [--skip-prefs]       Copy skills into ~/.pi/agent/skills and seed
-                                       ~/.pi/agent/preferences.md if missing.
-  pi-dev update [--include-prefs]     Refresh skills. By default keeps your global
-                                       preferences. Pass --include-prefs to overwrite.
-  pi-dev list                         Show installed skills + global prefs path.
-  pi-dev uninstall <skill>            Soft-remove a skill (renamed to .removed-…).
-  pi-dev doctor                       Check ~/.pi layout and external CLIs.
-  pi-dev version                      Print version.
-  pi-dev help                         This message.
+  pi-dev install [scope] [--skip-prefs] [--include-maintainer] [-y]
+      Install skills + seed preferences. Scope is one of:
+        --global   ~/.pi/agent/skills/   (default, every pi session sees it)
+        --local    .pi/skills/ in cwd    (only this repo)
+      Without a flag, an interactive TTY is prompted; non-TTY defaults to global.
+      Pass -y to skip the prompt and accept the default.
+      Pass --include-maintainer to also install maintainer-only skills
+      (only useful if you are developing pi-dev itself).
+
+  pi-dev update [--include-prefs] [--include-maintainer] [--global|--local]
+      Refresh skills in place. Scope is auto-detected from disk
+      (local wins if .pi/skills/ exists in cwd). Preferences are kept by default;
+      pass --include-prefs to re-seed. Maintainer skills already on disk are
+      preserved automatically; pass --include-maintainer to add them on update.
+
+  pi-dev list                 Show installed skills under both scopes (if present).
+  pi-dev uninstall <skill> [--global|--local]
+                              Soft-remove a skill (renamed to .removed-…).
+  pi-dev doctor               Check the active scope's layout and external CLIs.
+  pi-dev version              Print version.
+  pi-dev help                 This message.
 
 After install, in any pi session, you primarily call:
-  /do      — the one-shot engineering entry point
-  /taste   — view or update preferences
-  /where   — recall prior pi sessions for this cwd
+  /do                     — the one-shot engineering entry point
+  /taste                  — view or update preferences
+  /where                  — recall prior pi sessions for this cwd
 
 All other skills are invoked automatically by /do.
 `);
@@ -30,44 +42,66 @@ All other skills are invoked automatically by /do.
 function getFlag(name) {
     return args.includes(`--${name}`);
 }
-switch (cmd) {
-    case "install":
-        install({ skipPrefs: getFlag("skip-prefs") });
-        break;
-    case "update":
-        update({ skipPrefs: !getFlag("include-prefs") });
-        break;
-    case "list":
-        listInstalled();
-        break;
-    case "uninstall": {
-        const name = args[1];
-        if (!name) {
-            console.error("Usage: pi-dev uninstall <skill>");
-            process.exit(1);
+function getScope() {
+    if (getFlag("global"))
+        return "global";
+    if (getFlag("local"))
+        return "local";
+    return undefined;
+}
+async function main() {
+    switch (cmd) {
+        case "install":
+            await install({
+                skipPrefs: getFlag("skip-prefs"),
+                scope: getScope(),
+                yes: getFlag("yes") || args.includes("-y"),
+                includeMaintainer: getFlag("include-maintainer"),
+            });
+            break;
+        case "update":
+            await update({
+                skipPrefs: !getFlag("include-prefs"),
+                scope: getScope(),
+                includeMaintainer: getFlag("include-maintainer"),
+            });
+            break;
+        case "list":
+            listInstalled();
+            break;
+        case "uninstall": {
+            const name = args[1];
+            if (!name || name.startsWith("--")) {
+                console.error("Usage: pi-dev uninstall <skill> [--global|--local]");
+                process.exit(1);
+            }
+            uninstallSkill(name, getScope());
+            break;
         }
-        uninstallSkill(name);
-        break;
-    }
-    case "doctor":
-        doctor();
-        break;
-    case "version":
-    case "--version":
-    case "-v": {
-        const here = dirname(fileURLToPath(import.meta.url));
-        const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
-        console.log(pkg.version);
-        break;
+        case "doctor":
+            doctor();
+            break;
+        case "version":
+        case "--version":
+        case "-v": {
+            const here = dirname(fileURLToPath(import.meta.url));
+            const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+            console.log(pkg.version);
+            break;
+        }
+        case "help":
+        case "--help":
+        case "-h":
+        case undefined:
+            help();
+            break;
+        default:
+            console.error(`Unknown command: ${cmd}\n`);
+            help();
+            process.exit(1);
     }
-    case "help":
-    case "--help":
-    case "-h":
-    case undefined:
-        help();
-        break;
-    default:
-        console.error(`Unknown command: ${cmd}\n`);
-        help();
-        process.exit(1);
 }
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/install.js

@@ -1,21 +1,56 @@
 import { existsSync, mkdirSync, cpSync, copyFileSync, renameSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { join } from "node:path";
-import { SKILLS } from "./manifest.js";
-import { PI_AGENT_DIR, PI_SKILLS_DIR, PI_GLOBAL_PREFS, PKG_SKILLS_DIR, PKG_GLOBAL_PREFS_PRESET, } from "./paths.js";
-export function install(opts = {}) {
-    mkdirSync(PI_SKILLS_DIR, { recursive: true });
+import { createInterface } from "node:readline";
+import { SKILLS, CONSUMER_SKILLS } from "./manifest.js";
+import { PKG_SKILLS_DIR, PKG_GLOBAL_PREFS_PRESET, destFor, } from "./paths.js";
+function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((res) => {
+        rl.question(question, (a) => {
+            rl.close();
+            res(a);
+        });
+    });
+}
+async function resolveScope(opts) {
+    if (opts.scope)
+        return opts.scope;
+    // Non-interactive (CI, piped) → default to global silently.
+    if (opts.yes || !process.stdin.isTTY)
+        return "global";
+    const cwd = process.cwd();
+    const { skillsDir: localSkills } = destFor("local", cwd);
+    const { skillsDir: globalSkills } = destFor("global");
+    console.log("");
+    console.log("pi-dev: where should the skills live?");
+    console.log("");
+    console.log(`  [g] global  →  ${globalSkills}`);
+    console.log(`               every pi session on this machine sees them.`);
+    console.log("");
+    console.log(`  [l] local   →  ${localSkills}`);
+    console.log(`               only pi sessions started from this repo see them.`);
+    console.log(`               pi reads project-local config from .pi/ in the cwd.`);
+    console.log("");
+    const ans = (await ask("Choose [G/l] (default global): ")).trim().toLowerCase();
+    if (ans === "l" || ans === "local")
+        return "local";
+    return "global";
+}
+export async function install(opts = {}) {
+    const scope = await resolveScope(opts);
+    const { agentDir, skillsDir, prefsFile } = destFor(scope);
+    mkdirSync(skillsDir, { recursive: true });
+    const skillsToInstall = opts.includeMaintainer ? SKILLS : CONSUMER_SKILLS;
     let copied = 0;
-    for (const skill of SKILLS) {
+    for (const skill of skillsToInstall) {
         const src = join(PKG_SKILLS_DIR, skill.name);
-        const dst = join(PI_SKILLS_DIR, skill.name);
+        const dst = join(skillsDir, skill.name);
         if (!existsSync(src)) {
             console.warn(`  skip ${skill.name} (source not found in package)`);
             continue;
         }
         if (existsSync(dst) && !opts.force) {
-            // Replace contents but keep the directory; safer than rmSync for skills
-            // the user may have customised lightly.
             cpSync(src, dst, { recursive: true, force: true });
         }
         else {
@@ -23,63 +58,104 @@ export function install(opts = {}) {
         }
         copied++;
     }
-    console.log(`Installed ${copied} skill(s) into ${PI_SKILLS_DIR}`);
+    console.log(`Installed ${copied} skill(s) into ${skillsDir} [${scope}]`);
     if (opts.skipPrefs) {
-        console.log("Skipped global preferences (use --include-prefs on update to merge in new keys).");
+        console.log("Skipped preferences (pass --include-prefs on update to merge in new keys).");
         return;
     }
-    if (!existsSync(PI_GLOBAL_PREFS)) {
+    if (!existsSync(prefsFile)) {
         if (existsSync(PKG_GLOBAL_PREFS_PRESET)) {
-            copyFileSync(PKG_GLOBAL_PREFS_PRESET, PI_GLOBAL_PREFS);
-            console.log(`Seeded global preferences at ${PI_GLOBAL_PREFS}`);
+            copyFileSync(PKG_GLOBAL_PREFS_PRESET, prefsFile);
+            console.log(`Seeded preferences at ${prefsFile} [${scope}]`);
         }
     }
     else {
-        console.log(`Existing global preferences kept at ${PI_GLOBAL_PREFS} (use --include-prefs to merge new keys).`);
+        console.log(`Existing preferences kept at ${prefsFile} (pass --include-prefs to merge new keys).`);
+    }
+    if (scope === "local") {
+        console.log("");
+        console.log("Tip: add `.pi/sessions/` to .gitignore (sessions are local-only).");
+        console.log("     Skills under `.pi/skills/` are safe to commit.");
     }
 }
-export function update(opts = {}) {
-    // Update is install with force, but defaults to NOT overwriting global prefs.
-    install({ ...opts, force: true, skipPrefs: !opts.skipPrefs ? true : opts.skipPrefs });
+export async function update(opts = {}) {
+    // Update is install with force. If scope wasn't passed, infer it from what's
+    // already on disk: a local `.pi/skills/` in cwd wins over global.
+    let scope = opts.scope;
+    if (!scope) {
+        const local = destFor("local");
+        if (existsSync(local.skillsDir))
+            scope = "local";
+        else
+            scope = "global";
+    }
+    // On update, preserve the maintainer set if maintainer skills are already on
+    // disk — no need to make the user re-pass the flag every time.
+    const maintainerAlreadyInstalled = existsSync(join(destFor(scope).skillsDir, "improve-skill-flow", "SKILL.md"));
+    await install({
+        ...opts,
+        scope,
+        force: true,
+        skipPrefs: !opts.skipPrefs ? true : opts.skipPrefs,
+        yes: true,
+        includeMaintainer: opts.includeMaintainer || maintainerAlreadyInstalled,
+    });
 }
-export function uninstallSkill(name) {
-    const dst = join(PI_SKILLS_DIR, name);
+export function uninstallSkill(name, scope) {
+    const resolved = scope ?? (existsSync(destFor("local").skillsDir) ? "local" : "global");
+    const { skillsDir } = destFor(resolved);
+    const dst = join(skillsDir, name);
     if (!existsSync(dst)) {
-        console.error(`Skill not installed: ${name}`);
+        console.error(`Skill not installed [${resolved}]: ${name}`);
         process.exit(1);
     }
-    // Soft delete: rename to .removed-<ts>
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const moved = join(PI_SKILLS_DIR, `.removed-${stamp}-${name}`);
+    const moved = join(skillsDir, `.removed-${stamp}-${name}`);
     renameSync(dst, moved);
-    console.log(`Uninstalled ${name} (moved to ${moved}).`);
+    console.log(`Uninstalled ${name} from ${resolved} (moved to ${moved}).`);
 }
 export function listInstalled() {
-    console.log(`Skills directory: ${PI_SKILLS_DIR}\n`);
-    for (const skill of SKILLS) {
-        const path = join(PI_SKILLS_DIR, skill.name, "SKILL.md");
-        const installed = existsSync(path);
-        const tag = skill.kind === "human" ? "[user]   " : "[support]";
-        const status = installed ? "ok" : "missing";
-        console.log(`  ${tag} /${skill.name.padEnd(34)} ${status}  — ${skill.summary}`);
+    const local = destFor("local");
+    const global = destFor("global");
+    const targets = [];
+    if (existsSync(local.skillsDir))
+        targets.push({ label: "local", ...local });
+    targets.push({ label: "global", ...global });
+    for (const t of targets) {
+        console.log(`Skills directory [${t.label}]: ${t.skillsDir}`);
+        for (const skill of SKILLS) {
+            const path = join(t.skillsDir, skill.name, "SKILL.md");
+            const installed = existsSync(path);
+            const tag = skill.kind === "human"
+                ? "[user]      "
+                : skill.kind === "maintainer"
+                    ? "[maintainer]"
+                    : "[support]   ";
+            const status = installed ? "ok     " : "missing";
+            console.log(`  ${tag} /${skill.name.padEnd(34)} ${status}  — ${skill.summary}`);
+        }
+        console.log(`Preferences: ${existsSync(t.prefsFile) ? t.prefsFile : "(missing)"}`);
+        console.log("");
     }
-    console.log(`\nGlobal preferences: ${existsSync(PI_GLOBAL_PREFS) ? PI_GLOBAL_PREFS : "(missing)"}`);
 }
 export function doctor() {
     const issues = [];
-    if (!existsSync(PI_AGENT_DIR))
-        issues.push(`~/.pi/agent missing — run: pi-dev install`);
-    if (!existsSync(PI_SKILLS_DIR))
-        issues.push(`~/.pi/agent/skills missing — run: pi-dev install`);
+    const local = destFor("local");
+    const hasLocal = existsSync(local.skillsDir);
+    const activeScope = hasLocal ? "local" : "global";
+    const { agentDir, skillsDir, prefsFile } = destFor(activeScope);
+    if (!existsSync(agentDir))
+        issues.push(`${agentDir} missing — run: pi-dev install`);
+    if (!existsSync(skillsDir))
+        issues.push(`${skillsDir} missing — run: pi-dev install`);
     for (const skill of SKILLS.filter((s) => s.kind === "human")) {
-        if (!existsSync(join(PI_SKILLS_DIR, skill.name, "SKILL.md"))) {
-            issues.push(`Human skill /${skill.name} not installed — run: pi-dev update`);
+        if (!existsSync(join(skillsDir, skill.name, "SKILL.md"))) {
+            issues.push(`Human skill /${skill.name} not installed [${activeScope}] — run: pi-dev update`);
         }
     }
-    if (!existsSync(PI_GLOBAL_PREFS)) {
-        issues.push(`Global preferences missing — run: pi-dev install (or copy presets/preferences.md manually)`);
+    if (!existsSync(prefsFile)) {
+        issues.push(`Preferences missing at ${prefsFile} — run: pi-dev install (or copy presets/preferences.md manually)`);
     }
-    // Quick external check (best-effort)
     const checkCmd = (cmd, label) => {
         try {
             execSync(`${cmd} --version`, { stdio: "ignore" });
@@ -90,6 +166,7 @@ export function doctor() {
     };
     checkCmd("git", "git");
     checkCmd("gh", "gh CLI");
+    console.log(`Active scope: ${activeScope}`);
     if (issues.length === 0) {
         console.log("All checks passed.");
         return;

package/dist/manifest.js

@@ -3,6 +3,8 @@
  *
  * `human` skills are what the user calls directly: /do, /taste, /where.
  * `support` skills are auto-invoked by /do or /migrate.
+ * `maintainer` skills are for pi-dev framework maintenance only; they are
+ * NOT installed for consumers by default (pass --include-maintainer to opt in).
  *
  * The skill names match the directory names under `skills/`.
  */
@@ -11,7 +13,8 @@ export const SKILLS = [
     { name: "do", kind: "human", summary: "Do the engineering work end-to-end." },
     { name: "taste", kind: "human", summary: "View / update / onboard preferences." },
     { name: "where", kind: "human", summary: "Recall prior pi sessions for this cwd." },
-    { name: "improve-skill-flow", kind: "human", summary: "Audit pi session telemetry and propose evidence-based SKILL.md edits." },
+    // Maintainer-only — pi-dev framework itself, not shipped to consumers.
+    { name: "improve-skill-flow", kind: "maintainer", summary: "Maintainer-only. Audit pi telemetry, propose SKILL.md edits, release." },
     // Auto-invoked support skills
     { name: "migrate", kind: "support", summary: "Strict migration gate before /do can run." },
     { name: "setup", kind: "support", summary: "Scaffold issue-tracker / triage / domain docs." },
@@ -27,3 +30,5 @@ export const SKILLS = [
 ];
 export const HUMAN_SKILLS = SKILLS.filter((s) => s.kind === "human");
 export const SUPPORT_SKILLS = SKILLS.filter((s) => s.kind === "support");
+export const MAINTAINER_SKILLS = SKILLS.filter((s) => s.kind === "maintainer");
+export const CONSUMER_SKILLS = SKILLS.filter((s) => s.kind !== "maintainer");

package/dist/paths.js

@@ -12,3 +12,15 @@ export const PKG_ROOT = resolve(__dirname, "..");
 export const PKG_SKILLS_DIR = join(PKG_ROOT, "skills");
 export const PKG_PRESETS_DIR = join(PKG_ROOT, "presets");
 export const PKG_GLOBAL_PREFS_PRESET = join(PKG_PRESETS_DIR, "preferences.md");
+/** Compute install destinations for a given scope. `local` resolves against `cwd`. */
+export function destFor(scope, cwd = process.cwd()) {
+    if (scope === "global") {
+        return { agentDir: PI_AGENT_DIR, skillsDir: PI_SKILLS_DIR, prefsFile: PI_GLOBAL_PREFS };
+    }
+    const agentDir = join(cwd, ".pi");
+    return {
+        agentDir,
+        skillsDir: join(agentDir, "skills"),
+        prefsFile: join(agentDir, "preferences.md"),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-dev",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "An autonomous engineering skill framework for the pi runtime — built on Matt Pocock's skills.",
   "type": "module",
   "bin": {

package/skills/improve-skill-flow/SKILL.md

@@ -1,48 +1,71 @@
 ---
 name: improve-skill-flow
-description: Analyse real pi-runtime session telemetry from a consumer repo to find where the engineering skills (especially /do's chain) drift from their stated contract, then propose evidence-anchored edits to the SKILL.md files. Use when the user wants to improve, audit, debug, or evolve the pi-dev skill framework itself based on what actually happened in real sessions ("스킬 개선하자", "do 가 왜 멈춰", "히스토리 보고 분석해서 스킬 고치자", "메타 스킬 작업", etc).
+description: MAINTAINER-ONLY. Analyse real pi-runtime session telemetry from any consumer repo on this machine to find where the engineering skills (especially /do's chain) drift from their stated contract, then propose evidence-anchored edits to pi-dev's own SKILL.md files. Run only from inside the pi-dev repo — it edits pi-dev sources and triggers a release. Use when the maintainer wants to improve, audit, debug, or evolve the pi-dev skill framework itself based on what actually happened in real sessions ("스킬 개선하자", "do 가 왜 멈춰", "히스토리 보고 분석해서 스킬 고치자", "메타 스킬 작업", etc).
 ---
 
 # /improve-skill-flow — Meta-skill for evidence-based skill improvement
 
-The pi-dev skills are pure markdown. They get better by reading what real sessions did, comparing that to what the SKILL.md said *should* happen, and editing the gap closed. This skill is the canonical loop for that.
+**Audience: pi-dev maintainers only.** Consumers do not get this skill installed. Consumers improve their own setup by editing `docs/agents/preferences.md` (per project) or `~/.pi/agent/preferences.md` (per machine), not by editing SKILL.md bodies. The framework is fixed for them; only the maintainer changes it.
+
+The pi-dev skills are pure markdown. They get better when the maintainer reads what real sessions did across consumer repos, compares that to what the SKILL.md said *should* happen, and edits the gap closed. This skill is the canonical loop for that.
 
 The point: **never edit a SKILL.md from gut feeling.** Edit because session N showed phase P violated predicate Q on M occasions, and here is the line that would have prevented it.
 
+## Pre-flight (hard gate)
+
+Refuse to run unless cwd is the pi-dev repo. Releases happen from here; nothing else makes sense.
+
+```bash
+origin=$(git -C "$PWD" remote get-url origin 2>/dev/null || echo "")
+pkg_name=$(jq -r '.name // empty' package.json 2>/dev/null)
+ok=0
+case "$origin" in *pi-dev*|*pi-dev.git) ok=1 ;; esac
+[ "$pkg_name" = "pi-dev" ] && ok=1
+if [ "$ok" != 1 ]; then
+  echo "this skill is maintainer-only; cd into the pi-dev repo and re-run"
+  exit 1
+fi
+```
+
+If the gate fails, stop. Do not proceed in a consumer repo.
+
 ## When to run
 
-- A consumer repo has accumulated at least one real day of pi sessions (≈ 3+ `.jsonl` files).
+- A consumer repo on this machine has accumulated at least one real day of pi sessions (≈ 3+ `.jsonl` files).
 - A specific skill is suspected of misbehaving ("why does `/do` keep stopping?").
 - After landing a skill change, to verify the next session(s) actually follow the new wording.
 - Periodically (every N releases) as a regression sweep across all human-facing skills.
 
+Always from inside the pi-dev checkout (see Pre-flight).
+
 ## What this skill is NOT
 
-- Not for analysing the *codebase* of the consumer repo — that is `improve-codebase-architecture`.
+- Not for analysing the *codebase* of any repo — that is `improve-codebase-architecture`.
 - Not for shipping engineering work — it does not invoke `/do`. Findings turn into proposed SKILL.md diffs, which are committed via the normal release-please flow on `pi-dev`.
 - Not a real-time monitor — it reads completed session files.
+- Not a consumer-facing tool. Consumers don't get this skill installed; they tune their setup via `preferences.md`, not by editing SKILL bodies.
 
 ## Inputs
 
-- **Target repo path** (or its sessions directory). Defaults: the user names a repo; you resolve it.
+- **Consumer repo path** (or its sessions directory) to audit. The maintainer names a repo on this machine; you resolve its sessions dir.
 - Optional: a specific skill name to focus the audit on (`do`, `migrate`, `triage`, …).
 - Optional: a date range.
-- **Install scope** for any fixes that come out of the audit — `global` or `project`. Auto-detected (see Step 5.5); user can override per finding.
+- **Fix scope** per finding — `framework` or `consumer-prefs`. Defaults set in Step 5.5; maintainer can flip individual rows before applying.
 
-## Install scopes
+## Fix scopes
 
-pi-runtime today loads skill bodies from a single location: `~/.pi/agent/skills/<name>/SKILL.md`. The framework's 3-layer override is on **preferences**, not on SKILL bodies. So a finding lands in one of two places:
+pi-runtime today loads skill bodies from a single location (`~/.pi/agent/skills/<name>/SKILL.md` for global installs, `<repo>/.pi/skills/<name>/SKILL.md` for local installs). The framework's 3-layer override is on **preferences**, not on SKILL bodies. So a finding lands in one of two places:
 
 | scope | lands in | reaches | propagation | when to pick |
 | --- | --- | --- | --- | --- |
-| **global** | `pi-dev`'s `skills/<name>/SKILL.md` | every consumer after the next `npx pi-dev update` | release-please → npm publish | the SKILL.md wording itself is wrong; gap shows up generically |
-| **project** | consumer repo's `docs/agents/preferences.md` (Project taboos / Diagnosis posture / Local-live playbook / Free notes — whichever section fits) | only this repo, on every `/do` bootstrap | regular consumer-repo commit | gap is the repo's domain / paths / conventions, not the SKILL.md |
+| **framework** | this repo's `skills/<name>/SKILL.md` | every consumer after the next `npx pi-dev update` | release-please → npm publish | the SKILL.md wording itself is wrong; gap shows up generically |
+| **consumer-prefs** | the audited consumer repo's `docs/agents/preferences.md` (Project taboos / Diagnosis posture / Local-live playbook / Free notes — whichever section fits) | only that repo, on every `/do` bootstrap | regular consumer-repo commit | gap is the consumer repo's domain / paths / conventions, not the SKILL.md |
 
 Notes:
 
-- A `global` apply is **always** mirrored into `~/.pi/agent/skills/<name>/` on the operator's machine so the next session picks it up immediately, without waiting for npm.
-- A `project` apply touches no pi-dev files. It is committed to the consumer repo only.
-- A single audit may produce a mix of global and project findings. Decide scope per finding, not per audit.
+- A `framework` apply is **always** mirrored into `~/.pi/agent/skills/<name>/` on this machine so the next session picks it up immediately, without waiting for npm.
+- A `consumer-prefs` apply touches no pi-dev files. It is committed to the consumer repo only.
+- A single audit may produce a mix of framework and consumer-prefs findings. Decide scope per finding, not per audit.
 
 ## Session-data location & format
 
@@ -82,13 +105,13 @@ Timestamps on `message` records are ISO strings; some other record types use int
 
 ### 1 — Scope and load
 
-Ask the user (one round, only if not already specified):
+Ask the maintainer (one round, only if not already specified):
 
-- target repo (or "all repos with sessions")
+- target consumer repo (or "all repos with sessions on this machine")
 - a skill to focus on, or "everything"
 - a date range or "all"
 
-Resolve the sessions directory. List the `.jsonl` files with size + line count so the user can see the input scale.
+Resolve the sessions directory. List the `.jsonl` files with size + line count so the maintainer can see the input scale.
 
 ### 2 — Build the raw signal table
 
@@ -116,7 +139,7 @@ Use a deterministic Python or shell script you write once and check into `/tmp`
 
 ### 3 — Cross-reference with repo state
 
-For the same date range, pull:
+For the same date range, pull (against the **consumer repo** being audited):
 
 - `git log --since=<start> --pretty=format:"%h %ad %s"` — commit cadence vs. the predicate `auto-commit-per-slice`.
 - `gh issue list / pr list` (if GitHub) — slice/PR shape vs. `default-issue-style=vertical-slice`.
@@ -126,7 +149,7 @@ For the same date range, pull:
 Cross-reference each signal against:
 
 - The skill's **terminal predicate** in `do/SKILL.md` → "Phase contracts".
-- The repo's **`docs/agents/preferences.md`** taboos and `auto-*` settings.
+- The consumer repo's **`docs/agents/preferences.md`** taboos and `auto-*` settings.
 - The hard rules in the skill being audited.
 
 ### 4 — Score the gaps
@@ -157,31 +180,17 @@ For every 🔴 / 🟡 row, quote the smallest piece of evidence that makes the g
 
 If a finding cannot be backed by an excerpt, it is not actionable yet — demote to a TODO and keep digging.
 
-### 5.5 — Decide install scope per finding (auto + user-overridable)
-
-For each 🔴 / 🟡 finding, pick a default scope using this two-step heuristic, then show the table to the user once and let them flip individual rows before applying.
+### 5.5 — Decide fix scope per finding (auto + maintainer-overridable)
 
-**Step A — detect operator context.** Run once at the start of this step:
+For each 🔴 / 🟡 finding, pick a default scope using the heuristic below, then show the table once and let the maintainer flip individual rows before applying.
 
-```bash
-origin=$(git -C "$PWD" remote get-url origin 2>/dev/null || echo "")
-pkg_name=$(jq -r '.name // empty' package.json 2>/dev/null)
-is_maintainer=false
-case "$origin" in *pi-dev*|*pi-dev.git) is_maintainer=true ;; esac
-[ "$pkg_name" = "pi-dev" ] && is_maintainer=true
-echo "operator_context=$([ \"$is_maintainer\" = true ] && echo maintainer || echo consumer)"
-```
-
-- `operator_context=maintainer` → cwd is the pi-dev repo itself; the release path is available.
-- `operator_context=consumer` → cwd is a downstream repo; no release path. `global` findings here become "draft a patch + open an upstream PR / issue" rather than "push and release".
-
-**Step B — score each finding.** Default to `global` if the finding matches **any** of:
+Default to `framework` if the finding matches **any** of:
 
 - Cites SKILL.md wording / phase / predicate / rule numbers.
 - The proposed fix is a generic anti-pattern string, a terminator literal, a runway line, or a lockout that any repo would benefit from.
 - The same gap would plausibly show up in two or more consumer repos.
 
-Default to `project` if the finding matches **any** of:
+Default to `consumer-prefs` if the finding matches **any** of:
 
 - Cites a repo-specific path (`src/core/...`, `bin/...-smoke.ts`), brand, schema, table, or domain term.
 - The fix is a taboo, a smoke convention, an env / boot detail, or a glossary entry.
@@ -190,28 +199,28 @@ Default to `project` if the finding matches **any** of:
 Present the scope-decision table:
 
 ```
-| # | finding (short)                          | default scope | target file                          | flip? |
-| - | ---------------------------------------- | ------------- | ------------------------------------ | ----- |
-| 1 | /do hands flow back between phases       | global        | pi-dev:skills/do/SKILL.md            |       |
-| 2 | docs/handoff/ resurrected after marker   | global        | pi-dev:skills/migrate/SKILL.md       |       |
-| 3 | retro-action-item label still alive      | project       | hugn:docs/agents/preferences.md      |       |
-| 4 | smoke command name changed in S058       | project       | hugn:docs/agents/preferences.md      |       |
+| # | finding (short)                          | default scope    | target file                          | flip? |
+| - | ---------------------------------------- | ---------------- | ------------------------------------ | ----- |
+| 1 | /do hands flow back between phases       | framework        | pi-dev:skills/do/SKILL.md            |       |
+| 2 | docs/handoff/ resurrected after marker   | framework        | pi-dev:skills/migrate/SKILL.md       |       |
+| 3 | retro-action-item label still alive      | consumer-prefs   | hugn:docs/agents/preferences.md      |       |
+| 4 | smoke command name changed in S058       | consumer-prefs   | hugn:docs/agents/preferences.md      |       |
 ```
 
-Ask the user once: "OK to proceed with these scopes? Reply with row numbers to flip, or `go`." Apply their flips and move on. If `operator_context=consumer`, any rows still marked `global` get the suffix `(via upstream PR — cannot release locally)` and the apply step adjusts accordingly.
+Ask once: "OK to proceed with these scopes? Reply with row numbers to flip, or `go`." Apply the flips and move on.
 
 ### 6 — Propose edits (per-finding, scoped)
 
 For each 🔴 / 🟡 finding, draft the smallest possible edit that, **if it had been in place at session time, would have prevented the gap.** The shape of the draft depends on the scope from Step 5.5:
 
-**Global findings (target: pi-dev SKILL.md):**
+**Framework findings (target: pi-dev SKILL.md):**
 
 - Edit a **rule** or a **step**, not a flavour sentence. The model must be able to detect the constraint in its own draft output.
 - Prefer **explicit anti-pattern strings** ("Do not say 'shall I continue?'") over abstract injunctions ("be decisive"). The hugn-2026-05 audit showed that named anti-patterns work.
 - Prefer **terminal markers** ("the summary's last line must be one of these two literals: …") over qualitative descriptions of "good wrap-up".
 - Update **at most three skills per run.** More than that means findings aren't anchored well enough.
 
-**Project findings (target: consumer's `docs/agents/preferences.md`):**
+**Consumer-prefs findings (target: that repo's `docs/agents/preferences.md`):**
 
 - Pick the *narrowest* existing section that fits before adding a new one. Mapping:
 
@@ -228,31 +237,25 @@ For each 🔴 / 🟡 finding, draft the smallest possible edit that, **if it had
 - One bullet per finding. Reference the evidence ticket ("S058 smoke name", "#103 missing disclaimer") so the line stays auditable.
 - Do **not** invent new top-level sections unless three findings legitimately share one.
 
-Show all drafts as one unified diff per target file before applying. Group by target file: pi-dev's `skills/<name>/SKILL.md` first (global), then consumer's `docs/agents/preferences.md` (project).
+Show all drafts as one unified diff per target file before applying. Group by target file: pi-dev's `skills/<name>/SKILL.md` first (framework), then the consumer's `docs/agents/preferences.md` (consumer-prefs).
 
 ### 7 — Apply, release, verify (branches on scope)
 
 Run both branches if the audit produced mixed-scope findings. Each branch has its own terminal state.
 
-**7a. Global branch** — only if any finding was approved as `global` **and** `operator_context=maintainer`:
+**7a. Framework branch** — only if any finding was approved as `framework`:
 
-1. From the pi-dev checkout: `git add skills/<name>/SKILL.md && git commit -m "<conventional commit anchoring the evidence>"`. Commit body must cite the signal that motivated each change.
+1. From the pi-dev checkout (this repo): `git add skills/<name>/SKILL.md && git commit -m "<conventional commit anchoring the evidence>"`. Commit body must cite the signal that motivated each change.
 2. `cp` each edited SKILL.md into `~/.pi/agent/skills/<name>/` so the **next** session anywhere picks up the change immediately (release-please takes a minute and a half).
 3. `git push origin main`; release-please opens the version-bump PR; merge it; npm publish runs automatically.
 4. Confirm `npm view pi-dev@latest version` matches the bumped tag.
 
-**7a' — Global findings when `operator_context=consumer`:** you cannot release. Instead:
+**7b. Consumer-prefs branch** — only if any finding was approved as `consumer-prefs`:
 
-1. Stash the proposed diffs to `/tmp/pi-dev-upstream-<date>.patch` with one file per skill.
-2. Open an issue on `pi-dev` (or a PR if the operator has clone+push rights) with the evidence excerpts and the patch attached.
-3. As a hotfix for this machine only, optionally `cp` the edited bodies into `~/.pi/agent/skills/<name>/` and note in the issue that the next `pi-dev update` will overwrite them — which is the desired end state once the upstream change lands.
-
-**7b. Project branch** — only if any finding was approved as `project`:
-
-1. In the consumer repo: edit `docs/agents/preferences.md` per the drafts from Step 6. Keep the migration marker at the very end of the file undisturbed.
+1. In the audited consumer repo: edit `docs/agents/preferences.md` per the drafts from Step 6. Keep the migration marker at the very end of the file undisturbed.
 2. Bump the `last-updated` line at the top of the file to today's UTC date.
 3. `git add docs/agents/preferences.md && git commit -m "docs(agents): <one-liner per finding>"`. Conventional Commits apply.
-4. Push per the repo's normal workflow. No release-please involvement — preferences are not packaged.
+4. Push per that repo's normal workflow. No release-please involvement — preferences are not packaged.
 
 **Verification (both branches).** After the next pi session in the affected repo:
 
@@ -265,9 +268,9 @@ Run both branches if the audit produced mixed-scope findings. Each branch has it
 This skill is done when **all four** are true:
 
 1. A signal table with severities and evidence excerpts has been presented.
-2. Each finding has an approved scope (`global` / `project` / `defer`) on record, defaulted by Step 5.5 and confirmed by the user.
-3. Either (a) zero 🔴 findings — flow is healthy, recorded as "no change this cycle", OR (b) each 🔴 finding has landed in its scope's target file (or been stashed + filed upstream when an operator-context mismatch prevents release).
-4. For any landed change: if `global` and `maintainer`, the npm version has bumped (`npm view pi-dev@latest version`); if `project`, the consumer repo has the commit on its push-stream. Either way, the next-session re-audit plan is stated.
+2. Each finding has an approved scope (`framework` / `consumer-prefs` / `defer`) on record, defaulted by Step 5.5 and confirmed by the maintainer.
+3. Either (a) zero 🔴 findings — flow is healthy, recorded as "no change this cycle", OR (b) each 🔴 finding has landed in its scope's target file.
+4. For any landed change: if `framework`, the npm version has bumped (`npm view pi-dev@latest version`); if `consumer-prefs`, the consumer repo has the commit on its push-stream. Either way, the next-session re-audit plan is stated.
 
 The summary's **last line** must be one of:
 
@@ -276,17 +279,14 @@ audit complete — no changes this cycle.
 ```
 
 ```
-audit complete — global v<X.Y.Z> released, project commit <sha>, next re-audit after the next session.
-```
-
-```
-audit complete — upstream issue <#N> filed, project commit <sha>, hotfix mirrored to ~/.pi.
+audit complete — framework v<X.Y.Z> released, consumer-prefs commit <sha>, next re-audit after the next session.
 ```
 
 ## What this skill does not do
 
-- It does not modify a consumer repo's code, issues, or preferences. It only edits **pi-dev's own `skills/`**.
+- It does not modify a consumer repo's code or issues. It edits **pi-dev's own `skills/`** (framework scope) and — only when the audit demands it — the consumer's `docs/agents/preferences.md` (consumer-prefs scope).
 - It does not invent gaps from first principles. Every finding must come from a session excerpt or a repo-state probe.
+- It does not run from a consumer repo. The Pre-flight gate refuses; cd into pi-dev first.
 - It does not run faster than the data allows — if there is only one session, run it but say so up front; the signal is noisy.
 
 ## Heuristics
@@ -299,4 +299,4 @@ audit complete — upstream issue <#N> filed, project commit <sha>, hotfix mirro
 
 ## Why this skill exists
 
-Skills are prose. Prose drifts. Without a feedback loop, the SKILL.md files become wishful thinking that the agent ignores in real sessions. This skill is the loop.
+Skills are prose. Prose drifts. Without a feedback loop, the SKILL.md files become wishful thinking that the agent ignores in real sessions. This skill is the loop — and it is the maintainer's loop, not the consumer's.

package/skills/where/SKILL.md

@@ -1,11 +1,17 @@
 ---
 name: where
-description: Quickly absorb relevant prior pi sessions for the current cwd so multi-session work continues without rediscovery. Use when the user says "지난주에 뭐했지", "where were we", "이어서 가자", "다시 시작", or when /do detects continuation intent.
+description: Answer "where are we?" for this cwd — what stage the work is at, what just happened, and what comes next — by reading prior pi sessions, git, and the issue tracker. Use when the user says "지금 어디야", "우리 어디까지 했지", "지난주에 뭐했지", "where were we", "이어서 가자", "다시 시작", "다음 로드맵", or when /do detects continuation intent.
 ---
 
-# /where — Recall pi History
+# /where — Where Are We?
 
-This is a pi-specific skill. pi stores every session as a JSONL stream under `~/.pi/agent/sessions/<encoded-cwd>/<ts>_<sessionId>.jsonl`. This skill gives the agent a disciplined way to find and ingest only the slice of history that matters, without bloating context.
+The essence of this skill: answer three questions, in this order, about the current cwd.
+
+1. **어디까지 왔나 (stage)** — what phase / slice / release the work is in *right now*.
+2. **최근 뭐했나 (recent)** — what the last 1–3 sessions actually did, condensed.
+3. **다음 뭐 할까 (next)** — the most plausible next action, with the file / issue / command that picks it up.
+
+pi stores every session as a JSONL stream under `~/.pi/agent/sessions/<encoded-cwd>/<ts>_<sessionId>.jsonl`. That stream plus `git log` plus the issue tracker are the three signals this skill fuses to answer the three questions above. Without that fusion, "recall" is just history dumping; with it, the user can resume in one turn.
 
 ## When to use
 
@@ -19,18 +25,35 @@ Do not use:
 - To bypass the migration gate (it doesn't)
 - As a replacement for ADRs, CONTEXT.md, or issues (those are the durable channels)
 
+## Default action (zero-message invocation)
+
+When `/where` is invoked with **no accompanying user text** (the SKILL block is the only thing in the user turn), the invocation itself is the request: *"지금 어디야, 최근 뭐했고, 다음은 뭐야?"*
+
+Default behaviour, executed immediately and in the same turn:
+
+1. Run the full Process below with the **default relevance window** (last 3 sessions by mtime).
+2. Render the position card (the three sections: stage / recent / next).
+3. End with the next-action proposal as a question the user can confirm or correct.
+
+Do **not** print preamble like "What would you like me to recall?" or "Please specify a date range." The user already chose the skill; the only legal opening move is to start producing the card. Ask for narrowing only if Step 1 finds zero session files **and** `git log` shows no recent commits.
+
 ## Process
 
+Execute these steps as your **first action** after the skill loads. Do not narrate the plan, do not ask whether to proceed — run Step 1 immediately.
+
 ### 1. Resolve session directory
 
-```
-cwd = $(pwd)
-encoded = cwd with every "/" replaced by "-", wrapped in double dashes:
-   /Users/jason/pi/pi-mono  →  --Users-jason-pi-pi-mono--
-sessions_dir = ~/.pi/agent/sessions/$encoded
+Run this bash, do not just describe it:
+
+```bash
+cwd="$(pwd)"
+encoded="--$(echo "$cwd" | sed 's|^/||; s|/|-|g')--"
+sessions_dir="$HOME/.pi/agent/sessions/$encoded"
+[ -d "$sessions_dir" ] || { echo "no prior pi sessions for this cwd: $cwd"; exit 0; }
+ls -t "$sessions_dir"/*.jsonl 2>/dev/null | head -3
 ```
 
-If `sessions_dir` does not exist, exit cleanly: "no prior pi sessions for this cwd".
+If the directory does not exist, print exactly `no prior pi sessions for this cwd` and stop — nothing else to do.
 
 ### 2. Pick relevance window
 
@@ -44,54 +67,64 @@ ls -t ~/.pi/agent/sessions/$encoded/*.jsonl | head -3
 
 For each candidate file, read just the **first 3 lines** to get session metadata (id, model, cwd, timestamp). Skip files older than the window.
 
-### 4. Targeted extraction
+### 4. Targeted extraction (per session)
 
 Pull only these event kinds from each in-window jsonl:
 
-- `message` where `role=user` (intent)
-- `message` where `role=assistant` AND content includes one of: a heading, a final summary block, a list of changed files, a commit SHA, an issue URL
-- Tool calls of types: `Edit`, `Write`, `Bash` (filter by command keyword: `git commit|push|gh issue|gh pr`)
-- Any explicit handoff strings (`flow complete`, `Final summary`, `[flow] complete`)
+- `message` where `message.role == "user"` (intent)
+- `message` where `message.role == "assistant"` AND content includes one of: a heading, a final summary block, a list of changed files, a commit SHA, an issue URL
+- pi tool blocks of `name in ("edit", "write")` and lower-case `name == "bash"` whose `input.command` matches `git commit|git push|gh issue|gh pr`
+- Any explicit handoff strings (`chain complete`, `Final summary`, `flow complete`, `audit complete`)
 
-Implementation hint (jq):
+Implementation hint (jq, pi format — messages are nested under `.message`):
 
 ```bash
 jq -c 'select(
-  (.type == "message" and .role == "user") or
-  (.type == "tool_use" and (.name == "Edit" or .name == "Write")) or
-  (.type == "tool_use" and .name == "Bash" and (.input.command | test("git commit|git push|gh issue|gh pr"))) or
-  (.type == "message" and .role == "assistant" and (.content | tostring | test("Final summary|flow complete|## Summary")))
+  (.type == "message" and .message.role == "user") or
+  (.type == "message" and .message.role == "assistant" and ((.message.content // []) | tostring | test("chain complete|audit complete|Final summary|## Summary|flow complete")))
 )' <file>
 ```
 
 If `jq` is unavailable or the file format does not match, fall back to `grep`-based filters on the raw file. Keep extraction under 200 lines per session.
 
-### 5. Synthesise a recall card
+### 4b. Cross-reference live state
+
+The session log alone says "what was discussed". To answer **stage** and **next** you also need what actually landed:
+
+```bash
+git log --since="3 days ago" --pretty=format:"%h %ad %s" --date=short | head -10
+git status -sb
+# if GitHub is the tracker:
+gh pr list --state open --limit 5 2>/dev/null
+gh issue list --state open --limit 5 2>/dev/null
+```
+
+Reconcile: a session that ended with a commit + merged PR → stage = shipped; a session that ended with `git status` dirty or an open PR → stage = in flight; a session whose last assistant turn proposed a follow-up command → that command *is* the next action.
+
+### 5. Synthesise a position card
 
-Output exactly this shape, no more:
+Output exactly this three-section shape, no more. Each section answers one of the three questions.
 
 ```markdown
-## Recall: <cwd> — last <N> sessions
+## Where we are — <cwd>
 
-### <YYYY-MM-DD HH:MM> — session <short-id>
-- **Intent**: <one line drawn from the first user message>
-- **Touched**: <comma-separated file paths from Edit/Write tools>
-- **Side effects**: <commit SHAs / issue URLs / PR URLs>
-- **State**: <complete | incomplete: <reason>>
+### Stage (어디까지 왔나)
+<2–4 lines: current branch, last shipped version / merged PR, any open Release PR, any in-flight slice. One sentence per fact, no narration.>
 
-### <YYYY-MM-DD HH:MM> — session <short-id>
-...
+### Recent (최근 뭐했나 — last <N> sessions)
 
-## Continuation hypothesis
+- **<YYYY-MM-DD HH:MM> — <short-id>**: <intent in one line> → <files touched, condensed> → <side effects: commit SHA / PR / issue URL> — <complete | incomplete: <reason>>
+- **<YYYY-MM-DD HH:MM> — <short-id>**: …
 
-<one paragraph: what was likely left undone, which files/issues to look at first>
+### Next (다음 뭐 할까)
+<one paragraph: the single most plausible next action, named with the exact file / issue # / command that picks it up. If multiple candidates, rank them and pick #1; list #2–3 in one line.>
 ```
 
-Stop here. Do not start work. The hypothesis is the bridge to `/do`.
+Stop here. Do not start work. The Next section is the bridge to `/do` — it states an action, not a menu.
 
 ### 6. Hand off
 
-If the user confirms the hypothesis, invoke `/do` with the resolved intent + scope. If the hypothesis is wrong, ask one clarifying question and try once more.
+End with one short question: "이걸로 갈까?" (or English equivalent). If the user confirms the Next action, invoke `/do` with the resolved intent + scope. If the user picks a different candidate or corrects the framing, run Step 1 again with the narrower window and try once more.
 
 ## Privacy / safety