sinapse-ai 1.0.0

package/squad-claude/tasks/audit-setup.md

@@ -0,0 +1,85 @@
+---
+task: audit-setup
+responsavel: "@cm-orchestrator"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Audit Setup
+
+## Objective
+
+Perform a comprehensive audit of a project's Claude Code setup across all 6 dimensions: configuration completeness, hooks maturity, MCP integration, context efficiency, agent topology, and CI/CD readiness. Produce a scored report with prioritized recommendations.
+
+## Inputs
+
+- Project root path
+- Current .claude/ directory contents (if any)
+- CLAUDE.md files at all levels
+- Active MCP server configurations
+- Existing hooks (if any)
+
+## Steps
+
+1. **Scan Configuration Layer** — Read .claude/settings.json, all CLAUDE.md files, and .claude/rules/ directory. Check for missing required fields, deprecated options, and permission gaps.
+2. **Assess Hooks Maturity** — Enumerate all configured hooks, check event coverage (PreToolUse, PostToolUse, Notification, Stop), identify missing automation opportunities.
+3. **Evaluate MCP Integration** — List all configured MCP servers, verify connectivity, check for unused tools, assess security configuration.
+4. **Measure Context Efficiency** — Calculate total token footprint of CLAUDE.md + rules + knowledge bases. Identify redundancy, staleness, and bloat.
+5. **Review Agent Topology** — Assess subagent configurations, team topology patterns, worktree usage, and delegation clarity.
+6. **Check CI/CD Readiness** — Verify if Claude Code is integrated into CI/CD pipelines, check for automated review hooks, and assess deployment patterns.
+7. **Score Each Dimension** — Rate each dimension 1-5 (1=absent, 2=basic, 3=functional, 4=optimized, 5=exemplary). Calculate overall health score.
+8. **Generate Recommendations** — Produce prioritized list of improvements ordered by impact/effort ratio.
+
+## Quality Gates
+
+- All 6 dimensions must be assessed (no skips)
+- Each recommendation must include estimated effort (hours) and expected impact
+- Score justifications must reference specific files or configurations
+- Report must be actionable, not just descriptive
+
+## Output Format
+
+```markdown
+# Claude Code Setup Audit Report
+
+## Summary
+- **Overall Score:** X/30 (sum of 6 dimensions)
+- **Health Level:** [Critical | Needs Work | Functional | Optimized | Exemplary]
+
+## Dimension Scores
+| Dimension | Score | Key Finding |
+|-----------|-------|-------------|
+| Configuration | X/5 | ... |
+| Hooks | X/5 | ... |
+| MCP Integration | X/5 | ... |
+| Context Efficiency | X/5 | ... |
+| Agent Topology | X/5 | ... |
+| CI/CD Readiness | X/5 | ... |
+
+## Prioritized Recommendations
+1. [HIGH IMPACT] ...
+2. [MEDIUM IMPACT] ...
+3. ...
+
+## Detailed Findings
+### Configuration
+...
+### Hooks
+...
+(etc.)
+```

package/squad-claude/tasks/automated-code-review-pipeline.md

