@mastra/factory 0.26.0-alpha.0 → 0.26.0-alpha.2

package/README.md

@@ -66,12 +66,12 @@ import { defineBoard } from '@mastra/factory/boards';
 
 const releaseBoard = defineBoard({
   id: 'release',
-  title: 'Release',
-  initialPhase: 'queued',
+  name: 'Release',
+  initialPhase: 'backlog',
   phases: {
-    queued: { title: 'Queued', kind: 'resting', next: 'shipped' },
-    shipped: {
-      title: 'Shipped',
+    backlog: { name: 'Backlog', kind: 'resting', nextPhases: ['done'] },
+    done: {
+      name: 'Done',
       kind: 'terminal',
       onEnter: {
         manual: () => ({ type: 'reject', code: 'release_held', reason: 'Release is held.' }),
@@ -126,13 +126,13 @@ When a tracked GitHub, GitLab, Linear, or Jira issue or incident.io follow-up is
 ```typescript
 const releaseBoard = defineBoard({
   id: 'release',
-  title: 'Release',
-  initialPhase: 'queued',
-  sourceClosed: { completed: 'shipped', canceled: 'dropped' },
+  name: 'Release',
+  initialPhase: 'backlog',
+  sourceClosed: { completed: 'done', canceled: 'dropped' },
   phases: {
-    queued: { title: 'Queued', kind: 'resting', outcomes: { ship: 'shipped', drop: 'dropped' } },
-    shipped: { title: 'Shipped', kind: 'terminal' },
-    dropped: { title: 'Dropped', kind: 'terminal' },
+    backlog: { name: 'Backlog', kind: 'resting', nextPhases: ['done', 'dropped'] },
+    done: { name: 'Done', kind: 'terminal' },
+    dropped: { name: 'Dropped', kind: 'terminal' },
   },
 });
 ```
@@ -148,17 +148,17 @@ import { defineBoard } from '@mastra/factory/boards';
 import type { BoardToolResultRuleHandler } from '@mastra/factory/boards';
 
 const shipIt: BoardToolResultRuleHandler = context => {
-  if (context.result.status !== 'success' || context.item.stages[0] !== 'queued') return;
+  if (context.result.status !== 'success' || context.item.stages[0] !== 'backlog') return;
   return { type: 'notify', idempotencyKey: `${context.ingress.id}:shipped`, title: 'Release shipped' };
 };
 
 const releaseBoard = defineBoard({
   id: 'release',
-  title: 'Release',
-  initialPhase: 'queued',
+  name: 'Release',
+  initialPhase: 'backlog',
   phases: {
-    queued: { title: 'Queued', kind: 'resting', next: 'shipped' },
-    shipped: { title: 'Shipped', kind: 'terminal' },
+    backlog: { name: 'Backlog', kind: 'resting', nextPhases: ['done'] },
+    done: { name: 'Done', kind: 'terminal' },
   },
   tools: { ship_it: { onResult: shipIt } },
 });
@@ -166,7 +166,7 @@ const releaseBoard = defineBoard({
 
 The handler receives the bound item, actor, board, tool name, normalized result, and `configVersion`, and returns one decision or `undefined`. Tool names follow the identifier rules for decision roles; `onResult` must be a function and the leaf may contain nothing else. Violations are `BoardDefinitionError`s at definition time.
 
-The default Work board declares one rule: `submit_plan`. In an interactive session, a successful result whose content starts with `Plan approved.` transitions a Planning card to Execute when the actor is an agent in the `plan` role. Review declares none. Rules resolve from the installed board, so a replacement `work` board can declare its own `tools.submit_plan.onResult`. Resolution is fail-closed: a tool result on a card whose board is not installed, or whose board does not declare that tool, fires no rule. Other boards inherit nothing from Work even if they reuse its phase names.
+The default Work board declares two rules. `submit_plan`: in an interactive session, a successful result whose content starts with `Plan approved.` transitions a Planning card to Execute when the actor is the planning agent (`work`, or `plan` for cards planned before Planning moved to `work`). `factory_record_review_verdict` tells the builder to open the change request once self-review approves. Review declares none. Rules resolve from the installed board, so a replacement `work` board can declare its own `tools.submit_plan.onResult`. Resolution is fail-closed: a tool result on a card whose board is not installed, or whose board does not declare that tool, fires no rule. Other boards inherit nothing from Work even if they reuse its phase names.
 
 ### Board event rules
 
@@ -177,7 +177,7 @@ import { defineBoard } from '@mastra/factory';
 
 const deliveryBoard = defineBoard({
   id: 'delivery',
-  title: 'Delivery',
+  name: 'Delivery',
   initialPhase: 'triage',
   phases: {/* ... */},
   events: {
@@ -192,7 +192,7 @@ const deliveryBoard = defineBoard({
     },
     linear: {
       issueClosed: context =>
-        context.issue.stateType === 'canceled' && context.phase?.outcomes.includes('canceled')
+        context.issue.stateType === 'canceled' && context.phase?.nextPhases.includes('canceled')
           ? {
               type: 'transition',
               idempotencyKey: `${context.ingress.id}:canceled`,
@@ -215,7 +215,7 @@ For each event, Factory picks the handler in this order:
 
 A board handler that returns a decision replaces the default for that card. One that returns nothing lets the default run, so card-independent defaults such as dismissing stale Factory reviews still apply. The stock Work and Review behavior stays in the integration defaults and never acts on cards on other boards, so a custom board needs no board guards and no delegation to stock handlers.
 
-Every integration rule context bound to a card carries `phase`: `{ id, kind, role?, outcomes }`, describing what the card's current phase means on its board. `outcomes` lists the outcome names the phase declares. `phase` is absent when the card sits in more than one stage or its board does not declare the phase.
+Every integration rule context bound to a card carries `phase`: `{ id, kind, context?, nextPhases, outcomes }`, describing what the card's current phase means on its board. `context` is the session context of a working phase (`role` carries the same value and is deprecated), `nextPhases` lists the phases the card may move to, and `outcomes` lists the outcome names the phase declares, if any. `phase` is absent when the card sits in more than one stage or its board does not declare the phase.
 
 Unknown integrations, unknown event names, and handler values other than a function or `null` are rejected by `defineBoard` with a `BoardDefinitionError`.
 
@@ -236,7 +236,7 @@ new MastraFactory({ storage, rules: defaultFactoryRules({ version: 'v2', overrid
 new MastraFactory({ storage, configVersion: 'v2', boards: [defineBoard({ ..., tools: { my_tool: { onResult } } })] });
 ```
 
-Contexts that carried `ruleSetVersion` now carry `configVersion`. To customize Work's `submit_plan` rule, declare `tools.submit_plan.onResult` on the installed replacement `work` board.
+Contexts that carried `ruleSetVersion` now carry `configVersion`. To add a tool-result rule to Work, declare it under `tools` on the installed replacement `work` board.
 
 ### Board transition policy
 
@@ -249,19 +249,19 @@ import { defineBoard } from '@mastra/factory/boards';
 import type { BoardTransitionPolicy } from '@mastra/factory/boards';
 
 const releasePolicy: BoardTransitionPolicy = context => {
-  if (context.toStage === 'shipped' && !context.isHumanTransition) {
+  if (context.toStage === 'build' && !context.isHumanTransition) {
     return { type: 'reject', code: 'approval_required', reason: 'A person must approve this release.' };
   }
 };
 
 const releaseBoard = defineBoard({
   id: 'release',
-  title: 'Release',
+  name: 'Release',
   initialPhase: 'approval',
   transitionPolicy: releasePolicy,
   phases: {
-    approval: { title: 'Approval', kind: 'resting', next: 'shipped' },
-    shipped: { title: 'Shipped', kind: 'working', role: 'release' },
+    approval: { name: 'Approval', kind: 'resting', nextPhases: ['build'] },
+    build: { name: 'Build', kind: 'working', runner: { context: 'release' } },
   },
 });
 // Install through new MastraFactory({ storage, boards: [releaseBoard] }).
@@ -280,47 +280,148 @@ A policy cannot bypass topology, ingress authorization, board ownership, externa
 Every phase declares what it _is_ with a required `kind`; `defineBoard()` rejects a phase without one.
 
 - `resting` — the card is parked. A human move out of a resting phase arms autonomy; a move back into one disarms it. `initialPhase` must be resting: a card cannot arrive already seated or already finished.
-- `working` — an agent seat carries the card. `role` is required (same identifier rules as decision roles) and names the seat a human kickoff opens and the lane a rule-started run leaves rest for. Two working phases may share a role; `phaseForRole` returns the first in declaration order.
-- `terminal` — the card is finished. Entering it releases the sandbox and lets sweeps supersede stale decisions and revoke run bindings. `role` is not allowed.
+- `working` — an agent carries the card. `runner.context` (same identifier rules as decision roles, default `work`) names the session context a human kickoff opens and the lane a rule-started run leaves rest for. Two working phases may share a context, and then a session; `phaseForRole` returns the first in declaration order.
+- `terminal` — the card is finished. Entering it releases the sandbox and lets sweeps supersede stale decisions and revoke run bindings. `runner` is not allowed.
 
 ```typescript
 const releaseBoard = defineBoard({
   id: 'release',
-  title: 'Release',
-  initialPhase: 'queued',
+  name: 'Release',
+  initialPhase: 'backlog',
   phases: {
-    queued: { title: 'Queued', kind: 'resting', next: 'shipping' },
-    shipping: { title: 'Shipping', kind: 'working', role: 'release', next: 'shipped' },
-    shipped: { title: 'Shipped', kind: 'terminal' },
+    backlog: { name: 'Backlog', kind: 'resting', nextPhases: ['build'] },
+    build: { name: 'Build', kind: 'working', runner: { context: 'release' }, nextPhases: ['done'] },
+    done: { name: 'Done', kind: 'terminal' },
   },
 });
 ```
 
-Work declares `intake` resting; `triage`, `planning`, `execute`, and `review` working with roles `triage`, `plan`, `work`, and `work`; `done` and `canceled` terminal. Review declares `intake` resting, `review` working with role `review`, and `done`/`canceled` terminal. The definition exposes the derived helpers `phaseKind`, `isWorking`, `isTerminal`, `roleForPhase`, and `phaseForRole`.
+Work declares `intake` resting; `triage`, `planning`, `execute`, and `review` working with contexts `triage`, `work`, `work`, and `work`; `done` and `canceled` terminal. Review declares `intake` resting, `review` working with context `review`, and `done`/`canceled` terminal. The definition exposes the derived helpers `phaseKind`, `isWorking`, `isTerminal`, `roleForPhase`, and `phaseForRole`.
+
+Planning and Building on Work share the `work` session, so the builder keeps the planner's reasoning, branch and sandbox. Self-review still runs in its own `review` session. When the planner moves the card to Building, the build prompt is queued onto its own run, and the planner's run binding ends at that point: Factory tools it calls later in the same turn are rejected. When the builder moves a card back from Building to Planning, no new planning run starts; the builder keeps working in its run. When a person moves it back, Planning starts again, in the same `work` session. The old `plan` role still names Planning: a run requested or queued for `plan` starts Planning in a `plan` session, and the build then continues in that session. Cards planned before this change do the same.
 
 Consent, the external-author guard, kickoff seating, run-start lanes, terminal cleanup, and the closed-PR and issue sweeps all read the installed board's declarations; nothing name-matches phases. A board that reuses Work's phase names gets exactly what it declared. Persisted `board` is authoritative; rows without one are read as Review for pull requests and Work otherwise.
 
 Unknown semantics fail closed. When the board is not installed or the phase is not declared: external-event transitions ask for consent, no sweep or cleanup treats the card as finished, and a rule-started run from rest with no lane for its role is rejected.
 
-**Migration:** Existing `defineBoard()` calls must add `kind` to every phase and `role` to working phases.
+**Migration:** Existing `defineBoard()` calls must add `kind` to every phase. Working phases name their session context with `runner.context`.
 
 ```typescript
 // before
-phases: { queued: { title: 'Queued', next: 'shipped' }, shipped: { title: 'Shipped' } }
+phases: { backlog: { title: 'Backlog', next: 'done' }, done: { title: 'Done' } }
 // after
 phases: {
-  queued: { title: 'Queued', kind: 'resting', next: 'shipped' },
-  shipped: { title: 'Shipped', kind: 'terminal' },
+  backlog: { name: 'Backlog', kind: 'resting', nextPhases: ['done'] },
+  done: { name: 'Done', kind: 'terminal' },
 }
 ```
 
 **Remaining limitations:** Throughput and lead-time metrics still count completions by Work's `done` phase. `factory-ui` still renders the built-in stage and role pipeline.
 
+### Phase runners, automatic starts and exit tools
+
+Boards and phases take `name` and an optional `description`. A phase lists the phases a card may move to in `nextPhases`. A working phase can also declare:
+
+- `runner` — `{ agentId?, skill?, context?, instructions? }`. `context` names the session the phase runs in (defaults to `work`); phases that share a context share a session. When the agent moves its own card into another phase of its context, that phase's `skill` still starts: its prompt is queued onto the agent's run. `skill` starts that skill when a card enters the phase from a source the phase has no `onEnter` handler for. It names a built-in Factory skill or one of your app's skills (see [Skills for custom boards](#skills-for-custom-boards)). `instructions` (up to 1,000 characters) are added to every run the phase starts. `agentId` defaults to `code-agent`, the only agent Factory runs today.
+- `autoStart` and `autoStartWhen` — the phase's runs start without a person's approval, for every card or only for cards matching the rule. Cards from outside the write-access circle still wait for a person.
+- `exitTool` — a tool name, or `{ id, autoApprove, autoApproveWhen }`, that ends the phase. The factory-phase signal tells the agent the phase ends when that tool succeeds and lists `nextPhases`; the agent then moves the card itself with `factory_transition_work_item`, so it picks where the card goes. The phase needs at least one next phase. `autoApprove` answers the person's approval the tool waits for, for every card or only cards matching `autoApproveWhen`. Factory sessions already run tools without asking, so today this matters for `submit_plan`: an auto-approved plan is accepted without a person. `defineBoard()` accepts `autoApprove` on any exit tool, and the catalog reports it, but on other tools it has no effect yet.
+
+Rules test a card's facts: `item.labels`, `item.title`, `item.author`, `source.kind` and `source.integration`.
+
+```typescript
+const LOW_EFFORT = {
+  operator: 'AND',
+  conditions: [{ field: 'item.labels', operator: 'contains', value: 'effort:low' }],
+} as const;
+
+const releaseBoard = defineBoard({
+  id: 'release',
+  name: 'Release',
+  initialPhase: 'backlog',
+  phases: {
+    backlog: { name: 'Backlog', kind: 'resting', nextPhases: ['plan'] },
+    plan: {
+      name: 'Plan',
+      kind: 'working',
+      runner: { context: 'build', skill: 'factory-plan' },
+      autoStart: true,
+      autoStartWhen: LOW_EFFORT,
+      exitTool: { id: 'submit_plan', autoApprove: true },
+      nextPhases: ['build', 'canceled'],
+    },
+    build: { name: 'Build', kind: 'working', runner: { context: 'build' }, nextPhases: ['done'] },
+    done: { name: 'Done', kind: 'terminal' },
+    canceled: { name: 'Canceled', kind: 'terminal' },
+  },
+});
+```
+
+**Migration:** `defineBoard()` still accepts the old field names and maps them to the new ones straight away: `title` → `name`, `role` → `runner.context`, `next` → `nextPhases`. It logs one warning per board that still uses them. Setting both `title` and `name`, or `role` and `runner.context`, to different values is rejected. `outcomes` is not deprecated: its targets are added to `nextPhases` and outcome names keep working. The board `defineBoard()` returns, and the one `new MastraFactory({ boards })` takes, has only the new fields, so code that reads `board.title`, `phase.title`, `phase.role` or `phase.next` must switch to `name`, `runner.context` and `nextPhases`. The board catalog (`GET /web/factory/projects/:id/boards`) still sends `title` and `role` beside the new fields for older clients. Card session keys do not change: a phase's context is its old role.
+
+### Skills for custom boards
+
+A phase's `runner.skill` runs a skill when a card enters the phase. Use a built-in skill such as `factory-plan`, or write your own. Factory finds a skill in this order; the first match wins:
+
+1. **Code skills** — passed to `new MastraFactory({ skills })`, created with `createSkill()` from `@mastra/core/skills`.
+2. **Folder skills** — `src/mastra/factory-skills/<name>/SKILL.md` in your app. `mastra build` copies the folder into the build output. The older `src/mastra/public/factory-skills` still works; when both exist, `src/mastra/factory-skills` wins. Factory also looks in `public/factory-skills`, `factory-skills` and `output/factory-skills` under the working directory, and uses the first that exists. Supporting files, such as `references/`, can sit next to `SKILL.md`.
+3. **Built-in skills** shipped with `@mastra/factory`.
+
+A skill with the same name as a built-in skill replaces it, for the built-in boards too. A code skill replaces the whole folder skill of the same name, including its supporting files. Repository skills in a project's own repository never replace these.
+
+Skill names use 1–64 lowercase letters, digits and single hyphens, such as `release-notes`. A folder skill's `name` must match its directory name. Names in `skills` must be unique, or the constructor throws.
+
+```typescript
+import { createSkill } from '@mastra/core/skills';
+import { MastraFactory } from '@mastra/factory';
+import { defineBoard } from '@mastra/factory/boards';
+
+const releaseNotes = createSkill({
+  name: 'release-notes',
+  description: 'Draft release notes for a work item',
+  instructions: 'Group the release notes by package and end with a one-line summary. Then move the card to Published.',
+});
+
+const notesBoard = defineBoard({
+  id: 'notes',
+  name: 'Notes',
+  initialPhase: 'backlog',
+  phases: {
+    backlog: { name: 'Backlog', kind: 'resting', nextPhases: ['drafting'] },
+    drafting: {
+      name: 'Drafting',
+      kind: 'working',
+      runner: { context: 'writer', skill: 'release-notes' },
+      nextPhases: ['published'],
+    },
+    published: { name: 'Published', kind: 'terminal' },
+  },
+});
+
+const factory = new MastraFactory({ ...config, boards: [notesBoard], skills: [releaseNotes] });
+```
+
+The same skill as a folder skill is `src/mastra/factory-skills/release-notes/SKILL.md`:
+
+```markdown
+---
+name: release-notes
+description: Draft release notes for a work item
+---
+
+Group the release notes by package and end with a one-line summary. Then move the card to Published.
+```
+
+The skill receives the card's link, or its title when it has none, as arguments. Every Factory session can also load your skills on request, like the built-in ones.
+
+When a card enters the phase and the skill does not exist, no run starts and the card stays in the phase. The start fails with `Skill not found: <name>.`; after a few quick retries it stays failed, and you can retry it once the skill exists. The constructor logs a warning for each phase that names a missing skill. It also warns when a phase outside the `review` context runs a review skill (`factory-review`, `factory-rereview`, `factory-self-review`, `factory-gitlab-review`, `factory-gitlab-rereview`), because sessions only load those for reviews.
+
+Settings › Skills shows the skill each custom phase runs, marks a phase whose skill is missing, marks built-in skills your app replaces, and lists your other skills under **App skills**.
+
 ### Execute a custom board
 
 Installed custom boards can create linked items, start working roles, transition through bound tools, and react to completed tool results. Board and phase identifiers contain 1–128 letters, digits, underscores, or hyphens and start with a letter or digit. Identifiers are case-sensitive and cannot contain surrounding whitespace.
 
-This configuration runs a release rehearsal through `queued → preparing → shipping → shipped`. Add it to an existing Factory host with configured storage, a GitHub integration, a connected project repository, a sandbox, and organization-scoped model credentials. Enable automatic runs for the project. The repository must contain a `release:check` package script; it should validate the release without publishing it.
+This configuration runs a release rehearsal through `backlog → preparing → build → done`. Add it to an existing Factory host with configured storage, a GitHub integration, a connected project repository, a sandbox, and organization-scoped model credentials. Enable automatic runs for the project. The repository must contain a `release:check` package script; it should validate the release without publishing it.
 
 ```typescript
 import { MastraFactory } from '@mastra/factory';
@@ -328,14 +429,14 @@ import type { MastraFactoryConfig } from '@mastra/factory';
 import { defineBoard } from '@mastra/factory/boards';
 import type { BoardPhaseDefinition } from '@mastra/factory/boards';
 
-type ReleasePhase = 'queued' | 'preparing' | 'shipping' | 'shipped';
+type ReleasePhase = 'backlog' | 'preparing' | 'build' | 'done';
 
 const releaseBoard = defineBoard<'release', Record<ReleasePhase, BoardPhaseDefinition<ReleasePhase>>>({
   id: 'release',
-  title: 'Release',
-  initialPhase: 'queued',
+  name: 'Release',
+  initialPhase: 'backlog',
   transitionPolicy: context => {
-    if (context.fromStage === 'queued' && context.toStage === 'preparing' && !context.isHumanTransition) {
+    if (context.fromStage === 'backlog' && context.toStage === 'preparing' && !context.isHumanTransition) {
       return {
         type: 'reject',
         code: 'approval_required',
@@ -344,27 +445,27 @@ const releaseBoard = defineBoard<'release', Record<ReleasePhase, BoardPhaseDefin
     }
   },
   phases: {
-    queued: { title: 'Queued', kind: 'resting', next: 'preparing' },
+    backlog: { name: 'Backlog', kind: 'resting', nextPhases: ['preparing'] },
     preparing: {
-      title: 'Preparing',
+      name: 'Preparing',
       kind: 'working',
-      role: 'release-preparer',
-      next: 'shipping',
+      runner: { context: 'release-preparer' },
+      nextPhases: ['build'],
       onEnter: {
         issue: context => ({
           type: 'invokeSkill',
           idempotencyKey: `${context.ingress.id}:prepare`,
           role: 'release-preparer',
           prompt:
-            'Inspect the release changes. When ready, call factory_transition_work_item with stage shipping and the current expectedRevision from the Factory phase signal.',
+            'Inspect the release changes. When ready, call factory_transition_work_item with stage build and the current expectedRevision from the Factory phase signal.',
         }),
       },
     },
-    shipping: {
-      title: 'Shipping',
+    build: {
+      name: 'Build',
       kind: 'working',
-      role: 'release-publisher',
-      next: 'shipped',
+      runner: { context: 'release-publisher' },
+      nextPhases: ['done'],
       onEnter: {
         issue: context => ({
           type: 'invokeSkill',
@@ -375,13 +476,13 @@ const releaseBoard = defineBoard<'release', Record<ReleasePhase, BoardPhaseDefin
         }),
       },
     },
-    shipped: { title: 'Shipped', kind: 'terminal' },
+    done: { name: 'Done', kind: 'terminal' },
   },
   tools: {
     execute_command: {
       onResult: context => {
         if (
-          context.item.stages[0] !== 'shipping' ||
+          context.item.stages[0] !== 'build' ||
           context.result.status !== 'success' ||
           typeof context.result.value !== 'string' ||
           !context.result.value.trimEnd().endsWith('RELEASE_CHECK_PASSED')
@@ -392,7 +493,7 @@ const releaseBoard = defineBoard<'release', Record<ReleasePhase, BoardPhaseDefin
           type: 'transition',
           idempotencyKey: `${context.ingress.id}:checked`,
           board: 'release',
-          stage: 'shipped',
+          stage: 'done',
         };
       },
     },
@@ -406,7 +507,7 @@ export function createFactory(config: Omit<MastraFactoryConfig, 'boards' | 'incl
 
 Use the host's normal `prepare()`, `new Mastra(...)`, and `finalize()` sequence. Change the hardcoded `includeDefaultBoards: true` in `createFactory` to `false` to run without Work or Review. Working roles name bindings on the shared Code Agent; they do not register separate agents. Factory has no per-role agent configuration option. The board's kickoff prompts supply the role-specific instructions.
 
-Create a card with `POST /web/factory/projects/:id/work-items`, passing `board: 'release'`, a title, and the GitHub issue's `externalSource`. The card starts in `queued`. Then use `POST /web/factory/projects/:id/work-items/:workItemId/transition` with `board: 'release'`, `stage: 'preparing'`, the returned `expectedRevision`, a unique `requestId`, and a `cause`. Send these requests as an authorized user using the host's authentication. The human transition satisfies this board's policy and starts the preparer. Its bound tool advances to `shipping`; the publisher's completed check produces a deferred transition to `shipped`. Terminal entry revokes the binding and releases the sandbox. The Factory UI performs the same operations against installed boards (see below); verify the persisted card's board, phase, and deferred decision status either way.
+Create a card with `POST /web/factory/projects/:id/work-items`, passing `board: 'release'`, a title, and the GitHub issue's `externalSource`. The card starts in `backlog`. Then use `POST /web/factory/projects/:id/work-items/:workItemId/transition` with `board: 'release'`, `stage: 'preparing'`, the returned `expectedRevision`, a unique `requestId`, and a `cause`. Send these requests as an authorized user using the host's authentication. The human transition satisfies this board's policy and starts the preparer. Its bound tool advances to `build`; the publisher's completed check produces a deferred transition to `done`. Terminal entry revokes the binding and releases the sandbox. The Factory UI performs the same operations against installed boards (see below); verify the persisted card's board, phase, and deferred decision status either way.
 
 Lifecycle, tool-result, and integration handlers may return `upsertLinkedWorkItem` targeting a different installed board. Linked cards enter that board's declared initial phase before moving to the requested phase. Existing cards cannot be reassigned to another board through either decision type. Targets are validated against their own installed board before acceptance and again before uncommitted deferred effects execute; a phase declared only on another board is not valid. Committed replay retains its recorded result and original `configVersion`.
 
@@ -414,12 +515,12 @@ Custom phase signals and persisted tool-result ingestion use the item's installe
 
 ### Custom boards in the Factory UI
 
-`GET /web/factory/projects/:id/boards` returns the installed board catalog for an authorized project: each board's `id`, `title`, `initialPhase`, declaration-ordered `phases` (with `kind` and working `role`), and transition topology. Handlers, policies, and prompts are never serialized. The Factory UI reads this catalog instead of assuming Work and Review:
+`GET /web/factory/projects/:id/boards` returns the installed board catalog for an authorized project: each board's `id`, `title`, `initialPhase`, declaration-ordered `phases` (with `kind`, and for working phases `role` and the `skill` the runner starts), and transition topology. Handlers, policies, and prompts are never serialized. The Factory UI reads this catalog instead of assuming Work and Review:
 
 - Installed boards appear in the sidebar — built-ins first, then custom boards in registry order. Work and Review keep `/factories/:id/work` and `/factories/:id/review`; custom boards open at `/factories/:id/boards/:boardId`. An unknown board ID or a failed catalog request shows an explicit unavailable state rather than falling back to Work.
 - Columns, phase labels, and working/terminal presentation come from the phase definitions. Card creation sends the selected `board`, so the server picks the initial phase. Card menus offer only moves the topology declares; the server still enforces policy, authorization, and revisions.
 - A card's persisted `board` decides which board it belongs to. UI actions cannot move a card to a different board.
-- Settings › Skills groups built-in skills under Work and Review and lists each custom board's declared roles. Custom-board kickoff instructions live in code; there is no skill or per-role agent configuration for them.
+- Settings › Skills groups built-in skills under Work and Review. For each custom board it shows the skill each phase runs (`runner.skill`) and the roles of phases that run no skill; those phases' kickoff instructions live in the board definition. Your app's other skills appear under App skills.
 - Not yet board-aware: the Overview funnel and stage-hold metrics (Work-only), search scopes (Work/Review sessions), and the automation toggles that are specific to Work triage and Review. Custom-board cards still count toward in-flight totals and appear in activity and audit logs.
 
 ### Route intake to custom boards

package/dist/auth.d.ts.map

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

package/dist/boards/card-facts.d.ts

@@ -0,0 +1,5 @@
+import type { RuleFacts } from '../rules/rule-group.js';
+import type { WorkItemRow } from '../storage/domains/work-items/base.js';
+/** What a phase condition (`autoStartWhen`, `exitTool.autoApproveWhen`) can test about a card. */
+export declare function cardRuleFacts(item: Pick<WorkItemRow, 'title' | 'metadata' | 'externalSource'>): RuleFacts;
+//# sourceMappingURL=card-facts.d.ts.map

package/dist/boards/card-facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-facts.d.ts","sourceRoot":"","sources":["../../src/boards/card-facts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAEzE,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,UAAU,GAAG,gBAAgB,CAAC,GAAG,SAAS,CAiBzG"}

package/dist/boards/card-facts.js

@@ -0,0 +1,19 @@
+// src/boards/card-facts.ts
+/** What a phase condition (`autoStartWhen`, `exitTool.autoApproveWhen`) can test about a card. */
+function cardRuleFacts(item) {
+	const metadata = item.metadata ?? {};
+	const labels = Array.isArray(metadata.labels) ? metadata.labels.filter((label) => typeof label === "string") : [];
+	const source = item.externalSource;
+	return {
+		"item.labels": labels,
+		"item.title": item.title,
+		...typeof metadata.author === "string" ? { "item.author": metadata.author } : {},
+		...source ? {
+			"source.kind": source.type === "pull-request" ? "pull_request" : source.type,
+			"source.integration": source.integrationId
+		} : {}
+	};
+}
+export { cardRuleFacts };
+
+//# sourceMappingURL=card-facts.js.map

package/dist/boards/card-facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-facts.js","names":[],"sources":["../../src/boards/card-facts.ts"],"sourcesContent":["import type { RuleFacts } from '../rules/rule-group.js';\nimport type { WorkItemRow } from '../storage/domains/work-items/base.js';\n\n/** What a phase condition (`autoStartWhen`, `exitTool.autoApproveWhen`) can test about a card. */\nexport function cardRuleFacts(item: Pick<WorkItemRow, 'title' | 'metadata' | 'externalSource'>): RuleFacts {\n  const metadata = item.metadata ?? {};\n  const labels = Array.isArray(metadata.labels)\n    ? metadata.labels.filter((label): label is string => typeof label === 'string')\n    : [];\n  const source = item.externalSource;\n  return {\n    'item.labels': labels,\n    'item.title': item.title,\n    ...(typeof metadata.author === 'string' ? { 'item.author': metadata.author } : {}),\n    ...(source\n      ? {\n          'source.kind': source.type === 'pull-request' ? 'pull_request' : source.type,\n          'source.integration': source.integrationId,\n        }\n      : {}),\n  };\n}\n"],"mappings":";;AAIA,SAAgB,cAAc,MAA6E;CACzG,MAAM,WAAW,KAAK,YAAY,CAAC;CACnC,MAAM,SAAS,MAAM,QAAQ,SAAS,MAAM,IACxC,SAAS,OAAO,QAAQ,UAA2B,OAAO,UAAU,QAAQ,IAC5E,CAAC;CACL,MAAM,SAAS,KAAK;CACpB,OAAO;EACL,eAAe;EACf,cAAc,KAAK;EACnB,GAAI,OAAO,SAAS,WAAW,WAAW,EAAE,eAAe,SAAS,OAAO,IAAI,CAAC;EAChF,GAAI,SACA;GACE,eAAe,OAAO,SAAS,iBAAiB,iBAAiB,OAAO;GACxE,sBAAsB,OAAO;EAC/B,IACA,CAAC;CACP;AACF"}

package/dist/boards/define-board.d.ts

@@ -1,3 +1,4 @@
+import type { RuleFacts, RuleGroup } from '../rules/rule-group.js';
 import type { FactoryGithubEventName, FactoryGithubRuleContext, FactoryGitLabEventName, FactoryGitLabRuleContext, FactoryIncidentioEventName, FactoryIncidentioRuleContext, FactoryJiraEventName, FactoryJiraRuleContext, FactoryLinearEventName, FactoryLinearRuleContext, FactoryRuleHandler, FactoryRuleSource, FactoryStageRuleContext, FactoryToolResultRuleContext } from '../rules/types.js';
 import type { BoardTransitionPolicy } from './transition-policy.js';
 type BoardPhaseHandlers = Partial<Record<FactoryRuleSource, FactoryRuleHandler<FactoryStageRuleContext>>>;
@@ -33,26 +34,112 @@ type ReadonlyFactoryBoardRules = Readonly<Record<string, Readonly<Partial<Record
 /**
  * What a phase means to the runtime.
  * - `resting`: nobody is seated; a card waits for a person or an event.
- * - `working`: an agent in `role` carries the card; a person's move in arms autonomy.
+ * - `working`: an agent in the phase's context carries the card; a person's move in arms autonomy.
  * - `terminal`: the card is finished; sessions stop and held resources are released.
  */
 export type BoardPhaseKind = 'resting' | 'working' | 'terminal';
+/** The agent Factory runs every phase with. */
+export declare const FACTORY_AGENT_ID = "code-agent";
+/** The session context a working phase runs in when it names none. */
+export declare const DEFAULT_PHASE_CONTEXT = "work";
+/** Who runs a working phase, and with what. */
+export interface BoardPhaseRunner {
+    /** Must be `code-agent`, the agent Factory runs; omitted means that agent. */
+    readonly agentId?: string;
+    /** Skill started when a card enters the phase from a source with no `onEnter` handler. */
+    readonly skill?: string;
+    /**
+     * The session the phase runs in. Phases naming the same context share one session per card;
+     * a different context gets its own. Defaults to `work`.
+     */
+    readonly context?: string;
+    /** Appended to every run the phase starts. */
+    readonly instructions?: string;
+}
+/**
+ * The tool whose successful call ends a working phase. The agent then moves the card itself with
+ * `factory_transition_work_item`, to one of the phase's `nextPhases`.
+ */
+export interface BoardPhaseExitTool {
+    readonly id: string;
+    /**
+     * Answer the approval the tool waits for without a person. Factory sessions run other tools
+     * without asking, so today this applies to `submit_plan`. Defaults to false.
+     */
+    readonly autoApprove?: boolean;
+    /** With `autoApprove`, only cards this matches are approved without a person. */
+    readonly autoApproveWhen?: RuleGroup;
+}
 type BoardPhaseBase<PhaseId extends string> = {
-    readonly title: string;
+    readonly name?: string;
+    /** @deprecated Use `name`. */
+    readonly title?: string;
+    readonly description?: string;
+    /** Phases a card may move to from here. */
+    readonly nextPhases?: readonly PhaseId[];
+    /** @deprecated List the phase in `nextPhases`. */
     readonly next?: PhaseId;
+    /** Named moves rules can choose by outcome; each target is also an allowed next phase. */
     readonly outcomes?: Readonly<Record<string, PhaseId>>;
     readonly onEnter?: ReadonlyBoardPhaseHandlers;
     readonly onExit?: ReadonlyBoardPhaseHandlers;
 };
-export type BoardPhaseDefinition<PhaseId extends string> = (BoardPhaseBase<PhaseId> & {
-    readonly kind: 'resting';
+type WorkingPhaseFields = {
+    readonly runner?: BoardPhaseRunner;
+    /** @deprecated Use `runner.context`. */
+    readonly role?: string;
+    /** Runs start without anyone approving them, even with the project's auto-run off. */
+    readonly autoStart?: boolean;
+    /** With `autoStart`, only cards this matches start on their own. */
+    readonly autoStartWhen?: RuleGroup;
+    /** A bare tool name is shorthand for `{ id }`, with nothing approved on a person's behalf. */
+    readonly exitTool?: string | BoardPhaseExitTool;
+};
+type NonWorkingPhaseFields = {
+    readonly runner?: never;
     readonly role?: never;
-}) | (BoardPhaseBase<PhaseId> & {
+    readonly autoStart?: never;
+    readonly autoStartWhen?: never;
+    readonly exitTool?: never;
+};
+/** A phase as a board declares it. */
+export type BoardPhaseDefinition<PhaseId extends string> = (BoardPhaseBase<PhaseId> & NonWorkingPhaseFields & {
+    readonly kind: 'resting';
+}) | (BoardPhaseBase<PhaseId> & WorkingPhaseFields & {
     readonly kind: 'working';
-    readonly role: string;
-}) | (BoardPhaseBase<PhaseId> & {
+}) | (BoardPhaseBase<PhaseId> & NonWorkingPhaseFields & {
+    readonly kind: 'terminal';
+});
+type ResolvedPhaseBase<PhaseId extends string> = {
+    readonly name: string;
+    readonly description?: string;
+    /** Every phase a card may move to from here, including outcome targets. */
+    readonly nextPhases: readonly PhaseId[];
+    readonly outcomes?: Readonly<Record<string, PhaseId>>;
+    readonly onEnter?: ReadonlyBoardPhaseHandlers;
+    readonly onExit?: ReadonlyBoardPhaseHandlers;
+};
+/**
+ * A phase as the board resolved it: deprecated fields are replaced by their new names, so
+ * only the new structure leaves `defineBoard()`, and a resolved phase can be declared again.
+ */
+export type BoardPhase<PhaseId extends string> = (ResolvedPhaseBase<PhaseId> & {
+    readonly kind: 'resting';
+}) | (ResolvedPhaseBase<PhaseId> & {
+    readonly kind: 'working';
+    readonly runner: Readonly<BoardPhaseRunner & {
+        agentId: string;
+        context: string;
+    }>;
+    readonly autoStart?: boolean;
+    readonly autoStartWhen?: RuleGroup;
+    readonly exitTool?: Readonly<{
+        id: string;
+        autoApprove: boolean;
+        autoApproveWhen?: RuleGroup;
+    }>;
+}) | (ResolvedPhaseBase<PhaseId> & {
     readonly kind: 'terminal';
-    readonly role?: never;
 });
 export interface BoardTransition<PhaseId extends string> {
     readonly outcome: string | null;
@@ -68,9 +155,10 @@ export type BoardSourceClosed<PhaseId extends string> = Readonly<{
 }>;
 export interface BoardDefinition<BoardId extends string, PhaseId extends string> {
     readonly id: BoardId;
-    readonly title: string;
+    readonly name: string;
+    readonly description?: string;
     readonly initialPhase: PhaseId;
-    readonly phases: Readonly<Record<PhaseId, BoardPhaseDefinition<PhaseId>>>;
+    readonly phases: Readonly<Record<PhaseId, BoardPhase<PhaseId>>>;
     readonly transitions: Readonly<Record<PhaseId, readonly BoardTransition<PhaseId>[]>>;
     readonly rules: ReadonlyFactoryBoardRules;
     /** Tool-result rules keyed by tool name; empty when the board declares none. */
@@ -85,14 +173,22 @@ export interface BoardDefinition<BoardId extends string, PhaseId extends string>
     phaseKind(phase: string): BoardPhaseKind | undefined;
     isWorking(phase: string): boolean;
     isTerminal(phase: string): boolean;
-    /** Role seated in a working phase; undefined for resting/terminal/unknown phases. */
+    /** Session context of a working phase; undefined for resting/terminal/unknown phases. */
     roleForPhase(phase: string): string | undefined;
-    /** First working phase, in declaration order, carried by `role`. */
+    /** First working phase, in declaration order, running in `role`'s context. */
     phaseForRole(role: string): PhaseId | undefined;
+    /**
+     * Whether the phase's runs start without anyone approving them, for a card with these facts
+     * (`cardRuleFacts`). A phase with a start condition never starts on its own without facts.
+     */
+    startsAutomatically(phase: string, facts?: RuleFacts): boolean;
 }
 type BoardConfig<BoardId extends string, Phases extends Record<string, BoardPhaseDefinition<keyof Phases & string>>> = {
     id: BoardId;
-    title: string;
+    name?: string;
+    /** @deprecated Use `name`. */
+    title?: string;
+    description?: string;
     initialPhase: keyof Phases & string;
     phases: Phases;
     tools?: Record<string, BoardToolRule>;