@app-vitals/agent-runtime 0.16.0 → 0.16.2

package/default-specialty.shipped.integration.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Platform-only boot against the REAL shipped agent-types/ directory with an
+ * empty environment (PCD-3.1). Env is passed explicitly: the test preload
+ * presets fixture env vars on process.env, so nothing here reads it.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { SpecialtyRegistry } from "@app-vitals/agent-admin/specialty-manifest-loader";
+import {
+  resolveDefaultSpecialtyName,
+  resolveSpecialtiesDir,
+  SHIPPED_AGENT_TYPES_DIR,
+} from "@app-vitals/agent-lib/default-specialty";
+import { resolveTemplatesDir } from "./setup.ts";
+
+const EMPTY_ENV: Record<string, string | undefined> = {};
+
+describe("platform-only boot with empty env", () => {
+  it("SpecialtyRegistry resolves the default specialist type from the shipped agent-types/ without warning", () => {
+    const warnings: string[] = [];
+    const registry = new SpecialtyRegistry({
+      typesDir: resolveSpecialtiesDir(EMPTY_ENV),
+      defaultTypeName: resolveDefaultSpecialtyName(EMPTY_ENV),
+      warn: (m) => warnings.push(m),
+    });
+    const manifest = registry.getManifest(
+      resolveDefaultSpecialtyName(EMPTY_ENV),
+    );
+    expect(manifest.metadata.name).toBe("specialist");
+    expect(warnings).toEqual([]);
+    expect(registry.listTypes().map((t) => t.name)).toContain("specialist");
+  });
+
+  it("an unknown type warns and resolves to the shipped specialist manifest", () => {
+    const warnings: string[] = [];
+    const registry = new SpecialtyRegistry({
+      typesDir: SHIPPED_AGENT_TYPES_DIR,
+      defaultTypeName: "specialist",
+      warn: (m) => warnings.push(m),
+    });
+    expect(registry.getManifest("no-such-type").metadata.name).toBe(
+      "specialist",
+    );
+    expect(warnings).toHaveLength(1);
+  });
+
+  it("runtime resolveTemplatesDir agrees: the default type's shipped templates, no warning", () => {
+    const warnings: string[] = [];
+    const dir = resolveTemplatesDir(
+      undefined,
+      join(import.meta.dir, ".."),
+      (m) => warnings.push(m),
+      EMPTY_ENV,
+    );
+    expect(warnings).toEqual([]);
+    expect(dir).toBe(join(SHIPPED_AGENT_TYPES_DIR, "specialist", "templates"));
+    expect(existsSync(join(dir, "CLAUDE.md.template"))).toBe(true);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-runtime",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/app-vitals/agent.git",
@@ -40,8 +40,8 @@
     "./workspace-paths": "./workspace-paths.ts"
   },
   "dependencies": {
-    "@app-vitals/agent-admin": "0.16.0",
-    "@app-vitals/agent-lib": "0.16.0",
+    "@app-vitals/agent-admin": "0.16.2",
+    "@app-vitals/agent-lib": "0.16.2",
     "@octokit/auth-app": "^8.2.0",
     "@sentry/bun": "^10.63.0",
     "@slack/bolt": "^5.0.0",

package/setup.fixture.integration.test.ts

@@ -91,6 +91,48 @@ describe("fixture specialty templates", () => {
   });
 });
 
+describe("coding is not special-cased (PCD-2.2)", () => {
+  const writeCodingManifest = (templatesDir: string) => {
+    const specialties = join(root, "specialties");
+    mkdirSync(join(specialties, "coding"), { recursive: true });
+    writeFileSync(
+      join(specialties, "coding", "manifest.yaml"),
+      `identity:\n  templatesDir: ${templatesDir}\n`,
+    );
+    return specialties;
+  };
+
+  it("resolves coding through its manifest identity.templatesDir", () => {
+    const tpl = join(root, "coding-tpl");
+    mkdirSync(tpl, { recursive: true });
+    for (const f of [
+      "CLAUDE.md.template",
+      "SOUL.md.template",
+      "IDENTITY.md.template",
+    ])
+      writeFileSync(join(tpl, f), "x");
+    const warnings: string[] = [];
+    const dir = resolveTemplatesDir("coding", root, (m) => warnings.push(m), {
+      SHIPWRIGHT_SPECIALTIES_DIR: writeCodingManifest(tpl),
+    });
+    expect(dir).toBe(tpl);
+    expect(warnings).toEqual([]);
+  });
+
+  it("falls back to the built-in dir with a warning when coding is unresolvable", () => {
+    const warnings: string[] = [];
+    const dir = resolveTemplatesDir("coding", root, (m) => warnings.push(m), {
+      SHIPWRIGHT_SPECIALTIES_DIR: join(root, "no-specialties"),
+    });
+    expect(dir).toMatch(/workspace$/);
+    // Unknown "coding" warns and tries the default type, which is also absent
+    // here, so a second warning precedes the built-in fallback.
+    expect(warnings).toHaveLength(2);
+    expect(warnings[0]).toContain('"coding"');
+    expect(warnings[1]).toContain("built-in");
+  });
+});
+
 describe("no default specialty configured", () => {
   it("names the env vars when the default specialty's templates cannot be found", () => {
     const emptyDir = join(root, "empty-templates");

package/setup.integration.test.ts

@@ -894,6 +894,19 @@ describe("findStalePluginSpecs", () => {
 // these tests depend on ambient sandbox/image state.
 const NO_EXTRA_MARKETPLACES: string[] = [];
 
+const SHIPWRIGHT_ROW: AgentPlugin = {
+  plugin: "shipwright",
+  marketplace: "shipwright",
+};
+
+// A repo root carrying a local marketplace (coding image); platform images ship none.
+const repoRoot = (): string => {
+  const root = join(testHome, "repo-root");
+  mkdirSync(join(root, ".claude-plugin"), { recursive: true });
+  writeFileSync(join(root, ".claude-plugin", "marketplace.json"), "{}");
+  return root;
+};
+
 describe("installPlugins", () => {
   it("registers local marketplace then installs shipwright@shipwright using the shipwright marketplace", async () => {
     const calls: Array<{ cmd: string; args: string[] }> = [];
@@ -909,20 +922,15 @@ describe("installPlugins", () => {
     await installPlugins(
       mockExec,
       testHome,
-      [],
-      "/repo/root",
+      [SHIPWRIGHT_ROW],
+      repoRoot(),
       join(testHome, "nonexistent.json"),
       NO_EXTRA_MARKETPLACES,
     );
 
     // marketplace add + 1 install + 1 update = 3 calls (no stale paths)
     expect(calls).toHaveLength(3);
-    expect(calls[0].args).toEqual([
-      "plugin",
-      "marketplace",
-      "add",
-      "/repo/root",
-    ]);
+    expect(calls[0].args).toEqual(["plugin", "marketplace", "add", repoRoot()]);
     expect(calls[1].args).toEqual([
       "plugin",
       "install",
@@ -935,7 +943,7 @@ describe("installPlugins", () => {
     ]);
   });
 
-  it("installs agent-specific plugins after default plugins", async () => {
+  it("installs row plugins in row order", async () => {
     const calls: Array<{ cmd: string; args: string[] }> = [];
     const mockExec = async (
       cmd: string,
@@ -947,6 +955,7 @@ describe("installPlugins", () => {
     };
 
     const agentPlugins: AgentPlugin[] = [
+      SHIPWRIGHT_ROW,
       { marketplace: "my-marketplace", plugin: "custom-plugin" },
       { marketplace: "other-market", plugin: "another-plugin" },
     ];
@@ -955,7 +964,7 @@ describe("installPlugins", () => {
       mockExec,
       testHome,
       agentPlugins,
-      "/repo/root",
+      repoRoot(),
       join(testHome, "nonexistent.json"),
       NO_EXTRA_MARKETPLACES,
     );
@@ -963,14 +972,9 @@ describe("installPlugins", () => {
     // 1 marketplace add + 3 installs + 3 updates = 7 calls
     expect(calls).toHaveLength(7);
 
-    expect(calls[0].args).toEqual([
-      "plugin",
-      "marketplace",
-      "add",
-      "/repo/root",
-    ]);
+    expect(calls[0].args).toEqual(["plugin", "marketplace", "add", repoRoot()]);
 
-    // installs: default first, then agent-specific
+    // installs in row order
     expect(calls[1].args).toEqual([
       "plugin",
       "install",
@@ -987,7 +991,7 @@ describe("installPlugins", () => {
       "another-plugin@other-market",
     ]);
 
-    // updates: default first, then agent-specific
+    // updates in row order
     expect(calls[4].args).toEqual([
       "plugin",
       "update",
@@ -1005,7 +1009,7 @@ describe("installPlugins", () => {
     ]);
   });
 
-  it("empty agentPlugins installs only default plugins", async () => {
+  it("no plugin rows installs nothing (platform agents)", async () => {
     const calls: Array<{ args: string[] }> = [];
     const mockExec = async (
       _cmd: string,
@@ -1020,15 +1024,12 @@ describe("installPlugins", () => {
       mockExec,
       testHome,
       [],
-      "/repo/root",
+      "/repo/root-without-marketplace",
       join(testHome, "nonexistent.json"),
       NO_EXTRA_MARKETPLACES,
     );
 
-    // marketplace add + 1 install + 1 update = 3 calls
-    expect(calls).toHaveLength(3);
-    expect(calls[1].args).toContain("shipwright@shipwright");
-    expect(calls[2].args).toContain("shipwright@shipwright");
+    expect(calls).toEqual([]);
   });
 
   it("is non-fatal when the claude binary isn't available", async () => {
@@ -1040,8 +1041,8 @@ describe("installPlugins", () => {
       installPlugins(
         throwingExec,
         testHome,
-        [],
-        "/repo/root",
+        [SHIPWRIGHT_ROW],
+        repoRoot(),
         join(testHome, "nonexistent.json"),
         NO_EXTRA_MARKETPLACES,
       ),
@@ -1067,8 +1068,8 @@ describe("installPlugins", () => {
       installPlugins(
         mockExec,
         testHome,
-        [],
-        "/repo/root",
+        [SHIPWRIGHT_ROW],
+        repoRoot(),
         join(testHome, "nonexistent.json"),
         NO_EXTRA_MARKETPLACES,
       ),
@@ -1097,8 +1098,8 @@ describe("installPlugins", () => {
       installPlugins(
         mockExec,
         testHome,
-        [],
-        "/repo/root",
+        [SHIPWRIGHT_ROW],
+        repoRoot(),
         join(testHome, "nonexistent.json"),
         NO_EXTRA_MARKETPLACES,
       ),
@@ -1123,8 +1124,8 @@ describe("installPlugins", () => {
       installPlugins(
         mockExec,
         testHome,
-        [],
-        "/repo/root",
+        [SHIPWRIGHT_ROW],
+        repoRoot(),
         join(testHome, "nonexistent.json"),
         NO_EXTRA_MARKETPLACES,
       ),
@@ -1163,8 +1164,8 @@ describe("installPlugins", () => {
     await installPlugins(
       mockExec,
       testHome,
-      [],
-      "/repo/root",
+      [SHIPWRIGHT_ROW],
+      repoRoot(),
       manifestPath,
       NO_EXTRA_MARKETPLACES,
     );
@@ -1224,20 +1225,15 @@ describe("installPlugins", () => {
     await installPlugins(
       mockExec,
       testHome,
-      [],
-      "/repo/root",
+      [SHIPWRIGHT_ROW],
+      repoRoot(),
       manifestPath,
       NO_EXTRA_MARKETPLACES,
     );
 
     // marketplace add + uninstall (failed) = 2 calls; install and update are skipped
     expect(calls).toHaveLength(2);
-    expect(calls[0].args).toEqual([
-      "plugin",
-      "marketplace",
-      "add",
-      "/repo/root",
-    ]);
+    expect(calls[0].args).toEqual(["plugin", "marketplace", "add", repoRoot()]);
     expect(calls[1].args).toEqual([
       "plugin",
       "uninstall",
@@ -1277,8 +1273,8 @@ describe("installPlugins", () => {
     await installPlugins(
       mockExec,
       testHome,
-      [],
-      "/repo/root",
+      [SHIPWRIGHT_ROW],
+      repoRoot(),
       manifestPath,
       NO_EXTRA_MARKETPLACES,
     );
@@ -1392,8 +1388,8 @@ describe("installPlugins — extra marketplace discovery", () => {
     await installPlugins(
       mockExec,
       testHome,
-      [],
-      "/repo/root",
+      [SHIPWRIGHT_ROW],
+      repoRoot(),
       join(testHome, "nonexistent.json"),
       undefined, // use default discovery — pass conventionRoot via extraMarketplacesRoot
       conventionRoot,
@@ -1403,7 +1399,7 @@ describe("installPlugins — extra marketplace discovery", () => {
     const addCalls = calls.filter((c) => c.args[1] === "marketplace");
     expect(addCalls.length).toBeGreaterThanOrEqual(2);
     expect(addCalls[0].args[3]).toBe(extraMarketDir);
-    expect(addCalls[1].args[3]).toBe("/repo/root");
+    expect(addCalls[1].args[3]).toBe(repoRoot());
 
     // All install calls must come after all marketplace add calls
     const installIdx = calls.findIndex((c) => c.args[1] === "install");
@@ -1444,8 +1440,8 @@ describe("installPlugins — extra marketplace discovery", () => {
     await installPlugins(
       mockExec,
       testHome,
-      [],
-      "/repo/root",
+      [SHIPWRIGHT_ROW],
+      repoRoot(),
       join(testHome, "nonexistent.json"),
       undefined,
       conventionRoot,
@@ -1457,7 +1453,7 @@ describe("installPlugins — extra marketplace discovery", () => {
     const addDirs = addCalls.map((c) => c.args[3]);
     expect(addDirs).toContain(validDir);
     expect(addDirs).not.toContain(invalidDir);
-    expect(addDirs).toContain("/repo/root");
+    expect(addDirs).toContain(repoRoot());
   });
 
   it("is backward compatible when no extra marketplace dirs exist", async () => {
@@ -1478,8 +1474,8 @@ describe("installPlugins — extra marketplace discovery", () => {
     await installPlugins(
       mockExec,
       testHome,
-      [],
-      "/repo/root",
+      [SHIPWRIGHT_ROW],
+      repoRoot(),
       join(testHome, "nonexistent.json"),
       undefined,
       conventionRoot,
@@ -1488,7 +1484,7 @@ describe("installPlugins — extra marketplace discovery", () => {
     // Only the /repo/root marketplace add — same as before this feature
     const addCalls = calls.filter((c) => c.args[1] === "marketplace");
     expect(addCalls).toHaveLength(1);
-    expect(addCalls[0].args[3]).toBe("/repo/root");
+    expect(addCalls[0].args[3]).toBe(repoRoot());
     // marketplace add + install + update = 3 calls total
     expect(calls).toHaveLength(3);
   });

package/setup.ts

@@ -22,6 +22,10 @@ import {
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import type { AgentPlugin } from "@app-vitals/agent-admin";
+import {
+  resolveDefaultSpecialtyName,
+  resolveSpecialtiesDir,
+} from "@app-vitals/agent-lib/default-specialty";
 
 // ---------------------------------------------------------------------------
 // Template loading
@@ -53,16 +57,6 @@ export function resolveShipwrightRepoRoot(
   return env.SHIPWRIGHT_REPO_ROOT || DEFAULT_SHIPWRIGHT_REPO_ROOT;
 }
 
-// Local marketplace name — matches the `name` field in .claude-plugin/marketplace.json.
-const SHIPWRIGHT_MARKETPLACE = "shipwright";
-
-// Default plugin installed on all Shipwright agents.
-const DEFAULT_PLUGINS: readonly string[] = ["shipwright"];
-
-// The universal fallback type — mirrors admin's DEFAULT_SPECIALTY_NAME. Its
-// templates are the built-in workspace/ dir, so it never needs a manifest lookup.
-const DEFAULT_SPECIALTY_NAME = "coding";
-
 // The persona templates a type's templatesDir must provide or it is not usable.
 // Everything else (VOICE, mise, requirements, BOOTSTRAP) falls back per file to
 // the built-in workspace/ dir, and SPECIALTY.md.template is optional (ARD-6.2).
@@ -75,12 +69,17 @@ const REQUIRED_TEMPLATES: readonly string[] = [
 /**
  * Resolves the workspace template directory for a specialty (ARD-6.1).
  *
- * Reads `identity.templatesDir` from `<repoRoot>/specialties/<specialty>/manifest.yaml`
- * (relative paths resolve against the repo root, matching how the manifests
- * spell them). Returns the built-in workspace/ dir for `coding`, an absent
- * type, and any type that does not resolve (no manifest, unparseable, or the
- * directory is missing or lacks a required template) — logging a warning for the latter. Never throws:
- * a template lookup must not fail boot.
+ * Reads `identity.templatesDir` from `<specialtiesDir>/<specialty>/manifest.yaml`,
+ * where specialtiesDir is SHIPWRIGHT_SPECIALTIES_DIR or the shipped
+ * `agent-types/` (shared helper: @app-vitals/agent-lib/default-specialty). A
+ * relative templatesDir resolves against the repo root, then the specialties
+ * dir's parent (how the shipped manifests spell it: `agent-types/<t>/templates/`),
+ * then the manifest's own directory. An absent type resolves as the default
+ * type (`specialist`, or SHIPWRIGHT_DEFAULT_AGENT_TYPE). Returns the built-in
+ * (generic) workspace/ dir for any type that does not resolve (no manifest,
+ * unparseable, or the directory is missing or lacks a required template),
+ * logging a warning. An unknown requested type first falls back to the default
+ * type's templates (with a warning) before the built-in dir. Never throws: a template lookup must not fail boot.
  */
 export function resolveTemplatesDir(
   requestedType: string | undefined,
@@ -89,19 +88,12 @@ export function resolveTemplatesDir(
   env: Record<string, string | undefined> = process.env,
 ): string {
   const repoRoot = repoRootOverride ?? resolveShipwrightRepoRoot(env);
-  const specialty =
-    requestedType ||
-    env.SHIPWRIGHT_DEFAULT_AGENT_TYPE ||
-    DEFAULT_SPECIALTY_NAME;
-  if (specialty === DEFAULT_SPECIALTY_NAME) {
-    return WORKSPACE_TEMPLATE_DIR;
-  }
-  try {
-    const manifestPath = join(
-      env.SHIPWRIGHT_SPECIALTIES_DIR || join(repoRoot, "specialties"),
-      specialty,
-      "manifest.yaml",
-    );
+  const defaultSpecialty = resolveDefaultSpecialtyName(env);
+  const specialty = requestedType || defaultSpecialty;
+  const specialtiesDir = resolveSpecialtiesDir(env);
+
+  const lookup = (name: string): string => {
+    const manifestPath = join(specialtiesDir, name, "manifest.yaml");
     const manifest = Bun.YAML.parse(readFileSync(manifestPath, "utf8")) as {
       identity?: { templatesDir?: unknown };
     };
@@ -109,27 +101,49 @@ export function resolveTemplatesDir(
     if (typeof templatesDir !== "string" || templatesDir === "") {
       throw new Error("manifest has no identity.templatesDir");
     }
-    // Manifests written for the monorepo spell templatesDir relative to the
-    // repo root; a self-contained specialty (e.g. the platform test fixture)
-    // spells it relative to its own directory.
-    const fromRepoRoot = resolve(repoRoot, templatesDir);
-    const dir = existsSync(fromRepoRoot)
-      ? fromRepoRoot
-      : resolve(dirname(manifestPath), templatesDir);
+    // Manifests spell templatesDir relative to the repo root, or (shipped
+    // agent-types/, where the repo root may not be the image root) relative to
+    // the specialties dir's parent; a self-contained specialty (e.g. the
+    // platform test fixture) spells it relative to its own directory.
+    const dir =
+      [
+        resolve(repoRoot, templatesDir),
+        resolve(dirname(specialtiesDir), templatesDir),
+      ].find((candidate) => existsSync(candidate)) ??
+      resolve(dirname(manifestPath), templatesDir);
     if (!statSync(dir).isDirectory()) {
       throw new Error(`${dir} is not a directory`);
     }
     const missing = REQUIRED_TEMPLATES.filter(
-      (name) => !existsSync(join(dir, name)),
+      (file) => !existsSync(join(dir, file)),
     );
     if (missing.length > 0) {
       throw new Error(`${dir} is missing templates: ${missing.join(", ")}`);
     }
     return dir;
+  };
+
+  try {
+    return lookup(specialty);
   } catch (err) {
+    if (specialty !== defaultSpecialty) {
+      warn(
+        `[setup] could not resolve workspace templates for specialty "${specialty}" ` +
+          `(${(err as Error).message}) — falling back to the default type "${defaultSpecialty}"`,
+      );
+      try {
+        return lookup(defaultSpecialty);
+      } catch (defaultErr) {
+        warn(
+          `[setup] could not resolve workspace templates for default specialty "${defaultSpecialty}" ` +
+            `(${(defaultErr as Error).message}) — falling back to the built-in workspace templates`,
+        );
+        return WORKSPACE_TEMPLATE_DIR;
+      }
+    }
     warn(
       `[setup] could not resolve workspace templates for specialty "${specialty}" ` +
-        `(${(err as Error).message}) — falling back to "${DEFAULT_SPECIALTY_NAME}" templates`,
+        `(${(err as Error).message}) — falling back to the built-in workspace templates`,
     );
     return WORKSPACE_TEMPLATE_DIR;
   }
@@ -379,15 +393,15 @@ export function findStalePluginSpecs(
 }
 
 /**
- * Installs the shipwright default plugins plus any agent-specific plugins
- * from the config bundle. All commands are idempotent (exit 0 when already
+ * Installs the plugins in the agent's own AgentPlugin rows (seeded from the
+ * specialty manifest at create time). No plugin is installed by default. All commands are idempotent (exit 0 when already
  * present / already at latest), so reboots are a silent no-op.
  *
  * Non-fatal — a missing `claude` binary or network blip logs and returns
  * without throwing, so startup is never blocked.
  *
- * Install order: defaults first, then agent-specific plugins.
- * Update order: same.
+ * The built-in marketplace is only registered when `shipwrightRepoRoot` has a
+ * `.claude-plugin/marketplace.json` (the platform image ships none).
  *
  * Marketplace registration order:
  *   1. Extra baked marketplaces (discovered from `extraMarketplacesRoot` or
@@ -443,24 +457,22 @@ export async function installPlugins(
 
     // Register the local (built-in) shipwright marketplace so `claude plugin install`
     // can resolve plugins by name. Idempotent — safe to call on every startup.
-    const add = await execFn(
-      "claude",
-      ["plugin", "marketplace", "add", shipwrightRepoRoot],
-      { cwd },
-    );
-    if (add.exitCode !== 0) {
-      console.warn(
-        `[agent] claude plugin marketplace add exited ${add.exitCode}: ${add.stdout}`,
+    if (
+      existsSync(join(shipwrightRepoRoot, ".claude-plugin", "marketplace.json"))
+    ) {
+      const add = await execFn(
+        "claude",
+        ["plugin", "marketplace", "add", shipwrightRepoRoot],
+        { cwd },
       );
+      if (add.exitCode !== 0) {
+        console.warn(
+          `[agent] claude plugin marketplace add exited ${add.exitCode}: ${add.stdout}`,
+        );
+      }
     }
 
-    const defaultPluginSpecs = DEFAULT_PLUGINS.map(
-      (name) => `${name}@${SHIPWRIGHT_MARKETPLACE}`,
-    );
-    const agentPluginSpecs = agentPlugins.map(
-      (p) => `${p.plugin}@${p.marketplace}`,
-    );
-    const allSpecs = [...defaultPluginSpecs, ...agentPluginSpecs];
+    const allSpecs = agentPlugins.map((p) => `${p.plugin}@${p.marketplace}`);
 
     // Uninstall any plugin whose recorded installPath no longer exists. This
     // clears stale manifest entries left over from a different-HOME container
@@ -482,7 +494,7 @@ export async function installPlugins(
       }
     }
 
-    // Install all plugins (defaults then agent-specific).
+    // Install all plugins .
     // Skip any stale spec whose uninstall failed — install is idempotent and
     // would silently succeed without fixing the stale path, hiding the breakage.
     for (const spec of allSpecs) {
@@ -497,7 +509,7 @@ export async function installPlugins(
       }
     }
 
-    // Update all plugins (defaults then agent-specific).
+    // Update all plugins .
     // Skip specs whose uninstall failed for the same reason as the install loop.
     for (const spec of allSpecs) {
       if (failedUninstalls.has(spec)) continue;

package/setup.unit.test.ts

@@ -4,7 +4,7 @@
  * Pure logic tests: no I/O, no real binaries, injected exec doubles only.
  */
 
-import { describe, expect, it } from "bun:test";
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -22,56 +22,64 @@ import {
 // these tests depend on ambient sandbox/image state.
 const NO_EXTRA_MARKETPLACES: string[] = [];
 
-describe("installPlugins — local marketplace", () => {
-  it("registers the marketplace before installing plugins", async () => {
-    const calls: Array<{ cmd: string; args: string[] }> = [];
-    const mockExec = async (
-      cmd: string,
-      args: string[],
-      _opts: { cwd: string },
-    ) => {
-      calls.push({ cmd, args });
-      return { stdout: "", exitCode: 0 };
-    };
+const SHIPWRIGHT_ROW = { plugin: "shipwright", marketplace: "shipwright" };
+
+// A repo root that carries a local marketplace (a coding image); the platform
+// image has none.
+const makeMarketplaceRoot = (): string => {
+  const root = mkdtempSync(join(tmpdir(), "mkt-root-"));
+  mkdirSync(join(root, ".claude-plugin"), { recursive: true });
+  writeFileSync(join(root, ".claude-plugin", "marketplace.json"), "{}");
+  return root;
+};
+
+const recordCalls = () => {
+  const calls: Array<{ cmd: string; args: string[] }> = [];
+  const exec = async (cmd: string, args: string[], _opts: { cwd: string }) => {
+    calls.push({ cmd, args });
+    return { stdout: "", exitCode: 0 };
+  };
+  return { calls, exec };
+};
 
-    await installPlugins(
-      mockExec,
+describe("installPlugins — local marketplace", () => {
+  let root: string;
+  beforeEach(() => {
+    root = makeMarketplaceRoot();
+  });
+  afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+  const run = (
+    exec: ReturnType<typeof recordCalls>["exec"],
+    plugins: Array<{ plugin: string; marketplace: string }>,
+    repoRoot = root,
+    extra: string[] = NO_EXTRA_MARKETPLACES,
+  ) =>
+    installPlugins(
+      exec,
       "/tmp/cwd",
-      [],
-      "/repo/root",
+      plugins,
+      repoRoot,
       "/tmp/nonexistent-manifest.json",
-      NO_EXTRA_MARKETPLACES,
+      extra,
     );
 
-    // First call must be marketplace add
-    expect(calls[0].args).toEqual([
-      "plugin",
-      "marketplace",
-      "add",
-      "/repo/root",
-    ]);
+  it("registers the marketplace before installing plugins", async () => {
+    const { calls, exec } = recordCalls();
+    await run(exec, [SHIPWRIGHT_ROW]);
+    expect(calls[0].args).toEqual(["plugin", "marketplace", "add", root]);
   });
 
-  it("installs and updates shipwright@shipwright using the shipwright marketplace name", async () => {
-    const calls: Array<{ cmd: string; args: string[] }> = [];
-    const mockExec = async (
-      cmd: string,
-      args: string[],
-      _opts: { cwd: string },
-    ) => {
-      calls.push({ cmd, args });
-      return { stdout: "", exitCode: 0 };
-    };
-
-    await installPlugins(
-      mockExec,
-      "/tmp/cwd",
-      [],
-      "/repo/root",
-      "/tmp/nonexistent-manifest.json",
-      NO_EXTRA_MARKETPLACES,
-    );
+  it("installs nothing when the agent has no plugin rows", async () => {
+    const { calls, exec } = recordCalls();
+    await run(exec, []);
+    expect(calls.filter((c) => c.args[1] === "install")).toEqual([]);
+    expect(calls.filter((c) => c.args[1] === "update")).toEqual([]);
+  });
 
+  it("installs and updates shipwright@shipwright for a coding agent's shipwright row", async () => {
+    const { calls, exec } = recordCalls();
+    await run(exec, [SHIPWRIGHT_ROW]);
     // marketplace add + install + update = 3 calls
     expect(calls).toHaveLength(3);
     expect(calls[1].args).toEqual([
@@ -87,29 +95,14 @@ describe("installPlugins — local marketplace", () => {
   });
 
   it("agent plugins use their own marketplace, not the local one", async () => {
-    const calls: Array<{ cmd: string; args: string[] }> = [];
-    const mockExec = async (
-      cmd: string,
-      args: string[],
-      _opts: { cwd: string },
-    ) => {
-      calls.push({ cmd, args });
-      return { stdout: "", exitCode: 0 };
-    };
-
-    await installPlugins(
-      mockExec,
-      "/tmp/cwd",
-      [{ plugin: "my-plugin", marketplace: "org/my-marketplace" }],
-      "/repo/root",
-      "/tmp/nonexistent-manifest.json",
-      NO_EXTRA_MARKETPLACES,
-    );
-
+    const { calls, exec } = recordCalls();
+    await run(exec, [
+      SHIPWRIGHT_ROW,
+      { plugin: "my-plugin", marketplace: "org/my-marketplace" },
+    ]);
     // marketplace add + 2 installs + 2 updates = 5 calls
     expect(calls).toHaveLength(5);
-    const specs = calls.slice(1).map((c) => c.args[2]);
-    expect(specs).toEqual([
+    expect(calls.slice(1).map((c) => c.args[2])).toEqual([
       "shipwright@shipwright",
       "my-plugin@org/my-marketplace",
       "shipwright@shipwright",
@@ -117,128 +110,30 @@ describe("installPlugins — local marketplace", () => {
     ]);
   });
 
-  it("passes the repoRoot to marketplace add", async () => {
-    const calls: Array<{ cmd: string; args: string[] }> = [];
-    const mockExec = async (
-      cmd: string,
-      args: string[],
-      _opts: { cwd: string },
-    ) => {
-      calls.push({ cmd, args });
-      return { stdout: "", exitCode: 0 };
-    };
-
-    await installPlugins(
-      mockExec,
-      "/tmp/cwd",
-      [],
-      "/custom/repo/root",
-      "/tmp/nonexistent-manifest.json",
-      NO_EXTRA_MARKETPLACES,
-    );
-
-    expect(calls[0].args).toEqual([
-      "plugin",
-      "marketplace",
-      "add",
-      "/custom/repo/root",
-    ]);
+  it("skips the local marketplace add when the repo root has no marketplace", async () => {
+    const { calls, exec } = recordCalls();
+    await run(exec, [], "/repo/root");
+    expect(calls).toEqual([]);
   });
 
-  it("registers extra marketplaces before the /app marketplace", async () => {
-    const calls: Array<{ cmd: string; args: string[] }> = [];
-    const mockExec = async (
-      cmd: string,
-      args: string[],
-      _opts: { cwd: string },
-    ) => {
-      calls.push({ cmd, args });
-      return { stdout: "", exitCode: 0 };
-    };
-
-    // Pass a non-existent root so discoverBakedMarketplaces can't find dirs —
-    // we inject via extraMarketplaceDirs directly instead.
-    await installPlugins(
-      mockExec,
-      "/tmp/cwd",
-      [],
-      "/repo/root",
-      "/tmp/nonexistent-manifest.json",
-      ["/opt/shipwright/marketplaces/my-marketplace"],
-    );
-
-    // Extra marketplace add must come BEFORE the /repo/root marketplace add
+  it("registers extra marketplaces before the local marketplace", async () => {
+    const { calls, exec } = recordCalls();
+    await run(exec, [], root, ["/opt/shipwright/marketplaces/my-marketplace"]);
     const addCalls = calls.filter((c) => c.args[1] === "marketplace");
     expect(addCalls[0].args[3]).toBe(
       "/opt/shipwright/marketplaces/my-marketplace",
     );
-    expect(addCalls[1].args[3]).toBe("/repo/root");
-  });
-
-  it("is a no-op when no extra marketplace dirs exist", async () => {
-    const calls: Array<{ cmd: string; args: string[] }> = [];
-    const mockExec = async (
-      cmd: string,
-      args: string[],
-      _opts: { cwd: string },
-    ) => {
-      calls.push({ cmd, args });
-      return { stdout: "", exitCode: 0 };
-    };
-
-    await installPlugins(
-      mockExec,
-      "/tmp/cwd",
-      [],
-      "/repo/root",
-      "/tmp/nonexistent-manifest.json",
-      NO_EXTRA_MARKETPLACES,
-    );
-
-    // Only the /repo/root marketplace add — no extra adds
-    const addCalls = calls.filter((c) => c.args[1] === "marketplace");
-    expect(addCalls).toHaveLength(1);
-    expect(addCalls[0].args[3]).toBe("/repo/root");
+    expect(addCalls[1].args[3]).toBe(root);
   });
 
   it("never reads the real BAKED_MARKETPLACES_ROOT when extraMarketplaceDirs is injected (isolation regression)", async () => {
-    // Regression test for T-002: previously, tests that omitted the
-    // extraMarketplaceDirs arg silently fell through to
-    // discoverBakedMarketplaces(BAKED_MARKETPLACES_ROOT), which performs a
-    // real existsSync/readdirSync against /opt/shipwright/marketplaces. On any
-    // image/sandbox that bakes a marketplace there (this sandbox does), that
-    // extra ambient `marketplace add` call would silently appear before the
-    // expected calls and break exact-match assertions below.
-    //
-    // This test asserts the injected empty array wins deterministically,
-    // regardless of what (if anything) actually exists on disk at
-    // /opt/shipwright/marketplaces in the environment running the suite.
-    const calls: Array<{ cmd: string; args: string[] }> = [];
-    const mockExec = async (
-      cmd: string,
-      args: string[],
-      _opts: { cwd: string },
-    ) => {
-      calls.push({ cmd, args });
-      return { stdout: "", exitCode: 0 };
-    };
-
-    await installPlugins(
-      mockExec,
-      "/tmp/cwd",
-      [],
-      "/repo/root",
-      "/tmp/nonexistent-manifest.json",
-      NO_EXTRA_MARKETPLACES,
-    );
-
-    // Exactly one marketplace add (the built-in shipwright one) — no extra
-    // marketplace add sneaks in from real fs discovery, no matter what's
-    // actually present on disk at BAKED_MARKETPLACES_ROOT in this environment.
+    // The injected empty array must win over real fs discovery of
+    // /opt/shipwright/marketplaces, whatever the sandbox has baked there.
+    const { calls, exec } = recordCalls();
+    await run(exec, [SHIPWRIGHT_ROW]);
     const addCalls = calls.filter((c) => c.args[1] === "marketplace");
     expect(addCalls).toHaveLength(1);
-    expect(addCalls[0].args[3]).toBe("/repo/root");
-    // Full call count is deterministic: marketplace add + install + update = 3.
+    expect(addCalls[0].args[3]).toBe(root);
     expect(calls).toHaveLength(3);
   });
 });
@@ -281,9 +176,49 @@ describe("resolveTemplatesDir option resolution (AEP-1.2)", () => {
     expect(warnings).toEqual([]);
   });
 
-  it("resolves an absent type to the built-in templates with no env set", async () => {
+  it("resolves an absent type as the shipped specialist type with no env and no warning", async () => {
     const { resolveTemplatesDir } = await import("./setup.ts");
-    const dir = resolveTemplatesDir(undefined, "/nonexistent", () => {}, {});
+    const warnings: string[] = [];
+    const dir = resolveTemplatesDir(
+      undefined,
+      join(import.meta.dir, ".."),
+      (m) => warnings.push(m),
+      {},
+    );
+    expect(warnings).toEqual([]);
+    expect(dir).toBe(
+      join(import.meta.dir, "..", "agent-types", "specialist", "templates"),
+    );
+  });
+
+  it("warns and falls back to the default type's templates for an unknown requested type", async () => {
+    const { resolveTemplatesDir } = await import("./setup.ts");
+    const warnings: string[] = [];
+    const dir = resolveTemplatesDir(
+      "renamed-type",
+      join(import.meta.dir, ".."),
+      (m) => warnings.push(m),
+      {},
+    );
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('"renamed-type"');
+    expect(warnings[0]).toContain('"specialist"');
+    expect(dir).toBe(
+      join(import.meta.dir, "..", "agent-types", "specialist", "templates"),
+    );
+  });
+
+  it("falls back to the built-in templates when the default type cannot load either", async () => {
+    const { resolveTemplatesDir } = await import("./setup.ts");
+    const warnings: string[] = [];
+    const dir = resolveTemplatesDir(
+      "renamed-type",
+      "/nonexistent",
+      (m) => warnings.push(m),
+      { SHIPWRIGHT_SPECIALTIES_DIR: "/nonexistent/types" },
+    );
+    expect(warnings).toHaveLength(2);
+    expect(warnings[1]).toContain("built-in");
     expect(dir).toMatch(/workspace$/);
   });
 
@@ -328,28 +263,36 @@ describe("SHIPWRIGHT_REPO_ROOT override (PCB-1.1)", () => {
       "/tmp/nonexistent-baked-root",
       env,
     );
-    return calls[0][3];
+    return calls[0]?.[3];
   };
 
   it("installPlugins registers the marketplace from SHIPWRIGHT_REPO_ROOT when set", async () => {
-    expect(await registerRoot({ SHIPWRIGHT_REPO_ROOT: "/opt/custom" })).toBe(
-      "/opt/custom",
-    );
+    const custom = makeMarketplaceRoot();
+    try {
+      expect(await registerRoot({ SHIPWRIGHT_REPO_ROOT: custom })).toBe(custom);
+    } finally {
+      rmSync(custom, { recursive: true, force: true });
+    }
   });
 
   it("installPlugins keeps the computed default when unset or empty", async () => {
     const unset = await registerRoot({});
-    expect(unset).toBe(resolveShipwrightRepoRoot({}));
-    expect(unset).not.toBe("/opt/custom");
+    // Only registered when the computed default root carries a marketplace.
+    expect(unset === undefined || unset === resolveShipwrightRepoRoot({})).toBe(
+      true,
+    );
     expect(await registerRoot({ SHIPWRIGHT_REPO_ROOT: "" })).toBe(unset);
   });
 
   describe("resolveTemplatesDir", () => {
     const makeRoot = () => {
       const root = mkdtempSync(join(tmpdir(), "repo-root-"));
-      const dir = join(root, "specialties", "foo");
+      const dir = join(root, "types", "foo");
       mkdirSync(join(dir, "tpl"), { recursive: true });
-      writeFileSync(join(dir, "manifest.yaml"), "identity:\n  templatesDir: tpl\n");
+      writeFileSync(
+        join(dir, "manifest.yaml"),
+        "identity:\n  templatesDir: tpl\n",
+      );
       for (const f of [
         "CLAUDE.md.template",
         "SOUL.md.template",
@@ -360,7 +303,7 @@ describe("SHIPWRIGHT_REPO_ROOT override (PCB-1.1)", () => {
       return { root, tpl: join(dir, "tpl") };
     };
 
-    it("looks up specialties under SHIPWRIGHT_REPO_ROOT when set", () => {
+    it("resolves templatesDir against SHIPWRIGHT_REPO_ROOT when set", () => {
       const { root, tpl } = makeRoot();
       try {
         const warnings: string[] = [];
@@ -368,7 +311,10 @@ describe("SHIPWRIGHT_REPO_ROOT override (PCB-1.1)", () => {
           "foo",
           undefined,
           (m) => warnings.push(m),
-          { SHIPWRIGHT_REPO_ROOT: root },
+          {
+            SHIPWRIGHT_REPO_ROOT: root,
+            SHIPWRIGHT_SPECIALTIES_DIR: join(root, "types"),
+          },
         );
         expect(warnings).toEqual([]);
         expect(dir).toBe(tpl);

package/workspace/SPECIALTY.md.template

@@ -1,37 +1,6 @@
-### Shipwright
-
-You are a software engineering agent. All planning and code changes use the shipwright workflow:
-
-- **Planning:** `/shipwright:plan-session`
-- **Execution:** `/shipwright:dev-task` (single) or `/shipwright:dev-loop` (continuous)
-- **Review:** `/shipwright:review`
-
-The work queue lives in the hosted task-store service — query it directly:
-
-```bash
-curl -sf -H "Authorization: Bearer $SHIPWRIGHT_TASK_STORE_TOKEN" \
-  "$SHIPWRIGHT_TASK_STORE_URL/tasks?ready=true" | jq '.tasks'
-```
-
-`dev-task`, `review`, `patch`, and `deploy` are **explicit-target-only executors** — none of
-them self-discovers work. Candidate selection happens upstream, once per tick, in the
-`shipwright-loop` cron: its candidate providers merge dev-task/review/patch/deploy
-candidates and pick exactly one winning item via strict age-based FIFO, then dispatch the
-matching command with the winning task id or `org/repo#number` embedded directly in the
-prompt. `dev-task`, `review`, and `patch` are enabled by default; `deploy` is opt-in. A
-standalone phase cron with `shipwright-loop` disabled is **silently inert** — its prompt
-carries no target, so every tick responds `[silent]` and does nothing.
-
-### Policy
-
-Agent behavior is controlled by the policy fields on the agent record (review
-posting, self-review, confidence and finding limits, worktree cleanup),
-delivered via `GET /agents/:id/config` and edited through the agents UI or
-`PATCH /agents/:id`.
-
-### Reviews
-
-Review state is tracked in the task store's `PullRequest` record (`staged` +
-`commitSha` fields). Review artifacts (PR_REVIEW files and review JSON) live in
-`state/reviews/`. See `/shipwright:review` for the full flow.
+### Specialty
 
+This workspace was seeded from the platform's generic fallback template because
+no specialty-specific workspace content was available for this agent type.
+Describe this agent's specialty, tools, and workflow here. Existing workspace
+files are never rewritten, so edits to this file persist.

package/workspace/SPECIALTY.md.template.content.test.ts

@@ -1,10 +1,10 @@
 /**
- * SPECIALTY.md.template content regression guard — DPF-1.1
+ * SPECIALTY.md.template content regression guard — PCD-2.2
  *
- * Verifies the coding specialty's "Shipwright" section describes the
- * shipwright-loop-driven, explicit-target-only pipeline model (WLS-6.1), not
- * the stale self-discovering-cron model it replaced. Relocated from
- * the former CLAUDE template content test when the template was layered (ARD-6.2).
+ * The platform's SPECIALTY.md.template is the generic fallback for every agent
+ * type, so it must stay a neutral stub. Specialty-specific pipeline content
+ * (e.g. the coding specialty's Shipwright workflow) is shipped by the specialty
+ * itself through its manifest's identity.templatesDir.
  *
  * Content-assertion only: readFileSync, no I/O beyond local file reads.
  */
@@ -19,32 +19,23 @@ function readTemplate(): string {
   return readFileSync(TEMPLATE_PATH, "utf8");
 }
 
-describe("SPECIALTY.md.template — shipwright-loop model", () => {
-  it("mentions the shipwright-loop cron as the driver", () => {
-    expect(readTemplate()).toContain("shipwright-loop");
+describe("SPECIALTY.md.template — generic stub", () => {
+  it("is a non-empty stub", () => {
+    expect(readTemplate().trim().length).toBeGreaterThan(0);
   });
 
-  it("describes dev-task/review/patch/deploy as explicit-target-only executors", () => {
-    expect(readTemplate().toLowerCase()).toContain("explicit-target-only");
-  });
-
-  it("mentions strict age-based FIFO work selection", () => {
-    expect(readTemplate().toLowerCase()).toContain("fifo");
-  });
-
-  it("notes a standalone phase cron with shipwright-loop disabled is silently inert", () => {
-    expect(readTemplate().toLowerCase()).toContain("silently inert");
-  });
-
-  it("does not claim dev-task picks up pending items on a fixed schedule independent of the loop", () => {
-    expect(readTemplate()).not.toContain(
-      "picks up the next pending item every 30 minutes",
-    );
-  });
-
-  it("does not describe review/patch as independently self-discovering phases", () => {
-    expect(readTemplate()).not.toContain(
-      "run as independent phases — review posts",
-    );
+  it.each([
+    "shipwright",
+    "dev-task",
+    "dev-loop",
+    "plan-session",
+    "task-store",
+    "TASK_STORE",
+    "PullRequest",
+    "explicit-target-only",
+    "fifo",
+    "curl",
+  ])("does not mention Shipwright-pipeline term %p", (term) => {
+    expect(readTemplate().toLowerCase()).not.toContain(term.toLowerCase());
   });
 });