Files
archie/docs/development/workflows.md
T
sam 721968eeff fix(workflow): derive a declared output's captures need for profile selection
A declared output is written through a capture tool, but the dispatch-time
harness check read only the workflow's needs.captures. A workflow that
declared outputs without also writing needs: {captures: true} could name a
Kit profile whose adapter serves no capture tools; a required output then
parked with "output %q is required" instead of the profile being refused.

WorkflowInterface.Needs now reports captures for a non-empty Outputs beside
the declared needs, and the profile check and Kit launcher read it. The
needs: block keeps its meaning for a workflow that captures without
declaring outputs.

- internal/domain/workflow/task: Needs() derives captures; DeclaredNeeds
  carries only the declared block.
- internal/daemon: pinTaskProfile and runKitTask read Needs().
- tests: parse-time derivation, and pinTaskProfile refusing an
  outputs-declaring workflow against a Kit adapter with no capture MCP.
2026-10-02 03:19:07 +10:00

64 lines
3.2 KiB
Markdown

# Workflows
Authority: `docs/architecture/agent-system.md` for the lifecycle,
`docs/prds/event-automation.md` for inputs, repository modes and profiles.
Workflow definitions are YAML stored as a control-plane resource. The State
Store validates them and the agent compiles them, each against the step
vocabulary it registers, so both must see the same step types.
## Adding a step type
1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes
and validates its settings and returns an error for anything it cannot
honour. The factory runs when a definition is saved and again when it is
compiled, so a bad definition is refused on save.
2. Register it through a provider in
`internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is
what every process registers, which is how the validating and executing
sides agree.
3. An agent-driven step builds on `AgentStage`; do not start a second path to
the agent runner.
4. A step that needs no repository goes in `repoFreeStepTypes` in
`definition.go`, or workflows declaring `repository: none` or `optional`
cannot use it. A step that needs one may assume `tc.Dir` holds a worktree
only when the workflow's repository is `required`.
5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of
steps without an outcome is parked as a definition bug.
6. Add a parse test (settings accepted and refused) and a run test with fake
`Trees` and agent runner.
## Changing the definition format
- The fields a caller needs without the engine (inputs, repository, profile)
live in `task.WorkflowInterface`, because the dashboard process must not
import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a
binding or the dashboard checks goes there.
- The YAML decoder rejects unknown keys. Existing stored definitions must keep
parsing, so a new key is optional with a default that preserves today's
behaviour.
- A declared `outputs:` entry is written through a capture tool, so it forces
the captures need: `task.WorkflowInterface.Needs` resolves that from the
declaration rather than the author also writing `needs.captures`. A Kit
profile whose harness serves no capture tools is refused before dispatch.
- Examples in `examples/workflows/` are parsed against the registered
vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.
## Enabling and disabling
The `workflow-enablement` control-plane resource lists, per org, the workflows
that org has disabled; anything unlisted is enabled. Its readers are the
daemon's binding dispatch (a disabled workflow's binding is skipped like an
unarmed one), the dashboard's binding save (refused) and binding list
(`workflow_disabled`), and work requests. A new reader of "may this org run
this workflow" goes through `task.WorkflowEnablement.Enabled`, never a second
list. The dashboard acts in the default org until access resolves a caller's
own.
## Starting a workflow from chat
`task_spawn` accepts `workflow` and an `inputs` object. The gateway forwards
inputs through the task creation contract; it does not interpret individual
workflows. The daemon checks inputs against the pinned `WorkflowInterface`
before acquiring a container and parks invalid requests with the reason.