@kernloop/faculty-workforce 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Zujkowski and Kernloop contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/decompose.d.ts

@@ -0,0 +1,77 @@
+/**
+ * PM plan decomposition — the MECHANICAL half (spec §5.4; CLM-0041).
+ *
+ * The split: a PM model WRITES the subtask specs upstream, through an
+ * invoke function the composition root binds to the kernel adapters; this
+ * function never calls a model. It takes those specs as plain input and
+ * enforces the contract: schema validity, id/parent/overlay derivation,
+ * ceiling clamping, and the budget-sum invariant. The invariant is therefore
+ * unit-testable without any model in the loop.
+ */
+import { type TaskContract } from '@kernloop/contracts';
+import { z } from 'zod';
+/**
+ * One subtask as proposed by the PM. Identity, overlay, and authority are
+ * NOT inputs — they are derived from the parent here, so a PM cannot grant
+ * what the parent does not hold.
+ */
+export declare const SubtaskSpecSchema: z.ZodObject<{
+    goal: z.ZodString;
+    constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    budget: z.ZodObject<{
+        tokens: z.ZodNumber;
+        usd: z.ZodNumber;
+        wallClockMin: z.ZodNumber;
+    }, z.core.$strict>;
+    evidence: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            test: "test";
+            ci: "ci";
+            doc: "doc";
+            eval: "eval";
+        }>;
+        ref: z.ZodString;
+    }, z.core.$strict>>>;
+    definitionOfDone: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        command: z.ZodString;
+    }, z.core.$strict>>>;
+    assignTo: z.ZodEnum<{
+        pm: "pm";
+        coder: "coder";
+        reviewer: "reviewer";
+        documenter: "documenter";
+        researcher: "researcher";
+    }>;
+}, z.core.$strict>;
+export type SubtaskSpec = z.infer<typeof SubtaskSpecSchema>;
+/** Input to {@link decomposePlan}. */
+export interface DecomposePlanInput {
+    parent: TaskContract;
+    subtasks: SubtaskSpec[];
+}
+/**
+ * Derive zod-valid child TaskContracts from a parent plus PM-proposed
+ * subtask specs, enforcing (CLM-0041):
+ *
+ * - BUDGET INVARIANT: child budgets sum within the parent's on each of
+ *   tokens, usd, and wallClockMin independently; any breach throws
+ *   {@link BudgetExceededError} naming the dimension and amounts. An exact
+ *   sum is within budget. Zero/negative child slices are rejected.
+ * - Identity: `child.id = parent.id + '.<n>'` (1-based input order),
+ *   `child.parent = parent.id`, `child.overlay = parent.overlay`.
+ * - Authority: `child.authorityCeiling = min(parent ceiling, 'suggest')`.
+ *   Children NEVER exceed the parent ceiling, and agent work is generative,
+ *   so it is additionally clamped at the `suggest` entry tier (spec §3.2);
+ *   the spec is silent on per-child explicit ceilings, so none is accepted
+ *   — a PM cannot grant authority (narrowest reading, recorded).
+ * - Constraints: parent constraints bind children, so each child inherits
+ *   them, followed by the subtask's own constraints, followed by a routing
+ *   constraint `assign:agent.<template>` naming the assigned template's
+ *   capability.
+ *
+ * Fan-out parallelism is bounded by the parent budget as a consequence: the
+ * kernel meters, the PM allocates (spec §5.4).
+ */
+export declare function decomposePlan(input: DecomposePlanInput): TaskContract[];
+//# sourceMappingURL=decompose.d.ts.map

package/dist/decompose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decompose.d.ts","sourceRoot":"","sources":["../src/decompose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAkC,KAAK,YAAY,EAAa,MAAM,qBAAqB,CAAC;AACnG,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQ5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAqBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,YAAY,EAAE,CAyBvE"}

package/dist/decompose.js