@@ -0,0 +1,89 @@
+---
+task: automated-code-review-pipeline
+responsavel: "@hooks-architect"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Automated Code Review Pipeline
+
+## Objective
+
+Build an automated code review pipeline that uses Claude Code hooks, linting tools, and AI-powered analysis to review code changes before they are committed or pushed. Produce a pipeline that catches bugs, style violations, security issues, and architectural drift automatically.
+
+## Pre-Conditions
+
+- Project has linting and formatting tools configured (ESLint, Prettier, etc.)
+- Git repository initialized with branch protection awareness
+- Claude Code hooks system available
+- Code review criteria and standards documented
+- CI/CD pipeline accessible for integration (optional for full pipeline)
+
+## Steps
+
+1. **Define Review Stages** — Design the pipeline stages in order: Stage 1 (Pre-commit) — syntax and format checks; Stage 2 (Pre-push) — lint, type check, test; Stage 3 (PR) — AI-powered semantic review, security scan, architecture compliance.
+2. **Configure Pre-Commit Hooks** — Set up PostToolUse hooks that trigger after Bash(git commit): run linter on staged files, verify formatting compliance, check for debug statements (console.log, TODO), and validate import conventions.
+3. **Build Lint Gate** — Create a PreToolUse hook for Bash that detects git push commands and blocks them if: linting fails, type checking fails, or test suite has failures. Provide clear error messages indicating what to fix.
+4. **Design AI Review Prompt** — Create a structured prompt for AI-powered code review: include diff context, coding standards reference, common anti-patterns to check, security checklist, and output format (findings with severity, line numbers, and suggestions).
+5. **Implement Security Scanning** — Add checks for common security issues: hardcoded credentials (API keys, passwords in code), unsafe eval or exec calls, SQL injection patterns, XSS vulnerabilities in templates, and sensitive data in logs.
+6. **Add Architecture Compliance Check** — Create rules that validate architectural decisions: import boundaries (no frontend importing backend), layer violations (UI accessing database directly), dependency direction enforcement, and file placement rules.
+7. **Configure Feedback Format** — Design the review output format: severity levels (Critical/Warning/Info), file and line references, explanation of the issue, suggested fix with code example, and link to relevant coding standard.
+8. **Implement Self-Healing Loop** — For auto-fixable issues (formatting, import sorting, simple lint fixes), implement automatic correction: detect the issue, apply the fix, re-run validation, and report what was auto-fixed. Maximum 2 self-healing iterations.
+9. **Set Up Review Reporting** — Create a review summary that aggregates all findings: total issues by severity, files with most issues, recurring patterns, and trend analysis (is code quality improving or degrading over time).
+10. **Test the Pipeline** — Run the pipeline against: clean code (should pass), code with known issues (should catch all), large diffs (should complete in reasonable time), and edge cases (binary files, generated code, lock files).
+11. **Document and Onboard** — Write setup instructions, explain how to bypass the pipeline in emergencies (with justification requirement), how to add new review rules, and how to interpret review results.
+
+## Output
+
+```markdown
+# Automated Code Review Pipeline
+
+## Pipeline Stages
+| Stage | Trigger | Checks | Blocking? | Auto-Fix? |
+|-------|---------|--------|-----------|-----------|
+
+## Hook Configuration
+{JSON configuration for all review hooks}
+
+## Review Rules
+| Rule | Category | Severity | Auto-Fixable | Description |
+|------|----------|----------|-------------|-------------|
+
+## AI Review Prompt
+{complete prompt template for semantic review}
+
+## Self-Healing Config
+| Issue Type | Fix Strategy | Max Iterations |
+|-----------|-------------|----------------|
+
+## Setup Instructions
+1. {step-by-step setup}
+
+## Emergency Bypass
+- Command: {bypass command}
+- Requirement: {justification process}
+```
+
+## Quality Criteria
+
+- Pipeline must catch at least 90% of lint violations and formatting issues
+- Security scanning must detect hardcoded credentials with zero false negatives
+- Self-healing must successfully auto-fix formatting and import issues
+- Full pipeline execution must complete within 30 seconds for typical diffs
+- Review output must include actionable suggestions (not just "there is a problem")
+- Emergency bypass must be documented and require explicit justification

package/squad-claude/tasks/batch-processing-workflow.md

