@mastra/factory 0.28.0-alpha.1 → 0.28.0-alpha.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +244 -123
- package/dist/boards/board-events.d.ts +23 -3
- package/dist/boards/board-events.d.ts.map +1 -1
- package/dist/boards/board-events.js +44 -7
- package/dist/boards/board-events.js.map +1 -1
- package/dist/boards/board-writes.d.ts +1 -1
- package/dist/boards/board-writes.d.ts.map +1 -1
- package/dist/boards/board-writes.js +16 -1
- package/dist/boards/board-writes.js.map +1 -1
- package/dist/boards/card-facts.d.ts +1 -1
- package/dist/boards/card-facts.d.ts.map +1 -1
- package/dist/boards/card-facts.js +4 -0
- package/dist/boards/card-facts.js.map +1 -1
- package/dist/boards/default-board.d.ts +7 -0
- package/dist/boards/default-board.d.ts.map +1 -0
- package/dist/boards/default-board.js +10 -0
- package/dist/boards/default-board.js.map +1 -0
- package/dist/boards/define-board.d.ts +39 -17
- package/dist/boards/define-board.d.ts.map +1 -1
- package/dist/boards/define-board.js +64 -42
- package/dist/boards/define-board.js.map +1 -1
- package/dist/boards/index.d.ts +5 -8
- package/dist/boards/index.d.ts.map +1 -1
- package/dist/boards/index.js +5 -19
- package/dist/boards/intake-routing.d.ts +27 -5
- package/dist/boards/intake-routing.d.ts.map +1 -1
- package/dist/boards/intake-routing.js +69 -16
- package/dist/boards/intake-routing.js.map +1 -1
- package/dist/boards/legacy-plan-role.d.ts.map +1 -1
- package/dist/boards/legacy-plan-role.js +7 -2
- package/dist/boards/legacy-plan-role.js.map +1 -1
- package/dist/boards/phase-automation.d.ts +7 -0
- package/dist/boards/phase-automation.d.ts.map +1 -1
- package/dist/boards/phase-automation.js +16 -5
- package/dist/boards/phase-automation.js.map +1 -1
- package/dist/boards/phase-runner.d.ts +18 -10
- package/dist/boards/phase-runner.d.ts.map +1 -1
- package/dist/boards/phase-runner.js +39 -34
- package/dist/boards/phase-runner.js.map +1 -1
- package/dist/boards/project-boards.d.ts +9 -6
- package/dist/boards/project-boards.d.ts.map +1 -1
- package/dist/boards/project-boards.js +56 -18
- package/dist/boards/project-boards.js.map +1 -1
- package/dist/boards/registry.d.ts.map +1 -1
- package/dist/boards/registry.js +3 -1
- package/dist/boards/registry.js.map +1 -1
- package/dist/boards/relocate.d.ts +1 -1
- package/dist/boards/relocate.d.ts.map +1 -1
- package/dist/boards/relocate.js +3 -2
- package/dist/boards/relocate.js.map +1 -1
- package/dist/boards/review.d.ts +5 -2
- package/dist/boards/review.d.ts.map +1 -1
- package/dist/boards/review.js +12 -11
- package/dist/boards/review.js.map +1 -1
- package/dist/boards/semantics.d.ts +159 -20
- package/dist/boards/semantics.d.ts.map +1 -1
- package/dist/boards/semantics.js +256 -23
- package/dist/boards/semantics.js.map +1 -1
- package/dist/boards/stored-board.d.ts +32 -18
- package/dist/boards/stored-board.d.ts.map +1 -1
- package/dist/boards/stored-board.js +31 -97
- package/dist/boards/stored-board.js.map +1 -1
- package/dist/boards/work-migrations.d.ts +19 -0
- package/dist/boards/work-migrations.d.ts.map +1 -0
- package/dist/boards/work-migrations.js +257 -0
- package/dist/boards/work-migrations.js.map +1 -0
- package/dist/boards/work-routes.d.ts +53 -0
- package/dist/boards/work-routes.d.ts.map +1 -0
- package/dist/boards/work-routes.js +256 -0
- package/dist/boards/work-routes.js.map +1 -0
- package/dist/boards/work.d.ts +8 -19
- package/dist/boards/work.d.ts.map +1 -1
- package/dist/boards/work.js +38 -270
- package/dist/boards/work.js.map +1 -1
- package/dist/factory.d.ts +3 -3
- package/dist/factory.d.ts.map +1 -1
- package/dist/factory.js +58 -30
- package/dist/factory.js.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -3
- package/dist/integrations/base.d.ts +6 -2
- package/dist/integrations/base.d.ts.map +1 -1
- package/dist/integrations/closing-references.d.ts +15 -0
- package/dist/integrations/closing-references.d.ts.map +1 -0
- package/dist/integrations/closing-references.js +69 -0
- package/dist/integrations/closing-references.js.map +1 -0
- package/dist/integrations/github/default-rules.d.ts +15 -66
- package/dist/integrations/github/default-rules.d.ts.map +1 -1
- package/dist/integrations/github/default-rules.js +129 -71
- package/dist/integrations/github/default-rules.js.map +1 -1
- package/dist/integrations/github/issue-reconciler.d.ts.map +1 -1
- package/dist/integrations/github/issue-reconciler.js +3 -1
- package/dist/integrations/github/issue-reconciler.js.map +1 -1
- package/dist/integrations/github/pull-request-source.d.ts +8 -0
- package/dist/integrations/github/pull-request-source.d.ts.map +1 -0
- package/dist/integrations/github/pull-request-source.js +17 -0
- package/dist/integrations/github/pull-request-source.js.map +1 -0
- package/dist/integrations/github/review-status-reporter.d.ts.map +1 -1
- package/dist/integrations/github/review-status-reporter.js +7 -3
- package/dist/integrations/github/review-status-reporter.js.map +1 -1
- package/dist/integrations/github/routes.js +1 -1
- package/dist/integrations/github/rules.d.ts +13 -2
- package/dist/integrations/github/rules.d.ts.map +1 -1
- package/dist/integrations/github/rules.js +202 -34
- package/dist/integrations/github/rules.js.map +1 -1
- package/dist/integrations/github/session-subscriptions.js +2 -2
- package/dist/integrations/github/session-subscriptions.js.map +1 -1
- package/dist/integrations/github/token-refresh.d.ts +2 -1
- package/dist/integrations/github/token-refresh.d.ts.map +1 -1
- package/dist/integrations/github/token-refresh.js.map +1 -1
- package/dist/integrations/gitlab/agent-tools.js +1 -1
- package/dist/integrations/gitlab/default-rules.d.ts +73 -31
- package/dist/integrations/gitlab/default-rules.d.ts.map +1 -1
- package/dist/integrations/gitlab/default-rules.js +106 -43
- package/dist/integrations/gitlab/default-rules.js.map +1 -1
- package/dist/integrations/gitlab/issue-reconciler.d.ts.map +1 -1
- package/dist/integrations/gitlab/issue-reconciler.js +2 -1
- package/dist/integrations/gitlab/issue-reconciler.js.map +1 -1
- package/dist/integrations/gitlab/merge-request-reconciler.d.ts.map +1 -1
- package/dist/integrations/gitlab/merge-request-reconciler.js +11 -4
- package/dist/integrations/gitlab/merge-request-reconciler.js.map +1 -1
- package/dist/integrations/gitlab/rules.d.ts +6 -1
- package/dist/integrations/gitlab/rules.d.ts.map +1 -1
- package/dist/integrations/gitlab/rules.js +116 -23
- package/dist/integrations/gitlab/rules.js.map +1 -1
- package/dist/integrations/gitlab/session-subscriptions.js +1 -1
- package/dist/integrations/incidentio/agent-tools.js +1 -1
- package/dist/integrations/incidentio/default-rules.js +3 -3
- package/dist/integrations/incidentio/default-rules.js.map +1 -1
- package/dist/integrations/incidentio/issue-reconciler.d.ts.map +1 -1
- package/dist/integrations/incidentio/issue-reconciler.js +2 -1
- package/dist/integrations/incidentio/issue-reconciler.js.map +1 -1
- package/dist/integrations/incidentio/rules.d.ts +3 -1
- package/dist/integrations/incidentio/rules.d.ts.map +1 -1
- package/dist/integrations/incidentio/rules.js +14 -11
- package/dist/integrations/incidentio/rules.js.map +1 -1
- package/dist/integrations/jira/agent-tools.js +1 -1
- package/dist/integrations/jira/default-rules.js +3 -3
- package/dist/integrations/jira/default-rules.js.map +1 -1
- package/dist/integrations/jira/issue-reconciler.d.ts.map +1 -1
- package/dist/integrations/jira/issue-reconciler.js +2 -1
- package/dist/integrations/jira/issue-reconciler.js.map +1 -1
- package/dist/integrations/jira/rules.d.ts +3 -1
- package/dist/integrations/jira/rules.d.ts.map +1 -1
- package/dist/integrations/jira/rules.js +14 -11
- package/dist/integrations/jira/rules.js.map +1 -1
- package/dist/integrations/linear/agent-tools.d.ts +9 -1
- package/dist/integrations/linear/agent-tools.d.ts.map +1 -1
- package/dist/integrations/linear/agent-tools.js +80 -2
- package/dist/integrations/linear/agent-tools.js.map +1 -1
- package/dist/integrations/linear/default-rules.js +3 -3
- package/dist/integrations/linear/default-rules.js.map +1 -1
- package/dist/integrations/linear/integration.d.ts +4 -1
- package/dist/integrations/linear/integration.d.ts.map +1 -1
- package/dist/integrations/linear/integration.js +21 -1
- package/dist/integrations/linear/integration.js.map +1 -1
- package/dist/integrations/linear/issue-reconciler.d.ts.map +1 -1
- package/dist/integrations/linear/issue-reconciler.js +2 -1
- package/dist/integrations/linear/issue-reconciler.js.map +1 -1
- package/dist/integrations/linear/routes.d.ts +2 -1
- package/dist/integrations/linear/routes.d.ts.map +1 -1
- package/dist/integrations/linear/routes.js +4 -3
- package/dist/integrations/linear/routes.js.map +1 -1
- package/dist/integrations/linear/rules.d.ts +3 -1
- package/dist/integrations/linear/rules.d.ts.map +1 -1
- package/dist/integrations/linear/rules.js +15 -12
- package/dist/integrations/linear/rules.js.map +1 -1
- package/dist/integrations/platform/github/integration.d.ts.map +1 -1
- package/dist/integrations/platform/github/integration.js +33 -21
- package/dist/integrations/platform/github/integration.js.map +1 -1
- package/dist/integrations/platform/jira/agent-tools.js +1 -1
- package/dist/integrations/platform/linear/integration.d.ts +1 -1
- package/dist/integrations/platform/linear/integration.d.ts.map +1 -1
- package/dist/integrations/platform/linear/integration.js +6 -5
- package/dist/integrations/platform/linear/integration.js.map +1 -1
- package/dist/integrations/slack/chat-tools.js +1 -1
- package/dist/integrations/slack/reply-tool.js +1 -1
- package/dist/integrations/slack/share-file-tool.js +1 -1
- package/dist/integrations/slack/slack.d.ts +10 -4
- package/dist/integrations/slack/slack.d.ts.map +1 -1
- package/dist/integrations/slack/slack.js +19 -9
- package/dist/integrations/slack/slack.js.map +1 -1
- package/dist/links.d.ts.map +1 -1
- package/dist/links.js +3 -2
- package/dist/links.js.map +1 -1
- package/dist/mcp/routes.js +2 -2
- package/dist/routes/attention-parked.d.ts +1 -0
- package/dist/routes/attention-parked.d.ts.map +1 -1
- package/dist/routes/attention-parked.js +1 -1
- package/dist/routes/attention-parked.js.map +1 -1
- package/dist/routes/automation-runs.d.ts +4 -0
- package/dist/routes/automation-runs.d.ts.map +1 -1
- package/dist/routes/automation-runs.js +15 -0
- package/dist/routes/automation-runs.js.map +1 -1
- package/dist/routes/boards.d.ts +1 -1
- package/dist/routes/boards.d.ts.map +1 -1
- package/dist/routes/boards.js +1 -17
- package/dist/routes/boards.js.map +1 -1
- package/dist/routes/config.d.ts +4 -0
- package/dist/routes/config.d.ts.map +1 -1
- package/dist/routes/config.js +15 -0
- package/dist/routes/config.js.map +1 -1
- package/dist/routes/contracts.d.ts +125 -14
- package/dist/routes/contracts.d.ts.map +1 -1
- package/dist/routes/contracts.js +34 -15
- package/dist/routes/contracts.js.map +1 -1
- package/dist/routes/fs.d.ts +4 -0
- package/dist/routes/fs.d.ts.map +1 -1
- package/dist/routes/fs.js +8 -4
- package/dist/routes/fs.js.map +1 -1
- package/dist/routes/intake-routes.d.ts.map +1 -1
- package/dist/routes/intake-routes.js.map +1 -1
- package/dist/routes/intake.d.ts.map +1 -1
- package/dist/routes/intake.js +1 -0
- package/dist/routes/intake.js.map +1 -1
- package/dist/routes/projects.d.ts.map +1 -1
- package/dist/routes/projects.js +8 -2
- package/dist/routes/projects.js.map +1 -1
- package/dist/routes/provider-credentials.d.ts.map +1 -1
- package/dist/routes/provider-credentials.js +10 -5
- package/dist/routes/provider-credentials.js.map +1 -1
- package/dist/routes/running-packages.d.ts +13 -0
- package/dist/routes/running-packages.d.ts.map +1 -0
- package/dist/routes/running-packages.js +45 -0
- package/dist/routes/running-packages.js.map +1 -0
- package/dist/routes/surface.d.ts +10 -1
- package/dist/routes/surface.d.ts.map +1 -1
- package/dist/routes/surface.js +104 -35
- package/dist/routes/surface.js.map +1 -1
- package/dist/routes/work-items.d.ts.map +1 -1
- package/dist/routes/work-items.js +23 -3
- package/dist/routes/work-items.js.map +1 -1
- package/dist/rules/binding-context.d.ts.map +1 -1
- package/dist/rules/binding-context.js +1 -0
- package/dist/rules/binding-context.js.map +1 -1
- package/dist/rules/dispatcher.d.ts +0 -1
- package/dist/rules/dispatcher.d.ts.map +1 -1
- package/dist/rules/dispatcher.js +340 -42
- package/dist/rules/dispatcher.js.map +1 -1
- package/dist/rules/event-rules.d.ts +33 -2
- package/dist/rules/event-rules.d.ts.map +1 -1
- package/dist/rules/event-rules.js +46 -11
- package/dist/rules/event-rules.js.map +1 -1
- package/dist/rules/index.d.ts +2 -4
- package/dist/rules/index.d.ts.map +1 -1
- package/dist/rules/index.js +2 -3
- package/dist/rules/phase-goal.d.ts +54 -0
- package/dist/rules/phase-goal.d.ts.map +1 -0
- package/dist/rules/phase-goal.js +70 -0
- package/dist/rules/phase-goal.js.map +1 -0
- package/dist/rules/phase-tools.d.ts +11 -0
- package/dist/rules/phase-tools.d.ts.map +1 -0
- package/dist/rules/phase-tools.js +19 -0
- package/dist/rules/phase-tools.js.map +1 -0
- package/dist/rules/processor.d.ts.map +1 -1
- package/dist/rules/processor.js +112 -11
- package/dist/rules/processor.js.map +1 -1
- package/dist/rules/review-source-tool.d.ts +4 -1
- package/dist/rules/review-source-tool.d.ts.map +1 -1
- package/dist/rules/review-source-tool.js +24 -4
- package/dist/rules/review-source-tool.js.map +1 -1
- package/dist/rules/rule-group.d.ts +1 -1
- package/dist/rules/rule-group.d.ts.map +1 -1
- package/dist/rules/rule-group.js +2 -1
- package/dist/rules/rule-group.js.map +1 -1
- package/dist/rules/start-coordinator.d.ts +5 -1
- package/dist/rules/start-coordinator.d.ts.map +1 -1
- package/dist/rules/start-coordinator.js +9 -3
- package/dist/rules/start-coordinator.js.map +1 -1
- package/dist/rules/tools.d.ts.map +1 -1
- package/dist/rules/tools.js +39 -28
- package/dist/rules/tools.js.map +1 -1
- package/dist/rules/transition-service.d.ts +2 -7
- package/dist/rules/transition-service.d.ts.map +1 -1
- package/dist/rules/transition-service.js +61 -54
- package/dist/rules/transition-service.js.map +1 -1
- package/dist/rules/types.d.ts +83 -29
- package/dist/rules/types.d.ts.map +1 -1
- package/dist/rules/types.js +5 -41
- package/dist/rules/types.js.map +1 -1
- package/dist/rules/validation.d.ts.map +1 -1
- package/dist/rules/validation.js +32 -2
- package/dist/rules/validation.js.map +1 -1
- package/dist/secret-encryption.d.ts +21 -0
- package/dist/secret-encryption.d.ts.map +1 -1
- package/dist/secret-encryption.js +31 -4
- package/dist/secret-encryption.js.map +1 -1
- package/dist/session/self-review-gate.d.ts +6 -2
- package/dist/session/self-review-gate.d.ts.map +1 -1
- package/dist/session/self-review-gate.js +8 -4
- package/dist/session/self-review-gate.js.map +1 -1
- package/dist/session/session-threads.d.ts +2 -3
- package/dist/session/session-threads.d.ts.map +1 -1
- package/dist/session/session-threads.js.map +1 -1
- package/dist/session/source-control-tools.js +1 -1
- package/dist/session/work-item-state-processor.d.ts +27 -0
- package/dist/session/work-item-state-processor.d.ts.map +1 -0
- package/dist/session/work-item-state-processor.js +288 -0
- package/dist/session/work-item-state-processor.js.map +1 -0
- package/dist/storage/domains/boards/base.d.ts +44 -27
- package/dist/storage/domains/boards/base.d.ts.map +1 -1
- package/dist/storage/domains/boards/base.js +76 -121
- package/dist/storage/domains/boards/base.js.map +1 -1
- package/dist/storage/domains/boards/schemas.d.ts.map +1 -1
- package/dist/storage/domains/boards/schemas.js +12 -0
- package/dist/storage/domains/boards/schemas.js.map +1 -1
- package/dist/storage/domains/work-items/base.d.ts +32 -2
- package/dist/storage/domains/work-items/base.d.ts.map +1 -1
- package/dist/storage/domains/work-items/base.js +109 -26
- package/dist/storage/domains/work-items/base.js.map +1 -1
- package/dist/storage/domains/work-items/cards.d.ts +24 -2
- package/dist/storage/domains/work-items/cards.d.ts.map +1 -1
- package/dist/storage/domains/work-items/cards.js +118 -8
- package/dist/storage/domains/work-items/cards.js.map +1 -1
- package/dist/storage/domains/work-items/legacy-review.d.ts +63 -0
- package/dist/storage/domains/work-items/legacy-review.d.ts.map +1 -0
- package/dist/storage/domains/work-items/legacy-review.js +95 -0
- package/dist/storage/domains/work-items/legacy-review.js.map +1 -0
- package/dist/storage/domains/work-items/metrics.d.ts +12 -4
- package/dist/storage/domains/work-items/metrics.d.ts.map +1 -1
- package/dist/storage/domains/work-items/metrics.js +14 -32
- package/dist/storage/domains/work-items/metrics.js.map +1 -1
- package/dist/storage/domains/work-items/work-item-schema.d.ts +2 -0
- package/dist/storage/domains/work-items/work-item-schema.d.ts.map +1 -1
- package/dist/storage/domains/work-items/work-item-schema.js +5 -0
- package/dist/storage/domains/work-items/work-item-schema.js.map +1 -1
- package/dist/tools/approval-tools.d.ts.map +1 -1
- package/dist/tools/approval-tools.js +28 -9
- package/dist/tools/approval-tools.js.map +1 -1
- package/dist/tools/index.d.ts +1 -1
- package/dist/tools/index.js +1 -1
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/messaging-tools.d.ts +3 -0
- package/dist/tools/messaging-tools.d.ts.map +1 -1
- package/dist/tools/messaging-tools.js +2 -1
- package/dist/tools/messaging-tools.js.map +1 -1
- package/dist/tools/read-tools.d.ts +8 -2
- package/dist/tools/read-tools.d.ts.map +1 -1
- package/dist/tools/read-tools.js +83 -23
- package/dist/tools/read-tools.js.map +1 -1
- package/dist/tools/reports.d.ts +1 -0
- package/dist/tools/reports.d.ts.map +1 -1
- package/dist/tools/reports.js +2 -1
- package/dist/tools/reports.js.map +1 -1
- package/dist/tools/run-watch.d.ts +1 -1
- package/dist/tools/run-watch.d.ts.map +1 -1
- package/dist/tools/run-watch.js +1 -0
- package/dist/tools/run-watch.js.map +1 -1
- package/dist/tools/sandbox-tools.js +1 -1
- package/dist/tools/session-tools.js +1 -1
- package/dist/tools/sessions-state-processor.d.ts +2 -0
- package/dist/tools/sessions-state-processor.d.ts.map +1 -1
- package/dist/tools/sessions-state-processor.js +4 -2
- package/dist/tools/sessions-state-processor.js.map +1 -1
- package/dist/tools/side-sessions.d.ts +2 -0
- package/dist/tools/side-sessions.d.ts.map +1 -1
- package/dist/tools/side-sessions.js +2 -1
- package/dist/tools/side-sessions.js.map +1 -1
- package/dist/tools/work-item-tools.js +3 -3
- package/dist/tools/work-item-tools.js.map +1 -1
- package/dist/work-item-branch.d.ts +13 -0
- package/dist/work-item-branch.d.ts.map +1 -1
- package/dist/work-item-branch.js +16 -1
- package/dist/work-item-branch.js.map +1 -1
- package/dist/work-items/create-work-item.d.ts +6 -0
- package/dist/work-items/create-work-item.d.ts.map +1 -1
- package/dist/work-items/create-work-item.js +25 -1
- package/dist/work-items/create-work-item.js.map +1 -1
- package/dist/work-items/split-migration.d.ts.map +1 -1
- package/dist/work-items/split-migration.js +1 -0
- package/dist/work-items/split-migration.js.map +1 -1
- package/dist/workspace.d.ts.map +1 -1
- package/dist/workspace.js +53 -10
- package/dist/workspace.js.map +1 -1
- package/factory-skills/configure-factory-rules/SKILL.md +11 -9
- package/factory-skills/factory-build/SKILL.md +64 -0
- package/factory-skills/factory-gitlab-rereview/SKILL.md +1 -1
- package/factory-skills/factory-gitlab-review/SKILL.md +2 -2
- package/factory-skills/factory-plan/SKILL.md +8 -10
- package/factory-skills/factory-rereview/SKILL.md +3 -3
- package/factory-skills/factory-review/SKILL.md +14 -4
- package/factory-skills/factory-self-review/SKILL.md +31 -11
- package/factory-skills/factory-triage/SKILL.md +25 -10
- package/package.json +9 -9
- package/dist/boards/index.js.map +0 -1
- package/dist/boards/pull-request-review.d.ts +0 -14
- package/dist/boards/pull-request-review.d.ts.map +0 -1
- package/dist/boards/pull-request-review.js +0 -81
- package/dist/boards/pull-request-review.js.map +0 -1
- package/dist/boards/work-tool-rules.d.ts +0 -8
- package/dist/boards/work-tool-rules.d.ts.map +0 -1
- package/dist/boards/work-tool-rules.js +0 -19
- package/dist/boards/work-tool-rules.js.map +0 -1
- package/dist/rules/resolve.d.ts +0 -15
- package/dist/rules/resolve.d.ts.map +0 -1
- package/dist/rules/resolve.js +0 -22
- package/dist/rules/resolve.js.map +0 -1
- package/factory-skills/factory-complete-issue/SKILL.md +0 -24
package/README.md
CHANGED
|
@@ -104,7 +104,7 @@ MASTRA_TELEMETRY_DISABLED=true
|
|
|
104
104
|
|
|
105
105
|
### Work items, sources and board placements
|
|
106
106
|
|
|
107
|
-
Factory separates the work (`factory_work_items`) from external facts (`factory_work_item_sources`) and placement/process state (`factory_board_items`). A work item can have several sources
|
|
107
|
+
Factory separates the work (`factory_work_items`) from external facts (`factory_work_item_sources`) and placement/process state (`factory_board_items`). A work item can have several sources. A pull request or merge request that belongs to an issue already on Work is attached to that issue's card as another source instead of getting a card of its own (see [One card for an issue and its pull requests](#one-card-for-an-issue-and-its-pull-requests)). The first source stays the card's primary source, so the card keeps the issue's title, state, labels and branch. Native cards have no external source. Sources are deduplicated per organization, project, provider and external ID, not claimed across projects. Board placements do not acquire, adopt, look up or release claims.
|
|
108
108
|
|
|
109
109
|
The split migration preserves legacy card IDs for comments, subscriptions, runs and URLs. It never rewrites the legacy `work_items` table. Board placements store `triage_type`, `accepted_at`, `autonomy_armed_at` and `plans_preapproved_at`; the existing consent and plan-grant rules apply to them unchanged. The unused `claim_key` column stays only in legacy storage and is never copied into the new tables. A deterministic legacy fingerprint detects changes even when an older replica does not update `updated_at`; conflicting newer split-side changes are reported rather than overwritten.
|
|
110
110
|
|
|
@@ -116,37 +116,41 @@ There is no dual-write rollback: an older Factory version sees the legacy snapsh
|
|
|
116
116
|
|
|
117
117
|
Each project's boards live in its database, and the stored row is the board.
|
|
118
118
|
|
|
119
|
-
- **Factory's boards**: the built-in Work board and the boards you pass to `new MastraFactory({ boards })` (app boards). Factory stores each in a project once: when the project is created, and in existing projects the first time a process loads them, which includes the preload at startup. The project keeps a key's board from then on. A Factory release or an app change never rewrites it, and a board the project deleted is not stored again. A key you add later is stored once in every project that hasn't had it. The
|
|
119
|
+
- **Factory's boards**: the built-in Work board and the boards you pass to `new MastraFactory({ boards })` (app boards). Factory stores each in a project once: when the project is created, and in existing projects the first time a process loads them, which includes the preload at startup. The project keeps a key's board from then on. A Factory release or an app change never rewrites it (except through a [board migration](#board-migrations)), and a board the project deleted is not stored again. A key you add later is stored once in every project that hasn't had it. The retired Review board is never stored, and its `review` key is reserved: no board can be created or written under it. A project that still has open cards on it is served the code Review board, read-only (see [The retired Review board](#the-retired-review-board)).
|
|
120
120
|
- **The project's own boards**: boards an admin created through the boards API, or that an app wrote with [`factory.upsertBoard()`](#writing-a-board-into-projects).
|
|
121
121
|
|
|
122
122
|
A project's boards are the Work and app boards in code order, followed by the others. The catalog, card creation through the API and Factory tools, transitions, the dispatcher, phase runs and the attention views all read that list. Existing apps need no change.
|
|
123
123
|
|
|
124
|
-
**Data model.** A stored board has a `key` (the ID cards reference as `board`), `name`, optional `description`, and ordered phases. A phase has a `key` (the stage ID), `name`, optional `description`, `kind`, and for working phases `runner` (`{ skill?, context?, instructions? }`), `autoStart`, `autoStartWhen` and `
|
|
124
|
+
**Data model.** A stored board has a `key` (the ID cards reference as `board`), `name`, optional `description`, and ordered phases. A phase has a `key` (the stage ID), `name`, optional `description`, `kind`, and for working phases `runner` (`{ skill?, context?, instructions?, goal? }`), `autoStart`, `autoStartWhen`, `exitTool` (`{ id, autoApprove?, autoApproveWhen? }`) and `tools`, plus `nextPhases`. The first phase is the initial phase and must be `resting`. Saved boards pass the same checks `defineBoard()` applies, with the same messages. A phase's behaviour is exactly these fields (see [Phase runners, automatic starts and exit tools](#phase-runners-automatic-starts-and-exit-tools)): every working phase, on any board, starts its `runner` on entry. A board under a key no code board uses has no code behaviour besides that: no transition policy, `sourceClosed`, or tool and event rules.
|
|
125
125
|
|
|
126
126
|
`nextPhases` on a stored board: leaving it out (or `null`) on a resting or working phase allows moves to every other phase, `[]` allows none, and a terminal phase allows none unless it lists some.
|
|
127
127
|
|
|
128
|
-
**Editing the Work board and app boards.** The catalog and `GET …/boards/:boardKey` report each board's `source` (`builtin`, `app` or `stored`) and `editable` (`
|
|
128
|
+
**Editing the Work board and app boards.** The catalog and `GET …/boards/:boardKey` report each board's `source` (`builtin`, `app` or `stored`) and `editable` (`true` for every board but the retired Review board, which a project still using it is served read-only). `PATCH` replaces the project's board. Factory serves the stored fields with the board-level code behaviour of its key attached: tool and event rules, `sourceClosed` and the transition policy. No code runs when a card enters or leaves a phase: what a phase starts is its stored runner, so an edited runner is what runs.
|
|
129
129
|
|
|
130
130
|
What code behaviour depends on stays fixed, and an edit that changes it is refused with `422 code_behaviour`, listing every conflict:
|
|
131
131
|
|
|
132
|
-
- Every phase the code declares stays, with the same `kind`, and the code's initial phase stays first.
|
|
133
|
-
-
|
|
134
|
-
- A declared exit tool (`submit_plan` on Planning) keeps its `id`. Its `autoApprove` and `autoApproveWhen` are yours. A phase whose code handlers move cards on without an exit tool can't get one: it would hold those moves back.
|
|
135
|
-
- Every move the code board allows from a phase stays in its `nextPhases`. Code makes those moves itself: an approved plan moves Planning to Building, a merged or closed pull request moves its card to Done or Canceled, and integration rules move cards between phases. You can add moves.
|
|
132
|
+
- Every phase the code declares stays, with the same `kind`, and the code's initial phase stays first. `sourceClosed` needs its phases terminal (Done and Canceled on Work).
|
|
133
|
+
- Every move the code board allows from a phase stays in its `nextPhases`. Code makes those moves itself: a merged or closed pull request moves its card to Done or Canceled, and integration rules move cards between phases. You can add moves. The boards API reports these moves per phase as `codeBehaviour.<phase>.requiredNextPhases`.
|
|
136
134
|
|
|
137
|
-
Everything else can change: names and descriptions,
|
|
135
|
+
Everything else can change: names and descriptions, every runner field (skill, context, instructions and goal), `autoStart` and `autoStartWhen`, the exit tool and its approval, phase `tools`, added `nextPhases`, the order of phases after the first, and new phases.
|
|
138
136
|
|
|
139
137
|
**When Factory's definition changes.** A project keeps the board it stored, so a newer Work default or a changed app board doesn't reach it on its own. `POST …/boards/:boardKey/reset` with `expectedRevision` rewrites the board to Factory's current definition for its key (Work or an app board) at the next revision; revisions never go back, so a client holding an older revision is refused.
|
|
140
138
|
|
|
141
|
-
**Boards that no longer fit the code.** A Work or app board is served even when it has fallen out of step with a newer release's code, with the code behaviour that still fits it.
|
|
139
|
+
**Boards that no longer fit the code.** A Work or app board is served even when it has fallen out of step with a newer release's code, with the code behaviour that still fits it. The board's tool rules always stay; its event rules and transition policy need every phase the code declares, and `sourceClosed` needs both its phases, still terminal. A move Factory's code makes that the board's `nextPhases` don't allow is reported too; when code makes it, the move is refused (and retried until its attempts run out), and the card stays where it is. Each dropped behaviour is reported in the board's `problems`, for example `Board "release" runs without its code event rules (…): phase "testing" isn't stored.` or `Board "work" doesn't let phase "planning" move cards to "execute", so Factory's code can't make that move.` A board stored under an app board's key that the app stopped defining is served as one of the project's own boards.
|
|
142
140
|
|
|
143
|
-
Creating a board under a built-in or app board's key is refused with `409 code_board`, and so is deleting the Work board, whose code
|
|
141
|
+
Creating a board under a built-in or app board's key is refused with `409 code_board`, and so is deleting the Work board, whose code rules run by its key; reset it instead. App boards can be deleted like the project's own; Factory doesn't store them again, and `factory.upsertBoard()` brings one back. The retired Review board's `review` key is reserved: creating, editing, resetting or deleting a board under it is refused with `409 reserved_board`, because a new board under that key would take over the cards stored there.
|
|
144
142
|
|
|
145
|
-
**When a board isn't stored.** If storing Factory's boards in a project fails, the boards it couldn't store aren't served, the catalog reports `Board "<key>" isn't stored in this project yet; Factory stores it on the next load.`, and `GET …/boards/:boardKey` answers `404 board_not_found`; the project's next load tries again. Factory serves code boards itself only for
|
|
143
|
+
**When a board isn't stored.** If storing Factory's boards in a project fails, the boards it couldn't store aren't served, the catalog reports `Board "<key>" isn't stored in this project yet; Factory stores it on the next load.`, and `GET …/boards/:boardKey` answers `404 board_not_found`; the project's next load tries again. Factory serves code boards itself only for every project when the boards storage could not start, and on a replica that has not loaded a project yet, until its first load.
|
|
144
|
+
|
|
145
|
+
#### Board migrations
|
|
146
|
+
|
|
147
|
+
A release that changes what Factory's own boards need can carry a board migration: a one-time change to the project's stored copy that fills only fields still holding the value Factory stored before, so every field a person edited stays as they left it. Each project gets each migration once, on its first load after the upgrade; the keys applied are recorded on the project's board version row in the same transaction as the write, so concurrent replicas apply it once, and a field a person later sets back to an old default is never rewritten. A migration writes the board at the next revision as `factory` and logs one line per project naming the fields it filled. A fresh project is stored with the current board and records the migration without a change.
|
|
148
|
+
|
|
149
|
+
`work-phase-runners-v1` gives a project's Work board the runners of this release, field by field per phase: `runner`, `exitTool`, `tools`, `autoStart`, `autoStartWhen` and `nextPhases`. A field is filled only while it equals what earlier releases stored (for example Triage's runner `{ context: 'triage' }`); `nextPhases` only when the stored list is the old one exactly and every added phase is on the board; a runner is filled part by part (its `skill` and `goal` when unset, its `context` while it is the old default), so instructions a person wrote stay. A Building runner whose moves a person narrowed gets the skill without the goal. The migration runs only on Factory's own Work board, never on an app board under the `work` key. A phase the board no longer has, or holds as another kind, is left alone. An `autoStart` of `false` reads the same as unset, so Review's becomes `true` even where an admin had set it to `false`.
|
|
146
150
|
|
|
147
151
|
#### Writing a board into projects
|
|
148
152
|
|
|
149
|
-
`factory.upsertBoard()` writes a board definition into projects after `prepare()`: each named project (or all of them) that has no board under its key gets it, and each one that has it, edited or not, has it replaced at the next revision. Factory doesn't run it for you, so projects created later don't get the board until you run it again; run it from an admin script, or after `prepare()` when you want every project to have the definition you ship. The board is checked once, as the boards API checks it, each replacement passes the checks an edit does (cards in a removed phase refuse it with `phase_in_use` there), and each write is audited as `factory.board.created` or `factory.board.updated` by `system:factory`. It returns the projects it stored the board in, the ones it replaced it in, and the ones that already had it unchanged. A refused board throws `BoardWriteError`, whose `code` is the boards API's error code (`invalid_board`, `unknown_skill`, `code_behaviour`, `phase_in_use`, `project_not_found`, or `
|
|
153
|
+
`factory.upsertBoard()` writes a board definition into projects after `prepare()`: each named project (or all of them) that has no board under its key gets it, and each one that has it, edited or not, has it replaced at the next revision. Factory doesn't run it for you, so projects created later don't get the board until you run it again; run it from an admin script, or after `prepare()` when you want every project to have the definition you ship. The board is checked once, as the boards API checks it, each replacement passes the checks an edit does (cards in a removed phase refuse it with `phase_in_use` there), and each write is audited as `factory.board.created` or `factory.board.updated` by `system:factory`. It returns the projects it stored the board in, the ones it replaced it in, and the ones that already had it unchanged. A refused board throws `BoardWriteError`, whose `code` is the boards API's error code (`invalid_board`, `unknown_skill`, `code_behaviour`, `phase_in_use`, `project_not_found`, or `reserved_board` for the retired Review board's `review` key). A board under a new key has no code behaviour; an app board's key keeps the app board's, so it also brings back an app board a project deleted.
|
|
150
154
|
|
|
151
155
|
```ts
|
|
152
156
|
const bugs = {
|
|
@@ -176,14 +180,14 @@ const { inserted, updated, unchanged } = await factory.upsertBoard(bugs, { proje
|
|
|
176
180
|
|
|
177
181
|
**Routes.** All need project membership; changes need an organization admin when auth is enabled, and are recorded in the audit log as `factory.board.created`, `updated`, `deleted` and `reset`.
|
|
178
182
|
|
|
179
|
-
| Method | Path | Body | Result
|
|
180
|
-
| -------- | --------------------------------------------------------------- | ------------------------------------------------------- |
|
|
181
|
-
| `GET` | `/web/factory/projects/:id/boards` | — | The catalog, with each board's `source`, `editable` and `problems`.
|
|
182
|
-
| `GET` | `/web/factory/projects/:id/boards/:boardKey` | — | The definition, `revision
|
|
183
|
-
| `POST` | `/web/factory/projects/:id/boards` | The board, with `key`. | `201` and the board. `409 code_board` for a code board's key, `409 board_exists` for a stored board's
|
|
184
|
-
| `PATCH` | `/web/factory/projects/:id/boards/:boardKey` | The whole board without `key`, plus `expectedRevision`. | The board. Replaces every field. `422 code_behaviour` for an edit code behaviour can't honour, `409
|
|
185
|
-
| `POST` | `/web/factory/projects/:id/boards/:boardKey/reset` | `{ expectedRevision }` | The board, rewritten to Factory's current definition at the next revision. `409 not_code_board` for the project's own boards, `409
|
|
186
|
-
| `DELETE` | `/web/factory/projects/:id/boards/:boardKey?expectedRevision=n` | — | `204`. `409 code_board` for the Work
|
|
183
|
+
| Method | Path | Body | Result |
|
|
184
|
+
| -------- | --------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
185
|
+
| `GET` | `/web/factory/projects/:id/boards` | — | The catalog, with each board's `source`, `editable` and `problems`. |
|
|
186
|
+
| `GET` | `/web/factory/projects/:id/boards/:boardKey` | — | The definition, `revision`, `source`, `editable`, `problems`, `codeBehaviour` (per phase: `requiredNextPhases`, the moves Factory's code makes from it) and `canEdit` (whether you may change it). |
|
|
187
|
+
| `POST` | `/web/factory/projects/:id/boards` | The board, with `key`. | `201` and the board. `409 code_board` for a code board's key, `409 board_exists` for a stored board's, `409 reserved_board` for `review`. |
|
|
188
|
+
| `PATCH` | `/web/factory/projects/:id/boards/:boardKey` | The whole board without `key`, plus `expectedRevision`. | The board. Replaces every field. `422 code_behaviour` for an edit code behaviour can't honour, `409 reserved_board` for `review`. |
|
|
189
|
+
| `POST` | `/web/factory/projects/:id/boards/:boardKey/reset` | `{ expectedRevision }` | The board, rewritten to Factory's current definition at the next revision. `409 not_code_board` for the project's own boards, `409 reserved_board` for `review`. |
|
|
190
|
+
| `DELETE` | `/web/factory/projects/:id/boards/:boardKey?expectedRevision=n` | — | `204`. `409 code_board` for the Work board, `409 reserved_board` for `review`. |
|
|
187
191
|
|
|
188
192
|
A stale `expectedRevision` is refused with `409 revision_mismatch`; reload the board and try again.
|
|
189
193
|
|
|
@@ -228,15 +232,15 @@ Admins can make the same edits in the Factory UI under **Settings → Work board
|
|
|
228
232
|
[Mastra Factory] MastraFactory({ boards }) and defineBoard() are deprecated: boards live in the database, and each project stores these definitions once. Write board definitions into projects with factory.upsertBoard(), or manage them through the boards API; see the README "Stored boards" section and mastra-ai/mastra#28920.
|
|
229
233
|
```
|
|
230
234
|
|
|
231
|
-
`includeDefaultBoards` decides whether projects get the built-in Work board
|
|
235
|
+
`includeDefaultBoards` decides whether projects get the built-in Work board.
|
|
232
236
|
|
|
233
|
-
Using only the built-in boards logs nothing. A board that cards reach only through the API, the Factory UI or Factory tools, and that needs no
|
|
237
|
+
Using only the built-in boards logs nothing. A board that cards reach only through the API, the Factory UI or Factory tools, and that needs no policies or rules, can move off code: write its definition under a new key into projects with `factory.upsertBoard()`, move its cards, then stop passing the code board. Keep passing a board while integrations file cards onto it, intake bindings or label routes target it, or it needs code behaviors.
|
|
234
238
|
|
|
235
239
|
Removing `defineBoard()` still needs code behaviour that stored boards can reference by name, and integrations that read each project's boards. That work is tracked in [mastra-ai/mastra#28920](https://github.com/mastra-ai/mastra/issues/28920).
|
|
236
240
|
|
|
237
241
|
### Board lifecycle rules
|
|
238
242
|
|
|
239
|
-
|
|
243
|
+
A phase starts work only through its stored `runner` (see [Phase runners, automatic starts and exit tools](#phase-runners-automatic-starts-and-exit-tools)); no code runs when a card enters or leaves a phase. Work is installed automatically with Mastra's preferred defaults; no rule configuration is needed. `defineBoard()`, which is deprecated but still works, declares a custom board's phases with the same fields:
|
|
240
244
|
|
|
241
245
|
```typescript
|
|
242
246
|
import { MastraFactory } from '@mastra/factory';
|
|
@@ -248,14 +252,14 @@ const releaseBoard = defineBoard({
|
|
|
248
252
|
name: 'Release',
|
|
249
253
|
initialPhase: 'backlog',
|
|
250
254
|
phases: {
|
|
251
|
-
backlog: { name: 'Backlog', kind: 'resting', nextPhases: ['
|
|
252
|
-
|
|
253
|
-
name: '
|
|
254
|
-
kind: '
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
},
|
|
255
|
+
backlog: { name: 'Backlog', kind: 'resting', nextPhases: ['notes'] },
|
|
256
|
+
notes: {
|
|
257
|
+
name: 'Release notes',
|
|
258
|
+
kind: 'working',
|
|
259
|
+
runner: { context: 'writer', skill: 'release-notes', instructions: 'Keep it short.' },
|
|
260
|
+
nextPhases: ['done'],
|
|
258
261
|
},
|
|
262
|
+
done: { name: 'Done', kind: 'terminal' },
|
|
259
263
|
},
|
|
260
264
|
});
|
|
261
265
|
|
|
@@ -264,7 +268,15 @@ export function createFactory(storage: MastraFactoryConfig['storage']) {
|
|
|
264
268
|
}
|
|
265
269
|
```
|
|
266
270
|
|
|
267
|
-
|
|
271
|
+
**`onEnter`, `onExit` and `outcomes` are ignored.** Earlier releases let a code board's phases run source-specific `onEnter` and `onExit` handlers and name moves with `outcomes`. `defineBoard()` still accepts these fields, so existing boards compile, but no handler runs: a phase starts its `runner.skill` instead, and an outcome's target only stays one of the phase's allowed moves. Factory logs once per board:
|
|
272
|
+
|
|
273
|
+
```text
|
|
274
|
+
[Mastra Factory] Board "release" uses deprecated fields: phases.notes.outcomes → nextPhases. They still work but will be removed in a future release. It also declares phases.notes.onEnter, which are ignored; use runner.skill to start a phase's run.
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
To migrate, move each handler's skill into the phase's `runner.skill` (its prompt into `runner.instructions` or the skill), put card context the handler read into the skill (agents get it from the [`factory-work-item` signal](#the-factory-work-item-signal)), and list outcome targets in `nextPhases`. A handler that refused a move becomes a `transitionPolicy` rejection (`nextPhases` is the only limit on where a card may go).
|
|
278
|
+
|
|
279
|
+
To replace Work, disable the default board and install a board with the same ID. Projects created after that store your board. Existing projects keep the Work board they already stored until an admin resets it or you write yours into them with `factory.upsertBoard()`. You can reinstall the exported `workBoard` definition unchanged, or use its phases as the starting point for a customized definition:
|
|
268
280
|
|
|
269
281
|
```typescript
|
|
270
282
|
import { MastraFactory, workBoard } from '@mastra/factory';
|
|
@@ -276,27 +288,11 @@ const factory = new MastraFactory({
|
|
|
276
288
|
});
|
|
277
289
|
```
|
|
278
290
|
|
|
279
|
-
Board IDs must be unique among the installed boards, so a same-ID board still throws while the defaults are enabled. Cards stored before board tracking resolve to `work
|
|
280
|
-
|
|
281
|
-
**Preferred intake behavior:** By default, every integration arrival lands in its routed board's initial phase—Intake for Work and Review—and does not start or suggest a run. This includes GitHub, GitLab, Linear, Jira, and incident.io; Linear, Jira, and incident.io no longer land directly in Triage. Only custom routes or explicit placement rules choose a different phase. Trusted maintainer requests to review a GitHub pull request with no existing card file it directly in Reviewing.
|
|
282
|
-
|
|
283
|
-
The `authorTrusted` and `autoStartCandidate` metadata stamps remain available for custom board rules. For example, a custom board can restore guarded arrival triage on its initial phase:
|
|
291
|
+
Board IDs must be unique among the installed boards, so a same-ID board still throws while the defaults are enabled. Cards stored before board tracking resolve to `work`, and some runtime and UI behavior is keyed to those IDs, including Work issue intake and triage, the review-requested filter, and funnel metrics. Keep the built-in phase names and contexts in a replacement unless you intend to change that behavior.
|
|
284
292
|
|
|
285
|
-
|
|
286
|
-
const intakeRule = context =>
|
|
287
|
-
context.cause === 'linked_item_materialized' && context.item.metadata?.autoStartCandidate === true
|
|
288
|
-
? {
|
|
289
|
-
type: 'invokeSkill',
|
|
290
|
-
idempotencyKey: `${context.ingress.id}:factory-triage`,
|
|
291
|
-
role: 'triage',
|
|
292
|
-
skillName: 'factory-triage',
|
|
293
|
-
}
|
|
294
|
-
: undefined;
|
|
295
|
-
```
|
|
293
|
+
**Preferred intake behavior:** By default, every integration arrival lands in its routed board's initial phase—Intake for Work—and does not start or suggest a run. This includes GitHub, GitLab, Linear, Jira, and incident.io. An [intake route](#intake-routes) can file new cards straight into another phase, such as Triage, whose runner then starts (on its own when the phase's `autoStart` or `autoStartWhen` allows it). Trusted maintainer requests to review a GitHub pull request with no existing card file it directly in Work's Review.
|
|
296
294
|
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
There is no global rules object. Every rule has one owner: boards own lifecycle handlers, topology (`nextPhases`), phase semantics, tool-result rules, and how their cards react to integration events; integrations own their default event handlers. The runtime only executes rules.
|
|
295
|
+
There is no global rules object. Every rule has one owner: boards own their phases (runners, topology, exit tools), tool-result rules, and how their cards react to integration events; integrations own their default event handlers. The runtime only executes rules.
|
|
300
296
|
|
|
301
297
|
### Closing cards when their source closes
|
|
302
298
|
|
|
@@ -345,7 +341,7 @@ const releaseBoard = defineBoard({
|
|
|
345
341
|
|
|
346
342
|
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.
|
|
347
343
|
|
|
348
|
-
The default Work board declares
|
|
344
|
+
The default Work board declares no tool rules: Planning's exit tool `submit_plan` holds the card until the plan is approved, then `factory-plan` moves it to Building (see [Phase runners, automatic starts and exit tools](#phase-runners-automatic-starts-and-exit-tools)), and the builder opens the change request itself (on a board with a self-review phase, the self-review skill opens it once it approves). Rules resolve from the installed board, so a replacement `work` board can declare its own `tools.<name>.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.
|
|
349
345
|
|
|
350
346
|
### Board event rules
|
|
351
347
|
|
|
@@ -392,9 +388,9 @@ For each event, Factory picks the handler in this order:
|
|
|
392
388
|
2. The card's board handler. `null` switches the event off for cards on that board only; cards on other boards are unaffected.
|
|
393
389
|
3. The integration default.
|
|
394
390
|
|
|
395
|
-
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
|
|
391
|
+
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 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.
|
|
396
392
|
|
|
397
|
-
Every integration rule context bound to a card carries `phase`: `{ id, kind, context?, nextPhases
|
|
393
|
+
Every integration rule context bound to a card carries `phase`: `{ id, kind, context?, nextPhases }`, 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. `phase` is absent when the card sits in more than one stage or its board does not declare the phase.
|
|
398
394
|
|
|
399
395
|
Unknown integrations, unknown event names, and handler values other than a function or `null` are rejected by `defineBoard` with a `BoardDefinitionError`.
|
|
400
396
|
|
|
@@ -419,27 +415,30 @@ Contexts that carried `ruleSetVersion` now carry `configVersion`. To add a tool-
|
|
|
419
415
|
|
|
420
416
|
### Where cards can move
|
|
421
417
|
|
|
422
|
-
Boards own two separate concerns: topology (`nextPhases`) declares which moves exist, and
|
|
418
|
+
Boards own two separate concerns: topology (`nextPhases`) declares which moves exist, and each working phase's runner starts the work on entry. `nextPhases` binds everyone: people dragging cards on the Factory board, agents calling `factory_transition_work_item`, and board rules. A move it does not list is rejected with `invalid_transition`. Staying in the same phase is always allowed.
|
|
423
419
|
|
|
424
420
|
The built-in Work board lists these moves:
|
|
425
421
|
|
|
426
|
-
| From
|
|
427
|
-
|
|
|
428
|
-
| Intake
|
|
429
|
-
| Triage
|
|
430
|
-
| Planning
|
|
431
|
-
| Building
|
|
432
|
-
| Review
|
|
433
|
-
|
|
|
434
|
-
|
|
|
435
|
-
| Canceled | Intake, PR review | A canceled card is reopened in Intake; a reopened pull request goes back to PR review. |
|
|
422
|
+
| From | To | Why |
|
|
423
|
+
| -------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
424
|
+
| Intake | Triage, Planning, Review, Done, Canceled | Never straight to Building: a plan comes first. Review takes a card that carries a pull request; Done is where a completed source closes it. |
|
|
425
|
+
| Triage | Intake, Planning, Done, Canceled | A confirmed bug goes to Planning; any other open issue waits in Intake for a person. |
|
|
426
|
+
| Planning | Building, Intake, Done, Canceled | Into Building only through the approved plan (see `exitTool` below). |
|
|
427
|
+
| Building | Review, Planning, Done, Canceled | Review once the builder opened the change request; Planning again when the build shows the plan was wrong. |
|
|
428
|
+
| Review | Intake, Planning, Building, Done, Canceled | A card with a pull request: merged, closed, or set aside in Intake. A pull request's own card never reaches the builder's lanes. |
|
|
429
|
+
| Done | Review | A review request on a finished pull request reopens its review. |
|
|
430
|
+
| Canceled | Intake, Review | A canceled card is reopened in Intake; a reopened pull request goes back to Review. |
|
|
436
431
|
|
|
437
|
-
|
|
432
|
+
Work's Review phase is keyed `pr-review`: it reviews a card's pull request.
|
|
438
433
|
|
|
439
|
-
|
|
434
|
+
A pull request's own card only enters Intake, Review, Done and Canceled, and only a card that carries a pull request (its own, or one attached to an issue card) enters Review, for people too. An issue card with an attached pull request can still go back to Planning or Building for a fix; Intake leads to both Triage and Review and which one fits depends on the card, so this one rule stays in code (`workPullRequestCardRejection`). Planning ends with `submit_plan`, its exit tool: a plan waits for a person to approve it, and the approved plan moves the card to Building. Whether work is finished (no open pull request, no review asking for changes) is not checked by the board: the build instructions tell the agent when to move a card to Done. Intake is resting, so nothing runs on a card parked there; an agent in another session could still move it.
|
|
440
435
|
|
|
441
436
|
**Triage.** The triage agent sends a confirmed bug to Planning, an open non-bug back to Intake, and closures to Done or Canceled. A person moving the card on from Intake is the approval; Factory records no classification or acceptance, and that move removes the `status: needs approval` label from the GitHub issue. On boot, Factory moves any card left in Triage by the old classify-and-accept rule back to Intake, once.
|
|
442
437
|
|
|
438
|
+
**A board without an approval wait.** A board that should start work on its own says so in its triage phase's `runner.instructions` (for example `This board needs no approval before work starts.`). factory-triage then sends an open feature request, docs or maintenance item from a trusted author, that the repository would take on, to the phase a confirmed bug goes to (Planning on Work) instead of back to rest, and adds no `status: needs approval` label. Untrusted authors, questions and anything to close still rest or close as before. The agent's move starts the planning run without a person, whether or not that phase has `autoStart`: an agent's move consents to the runs it queues. Work's triage phase has no instructions, so Work keeps its approval wait.
|
|
439
|
+
|
|
440
|
+
**Labels on a new repository.** factory-triage and factory-build create each GitHub label they add (`status: needs triage`, `status: auto-triaged`, `status: needs approval`, `status: pending-close`, `effort:*`, `impact:*`, `severity:*`) when the repository doesn't have it, and add one label per call, so a missing label never costs the others.
|
|
441
|
+
|
|
443
442
|
**Migration:** `transitionPolicy` on `defineBoard()` is deprecated. It still runs for boards that set it, and `defineBoard()` logs one warning per board. Its context no longer carries a requested classification, and `triageType` and `accept` on an `allow` are ignored. Express the flow with each phase's `nextPhases` and `exitTool` instead:
|
|
444
443
|
|
|
445
444
|
```typescript
|
|
@@ -453,6 +452,8 @@ transitionPolicy: context => {
|
|
|
453
452
|
nextPhases: ['build'],
|
|
454
453
|
```
|
|
455
454
|
|
|
455
|
+
The built-in Work and Review boards no longer declare a transition policy, so `workBoard.transitionPolicy` and `reviewBoard.transitionPolicy` are `undefined`. A board that wraps either one and calls its policy (for example `context => workBoard.transitionPolicy!(context)`) throws `transitionPolicy is not a function` on every transition, recorded as a `rule_error`. Drop the delegating call; keep only your own checks, or move them to `nextPhases` and `exitTool`.
|
|
456
|
+
|
|
456
457
|
Rule contexts still carry `acceptedAt`, deprecated: it is the stamp on older cards and `null` for cards since.
|
|
457
458
|
|
|
458
459
|
### Board phase semantics
|
|
@@ -476,13 +477,66 @@ const releaseBoard = defineBoard({
|
|
|
476
477
|
});
|
|
477
478
|
```
|
|
478
479
|
|
|
479
|
-
Work declares `intake` resting; `triage`, `planning`, `execute
|
|
480
|
+
Work declares `intake` resting; `triage`, `planning`, `execute` and `pr-review` (named Review, the independent review of a card's pull request) working; `done` and `canceled` terminal. Its working phases run on stored runners, which an admin can edit:
|
|
481
|
+
|
|
482
|
+
| Phase | Runner | Also |
|
|
483
|
+
| -------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
484
|
+
| Triage | `factory-triage` in `triage` | Investigates the issue; a card labelled `status: needs approval` gets a summary of the decision needed instead. |
|
|
485
|
+
| Planning | `factory-plan` in `work` | Exit tool `submit_plan`, never auto-approved; once the plan is approved the planner moves the card to Building. |
|
|
486
|
+
| Building | `factory-build` in `work`, as a goal (up to 20 runs) | Builds the approved plan, runs its gates and pushes, then opens the change request and moves the card to Review. |
|
|
487
|
+
| Review | `factory-review` in `review` | Grants `factory_record_review_verdict` and `factory_review_source`. |
|
|
488
|
+
|
|
489
|
+
#### Self-review is a board's choice
|
|
490
|
+
|
|
491
|
+
Work has no self-review phase: Building opens the change request itself. Self-review stays a capability any board can add. A working phase in the `review` context that grants only `factory_record_review_verdict` (not `factory_review_source`), and that the build phase can move into, is the board's self-review phase ([the pull request loop on any board](#the-pull-request-loop-on-any-board)). There `factory-self-review` tests the builder's pushed branch before any change request exists: requesting changes sends the card back to the build phase, approving opens the change request from the approved head and moves the card to the board's pull request review phase, and at its round limit it parks the card in the board's first phase. While the project's self-review setting is on, a change request opened from the build phase is refused until self-review approves. The setting, and the self-review switch on the board, only show on a board that has such a phase.
|
|
492
|
+
|
|
493
|
+
```typescript
|
|
494
|
+
check: {
|
|
495
|
+
name: 'Self-review',
|
|
496
|
+
kind: 'working',
|
|
497
|
+
runner: { skill: 'factory-self-review', context: 'review' },
|
|
498
|
+
autoStart: true,
|
|
499
|
+
autoStartWhen: { operator: 'AND', conditions: [{ field: 'item.pullRequest', operator: 'not_exists' }] },
|
|
500
|
+
tools: ['factory_record_review_verdict'],
|
|
501
|
+
nextPhases: ['build', 'inbox', 'pr'],
|
|
502
|
+
},
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
Projects stored before Work dropped its self-review phase keep it: their Work row is their board, so it still holds the `review` phase (named Review) between Building and PR review, and runs it as before. Nothing is migrated. To drop it from such a project, edit the Work board: remove the phase and Building's move to it.
|
|
506
|
+
|
|
507
|
+
The agent that finishes a card's work cleans up the source issue's status labels (removes `status: needs triage`, `status: auto-triaged` and `status: needs approval`, adds `status: pending-close` and posts a done comment) before it moves the card to Done; a merged pull request that closes the issue moves the card there through the intake routes. Done itself starts nothing: earlier releases ran that cleanup on every entry into Done, so an issue card a merge or a person moves to Done now keeps its labels and gets no comment. The definition exposes the derived helpers `phaseKind`, `isWorking`, `isTerminal`, `roleForPhase`, and `phaseForRole`.
|
|
508
|
+
|
|
509
|
+
A new pull request or merge request that belongs to a card already on a board that reviews pull requests (Work, or any board with a [pull request loop](#the-pull-request-loop-on-any-board)) is attached to that card (see below). One with no such card gets its own card in Work Intake or Review, as the intake routes decide. The card's Review action moves it into Work's Review phase (`pr-review`), where an independent reviewer runs `factory-review` in the card's `review` session; the skill follows the GitLab or re-review procedure the `factory-work-item` signal names for the card. A pull request's own card never enters a board's self-review phase. A pull request's own card only enters Intake, Review, Done, and Canceled; merging moves it to Done and closing it unmerged to Canceled.
|
|
510
|
+
|
|
511
|
+
#### One card for an issue and its pull requests
|
|
512
|
+
|
|
513
|
+
When Factory first sees a pull request (GitHub `pull_request.opened`) or merge request (GitLab `open`), it looks for a home card in the same Factory project and repository. The home card must be on a board that reviews pull requests, not in one of its terminal phases, and not a pull request's own card. Factory checks, in order:
|
|
514
|
+
|
|
515
|
+
1. **A pull request Factory opened for one of its cards** goes to that card, found by provenance or by the head branch matching the card's session branch. On GitHub that card must be a GitHub issue card from the same repository; on GitLab, any card with an issue of its own (GitLab, Linear, Jira or incident.io). A manual card never takes one, since the pull request would become its only source; its pull request gets a separate card. A card still in Building moves to the board's pull request review phase (on a board with self-review, that phase opens the pull request itself, so it has been skipped). A review request or `@<app> review` still sends it there.
|
|
516
|
+
2. **A pull request that closes an issue** can join that issue's card if a project [intake route](#intake-routes) with a `joinClosedIssue` target says so. Factory reads closing keywords from the pull request body or merge request description: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`, and on GitLab also `implement`, `implements`, `implemented`, `implementing`. The target is `#N`, or `owner/repo#N` (`group/project#N`) naming the same repository. References to other repositories, links, and code spans don't count. If the pull request names several issues, the first one with an eligible card is the one routes see. The default route joins a trusted author's pull request to a card still waiting in Intake with no pull request yet, and moves that card to Review. Once the card has moved on (Triage, Planning or Building), or already carries a pull request, someone else's pull request gets its own card in Review and is reviewed right away. Done and Canceled cards are finished, so a pull request for them gets its own card too.
|
|
517
|
+
3. **Anything else** gets its own card, exactly as before.
|
|
518
|
+
|
|
519
|
+
An untrusted author's pull request never attaches, even when it says `fixes #12` and a route would allow it: it gets its own card in Intake, so an outside author can't take over a trusted card or its sessions. Linking only happens on first sighting: editing the body later doesn't move a pull request onto or off a card, and a replayed delivery doesn't attach it twice. A link made only in GitHub's sidebar isn't visible in the webhook, so that pull request gets its own card. The reconcile sweep doesn't carry the body either, so closing references are only read from live deliveries.
|
|
520
|
+
|
|
521
|
+
Any card that enters Work's Review (`pr-review`), or another board's pull request review phase, carrying a pull request starts the reviewer, whatever its own source. On a card with an attached pull request, the pull request's state lives on its own source, and the issue keeps its own; a reopened merge request is open on the card again. `openPullRequestNumber` only names a pull request the card's own sessions opened (its head is one of the card's session branches, or the branch Factory builds the card on). When that pull request closes, it moves to the card's next open one of its own, or clears, never to someone else's, so another person's pull request never switches off the builder's self-review or its own pull request. When a pull request merges, the card moves to Done unless another one is still open, in which case its session is told which one is out. When one closes unmerged, a card in Review with no open pull request left goes back to Intake. The reviewer checks out the pull request on its own branch (`factory/pr-<n>-…`, `factory/gitlab-mr-<n>-…`) in an untrusted checkout, never in the builder's session or branch.
|
|
522
|
+
|
|
523
|
+
#### The retired Review board
|
|
524
|
+
|
|
525
|
+
New projects get no Review board; Work's Review phase (`pr-review`) does its job. Nothing in the database is migrated. Whether an existing project keeps the board is decided per project when its boards and cards are read:
|
|
480
526
|
|
|
481
|
-
|
|
527
|
+
- **Still in use**: the project has at least one card stored on `review` that isn't in Done or Canceled. It keeps the Review board exactly as before: the board is served (read-only), its cards stay on it in their phases, Review and Re-review start the reviewer in its Reviewing phase, and merging or closing a pull request moves its card to Done or Canceled there. No card can be created on it. `/factories/:id/review` opens it.
|
|
528
|
+
- **Redundant**: every card stored on `review` is in Done or Canceled, or there are none. The board isn't served. Those cards read as Work cards (Intake, Done and Canceled are unchanged; `review` reads as `pr-review`), and the next normal write stores them on `work`. `/factories/:id/review` opens Work filtered to cards with a pull request. Once a project's last open Review card finishes, the board goes away; it never comes back.
|
|
482
529
|
|
|
483
|
-
|
|
530
|
+
A project that ran an earlier release may also hold a stored `review` board row from when Review was seeded. It is never served either way. When Factory wrote it and nobody edited it since, the board catalog ignores it; a row a person edited is listed under the catalog's `problems`, because its edits are not served.
|
|
484
531
|
|
|
485
|
-
|
|
532
|
+
Either way, new pull requests follow the project's intake routes, and the default `pull-requests` route files them on Work › Review, so nothing new lands on Review unless one of the project's own routes targets it. In a project whose Review board is redundant, a route that targets `review` stops matching and arrivals fall through to the next route. A board config or skill override for `review` is ignored, and `review` is reserved: a custom board can't use that ID. For an existing install:
|
|
533
|
+
|
|
534
|
+
- A run in flight on an old Review card keeps its binding; its Reviewing phase runs its runner (`factory-review`).
|
|
535
|
+
- Pairs filed before this change (a pull request card plus the card that authored it) stay two cards and keep working.
|
|
536
|
+
|
|
537
|
+
Planning and Building on Work share the `work` session, so the builder keeps the planner's reasoning, branch and sandbox. A self-review phase, on a board that has one, runs in its own `review` session. When the planner moves the card to Building after its plan is approved, the build kickoff is queued onto the planner's 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.
|
|
538
|
+
|
|
539
|
+
Consent, kickoff seating, run-start lanes, terminal cleanup, and the closed-PR and issue sweeps all read the project's board; 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 Work, and so are rows stored on the retired `review` board in a project that no longer uses it.
|
|
486
540
|
|
|
487
541
|
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.
|
|
488
542
|
|
|
@@ -498,17 +552,33 @@ phases: {
|
|
|
498
552
|
}
|
|
499
553
|
```
|
|
500
554
|
|
|
501
|
-
**Remaining limitations:**
|
|
555
|
+
**Remaining limitations:** `factory-ui` still renders the built-in stage and role pipeline.
|
|
556
|
+
|
|
557
|
+
#### The pull request loop on any board
|
|
558
|
+
|
|
559
|
+
Nothing in Factory's runtime reads Work's board key or phase keys. Each part of the issue → build → self-review → pull request → review → merge loop is found by what a board's phases declare, so a board you create in the UI, through the API or in code runs the same loop under its own key and phase names:
|
|
560
|
+
|
|
561
|
+
| Part | The phase that plays it |
|
|
562
|
+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
563
|
+
| Pull request review | The first working phase in the `review` context that grants `factory_review_source`. A pull request's own card is reviewed there, a pull request attached to an issue card is reviewed there, `factory_record_review_verdict` records verdicts on pull requests there, and a push, a review request or `@<app> review` re-enters it. |
|
|
564
|
+
| Self-review | The first other working phase in the `review` context that grants `factory_record_review_verdict`. It reviews the builder's pushed branch before any pull request: request changes sends the card back to the build phase (every third round parks it in the board's initial phase), and the pull request may only open from the head it approved. |
|
|
565
|
+
| Build | The last other working phase that can move into the self-review phase (else the pull request review phase). Its context is the seat pull request feedback (`changes_requested` reviews, comments) wakes, and a pull request the card's session opens moves it from here into review. |
|
|
566
|
+
| Triage | On a board with a build phase, the first working phase that neither builds nor reviews. A `status: needs approval` label holds a card only in a resting phase or here. |
|
|
567
|
+
| Completed / canceled | The board's `sourceClosed` phases, else its first and second terminal phases. A merge moves the card to the completed phase; a pull request card closed unmerged goes to the canceled one, and an issue card in review with no open pull request left goes back to the initial phase. Completion metrics count entries into the completed phase. |
|
|
568
|
+
|
|
569
|
+
A board with no `factory_review_source` phase has no pull request loop: a pull request is never attached to its cards and verdicts are refused there. The `factory-phase` signal names each part's phase on the card's own board (`Board phases by part: rest: …; build: …; self-review: …; pull request review: …`), and the bundled skills move cards by those names, never by Work's keys.
|
|
502
570
|
|
|
503
571
|
### Phase runners, automatic starts and exit tools
|
|
504
572
|
|
|
505
573
|
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:
|
|
506
574
|
|
|
507
|
-
- `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
|
|
575
|
+
- `runner` — `{ agentId?, skill?, context?, instructions?, goal? }`. The runner is the only way a phase starts work: when a card enters the phase, from any source and including a card filed straight into it, Factory starts `skill` in the `context` session. `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 kickoff is queued onto the agent's run. Moving a card back into the phase it is in (a re-entry, such as a re-review after a push) supersedes the run in flight and resumes the skill. `skill` names a built-in Factory skill or one of your app's skills (see [Skills for custom boards](#skills-for-custom-boards)); a phase without one starts nothing. The kickoff names the card only by its URL (or title, quoted as untrusted data when an outside author wrote it); the agent reads everything else from the [`factory-work-item` signal](#the-factory-work-item-signal). `instructions` (up to 1,000 characters) are added to the kickoff. `agentId` defaults to `code-agent`, the only agent Factory runs today.
|
|
576
|
+
- `runner.goal` — `{ objective, maxRuns? }`: the run pursues `objective` (up to 2,000 characters) as a Mastra goal. Factory stores it on the session's thread as the run starts, with the session's model as judge, and after each run the judge decides from the objective text and the latest messages whether the work is done, should continue (Factory starts another run, up to `maxRuns`, 1–50) or is waiting for a person. Waiting leaves the goal active and the card in its phase; the next message a person sends resumes it, and a skill asks people with `ask_user`, which parks the run in Factory's attention view. When `maxRuns` runs out, the goal pauses and the card stays: resume it from the session or move the card. When the card leaves the phase, by anyone, Factory marks the goal done. The judge sees only the objective and the latest messages, so state the done and waiting criteria in the objective. Work's Building pursues the approved plan this way, with up to 20 runs.
|
|
508
577
|
- `autoStart` and `autoStartWhen` — the phase's runs start without a person's approval, for every card or only for cards matching the rule. To start only trusted authors' cards, add `author.trusted equals true` to `autoStartWhen`; by default, [intake routes](#intake-routes) file GitHub and GitLab cards from outside the write-access circle in Work › Intake, where nothing starts on its own.
|
|
509
|
-
- `exitTool` — a tool name, or `{ id, autoApprove, autoApproveWhen }`, that ends the phase. The
|
|
578
|
+
- `exitTool` — a tool name, or `{ id, autoApprove, autoApproveWhen }`, that ends the phase. The phase holds the card until that tool succeeds (for `submit_plan`, with an approved plan) in the session that works the card there: until then an agent or board rule asking to move the card on to another working phase is rejected with `approval_required`. Once it has succeeded during the card's current visit to the phase, the agent moves the card itself with `factory_transition_work_item` (the factory-phase signal tells it so and lists `nextPhases`), or a board tool rule for the exit tool (`tools`) moves it; the tool's success never moves the card by itself. A person can move the card at any time. The phase needs at least one next phase. `autoApprove` and `autoApproveWhen` only decide whether the tool approves itself, for every card or only cards matching the rule, or waits for a person; they are the only way plans are approved without a person. Factory sessions already run tools without asking, so for `submit_plan` this means an auto-approved plan is accepted without a person. Work's Planning declares `{ id: 'submit_plan', autoApprove: false }`: every plan waits for a person, who approves `submit_plan` in a signed-in chat (or moves the card), and then `factory-plan` moves the card to Building.
|
|
579
|
+
- `tools` — Factory tools the phase gives the session that works the card in it (the session whose context is the phase's `runner.context`): `factory_record_review_verdict` and `factory_review_source`. Tools follow the card: when it moves to a phase without them, the session loses them on its next turn, and a verdict tool call made after the card moved is refused. Every bound session keeps `factory_transition_work_item`. Work's Review grants both; a self-review phase, on a board that has one, grants only the verdict tool.
|
|
510
580
|
|
|
511
|
-
Rules test a card's facts: `item.labels`, `item.title`, `item.author`, `author.trusted`, `source.kind` and `source.integration`.
|
|
581
|
+
Rules test a card's facts: `item.labels`, `item.title`, `item.author`, `author.trusted`, `item.pullRequest` (the number of the card's open pull or merge request, absent when it has none), `source.kind` and `source.integration`.
|
|
512
582
|
|
|
513
583
|
The example below is a custom board, not Work's behavior: it auto-starts and auto-approves planning only for cards labelled `effort:low`.
|
|
514
584
|
|
|
@@ -540,7 +610,11 @@ const releaseBoard = defineBoard({
|
|
|
540
610
|
});
|
|
541
611
|
```
|
|
542
612
|
|
|
543
|
-
**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`
|
|
613
|
+
**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`, `onEnter` and `onExit` are ignored (see [Board lifecycle rules](#board-lifecycle-rules)); outcome targets are added to `nextPhases`. The board `defineBoard()` returns still has the old names as read-only copies — `board.title` and `phase.title` equal `name`, a working phase's `role` equals `runner.context`, and `phase.next` is set when the phase declared `next` — so code that reads them, or passes a defined board's phases to `defineBoard()` again, keeps working. They are deprecated; read `name`, `runner.context` and `nextPhases` instead. 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.
|
|
614
|
+
|
|
615
|
+
### The `factory-work-item` signal
|
|
616
|
+
|
|
617
|
+
Every session bound to a card gets a `<factory-work-item>` state signal describing it, re-rendered only when the card, its sources, the binding or the project's self-review setting change (the setting counts only for a card whose board has a self-review phase). It carries the card's key, title, URL, board and phase, next phases, labels, author and whether they're trusted, and the session's branch; its sources (issue and each pull or merge request, with state, head commit, a head branch that passes Factory's branch-name check, and the tool to fetch details); and Factory's state: whether the plan was approved, self-review on or off (only on a board with a self-review phase), self-review rounds used, the last self-review and PR review verdicts with the commits they covered and findings, and the card's open change request. The session that reviews a pull request also gets the procedure to follow, the checkout steps and the head to review. The source description is included, inside an `<untrusted-source-description>` block when an outside author wrote it. Comment threads are not included.
|
|
544
618
|
|
|
545
619
|
### Skills for custom boards
|
|
546
620
|
|
|
@@ -622,6 +696,21 @@ import { MastraFactory } from '@mastra/factory';
|
|
|
622
696
|
import type { MastraFactoryConfig } from '@mastra/factory';
|
|
623
697
|
import { defineBoard } from '@mastra/factory/boards';
|
|
624
698
|
import type { BoardPhaseDefinition } from '@mastra/factory/boards';
|
|
699
|
+
import { createSkill } from '@mastra/core/skills';
|
|
700
|
+
|
|
701
|
+
const prepareRelease = createSkill({
|
|
702
|
+
name: 'prepare-release',
|
|
703
|
+
description: 'Inspect the release changes',
|
|
704
|
+
instructions:
|
|
705
|
+
'Inspect the release changes. When ready, call factory_transition_work_item with stage build and the current expectedRevision from the Factory phase signal.',
|
|
706
|
+
});
|
|
707
|
+
|
|
708
|
+
const checkRelease = createSkill({
|
|
709
|
+
name: 'check-release',
|
|
710
|
+
description: 'Rehearse the release check',
|
|
711
|
+
instructions:
|
|
712
|
+
'Run npm run release:check && printf "RELEASE_CHECK_PASSED\\n" with execute_command. This is a rehearsal; do not publish anything.',
|
|
713
|
+
});
|
|
625
714
|
|
|
626
715
|
type ReleasePhase = 'backlog' | 'preparing' | 'build' | 'done';
|
|
627
716
|
|
|
@@ -634,32 +723,14 @@ const releaseBoard = defineBoard<'release', Record<ReleasePhase, BoardPhaseDefin
|
|
|
634
723
|
preparing: {
|
|
635
724
|
name: 'Preparing',
|
|
636
725
|
kind: 'working',
|
|
637
|
-
runner: { context: 'release-preparer' },
|
|
726
|
+
runner: { context: 'release-preparer', skill: 'prepare-release' },
|
|
638
727
|
nextPhases: ['build'],
|
|
639
|
-
onEnter: {
|
|
640
|
-
issue: context => ({
|
|
641
|
-
type: 'invokeSkill',
|
|
642
|
-
idempotencyKey: `${context.ingress.id}:prepare`,
|
|
643
|
-
role: 'release-preparer',
|
|
644
|
-
prompt:
|
|
645
|
-
'Inspect the release changes. When ready, call factory_transition_work_item with stage build and the current expectedRevision from the Factory phase signal.',
|
|
646
|
-
}),
|
|
647
|
-
},
|
|
648
728
|
},
|
|
649
729
|
build: {
|
|
650
730
|
name: 'Build',
|
|
651
731
|
kind: 'working',
|
|
652
|
-
runner: { context: 'release-publisher' },
|
|
732
|
+
runner: { context: 'release-publisher', skill: 'check-release' },
|
|
653
733
|
nextPhases: ['done'],
|
|
654
|
-
onEnter: {
|
|
655
|
-
issue: context => ({
|
|
656
|
-
type: 'invokeSkill',
|
|
657
|
-
idempotencyKey: `${context.ingress.id}:check`,
|
|
658
|
-
role: 'release-publisher',
|
|
659
|
-
prompt:
|
|
660
|
-
'Run npm run release:check && printf "RELEASE_CHECK_PASSED\\n" with execute_command. This is a rehearsal; do not publish anything.',
|
|
661
|
-
}),
|
|
662
|
-
},
|
|
663
734
|
},
|
|
664
735
|
done: { name: 'Done', kind: 'terminal' },
|
|
665
736
|
},
|
|
@@ -686,31 +757,36 @@ const releaseBoard = defineBoard<'release', Record<ReleasePhase, BoardPhaseDefin
|
|
|
686
757
|
});
|
|
687
758
|
|
|
688
759
|
export function createFactory(config: Omit<MastraFactoryConfig, 'boards' | 'includeDefaultBoards'>) {
|
|
689
|
-
return new MastraFactory({
|
|
760
|
+
return new MastraFactory({
|
|
761
|
+
...config,
|
|
762
|
+
boards: [releaseBoard],
|
|
763
|
+
skills: [prepareRelease, checkRelease],
|
|
764
|
+
includeDefaultBoards: true,
|
|
765
|
+
});
|
|
690
766
|
}
|
|
691
767
|
```
|
|
692
768
|
|
|
693
|
-
Use the host's normal `prepare()`, `new Mastra(...)`, and `finalize()` sequence. Change the hardcoded `includeDefaultBoards: true` in `createFactory` to `false` to run without Work
|
|
769
|
+
Use the host's normal `prepare()`, `new Mastra(...)`, and `finalize()` sequence. Change the hardcoded `includeDefaultBoards: true` in `createFactory` to `false` to run without Work. Working roles name bindings on the shared Code Agent; they do not register separate agents. Factory has no per-role agent configuration option. Each phase's skill supplies the role-specific instructions.
|
|
694
770
|
|
|
695
771
|
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 move 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.
|
|
696
772
|
|
|
697
|
-
|
|
773
|
+
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`.
|
|
698
774
|
|
|
699
775
|
Custom phase signals and persisted tool-result ingestion use the item's installed board. Bound tools re-resolve the live binding, retain revision and topology checks, and reject session reassignment. A custom role named `triage` does not inherit Work's classification requirements. Existing authorization, external-author safeguards, and board-owned policies still apply.
|
|
700
776
|
|
|
701
777
|
### Custom boards in the Factory UI
|
|
702
778
|
|
|
703
|
-
`GET /web/factory/projects/:id/boards` returns the project's boards (its code boards, then its stored boards) for an authorized user: 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
|
|
779
|
+
`GET /web/factory/projects/:id/boards` returns the project's boards (its code boards, then its stored boards) for an authorized user: 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:
|
|
704
780
|
|
|
705
|
-
- Installed boards appear in the sidebar — built-ins first, then custom boards in registry order. Work
|
|
781
|
+
- Installed boards appear in the sidebar — built-ins first, then custom boards in registry order. Work keeps `/factories/:id/work` (`/factories/:id/review` redirects there, filtered to pull requests); 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.
|
|
706
782
|
- 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.
|
|
707
783
|
- A card's persisted `board` decides which board it belongs to. UI actions cannot move a card to a different board.
|
|
708
|
-
- Settings › Skills groups built-in skills under Work
|
|
709
|
-
- Not yet board-aware: the Overview funnel and stage-hold metrics (Work-only), search scopes (Work
|
|
784
|
+
- Settings › Skills groups built-in skills under Work. 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.
|
|
785
|
+
- Not yet board-aware: the Overview funnel and stage-hold metrics (Work-only), search scopes (Work 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.
|
|
710
786
|
|
|
711
787
|
### Route intake to custom boards
|
|
712
788
|
|
|
713
|
-
Intake bindings are explicit. A Linear project, Jira project, or GitHub repository is only offered as a candidate feed once it is bound to a board; nothing is materialized just by opening a board.
|
|
789
|
+
Intake bindings are explicit. A Linear project, Jira project, or GitHub repository is only offered as a candidate feed once it is bound to a board; nothing is materialized just by opening a board.
|
|
714
790
|
|
|
715
791
|
- **Linear:** each project binding selects one installed board. Changing the board moves that source's existing cards to the new board's initial phase, skipping terminal cards and cards with an active session.
|
|
716
792
|
- **Jira:** each connected-site project binding selects one installed board. One Jira project can feed several Factory projects: each binding takes either all issues or only issues carrying its labels (Settings › Intake › Jira routing, or `labels` on `PUT /web/intake/bindings`). Each label belongs to one binding per Jira project, and only one binding per project can take all issues. Label bindings win over the all-issues binding; an issue carrying labels of two label bindings goes to the binding created first. The split happens in the JQL each Factory sends, so every issue is filed in exactly one Factory. Labels only decide placement when an issue is first filed: relabelling an issue, or editing a binding's labels, does not move existing cards. Remove one Factory's binding with `DELETE /web/intake/bindings?integrationId=jira&sourceId=…&factoryProjectId=…`. The create-Factory flow can select a Jira project and initially binds it to Work. The browser checks routed projects for new issues every 30 seconds and on window focus; issues observed for a routed project materialize automatically as work items on the bound board (mirroring Linear), and closed issues transition their linked card to done or canceled. Both `JiraIntegration` and `PlatformJiraIntegration` reconcile imported cards every five minutes by default so status and metadata continue to refresh without an open browser, and both accept a `rules` option to replace or disable the `issueObserved` / `issueClosed` defaults. Agents on Jira-sourced runs get `jira_get_issue` and `jira_create_comment`. Set `MASTRACODE_JIRA_RECONCILE_ENABLED=false` to disable reconciliation or `MASTRACODE_JIRA_RECONCILE_INTERVAL_MS` to a positive millisecond interval to change its cadence.
|
|
@@ -722,7 +798,25 @@ A project's [intake routes](#intake-routes) are checked before these bindings an
|
|
|
722
798
|
|
|
723
799
|
Each project has an ordered list of intake routes, managed through the API (there is no UI yet). A route names the board events it handles in `on`. A route on `work_item.created`, the default, decides where a new card lands: the first enabled route whose `when` matches the card names its board and phase. A route on `work_item.closed` or `work_item.reopened` decides where an existing card moves when its source closes or reopens (see [Status events](#status-events-move-existing-cards)).
|
|
724
800
|
|
|
725
|
-
**The default routes.** Every project starts with
|
|
801
|
+
**The default routes.** Every project starts with eleven routes: three for new cards, one of which files a pull request on its issue's card; three that move cards when their issue closes or reopens; and five that move cards when a pull request's status changes. The first, `Pull requests that close a waiting issue join its card`:
|
|
802
|
+
|
|
803
|
+
```json
|
|
804
|
+
{
|
|
805
|
+
"when": {
|
|
806
|
+
"operator": "AND",
|
|
807
|
+
"conditions": [
|
|
808
|
+
{ "field": "source.kind", "operator": "equals", "value": "pull_request" },
|
|
809
|
+
{ "field": "author.trusted", "operator": "equals", "value": true },
|
|
810
|
+
{ "field": "pullRequest.closesIssue", "operator": "equals", "value": true },
|
|
811
|
+
{ "field": "closedIssue.phase", "operator": "in", "value": ["intake"] },
|
|
812
|
+
{ "field": "closedIssue.hasPullRequest", "operator": "equals", "value": false }
|
|
813
|
+
]
|
|
814
|
+
},
|
|
815
|
+
"target": { "boardKey": "work", "phaseKey": "pr-review", "joinClosedIssue": true }
|
|
816
|
+
}
|
|
817
|
+
```
|
|
818
|
+
|
|
819
|
+
It adds a trusted author's pull request to the card of the issue it closes while that card is still waiting (see [One card for an issue and its pull requests](#one-card-for-an-issue-and-its-pull-requests)). Edit `closedIssue.phase` to let pull requests join cards further along, or delete the route to give every pull request its own card. The second, `Outside authors wait in Intake`:
|
|
726
820
|
|
|
727
821
|
```json
|
|
728
822
|
{
|
|
@@ -737,7 +831,7 @@ Each project has an ordered list of intake routes, managed through the API (ther
|
|
|
737
831
|
}
|
|
738
832
|
```
|
|
739
833
|
|
|
740
|
-
It files GitHub and GitLab issues and pull requests from authors outside the write-access circle in Work › Intake, ahead of any label route or binding. Intake is a resting phase, so nothing starts there on its own. Any session, a person's or an agent's, can move the card on, and that move starts the next phase's run. Pushes to a pull request resting in Intake don't re-review it, and comments and edits on an issue never re-run Triage (see GitHub event rules). Trusted authors' cards, and Linear, Jira and incident.io cards (which carry no trust stamp), land where they did before. The
|
|
834
|
+
It files GitHub and GitLab issues and pull requests from authors outside the write-access circle in Work › Intake, ahead of any label route or binding. Intake is a resting phase, so nothing starts there on its own. Any session, a person's or an agent's, can move the card on, and that move starts the next phase's run. Pushes to a pull request resting in Intake don't re-review it, and comments and edits on an issue never re-run Triage (see GitHub event rules). Trusted authors' cards, and Linear, Jira and incident.io cards (which carry no trust stamp), land where they did before. The third, `Pull requests go to Review`, sends every other pull request and merge request (`source.kind equals pull_request`) to Work › Review, where the reviewer runs once a person or the project's auto-run lets it start. Because it comes after the outside-authors route, an outside author's pull request still waits in Intake. A pull request Factory opened for one of its own cards is filed by that card's rule, which no route re-places: it is attached to the authoring card, which goes out for review. Pull requests opened before attaching existed keep their own card.
|
|
741
835
|
|
|
742
836
|
The other three move Work cards when their issue's status changes:
|
|
743
837
|
|
|
@@ -747,35 +841,45 @@ The other three move Work cards when their issue's status changes:
|
|
|
747
841
|
| `Issues closed as not planned go to Canceled` | `["work_item.closed"]` | `event.reason equals canceled` | Work › Canceled |
|
|
748
842
|
| `Reopened issues go back to Intake` | `["work_item.reopened"]` | none | Work › Intake |
|
|
749
843
|
|
|
844
|
+
Five more move Work cards when a pull request's status changes. Each agrees with the move Work's default pull request rule already makes, so out of the box nothing changes; retarget one to send those cards elsewhere:
|
|
845
|
+
|
|
846
|
+
| Route | `on` | `when` | Target |
|
|
847
|
+
| ------------------------------------------------------------- | ----------------------------------- | ------------------------------------- | ----------------------------------- |
|
|
848
|
+
| `Merged pull requests go to Done` | `["pull_request.merged"]` | none | Work › Done |
|
|
849
|
+
| `Pull requests closed unmerged go to Canceled` | `["pull_request.closed"]` | `source.kind equals pull_request` | Work › Canceled |
|
|
850
|
+
| `Issues whose pull request closed unmerged go back to Intake` | `["pull_request.closed"]` | `source.kind not_equals pull_request` | Work › Intake |
|
|
851
|
+
| `Pushes to a reviewed pull request re-review it` | `["pull_request.synchronized"]` | none | Work › Review (`allowWorkingPhase`) |
|
|
852
|
+
| `Requested reviews go to Review` | `["pull_request.review_requested"]` | none | Work › Review (`allowWorkingPhase`) |
|
|
853
|
+
|
|
750
854
|
They replace the close handlers each integration used to apply on its own, so a closed GitHub, GitLab, Linear, Jira or incident.io issue lands where it did before, but you can now edit or disable that move. To stop closes from moving Work cards, disable both close routes. Deleting them does not stop the move: with no route left that handles closes, Work's `sourceClosed` mapping moves closed cards to Done or Canceled again.
|
|
751
855
|
|
|
752
|
-
The default routes are stored routes like any other: list them, edit them, disable them, reorder them or delete them through the API. Factory adds each one once, the first time the project's routes are read or written, appending it after the project's existing routes, and doesn't add it back after an admin deletes it. Deleting a default is permanent: recreate it by hand to get it back. A project set up before the pull request
|
|
856
|
+
The default routes are stored routes like any other: list them, edit them, disable them, reorder them or delete them through the API. Factory adds each one once, the first time the project's routes are read or written, appending it after the project's existing routes, and doesn't add it back after an admin deletes it. The closing-issue route is the exception: it goes first, since its condition only matches trusted authors' pull requests that close an issue. Deleting a default is permanent: recreate it by hand to get it back. A project set up before the pull request, closing-issue or close and reopen routes existed gets them this way too.
|
|
753
857
|
|
|
754
858
|
**Trust only decides where a card arrives.** Once a card is moved out of Intake, later input on it runs like on any card: a maintainer's push re-reviews an outside author's pull request. A phase that should only auto-start for trusted authors says so in its `autoStartWhen` (`author.trusted equals true`). Runs on untrusted cards still use their own isolated memory.
|
|
755
859
|
|
|
756
860
|
**Route shape.**
|
|
757
861
|
|
|
758
|
-
| Field | Meaning
|
|
759
|
-
| ------------------- |
|
|
760
|
-
| `name` | Up to 120 characters.
|
|
761
|
-
| `enabled` | Defaults to `true`. Disabled routes are skipped.
|
|
762
|
-
| `on` | The board events the route handles: `work_item.created` (the default), `work_item.closed` and `
|
|
763
|
-
| `when` | A rule over the card's facts (the same format as `autoStartWhen`). `null`, the default, matches every card. A route that handles more than `work_item.created` can also test `event.type` and `event.reason`.
|
|
764
|
-
| `target` | Required. `{ boardKey, phaseKey? }` sets where matching cards land; without `phaseKey` they land in the board's first phase. The board must be installed in the project (code or stored). For a route on `work_item.created`, the phase can't be terminal and must be reachable from the board's first phase; a route that only moves existing cards can target any phase, terminal ones included. |
|
|
765
|
-
| `allowWorkingPhase` | Defaults to `false`. A status move into a working phase (one that starts runs, such as Triage) is refused unless this is `true`, so a reopened card doesn't re-run Triage by accident.
|
|
862
|
+
| Field | Meaning |
|
|
863
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
864
|
+
| `name` | Up to 120 characters. |
|
|
865
|
+
| `enabled` | Defaults to `true`. Disabled routes are skipped. |
|
|
866
|
+
| `on` | The board events the route handles: `work_item.created` (the default), `work_item.closed`, `work_item.reopened`, `pull_request.opened`, `pull_request.synchronized`, `pull_request.review_requested`, `pull_request.merged` and `pull_request.closed`. Each at most once. `work_item.commented` and `work_item.edited` are activity, which never moves a card, so a route can't name them. |
|
|
867
|
+
| `when` | A rule over the card's facts (the same format as `autoStartWhen`). `null`, the default, matches every card. A route that handles more than `work_item.created` can also test `event.type` and `event.reason`. |
|
|
868
|
+
| `target` | Required. `{ boardKey, phaseKey?, joinClosedIssue? }` sets where matching cards land; without `phaseKey` they land in the board's first phase. The board must be installed in the project (code or stored). For a route on `work_item.created`, the phase can't be terminal and must be reachable from the board's first phase; a route that only moves existing cards can target any phase, terminal ones included. With `joinClosedIssue: true`, a pull request is added to the card of the issue it closes instead of getting its own card, and that card moves to `phaseKey` when the board allows the move (otherwise it stays put); the route is skipped when there is no such card on `boardKey`, and its `on` must be `["work_item.created"]` alone. An update that sets `target` replaces the whole target, so repeat `joinClosedIssue: true` to keep a route joining. |
|
|
869
|
+
| `allowWorkingPhase` | Defaults to `false`. A status move into a working phase (one that starts runs, such as Triage) is refused unless this is `true`, so a reopened card doesn't re-run Triage by accident. |
|
|
766
870
|
|
|
767
|
-
Routes are evaluated in `position` order (0 first). Rules can test these card facts: `item.labels`, `item.title`, `item.author`, `source.kind` (`issue`, `pull_request`, …), `source.integration` (`github`, `gitlab`, `linear`, `jira`, `incidentio`, …) and `author.trusted`. `author.trusted` is `true` when the card carries an `authorTrusted: true` or `factoryAuthored: true` stamp. GitHub and GitLab stamp `authorTrusted` from the author's repository permission, and a stamp that is missing counts as untrusted.
|
|
871
|
+
Routes are evaluated in `position` order (0 first). Rules can test these card facts: `item.labels`, `item.title`, `item.author`, `source.kind` (`issue`, `pull_request`, …), `source.integration` (`github`, `gitlab`, `linear`, `jira`, `incidentio`, …) and `author.trusted`. For pull requests, routes can also test `pullRequest.closesIssue` (`true` when the body closes an issue that has a usable card), `closedIssue.phase` and `closedIssue.hasPullRequest` (that card's phase and whether it already carries a pull request). These three are route-only: phase rules can't use them. A route that lets a pull request join a card already in its review phase doesn't start a second review: the review in progress keeps its pull request, and the new one is reviewed on its next push by a trusted author, or on a review request once the current pass has a verdict. That's why the default route requires `closedIssue.hasPullRequest` to be `false`. `author.trusted` is `true` when the card carries an `authorTrusted: true` or `factoryAuthored: true` stamp. GitHub and GitLab stamp `authorTrusted` from the author's repository permission, and a stamp that is missing counts as untrusted.
|
|
768
872
|
|
|
769
|
-
**Placement.** When an integration files a new card, or a card is created without naming a board (the `factory_create_work_item` tool, or `POST /web/factory/projects/:id/work-items` without `board`), the first enabled route that matches the card and whose board can take it decides where the card lands. On the built-in boards, a pull request lands on Work only in Intake or
|
|
873
|
+
**Placement.** When an integration files a new card, or a card is created without naming a board (the `factory_create_work_item` tool, or `POST /web/factory/projects/:id/work-items` without `board`), the first enabled route that matches the card and whose board can take it decides where the card lands. On the built-in boards, a pull request lands on Work only in Intake or Review and Review takes only cards with a pull request; a route a card can't take is skipped and the next one is tried. If the route's phase no longer exists, or can no longer be reached from the first phase, the card lands in the first phase. A card routed to a later phase enters the first phase and then moves on through the transition service as a system move, recorded in the card's history. The route makes this move, not a person, so it gives no consent to start work; a run the phase asks for still needs a person or the project's auto-run. A board whose transition policy refuses system moves refuses the route, and the card is not filed. If no route places a card, the integration's binding, label route or default decides.
|
|
770
874
|
|
|
771
875
|
A card a route placed records the route's id in its `intakeRouteId` metadata and stays on that board afterwards: a GitHub label change, a reconcile that replays a known issue, a label route change, and rebinding the card's source all leave it there (its labels still update). An edited route moves no existing card. If filing a card stopped partway (it entered the board's first phase but the move to the route's phase failed), the retry keeps the card on that board: it moves to the phase the route names now, or stays in the first phase when the route was deleted, disabled or pointed at another board. Cards no route placed keep following label routes and bindings as before. An explicit placement wins over routes, for example:
|
|
772
876
|
|
|
773
|
-
- a maintainer's review request that files a pull request directly in
|
|
877
|
+
- a maintainer's review request that files a pull request directly in Review;
|
|
774
878
|
- a custom rule with `skipRules`;
|
|
775
879
|
- a child card a board's own rule files;
|
|
776
880
|
- a board named when the card is created. The board's **New card** button always names its board, so routes never place cards made there.
|
|
777
881
|
|
|
778
|
-
|
|
882
|
+
A pull request routed to a board with a [pull request loop](#the-pull-request-loop-on-any-board) is reviewed there; on a board without one, review requests and pushes do nothing to its card.
|
|
779
883
|
|
|
780
884
|
#### Status events move existing cards
|
|
781
885
|
|
|
@@ -785,14 +889,23 @@ When one of these arrives for a card that already exists, the first enabled rout
|
|
|
785
889
|
|
|
786
890
|
- The move is a system move made by the route, recorded in the card's history (`by: intake-route:<routeId>`) and in the audit log (`factory.work_item.stage_moved` with `cause: event_route`, made by actor `intake-route:<routeId>`).
|
|
787
891
|
- The move clears the card's armed autonomy. A provider event is not a person's go-ahead, so a reopened card waits for a person or the project's auto-run before a phase run starts.
|
|
788
|
-
- It skips the board's `nextPhases`, so a reopened card can leave Done. It still checks that the phase exists and that the board's card lanes take the card (an issue
|
|
892
|
+
- It skips the board's `nextPhases`, so a reopened card can leave Done. It still checks that the phase exists and that the board's card lanes take the card (an issue card enters Review only once it has a pull request).
|
|
789
893
|
- It is refused with `approval_required` when the target is a working phase and the route doesn't set `allowWorkingPhase`.
|
|
790
894
|
- A move into a working or resting phase waits for a run in flight on the card to end, then moves the card. While it waits it goes back to the queue, so it never holds a dispatch slot.
|
|
791
895
|
- The source's last status wins. When an issue is closed and reopened before Factory applies the close, the close is dropped and the card stays where it was.
|
|
792
896
|
- A move into a terminal phase doesn't wait: it runs terminal cleanup like any other, so a session still running on the card is aborted at once, as a close always has.
|
|
793
897
|
- A close moves only an unfinished card, and a reopen only a finished one. Redelivered or reconciled webhooks move the card once.
|
|
794
898
|
|
|
795
|
-
|
|
899
|
+
Pull request events (GitHub and GitLab) work the same way, with these differences:
|
|
900
|
+
|
|
901
|
+
- The integration's default pull request rule decides first, then hands its move to the routes: a route on the card's board naming the event sends the card to the route's phase instead. A route that targets the phase the rule already chose keeps the rule's move whole, its message and its re-entry (a push re-enters Review to restart the pass) included. A rule that moves nothing (an older pull request merging while a newer one is open, a push to a card resting in its first phase) leaves routes out of it.
|
|
902
|
+
- On a board with no pull request loop, a merge or close of a pull request's own card goes to the routes alone; without a route naming it the card stays put.
|
|
903
|
+
- A merge or close moves only an unfinished card. `pull_request.opened`, `pull_request.synchronized` and `pull_request.review_requested` move finished cards too, so a done pull request is re-reviewed on a push as before.
|
|
904
|
+
- When the card's board has routes on the event but none enabled matches the card, the rule's own move still runs: disabling the merge route doesn't strand a merged card in review.
|
|
905
|
+
- Pull request events never drop one another: each concerns its own pull request.
|
|
906
|
+
- Factory sees no pull request reopen, so there is no `pull_request.reopened`.
|
|
907
|
+
|
|
908
|
+
Only routes targeting the card's own board apply; a route naming another board is skipped. For issue status events (`work_item.closed` and `work_item.reopened`), a route on the card's board that names the event owns it even when it is disabled or its `when` doesn't match: the card stays put. Pull request events differ, as above: when no enabled route takes the card, the rule's own move still runs. Only on a board where no route names the event does the board's `sourceClosed` mapping apply, so custom boards keep closing as before. To stop closes from moving Work cards, disable both close routes: deleting them hands closes back to Work's `sourceClosed` mapping, which moves the card to Done or Canceled.
|
|
796
909
|
|
|
797
910
|
A deployment that answers an event itself keeps routes out of it: a handler or `null` set explicitly on the integration's `rules` for `issueClosed`, `issueReopened`, `issueCommentCreated` and so on, or `null` on the card's board handlers. An override that moves nothing really moves nothing. A board handler that wraps or returns the stock close move is different: that move still goes to the routes, as the stock handler's own would.
|
|
798
911
|
|
|
@@ -962,7 +1075,7 @@ A decision _without_ the flag that reaches a card which already exists keeps the
|
|
|
962
1075
|
|
|
963
1076
|
Reconciliation re-applies label-derived placement. The issue sweep replays an open issue through the rules ingress whenever the issue's live labels differ from the card's stored ones — the `labeled`/`unlabeled` webhook may never have arrived (Factory was down, or the label was applied by something else). The deployment rule decides placement, exactly as at arrival, and the context carries the existing card on `item`, so one handler answers for both: a card still resting on the board's initial phase is landed the normal way, and a card that has already left it is re-placed with `skipRules` and no phase rule run. Cards parked by hand are untouched while an issue's labels are unchanged.
|
|
964
1077
|
|
|
965
|
-
A delivery that concerns two cards is evaluated once per card, each under its own ingress identity: every decision is committed against one card, at that card's revision. A merged pull request is the standard case — its own card closes, and the built-in `pullRequestMerged` rule moves the Work item that wrote the code to Done. If that Work item has another pull request open, it stays where it is and its session is told which pull request is still out. An opening pull request is evaluated the same way.
|
|
1078
|
+
A delivery that concerns two cards is evaluated once per card, each under its own ingress identity: every decision is committed against one card, at that card's revision. A merged pull request is the standard case — its own card closes, and the built-in `pullRequestMerged` rule moves the Work item that wrote the code to Done. If that Work item has another pull request open, it stays where it is and its session is told which pull request is still out. An opening pull request is evaluated the same way. The arrival is evaluated with `pullRequestIntake` set and, when a home card exists, `pullRequestHome` naming it; the built-in `pullRequestOpened` then attaches the pull request to that card (`upsertLinkedWorkItem` with `attachTo`) or files its own card. The authoring item is then answered in a second evaluation of its own (`pullRequestIntake` unset), which is where a handler places the item that is now out for review. On the authoring item's evaluation it moves that Work item from Building to Review when the pull request is open and comes from a trusted author or from Factory; otherwise it returns nothing.
|
|
966
1079
|
|
|
967
1080
|
### GitHub CLI authentication in Factory sessions
|
|
968
1081
|
|
|
@@ -1108,7 +1221,7 @@ Read tools and `factory_message_origin` are available on every turn. The other t
|
|
|
1108
1221
|
|
|
1109
1222
|
`factory_switch_session_model` changes the model of a side, work item or review session you own in the same Factory, without recreating it. It refuses a model this server can't run. A running session switches right away; a stopped one uses the model on its next run.
|
|
1110
1223
|
|
|
1111
|
-
`factory_create_work_item` files the card as the caller where the project's [intake routes](#intake-routes) send it, or in the Work board's first phase when no route matches, posts the brief as its first comment, and subscribes the session. Name the `repository` when the Factory links more than one: a run can't start on a card that doesn't say which. `factory_update_work_item` sets it afterwards, like choosing a repository on the card, and also edits the title
|
|
1224
|
+
`factory_create_work_item` files the card as the caller where the project's [intake routes](#intake-routes) send it, or in the Work board's first phase when no route matches, posts the brief as its first comment, and subscribes the session. Name the `repository` when the Factory links more than one: a run can't start on a card that doesn't say which. `factory_update_work_item` sets it afterwards, like choosing a repository on the card, and also edits the title and the parent item. It can't pre-approve plans: a plan waits for a person unless the board's phase auto-approves it. Both refuse a repository the Factory doesn't link, and a card synced from an issue keeps the issue's repository. Stages, the board and role sessions aren't fields it edits; stages move with `factory_transition_work_item`. Subscriptions are stored per work item and session in the `factory_work_item_subscriptions` collection and are removed with the item, so any number of sessions can follow one item.
|
|
1112
1225
|
|
|
1113
1226
|
#### Messaging between sessions
|
|
1114
1227
|
|
|
@@ -1272,6 +1385,14 @@ pnpm --filter ./mastracode/factory build:lib
|
|
|
1272
1385
|
pnpm --filter ./mastracode/factory smoke:dist
|
|
1273
1386
|
```
|
|
1274
1387
|
|
|
1388
|
+
The full `test` suite takes several minutes. For quick verification, run only the colocated test files for the code you changed:
|
|
1389
|
+
|
|
1390
|
+
```bash
|
|
1391
|
+
pnpm --filter ./mastracode/factory exec vitest run <test-files> --reporter=dot --bail 1
|
|
1392
|
+
```
|
|
1393
|
+
|
|
1394
|
+
Broad runs, like the full suite, whole `src/integrations` or `src/rules` directories, `vitest related`, or `vitest run --changed`, can fan out to most of the suite because many modules are shared. Run them in the background or leave them to CI.
|
|
1395
|
+
|
|
1275
1396
|
Tests are colocated with source as `*.test.ts`. Use `smoke:dist` after building to verify that the published entry point can be imported successfully.
|
|
1276
1397
|
|
|
1277
1398
|
## Changelog
|