A workflow-enablement control-plane resource lists, per org, the workflows that org has disabled. A binding targeting a disabled workflow is skipped at dispatch like an unarmed one, is refused on save, and is flagged on the binding list; the workflows page toggles it. Bindings now carry the org_id column they already had in storage, over the State Store wire too. Org-owned workflow definitions are deferred to a follow-up bead: they need the caller's org, which the access chain resolves.
60 lines
2.9 KiB
Markdown
60 lines
2.9 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.
|
|
- 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.
|