@cat-factory/agents 0.6.0

package/dist/agents/companions.d.ts

@@ -0,0 +1,20 @@
+import type { AgentKind } from '@cat-factory/kernel';
+export interface CompanionDefinition {
+    /** The companion's own agent kind. */
+    kind: AgentKind;
+    /** Producer kinds this companion may review (allow-list for pipeline placement). */
+    targets: AgentKind[];
+    /** Default quality bar (0..1) a pipeline step uses when it sets no explicit threshold. */
+    defaultThreshold: number;
+    /** Short label for the producer being reviewed, woven into the companion's prompt. */
+    reviews: string;
+}
+/** The built-in companion catalog. */
+export declare const COMPANIONS: CompanionDefinition[];
+/** Whether `kind` is a companion agent (driven by the engine's companion review loop). */
+export declare function isCompanionKind(kind: AgentKind): boolean;
+/** The companion definition for `kind`, or undefined if it is not a companion. */
+export declare function companionFor(kind: AgentKind): CompanionDefinition | undefined;
+/** The producer kinds a companion may be attached to (empty if not a companion). */
+export declare function companionTargets(kind: AgentKind): AgentKind[];
+//# sourceMappingURL=companions.d.ts.map

package/dist/agents/companions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companions.d.ts","sourceRoot":"","sources":["../../src/agents/companions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAYpD,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,IAAI,EAAE,SAAS,CAAA;IACf,oFAAoF;IACpF,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,0FAA0F;IAC1F,gBAAgB,EAAE,MAAM,CAAA;IACxB,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,sCAAsC;AACtC,eAAO,MAAM,UAAU,EAAE,mBAAmB,EAqB3C,CAAA;AAID,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAExD;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,mBAAmB,GAAG,SAAS,CAE7E;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,EAAE,CAE7D"}

package/dist/agents/companions.js

@@ -0,0 +1,38 @@
+import { DEFAULT_COMPANION_THRESHOLD } from '@cat-factory/contracts';
+/** The built-in companion catalog. */
+export const COMPANIONS = [
+    {
+        kind: 'architect-companion',
+        targets: ['architect'],
+        defaultThreshold: DEFAULT_COMPANION_THRESHOLD,
+        reviews: 'solution design / architecture proposal',
+    },
+    {
+        kind: 'spec-companion',
+        targets: ['spec-writer'],
+        defaultThreshold: DEFAULT_COMPANION_THRESHOLD,
+        reviews: 'service specification and the completeness of its acceptance-scenario coverage',
+    },
+    {
+        // `reviewer` is the coder's companion: it directly challenges the builder's
+        // output and can loop it back for rework. Auto-only by default (no human gate).
+        kind: 'reviewer',
+        targets: ['coder'],
+        defaultThreshold: DEFAULT_COMPANION_THRESHOLD,
+        reviews: 'code change for correctness, quality, security and risk',
+    },
+];
+const BY_KIND = new Map(COMPANIONS.map((c) => [c.kind, c]));
+/** Whether `kind` is a companion agent (driven by the engine's companion review loop). */
+export function isCompanionKind(kind) {
+    return BY_KIND.has(kind);
+}
+/** The companion definition for `kind`, or undefined if it is not a companion. */
+export function companionFor(kind) {
+    return BY_KIND.get(kind);
+}
+/** The producer kinds a companion may be attached to (empty if not a companion). */
+export function companionTargets(kind) {
+    return BY_KIND.get(kind)?.targets ?? [];
+}
+//# sourceMappingURL=companions.js.map

package/dist/agents/companions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"companions.js","sourceRoot":"","sources":["../../src/agents/companions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAA;AAsBpE,sCAAsC;AACtC,MAAM,CAAC,MAAM,UAAU,GAA0B;IAC/C;QACE,IAAI,EAAE,qBAAqB;QAC3B,OAAO,EAAE,CAAC,WAAW,CAAC;QACtB,gBAAgB,EAAE,2BAA2B;QAC7C,OAAO,EAAE,yCAAyC;KACnD;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,CAAC,aAAa,CAAC;QACxB,gBAAgB,EAAE,2BAA2B;QAC7C,OAAO,EAAE,gFAAgF;KAC1F;IACD;QACE,4EAA4E;QAC5E,gFAAgF;QAChF,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,CAAC,OAAO,CAAC;QAClB,gBAAgB,EAAE,2BAA2B;QAC7C,OAAO,EAAE,yDAAyD;KACnE;CACF,CAAA;AAED,MAAM,OAAO,GAAG,IAAI,GAAG,CAA8B,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;AAExF,0FAA0F;AAC1F,MAAM,UAAU,eAAe,CAAC,IAAe;IAC7C,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC1B,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,IAAe;IAC1C,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC1B,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,gBAAgB,CAAC,IAAe;IAC9C,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,IAAI,EAAE,CAAA;AACzC,CAAC"}

package/dist/agents/kinds/companions.d.ts

