pi-gauntlet 4.0.0

package/agents/spec-summarizer.md

@@ -0,0 +1,42 @@
+---
+name: spec-summarizer
+description: Produces a tight, human-readable summary of a single spec for the brainstorming user review gate. Fresh context, read-only, reads only the spec file it is given. Dispatched only by the brainstorming skill's gate step; not for direct dispatch.
+tools: read
+defaultContext: fresh
+inheritProjectContext: false
+inheritSkills: false
+completionGuard: false
+systemPromptMode: replace
+---
+
+You are a cold reader producing a tight, human-readable summary of one spec, so a supervising human can green-light plan + execution without reading the whole document. The summary is a decision aid, not a rewrite.
+
+You receive the absolute path to a spec file. Read **only that file**. Do not read any other file, do not grep, find, ls, or explore the codebase, and do not infer anything beyond what the spec states. If the spec references external context it does not contain (a ticket, an acceptance criterion, a commit SHA, another doc), do not invent it - list it in the gap footer.
+
+Your output is judged on whether a busy supervisor can decide from it alone. A thin or confused summary is a faithful signal that the spec itself is thin - do not paper over gaps to look complete.
+
+## What to emit
+
+Optimize for "what does a supervisor need to approve **this** spec." The list below is a recommended checklist, not a rigid template:
+
+- **Omit any section that is empty.** A bugfix has no new endpoint; a refactor has no algorithm. Write nothing for an empty section - never "N/A" or filler.
+- **Order decision-layer-first** (problem -> decisions -> scope -> risk), then the descriptive layer, so the reader can stop early once confident.
+- **Add a section the spec demands** if it carries decision-relevant content none of the below captures.
+
+Recommended sections:
+
+1. **Problem + idea** - 3-5 sentences: what's broken and the chosen approach.
+2. **Key decisions** - the decisions that define the solution, plus any notable rejected alternative ("chose X over Y because Z").
+3. **Scope** - what's in, and what's explicitly out (non-goals).
+4. **Risk surface** - shared contracts, schema/migrations, irreversibility, rollout - where approval risk concentrates.
+5. **Inputs / conditions / UI / endpoints.**
+6. **Outputs** - new pages, comms protocols, DB/data changes.
+7. **Key changes to the current process.**
+8. **Caveats / edge cases.**
+9. **Algorithm** - only if the spec defines one. Give the key mechanism and decision points; an example with a short explanation beats an exhaustive step transcript. Skip SQL/syntax.
+10. **Acceptance** - how we'll know it's done, only if the spec defines it.
+11. **Gap footer** - external context the spec leans on but does not inline. Omit if there is none.
+
+Tight, human-readable, no obvious statements. If the topic is complex, an example with explanation beats prose.
+
+Output the summary as your final text response. Do not write any file.

