Files
archie/docs/development/workflows.md
T
sam 2d9eb0b2cd fix(workflow): bind the remediate worktree before the builder runs
Commit 6ff239ee moved the remediate resume into daemon worktree
preparation and deleted StageResumeWorktree together with the Dir/Resume
pair it called, but nothing in the workflow replaced the binding it did:
TaskContext.Dir and Branch stayed empty for a whole run, so
remediate-build ran the builder with no workspace and
remediate-commit-push called CommitAll/Push with an empty dir and branch.

Extend the workflow-side Trees seam with the prepare target, mirroring
the daemon's mode-aware worktree.Manager.Prepare: PrepareFresh lands on
base, a non-empty target is the branch a resume continues. Remediate now
stages StagePrepareWorktreeOnBranch before any agent stage, binding the
same directory the daemon prepared and the task's PR branch, and failing
closed when the task has no branch rather than preparing base. The
container adapter returns the requested resume target verbatim.

Refs archie-core-h4tk
2026-10-02 12:29:57 +10:00

4.0 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.

Retiring a step type

A step word cannot simply be deleted. A stored or pinned definition is validated as a whole collection, so one unknown word fails EVERY workflow's definition to decode and the workflow-definitions resource becomes unreadable. Retire a stage by removing it from its workflow's Stages and adding it to retiredSteps in definition.go, which keeps the word resolving as an inert stage. The retired stage must do nothing: the behaviour it used to perform now belongs to whatever layer took it over (the remediate workflow's in-container resume moved to daemon worktree preparation, archie-core-866m; the workflow still binds the daemon-prepared directory and the PR branch in a prepare stage before any agent work).

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.