Analyze Hooks Implementation
System Prompt
⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:
- IMMEDIATELY execute - no questions, no explanations first
- ALWAYS show full output from script/tool execution
- ALWAYS provide summary after execution completes
DO NOT:
- Say "I don't need to take action" - you ALWAYS execute when invoked
- Ask for confirmation unless
requires_confirmation: truein frontmatter - Skip execution even if it seems redundant - run it anyway
The user invoking the command IS the confirmation.
Usage
/analyze-hooks [path]
Analyze hooks implementation for: $ARGUMENTS
This command analyzes CODITECT's readiness for Claude Code hooks implementation, evaluates current processes that could be automated with hooks, identifies security requirements, and recommends optimal hook strategies for different scenarios.
Arguments
$ARGUMENTS - Analysis Scope (optional)
Specify what to analyze:
- Full analysis: "Analyze all hook opportunities" or no arguments
- Specific area: "Analyze hooks for component validation"
- Security focus: "Analyze hooks security requirements"
- ROI analysis: "Analyze hooks ROI and implementation priority"
Default Behavior
If no arguments:
- Assesses current hook candidates across all CODITECT processes
- Evaluates security and performance requirements
- Recommends implementation phases with priorities
- Provides ROI analysis
Steps to follow:
Step 1: Assess Current Hook Candidates
Analyze existing CODITECT processes to identify which could be automated with hooks.
Action: Research and document existing processes that would benefit from automation.
Use codebase-analyzer subagent to:
1. Identify all manual validation steps in component creation
2. Find all post-operation cleanup or verification tasks
3. Locate pre-execution checks that could be automated
4. Document timing of each process (how long before issue found)
5. Estimate token savings if automated
Look for:
- ✅ Standards compliance validation (currently manual review)
- ✅ Git pre-commit checks (currently manual or absent)
- ✅ Documentation synchronization (currently manual)
- ✅ Quality gates (currently manual)
- ✅ Prompt preprocessing (manual context addition)
Success Criteria:
- Identified 10+ processes that could use hooks
- Documented current validation timing
- Estimated token savings for each
- Prioritized by impact and complexity
Step 2: Security & Permission Requirements Analysis
Analyze what permissions and security controls hooks need.
Action: Review hook security considerations and CODITECT needs.
Use security-specialist subagent to:
1. Map hook access requirements (file read/write/execute)
2. Identify sensitive paths that must be protected (.env, .git, secrets)
3. Design input validation requirements
4. Document permission boundaries per hook
5. Create security checklist for hook development
Consider:
- ✅ Which hooks need blocking capability (PreToolUse)?
- ✅ Which hooks should run async (PostToolUse)?
- ✅ What environment variables are needed?
- ✅ How to handle sensitive operations safely?
- ✅ Audit trail and logging requirements?
Success Criteria:
- Security analysis complete for 5 critical hooks
- Input validation requirements documented
- Sensitive file protection strategy defined
- Permission scope documented for each hook
- Security checklist created
Step 3: Hook Configuration & Usage Pattern Analysis
Analyze how hooks should be configured and used in CODITECT context.
Action: Document hook configuration patterns for CODITECT.
Use codebase-pattern-finder subagent to:
1. Research existing Claude Code hook implementations
2. Identify best practices from community examples
3. Document configuration patterns (JSON structure)
4. Find examples of blocking vs non-blocking hooks
5. Document error handling patterns for different scenarios
Patterns to identify:
- ✅ How to structure
.claude/settings.json - ✅ Matcher patterns for common tools (Write, Edit, Bash)
- ✅ How to handle stdin/stdout with tools
- ✅ Error response format (JSON with continue/stopReason)
- ✅ Timeout and async execution patterns
Success Criteria:
- 5+ working hook implementations documented
- JSON configuration examples for each
- Stdin/stdout handling documented
- Error response patterns clarified
- Best practices summarized
Step 4: CODITECT-Specific Hook Strategy Design
Design hooks specifically for CODITECT's needs and architecture.
Action: Create CODITECT hooks strategy document.
Use orchestrator subagent to coordinate:
1. software-design-document-specialist: Document hook architecture
2. security-specialist: Security requirements for each hook
3. codebase-analyzer: Current process analysis
4. research-agent: Best practices and patterns
Combined output: HOOKS-IMPLEMENTATION-STRATEGY.md with:
- Hook priority matrix (impact vs complexity)
- Phase-based rollout plan
- Security requirements per hook
- Success metrics and measurement approach
Design considerations:
- ✅ Which hooks prevent problems (highest impact)?
- ✅ Which hooks improve user experience?
- ✅ Which hooks reduce token consumption?
- ✅ Deployment sequence (phase 1, 2, 3)?
- ✅ Metrics to measure success?
Success Criteria:
- Strategy document complete
- Priority matrix created
- Phased rollout plan defined
- Security requirements mapped
- Success metrics identified
Step 5: Implementation Readiness Assessment
Assess CODITECT's readiness to implement hooks.
Action: Create readiness report and blockers list.
Evaluate:
1. Directory structure for hooks/ (does it exist?)
2. Configuration file structure (is settings.json ready?)
3. Script infrastructure (can we run bash scripts?)
4. Testing framework (can we validate hooks work?)
5. Documentation (is hooks info accessible?)
6. Team knowledge (do developers understand hooks?)
Checklist:
-
.coditect/hooks/directory exists -
.claude/settings.jsonstructure defined - Hook script templates created
- Test framework for hooks established
- Documentation complete and accessible
- Team trained on hook patterns
- Security checklist reviewed
- Configuration examples provided
Success Criteria:
- Readiness report complete
- All blockers identified
- Mitigation plan created for each blocker
- Timeline estimate provided
- Resource requirements documented
Important notes:
-
Comprehensive analysis: Analyze not just tools but entire workflow. Hooks can enhance prompts, validate components, enforce standards, and optimize token usage.
-
Security first: Every hook must validate inputs, use absolute paths, skip sensitive files, and implement proper error handling. Security analysis is NOT optional.
-
Phased approach: Don't try to implement all hooks at once. Phase 1 should be quick wins (component validation), Phase 2 should be quality improvements (git checks), Phase 3+ should be advanced features.
-
Measurement matters: Define success metrics upfront. How will we measure if hooks are working? (Reduction in non-standard components, token savings, development speed, etc.)
-
Documentation critical: Hooks require clear documentation of what they do, why they're needed, how to configure them, and troubleshooting steps. Under-documented hooks become abandoned.
-
Testing essential: Hook behavior can be subtle (they run async, have 60s timeouts, stream JSON). Create test cases before deploying.
-
Community patterns: Research how other teams use hooks. Learn from existing implementations, especially in open-source Claude Code projects.
-
Integration with existing processes: Hooks shouldn't replace existing workflows, they should enhance them. Plan how hooks integrate with current standards, reviews, and quality gates.
-
Performance awareness: Hooks add latency. PreToolUse hooks delay operations. Monitor and optimize. Aim for <5s typical execution.
Required Tools
| Tool | Purpose | Required |
|---|---|---|
Read | Analyze existing hooks and configurations | Yes |
Grep | Search for hook patterns in codebase | Yes |
Glob | Find hook files and settings | Yes |
Task | Spawn specialist agents for analysis | Yes |
Bash | Test hook execution and timing | Optional |
Subagents Used:
codebase-analyzer- Identify manual processessecurity-specialist- Security requirementscodebase-pattern-finder- Hook patternsorchestrator- Strategy coordination
Output Validation
Before marking complete, verify output contains:
- At least 5 hook candidate processes identified
- Security analysis for critical hooks
- Configuration patterns with JSON examples
- Readiness checklist (8 items)
- Implementation roadmap with phases
- ROI estimate for top candidates
Action Policy
<default_behavior> This command analyzes and recommends without making changes. Provides:
- Comprehensive CODITECT hooks readiness assessment
- Automatable process identification with ROI estimates
- Specific hook integration strategies by category
- Implementation roadmap with priority levels
- Risk analysis and mitigation strategies
User decides which hooks recommendations to implement. </default_behavior>
Success Output
When hooks analysis completes:
✅ COMMAND COMPLETE: /analyze-hooks
Hook Candidates: N identified
Security Analysis: X critical areas reviewed
Readiness: Y% ready
Implementation Phases: Z defined
ROI Estimate: <value>
Completion Checklist
Before marking complete:
- All hook categories assessed
- Security requirements analyzed
- Configuration patterns documented
- Readiness assessment complete
- Implementation roadmap created
Failure Indicators
This command has FAILED if:
- ❌ No hook candidates identified
- ❌ Security analysis skipped
- ❌ No readiness assessment
- ❌ Missing implementation phases
When NOT to Use
Do NOT use when:
- No Claude Code hooks available
- Just need to create one hook
- Understanding existing hooks only
Anti-Patterns (Avoid)
| Anti-Pattern | Problem | Solution |
|---|---|---|
| Skip security analysis | Vulnerable hooks | Always analyze security |
| No phasing | Overwhelming scope | Implement in phases |
| No metrics | Can't measure success | Define success metrics |
Principles
This command embodies:
- #3 Complete Execution - All 5 steps
- #9 Based on Facts - ROI-based priorities
- #4 Separation of Concerns - Phased approach
Full Standard: CODITECT-STANDARD-AUTOMATION.md