portable-agent-layer 0.59.0 → 0.60.0

package/README.md

@@ -88,6 +88,9 @@ pal cli status        # check your setup
 | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
 | `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
 | `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |
+| `pal cli subagent link <name>` | Install a personal `~/.pal/agents/<name>.md` (merged multi-platform definition) into every installed agent, split per platform |
+| `pal cli subagent doctor <name>` | Evaluate a subagent definition against the authoring best practices (name/file match, per-platform blocks, model/tools/permission shape, shipped-name collision) |
+| `pal cli subagent list` | List the user-authored subagents in `~/.pal/agents/` |
 
 ### Target flags
 

package/assets/agents/subagent-author.md

@@ -0,0 +1,50 @@
+---
+name: subagent-author
+description: Authors a new personal PAL subagent end-to-end — writes the merged multi-platform definition under ~/.pal/agents/, installs it into every agent, and runs the doctor. Invoked by the create-subagent skill to delegate the authoring to a flagship model.
+
+claude:
+  tools: Bash, Read, Write, Edit, Grep, Glob
+  model: fable
+
+opencode:
+  mode: subagent
+  permission:
+    read: allow
+    write: allow
+    edit: allow
+    bash: allow
+
+cursor:
+  model: inherit
+  readonly: false
+  is_background: false
+---
+
+You author a single new personal subagent for this user. You are handed a **subagent name** and a **description**, and interview answers about its model, tools, skills, and system prompt.
+
+## Steps
+
+1. Read the authoring guide — it is the single source of truth for the merged frontmatter schema and per-platform field rules:
+   ```bash
+   cat ~/.pal/skills/create-subagent/authoring-guide.md
+   ```
+2. Validate the name: lowercase-kebab, no spaces. It must not collide with an existing personal subagent (`pal cli subagent list`) or a shipped one. If it collides or is malformed, stop and report the conflict instead of overwriting.
+3. Write `~/.pal/agents/<name>.md` (create `~/.pal/agents/` if missing), populated per the guide's merged schema: global `name` + `description`, then only the platform blocks that matter (`claude:`, `opencode:`, `cursor:`, `copilot:`), then the system prompt body. Remember: `skills:` is Claude-only and preloads — for other agents, name intended skills in the body.
+4. Install it into every installed agent:
+   ```bash
+   pal cli subagent link <name>
+   ```
+5. Run the doctor and fix every `✗` error; weigh each `⚠`:
+   ```bash
+   pal cli subagent doctor <name>
+   ```
+   A name/file mismatch makes the subagent silently fail to load — never skip this.
+6. Hand-check what the doctor can't: trigger clarity (would the parent agent delegate from the description alone?), role discipline (one job), prompt concreteness, and least-privilege tool/permission fit.
+
+## Output
+
+Return, concisely:
+- The path of the created definition (`~/.pal/agents/<name>.md`).
+- The agents it was installed into (from the `pal cli subagent link` output).
+- The doctor's final result (errors resolved).
+- A 2-3 sentence summary of the subagent's role and when to delegate to it.

package/assets/skills/create-subagent/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: create-subagent
+description: "Create a user-scoped subagent for every installed agent (Claude Code, opencode, Cursor, Copilot) from one merged definition, then install and run the doctor on it. Use when the user asks to create a subagent, add a custom agent, delegate a role to a specialized agent, or \"make a subagent that…\"."
+argument-hint: <subagent name> <what it does + when to delegate>
+---
+
+# Create a personal subagent
+
+This authors a personal subagent into the user's own `~/.pal/agents/<name>.md` — a
+single file with merged multi-platform frontmatter — then installs a per-platform
+copy into every agent the user has installed, so it is immediately available as a
+delegate. It does not touch the subagents PAL ships (those live in the repo).
+
+The per-platform frontmatter schema and every field rule live in one place — read it
+before writing anything:
+
+```bash
+cat ~/.pal/skills/create-subagent/authoring-guide.md
+```
+
+## Workflow when invoked with `<name> <description>`
+
+1. Validate the name: lowercase-kebab, no spaces. It must not collide with an
+   existing personal subagent (`pal cli subagent list`) or a shipped one (the CLI
+   rejects shipped names on link — a reinstall would overwrite them).
+2. Interview the user for what the description leaves unspecified. Ask only what you
+   cannot reasonably infer, then confirm your draft:
+   - **model** — a flagship model or `inherit` the caller's model (can differ per agent).
+   - **tools** — which tools it may use (a comma list for Claude/Copilot; a permission
+     map for opencode). Default: inherit all tools.
+   - **skills** — skills to PRELOAD. Claude Code only; the other agents have no such
+     field (see the guide). Record intended skills in the body for the others.
+   - **system prompt** — the role and behavior. Draft it and confirm with the user.
+3. Check whether a flagship authoring model is configured for the current agent:
+   ```bash
+   pal cli subagent author-model
+   ```
+4. **If it prints a model** → delegate the authoring to the `subagent-author` subagent
+   (preconfigured to run on that flagship model). Hand it the name, description, and
+   interview answers; let it write `~/.pal/agents/<name>.md`, run `pal cli subagent
+   link`, and run the doctor. Relay its result.
+5. **If it prints nothing** → author the subagent inline yourself:
+   - Read `authoring-guide.md` (above) and follow the merged frontmatter schema.
+   - Write `~/.pal/agents/<name>.md` (create `~/.pal/agents/` if it is missing).
+   - Install it into every installed agent:
+     ```bash
+     pal cli subagent link <name>
+     ```
+   - Run the doctor and fix every `✗` error; weigh each `⚠`:
+     ```bash
+     pal cli subagent doctor <name>
+     ```
+
+Either path: if only some agents are installed, `pal cli subagent link` writes only to
+those — re-run it after installing another agent to propagate the subagent there.
+
+## Output format
+
+After installing, return:
+- The path of the created definition (`~/.pal/agents/<name>.md`).
+- The agents it was installed into (from the `pal cli subagent link` output).
+- The doctor's final result (errors resolved).
+- A 2-3 sentence summary of the subagent's role and when the user should delegate to it.
+
+## When to use / Do NOT use
+
+- **Use** when the user wants a reusable, specialized *agent* they delegate work to,
+  shared across their installed agents.
+- **Do NOT use** for a personal *skill* — a workflow the current agent runs itself.
+  That is `create-skill`. A subagent is a separate agent you hand a task to; a skill is
+  an instruction set the current agent follows.

