New Hook Flow

AI runs orchestrator with --dry-run:

python scripts/devops/scaffold/new_hook.py   --id "<hook_id>"   --event-type "<event_type>"   --blocking true   --handler-kind script   --handler-command "scripts/hooks/<hook_id>.py"   --summary "Brief description of hook purpose"   --order 100   --dry-run --json

AI presents planned_changes to human.

Human checkpoint: Review and approve planned changes.

Step 4: Execute Registration (AI)

AI runs orchestrator without --dry-run:

python scripts/devops/scaffold/new_hook.py   --id "<hook_id>"   --event-type "<event_type>"   --blocking true   --handler-kind script   --handler-command "scripts/hooks/<hook_id>.py"   --summary "Brief description of hook purpose"   --json

The orchestrator validates the hook registration against hook.schema.yaml.

Step 5: Create Handler Placeholder (AI)

If handler script does not exist, the orchestrator creates a placeholder:

#!/usr/bin/env python3
"""Hook handler for <hook_id>."""

def handle(event):
    """Handle the <event_type> event."""
    # TODO: Implement handler logic
    return {"status": "ok"}

if __name__ == "__main__":
    import json
    import sys
    event = json.loads(sys.stdin.read())
    result = handle(event)
    print(json.dumps(result))

Step 6: Verify Results (AI)

AI verifies:

• Hook file exists in /.system/hooks/
• hooks.py --check passes
• Handler placeholder exists (if created)

Step 7: Record in Workdocs (AI)

AI records scaffold execution:

• Task ID, timestamp, parameters
• Hook file created
• Handler placeholder created (if applicable)
• Follow-up: implement actual handler logic