# Proactive Engineering Behaviour

> These rules are written for Claude Code but the concepts apply to any AI agent system.

## Before Any Task: System Consistency Check

Before starting any work, scan for known failure patterns and surface them explicitly. Do not wait for the operator to discover them. A good engineer notices the thing adjacent to the reported problem.

Check in particular:
- Settings allow list: does any rule auto-approve a class of commands that should require human confirmation?
- Hook chain: is every hook wired into settings AND executable?
- Tool manifest: does every tool listed have a named volume in compose.yml?
- compose.yml: does every named volume have a corresponding entry in the `volumes:` block at the top?
- Dockerfile: does every tool in the manifest appear in the Dockerfile?

## After Any Fix: Propagation Check

After fixing a problem, ask: "what else has this same underlying issue?"

Examples:
- Fixed a missing volume for Codex → check Gemini has one too
- Fixed a broken hook → check all hooks are executable and wired
- Fixed a stale doc → check all docs referencing the same system state

## The "What Layer Does This Live On?" Question

Before suggesting any install or configuration step inside a running container, explicitly state which Docker layer it targets:

| Layer | Survives | Notes |
|-------|----------|-------|
| Image (Dockerfile RUN) | Everything | Requires image rebuild to change |
| Named volume | Restart + rebuild, NOT `compose down -v` | Auth/config persistence |
| Bind mount | Everything | Host filesystem |
| Container overlay | Nothing — EPHEMERAL | Wrong layer for anything durable |

If the answer is "container overlay": stop. That is the wrong layer.

## New Tool Checklist (from ADR-001)

No new CLI tool is complete until ALL of these are done:

1. [ ] Binary baked into Dockerfile (RUN line)
2. [ ] Named volume defined in compose.yml volumes block
3. [ ] Named volume mounted to auth directory in service definition
4. [ ] Tool listed in bootstrap manifest
5. [ ] Bootstrap script has a "Found / Not found" check for the binary
6. [ ] Documentation updated with tool entry

Partial completion = broken. A tool with binary but no volume loses auth on compose down. A tool with volume but no binary vanishes on image rebuild.