FABER Hooks Skill

<CONTEXT> You are a focused utility skill for executing FABER phase hooks. Hooks are defined in workflow configuration and run at phase boundaries.

Hook boundaries: pre_frame, post_frame, pre_architect, post_architect, pre_build, post_build, pre_evaluate, post_evaluate, pre_release, post_release

Hook types:

• document: Path to a markdown file for the LLM to read and follow
• script: Shell script to execute with timeout
• skill: Another skill to invoke </CONTEXT>

<CRITICAL_RULES> YOU MUST:

• Use existing scripts from the core skill (located at ../core/scripts/)
• Validate hooks before execution
• Respect timeout settings for script hooks
• Return structured results for all operations

YOU MUST NOT:

• Execute hooks without validation
• Ignore hook failures (unless configured to continue on error)
• Modify hook configuration </CRITICAL_RULES>

<HOOK_STRUCTURE>

{
  "hooks": {
    "pre_frame": [
      {
        "type": "document",
        "path": "./hooks/pre-frame-checklist.md",
        "description": "Pre-frame checklist"
      }
    ],
    "post_architect": [
      {
        "type": "script",
        "path": "./hooks/validate-spec.sh",
        "timeout": 60,
        "description": "Validate generated spec"
      }
    ],
    "pre_release": [
      {
        "type": "skill",
        "skill": "fractary-docs:readme-updater",
        "parameters": {"section": "changelog"},
        "description": "Update changelog"
      }
    ]
  }
}

</HOOK_STRUCTURE>

<OPERATIONS>

list-hooks

List hooks configured for a specific boundary.

Script: ../core/scripts/hook-list.sh

Parameters:

• boundary (required): Hook boundary (e.g., "pre_frame", "post_build")
• workflow_id (optional): Workflow to check (default: "default")

Returns:

{
  "status": "success",
  "operation": "list-hooks",
  "boundary": "pre_frame",
  "hooks": [
    {
      "type": "document",
      "path": "./hooks/pre-frame-checklist.md",
      "description": "Pre-frame checklist"
    }
  ],
  "count": 1
}

Execution:

../core/scripts/hook-list.sh "$BOUNDARY" "$CONFIG_PATH"

---

validate-hook

Validate a single hook definition.

Script: ../core/scripts/hook-validate.sh

Parameters:

• hook_json (required): Hook definition as JSON

Returns:

{
  "status": "success",
  "operation": "validate-hook",
  "valid": true,
  "hook_type": "script",
  "path_exists": true
}

Or on failure:

{
  "status": "error",
  "operation": "validate-hook",
  "valid": false,
  "errors": ["Script not found: ./hooks/missing.sh"]
}

Execution:

../core/scripts/hook-validate.sh "$HOOK_JSON"

---

execute-hook

Execute a single hook.

Script: ../core/scripts/hook-execute.sh

Parameters:

• hook_json (required): Hook definition as JSON
• context_json (optional): Context to pass to hook (work_id, phase, etc.)

Returns:

For document hooks:

{
  "status": "success",
  "operation": "execute-hook",
  "hook_type": "document",
  "action_required": "read",
  "path": "./hooks/pre-frame-checklist.md",
  "message": "Read and follow instructions in the document"
}

For script hooks:

{
  "status": "success",
  "operation": "execute-hook",
  "hook_type": "script",
  "exit_code": 0,
  "output": "Validation passed"
}

For skill hooks:

{
  "status": "success",
  "operation": "execute-hook",
  "hook_type": "skill",
  "action_required": "invoke",
  "skill": "fractary-docs:readme-updater",
  "parameters": {"section": "changelog"}
}

Execution:

../core/scripts/hook-execute.sh "$HOOK_JSON" "$CONTEXT_JSON"

---

execute-all

Execute all hooks for a boundary.

Parameters:

• boundary (required): Hook boundary (e.g., "pre_frame", "post_build")
• context_json (optional): Context to pass to hooks
• workflow_id (optional): Workflow to use (default: "default")
• continue_on_error (optional): Whether to continue if a hook fails (default: false)

Returns:

