Skip to content

Feature Mastering Hooks Spec

Jump to bottom
Rick Hightower edited this page Jan 28, 2026 · 1 revision

Feature Specification: CCH Skill v1

Feature Branch: feature/cch-skill-v1 Created: 2025-01-21 Status: In Progress Input: PRD documents from docs/prds/

User Scenarios & Testing (mandatory)

User Story 1 - Install CCH Binary (Priority: P1)

As a developer, I want to say "Install CCH" and have the skill automatically download and install the correct binary for my platform.

Why this priority: Without the binary, nothing else works. Installation must be seamless.

Independent Test: Can be fully tested by running the skill on a machine without CCH and verifying the binary is installed and working.

Acceptance Scenarios:

  1. Given CCH binary is not installed, When user says "Install CCH", Then skill detects OS/arch, downloads correct artifact, verifies checksum, and installs to .claude/bin/cch
  2. Given CCH binary is installed, When user says "Install CCH", Then skill reports current version and offers to update if newer available
  3. Given installation completes, When running cch --version --json, Then output shows valid version and api_version
  4. Given download fails, When checksum doesn't match, Then skill reports error and does not install

User Story 2 - Set Up Hooks for Project (Priority: P1)

As a developer, I want to say "Set up hooks for this project" and have the skill analyze my codebase and generate appropriate rules.

Why this priority: Zero-config setup is the key value proposition that differentiates CCH Skill from manual configuration.

Independent Test: Can be tested by running the skill on a project with skills and CLAUDE.md, verifying hooks.yaml is generated with sensible rules.

Acceptance Scenarios:

  1. Given a project with .claude/skills/ containing skill definitions, When user requests setup, Then skill generates PreToolUse trigger rules for each skill
  2. Given CLAUDE.md contains "MUST NOT use console.log", When user requests setup, Then skill generates a validator script and rule to enforce it
  3. Given analysis complete, When presenting to user, Then skill shows each recommended rule with explanation of WHY it's recommended
  4. Given user approves, When installing, Then skill creates hooks.yaml, context files, validators, runs cch validate, and runs cch install --project

User Story 3 - Add Single Rule (Priority: P2)

As a developer, I want to say "Create a hook to trigger the CDK skill when editing infra files" and have the skill add just that rule.

Why this priority: Incremental configuration is essential for users who want fine-grained control.

Independent Test: Can be tested by requesting a single rule addition and verifying hooks.yaml is updated correctly.

Acceptance Scenarios:

  1. Given user describes a rule, When skill parses request, Then it identifies skill, target files, and action type
  2. Given skill exists at .claude/skills/aws-cdk/SKILL.md, When creating trigger rule, Then skill extracts relevant extensions/directories from SKILL.md
  3. Given existing hooks.yaml, When adding rule, Then skill merges new rule without breaking existing configuration
  4. Given rule added, When user approves, Then skill runs cch validate and cch install --project

User Story 4 - Troubleshoot Hook Issues (Priority: P2)

As a developer, I want to ask "Why isn't my hook blocking WIP commits?" and get a clear explanation with suggested fixes.

Why this priority: Users will inevitably have configuration issues; good troubleshooting builds trust.

Independent Test: Can be tested by creating a misconfigured rule and asking the skill to debug it.

Acceptance Scenarios:

  1. Given user reports hook not working, When skill investigates, Then it reads hooks.yaml, finds relevant rule, and queries logs
  2. Given logs show event, When rule didn't match, Then skill explains which matcher failed and why
  3. Given rule matched but didn't block, When mode is "audit", Then skill explains the mode and suggests changing to "enforce"
  4. Given analysis complete, When presenting to user, Then skill shows relevant log entry and suggests specific fix

User Story 5 - Explain Rule Provenance (Priority: P3)

As a developer, I want to ask "Why does this rule exist?" and understand where it came from and its purpose.

Why this priority: Enterprise governance requires auditability of all policy decisions.

Independent Test: Can be tested by querying provenance of rules generated by the skill.

Acceptance Scenarios:

  1. Given rule has metadata.author, When user asks about rule, Then skill shows who created it
  2. Given rule came from CLAUDE.md, When explaining, Then skill shows the original text and line number
  3. Given rule is a safety default, When explaining, Then skill explains it's a recommended standard protection
  4. Given rule has confidence level, When explaining, Then skill shows confidence and explains implications

Edge Cases

  • What if project has no skills? → Generate only safety defaults and CLAUDE.md rules
  • What if CLAUDE.md is missing? → Continue with skill triggers and safety defaults
  • What if CCH binary is incompatible version? → Warn user and offer to upgrade
  • What if rules conflict? → Detect and present conflicts to user for resolution
  • What if user rejects all recommendations? → Allow cancel without changes

Requirements (mandatory)

Functional Requirements

  • FR-001: Skill MUST detect OS (macOS, Linux, Windows) and architecture (x86_64, ARM64)
  • FR-002: Skill MUST download CCH binary from official GitHub releases
  • FR-003: Skill MUST verify binary checksum before installation
  • FR-004: Skill MUST discover all SKILL.md files in .claude/skills/ recursively
  • FR-005: Skill MUST parse CLAUDE.md and extract MUST/MUST NOT/SHOULD rules
  • FR-006: Skill MUST classify rules by confidence: high (enforceable), medium (ambiguous), low (vague)
  • FR-007: Skill MUST generate hooks.yaml with provenance comments
  • FR-008: Skill MUST generate validator scripts for complex rules
  • FR-009: Skill MUST detect rule conflicts and present for resolution
  • FR-010: Skill MUST maintain audit trail in .claude/cch/install.json

Key Entities

  • DiscoveredSkill: Name, path, description, applicable extensions/directories
  • ExtractedRule: Original text, classification (hard/soft), confidence, scope
  • Recommendation: Rule to generate, explanation of why, confidence level
  • Conflict: Two rules with overlapping scope and incompatible actions
  • AuditRecord: Installation history with timestamps, versions, sources analyzed

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: Installation succeeds on macOS (Intel + Apple Silicon), Linux (x86_64 + ARM64), Windows (x86_64)
  • SC-002: Project analysis completes in <10 seconds for typical projects
  • SC-003: Generated hooks.yaml passes cch validate in 100% of cases
  • SC-004: All generated rules include provenance comments
  • SC-005: User understands each recommendation (measured by approval rate >80%)

Clone this wiki locally