ArcheFlow Hook Points

Hooks let you run custom commands at key points during an ArcheFlow orchestration run. Use them for notifications, custom validation, CI integration, or project-specific checks.

Available Hooks

Hook	When	Env Vars	Default `fail_action`
`run-start`	After initialization, before Plan phase begins	`ARCHEFLOW_RUN_ID`, `ARCHEFLOW_WORKFLOW`, `ARCHEFLOW_TASK`	`warn`
`phase-complete`	After each PDCA phase finishes	`ARCHEFLOW_RUN_ID`, `ARCHEFLOW_PHASE`, `ARCHEFLOW_CYCLE`	`warn`
`agent-complete`	After each agent returns	`ARCHEFLOW_RUN_ID`, `ARCHEFLOW_AGENT`, `ARCHEFLOW_PHASE`, `ARCHEFLOW_DURATION_MS`	`warn`
`pre-merge`	After all reviewers approve, before merging to target branch	`ARCHEFLOW_RUN_ID`, `ARCHEFLOW_BRANCH`, `ARCHEFLOW_TARGET`	`abort`
`post-merge`	After successful merge to target branch	`ARCHEFLOW_RUN_ID`, `ARCHEFLOW_BRANCH`, `ARCHEFLOW_MERGE_COMMIT`	`warn`
`run-complete`	After the run finishes (success or failure)	`ARCHEFLOW_RUN_ID`, `ARCHEFLOW_STATUS`, `ARCHEFLOW_CYCLES`, `ARCHEFLOW_DURATION_S`	`warn`

Configuration

Add a hooks: section to your project's .archeflow/config.yaml:

hooks:
  run-start:
    command: "echo 'Run starting: $ARCHEFLOW_RUN_ID'"
    fail_action: warn
  pre-merge:
    command: "./scripts/lint-check.sh"
    fail_action: abort
  run-complete:
    command: "curl -X POST https://slack.example.com/webhook -d '{\"text\": \"ArcheFlow run $ARCHEFLOW_STATUS\"}'"
    fail_action: warn

Each hook entry has two fields:

command -- shell command to execute. Env vars are available. Runs with bash -c.
fail_action -- what happens if the command exits non-zero:
- warn -- log a warning, continue the run
- abort -- stop the run immediately, report the failure

`fail_action` Semantics

`fail_action`	On command exit 0	On command exit non-zero
`warn`	Continue silently	Log warning, continue
`abort`	Continue silently	Emit `decision` event with `"chosen":"hook_abort"`, halt run, report to user

Recommended settings:

Use abort for pre-merge -- a failing pre-merge check should block the merge
Use warn for informational hooks (run-start, run-complete, post-merge)
Use warn for agent-complete and phase-complete unless you have strict SLA requirements

Examples

Slack notification on run complete

hooks:
  run-complete:
    command: >
      curl -s -X POST "$SLACK_WEBHOOK_URL"
        -H 'Content-Type: application/json'
        -d '{"text":"ArcheFlow run '"$ARCHEFLOW_RUN_ID"' '"$ARCHEFLOW_STATUS"' ('"$ARCHEFLOW_CYCLES"' cycles, '"$ARCHEFLOW_DURATION_S"'s)"}'
    fail_action: warn

Pre-merge lint gate

hooks:
  pre-merge:
    command: "npm run lint && npm run typecheck"
    fail_action: abort

Log phase timing

hooks:
  phase-complete:
    command: "echo \"$(date -u +%H:%M:%S) phase=$ARCHEFLOW_PHASE cycle=$ARCHEFLOW_CYCLE run=$ARCHEFLOW_RUN_ID\" >> .archeflow/phase-timing.log"
    fail_action: warn

Hook Execution

Hooks are executed by the archeflow:run skill at the corresponding lifecycle point. The command runs in the project root directory with bash -c. A 30-second timeout applies to each hook -- if a hook exceeds this, it is killed and treated as a failure (subject to fail_action).

Hooks are optional. If no hooks: section exists in config, no hooks run. If a specific hook event is not configured, it is silently skipped.

3.6 KiB Raw Blame History