89 lines
3.6 KiB
Markdown
89 lines
3.6 KiB
Markdown
# 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`:
|
|
|
|
```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
|
|
|
|
```yaml
|
|
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
|
|
|
|
```yaml
|
|
hooks:
|
|
pre-merge:
|
|
command: "npm run lint && npm run typecheck"
|
|
fail_action: abort
|
|
```
|
|
|
|
### Log phase timing
|
|
|
|
```yaml
|
|
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.
|