@@ -0,0 +1,20 @@
+import type { AgentKind } from '@cat-factory/kernel';
+export interface CompanionDefinition {
+    /** The companion's own agent kind. */
+    kind: AgentKind;
+    /** Producer kinds this companion may review (allow-list for pipeline placement). */
+    targets: AgentKind[];
+    /** Default quality bar (0..1) a pipeline step uses when it sets no explicit threshold. */
+    defaultThreshold: number;
+    /** Short label for the producer being reviewed, woven into the companion's prompt. */
+    reviews: string;
+}
+/** The built-in companion catalog. */
+export declare const COMPANIONS: CompanionDefinition[];
+/** Whether `kind` is a companion agent (driven by the engine's companion review loop). */
+export declare function isCompanionKind(kind: AgentKind): boolean;
+/** The companion definition for `kind`, or undefined if it is not a companion. */
+export declare function companionFor(kind: AgentKind): CompanionDefinition | undefined;
+/** The producer kinds a companion may be attached to (empty if not a companion). */
+export declare function companionTargets(kind: AgentKind): AgentKind[];
+//# sourceMappingURL=companions.d.ts.map

package/dist/agents/kinds/companions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companions.d.ts","sourceRoot":"","sources":["../../../src/agents/kinds/companions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAYpD,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,IAAI,EAAE,SAAS,CAAA;IACf,oFAAoF;IACpF,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,0FAA0F;IAC1F,gBAAgB,EAAE,MAAM,CAAA;IACxB,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,sCAAsC;AACtC,eAAO,MAAM,UAAU,EAAE,mBAAmB,EAuB3C,CAAA;AAID,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAExD;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,mBAAmB,GAAG,SAAS,CAE7E;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,EAAE,CAE7D"}

package/dist/agents/kinds/companions.js

@@ -0,0 +1,39 @@
+import { DEFAULT_COMPANION_THRESHOLD } from '@cat-factory/contracts';
+/** The built-in companion catalog. */
+export const COMPANIONS = [
+    {
+        kind: 'architect-companion',
+        targets: ['architect'],
+        defaultThreshold: DEFAULT_COMPANION_THRESHOLD,
+        reviews: 'solution design / architecture proposal',
+    },
+    {
+        kind: 'spec-companion',
+        targets: ['spec-writer'],
+        defaultThreshold: DEFAULT_COMPANION_THRESHOLD,
+        reviews: "specification increment's fidelity to the task requirements it was given and the " +
+            'completeness of its acceptance-scenario coverage',
+    },
+    {
+        // `reviewer` is the coder's companion: it directly challenges the builder's
+        // output and can loop it back for rework. Auto-only by default (no human gate).
+        kind: 'reviewer',
+        targets: ['coder'],
+        defaultThreshold: DEFAULT_COMPANION_THRESHOLD,
+        reviews: 'code change for correctness, quality, security and risk',
+    },
+];
+const BY_KIND = new Map(COMPANIONS.map((c) => [c.kind, c]));
+/** Whether `kind` is a companion agent (driven by the engine's companion review loop). */
+export function isCompanionKind(kind) {
+    return BY_KIND.has(kind);
+}
+/** The companion definition for `kind`, or undefined if it is not a companion. */
+export function companionFor(kind) {
+    return BY_KIND.get(kind);
+}
+/** The producer kinds a companion may be attached to (empty if not a companion). */
+export function companionTargets(kind) {
+    return BY_KIND.get(kind)?.targets ?? [];
+}
+//# sourceMappingURL=companions.js.map

package/dist/agents/kinds/companions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"companions.js","sourceRoot":"","sources":["../../../src/agents/kinds/companions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAA;AAsBpE,sCAAsC;AACtC,MAAM,CAAC,MAAM,UAAU,GAA0B;IAC/C;QACE,IAAI,EAAE,qBAAqB;QAC3B,OAAO,EAAE,CAAC,WAAW,CAAC;QACtB,gBAAgB,EAAE,2BAA2B;QAC7C,OAAO,EAAE,yCAAyC;KACnD;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,CAAC,aAAa,CAAC;QACxB,gBAAgB,EAAE,2BAA2B;QAC7C,OAAO,EACL,mFAAmF;YACnF,kDAAkD;KACrD;IACD;QACE,4EAA4E;QAC5E,gFAAgF;QAChF,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,CAAC,OAAO,CAAC;QAClB,gBAAgB,EAAE,2BAA2B;QAC7C,OAAO,EAAE,yDAAyD;KACnE;CACF,CAAA;AAED,MAAM,OAAO,GAAG,IAAI,GAAG,CAA8B,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;AAExF,0FAA0F;AAC1F,MAAM,UAAU,eAAe,CAAC,IAAe;IAC7C,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC1B,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,IAAe;IAC1C,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC1B,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,gBAAgB,CAAC,IAAe;IAC9C,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,IAAI,EAAE,CAAA;AACzC,CAAC"}

package/dist/agents/kinds/configs.d.ts

@@ -0,0 +1,17 @@
+import type { AgentConfigDescriptor, AgentKind } from '@cat-factory/kernel';
+/** The Tester's environment choice: stand infra up locally, or use the ephemeral env. */
+export declare const TESTER_ENVIRONMENT_CONFIG_ID = "tester.environment";
+/** The acceptance/e2e execution target: project CI, or the ephemeral env. */
+export declare const PLAYWRIGHT_E2E_TARGET_CONFIG_ID = "playwright.e2eTarget";
+/**
+ * The config descriptors an agent kind contributes: the built-in ones plus any a
+ * deployment registered for the kind. Empty for kinds that contribute none.
+ */
+export declare function configContributionsFor(kind: AgentKind): AgentConfigDescriptor[];
+/**
+ * The deduplicated catalog of config descriptors contributed across a set of agent
+ * kinds (e.g. all the kinds used by a workspace's pipelines), keyed by descriptor
+ * id (first contribution wins). This is what the workspace snapshot carries.
+ */
+export declare function configContributionCatalog(kinds: Iterable<AgentKind>): AgentConfigDescriptor[];
+//# sourceMappingURL=configs.d.ts.map