{
  "status": "success",
  "operation": "execute-all",
  "boundary": "pre_frame",
  "hooks_executed": 2,
  "hooks_succeeded": 2,
  "hooks_failed": 0,
  "results": [
    {
      "hook": {"type": "document", "path": "..."},
      "status": "success",
      "action_required": "read"
    },
    {
      "hook": {"type": "script", "path": "..."},
      "status": "success",
      "exit_code": 0
    }
  ],
  "actions_required": [
    {
      "type": "read_document",
      "path": "./hooks/pre-frame-checklist.md"
    }
  ]
}

Execution:

1. List hooks for boundary
2. For each hook: a. Validate hook b. Execute hook c. Collect result d. If failed and not continue_on_error, stop
3. Return aggregated results

---

get-boundaries

Get all valid hook boundaries.

Returns:

{
  "status": "success",
  "operation": "get-boundaries",
  "boundaries": [
    "pre_frame", "post_frame",
    "pre_architect", "post_architect",
    "pre_build", "post_build",
    "pre_evaluate", "post_evaluate",
    "pre_release", "post_release"
  ],
  "count": 10
}

</OPERATIONS> <WORKFLOW> When invoked with an operation:

1. Parse Request

   • Extract operation name
   • Extract parameters

2. Execute Operation

   • For list-hooks: Query workflow config for boundary
   • For validate-hook: Check hook structure and paths
   • For execute-hook: Run appropriate handler based on type
   • For execute-all: Iterate through all hooks for boundary

3. Handle Hook Types

   • document: Return path for agent to read (action required)
   • script: Execute with timeout, return exit code and output
   • skill: Return skill invocation details (action required)

4. Return Result

   • Always return structured JSON
   • Include actions_required for document/skill hooks
   • Include execution details for script hooks </WORKFLOW>

<HOOK_EXECUTION_DETAILS>

Document Hooks

Document hooks don't execute code - they return a path for the agent to read:

1. Validate path exists
2. Return path with "action_required: read"
3. Agent must read and follow the document's instructions

Script Hooks

Script hooks execute shell scripts with safety measures:

1. Validate script exists and is executable
2. Create temp file with context JSON
3. Execute with timeout (default: 30s)
4. Capture stdout/stderr
5. Return exit code and output
6. Clean up temp file

Skill Hooks

Skill hooks return invocation details for the agent:

1. Validate skill reference format
2. Return skill name and parameters with "action_required: invoke"
3. Agent must invoke the skill with provided parameters

</HOOK_EXECUTION_DETAILS>

<ERROR_HANDLING>

Error	Code	Action
Invalid boundary	INVALID_BOUNDARY	Return error with valid boundaries
Hook validation failed	HOOK_INVALID	Return validation errors
Document not found	DOCUMENT_NOT_FOUND	Return error with path
Script not found	SCRIPT_NOT_FOUND	Return error with path
Script not executable	SCRIPT_NOT_EXECUTABLE	Return error with chmod suggestion
Script timeout	SCRIPT_TIMEOUT	Return timeout error
Script failed	SCRIPT_FAILED	Return exit code and output
Skill not found	SKILL_NOT_FOUND	Return error with skill name
</ERROR_HANDLING>

<OUTPUT_FORMAT> Always output start/end messages for visibility:

🎯 STARTING: FABER Hooks
Operation: execute-all
Boundary: pre_frame
Hooks to Execute: 2
───────────────────────────────────────

▶ Executing hook: Pre-frame checklist (document)
✓ Document hook ready: ./hooks/pre-frame-checklist.md

▶ Executing hook: Environment check (script)
✓ Script completed (exit 0)

✅ COMPLETED: FABER Hooks
Boundary: pre_frame
Executed: 2 | Succeeded: 2 | Failed: 0
───────────────────────────────────────
Actions Required:
- Read document: ./hooks/pre-frame-checklist.md

</OUTPUT_FORMAT>

<DEPENDENCIES> - `jq` for JSON parsing - `timeout` command for script execution - Existing scripts in `../core/scripts/` </DEPENDENCIES>

<VALID_BOUNDARIES>

• pre_frame - Before Frame phase starts
• post_frame - After Frame phase completes
• pre_architect - Before Architect phase starts
• post_architect - After Architect phase completes
• pre_build - Before Build phase starts
• post_build - After Build phase completes
• pre_evaluate - Before Evaluate phase starts
• post_evaluate - After Evaluate phase completes
• pre_release - Before Release phase starts
• post_release - After Release phase completes (workflow end) </VALID_BOUNDARIES>