@@ -0,0 +1,93 @@
+---
+task: batch-processing-workflow
+responsavel: "@hooks-architect"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Batch Processing Workflow
+
+## Objective
+
+Design batch processing workflows that leverage Claude Code to process multiple files, data sets, or operations efficiently. Create patterns for parallel processing, progress tracking, error recovery, and result aggregation across large-scale automated tasks.
+
+## Pre-Conditions
+
+- Batch operation requirements defined (what to process, how many items)
+- Input data format and source documented
+- Output format and destination specified
+- Error tolerance level defined (fail-fast vs. best-effort)
+- Resource constraints identified (memory, API rate limits, context window)
+
+## Steps
+
+1. **Define Batch Scope** — Document the batch operation: input source (file system, API, database), item count estimate, processing logic per item, output destination, and success criteria. Classify as small (< 50 items), medium (50-500), or large (500+).
+2. **Design Item Processing Logic** — Define the processing pipeline for a single item: read input, validate format, transform/analyze, generate output, and write result. Identify which steps require AI processing and which are mechanical.
+3. **Implement Chunking Strategy** — Break the batch into manageable chunks based on constraints: context window limits (max items per prompt), API rate limits (requests per second), memory constraints, and optimal parallelism level. Define chunk size and overlap handling.
+4. **Build Progress Tracking** — Create a progress tracking system: log file recording processed items, pending items, failed items, and current position. Enable resume from last checkpoint after interruption. Include estimated time remaining based on throughput.
+5. **Design Error Recovery** — Implement error handling per item and per batch: per-item errors (log, skip, retry up to 3 times), per-chunk errors (retry chunk, reduce chunk size, escalate), per-batch errors (save progress, report, allow manual resume).
+6. **Create Parallel Execution Plan** — Identify independent operations that can run in parallel: file reads, API calls, transformations. Design the parallelism strategy: concurrent tool calls within a turn, sequential turns with batched operations, or subagent delegation.
+7. **Implement Result Aggregation** — Design how individual results are combined: append to output file, merge into summary document, update database, or generate aggregate statistics. Handle partial results (some items failed) gracefully.
+8. **Add Rate Limiting** — Implement rate limiting for external API calls: token bucket or sliding window algorithm, configurable limits per API, backoff strategy when limits are hit, and queue management for pending requests.
+9. **Build Validation Pipeline** — Create post-processing validation: verify output count matches input count (minus expected failures), spot-check random results for quality, verify output format compliance, and generate quality metrics.
+10. **Create Batch Report** — Generate a comprehensive batch execution report: total items, processed/failed/skipped counts, execution time, throughput metrics, error summary with categories, and sample outputs for quality review.
+
+## Output
+
+```markdown
+# Batch Processing Workflow: {Operation Name}
+
+## Batch Configuration
+| Parameter | Value |
+|-----------|-------|
+| Input source | {source} |
+| Item count | {count} |
+| Chunk size | {size} |
+| Parallelism | {level} |
+| Error tolerance | {fail-fast/best-effort} |
+
+## Processing Pipeline
+1. {step} — {tool/method} — {output}
+2. {step} — {tool/method} — {output}
+
+## Chunking Strategy
+- Chunk size: {items per chunk}
+- Total chunks: {count}
+- Overlap handling: {strategy}
+
+## Error Recovery
+| Error Type | Strategy | Max Retries | Fallback |
+|-----------|----------|-------------|----------|
+
+## Progress Tracking
+- Log file: {path}
+- Checkpoint frequency: {every N items}
+- Resume command: {command}
+
+## Execution Report Template
+{report template with placeholders}
+```
+
+## Quality Criteria
+
+- Batch must be resumable from any checkpoint after interruption
+- Error recovery must handle all three levels (item, chunk, batch)
+- Progress tracking must be accurate to within 1% of actual completion
+- Parallel execution must not exceed defined rate limits
+- Result aggregation must account for partial failures (no silent data loss)
+- Batch report must include quality metrics alongside completion metrics

package/squad-claude/tasks/brownfield-setup.md