@@ -0,0 +1,109 @@
+/**
+ * PM plan decomposition — the MECHANICAL half (spec §5.4; CLM-0041).
+ *
+ * The split: a PM model WRITES the subtask specs upstream, through an
+ * invoke function the composition root binds to the kernel adapters; this
+ * function never calls a model. It takes those specs as plain input and
+ * enforces the contract: schema validity, id/parent/overlay derivation,
+ * ceiling clamping, and the budget-sum invariant. The invariant is therefore
+ * unit-testable without any model in the loop.
+ */
+import { TaskContractSchema, TierSchema } from '@kernloop/contracts';
+import { z } from 'zod';
+import { BudgetExceededError, InvalidParentError, InvalidSubtaskError } from './errors.js';
+import { SHIPPED_TEMPLATE_NAMES } from './templates.js';
+/** Authority ladder, lowest first (spec §3.2). */
+const TIER_ORDER = TierSchema.options;
+/** The lower of two tiers on the ladder. */
+function minTier(a, b) {
+    return TIER_ORDER.indexOf(a) <= TIER_ORDER.indexOf(b) ? a : b;
+}
+/**
+ * A child budget as the PM proposes it. Stricter than TaskContract's
+ * nonnegative budget: a zero or negative slice on any dimension is rejected
+ * — a child with nothing to spend is a stub, and stubs are forbidden.
+ */
+const SubtaskBudgetSchema = z.strictObject({
+    tokens: z.number().int().positive(),
+    usd: z.number().positive(),
+    wallClockMin: z.number().positive(),
+});
+/**
+ * One subtask as proposed by the PM. Identity, overlay, and authority are
+ * NOT inputs — they are derived from the parent here, so a PM cannot grant
+ * what the parent does not hold.
+ */
+export const SubtaskSpecSchema = z.strictObject({
+    goal: z.string().min(1),
+    constraints: z.array(z.string().min(1)).optional(),
+    budget: SubtaskBudgetSchema,
+    evidence: TaskContractSchema.shape.evidence.optional(),
+    definitionOfDone: TaskContractSchema.shape.definitionOfDone.optional(),
+    /** Shipped template name this child is assigned to (custom templates: P3, #177). */
+    assignTo: z.enum(SHIPPED_TEMPLATE_NAMES),
+});
+/** Parse one subtask spec, wrapping any schema failure as a typed error. */
+function parseSubtask(spec, index) {
+    const parsed = SubtaskSpecSchema.safeParse(spec);
+    if (!parsed.success) {
+        throw new InvalidSubtaskError(index, z.prettifyError(parsed.error));
+    }
+    return parsed.data;
+}
+/** Enforce sum(child) ≤ parent independently per budget dimension. */
+function checkBudgetInvariant(parent, subtasks) {
+    for (const dimension of ['tokens', 'usd', 'wallClockMin']) {
+        const childSum = subtasks.reduce((sum, s) => sum + s.budget[dimension], 0);
+        if (childSum > parent.budget[dimension]) {
+            throw new BudgetExceededError(dimension, parent.budget[dimension], childSum);
+        }
+    }
+}
+/**
+ * Derive zod-valid child TaskContracts from a parent plus PM-proposed
+ * subtask specs, enforcing (CLM-0041):
+ *
+ * - BUDGET INVARIANT: child budgets sum within the parent's on each of
+ *   tokens, usd, and wallClockMin independently; any breach throws
+ *   {@link BudgetExceededError} naming the dimension and amounts. An exact
+ *   sum is within budget. Zero/negative child slices are rejected.
+ * - Identity: `child.id = parent.id + '.<n>'` (1-based input order),
+ *   `child.parent = parent.id`, `child.overlay = parent.overlay`.
+ * - Authority: `child.authorityCeiling = min(parent ceiling, 'suggest')`.
+ *   Children NEVER exceed the parent ceiling, and agent work is generative,
+ *   so it is additionally clamped at the `suggest` entry tier (spec §3.2);
+ *   the spec is silent on per-child explicit ceilings, so none is accepted
+ *   — a PM cannot grant authority (narrowest reading, recorded).
+ * - Constraints: parent constraints bind children, so each child inherits
+ *   them, followed by the subtask's own constraints, followed by a routing
+ *   constraint `assign:agent.<template>` naming the assigned template's
+ *   capability.
+ *
+ * Fan-out parallelism is bounded by the parent budget as a consequence: the
+ * kernel meters, the PM allocates (spec §5.4).
+ */
+export function decomposePlan(input) {
+    const parentResult = TaskContractSchema.safeParse(input.parent);
+    if (!parentResult.success) {
+        throw new InvalidParentError(z.prettifyError(parentResult.error));
+    }
+    const parent = parentResult.data;
+    const subtasks = input.subtasks.map((spec, i) => parseSubtask(spec, i));
+    checkBudgetInvariant(parent, subtasks);
+    return subtasks.map((spec, i) => TaskContractSchema.parse({
+        id: `${parent.id}.${i + 1}`,
+        parent: parent.id,
+        goal: spec.goal,
+        constraints: [
+            ...parent.constraints,
+            ...(spec.constraints ?? []),
+            `assign:agent.${spec.assignTo}`,
+        ],
+        budget: spec.budget,
+        evidence: spec.evidence ?? [],
+        definitionOfDone: spec.definitionOfDone ?? [],
+        authorityCeiling: minTier(parent.authorityCeiling, 'suggest'),
+        overlay: parent.overlay,
+    }));
+}
+//# sourceMappingURL=decompose.js.map