package/assets/skills/create-subagent/authoring-guide.md

@@ -0,0 +1,87 @@
+# Subagent authoring guide
+
+The canonical rules for authoring a personal PAL subagent. Both the `create-subagent`
+dispatcher and the delegated `subagent-author` subagent follow this file, so it is the
+single source of truth for subagent quality and the exact frontmatter schema.
+
+## What a subagent is
+
+A subagent is a **separate agent you delegate a scoped task to** — a reviewer, a
+researcher, a refactorer. It has its own system prompt, its own tool access, and
+optionally its own model. It is not a skill (a workflow the current agent runs). If the
+user wants "a thing the assistant does," that is `create-skill`; if they want "another
+agent I can hand work to," that is this.
+
+## One definition, every agent
+
+A personal subagent is stored once as `~/.pal/agents/<name>.md` with **merged
+multi-platform frontmatter**. On `pal cli subagent link <name>`, PAL splits it per
+platform and writes a native file into each installed agent's agents directory. Global
+fields (`name`, `description`) always ship; each platform block is un-indented into that
+agent's frontmatter and the other blocks are stripped.
+
+```markdown
+---
+name: <slug>                    # lowercase-kebab; MUST equal the file stem
+description: "<what it does + WHEN to delegate to it>"
+claude:
+  tools: Read, Grep, Bash       # comma list; omit to inherit all tools
+  model: fable                  # a model alias/id, or `inherit`
+  skills:                       # OPTIONAL, Claude only — PRELOADS these skills
+    - some-skill
+opencode:
+  mode: subagent                # required so opencode treats it as a delegate
+  model: inherit
+  permission:                   # per-capability: allow | ask | deny
+    read: allow
+    write: allow
+    edit: allow
+    bash: allow
+cursor:
+  model: inherit
+  readonly: false
+  is_background: false
+copilot:
+  model: inherit
+  tools: read, edit             # comma list
+---
+
+<system prompt — second-person instructions to the subagent>
+```
+
+Only include the platform blocks that matter. A block you omit means that agent installs
+with just `name` + `description` (a valid, minimal subagent).
+
+## Per-platform field rules (verified, do not guess)
+
+- **model** — `inherit` uses the caller's model. A flagship alias (`fable`, etc.) or a
+  full model id pins it. Unknown values are a doctor warning, not an error, because model
+  names drift.
+- **tools** (Claude, Copilot) — a comma-separated allow-list. Omit to inherit all tools;
+  do not write an empty `tools:`.
+- **opencode** — set `mode: subagent`. Access is a `permission:` map (`read`, `write`,
+  `edit`, `bash`, …) with values `allow` / `ask` / `deny`. opencode has **no** `tools`
+  allow-list field.
+- **skills** — **Claude Code only**, and it *preloads* skills into the subagent's context;
+  it does not restrict them. opencode, Cursor, and Copilot have **no** `skills` frontmatter
+  field — emitting one there is ignored. If a subagent should lean on specific skills on
+  those agents, name them in the system prompt body instead.
+- **cursor** — `readonly` and `is_background` are booleans (`true`/`false`).
+
+## What makes a good subagent
+
+1. **Pointed at the subagent, not the user.** The body is the subagent's system prompt —
+   second-person instructions to *it* ("You review…", "Return…"). Not a tutorial.
+2. **One job.** A subagent has a single role. "Reviews security AND writes migrations" is
+   two subagents.
+3. **A trigger in the description.** State *when to delegate* to it, in third person, with
+   the terms a model would match on — the parent agent uses this to decide to hand off.
+4. **Least privilege.** Grant only the tools/permissions the role needs. A read-only
+   reviewer should not have write/bash.
+
+## Hand-checks the doctor can't judge
+
+- **Trigger clarity** — could the parent agent fail to delegate from the description alone?
+- **Role discipline** — one job, one subagent.
+- **Prompt concreteness** — the body tells the subagent exactly what to do and what to return.
+- **Privilege fit** — tools/permissions match the role, nothing broader.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -18,6 +18,8 @@
  *   usage                             Summarize token usage and cost
  *   skill link <name>                 Link a personal ~/.pal/skills/<name>/ into installed agents
  *   skill doctor <name>               Evaluate a skill against the authoring best practices