package/dist/agents/kinds/configs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configs.d.ts","sourceRoot":"","sources":["../../../src/agents/kinds/configs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAQ3E,yFAAyF;AACzF,eAAO,MAAM,4BAA4B,uBAAuB,CAAA;AAChE,6EAA6E;AAC7E,eAAO,MAAM,+BAA+B,yBAAyB,CAAA;AAqCrE;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,qBAAqB,EAAE,CAI/E;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,qBAAqB,EAAE,CAQ7F"}

package/dist/agents/kinds/configs.js

@@ -0,0 +1,66 @@
+import { registeredConfigContributions } from './registry.js';
+// Built-in agent config contributions. An agent kind declares the task-level
+// parameters it cares about here; the union over a pipeline's kinds is what the
+// task-creation form and inspector render (and freeze once the owning step runs).
+// Custom kinds contribute the same way via `registerAgentKind({ configContributions })`.
+/** The Tester's environment choice: stand infra up locally, or use the ephemeral env. */
+export const TESTER_ENVIRONMENT_CONFIG_ID = 'tester.environment';
+/** The acceptance/e2e execution target: project CI, or the ephemeral env. */
+export const PLAYWRIGHT_E2E_TARGET_CONFIG_ID = 'playwright.e2eTarget';
+const BUILTIN_CONFIG_CONTRIBUTIONS = {
+    tester: [
+        {
+            id: TESTER_ENVIRONMENT_CONFIG_ID,
+            agentKind: 'tester',
+            label: 'Test environment',
+            description: "Where the Tester runs the suite: with the service's dependencies stood up locally via docker-compose, or against the provisioned ephemeral environment.",
+            type: 'select',
+            options: [
+                { value: 'ephemeral', label: 'Ephemeral environment' },
+                { value: 'local', label: 'Local (docker-compose infra)' },
+            ],
+            // Ephemeral is the zero-config default; local is an opt-in that requires the
+            // service's test infra to be configured (a compose path or the no-infra flag).
+            default: 'ephemeral',
+        },
+    ],
+    playwright: [
+        {
+            id: PLAYWRIGHT_E2E_TARGET_CONFIG_ID,
+            agentKind: 'playwright',
+            label: 'E2E execution target',
+            description: 'Where the acceptance / end-to-end tests run: in the project CI (GitHub Actions), or against the provisioned ephemeral environment.',
+            type: 'select',
+            options: [
+                { value: 'ci', label: 'Project CI (GitHub Actions)' },
+                { value: 'ephemeral', label: 'Ephemeral environment' },
+            ],
+            default: 'ci',
+        },
+    ],
+};
+/**
+ * The config descriptors an agent kind contributes: the built-in ones plus any a
+ * deployment registered for the kind. Empty for kinds that contribute none.
+ */
+export function configContributionsFor(kind) {
+    const builtin = BUILTIN_CONFIG_CONTRIBUTIONS[kind] ?? [];
+    const registered = registeredConfigContributions(kind);
+    return registered.length ? [...builtin, ...registered] : builtin;
+}
+/**
+ * The deduplicated catalog of config descriptors contributed across a set of agent
+ * kinds (e.g. all the kinds used by a workspace's pipelines), keyed by descriptor
+ * id (first contribution wins). This is what the workspace snapshot carries.
+ */
+export function configContributionCatalog(kinds) {
+    const byId = new Map();
+    for (const kind of kinds) {
+        for (const descriptor of configContributionsFor(kind)) {
+            if (!byId.has(descriptor.id))
+                byId.set(descriptor.id, descriptor);
+        }
+    }
+    return [...byId.values()];
+}
+//# sourceMappingURL=configs.js.map