package/dist/decompose.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Typed errors thrown at the workforce faculty's boundaries. Callers
+ * discriminate on `name` or `instanceof` — never on message text.
+ */
+import type { TaskContract } from '@kernloop/contracts';
+/** The three independently-summed budget dimensions of a TaskContract. */
+export type BudgetDimension = keyof TaskContract['budget'];
+/**
+ * Thrown when the sum of child budgets exceeds the parent budget on any
+ * dimension (spec §5.4: child TaskContract budgets "must sum within the
+ * parent's"; CLM-0041). Carries the offending dimension and both amounts so
+ * the caller can report — or a PM can replan — without parsing text.
+ */
+export declare class BudgetExceededError extends Error {
+    readonly dimension: BudgetDimension;
+    readonly parentBudget: number;
+    readonly childSum: number;
+    constructor(dimension: BudgetDimension, parentBudget: number, childSum: number);
+}
+/**
+ * Thrown when a subtask spec is malformed for a reason other than the
+ * budget-sum invariant: schema violation, zero/negative budget dimension,
+ * or `assignTo` naming no shipped template.
+ */
+export declare class InvalidSubtaskError extends Error {
+    /** Zero-based index of the offending subtask in the input array. */
+    readonly index: number;
+    constructor(index: number, message: string);
+}
+/**
+ * Thrown when the parent contract handed to decomposePlan fails
+ * TaskContractSchema validation (charter: zod-validate at every contract
+ * boundary).
+ */
+export declare class InvalidParentError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;AAE3D;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,SAAS,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU/E;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK3C;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/errors.js

@@ -0,0 +1,45 @@
+/**
+ * Thrown when the sum of child budgets exceeds the parent budget on any
+ * dimension (spec §5.4: child TaskContract budgets "must sum within the
+ * parent's"; CLM-0041). Carries the offending dimension and both amounts so
+ * the caller can report — or a PM can replan — without parsing text.
+ */
+export class BudgetExceededError extends Error {
+    dimension;
+    parentBudget;
+    childSum;
+    constructor(dimension, parentBudget, childSum) {
+        super(`child budgets exceed parent on ${dimension}: ` +
+            `sum ${childSum} > parent ${parentBudget} (spec §5.4)`);
+        this.name = 'BudgetExceededError';
+        this.dimension = dimension;
+        this.parentBudget = parentBudget;
+        this.childSum = childSum;
+    }
+}
+/**
+ * Thrown when a subtask spec is malformed for a reason other than the
+ * budget-sum invariant: schema violation, zero/negative budget dimension,
+ * or `assignTo` naming no shipped template.
+ */
+export class InvalidSubtaskError extends Error {
+    /** Zero-based index of the offending subtask in the input array. */
+    index;
+    constructor(index, message) {
+        super(`subtask[${index}]: ${message}`);
+        this.name = 'InvalidSubtaskError';
+        this.index = index;
+    }
+}
+/**
+ * Thrown when the parent contract handed to decomposePlan fails
+ * TaskContractSchema validation (charter: zod-validate at every contract
+ * boundary).
+ */
+export class InvalidParentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidParentError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,SAAS,CAAkB;IAC3B,YAAY,CAAS;IACrB,QAAQ,CAAS;IAE1B,YAAY,SAA0B,EAAE,YAAoB,EAAE,QAAgB;QAC5E,KAAK,CACH,kCAAkC,SAAS,IAAI;YAC7C,OAAO,QAAQ,aAAa,YAAY,cAAc,CACzD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,oEAAoE;IAC3D,KAAK,CAAS;IAEvB,YAAY,KAAa,EAAE,OAAe;QACxC,KAAK,CAAC,WAAW,KAAK,MAAM,OAAO,EAAE,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @kernloop/faculty-workforce — Layer 2 workforce faculty (spec §5.4).
+ *
+ * Agents are configuration, not generation: five shipped templates (PM,
+ * Coder, Reviewer, Documenter, Researcher) instantiate as agentTemplate
+ * Manifests (CLM-0040), and PM plan decomposition is mechanically enforced
+ * under the budget-sum invariant (CLM-0041). This package contains no model
+ * calls — generative work happens through an invoke function injected by
+ * the composition root. It imports only @kernloop/contracts and external
+ * dependencies (constitutional rule 5).
+ */
+export { AgentTemplateSchema, MODEL_TIER_COST, SHIPPED_TEMPLATES, SHIPPED_TEMPLATE_NAMES, } from './templates.js';
+export type { AgentTemplate, ShippedTemplateName } from './templates.js';
+export { instantiateAgent, InstantiateOptionsSchema, WORKFORCE_VERSION } from './instantiate.js';
+export type { InstantiateOptions } from './instantiate.js';
+export { decomposePlan, SubtaskSpecSchema } from './decompose.js';
+export type { SubtaskSpec, DecomposePlanInput } from './decompose.js';
+export { BudgetExceededError, InvalidParentError, InvalidSubtaskError } from './errors.js';
+export type { BudgetDimension } from './errors.js';
+export { workforceManifest } from './manifest.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACjG,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAClE,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC3F,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @kernloop/faculty-workforce — Layer 2 workforce faculty (spec §5.4).
+ *
+ * Agents are configuration, not generation: five shipped templates (PM,
+ * Coder, Reviewer, Documenter, Researcher) instantiate as agentTemplate
+ * Manifests (CLM-0040), and PM plan decomposition is mechanically enforced
+ * under the budget-sum invariant (CLM-0041). This package contains no model
+ * calls — generative work happens through an invoke function injected by
+ * the composition root. It imports only @kernloop/contracts and external
+ * dependencies (constitutional rule 5).
+ */
+export { AgentTemplateSchema, MODEL_TIER_COST, SHIPPED_TEMPLATES, SHIPPED_TEMPLATE_NAMES, } from './templates.js';
+export { instantiateAgent, InstantiateOptionsSchema, WORKFORCE_VERSION } from './instantiate.js';
+export { decomposePlan, SubtaskSpecSchema } from './decompose.js';
+export { BudgetExceededError, InvalidParentError, InvalidSubtaskError } from './errors.js';
+export { workforceManifest } from './manifest.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEjG,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAElE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE3F,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/instantiate.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Template → Manifest instantiation (spec §5.4; CLM-0040). Purely
+ * mechanical: validate the template, stamp it into a `agentTemplate`
+ * Manifest, and parse the result through ManifestSchema so an invalid
+ * instantiation fails fast.
+ */
+import { type Manifest } from '@kernloop/contracts';
+import { z } from 'zod';
+import { type AgentTemplate } from './templates.js';
+/** Version stamped on every instantiated agent manifest. */
+export declare const WORKFORCE_VERSION = "0.1.0";
+/** Options for {@link instantiateAgent}. */
+export declare const InstantiateOptionsSchema: z.ZodObject<{
+    overlay: z.ZodString;
+    overrides: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        rolePrompt: z.ZodOptional<z.ZodString>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        model: z.ZodOptional<z.ZodObject<{
+            tier: z.ZodDefault<z.ZodEnum<{
+                frontier: "frontier";
+                large: "large";
+                medium: "medium";
+                small: "small";
+            }>>;
+            effort: z.ZodDefault<z.ZodEnum<{
+                medium: "medium";
+                low: "low";
+                high: "high";
+                xhigh: "xhigh";
+            }>>;
+            capabilities: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                toolUse: "toolUse";
+                vision: "vision";
+                longContext: "longContext";
+                jsonMode: "jsonMode";
+            }>>>;
+        }, z.core.$strict>>;
+        budgetShare: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type InstantiateOptions = z.infer<typeof InstantiateOptionsSchema>;
+/**
+ * Instantiate an agent template as a Manifest (kind `agentTemplate`).
+ *
+ * - `tier` is always `suggest`: templates are generative components and
+ *   anything generative enters at `suggest` (spec §3.2, §5.4); promotion is
+ *   never a default.
+ * - `maturity` is `stable` only for an unmodified shipped template (PM,
+ *   Coder, Reviewer, Documenter, Researcher); any custom template — composed
+ *   from existing ones via `overrides` or supplied whole — is
+ *   `experimental` until ratified into the library.
+ * - `claims` is empty: an instantiated agent is a runtime configuration
+ *   record, not a repo capability; the claim backing this machinery
+ *   (CLM-0040) lives on the faculty manifest.
+ * - the model `tier`/`effort` and `overlay` are recorded in the capability
+ *   description; the cost profile reflects the tier and the `model`
+ *   requirement is stamped onto the manifest (spec §8.4). Binding the tier to
+ *   a concrete model id is the composition root's concern.
+ *
+ * DEFERRED (P3, #178): the spec grants the PM authority to compose bespoke
+ * specialists at `enforce`. Per the P2 design-notes ratification point, that
+ * enforce grant is deferred to P3 evidence — there is deliberately no
+ * enforce path here, and composed templates come out `suggest`/
+ * `experimental` like any other custom template.
+ */
+export declare function instantiateAgent(template: AgentTemplate, options: InstantiateOptions): Manifest;
+//# sourceMappingURL=instantiate.d.ts.map

