Workflow Design -- PDCA Cycles

PDCA cycles spiral upward: each cycle incorporates feedback from the previous one.

Built-in Workflows

/archeflow:run knows exactly these three workflows (--workflow <name>, or workflow: in .archeflow/config.yaml). Files in .archeflow/workflows/ and .archeflow/teams/ (copied there by bundles) describe a setup for people reading it; the run does not read them.

Shaping a run

Lenses and patterns are described in the run skill's reference.md. More than 3 cycles rarely converges; if two cycles did not, change the task, not the cycle count.

Hooks

The one hook specification (the run skill and docs/hooks.md follow it). Hooks live in .archeflow/hooks.yaml, one top-level key per hook:

pre-merge:
  command: "npm run lint && npm run typecheck"
  fail_action: abort
run-complete:
  command: "echo run $ARCHEFLOW_RUN_ID finished: $ARCHEFLOW_STATUS >> .archeflow/hooks.log"
  fail_action: warn

There are no other hook points; other keys in hooks.yaml are ignored (say so if you find one).

fail_action: warn = log and continue; abort = emit a decision event ({"what": "hook", "chosen": "hook_abort"}), stop the run and report.

Hooks are run by the orchestrating agent, not by a script. The file comes from the repository, so show each hook command to the user and get a yes before its first run in a session; never run a hook the user declined. The yes covers that exact command text: if hooks.yaml changed since (during a run, or after a pull), show the new command and ask again. To run one, write its command to .archeflow/artifacts/<run_id>/hook.sh with your file tool, then from the project root: ARCHEFLOW_RUN_ID=<run_id> <other variables> bash .archeflow/artifacts/<run_id>/hook.sh.

Anti-Patterns

• Using thorough for small changes (cost without benefit)
• Re-running a run that hit a Wiggum Break without changing the task
• Skipping the Check phase