Comprehensive health check for hooks - detects import errors, runtime failures, performance issues, and provides auto-fix suggestions
Runs comprehensive health checks on all project hooks, detecting import errors, runtime failures, and performance issues. Use it to diagnose hook problems before deployments or when hooks behave unexpectedly.
/plugin marketplace add anton-abyzov/specweave/plugin install sw@specweaveCommand: /sw:check-hooks
Runs comprehensive health check on all hooks in the project. Detects import errors, runtime failures, performance issues, and provides auto-fix suggestions.
# Check all hooks
/sw:check-hooks
# Check and auto-fix issues
/sw:check-hooks --fix
# Check only critical hooks
/sw:check-hooks --critical
# Verbose output with details
/sw:check-hooks --verbose
# Check specific hook
/sw:check-hooks update-ac-status
# Generate markdown report
/sw:check-hooks --format markdown --output report.md
--fix - Automatically repair fixable issues (missing .js extensions, etc.)--critical - Check only critical hooks (post-task-completion, user-prompt-submit)--verbose - Show detailed error messages and stack traces--format <format> - Output format: console (default), markdown, json, junit--output <file> - Write report to file--timeout <ms> - Hook execution timeout (default: 5000ms)--fail-on-warnings - Exit with error code if warnings detectedThe --fix flag can automatically repair:
Missing .js Extensions
// Before:
import { ACStatusManager } from '../../../../src/core/increment/ac-status-manager';
// After:
import { ACStatusManager } from '../../../../src/core/increment/ac-status-manager.js';
Import Path Corrections (high confidence only)
Colorized output for terminal viewing:
š„ Hook Health Check
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
All hooks healthy (8/8 passed)
Hooks Checked:
ā
update-ac-status (42ms)
ā
auto-transition (38ms)
ā
sync-living-docs (156ms)
...
Summary:
Total Hooks: 8
ā
Passed: 8
ā±ļø Total Time: 625ms
Detailed report for documentation:
# š„ Hook Health Check Report
**Generated**: 2025-11-16 14:00:00
**Overall Health**: š¢ HEALTHY
## Summary
- **Total Hooks**: 8
- **Passed**: ā
8
- **Failed**: ā 0
Machine-readable format for CI/CD:
{
"timestamp": "2025-11-16T14:00:00Z",
"totalHooks": 8,
"passedHooks": 8,
"failedHooks": 0,
"overallHealth": "healthy"
}
For CI/CD test reporting:
<testsuite name="Hook Health Check" tests="8" failures="0">
<testcase name="update-ac-status" classname="specweave" time="0.042"/>
</testsuite>
0 - All hooks healthy1 - Hook failures detected2 - Critical hook failures (blocks workflow)npm run check:hooks
# .github/workflows/test.yml
- name: Check Hook Health
run: npm run check:hooks -- --format junit --output junit.xml
- name: Publish Test Results
uses: EnricoMi/publish-unit-test-result-action@v2
with:
files: junit.xml
#!/bin/bash
# .git/hooks/pre-commit
npm run check:hooks --critical
if [ $? -ne 0 ]; then
echo "ā Critical hooks failing - commit blocked"
exit 1
fi
Increase timeout: /sw:check-hooks --timeout 10000
Run with auto-fix: /sw:check-hooks --fix
Check hook file permissions: chmod +x plugins/*/hooks/*.sh
For a quick visual dashboard of hook health, run:
bash plugins/specweave/scripts/hook-health.sh
Or use specific views:
bash plugins/specweave/scripts/hook-health.sh --status # Quick status
bash plugins/specweave/scripts/hook-health.sh --metrics # Detailed metrics
bash plugins/specweave/scripts/hook-health.sh --reset # Reset circuit breakers
bash plugins/specweave/scripts/hook-health.sh --clean # Clean stale state
The hook system uses proper concurrency primitives:
Environment variables:
HOOK_MAX_CONCURRENT - Max concurrent hooks (default: 15)HOOK_TIMEOUT - Hook execution timeout in seconds (default: 5)HOOK_DEBUG - Enable debug logging (1 = enabled).specweave/increments/0037-project-specific-tasks/architecture/HOOK-HEALTH-CHECK-ARCHITECTURE.md.specweave/docs/public/guides/hook-development.mdplugins/specweave/hooks/lib/