Flow: New Hook Registration

This doc contains the step-by-step flow. For inputs, tools, outputs, and safety, see /.system/skills/ssot/repo/scaffolding/new-hook/SKILL.md.

Step-by-Step Flow (AI + Human)

Step 1: Collect Parameters (AI -> Human)

AI asks human for:

1. •Hook ID (validate: unique, follows naming convention)
2. •Event type (which lifecycle event to respond to)
3. •Blocking behavior (should it block execution?)
4. •Handler details (script path or function reference)
5. •Optional: match conditions for selective execution

Human checkpoint: Confirm parameters before proceeding.

Step 2: Validate Inputs (AI)

AI validates:

• •id uniqueness in existing hooks
• •event_type is valid
• •Handler reference is valid (if script, file exists or will be created)
• •Filename will match id

Step 3: Preview Changes (AI)

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