@app-vitals/agent-runtime 0.15.0 → 0.16.1

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.15.0",
+  "version": "0.16.1",
   "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.15.0",
-    "@app-vitals/agent-lib": "0.15.0",
+    "@app-vitals/agent-admin": "0.16.1",
+    "@app-vitals/agent-lib": "0.16.1",
     "@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.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
@@ -59,10 +63,6 @@ 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 +75,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 +94,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 +107,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;
   }

package/setup.unit.test.ts

@@ -281,9 +281,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$/);
   });
 
@@ -347,9 +387,12 @@ describe("SHIPWRIGHT_REPO_ROOT override (PCB-1.1)", () => {
   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 +403,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 +411,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());
   });
 });