package/dist/instantiate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instantiate.d.ts","sourceRoot":"","sources":["../src/instantiate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAExB,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,4CAA4C;AAC5C,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAUnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAQ1E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,kBAAkB,GAAG,QAAQ,CA6B/F"}

package/dist/instantiate.js

@@ -0,0 +1,81 @@
+/**
+ * Template → Manifest instantiation (spec §5.4; CLM-0040). Purely
+ * mechanical: validate the template, stamp it into a `agentTemplate`
+ * Manifest, and parse the result through ManifestSchema so an invalid
+ * instantiation fails fast.
+ */
+import { ManifestSchema } from '@kernloop/contracts';
+import { z } from 'zod';
+import { AgentTemplateSchema, MODEL_TIER_COST, SHIPPED_TEMPLATES, } from './templates.js';
+/** Version stamped on every instantiated agent manifest. */
+export const WORKFORCE_VERSION = '0.1.0';
+/** Options for {@link instantiateAgent}. */
+export const InstantiateOptionsSchema = z.strictObject({
+    /** Repo overlay id the agent serves (spec §7); recorded in the capability description. */
+    overlay: z.string().min(1),
+    /**
+     * Field overrides composing a CUSTOM template from an existing one. Any
+     * override — even an identity rewrite — makes the result custom:
+     * `experimental` maturity at `suggest` tier, ratified into the library
+     * later (spec §5.4).
+     */
+    overrides: AgentTemplateSchema.partial().optional(),
+});
+/** True iff `t` is byte-for-byte one of the five shipped templates. */
+function isShipped(t) {
+    const shipped = SHIPPED_TEMPLATES[t.name];
+    return shipped !== undefined && JSON.stringify(shipped) === JSON.stringify(t);
+}
+/**
+ * Instantiate an agent template as a Manifest (kind `agentTemplate`).
+ *
+ * - `tier` is always `suggest`: templates are generative components and
+ *   anything generative enters at `suggest` (spec §3.2, §5.4); promotion is
+ *   never a default.
+ * - `maturity` is `stable` only for an unmodified shipped template (PM,
+ *   Coder, Reviewer, Documenter, Researcher); any custom template — composed
+ *   from existing ones via `overrides` or supplied whole — is
+ *   `experimental` until ratified into the library.
+ * - `claims` is empty: an instantiated agent is a runtime configuration
+ *   record, not a repo capability; the claim backing this machinery
+ *   (CLM-0040) lives on the faculty manifest.
+ * - the model `tier`/`effort` and `overlay` are recorded in the capability
+ *   description; the cost profile reflects the tier and the `model`
+ *   requirement is stamped onto the manifest (spec §8.4). Binding the tier to
+ *   a concrete model id is the composition root's concern.
+ *
+ * DEFERRED (P3, #178): the spec grants the PM authority to compose bespoke
+ * specialists at `enforce`. Per the P2 design-notes ratification point, that
+ * enforce grant is deferred to P3 evidence — there is deliberately no
+ * enforce path here, and composed templates come out `suggest`/
+ * `experimental` like any other custom template.
+ */
+export function instantiateAgent(template, options) {
+    const opts = InstantiateOptionsSchema.parse(options);
+    const base = AgentTemplateSchema.parse(template);
+    const effective = opts.overrides === undefined ? base : AgentTemplateSchema.parse({ ...base, ...opts.overrides });
+    const custom = opts.overrides !== undefined || !isShipped(effective);
+    return ManifestSchema.parse({
+        name: `workforce/${effective.name}`,
+        version: WORKFORCE_VERSION,
+        kind: 'agentTemplate',
+        capabilities: [
+            {
+                name: `agent.${effective.name}`,
+                description: `${effective.name} agent (${effective.model.tier} tier, ${effective.model.effort} effort, ` +
+                    `budget share ${effective.budgetShare}, skills: ${effective.skills.join(', ') || 'none'}) ` +
+                    `for overlay ${opts.overlay}`,
+            },
+        ],
+        contracts: {
+            consumes: ['TaskContract'],
+            emits: ['Outcome'],
+        },
+        cost: MODEL_TIER_COST[effective.model.tier],
+        tier: 'suggest',
+        claims: [],
+        maturity: custom ? 'experimental' : 'stable',
+        model: effective.model,
+    });
+}
+//# sourceMappingURL=instantiate.js.map