@@ -0,0 +1,77 @@
+---
+task: brownfield-setup
+responsavel: "@project-integrator"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Brownfield Setup
+
+## Objective
+
+Perform a brownfield assessment of an existing project's Claude Code setup, identify the current maturity level, and create an upgrade plan to reach the target maturity level with minimal disruption.
+
+## Inputs
+
+- Project root path
+- Current .claude/ directory contents
+- Current CLAUDE.md files
+- Target maturity level (basic / standard / advanced / expert)
+- Constraints (files that must not be modified, team preferences)
+
+## Steps
+
+1. **Assess Current Maturity** — Score the existing setup using the Integration Maturity Model: Level 0 (no Claude Code), Level 1 (basic CLAUDE.md), Level 2 (rules + settings), Level 3 (hooks + MCP), Level 4 (full automation + CI/CD).
+2. **Identify Gaps** — Compare current level to target level. List every configuration, file, and integration missing to reach the target.
+3. **Check for Anti-Patterns** — Scan existing configuration for common mistakes: overly broad permissions, stale CLAUDE.md content, missing deny rules, hardcoded paths, etc.
+4. **Design Upgrade Path** — Create a step-by-step migration plan from current level to target. Each step must be independently valuable (no "all or nothing" migrations).
+5. **Estimate Effort** — For each step, estimate time and risk. Order steps by value/effort ratio for optimal adoption.
+6. **Execute First Step** — Implement the highest-value, lowest-risk step to demonstrate immediate improvement.
+7. **Generate Upgrade Plan** — Produce the complete upgrade plan with timeline, dependencies, and rollback instructions for each step.
+
+## Quality Gates
+
+- Current maturity must be accurately assessed (validated against actual files)
+- Upgrade path must be incremental (each step independently valuable)
+- Anti-patterns must be flagged with severity
+- First step must be successfully executed and validated
+
+## Output Format
+
+```markdown
+# Brownfield Assessment
+
+## Current Maturity: Level {X}
+## Target Maturity: Level {Y}
+
+## Gap Analysis
+| Gap | Priority | Effort | Risk |
+|-----|----------|--------|------|
+
+## Anti-Patterns Found
+| # | Pattern | Severity | Fix |
+|---|---------|----------|-----|
+
+## Upgrade Plan
+### Step 1 (DONE): {description}
+### Step 2: {description}
+...
+
+## Timeline
+{estimated timeline to reach target}
+```

package/squad-claude/tasks/chain-of-thought-optimization.md

@@ -0,0 +1,91 @@
+---
+task: chain-of-thought-optimization
+responsavel: "@skill-craftsman"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Chain-of-Thought Optimization
+
+## Objective
+
+Optimize chain-of-thought (CoT) prompting strategies for complex reasoning tasks. Analyze existing prompts, identify reasoning gaps, and restructure prompts to elicit step-by-step thinking that improves accuracy and reduces hallucination in multi-step problem solving.
+
+## Pre-Conditions
+
+- Target task or domain requiring multi-step reasoning identified
+- Baseline prompts (without CoT) available for comparison
+- Sample inputs covering easy, medium, and hard difficulty levels
+- Success criteria defined (accuracy, completeness, consistency)
+- Understanding of the reasoning chain expected for the task
+
+## Steps
+
+1. **Analyze the Reasoning Task** — Break down the target task into its logical reasoning steps. Identify where the model typically fails: missing steps, incorrect inferences, premature conclusions, or circular reasoning. Document the ideal reasoning chain.
+2. **Audit Existing Prompts** — Review current prompts for reasoning quality. Score each on: step granularity (are steps explicit?), logical flow (does each step follow from the previous?), verification points (does the model check its work?), and conclusion validity.
+3. **Select CoT Strategy** — Choose the appropriate CoT variant: zero-shot CoT ("Let's think step by step"), few-shot CoT (examples with reasoning), structured CoT (numbered steps with specific sub-tasks), or self-consistency CoT (multiple reasoning paths).
+4. **Design Reasoning Scaffolds** — Create explicit reasoning templates that guide the model through the required steps. Include placeholders for intermediate results, verification checkpoints, and decision points.
+5. **Add Verification Prompts** — Insert self-check instructions at critical points: "Before proceeding, verify that X is consistent with Y", "Check your calculation by working backwards", "List any assumptions you made in this step."
+6. **Implement Step Decomposition** — Break complex steps into atomic sub-steps. Each sub-step should produce a verifiable intermediate result. Use numbered lists with clear input/output for each step.
+7. **Test with Graduated Difficulty** — Run the optimized prompt against easy, medium, and hard test cases. Track accuracy at each difficulty level. Identify the point where reasoning breaks down.
+8. **Compare Against Baseline** — Measure improvement over non-CoT baseline: accuracy delta, reasoning completeness, consistency across runs, and hallucination rate. Document with specific examples.
+9. **Optimize Token Efficiency** — Balance reasoning quality with token cost. Identify which reasoning steps are essential vs. verbose. Test compressed versions that maintain accuracy while reducing token usage by 20-30%.
+10. **Document Patterns** — Extract reusable CoT patterns that can be applied to similar tasks. Create a pattern library with trigger conditions (when to use each pattern) and expected outcomes.
+
+## Output
+
+```markdown
+# Chain-of-Thought Optimization Report
+
+## Task Analysis
+- Task: {description}
+- Reasoning steps required: {count}
+- Key failure points: {list}
+
+## Strategy Selected
+- CoT variant: {variant}
+- Rationale: {why this variant}
+
+## Optimized Prompt
+{complete prompt with CoT scaffolding}
+
+## Results
+| Difficulty | Baseline Accuracy | CoT Accuracy | Delta |
+|-----------|------------------|-------------|-------|
+| Easy      | {%}              | {%}         | {+%}  |
+| Medium    | {%}              | {%}         | {+%}  |
+| Hard      | {%}              | {%}         | {+%}  |
+
+## Reusable Patterns
+| Pattern | Trigger | Template |
+|---------|---------|----------|
+
+## Token Impact
+- Baseline tokens: {count}
+- CoT tokens: {count}
+- Cost increase: {percentage}
+```
+
+## Quality Criteria
+
+- CoT prompt must improve accuracy by at least 15% over baseline on hard tasks
+- Every reasoning step must produce a verifiable intermediate output
+- Self-check instructions must catch at least 50% of reasoning errors in testing
+- Token overhead from CoT must not exceed 3x the baseline prompt length
+- At least 3 reusable patterns must be extracted and documented
+- Prompt must maintain accuracy across 5+ consecutive runs (consistency check)

