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