package/dist/instantiate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instantiate.js","sourceRoot":"","sources":["../src/instantiate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAiB,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,iBAAiB,GAElB,MAAM,gBAAgB,CAAC;AAExB,4DAA4D;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;AAEzC,4CAA4C;AAC5C,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,YAAY,CAAC;IACrD,0FAA0F;IAC1F,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B;;;;;OAKG;IACH,SAAS,EAAE,mBAAmB,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACpD,CAAC,CAAC;AAGH,uEAAuE;AACvE,SAAS,SAAS,CAAC,CAAgB;IACjC,MAAM,OAAO,GAAG,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC1C,OAAO,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAuB,EAAE,OAA2B;IACnF,MAAM,IAAI,GAAG,wBAAwB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACjD,MAAM,SAAS,GACb,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IAClG,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IACrE,OAAO,cAAc,CAAC,KAAK,CAAC;QAC1B,IAAI,EAAE,aAAa,SAAS,CAAC,IAAI,EAAE;QACnC,OAAO,EAAE,iBAAiB;QAC1B,IAAI,EAAE,eAAe;QACrB,YAAY,EAAE;YACZ;gBACE,IAAI,EAAE,SAAS,SAAS,CAAC,IAAI,EAAE;gBAC/B,WAAW,EACT,GAAG,SAAS,CAAC,IAAI,WAAW,SAAS,CAAC,KAAK,CAAC,IAAI,UAAU,SAAS,CAAC,KAAK,CAAC,MAAM,WAAW;oBAC3F,gBAAgB,SAAS,CAAC,WAAW,aAAa,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,IAAI;oBAC3F,eAAe,IAAI,CAAC,OAAO,EAAE;aAChC;SACF;QACD,SAAS,EAAE;YACT,QAAQ,EAAE,CAAC,cAAc,CAAC;YAC1B,KAAK,EAAE,CAAC,SAAS,CAAC;SACnB;QACD,IAAI,EAAE,eAAe,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC;QAC3C,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ;QAC5C,KAAK,EAAE,SAAS,CAAC,KAAK;KACvB,CAAC,CAAC;AACL,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The workforce faculty's registration record (spec §4, §5.4). Parsed
+ * through `ManifestSchema` at module load so an invalid manifest fails
+ * fast, not at registry time.
+ */
+import { type Manifest } from '@kernloop/contracts';
+/**
+ * The faculty-workforce registration manifest. Tier is `suggest` — the
+ * workforce stands behind the PM, a generative role, and anything
+ * generative enters at `suggest` (spec §3.2); promotion needs evidence +
+ * ratification. Consumes TaskContract (the parent plan) and emits
+ * TaskContract (the derived children). Cost is zero tokens/usd: template
+ * instantiation and decomposition enforcement are mechanical — the PM's
+ * generative work runs through the composition-root-injected invoke, where
+ * the adapters meter it.
+ */
+export declare const workforceManifest: Manifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpE;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,EAAE,QA0B9B,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,44 @@
+/**
+ * The workforce faculty's registration record (spec §4, §5.4). Parsed
+ * through `ManifestSchema` at module load so an invalid manifest fails
+ * fast, not at registry time.
+ */
+import { ManifestSchema } from '@kernloop/contracts';
+/**
+ * The faculty-workforce registration manifest. Tier is `suggest` — the
+ * workforce stands behind the PM, a generative role, and anything
+ * generative enters at `suggest` (spec §3.2); promotion needs evidence +
+ * ratification. Consumes TaskContract (the parent plan) and emits
+ * TaskContract (the derived children). Cost is zero tokens/usd: template
+ * instantiation and decomposition enforcement are mechanical — the PM's
+ * generative work runs through the composition-root-injected invoke, where
+ * the adapters meter it.
+ */
+export const workforceManifest = ManifestSchema.parse({
+    name: '@kernloop/faculty-workforce',
+    version: '0.1.0',
+    kind: 'faculty',
+    capabilities: [
+        {
+            name: 'workforce.instantiate',
+            description: 'Instantiate an agent template as an agentTemplate Manifest (spec §5.4)',
+        },
+        {
+            name: 'workforce.decompose',
+            description: 'Derive child TaskContracts from a parent plan under the budget-sum invariant',
+        },
+    ],
+    contracts: {
+        consumes: ['TaskContract'],
+        emits: ['TaskContract'],
+    },
+    cost: {
+        tokens: 0,
+        usd: 0,
+        latencyMs: 10,
+    },
+    tier: 'suggest',
+    claims: ['CLM-0040', 'CLM-0041'],
+    maturity: 'stable',
+});
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAiB,MAAM,qBAAqB,CAAC;AAEpE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAa,cAAc,CAAC,KAAK,CAAC;IAC9D,IAAI,EAAE,6BAA6B;IACnC,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,SAAS;IACf,YAAY,EAAE;QACZ;YACE,IAAI,EAAE,uBAAuB;YAC7B,WAAW,EAAE,wEAAwE;SACtF;QACD;YACE,IAAI,EAAE,qBAAqB;YAC3B,WAAW,EAAE,8EAA8E;SAC5F;KACF;IACD,SAAS,EAAE;QACT,QAAQ,EAAE,CAAC,cAAc,CAAC;QAC1B,KAAK,EAAE,CAAC,cAAc,CAAC;KACxB;IACD,IAAI,EAAE;QACJ,MAAM,EAAE,CAAC;QACT,GAAG,EAAE,CAAC;QACN,SAAS,EAAE,EAAE;KACd;IACD,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,EAAE,QAAQ;CACnB,CAAC,CAAC"}