package/dist/agents/kinds/configs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configs.js","sourceRoot":"","sources":["../../../src/agents/kinds/configs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAA;AAE7D,6EAA6E;AAC7E,gFAAgF;AAChF,kFAAkF;AAClF,yFAAyF;AAEzF,yFAAyF;AACzF,MAAM,CAAC,MAAM,4BAA4B,GAAG,oBAAoB,CAAA;AAChE,6EAA6E;AAC7E,MAAM,CAAC,MAAM,+BAA+B,GAAG,sBAAsB,CAAA;AAErE,MAAM,4BAA4B,GAAwD;IACxF,MAAM,EAAE;QACN;YACE,EAAE,EAAE,4BAA4B;YAChC,SAAS,EAAE,QAAQ;YACnB,KAAK,EAAE,kBAAkB;YACzB,WAAW,EACT,yJAAyJ;YAC3J,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE;gBACP,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,uBAAuB,EAAE;gBACtD,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,8BAA8B,EAAE;aAC1D;YACD,6EAA6E;YAC7E,+EAA+E;YAC/E,OAAO,EAAE,WAAW;SACrB;KACF;IACD,UAAU,EAAE;QACV;YACE,EAAE,EAAE,+BAA+B;YACnC,SAAS,EAAE,YAAY;YACvB,KAAK,EAAE,sBAAsB;YAC7B,WAAW,EACT,oIAAoI;YACtI,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE;gBACP,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,6BAA6B,EAAE;gBACrD,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,uBAAuB,EAAE;aACvD;YACD,OAAO,EAAE,IAAI;SACd;KACF;CACF,CAAA;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAe;IACpD,MAAM,OAAO,GAAG,4BAA4B,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;IACxD,MAAM,UAAU,GAAG,6BAA6B,CAAC,IAAI,CAAC,CAAA;IACtD,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;AAClE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAA0B;IAClE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAiC,CAAA;IACrD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,UAAU,IAAI,sBAAsB,CAAC,IAAI,CAAC,EAAE,CAAC;YACtD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,CAAA;QACnE,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAA;AAC3B,CAAC"}

package/dist/agents/kinds/read-only.d.ts

@@ -0,0 +1,13 @@
+import type { AgentKind } from '@cat-factory/kernel';
+/** Container agent kinds that operate read-only (explore + report; no edits/commits/PR). */
+export declare const READ_ONLY_AGENT_KINDS: Set<string>;
+/** Whether `kind` is a read-only container agent (runs the harness `/explore` path). */
+export declare function isReadOnlyAgentKind(kind: AgentKind): boolean;
+/**
+ * Appended to a read-only agent's system prompt so it never tries to edit, commit or
+ * open a PR — the prose report it returns is its sole deliverable. Centralised here
+ * (rather than repeated in each role prompt) so every read-only kind states the same
+ * guardrail exactly once.
+ */
+export declare const READ_ONLY_GUARDRAIL: string;
+//# sourceMappingURL=read-only.d.ts.map

package/dist/agents/kinds/read-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-only.d.ts","sourceRoot":"","sources":["../../../src/agents/kinds/read-only.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAkBpD,4FAA4F;AAC5F,eAAO,MAAM,qBAAqB,aAAiE,CAAA;AAEnG,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAIiB,CAAA"}

package/dist/agents/kinds/read-only.js

@@ -0,0 +1,32 @@
+// Read-only container agents. Some agent kinds need a real checkout to do their
+// work but only ever READ it: they clone the repo, explore it, and return a prose
+// report/proposal — making no edits, no commits and opening no pull request. They
+// run through the harness `/explore` endpoint (not `/run`), where an edit-free run
+// is the expected, correct outcome rather than an "implementation produced no
+// changes" failure, and where no work branch or PR is created.
+//
+// Today that is the `architect` (proposes a design after reading the existing code,
+// whose prose proposal feeds the human gate / architect-companion) and the tech-debt
+// `analysis` agent (audits the repo and emits a prioritized report). Both share the
+// single reusable read-only execution path (see ContainerAgentExecutor's explore
+// body + the harness `handleExplore`).
+// The `bug-investigator` joins this set: it clones the repo, reads the codebase from a
+// raw bug report and returns a prose enriched report (+ an optional, confidence-gated
+// hypothesis), making no edits — the same read-only `/explore` path as architect/analysis.
+/** Container agent kinds that operate read-only (explore + report; no edits/commits/PR). */
+export const READ_ONLY_AGENT_KINDS = new Set(['architect', 'analysis', 'bug-investigator']);
+/** Whether `kind` is a read-only container agent (runs the harness `/explore` path). */
+export function isReadOnlyAgentKind(kind) {
+    return READ_ONLY_AGENT_KINDS.has(kind);
+}
+/**
+ * Appended to a read-only agent's system prompt so it never tries to edit, commit or
+ * open a PR — the prose report it returns is its sole deliverable. Centralised here
+ * (rather than repeated in each role prompt) so every read-only kind states the same
+ * guardrail exactly once.
+ */
+export const READ_ONLY_GUARDRAIL = 'IMPORTANT — this is a READ-ONLY exploration: you may read and inspect any file in ' +
+    'the repository, but you MUST NOT modify, create or delete files, run commands that ' +
+    'change the repository, commit, or open a pull request. Your written report is the ' +
+    'only deliverable; return it as your response.';
+//# sourceMappingURL=read-only.js.map

package/dist/agents/kinds/read-only.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-only.js","sourceRoot":"","sources":["../../../src/agents/kinds/read-only.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,kFAAkF;AAClF,kFAAkF;AAClF,mFAAmF;AACnF,8EAA8E;AAC9E,+DAA+D;AAC/D,EAAE;AACF,oFAAoF;AACpF,qFAAqF;AACrF,oFAAoF;AACpF,iFAAiF;AACjF,uCAAuC;AAEvC,uFAAuF;AACvF,sFAAsF;AACtF,2FAA2F;AAC3F,4FAA4F;AAC5F,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAS,CAAC,WAAW,EAAE,UAAU,EAAE,kBAAkB,CAAC,CAAC,CAAA;AAEnG,wFAAwF;AACxF,MAAM,UAAU,mBAAmB,CAAC,IAAe;IACjD,OAAO,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAC9B,oFAAoF;IACpF,qFAAqF;IACrF,oFAAoF;IACpF,+CAA+C,CAAA"}

