Initial commit
This commit is contained in:
Zhongwei Li
972
skills/task-orchestrator-hooks-builder/examples.md
Normal file
972
skills/task-orchestrator-hooks-builder/examples.md
Normal file
@@ -0,0 +1,972 @@
|
||||
# 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**:
|
||||
```bash
|
||||
# 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):
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```bash
|
||||
# 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`:**
|
||||
```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`):**
|
||||
```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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
if [ "$AUTOMATIC" == "true" ]; then
|
||||
```
|
||||
|
||||
To:
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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`:**
|
||||
```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
|
||||
|
||||
```bash
|
||||
# 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):
|
||||
```bash
|
||||
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):
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
"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
|
||||
|
||||
```bash
|
||||
# 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`:**
|
||||
```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`
|
||||
|
||||
```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`
|
||||
|
||||
```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:**
|
||||
```bash
|
||||
tail -10 .claude/metrics/cascade-events.csv
|
||||
```
|
||||
|
||||
**Count auto vs manual:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
tail -n +2 .claude/metrics/cascade-events.csv | grep ",with_review_flow,"
|
||||
```
|
||||
|
||||
**View summary statistics:**
|
||||
```bash
|
||||
cat .claude/metrics/cascade-summary.json | jq .
|
||||
```
|
||||
|
||||
### Sample Test Input
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# Line 28 - change log directory
|
||||
LOG_DIR="$CLAUDE_PROJECT_DIR/metrics" # Instead of .claude/metrics
|
||||
```
|
||||
|
||||
**Add email alerts for manual confirmations:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# Your hooks will trigger on real manage_container operations
|
||||
# Watch for hook output in Claude Code
|
||||
```
|
||||
|
||||
2. **Check logs:**
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
#!/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:**
|
||||
```bash
|
||||
# Add to top of hook (after #!/bin/bash)
|
||||
set -x # Print each command
|
||||
```
|
||||
|
||||
**Check hook execution:**
|
||||
```bash
|
||||
# Claude Code logs hook execution
|
||||
# Look for "Running hook: .claude/hooks/..."
|
||||
```
|
||||
|
||||
**Test JSON parsing:**
|
||||
```bash
|
||||
# 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`:
|
||||
|
||||
```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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```bash
|
||||
cat .claude/settings.local.json
|
||||
# Verify hook is listed under postToolUse
|
||||
```
|
||||
|
||||
**Check executable permission:**
|
||||
```bash
|
||||
ls -la .claude/hooks/
|
||||
# Should show -rwxr-xr-x (executable)
|
||||
```
|
||||
|
||||
**Check tool name:**
|
||||
```json
|
||||
{
|
||||
"tools": ["mcp__task-orchestrator__manage_container"]
|
||||
// Note: Double underscores, correct tool name
|
||||
}
|
||||
```
|
||||
|
||||
### Cascade Events Not Appearing
|
||||
|
||||
**Verify operation triggers cascade:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# Feature must have tasks
|
||||
# Project must have features
|
||||
# Otherwise no cascade occurs
|
||||
```
|
||||
|
||||
### JSON Parsing Errors
|
||||
|
||||
**Install jq if missing:**
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install jq
|
||||
|
||||
# macOS
|
||||
brew install jq
|
||||
|
||||
# Windows (via scoop)
|
||||
scoop install jq
|
||||
```
|
||||
|
||||
**Test jq installation:**
|
||||
```bash
|
||||
echo '{"test": "value"}' | jq -r '.test'
|
||||
# Should output: value
|
||||
```
|
||||
|
||||
### Gradlew Not Found (flow-aware-gate.sh)
|
||||
|
||||
**Verify project structure:**
|
||||
```bash
|
||||
ls -la ./gradlew
|
||||
# Should exist and be executable
|
||||
```
|
||||
|
||||
**Adjust path in hook:**
|
||||
```bash
|
||||
# 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):
|
||||
```json
|
||||
{
|
||||
"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):
|
||||
```json
|
||||
{
|
||||
"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):
|
||||
```json
|
||||
{
|
||||
"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
Block a user