package/dist/templates.d.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+/**
+ * One workforce agent template (spec §5.4): role prompt + skill set + model
+ * requirement + budget slice. `budgetShare` is the fraction of the parent
+ * task's budget this role may receive by default when the PM slices budgets —
+ * a default allocation hint, not a kernel-enforced ceiling (the kernel
+ * meters, the PM allocates).
+ *
+ * `model` is the role's two-axis {@link ModelRequirement} (spec §8.4): the
+ * model `tier` (frontier > large > medium > small) and reasoning `effort` the
+ * role demands. Mapping a tier+effort to a concrete model id + effort arg is a
+ * composition-root concern resolved through the kernel translation seam; this
+ * faculty only declares the requirement as configuration.
+ */
+export declare const AgentTemplateSchema: z.ZodObject<{
+    name: z.ZodString;
+    rolePrompt: z.ZodString;
+    skills: z.ZodArray<z.ZodString>;
+    model: z.ZodObject<{
+        tier: z.ZodDefault<z.ZodEnum<{
+            frontier: "frontier";
+            large: "large";
+            medium: "medium";
+            small: "small";
+        }>>;
+        effort: z.ZodDefault<z.ZodEnum<{
+            medium: "medium";
+            low: "low";
+            high: "high";
+            xhigh: "xhigh";
+        }>>;
+        capabilities: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            toolUse: "toolUse";
+            vision: "vision";
+            longContext: "longContext";
+            jsonMode: "jsonMode";
+        }>>>;
+    }, z.core.$strict>;
+    budgetShare: z.ZodNumber;
+}, z.core.$strict>;
+export type AgentTemplate = z.infer<typeof AgentTemplateSchema>;
+/**
+ * Expected cost profile per model tier, declared on instantiated manifests
+ * for router budget-matching (spec §3.1). Expectations, not meters — the
+ * kernel adapters meter actual spend per call. Effort is noted, not separately
+ * priced: a tier's row is the expectation at its default effort; raising
+ * effort raises realized tokens, which the per-call meters capture.
+ */
+export declare const MODEL_TIER_COST: {
+    readonly frontier: {
+        readonly tokens: 48000;
+        readonly usd: 0.8;
+        readonly latencyMs: 180000;
+    };
+    readonly large: {
+        readonly tokens: 32000;
+        readonly usd: 0.5;
+        readonly latencyMs: 120000;
+    };
+    readonly medium: {
+        readonly tokens: 16000;
+        readonly usd: 0.1;
+        readonly latencyMs: 60000;
+    };
+    readonly small: {
+        readonly tokens: 8000;
+        readonly usd: 0.02;
+        readonly latencyMs: 30000;
+    };
+};
+/**
+ * The five shipped templates (spec §5.4): PM, Coder, Reviewer, Documenter,
+ * Researcher. Research ships as a single Researcher template + the
+ * `research` skill pack — NOT a faculty (spec §5.8). Shipped templates are
+ * `stable`; anything else instantiates as `experimental` (see
+ * instantiateAgent). Tiers reflect each role's load (spec §8.4): the
+ * load-bearing generation roles (Coder, PM, Researcher) on `large` at high
+ * effort; the judging/writing roles (Reviewer, Documenter) on `medium`.
+ *
+ * ROUTING (honesty, #45/#200): in the canonical loop today only PM, Coder, and
+ * Researcher are routed (to the plan/decompose, implement, and research nodes),
+ * and child review runs as a separate advisory GATE (faculty-gates/review), NOT
+ * this Reviewer template. The Reviewer/Documenter templates are shipped
+ * specialists the runtime loop does NOT yet route to — a child's `assignTo`
+ * records the intended specialist as provenance, but every fan-out child is
+ * currently implemented by the Coder until specialist routing lands (#200).
+ */
+export declare const SHIPPED_TEMPLATES: Readonly<Record<string, AgentTemplate>>;
+/** Names of the five shipped templates, in spec §5.4 order. */
+export declare const SHIPPED_TEMPLATE_NAMES: readonly ["pm", "coder", "reviewer", "documenter", "researcher"];
+export type ShippedTemplateName = (typeof SHIPPED_TEMPLATE_NAMES)[number];
+//# sourceMappingURL=templates.d.ts.map

