Files
archie/docs/development/workflows.md
T
sam e5a7fadcd6 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

3.2 KiB

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.