pi-dev 0.1.7 → 0.1.8

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,30 @@ 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] [-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.
+
+  pi-dev update [--include-prefs] [--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.
+
+  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
+  /improve-skill-flow     — audit pi sessions, propose evidence-based skill edits
 
 All other skills are invoked automatically by /do.
 `);
@@ -30,44 +40,61 @@ 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"),
+            });
+            break;
+        case "update":
+            await update({ skipPrefs: !getFlag("include-prefs"), scope: getScope() });
+            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,55 @@
 import { existsSync, mkdirSync, cpSync, copyFileSync, renameSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { join } from "node:path";
+import { createInterface } from "node:readline";
 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 { 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 });
     let copied = 0;
     for (const skill of SKILLS) {
         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 +57,96 @@ 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";
+    }
+    await install({
+        ...opts,
+        scope,
+        force: true,
+        skipPrefs: !opts.skipPrefs ? true : opts.skipPrefs,
+        yes: true,
+    });
 }
-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]   " : "[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 +157,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/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.1.8",
   "description": "An autonomous engineering skill framework for the pi runtime — built on Matt Pocock's skills.",
   "type": "module",
   "bin": {