package/squad-claude/tasks/ci-cd-setup.md

@@ -0,0 +1,56 @@
+---
+task: ci-cd-setup
+responsavel: "@project-integrator"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# CI/CD Setup
+
+## Objective
+
+Integrate Claude Code into CI/CD pipelines for automated code review, generation, and validation. Configure GitHub Actions, GitLab CI, or other CI systems to leverage Claude Code in the development workflow.
+
+## Inputs
+
+- CI/CD platform (GitHub Actions, GitLab CI, Jenkins, CircleCI)
+- Pipeline triggers (PR, push, schedule)
+- Claude Code tasks to automate (code review, test generation, documentation)
+- API key management strategy
+- Cost constraints (API usage limits)
+
+## Steps
+
+1. **Assess Pipeline Requirements** — Determine which Claude Code operations should run in CI/CD: PR review, commit message validation, test generation, documentation updates, code quality checks.
+2. **Design Pipeline Stage** — Create a dedicated Claude Code stage in the CI/CD pipeline. Position it after build/test but before deploy. Define when it runs (all PRs? only specific paths?).
+3. **Configure Authentication** — Set up API key management using CI/CD secrets. Ensure keys are scoped appropriately and rotated regularly. Never hardcode keys.
+4. **Create Pipeline Configuration** — Write the CI/CD configuration file (workflow YAML, Jenkinsfile, etc.) with Claude Code invocation commands, timeout settings, and failure handling.
+5. **Implement Cost Controls** — Add guards: max token limits per run, path-based filtering (only run on changed files), caching of previous results, scheduling limits.
+6. **Add Reporting** — Configure pipeline to output Claude Code results as PR comments, check annotations, or pipeline artifacts.
+7. **Test Pipeline** — Run the pipeline on a test PR to verify: correct trigger, successful authentication, accurate results, proper reporting, and acceptable cost.
+
+## Quality Gates
+
+- API keys must be stored as CI/CD secrets (never in code)
+- Pipeline must have timeout configured (prevent runaway costs)
+- Cost controls must be implemented and tested
+- Pipeline failure must not block deployment (unless configured as required check)
+
+## Output Format
+
+Complete CI/CD configuration file plus documentation of the pipeline design, cost controls, and maintenance procedures.

package/squad-claude/tasks/claude-code-hooks-setup.md

