zhongwei/gh-jpicklyk-task-orchestrator-claude-plugins-task-orchestrator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-jpicklyk-task-orchestrat…/skills/task-orchestrator-hooks-builder/examples.md
Zhongwei Li 87c03319a3 Initial commit
2025-11-30 08:29:28 +08:00

25 KiB
Raw Permalink Blame History

Task Orchestrator Hooks - Working Examples

This document provides complete working examples of hooks that integrate with Task Orchestrator's workflow cascade event system. All examples follow the opinionated approach (auto-apply by default) with clear guidance on when to use conservative alternatives.

Overview

Three example hooks are provided:

  1. cascade-auto-progress.sh - Opinionated auto-apply with audit trail (RECOMMENDED)
  2. flow-aware-gate.sh - Adaptive quality gates based on workflow flow
  3. cascade-logger.sh - Non-blocking analytics for learning patterns (SAFE for production)

All examples are located in: src/main/resources/claude/skills/task-orchestrator-hooks-builder/example-hooks/

Quick Start

Installation Steps

  1. Copy hook to your project's hooks directory:

    # Create hooks directory if it doesn't exist
mkdir -p .claude/hooks

# Copy desired example hook
cp src/main/resources/claude/skills/task-orchestrator-hooks-builder/example-hooks/cascade-auto-progress.sh \
   .claude/hooks/cascade-auto-progress.sh