package/bin/install-agents.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * Install agents/*.md into the pi-cohort discovery path.
+ *
+ * Two modes, chosen by where this package was installed:
+ *
+ *   - PROJECT install (package lives under <repo>/.pi/...): copy personas into
+ *     <repo>/.pi/agents/ so pi-cohort discovers them at PROJECT scope. Copy
+ *     (not symlink) because a consumer may commit .pi/agents/; a symlink would
+ *     point into the gitignored .pi/git/... install dir and commit as a broken
+ *     machine-local path. The dir is install-managed, so copies refresh on every
+ *     install. Project scope wins over user scope, keeping repos independent.
+ *
+ *   - USER install (package under <home>/.pi/<profile>/...) or a local-path dev
+ *     install (no .pi ancestor): symlink personas into getAgentDir()/agents,
+ *     i.e. $PI_CODING_AGENT_DIR/agents or ~/.pi/agent/agents by default. This is
+ *     pi-cohort's profile-scoped user dir (userDirOld), so each pi profile
+ *     gets its own personas instead of sharing the global ~/.agents. Symlinks
+ *     give live dev-edit and refresh on install; non-symlink files are left.
+ *
+ * Migration: pi-cohort discovers BOTH getAgentDir()/agents and the legacy
+ * global ~/.agents, and ~/.agents wins on name collisions. Older versions of
+ * this package symlinked into ~/.agents, so on a user install we remove any
+ * stale ~/.agents/<name>.md symlinks that point into a pi-gauntlet package;
+ * otherwise they would shadow the new profile-scoped install.
+ *
+ * Override the target dir via PI_GAUNTLET_AGENT_DIR (always symlink mode).
+ *
+ * Invoked automatically by `npm install` (which pi runs on git package installs)
+ * and manually via `npm run link-agents` for local-path dev installs.
+ */
+import { readdirSync, symlinkSync, unlinkSync, mkdirSync, existsSync, lstatSync, copyFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, basename } from "node:path";
+import { homedir } from "node:os";
+
+const PKG_DIR = dirname(fileURLToPath(import.meta.url)).replace(/\/bin$/, "");
+const AGENTS_SRC = join(PKG_DIR, "agents");
+
+if (!existsSync(AGENTS_SRC)) {
+  console.log(`pi-gauntlet: no agents/ dir at ${AGENTS_SRC}; skipping`);
+  process.exit(0);
+}
+
+const personas = readdirSync(AGENTS_SRC).filter((n) => n.endsWith(".md"));
+const { target, mode } = resolveTarget(PKG_DIR);
+if (!existsSync(target)) mkdirSync(target, { recursive: true });
+
+for (const f of personas) {
+  const src = join(AGENTS_SRC, f);
+  const dst = join(target, f);
+  const dstStat = safelstat(dst);
+
+  if (mode === "copy") {
+    if (dstStat?.isSymbolicLink()) unlinkSync(dst);
+    copyFileSync(src, dst);
+    console.log(`pi-gauntlet: copied ${dst}`);
+    continue;
+  }
+
+  if (dstStat === null) {
+    symlinkSync(src, dst);
+    console.log(`pi-gauntlet: linked ${dst}`);
+  } else if (dstStat.isSymbolicLink()) {
+    unlinkSync(dst);
+    symlinkSync(src, dst);
+    console.log(`pi-gauntlet: refreshed ${dst}`);
+  } else {
+    console.warn(`pi-gauntlet: skip ${dst} (not a symlink; delete to install)`);
+  }
+}
+
+if (mode === "symlink") migrateLegacyGlobalLinks(personas, target);
+
+/**
+ * Decide where personas go and how. A project install is one whose nearest
+ * `.pi` ancestor is NOT the user's home `.pi` (i.e. `<repo>/.pi`, not
+ * `<home>/.pi/<profile>`). Env override always forces user-style symlinks.
+ */
+function resolveTarget(pkgDir) {
+  if (process.env.PI_GAUNTLET_AGENT_DIR) {
+    return { target: expandTilde(process.env.PI_GAUNTLET_AGENT_DIR), mode: "symlink" };
+  }
+  const piDir = findPiAncestor(pkgDir);
+  if (piDir && canonical(dirname(piDir)) !== canonical(homedir())) {
+    return { target: join(piDir, "agents"), mode: "copy" };
+  }
+  return { target: join(getAgentDir(), "agents"), mode: "symlink" };
+}
+
+/** Mirror of pi-cohort shared/utils.ts getAgentDir(). */
+function getAgentDir() {
+  const configured = process.env.PI_CODING_AGENT_DIR;
+  if (configured === "~") return homedir();
+  if (configured?.startsWith("~/")) return join(homedir(), configured.slice(2));
+  return configured || join(homedir(), ".pi", "agent");
+}
+
+/**
+ * Remove stale ~/.agents/<name>.md symlinks left by older versions, so the
+ * legacy global dir stops shadowing the profile-scoped install. Only touches
+ * symlinks resolving into a pi-gauntlet package; leaves real files and
+ * unrelated links alone. Skips when the new target already IS ~/.agents.
+ */
+function migrateLegacyGlobalLinks(names, newTarget) {
+  const legacy = join(homedir(), ".agents");
+  if (canonical(legacy) === canonical(newTarget)) return;
+  for (const f of names) {
+    const p = join(legacy, f);
+    const st = safelstat(p);
+    if (!st?.isSymbolicLink()) continue;
+    if (canonical(p).includes("pi-gauntlet")) {
+      unlinkSync(p);
+      console.log(`pi-gauntlet: removed legacy ${p}`);
+    }
+  }
+}
+
+function findPiAncestor(start) {
+  let dir = start;
+  for (;;) {
+    if (basename(dir) === ".pi") return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function expandTilde(p) {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/")) return join(homedir(), p.slice(2));
+  return p;
+}
+
+function canonical(p) {
+  try { return realpathSync(p); } catch { return p; }
+}
+
+function safelstat(p) {
+  try { return lstatSync(p); } catch { return null; }
+}