package/dist/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;kBAW9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;CAK8D,CAAC;AAQ3F;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAoDrE,CAAC;AAEF,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB,kEAMzB,CAAC;AACX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/templates.js

@@ -0,0 +1,124 @@
+/**
+ * Agent templates as DATA (spec §5.4: "configuration, not generation").
+ * An agent is a manifest instantiated from a template: role prompt + skill
+ * set + model requirement + budget slice. Nothing here calls a model —
+ * generative work happens through an invoke function the composition root
+ * binds to the kernel adapters later.
+ */
+import { ModelRequirementSchema } from '@kernloop/contracts';
+import { z } from 'zod';
+/**
+ * One workforce agent template (spec §5.4): role prompt + skill set + model
+ * requirement + budget slice. `budgetShare` is the fraction of the parent
+ * task's budget this role may receive by default when the PM slices budgets —
+ * a default allocation hint, not a kernel-enforced ceiling (the kernel
+ * meters, the PM allocates).
+ *
+ * `model` is the role's two-axis {@link ModelRequirement} (spec §8.4): the
+ * model `tier` (frontier > large > medium > small) and reasoning `effort` the
+ * role demands. Mapping a tier+effort to a concrete model id + effort arg is a
+ * composition-root concern resolved through the kernel translation seam; this
+ * faculty only declares the requirement as configuration.
+ */
+export const AgentTemplateSchema = z.strictObject({
+    /** Stable template name, e.g. `pm`; becomes `workforce/<name>` on instantiation. */
+    name: z.string().regex(/^[a-z][a-z0-9-]*$/, 'template name must be lowercase kebab-case'),
+    /** The role prompt the agent runs under. */
+    rolePrompt: z.string().min(1),
+    /** Skill names from the skill library this role loads (spec §5.2 procedural memory). */
+    skills: z.array(z.string().min(1)),
+    /** The role's two-axis model demand (spec §8.4): tier + effort + capabilities. */
+    model: ModelRequirementSchema,
+    /** Default fraction (0, 1] of the parent budget this role may receive. */
+    budgetShare: z.number().gt(0).max(1),
+});
+/**
+ * Expected cost profile per model tier, declared on instantiated manifests
+ * for router budget-matching (spec §3.1). Expectations, not meters — the
+ * kernel adapters meter actual spend per call. Effort is noted, not separately
+ * priced: a tier's row is the expectation at its default effort; raising
+ * effort raises realized tokens, which the per-call meters capture.
+ */
+export const MODEL_TIER_COST = {
+    frontier: { tokens: 48_000, usd: 0.8, latencyMs: 180_000 },
+    large: { tokens: 32_000, usd: 0.5, latencyMs: 120_000 },
+    medium: { tokens: 16_000, usd: 0.1, latencyMs: 60_000 },
+    small: { tokens: 8_000, usd: 0.02, latencyMs: 30_000 },
+};
+/** Build a {@link ModelRequirement} from a partial, applying the schema defaults. */
+const model = (req) => ModelRequirementSchema.parse(req);
+const template = (t) => AgentTemplateSchema.parse(t);
+/**
+ * The five shipped templates (spec §5.4): PM, Coder, Reviewer, Documenter,
+ * Researcher. Research ships as a single Researcher template + the
+ * `research` skill pack — NOT a faculty (spec §5.8). Shipped templates are
+ * `stable`; anything else instantiates as `experimental` (see
+ * instantiateAgent). Tiers reflect each role's load (spec §8.4): the
+ * load-bearing generation roles (Coder, PM, Researcher) on `large` at high
+ * effort; the judging/writing roles (Reviewer, Documenter) on `medium`.
+ *
+ * ROUTING (honesty, #45/#200): in the canonical loop today only PM, Coder, and
+ * Researcher are routed (to the plan/decompose, implement, and research nodes),
+ * and child review runs as a separate advisory GATE (faculty-gates/review), NOT
+ * this Reviewer template. The Reviewer/Documenter templates are shipped
+ * specialists the runtime loop does NOT yet route to — a child's `assignTo`
+ * records the intended specialist as provenance, but every fan-out child is
+ * currently implemented by the Coder until specialist routing lands (#200).
+ */
+export const SHIPPED_TEMPLATES = {
+    pm: template({
+        name: 'pm',
+        rolePrompt: 'You are the PM. Decompose the ratified plan into child TaskContracts, ' +
+            'each with a goal, evidence requirements, a definition of done, and a ' +
+            'budget slice. Child budgets must sum within the parent budget on every ' +
+            'dimension; the kernel meters, you allocate.',
+        skills: ['plan-decomposition', 'budget-allocation'],
+        model: model({ tier: 'large', effort: 'high' }),
+        budgetShare: 0.1,
+    }),
+    coder: template({
+        name: 'coder',
+        rolePrompt: 'You are the Coder. Implement exactly the child TaskContract you were ' +
+            'assigned: satisfy its definition of done, produce its evidence, and ' +
+            'respect its constraints and budget. Wiring-complete or absent.',
+        skills: ['implementation', 'testing'],
+        model: model({ tier: 'large', effort: 'high' }),
+        budgetShare: 0.5,
+    }),
+    reviewer: template({
+        name: 'reviewer',
+        rolePrompt: 'You are the Reviewer. Adversarially review the proposed change against ' +
+            'its contract: correctness, constraint violations, untested claims. ' +
+            'Report severity-tagged findings; do not rewrite the work.',
+        skills: ['diff-review'],
+        model: model({ tier: 'medium', effort: 'high' }),
+        budgetShare: 0.15,
+    }),
+    documenter: template({
+        name: 'documenter',
+        rolePrompt: 'You are the Documenter. Update docs in the same change set, tagging ' +
+            'every capability statement with its claim id. Documentation may state ' +
+            'only verified capability.',
+        skills: ['docs'],
+        model: model({ tier: 'medium', effort: 'high' }),
+        budgetShare: 0.1,
+    }),
+    researcher: template({
+        name: 'researcher',
+        rolePrompt: 'You are the Researcher. Gather and condense the source material the ' +
+            'task needs — code, specs, prior art — with provenance on every finding. ' +
+            'You produce inputs for others; you do not implement.',
+        skills: ['research'],
+        model: model({ tier: 'large', effort: 'high' }),
+        budgetShare: 0.15,
+    }),
+};
+/** Names of the five shipped templates, in spec §5.4 order. */
+export const SHIPPED_TEMPLATE_NAMES = [
+    'pm',
+    'coder',
+    'reviewer',
+    'documenter',
+    'researcher',
+];
+//# sourceMappingURL=templates.js.map

package/dist/templates.js.map

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

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@kernloop/faculty-workforce",
+  "version": "0.1.0",
+  "description": "Kernloop Layer 2 — the workforce faculty (spec §5.4). Agents are configuration, not generation: PM, Coder, Reviewer, Documenter, and Researcher templates instantiate as agentTemplate Manifests, and the PM's plan decomposition is mechanically enforced — child TaskContract budgets must sum within the parent's on every dimension. No model calls: generative work happens through an invoke function injected by the composition root.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@kernloop/contracts": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kernloop/kernloop.git",
+    "directory": "packages/faculty-workforce"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --coverage"
+  }
+}