# Make executable
chmod +x .claude/hooks/cascade-auto-progress.sh

  2. Register hook in Claude Code settings: Edit .claude/settings.local.json (create if doesn't exist):

    {
  "hooks": {
    "postToolUse": [
      {
        "hook": ".claude/hooks/cascade-auto-progress.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      }
    ]
  }
}

  3. Test the hook (see Testing section below)

Example 1: Cascade Auto-Progress (Opinionated)

Purpose

Automatically logs cascade events for auto-application when automatic=true. This is the RECOMMENDED opinionated approach for most projects.

Use Cases

✅ Use this when:

  • Normal development workflows
  • You trust the Task Orchestrator's cascade event logic
  • You want automatic progression (Task complete → Feature progresses → Project progresses)
  • You need an audit trail of all cascade events

⚠️ Consider alternatives when:

  • Critical production deployments requiring manual approval
  • Security/compliance workflows needing sign-off
  • Learning/training environments where you want to see every step
  • You need full control over every status transition

Installation

# Copy to hooks directory
cp src/main/resources/claude/skills/task-orchestrator-hooks-builder/example-hooks/cascade-auto-progress.sh \
   .claude/hooks/cascade-auto-progress.sh

# Make executable
chmod +x .claude/hooks/cascade-auto-progress.sh

Register in .claude/settings.local.json:

{
  "hooks": {
    "postToolUse": [
      {
        "hook": ".claude/hooks/cascade-auto-progress.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      }
    ]
  }
}

Expected Behavior

When a cascade event occurs (e.g., all tasks in a feature complete):

════════════════════════════════════════════
🔄 CASCADE EVENT PROCESSING (Opinionated Mode)
════════════════════════════════════════════

Event #1: all_tasks_complete
  Target: User Authentication (feature)
  Status: in-development → testing
  Flow: default_flow
  Reason: All tasks completed, ready for testing phase
  ✅ AUTO-APPLY: Logging for orchestrator to apply status
     Cascade event logged - orchestrator will apply status automatically

════════════════════════════════════════════
✓ Cascade event processing complete
  Log: .claude/metrics/cascade-events.csv
════════════════════════════════════════════

Audit Trail (~/.claude/metrics/cascade-events.csv):

2025-10-27T14:30:45Z,all_tasks_complete,feature,abc-123-def,"User Authentication",in-development,testing,default_flow,auto
2025-10-27T14:32:10Z,first_task_started,feature,abc-123-def,"User Authentication",planning,in-development,default_flow,auto

Sample Test Input

You can test this hook by simulating a manage_container response with cascade events:

# Create test input file
cat > test-cascade-input.json << 'EOF'
{
  "tool": "mcp__task-orchestrator__manage_container",
  "tool_input": {
    "operation": "setStatus",
    "containerType": "task",
    "id": "task-uuid-123",
    "status": "completed"
  },
  "tool_output": {
    "success": true,
    "data": {
      "cascadeEvents": [
        {
          "event": "all_tasks_complete",
          "targetType": "feature",
          "targetId": "feature-uuid-456",
          "targetName": "User Authentication",
          "currentStatus": "in-development",
          "suggestedStatus": "testing",
          "flow": "default_flow",
          "automatic": true,
          "reason": "All tasks completed, ready for testing phase"
        }
      ]
    }
  }
}
EOF

# Test the hook
cat test-cascade-input.json | .claude/hooks/cascade-auto-progress.sh

Customization

To make MORE conservative (require manual confirmation):

Change line 52 from:

if [ "$AUTOMATIC" == "true" ]; then

To:

if [ "$AUTOMATIC" == "true" ] && [ "$FLOW" != "with_review_flow" ]; then

This will require manual confirmation for security/compliance workflows.

To disable auto-apply entirely:

Use the Progressive Disclosure example instead (see Template 16 in hook-templates.md).

Example 2: Flow-Aware Quality Gate

Purpose

Adapts quality gate behavior based on workflow flow. Skips tests for prototypes, enforces strict validation for security features, runs standard tests for normal development.

Use Cases

✅ Use this when:

  • You have different types of features (prototypes, production, security)
  • You want fast iteration on experimental work
  • You need strict validation for compliance features
  • You tag your features consistently (prototype, security, etc.)

⚠️ Consider alternatives when:

  • All features should have the same quality standards
  • You don't use feature tags for workflow classification
  • You prefer consistent behavior across all work

Installation

# Copy to hooks directory
cp src/main/resources/claude/skills/task-orchestrator-hooks-builder/example-hooks/flow-aware-gate.sh \
   .claude/hooks/flow-aware-gate.sh

# Make executable
chmod +x .claude/hooks/flow-aware-gate.sh

Register in .claude/settings.local.json:

{
  "hooks": {
    "postToolUse": [
      {
        "hook": ".claude/hooks/flow-aware-gate.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      }
    ]
  }
}

Expected Behavior

For a feature tagged with "prototype":

════════════════════════════════════════════
🔍 FLOW-AWARE QUALITY GATE
════════════════════════════════════════════
  Detected Flow: rapid_prototype_flow
  Feature Tags: prototype, spike, frontend
  Target Status: testing

⚡ RAPID PROTOTYPE FLOW
   Skipping all quality gates for fast iteration
   Rationale: Prototypes prioritize speed over validation

   ✅ Quality gate skipped (by design)
════════════════════════════════════════════

For a feature tagged with "security":

════════════════════════════════════════════
🔍 FLOW-AWARE QUALITY GATE
════════════════════════════════════════════
  Detected Flow: with_review_flow
  Feature Tags: security, authentication, api
  Target Status: testing

🔒 SECURITY/COMPLIANCE FLOW
   Enforcing strict quality gates

   [1/2] Running full test suite...
       ✅ Tests passed (235 tests, 0 failures)
   [2/2] Running security vulnerability scan...
       ✅ Security scan passed (0 vulnerabilities)

   ✅ All strict quality gates passed
════════════════════════════════════════════

For a normal feature (default flow):

════════════════════════════════════════════
🔍 FLOW-AWARE QUALITY GATE
════════════════════════════════════════════
  Detected Flow: default_flow
  Feature Tags: backend, api, enhancement
  Target Status: testing

✓ DEFAULT FLOW
   Running standard quality gates

   [1/1] Running standard test suite...
       ✅ Tests passed (187 tests, 0 failures)

   ✅ Standard quality gates passed
════════════════════════════════════════════

Flow Detection

The hook detects workflow flow from feature tags:

Flow Detected Tags Behavior
rapid_prototype_flow prototype, spike, experiment Skip all tests
with_review_flow security, compliance, audit Strict validation + security scan
default_flow (anything else) Standard test suite

Sample Test Input

# Create test input for security feature
cat > test-flow-gate-input.json << 'EOF'
{
  "tool": "mcp__task-orchestrator__manage_container",
  "tool_input": {
    "operation": "setStatus",
    "containerType": "feature",
    "id": "feature-uuid-789",
    "status": "testing"
  },
  "tool_output": {
    "success": true,
    "data": {
      "id": "feature-uuid-789",
      "tags": "security,authentication,api"
    }
  }
}
EOF

# Test the hook (will attempt to run gradlew test)
cat test-flow-gate-input.json | .claude/hooks/flow-aware-gate.sh

Customization

To add a new flow (e.g., "experimental_flow"):

Add to flow detection (around line 42):

if echo "$TAGS" | grep -qE "prototype|spike|experiment"; then
  FLOW="rapid_prototype_flow"
elif echo "$TAGS" | grep -qE "experimental|research"; then
  FLOW="experimental_flow"
elif echo "$TAGS" | grep -qE "security|compliance|audit"; then
  FLOW="with_review_flow"
fi

Then add case handling (around line 58):

case "$FLOW" in
  "experimental_flow")
    echo "🔬 EXPERIMENTAL FLOW"
    echo "   Running fast tests only, skipping integration tests"
    ./gradlew test -x integrationTest || {
      # Block on failure
    }
    ;;

To make prototype flow less permissive:

Change line 60-67 to run minimal tests instead of skipping entirely:

"rapid_prototype_flow")
  echo "⚡ RAPID PROTOTYPE FLOW"
  echo "   Running smoke tests only (skipping full suite)"
  ./gradlew smokeTest || {
    cat << EOF
{
  "decision": "block",
  "reason": "Even prototypes must pass smoke tests. Fix failing tests before proceeding."
}
EOF
    exit 0
  }
  ;;

Example 3: Cascade Logger (Analytics)

Purpose

Non-blocking analytics hook that logs all cascade events to CSV for understanding workflow patterns. SAFE to add to production - observation only, never blocks or modifies behavior.

Use Cases

✅ Use this when:

  • Learning how cascade events work
  • Analyzing workflow patterns in your project
  • Collecting metrics on automation effectiveness
  • Need audit trail without affecting behavior
  • Want to understand which events are automatic vs manual

✅ Safe for:

  • Production environments (observation only)
  • Learning environments
  • Any project (zero risk)

Installation

# Copy to hooks directory
cp src/main/resources/claude/skills/task-orchestrator-hooks-builder/example-hooks/cascade-logger.sh \
   .claude/hooks/cascade-logger.sh

# Make executable
chmod +x .claude/hooks/cascade-logger.sh

Register in .claude/settings.local.json:

{
  "hooks": {
    "postToolUse": [
      {
        "hook": ".claude/hooks/cascade-logger.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      }
    ]
  }
}

Expected Behavior

When cascade events occur:

📊 Cascade Event Logger - Recording events for analytics
   ✓ Event #1: all_tasks_complete (feature) - auto=true, flow=default_flow
   ✓ Event #2: first_task_started (feature) - auto=true, flow=rapid_prototype_flow

📈 Summary Statistics:
   Total Events: 47
   Auto-Apply: 42 (89%)
   Manual Confirm: 5

   By Event Type:
     first_task_started: 15
     all_tasks_complete: 28
     all_features_complete: 4

   By Workflow Flow:
     default_flow: 32
     rapid_prototype_flow: 10
     with_review_flow: 5

✓ Cascade events logged successfully
  CSV Log: .claude/metrics/cascade-events.csv
  Summary: .claude/metrics/cascade-summary.json

  Analytics Queries:
    tail -10 .claude/metrics/cascade-events.csv  # Recent events
    cat .claude/metrics/cascade-summary.json     # Summary stats

CSV Output Format

File: .claude/metrics/cascade-events.csv

timestamp,event,target_type,target_id,target_name,current_status,suggested_status,flow,automatic,reason
2025-10-27T14:30:45Z,all_tasks_complete,feature,abc-123,"User Auth",in-development,testing,default_flow,true,"All tasks completed"
2025-10-27T14:32:10Z,first_task_started,feature,abc-123,"User Auth",planning,in-development,default_flow,true,"First task started"

JSON Summary Output

File: .claude/metrics/cascade-summary.json

{
  "total_cascade_events": 47,
  "automatic_events": 42,
  "manual_events": 5,
  "by_event_type": {
    "first_task_started": 15,
    "all_tasks_complete": 28,
    "all_features_complete": 4
  },
  "by_flow": {
    "default_flow": 32,
    "rapid_prototype_flow": 10,
    "with_review_flow": 5
  },
  "auto_percentage": 89,
  "last_updated": "2025-10-27T14:35:22Z"
}

Analytics Queries

View recent events:

tail -10 .claude/metrics/cascade-events.csv

Count auto vs manual:

tail -n +2 .claude/metrics/cascade-events.csv | grep ",true," | wc -l   # Auto
tail -n +2 .claude/metrics/cascade-events.csv | grep ",false," | wc -l  # Manual

Find all security flow events:

tail -n +2 .claude/metrics/cascade-events.csv | grep ",with_review_flow,"

View summary statistics:

cat .claude/metrics/cascade-summary.json | jq .

Sample Test Input

# Create test input with multiple cascade events
cat > test-logger-input.json << 'EOF'
{
  "tool": "mcp__task-orchestrator__manage_container",
  "tool_input": {
    "operation": "setStatus",
    "containerType": "task",
    "id": "task-uuid-123",
    "status": "completed"
  },
  "tool_output": {
    "success": true,
    "data": {
      "cascadeEvents": [
        {
          "event": "all_tasks_complete",
          "targetType": "feature",
          "targetId": "feature-uuid-456",
          "targetName": "API Authentication",
          "currentStatus": "in-development",
          "suggestedStatus": "testing",
          "flow": "default_flow",
          "automatic": true,
          "reason": "All 8 tasks completed successfully"
        },
        {
          "event": "all_features_complete",
          "targetType": "project",
          "targetId": "project-uuid-789",
          "targetName": "User Management System",
          "currentStatus": "in-progress",
          "suggestedStatus": "completed",
          "flow": "with_review_flow",
          "automatic": false,
          "reason": "All features complete, requires final approval"
        }
      ]
    }
  }
}
EOF

# Test the hook
cat test-logger-input.json | .claude/hooks/cascade-logger.sh

Customization

This hook is safe as-is, but you can customize:

Change CSV location:

# Line 28 - change log directory
LOG_DIR="$CLAUDE_PROJECT_DIR/metrics"  # Instead of .claude/metrics

Add email alerts for manual confirmations:

# After line 73, add:
if [ "$AUTOMATIC" == "false" ]; then
  echo "Manual confirmation required for $TARGET_NAME" | \
    mail -s "Task Orchestrator: Manual Approval Needed" admin@example.com
fi

Export to external analytics:

# After line 116, add:
curl -X POST https://analytics.example.com/api/cascade-events \
  -H "Content-Type: application/json" \
  -d @"$SUMMARY_LOG"

Testing Your Hooks

Testing with Real Operations

  1. Create a test task and complete it:

    # Your hooks will trigger on real manage_container operations
# Watch for hook output in Claude Code

  2. Check logs:

    ls -la .claude/metrics/
cat .claude/metrics/cascade-events.csv
cat .claude/metrics/cascade-summary.json

Testing with Simulated Input

Create a test script to simulate cascade events:

#!/bin/bash
# test-cascade-hooks.sh - Simulate cascade events for testing

cat << 'EOF' | .claude/hooks/cascade-auto-progress.sh
{
  "tool": "mcp__task-orchestrator__manage_container",
  "tool_input": {
    "operation": "setStatus",
    "containerType": "task",
    "id": "test-task-123",
    "status": "completed"
  },
  "tool_output": {
    "success": true,
    "data": {
      "cascadeEvents": [
        {
          "event": "all_tasks_complete",
          "targetType": "feature",
          "targetId": "test-feature-456",
          "targetName": "Test Feature",
          "currentStatus": "in-development",
          "suggestedStatus": "testing",
          "flow": "default_flow",
          "automatic": true,
          "reason": "All tasks completed for testing"
        }
      ]
    }
  }
}
EOF

echo ""
echo "✓ Test completed. Check output above."

Debugging Hooks

Enable verbose output:

# Add to top of hook (after #!/bin/bash)
set -x  # Print each command

Check hook execution:

# Claude Code logs hook execution
# Look for "Running hook: .claude/hooks/..."

Test JSON parsing:

# Verify jq is working
echo '{"test": "value"}' | jq -r '.test'
# Should output: value

Combining Multiple Hooks

You can use multiple hooks together. They run in the order listed in settings.local.json:

{
  "hooks": {
    "postToolUse": [
      {
        "hook": ".claude/hooks/cascade-logger.sh",
        "tools": ["mcp__task-orchestrator__manage_container"],
        "comment": "Always log first (observation only)"
      },
      {
        "hook": ".claude/hooks/flow-aware-gate.sh",
        "tools": ["mcp__task-orchestrator__manage_container"],
        "comment": "Then run quality gates (may block)"
      },
      {
        "hook": ".claude/hooks/cascade-auto-progress.sh",
        "tools": ["mcp__task-orchestrator__manage_container"],
        "comment": "Finally handle cascade progression"
      }
    ]
  }
}

Recommended Order:

  1. Logger (observation only, always safe)
  2. Quality gates (may block if tests fail)
  3. Auto-progress (applies status changes)

Migration from Conservative to Opinionated

Starting Conservative

If you're new to cascade events, start with the logger:

{
  "hooks": {
    "postToolUse": [
      {
        "hook": ".claude/hooks/cascade-logger.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      }
    ]
  }
}

Goal: Understand cascade event patterns in your project.

When to progress: After 1-2 weeks, review .claude/metrics/cascade-summary.json. If auto_percentage > 80%, you're ready for opinionated approach.

Adopting Opinionated Approach

Add cascade-auto-progress.sh:

{
  "hooks": {
    "postToolUse": [
      {
        "hook": ".claude/hooks/cascade-logger.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      },
      {
        "hook": ".claude/hooks/cascade-auto-progress.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      }
    ]
  }
}

Goal: Automatic progression with full audit trail.

When to progress: Once comfortable with automatic behavior, consider flow-aware gates.

Adding Flow-Aware Gates

Enable adaptive quality gates:

{
  "hooks": {
    "postToolUse": [
      {
        "hook": ".claude/hooks/cascade-logger.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      },
      {
        "hook": ".claude/hooks/flow-aware-gate.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      },
      {
        "hook": ".claude/hooks/cascade-auto-progress.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      }
    ]
  }
}

Goal: Prototype features skip tests, security features enforce strict validation.

Requirement: Consistent feature tagging (prototype, security, etc.).

Troubleshooting

Hook Not Executing

Check registration:

cat .claude/settings.local.json
# Verify hook is listed under postToolUse

Check executable permission:

ls -la .claude/hooks/
# Should show -rwxr-xr-x (executable)

Check tool name:

{
  "tools": ["mcp__task-orchestrator__manage_container"]
  // Note: Double underscores, correct tool name
}

Cascade Events Not Appearing

Verify operation triggers cascade:

# Cascade events only occur on certain operations:
# - Completing a task (when all tasks in feature complete)
# - Starting first task in a feature
# - Completing all features in a project

Check feature/project has children:

# Feature must have tasks
# Project must have features
# Otherwise no cascade occurs

JSON Parsing Errors

Install jq if missing:

# Ubuntu/Debian
sudo apt-get install jq

# macOS
brew install jq

# Windows (via scoop)
scoop install jq

Test jq installation:

echo '{"test": "value"}' | jq -r '.test'
# Should output: value

Gradlew Not Found (flow-aware-gate.sh)

Verify project structure:

ls -la ./gradlew
# Should exist and be executable

Adjust path in hook:

# Line 76, 120, 146 - change to absolute path
cd "$CLAUDE_PROJECT_DIR"
./gradlew test

Best Practices

General Guidelines

  1. Start with logger - Always begin with cascade-logger.sh to learn patterns
  2. Test in isolation - Test each hook individually before combining
  3. Keep hooks simple - Each hook should do one thing well
  4. Exit cleanly - Always exit 0 unless blocking (exit 1 requires JSON)
  5. Log everything - Create audit trails for debugging

Security Considerations

  1. Review hook source - Always review hook code before installation
  2. Limit permissions - Hooks run with user permissions, no sudo required
  3. Validate input - Check for null/empty values from JSON
  4. Handle errors - Use || true for non-critical operations
  5. Don't store secrets - Never hardcode credentials in hooks

Performance Tips

  1. Use lightweight operations - Hooks add overhead to every operation
  2. Filter early - Exit early if operation doesn't match
  3. Batch operations - Update metrics once, not per event
  4. Avoid network calls - Local operations are faster
  5. Cache database queries - SQLite queries can be slow for large databases

Additional Resources

Hook Templates

See hook-templates.md for 16 copy-paste templates covering:

  • Templates 1-11: Core hook patterns (git, testing, metrics, notifications)
  • Templates 12-16: Cascade event integration (NEW in v2.0)

Documentation

  • SKILL.md - Complete hook builder skill with interactive interview
  • docs/hooks-guide.md - Comprehensive hook system documentation
  • WorkflowConfig.kt - Source code for cascade event system

Getting Help

  1. Use the Task Orchestrator Hooks Builder skill in Claude Code
  2. Read the interactive interview questions (handles 95% of use cases)
  3. Review these examples for working patterns
  4. Check docs/hooks-guide.md for advanced scenarios

Summary

Recommended Setup (Most projects):

{
  "hooks": {
    "postToolUse": [
      {
        "hook": ".claude/hooks/cascade-logger.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      },
      {
        "hook": ".claude/hooks/cascade-auto-progress.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      }
    ]
  }
}

Full Setup (With flow-aware quality gates):

{
  "hooks": {
    "postToolUse": [
      {
        "hook": ".claude/hooks/cascade-logger.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      },
      {
        "hook": ".claude/hooks/flow-aware-gate.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      },
      {
        "hook": ".claude/hooks/cascade-auto-progress.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      }
    ]
  }
}

Conservative Setup (Learning mode):

{
  "hooks": {
    "postToolUse": [
      {
        "hook": ".claude/hooks/cascade-logger.sh",
        "tools": ["mcp__task-orchestrator__manage_container"]
      }
    ]
  }
}

All examples follow the opinionated approach - auto-apply by default with clear guidance on when to use conservative alternatives. Start with the logger to learn, then adopt auto-progress when comfortable.

Reference in New Issue View Git Blame Copy Permalink