+ *   subagent link <name>             Install a personal ~/.pal/agents/<name>.md into installed agents
+ *   subagent doctor <name>           Evaluate a subagent against the authoring best practices
  *   debug [on|off]                    Enable / disable verbose hook debug logging
  */
 
@@ -208,6 +210,12 @@ async function runCli(command: string | undefined, args: string[]) {
       if (code !== 0) process.exit(code);
       break;
     }
+    case "subagent": {
+      const { runSubagent } = await import("./subagent");
+      const code = await runSubagent(args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
     case "skill": {
       const { runSkill } = await import("./skill");
       const code = await runSkill(args);
@@ -263,6 +271,10 @@ function showHelp() {
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
     pal cli skill doctor <name>             Evaluate a skill against the authoring best practices
     pal cli skill author-model              Print the flagship model that authors skills for the active agent
+    pal cli subagent link <name>            Install a personal ~/.pal/agents/<name>.md into installed agents
+    pal cli subagent doctor <name>          Evaluate a subagent against the authoring best practices
+    pal cli subagent list                   List the user-authored subagents in ~/.pal/agents/
+    pal cli subagent author-model           Print the flagship model that authors subagents for the active agent
     pal cli debug [on|off]                  Enable/disable verbose hook debug logging (persisted)
 
   Environment:

package/src/cli/subagent.ts

@@ -0,0 +1,75 @@
+/**
+ * pal cli subagent — manage personal subagents under ~/.pal/agents/.
+ *
+ *   pal cli subagent link <name>     Install ~/.pal/agents/<name>.md into every
+ *                                    installed agent (split per platform).
+ *   pal cli subagent doctor <name>   Evaluate ~/.pal/agents/<name>.md against the
+ *                                    subagent-authoring best practices.
+ *   pal cli subagent list            List the user-authored subagents.
+ *   pal cli subagent author-model    Print the flagship model configured to author
+ *                                    subagents for the active agent (empty if none).
+ */
+
+import { getActiveAgent } from "../hooks/lib/agent";
+import { flagshipAuthorModel } from "../hooks/lib/models";
+import { installPersonalSubagent, listPersonalSubagents, log } from "../targets/lib";
+import {
+  formatSubagentReport,
+  lintSubagent,
+  resolveSubagentFile,
+} from "../tools/subagent-doctor";
+
+export async function runSubagent(args: string[]): Promise<number> {
+  const [sub, name] = args;
+
+  if (sub === "author-model") {
+    const model = flagshipAuthorModel(getActiveAgent());
+    if (model) console.log(model);
+    return 0;
+  }
+
+  if (sub === "list") {
+    const names = listPersonalSubagents();
+    if (names.length === 0) {
+      log.info("No personal subagents in ~/.pal/agents/");
+    } else {
+      for (const n of names) console.log(n);
+    }
+    return 0;
+  }
+
+  if (sub === "doctor") {
+    if (!name) {
+      log.error("Usage: pal cli subagent doctor <name>");
+      return 1;
+    }
+    const report = lintSubagent(resolveSubagentFile(name));
+    console.log(formatSubagentReport(report));
+    return report.errors > 0 ? 1 : 0;
+  }
+
+  if (sub === "link") {
+    if (!name) {
+      log.error("Usage: pal cli subagent link <name>");
+      return 1;
+    }
+    try {
+      const installed = installPersonalSubagent(name);
+      if (installed.length === 0) {
+        log.warn(
+          `'${name}' installed into no agents (none installed yet). ` +
+            "Run 'pal cli install' first, then re-link."
+        );
+      } else {
+        log.success(`Installed '${name}' into: ${installed.join(", ")}`);
+      }
+      return 0;
+    } catch (e) {
+      log.error(e instanceof Error ? e.message : String(e));
+      return 1;
+    }
+  }
+
+  log.error("Usage: pal cli subagent <link|doctor|list|author-model> [name]");
+  return 1;
+}

package/src/hooks/handlers/persist-last-exchange.ts

@@ -7,9 +7,11 @@
  *  2. last-handoff.json keyed by cwd
  *     → read by loadHandoff() to surface "Pick Up Where You Left Off"
  *
- * Always overwrites — Stop is the source of truth for both. The LEARN-phase
- * handoff-note.ts tool may also write to last-handoff.json; whichever runs last wins,
- * but raw exchange is sufficient for continuity and costs nothing.
+ * last-exchange is always overwritten — Stop is its source of truth. last-handoff
+ * is NOT: a deliberate LEARN-phase note (written by handoff-note.ts with
+ * source:"deliberate") outranks this raw auto-snapshot, so we leave it intact
+ * while it is still fresh and in-progress. Otherwise the auto-snapshot would
+ * clobber the curated handoff the moment the session stopped (ISC-39).
  */
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
@@ -21,6 +23,18 @@ import { detectStatus } from "../lib/work-tracking";
 
 type ParsedMessage = { role: string; content: unknown };
 
+/** Matches loadHandoff()'s staleness window in hooks/lib/context.ts. */
+const HANDOFF_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** A fresh, in-progress deliberate note must not be overwritten by the auto-snapshot. */
+function isProtectedHandoff(entry: unknown): boolean {
+  if (!entry || typeof entry !== "object") return false;
+  const e = entry as { source?: string; status?: string; timestamp?: string };
+  if (e.source !== "deliberate" || e.status !== "in-progress" || !e.timestamp)
+    return false;
+  return Date.now() - new Date(e.timestamp).getTime() <= HANDOFF_STALE_MS;
+}
+
 export function persistLastExchange(
   messages: ParsedMessage[],
   sessionId: string,
@@ -45,26 +59,30 @@ export function persistLastExchange(
     writeFileSync(resolve(stateDir, `${sessionId}.json`), json, "utf-8");
     writeFileSync(resolve(stateDir, "latest.json"), json, "utf-8");
 
-    // 2. Write last-handoff.json for "Pick Up Where You Left Off"
+    // 2. Write last-handoff.json for "Pick Up Where You Left Off" — unless a
+    //    fresh deliberate note already owns this cwd (ISC-39).
     const handoffPath = resolve(paths.state(), "last-handoff.json");
     const existing: Record<string, unknown> = existsSync(handoffPath)
       ? JSON.parse(readFileSync(handoffPath, "utf-8"))
       : {};
-    const title = (lastUser.slice(0, 80).replace(/\n/g, " ") || "Session").trim();
-    const handoff = [
-      lastUser ? `Last user message:\n${lastUser.slice(0, 500)}` : "",
-      lastAssistant ? `\nLast assistant response:\n${lastAssistant.slice(0, 500)}` : "",
-    ]
-      .filter(Boolean)
-      .join("");
-    existing[cwd] = {
-      timestamp: new Date().toISOString(),
-      title,
-      status: detectStatus(lastAssistant),
-      handoff,
-      artifacts: [],
-    };
-    writeFileSync(handoffPath, JSON.stringify(existing, null, 2), "utf-8");
+    if (!isProtectedHandoff(existing[cwd])) {
+      const title = (lastUser.slice(0, 80).replace(/\n/g, " ") || "Session").trim();
+      const handoff = [
+        lastUser ? `Last user message:\n${lastUser.slice(0, 500)}` : "",
+        lastAssistant ? `\nLast assistant response:\n${lastAssistant.slice(0, 500)}` : "",
+      ]
+        .filter(Boolean)
+        .join("");
+      existing[cwd] = {
+        timestamp: new Date().toISOString(),
+        title,
+        status: detectStatus(lastAssistant),
+        handoff,
+        artifacts: [],
+        source: "auto",
+      };
+      writeFileSync(handoffPath, JSON.stringify(existing, null, 2), "utf-8");
+    }
 
     logDebug(
       "persist-last-exchange",

package/src/hooks/lib/export.ts

@@ -8,8 +8,13 @@ import { relative, resolve } from "node:path";
 import AdmZip from "adm-zip";
 import { palHome } from "./paths";
 
-/** Directories within PAL_HOME that contain user state worth exporting. */
-const EXPORT_DIRS = ["telos", "memory"];
+/**
+ * Directories within PAL_HOME that contain user state worth exporting.
+ * `skills` and `agents` hold user-authored personal skills and subagents.
+ * Shipped skills live in `skills/` only as symlinks back to the repo, and
+ * walkDir skips symlinks (see below) — so only real, user-owned files travel.
+ */
+const EXPORT_DIRS = ["telos", "memory", "skills", "agents"];
 
 /** Subdirectories/files to skip during export. */
 const SKIP_PATTERNS = ["memory/downloads"];
@@ -30,6 +35,9 @@ function walkDir(dir: string, root: string): string[] {
 
     if (shouldSkip(relPath)) continue;
 
+    // Symlinks report neither isDirectory nor isFile, so they are skipped —
+    // this is what keeps shipped-skill symlinks (skills/<name> → repo) out of
+    // the export. Do not switch to stat()-based following.
     if (entry.isDirectory()) {
       files.push(...walkDir(fullPath, root));
     } else if (entry.isFile()) {

package/src/targets/lib.ts

@@ -927,7 +927,7 @@ function extractAgentForPlatform(content: string, platform: AgentPlatform): stri
   for (const line of frontmatter.split("\n")) {
     if (!line.trim()) continue;
 
-    const platformMatch = new RegExp(/^(claude|opencode|cursor):\s*$/).exec(line);
+    const platformMatch = new RegExp(/^(claude|opencode|cursor|copilot):\s*$/).exec(line);
     if (platformMatch) {
       currentPlatform = platformMatch[1] as AgentPlatform;
       continue;
@@ -1013,6 +1013,79 @@ export function removeAgentsFromCopilot(copilotAgentsDir: string): string[] {
   return uninstallAgents(copilotAgentsDir, "copilot");
 }
 
+// --- Personal subagents (user-authored, under ~/.pal/agents/) ---
+
+/**
+ * Store for user-authored subagents: ~/.pal/agents/<name>.md — one merged
+ * multi-platform frontmatter file per subagent (same schema as assets/agents/).
+ */
+const PAL_AGENTS_STORE = resolve(palHome(), "agents");
+
+/**
+ * Each installed agent and the native agents directory a personal subagent is
+ * written into. An agent counts as installed when its agents directory already
+ * exists (mirrors linkPersonalSkill's per-agent gate).
+ */
+function personalSubagentTargets(): { agent: AgentPlatform; dir: string }[] {
+  return [
+    { agent: "claude", dir: resolve(platform.claudeDir(), "agents") },
+    { agent: "opencode", dir: resolve(platform.opencodeDir(), "agents") },
+    { agent: "cursor", dir: resolve(platform.cursorDir(), "agents") },
+    { agent: "copilot", dir: resolve(platform.copilotDir(), "agents") },
+  ];
+}
+
+/** Names of the subagents PAL ships (assets/agents/*.md). */
+function shippedAgentNames(): Set<string> {
+  const dir = assets.agents();
+  if (!existsSync(dir)) return new Set();
+  return new Set(
+    readdirSync(dir)
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => f.replace(/\.md$/, ""))
+  );
+}
+
+/** List the user-authored subagents in ~/.pal/agents/. */
+export function listPersonalSubagents(): string[] {
+  if (!existsSync(PAL_AGENTS_STORE)) return [];
+  return readdirSync(PAL_AGENTS_STORE)
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => f.replace(/\.md$/, ""))
+    .sort();
+}
+
+/**
+ * Install a personal subagent (~/.pal/agents/<name>.md) into every installed
+ * agent by splitting its merged frontmatter per platform and writing the
+ * result into that agent's native agents dir. Unlike personal skills (which are
+ * symlinked), subagents are transformed-and-copied because each platform needs
+ * its own frontmatter shape. Returns the agents it was installed into.
+ */
+export function installPersonalSubagent(name: string): string[] {
+  const src = resolve(PAL_AGENTS_STORE, `${name}.md`);
+  if (!existsSync(src)) {
+    throw new Error(`No subagent found at ${src}`);
+  }
+  if (shippedAgentNames().has(name)) {
+    throw new Error(
+      `'${name}' is a shipped PAL subagent — choose another name (a reinstall would overwrite it).`
+    );
+  }
+  const content = readFileSync(src, "utf-8");
+  const installed: string[] = [];
+  for (const { agent, dir } of personalSubagentTargets()) {
+    if (!existsSync(dir)) continue; // agent not installed
+    writeFileSync(
+      resolve(dir, `${name}.md`),
+      extractAgentForPlatform(content, agent),
+      "utf-8"
+    );
+    installed.push(agent);
+  }
+  return installed;
+}
+
 /** Load and resolve the Copilot hooks template, substituting PKG_ROOT */
 export function loadCopilotHooksTemplate(templatePath: string, pkgRoot: string): unknown {
   const resolved = readFileSync(templatePath, "utf-8").replaceAll(

package/src/tools/agent/handoff-note.ts

@@ -21,6 +21,7 @@ interface HandoffEntry {
   status: "in-progress" | "completed";
   handoff: string;
   artifacts: string[];
+  source: "deliberate" | "auto";
 }
 
 function handoffPath(): string {
@@ -56,6 +57,7 @@ function writeHandoffNote(
     status: done ? "completed" : "in-progress",
     handoff: text,
     artifacts: [],
+    source: "deliberate",
   };
   writeHandoffs(handoffs);
   return {

package/src/tools/subagent-doctor.ts

@@ -0,0 +1,414 @@
+/**
+ * subagent-doctor — static evaluator for a personal subagent definition
+ * (~/.pal/agents/<name>.md) with merged multi-platform frontmatter. Checks only
+ * what is mechanically verifiable: name/description constraints, per-platform
+ * blocks (claude/opencode/cursor/copilot), model/tools/permission shape, body
+ * length, and absolute-path portability.
+ *
+ * Library:  import { lintSubagent, formatSubagentReport } from ".../subagent-doctor"
+ * Script:   bun src/tools/subagent-doctor.ts <file-or-name>
+ *           (resolves a path, or a name under ~/.pal/agents/)
+ * CLI:      pal cli subagent doctor <name>   (see src/cli/subagent.ts)
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { assets, palHome } from "../hooks/lib/paths";
+
+type Level = "pass" | "warn" | "error";
+
+interface DoctorFinding {
+  level: Level;
+  check: string;
+  message: string;
+}
+
+export interface SubagentReport {
+  file: string;
+  name: string | null;
+  findings: DoctorFinding[];
+  errors: number;
+  warnings: number;
+}
+
+const AGENT_PLATFORMS = ["claude", "opencode", "cursor", "copilot"] as const;
+type AgentPlatform = (typeof AGENT_PLATFORMS)[number];
+
+interface ParsedSubagent {
+  hasFrontmatter: boolean;
+  name: string | null;
+  description: string | null;
+  descriptionQuoted: boolean;
+  global: string[];
+  platforms: Partial<Record<AgentPlatform, string[]>>;
+  body: string;
+}
+
+const RESERVED_WORDS = ["anthropic", "claude"];
+const MAX_NAME = 64;
+const MAX_DESCRIPTION = 1024;
+const MAX_BODY_LINES = 500;
+
+/** Model values PAL recognises across agents; anything else warns (naming drifts). */
+const KNOWN_MODELS = ["inherit", "fable", "sonnet", "opus", "haiku"];
+const PERMISSION_VALUES = ["allow", "ask", "deny"];
+const OPENCODE_MODES = ["subagent", "primary", "all"];
+
+/** Machine/user-specific absolute paths that will not survive an export. */
+const ABSOLUTE_PATH_RE =
+  /(?:\/(?:Users|home)\/[A-Za-z0-9._-]+|\/root\/[A-Za-z0-9._-]|[A-Za-z]:\\Users\\[A-Za-z0-9._-]+)/;
+
+/** Names of the subagents PAL ships — a personal subagent may not reuse one. */
+function shippedAgentNames(): Set<string> {
+  const dir = assets.agents();
+  if (!existsSync(dir)) return new Set();
+  return new Set(
+    readdirSync(dir)
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => f.replace(/\.md$/, ""))
+  );
+}
+
+/** Split a merged subagent .md into global fields, per-platform blocks, and body. */
+function parseSubagent(content: string): ParsedSubagent {
+  const parts = content.split(/^---\s*$/m);
+  if (parts.length < 3) {
+    return {
+      hasFrontmatter: false,
+      name: null,
+      description: null,
+      descriptionQuoted: false,
+      global: [],
+      platforms: {},
+      body: content,
+    };
+  }
+  const frontmatter = parts[1];
+  const body = parts.slice(2).join("---");
+
+  const global: string[] = [];
+  const platforms: Partial<Record<AgentPlatform, string[]>> = {};
+  let current: AgentPlatform | null = null;
+
+  for (const line of frontmatter.split("\n")) {
+    if (!line.trim()) continue;
+    const pm = /^(claude|opencode|cursor|copilot):\s*$/.exec(line);
+    if (pm) {
+      current = pm[1] as AgentPlatform;
+      platforms[current] ??= [];
+      continue;
+    }
+    if (current) {
+      if (/^ {2}/.test(line)) {
+        platforms[current]?.push(line.slice(2));
+        continue;
+      }
+      current = null;
+    }
+    global.push(line);
+  }
+
+  const globalText = global.join("\n");
+  const name = /^name:\s*"?(.+?)"?\s*$/m.exec(globalText)?.[1] ?? null;
+  const rawDesc = /^description:[ \t]*(.*?)\s*$/m.exec(globalText)?.[1] ?? null;
+  const descriptionQuoted =
+    rawDesc !== null &&
+    rawDesc.length >= 2 &&
+    rawDesc.startsWith('"') &&
+    rawDesc.endsWith('"');
+  const description = descriptionQuoted ? rawDesc.slice(1, -1) : rawDesc;
+
+  return {
+    hasFrontmatter: true,
+    name,
+    description,
+    descriptionQuoted,
+    global,
+    platforms,
+    body,
+  };
+}
+
+/** Value of a single-line `key: value` field within an un-indented block. */
+function fieldValue(lines: string[], key: string): string | null {
+  const re = new RegExp(String.raw`^${key}:[ \t]*(.*?)\s*$`);
+  for (const line of lines) {
+    const m = re.exec(line);
+    if (m) return m[1].replace(/^"(.*)"$/, "$1");
+  }
+  return null;
+}
+
+/** True when a block declares `key:` (with or without an inline value). */
+function hasField(lines: string[], key: string): boolean {
+  return lines.some((l) => new RegExp(`^${key}:`).test(l));
+}
+
+function checkClaudeBlock(lines: string[], add: AddFinding): void {
+  const model = fieldValue(lines, "model");
+  if (model) validateModel(model, "claude", add);
+  const tools = fieldValue(lines, "tools");
+  if (tools !== null && tools.trim() === "") {
+    add("warn", "claude.tools", "`tools` is empty — omit it to inherit all tools");
+  }
+}
+
+function checkOpencodeBlock(lines: string[], add: AddFinding): void {
+  const mode = fieldValue(lines, "mode");
+  if (!mode) {
+    add(
+      "warn",
+      "opencode.mode",
+      "no `mode` — set `mode: subagent` so opencode treats it as a delegate"
+    );
+  } else if (!OPENCODE_MODES.includes(mode)) {
+    add(
+      "warn",
+      "opencode.mode",
+      `mode "${mode}" — expected one of ${OPENCODE_MODES.join(", ")}`
+    );
+  } else if (mode !== "subagent") {
+    add("warn", "opencode.mode", `mode is "${mode}", not "subagent" — intended?`);
+  }
+  const model = fieldValue(lines, "model");
+  if (model) validateModel(model, "opencode", add);
+  for (const line of lines) {
+    const perm = /^\s*(read|write|edit|bash|webfetch|skill):\s*"?([a-z-]+)"?\s*$/.exec(
+      line
+    );
+    if (perm && !PERMISSION_VALUES.includes(perm[2])) {
+      add(
+        "warn",
+        "opencode.permission",
+        `${perm[1]}: "${perm[2]}" — expected ${PERMISSION_VALUES.join("/")}`
+      );
+    }
+  }
+}
+
+function checkCursorBlock(lines: string[], add: AddFinding): void {
+  const model = fieldValue(lines, "model");
+  if (model) validateModel(model, "cursor", add);
+  for (const key of ["readonly", "is_background"]) {
+    const v = fieldValue(lines, key);
+    if (v !== null && v !== "true" && v !== "false") {
+      add("warn", `cursor.${key}`, `${key}: "${v}" — must be true or false`);
+    }
+  }
+}
+
+function checkCopilotBlock(lines: string[], add: AddFinding): void {
+  const model = fieldValue(lines, "model");
+  if (model) validateModel(model, "copilot", add);
+}
+
+function validateModel(model: string, platform: string, add: AddFinding): void {
+  const known = KNOWN_MODELS.includes(model) || /^(claude-|gpt-|o\d|gemini-)/.test(model);
+  if (!known) {
+    add(
+      "warn",
+      `${platform}.model`,
+      `model "${model}" is unrecognised — confirm it is a valid ${platform} model id/alias`
+    );
+  }
+}
+
+type AddFinding = (level: Level, check: string, message: string) => void;
+
+/**
+ * Evaluate the subagent file at `file` (a merged multi-platform .md) and return
+ * a structured report. Loader-fatal problems surface as errors; best-practice
+ * nudges surface as warnings.
+ */
+export function lintSubagent(file: string): SubagentReport {
+  const findings: DoctorFinding[] = [];
+  const add: AddFinding = (level, check, message) =>
+    findings.push({ level, check, message });
+
+  if (!existsSync(file)) {
+    add("error", "structure", `No subagent file at ${file}`);
+    return { file, name: null, findings, errors: 1, warnings: 0 };
+  }
+
+  const parsed = parseSubagent(readFileSync(file, "utf-8"));
+  if (!parsed.hasFrontmatter) {
+    add("error", "structure", "No frontmatter (--- … ---) block found");
+    return { file, name: null, findings, errors: 1, warnings: 0 };
+  }
+
+  const { name, description, descriptionQuoted, platforms, body } = parsed;
+
+  // ── name ──
+  const stem = basename(file).replace(/\.md$/, "");
+  if (!name) {
+    add("error", "name", "Missing `name` in frontmatter");
+  } else {
+    name === stem
+      ? add("pass", "name.file", `matches file name "${stem}"`)
+      : add(
+          "error",
+          "name.file",
+          `name "${name}" must equal the file name "${stem}" verbatim — otherwise the subagent is silently ignored`
+        );
+    name.length <= MAX_NAME
+      ? add("pass", "name.length", `${name.length}/${MAX_NAME} chars`)
+      : add("error", "name.length", `${name.length} chars exceeds ${MAX_NAME}`);
+    /^[a-z0-9-]+$/.test(name)
+      ? add("pass", "name.charset", "lowercase letters, numbers, hyphens only")
+      : add(
+          "error",
+          "name.charset",
+          `"${name}" must be lowercase a-z, 0-9, hyphens only`
+        );
+    const reserved = RESERVED_WORDS.find((w) => name.toLowerCase().includes(w));
+    reserved
+      ? add("error", "name.reserved", `contains reserved word "${reserved}"`)
+      : add("pass", "name.reserved", "no reserved words");
+    shippedAgentNames().has(name)
+      ? add(
+          "error",
+          "name.collision",
+          `"${name}" is a shipped PAL subagent — a reinstall would overwrite it; choose another name`
+        )
+      : add("pass", "name.collision", "does not collide with a shipped subagent");
+  }
+
+  // ── description ──
+  if (!description) {
+    add("error", "description", "Missing `description` in frontmatter");
+  } else {
+    description.length <= MAX_DESCRIPTION
+      ? add(
+          "pass",
+          "description.length",
+          `${description.length}/${MAX_DESCRIPTION} chars`
+        )
+      : add(
+          "error",
+          "description.length",
+          `${description.length} chars exceeds ${MAX_DESCRIPTION}`
+        );
+    descriptionQuoted
+      ? add("pass", "description.quoted", "value is wrapped in double quotes")
+      : add(
+          "warn",
+          "description.quoted",
+          'value is not wrapped in double quotes — unquoted YAML mis-parses on colons and commas; wrap it in "..."'
+        );
+    /<[^>]+>/.test(description)
+      ? add(
+          "warn",
+          "description.xml",
+          "contains angle-bracket content — rephrase placeholders in prose"
+        )
+      : add("pass", "description.xml", "no XML tags");
+    /\bwhen\b/i.test(description)
+      ? add("pass", "description.trigger", "states when to delegate to the subagent")
+      : add(
+          "warn",
+          "description.trigger",
+          "no 'when to use' trigger — add 'Use when …' so the model knows when to delegate"
+        );
+  }
+
+  // ── platform blocks ──
+  const present = AGENT_PLATFORMS.filter((p) => (platforms[p]?.length ?? 0) > 0);
+  present.length > 0
+    ? add("pass", "platforms", `defines block(s): ${present.join(", ")}`)
+    : add(
+        "warn",
+        "platforms",
+        "no platform block — the subagent installs with only name/description; add a claude:/opencode:/cursor:/copilot: block to set model, tools, mode"
+      );
+
+  if (platforms.claude) checkClaudeBlock(platforms.claude, add);
+  if (platforms.opencode) checkOpencodeBlock(platforms.opencode, add);
+  if (platforms.cursor) checkCursorBlock(platforms.cursor, add);
+  if (platforms.copilot) checkCopilotBlock(platforms.copilot, add);
+
+  // ── skills field: Claude preloads it; the others have no such field ──
+  for (const p of ["opencode", "cursor", "copilot"] as const) {
+    if (platforms[p] && hasField(platforms[p] ?? [], "skills")) {
+      add(
+        "warn",
+        `${p}.skills`,
+        `${p} has no native \`skills\` frontmatter field — it will be ignored; record intended skills in the body instead`
+      );
+    }
+  }
+
+  // ── body ──
+  const bodyLines = body.split("\n").length;
+  bodyLines <= MAX_BODY_LINES
+    ? add("pass", "body.length", `${bodyLines}/${MAX_BODY_LINES} lines`)
+    : add(
+        "warn",
+        "body.length",
+        `${bodyLines} lines exceeds ${MAX_BODY_LINES} — trim the system prompt`
+      );
+  body.trim().length > 0
+    ? add("pass", "body.present", "has a system prompt")
+    : add(
+        "error",
+        "body.present",
+        "empty body — a subagent needs a system prompt after the frontmatter"
+      );
+
+  // ── absolute-path portability ──
+  const hits: string[] = [];
+  const allLines = readFileSync(file, "utf-8").split("\n");
+  for (let i = 0; i < allLines.length; i++) {
+    const m = ABSOLUTE_PATH_RE.exec(allLines[i]);
+    if (m) hits.push(`${i + 1} → ${m[0]}`);
+  }
+  const more = hits.length > 3 ? ` (+${hits.length - 3} more)` : "";
+  hits.length > 0
+    ? add(
+        "warn",
+        "paths.absolute",
+        `hardcoded machine-specific path(s): ${hits.slice(0, 3).join("; ")}${more} — prefer $HOME/~ or an env var`
+      )
+    : add("pass", "paths.absolute", "no machine-specific absolute paths");
+
+  const errors = findings.filter((f) => f.level === "error").length;
+  const warnings = findings.filter((f) => f.level === "warn").length;
+  return { file, name, findings, errors, warnings };
+}
+
+/** Render a subagent report as a human-readable string. */
+export function formatSubagentReport(r: SubagentReport): string {
+  const icon = { pass: "✓", warn: "⚠", error: "✗" } as const;
+  const lines = [`subagent-doctor: ${r.name ?? "(unparsed)"}  —  ${r.file}`];
+  for (const f of r.findings) {
+    lines.push(`  ${icon[f.level]} ${f.check}: ${f.message}`);
+  }
+  let verdict: string;
+  if (r.errors > 0) {
+    verdict = `FAIL — ${r.errors} error(s), ${r.warnings} warning(s)`;
+  } else if (r.warnings > 0) {
+    verdict = `OK with ${r.warnings} warning(s)`;
+  } else {
+    verdict = "PASS — all checks clean";
+  }
+  lines.push(`  ${verdict}`);
+  return lines.join("\n");
+}
+
+/** Resolve a doctor argument to a subagent .md path (a path, or a name in the store). */
+export function resolveSubagentFile(arg: string): string {
+  if (arg.endsWith(".md") && existsSync(resolve(arg))) return resolve(arg);
+  const direct = resolve(arg);
+  if (existsSync(direct) && direct.endsWith(".md")) return direct;
+  return resolve(palHome(), "agents", arg.endsWith(".md") ? arg : `${arg}.md`);
+}
+
+if (import.meta.main) {
+  const arg = process.argv[2];
+  if (!arg) {
+    console.error("Usage: bun src/tools/subagent-doctor.ts <file-or-name>");
+    process.exit(2);
+  }
+  const report = lintSubagent(resolveSubagentFile(arg));
+  console.log(formatSubagentReport(report));
+  process.exit(report.errors > 0 ? 1 : 0);
+}