@@ -0,0 +1,85 @@
+---
+task: claude-code-hooks-setup
+responsavel: "@hooks-architect"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Claude Code Hooks Setup
+
+## Objective
+
+Set up a comprehensive Claude Code hooks system for a project, implementing automation hooks across all available event types (PreToolUse, PostToolUse, Notification, Stop, SubagentStop). Produce a fully configured hooks setup with testing and documentation.
+
+## Pre-Conditions
+
+- Claude Code installed and project initialized
+- Automation goals documented (what should be automated)
+- Understanding of project workflow (which tools are used, when)
+- Shell scripting capability available (bash/zsh)
+- Performance budget defined (max hook execution time)
+
+## Steps
+
+1. **Audit Automation Opportunities** — Review the project workflow and identify automation candidates: pre-commit validation, file generation after scaffold, notification on long operations, security scanning before file writes, format enforcement, and dependency checking.
+2. **Map Goals to Hook Events** — For each automation goal, select the appropriate hook event: PreToolUse for gates and validation (block unsafe operations), PostToolUse for reactions (trigger after tool completes), Notification for alerts, Stop for session cleanup, SubagentStop for agent lifecycle management.
+3. **Design Hook Scripts** — For each hook, write the shell script that will execute. Each script must: read the JSON payload from stdin, extract relevant fields (session_id, tool_name, tool_input), perform its action, and exit with appropriate code (0=allow, non-zero=block for PreToolUse).
+4. **Configure Matchers** — Define precise matcher patterns to prevent false triggers. Use tool name matchers for tool-specific hooks, file glob matchers for path-specific hooks, and content pattern matchers for context-specific hooks. Test matchers against sample payloads.
+5. **Set Performance Budgets** — Configure timeouts for each hook: PreToolUse hooks must complete in < 500ms (they block the tool), PostToolUse hooks should complete in < 2s, Notification hooks can be longer but should use async patterns for > 5s operations.
+6. **Implement Error Handling** — Configure on_error behavior for each hook: "block" for security-critical PreToolUse hooks, "warn" for advisory PostToolUse hooks, "ignore" for non-critical notifications. Ensure hook failures never crash the Claude Code session.
+7. **Create the Configuration** — Write the complete hooks configuration in .claude/settings.json (project-level) or ~/.claude/settings.json (user-level). Organize hooks by event type, add comments explaining each hook's purpose.
+8. **Build Test Harness** — Create a test script that simulates hook payloads: generate sample JSON payloads for each hook event, pipe them through the hook scripts, verify exit codes and output. Include tests for edge cases (malformed JSON, missing fields, timeout).
+9. **Test Integration** — Trigger each hook in a live Claude Code session: perform the action that should fire the hook, verify it executes correctly, check for false triggers on similar but non-matching actions, and measure actual latency.
+10. **Document the Setup** — Write documentation covering: what each hook does, when it fires, how to disable individual hooks, how to add new hooks, troubleshooting common issues, and the test harness usage.
+
+## Output
+
+```markdown
+# Claude Code Hooks Setup
+
+## Hooks Registry
+| Hook | Event | Matcher | Script | Timeout | On Error |
+|------|-------|---------|--------|---------|----------|
+
+## Configuration (.claude/settings.json)
+{complete JSON configuration}
+
+## Hook Scripts
+### {hook_name}.sh
+- Purpose: {description}
+- Trigger: {event + matcher}
+- Performance: {expected latency}
+
+## Test Harness
+- Location: {path to test script}
+- Usage: `{command to run tests}`
+- Coverage: {list of tested scenarios}
+
+## Troubleshooting
+| Issue | Cause | Fix |
+|-------|-------|-----|
+```
+
+## Quality Criteria
+
+- At least one hook must be configured for each event type used
+- All PreToolUse hooks must complete within 500ms in testing
+- Hook scripts must handle malformed JSON input without crashing
+- Test harness must cover happy path, edge cases, and error scenarios
+- Configuration must be valid JSON that Claude Code accepts without errors
+- Documentation must explain how to add, modify, and disable hooks