Hooks & Enforcement

For leads and PMs: your workflow runs itself and your PM tool is always current. Every status transition gets a comment. Every issue moves through the right stages. You get process compliance without chasing developers.

For developers: the agent handles process overhead so you focus on code. Formatting, context loading, script approval, status updates — all happen automatically. You stop thinking about process and start shipping.

How? Hooks — platform-triggered scripts that fire automatically on specific events. They are not suggestions the AI might follow. They are not instructions it could skip. They are code-level gates that run unconditionally, every time, regardless of what the AI decides to do. A 400-line instructions file is still a suggestion. Hooks are enforcement.

The 7 hooks

FlyDocs uses 7 hooks across 5 event types. Each fires at a specific point in the AI interaction lifecycle.

The enforcement story

Consider what happens without hooks. You write in your instructions file: "Always format code after editing." The AI follows that instruction 90% of the time. The other 10%, it forgets, gets distracted by a complex task, or decides formatting is not needed. You write: "Always add a comment when transitioning an issue." The AI does it when it remembers.

Hooks eliminate the 10%. The post-edit hook formats every file the AI touches, every time. The transition validation hook catches missing comments on every status change. The stop gate blocks the AI from finishing with an issue still in progress. These are not instructions the AI interprets. They are code that runs.

The CI/CD analogy

A CI pipeline runs tests whether or not the developer remembers to. It does not trust the developer to always run tests before pushing. It enforces the rule at the infrastructure level.

Hooks do the same thing for AI-assisted development. They do not trust the AI to always format code, always inject context, or always validate transitions. They enforce it at the platform level. The AI cannot opt out. Hooks are to AI development what CI pipelines are to code quality -- an infrastructure-level guarantee that the process is followed.

Event types

Matchers narrow which tool invocations trigger a hook. Bash|Edit|Write matches file and command operations. Bash alone matches shell commands. An empty matcher matches all invocations of that event type.

How hooks are configured

Hooks are registered in .claude/settings.json. Each hook specifies the event it triggers on, an optional matcher pattern, the script it runs, and a timeout:

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command",
        "command": "python3 .claude/hooks/context-injection.py",
        "timeout": 10 }] }
    ],
    "PreToolUse": [
      { "matcher": "Bash|Edit|Write",
        "hooks": [{ "type": "command",
          "command": "python3 .claude/hooks/auto-approve.py",
          "timeout": 5 }] }
    ],
    "PostToolUse": [
      { "matcher": "Edit|Write",
        "hooks": [{ "type": "command",
          "command": "python3 .claude/hooks/post-edit.py",
          "timeout": 30 }] },
      { "matcher": "Bash",
        "hooks": [{ "type": "command",
          "command": "python3 .claude/hooks/post-bash.py",
          "timeout": 10 }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command",
        "command": "python3 .claude/hooks/stop-gate.py",
        "timeout": 10 }] }
    ],
    "SessionStart": [
      { "hooks": [{ "type": "command",
        "command": "python3 .claude/hooks/session-start.py",
        "timeout": 10 }] }
    ]
  }
}

The hook scripts live in .claude/hooks/:

.claude/hooks/
├── context-injection.py   # Injects git state, active issue, workflow position
├── auto-approve.py        # Approves FlyDocs skill scripts without confirmation
├── post-edit.py           # Formats code, logs to audit trail
├── post-bash.py           # PR validation, transition validation
└── stop-gate.py           # Blocks completion with incomplete work
    session-start.py       # Injects previous session summary

These scripts are installed by FlyDocs during setup and maintained as managed artifacts. They are small, focused, and readable -- you can inspect exactly what each hook does by reading the Python files directly. On the cloud tier, the server delivers the latest hook scripts automatically so every team member runs the same enforcement layer.

Hooks vs rules vs skills

If something must happen every time without exception, it belongs in a hook. If it is methodology the AI should follow with structured steps, it belongs in a skill. If it is a preference or convention, it belongs in a rule. The layers are complementary: skills define the workflow, rules guide the AI's behavior, and hooks enforce what cannot be left to chance.

Next

• Context & Memory: how context injection and session continuity work in practice
• Skills: the knowledge and procedures that hooks enforce
• Workflow Lifecycle: the stages where hooks validate transitions