package/dist/agents/kinds/registry.d.ts

@@ -0,0 +1,70 @@
+import type { AgentConfigDescriptor, AgentKind, AgentRunContext } from '@cat-factory/kernel';
+import type { AgentTrait } from './traits.js';
+export interface AgentKindDefinition {
+    /** The free-form agent-kind id used in pipelines and steps (e.g. `security-auditor`). */
+    kind: AgentKind;
+    /**
+     * The system prompt (role) for this kind. A function form receives the kind id so a
+     * single definition object can serve a family of related kinds.
+     */
+    systemPrompt: string | ((kind: AgentKind) => string);
+    /**
+     * Optional custom user-prompt builder. When omitted the kind uses the generic user
+     * prompt (block context + prior pipeline outputs), exactly like any other
+     * non-standard-phase kind. Human revision feedback is appended automatically.
+     */
+    userPrompt?: (context: AgentRunContext) => string;
+    /**
+     * When true this kind needs a real checkout (clone/edit/commit/PR) and must run in a
+     * container rather than as a one-shot inline LLM call — see the Worker's
+     * `CompositeAgentExecutor`. Defaults to false (an inline LLM agent). NOTE: a container
+     * kind ALSO needs harness support for its dispatch endpoint; inline kinds work
+     * end-to-end with no harness changes.
+     */
+    requiresContainer?: boolean;
+    /**
+     * Optional one-clause reason this kind should reach for web search, phrased to
+     * complete "Use it mainly to …" (e.g. "verify the vendor's current API contract
+     * before generating a client"). When web search is enabled for the deployment, this
+     * is folded into the kind's web-search guidance so a proprietary kind gets a nudge
+     * tailored to its job — without the shared library needing to know the kind exists.
+     * Omitted ⇒ the generic "verify a fact that changes" hint. See `webResearchGuidanceFor`.
+     */
+    webResearchHint?: string;
+    /**
+     * Task-level configuration parameters this kind contributes (see the agent-config
+     * contracts). When a pipeline that includes this kind is selected for a task, these
+     * descriptors are surfaced on task creation + the inspector, editable until the
+     * kind's step starts. Each descriptor's `agentKind` should match this `kind` so the
+     * freeze targets the right step. Omitted ⇒ the kind contributes no config.
+     */
+    configContributions?: AgentConfigDescriptor[];
+    /**
+     * Capability traits this kind carries (see ./traits). `code-aware` makes the engine
+     * fold the running service's selected best-practice fragments into the agent's prompt;
+     * `spec-aware` appends the in-repo-spec reading guidance. Deployments can also assign
+     * their own traits registered via `registerAgentTrait`. Omitted ⇒ no traits.
+     */
+    traits?: AgentTrait[];
+}
+/** Register a custom agent kind. A later registration of the same id replaces the earlier one. */
+export declare function registerAgentKind(definition: AgentKindDefinition): void;
+/** Register several custom agent kinds at once. */
+export declare function registerAgentKinds(definitions: Iterable<AgentKindDefinition>): void;
+/** The registered definition for a kind, or undefined for built-in / unregistered kinds. */
+export declare function registeredAgentKind(kind: AgentKind): AgentKindDefinition | undefined;
+/** All registered custom agent kinds (registration order). */
+export declare function registeredAgentKinds(): AgentKindDefinition[];
+/** Whether a registered kind asked to run in a container. False for built-in / unregistered kinds. */
+export declare function registeredKindRequiresContainer(kind: AgentKind): boolean;
+/** Drop all registered kinds. Intended for tests that exercise registration. */
+export declare function clearRegisteredAgentKinds(): void;
+/** A registered kind's system prompt, or undefined when the kind is not registered. */
+export declare function registeredSystemPrompt(kind: AgentKind): string | undefined;
+/** A registered kind's user prompt, or undefined when the kind is not registered / has no builder. */
+export declare function registeredUserPrompt(context: AgentRunContext): string | undefined;
+/** A registered kind's web-research hint, or undefined when unregistered / not supplied. */
+export declare function registeredWebResearchHint(kind: AgentKind): string | undefined;
+/** A registered kind's contributed config descriptors, or an empty array when none. */
+export declare function registeredConfigContributions(kind: AgentKind): AgentConfigDescriptor[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/agents/kinds/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/agents/kinds/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAC5F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAY7C,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,IAAI,EAAE,SAAS,CAAA;IACf;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC,CAAA;IACpD;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,MAAM,CAAA;IACjD;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,qBAAqB,EAAE,CAAA;IAC7C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,EAAE,CAAA;CACtB;AAOD,kGAAkG;AAClG,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAEvE;AAED,mDAAmD;AACnD,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,QAAQ,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAEnF;AAED,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,mBAAmB,GAAG,SAAS,CAEpF;AAED,8DAA8D;AAC9D,wBAAgB,oBAAoB,IAAI,mBAAmB,EAAE,CAE5D;AAED,sGAAsG;AACtG,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAExE;AAED,gFAAgF;AAChF,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAM1E;AAED,sGAAsG;AACtG,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAEjF;AAED,4FAA4F;AAC5F,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAE7E;AAED,uFAAuF;AACvF,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,SAAS,GAAG,qBAAqB,EAAE,CAEtF"}

package/dist/agents/kinds/registry.js

@@ -0,0 +1,51 @@
+// Process-wide registry, mirroring the Worker's model-provider registry. Registration
+// is a startup side effect read by every prompt build / routing decision, so the extra
+// kinds reach all paths — HTTP requests, the durable driver and the cron sweeper.
+const registry = new Map();
+/** Register a custom agent kind. A later registration of the same id replaces the earlier one. */
+export function registerAgentKind(definition) {
+    registry.set(definition.kind, definition);
+}
+/** Register several custom agent kinds at once. */
+export function registerAgentKinds(definitions) {
+    for (const definition of definitions)
+        registerAgentKind(definition);
+}
+/** The registered definition for a kind, or undefined for built-in / unregistered kinds. */
+export function registeredAgentKind(kind) {
+    return registry.get(kind);
+}
+/** All registered custom agent kinds (registration order). */
+export function registeredAgentKinds() {
+    return [...registry.values()];
+}
+/** Whether a registered kind asked to run in a container. False for built-in / unregistered kinds. */
+export function registeredKindRequiresContainer(kind) {
+    return registry.get(kind)?.requiresContainer === true;
+}
+/** Drop all registered kinds. Intended for tests that exercise registration. */
+export function clearRegisteredAgentKinds() {
+    registry.clear();
+}
+/** A registered kind's system prompt, or undefined when the kind is not registered. */
+export function registeredSystemPrompt(kind) {
+    const definition = registry.get(kind);
+    if (!definition)
+        return undefined;
+    return typeof definition.systemPrompt === 'function'
+        ? definition.systemPrompt(kind)
+        : definition.systemPrompt;
+}
+/** A registered kind's user prompt, or undefined when the kind is not registered / has no builder. */
+export function registeredUserPrompt(context) {
+    return registry.get(context.agentKind)?.userPrompt?.(context);
+}
+/** A registered kind's web-research hint, or undefined when unregistered / not supplied. */
+export function registeredWebResearchHint(kind) {
+    return registry.get(kind)?.webResearchHint;
+}
+/** A registered kind's contributed config descriptors, or an empty array when none. */
+export function registeredConfigContributions(kind) {
+    return registry.get(kind)?.configContributions ?? [];
+}
+//# sourceMappingURL=registry.js.map

package/dist/agents/kinds/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/agents/kinds/registry.ts"],"names":[],"mappings":"AA6DA,sFAAsF;AACtF,uFAAuF;AACvF,kFAAkF;AAClF,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA+B,CAAA;AAEvD,kGAAkG;AAClG,MAAM,UAAU,iBAAiB,CAAC,UAA+B;IAC/D,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;AAC3C,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,kBAAkB,CAAC,WAA0C;IAC3E,KAAK,MAAM,UAAU,IAAI,WAAW;QAAE,iBAAiB,CAAC,UAAU,CAAC,CAAA;AACrE,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,mBAAmB,CAAC,IAAe;IACjD,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC3B,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,oBAAoB;IAClC,OAAO,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;AAC/B,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,+BAA+B,CAAC,IAAe;IAC7D,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,iBAAiB,KAAK,IAAI,CAAA;AACvD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,yBAAyB;IACvC,QAAQ,CAAC,KAAK,EAAE,CAAA;AAClB,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,sBAAsB,CAAC,IAAe;IACpD,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACrC,IAAI,CAAC,UAAU;QAAE,OAAO,SAAS,CAAA;IACjC,OAAO,OAAO,UAAU,CAAC,YAAY,KAAK,UAAU;QAClD,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC;QAC/B,CAAC,CAAC,UAAU,CAAC,YAAY,CAAA;AAC7B,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,oBAAoB,CAAC,OAAwB;IAC3D,OAAO,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,CAAC,OAAO,CAAC,CAAA;AAC/D,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,yBAAyB,CAAC,IAAe;IACvD,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,eAAe,CAAA;AAC5C,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,6BAA6B,CAAC,IAAe;IAC3D,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,mBAAmB,IAAI,EAAE,CAAA;AACtD,CAAC"}

package/dist/agents/kinds/traits.d.ts

@@ -0,0 +1,60 @@
+import type { AgentKind } from '@cat-factory/kernel';
+/** A trait id. Free-form so deployments can define their own beyond the standard two. */
+export type AgentTrait = string;
+/**
+ * Code-aware kinds read and/or change the service's code. The service's selected
+ * best-practice / guideline fragments (Node, Fastify, performance, …) are folded into
+ * their system prompt by the execution engine.
+ */
+export declare const CODE_AWARE_TRAIT: AgentTrait;
+/**
+ * Spec-aware kinds are told to read the in-repo `spec/` artifact (the prescriptive
+ * service specification) and how to interpret it. The instruction is appended to their
+ * system prompt via {@link traitGuidanceFor}.
+ */
+export declare const SPEC_AWARE_TRAIT: AgentTrait;
+/** The guidance appended to a spec-aware kind's system prompt — explains the spec format. */
+export declare const SPEC_AWARE_GUIDANCE: string;
+/**
+ * Built-in trait assignment per agent kind.
+ *  - `code-aware`: the kinds that read/modify the service's code, so the service's
+ *    best-practice fragments are relevant to them.
+ *  - `spec-aware`: every code-touching kind (anything that clones and reads the repo),
+ *    so each is pointed at the in-repo spec. The `spec-writer` is intentionally absent —
+ *    it AUTHORS the spec rather than consuming it.
+ */
+export declare const STANDARD_AGENT_TRAITS: Partial<Record<AgentKind, AgentTrait[]>>;
+/** Definition of a (custom) trait: its id and optional system-prompt guidance. */
+export interface AgentTraitDefinition {
+    /** The trait id used in `STANDARD_AGENT_TRAITS` / `AgentKindDefinition.traits`. */
+    id: AgentTrait;
+    /**
+     * Guidance folded into the system prompt of every kind carrying this trait. A function
+     * form receives the kind id. Omit for a pure marker trait whose effect lives in the
+     * engine (like `code-aware`).
+     */
+    guidance?: string | ((kind: AgentKind) => string);
+}
+/** Assign extra capability traits to an (existing) agent kind. Additive; idempotent per trait. */
+export declare function assignAgentTraits(kind: AgentKind, traits: Iterable<AgentTrait>): void;
+/** Drop all extra trait assignments. Intended for tests that exercise assignment. */
+export declare function clearAssignedAgentTraits(): void;
+/** Register a custom trait definition. A later registration of the same id replaces it. */
+export declare function registerAgentTrait(definition: AgentTraitDefinition): void;
+/** Register several custom trait definitions at once. */
+export declare function registerAgentTraits(definitions: Iterable<AgentTraitDefinition>): void;
+/** The definition for a trait id, or undefined when it is a pure marker / unregistered. */
+export declare function registeredAgentTrait(id: AgentTrait): AgentTraitDefinition | undefined;
+/** Drop all registered (custom) traits. Intended for tests; standard traits re-register below. */
+export declare function clearRegisteredAgentTraits(): void;
+/** The traits a kind carries: its built-in set unioned with a registered custom kind's. */
+export declare function traitsFor(kind: AgentKind): Set<AgentTrait>;
+/** Whether `kind` carries `trait`. */
+export declare function hasTrait(kind: AgentKind, trait: AgentTrait): boolean;
+/**
+ * The guidance lines contributed by the traits a kind carries, in trait order. Folded
+ * into the kind's system prompt by `systemPromptFor`. Marker traits (no guidance, e.g.
+ * `code-aware`) contribute nothing here.
+ */
+export declare function traitGuidanceFor(kind: AgentKind): string[];
+//# sourceMappingURL=traits.d.ts.map

package/dist/agents/kinds/traits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traits.d.ts","sourceRoot":"","sources":["../../../src/agents/kinds/traits.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAapD,yFAAyF;AACzF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAA;AAE/B;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAAyB,CAAA;AAExD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAAyB,CAAA;AAExD,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,QAOpB,CAAA;AAEZ;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC,CAkB1E,CAAA;AAED,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,EAAE,EAAE,UAAU,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC,CAAA;CAClD;AAaD,kGAAkG;AAClG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,CAIrF;AAED,qFAAqF;AACrF,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,oBAAoB,GAAG,IAAI,CAEzE;AAED,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAErF;AAED,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,GAAG,oBAAoB,GAAG,SAAS,CAErF;AAED,kGAAkG;AAClG,wBAAgB,0BAA0B,IAAI,IAAI,CAGjD;AAED,2FAA2F;AAC3F,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,GAAG,CAAC,UAAU,CAAC,CAK1D;AAED,sCAAsC;AACtC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,EAAE,CAQ1D"}

package/dist/agents/kinds/traits.js

@@ -0,0 +1,123 @@
+import { SPEC_FEATURES_DIR, SPEC_JSON_PATH, SPEC_OVERVIEW_PATH, SPEC_RULES_PATH, } from '@cat-factory/contracts';
+import { registeredAgentKind } from './registry.js';
+/**
+ * Code-aware kinds read and/or change the service's code. The service's selected
+ * best-practice / guideline fragments (Node, Fastify, performance, …) are folded into
+ * their system prompt by the execution engine.
+ */
+export const CODE_AWARE_TRAIT = 'code-aware';
+/**
+ * Spec-aware kinds are told to read the in-repo `spec/` artifact (the prescriptive
+ * service specification) and how to interpret it. The instruction is appended to their
+ * system prompt via {@link traitGuidanceFor}.
+ */
+export const SPEC_AWARE_TRAIT = 'spec-aware';
+/** The guidance appended to a spec-aware kind's system prompt — explains the spec format. */
+export const SPEC_AWARE_GUIDANCE = [
+    `This repository may contain a prescriptive SPECIFICATION for the service under the \`spec/\` directory — the source of truth for what the service must do. When it is present, read it before doing the work:`,
+    `- \`${SPEC_OVERVIEW_PATH}\` first, for the high-level product intent.`,
+    `- \`${SPEC_RULES_PATH}\` for cross-cutting domain rules, invariants and constraints.`,
+    `- \`${SPEC_FEATURES_DIR}/*.feature\` for the Gherkin (Given/When/Then) acceptance scenarios.`,
+    `- \`${SPEC_JSON_PATH}\` is the canonical machine-readable tree the markdown/feature files are rendered from; consult it when you need exact detail.`,
+    `Treat the spec as authoritative for required behaviour: make your change satisfy it, and if your change conflicts with the spec, follow the spec or call out the discrepancy rather than silently diverging.`,
+].join('\n');
+/**
+ * Built-in trait assignment per agent kind.
+ *  - `code-aware`: the kinds that read/modify the service's code, so the service's
+ *    best-practice fragments are relevant to them.
+ *  - `spec-aware`: every code-touching kind (anything that clones and reads the repo),
+ *    so each is pointed at the in-repo spec. The `spec-writer` is intentionally absent —
+ *    it AUTHORS the spec rather than consuming it.
+ */
+export const STANDARD_AGENT_TRAITS = {
+    architect: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
+    coder: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
+    reviewer: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
+    'ci-fixer': [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
+    fixer: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
+    'conflict-resolver': [SPEC_AWARE_TRAIT],
+    tester: [SPEC_AWARE_TRAIT],
+    playwright: [SPEC_AWARE_TRAIT],
+    blueprints: [SPEC_AWARE_TRAIT],
+    'business-documenter': [SPEC_AWARE_TRAIT],
+    'business-reviewer': [SPEC_AWARE_TRAIT],
+    analysis: [SPEC_AWARE_TRAIT],
+    mocker: [SPEC_AWARE_TRAIT],
+    merger: [SPEC_AWARE_TRAIT],
+    // The on-call agent clones the released change and reads the code to correlate the diff
+    // with the regression evidence, so it gets the service's best-practice + spec context.
+    'on-call': [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
+};
+// Process-wide trait registry, mirroring the agent-kind / model-provider registries.
+const traitRegistry = new Map();
+// Extra trait ASSIGNMENTS registered by a deployment/plugin at startup — e.g. the
+// optional `@cat-factory/consensus` package marking which built-in kinds are eligible
+// for a consensus strategy (`specialist-panel-capable`, …). Distinct from a kind's
+// built-in STANDARD_AGENT_TRAITS and from a registered custom kind's own `traits`:
+// this seam adds traits to an EXISTING kind without redefining its prompt. Unioned in
+// {@link traitsFor}. Mirrors the registry seams above.
+const assignedTraits = new Map();
+/** Assign extra capability traits to an (existing) agent kind. Additive; idempotent per trait. */
+export function assignAgentTraits(kind, traits) {
+    const set = assignedTraits.get(kind) ?? new Set();
+    for (const trait of traits)
+        set.add(trait);
+    assignedTraits.set(kind, set);
+}
+/** Drop all extra trait assignments. Intended for tests that exercise assignment. */
+export function clearAssignedAgentTraits() {
+    assignedTraits.clear();
+}
+/** Register a custom trait definition. A later registration of the same id replaces it. */
+export function registerAgentTrait(definition) {
+    traitRegistry.set(definition.id, definition);
+}
+/** Register several custom trait definitions at once. */
+export function registerAgentTraits(definitions) {
+    for (const definition of definitions)
+        registerAgentTrait(definition);
+}
+/** The definition for a trait id, or undefined when it is a pure marker / unregistered. */
+export function registeredAgentTrait(id) {
+    return traitRegistry.get(id);
+}
+/** Drop all registered (custom) traits. Intended for tests; standard traits re-register below. */
+export function clearRegisteredAgentTraits() {
+    traitRegistry.clear();
+    registerStandardTraits();
+}
+/** The traits a kind carries: its built-in set unioned with a registered custom kind's. */
+export function traitsFor(kind) {
+    const traits = new Set(STANDARD_AGENT_TRAITS[kind] ?? []);
+    for (const trait of registeredAgentKind(kind)?.traits ?? [])
+        traits.add(trait);
+    for (const trait of assignedTraits.get(kind) ?? [])
+        traits.add(trait);
+    return traits;
+}
+/** Whether `kind` carries `trait`. */
+export function hasTrait(kind, trait) {
+    return traitsFor(kind).has(trait);
+}
+/**
+ * The guidance lines contributed by the traits a kind carries, in trait order. Folded
+ * into the kind's system prompt by `systemPromptFor`. Marker traits (no guidance, e.g.
+ * `code-aware`) contribute nothing here.
+ */
+export function traitGuidanceFor(kind) {
+    const lines = [];
+    for (const trait of traitsFor(kind)) {
+        const guidance = traitRegistry.get(trait)?.guidance;
+        if (!guidance)
+            continue;
+        lines.push(typeof guidance === 'function' ? guidance(kind) : guidance);
+    }
+    return lines;
+}
+/** Register the two standard traits' definitions (spec-aware carries guidance). */
+function registerStandardTraits() {
+    registerAgentTrait({ id: CODE_AWARE_TRAIT });
+    registerAgentTrait({ id: SPEC_AWARE_TRAIT, guidance: SPEC_AWARE_GUIDANCE });
+}
+registerStandardTraits();
+//# sourceMappingURL=traits.js.map

package/dist/agents/kinds/traits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traits.js","sourceRoot":"","sources":["../../../src/agents/kinds/traits.ts"],"names":[],"mappings":"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"}