9thlevelsoftware/legion/hooks-integration

Hooks Integration

Defines Claude Code hook configurations for automating Legion lifecycle events. Hooks are opt-in — users configure them in their Claude Code settings. This skill documents the recommended hooks and their behavior.

Section 1: Overview

Claude Code hooks execute shell commands before or after specific events (tool calls, commands, etc.). Legion leverages hooks for:

1. Pre-build validation — validate plan schemas before execution starts
2. Post-build outcome recording — auto-record outcomes to memory after builds
3. Pre-ship security gate — run security scan before ship pipeline
4. Post-commit state update — update STATE.md progress after commits

Hooks are configured in .claude/settings.json (project-level) or ~/.claude/settings.json (global). Users must opt in — Legion never auto-installs hooks.

Section 2: Recommended Hook Configurations

2.1: Pre-Build Plan Validation

Validates plan file integrity before /legion:build executes.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Agent",
        "hooks": [
          {
            "type": "command",
            "command": "node -e \"const fs=require('fs'); const p='.planning/STATE.md'; if(!fs.existsSync(p)){process.exit(0)} const s=fs.readFileSync(p,'utf8'); if(!s.includes('Current')){console.error('STATE.md malformed'); process.exit(1)}\"",
            "description": "Legion: validate STATE.md before agent spawn"
          }
        ]
      }
    ]
  }
}

When: Before any Agent tool call (catches build agent spawns) What: Checks STATE.md exists and has required structure On failure: Blocks the agent spawn, displays error

2.2: Post-Build Outcome Notification

Notifies the user when a build phase completes.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Agent",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Legion: Agent task completed'",
            "description": "Legion: notify on agent completion"
          }
        ]
      }
    ]
  }
}

When: After any Agent tool call completes What: Simple notification (can be extended to trigger memory recording) Note: Full outcome recording still happens in the build command — this hook is informational

2.3: Pre-Ship Security Gate

Runs a lightweight security check before /legion:ship creates a PR.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node -e \"const cmd=process.env.CLAUDE_TOOL_INPUT||''; if(cmd.includes('gh pr create')){const r=require('child_process').execSync('npm audit --audit-level=critical 2>/dev/null',{encoding:'utf8',stdio:'pipe'}); if(r.includes('critical')){console.error('CRITICAL vulnerabilities found. Run npm audit fix before shipping.'); process.exit(1)}}\"",
            "description": "Legion: security gate before PR creation"
          }
        ]
      }
    ]
  }
}

When: Before any Bash call that includes gh pr create What: Runs npm audit and blocks if critical vulnerabilities found On failure: Blocks PR creation with security warning

Section 3: Installation Guide

For Users

To enable Legion hooks, add the desired hook configurations to your project's .claude/settings.json:

1. Open or create .claude/settings.json in the project root
2. Add the hooks section with desired configurations from Section 2
3. Hooks activate immediately on the next Claude Code session

Configuration Tips

• Start with just the pre-build validation hook — it's the lowest-risk, highest-value
• The pre-ship security gate may produce false positives on projects with known audit issues
• Hooks run synchronously — keep commands fast (under 2 seconds)
• Use process.exit(0) to pass silently, process.exit(1) to block with error

Removing Hooks

Delete the hooks section from .claude/settings.json. Hooks deactivate immediately.

Section 4: Integration with Legion Commands

What Hooks Do NOT Replace

Hooks are lightweight automation. They do NOT replace:

• The full security-review skill (hooks run simple checks; the skill runs comprehensive OWASP analysis)
• The memory-manager outcome recording (hooks notify; the skill records structured outcomes)
• The authority-enforcer boundary checks (hooks can't access plan file context)

Section 5: Graceful Degradation

• If hooks are not configured: Legion operates identically to pre-hook behavior
• If a hook command fails to execute (not found, permission denied): Claude Code logs the error and continues
• Hooks are Claude Code-specific — other CLI adapters ignore this skill entirely
• Hook configurations in this skill are recommendations, not requirements