Skip to content

SpecKit Features Index

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

Discovered Features

Git Workflow Note: develop is the main working branch. Feature branches are created from develop, and PRs are merged back to develop. Only releases merge to main.

rulez-ui (In Progress)

Status: In Progress (M1 Complete) Priority: P1 (User Experience) Description: Native desktop application for visualizing, editing, validating, and debugging CCH configurations Location: rulez_ui/ (Tauri + React implementation) PRD: docs/prds/rulez_ui_prd.md Plan: docs/plans/rulez_ui_plan.md PR: #72 (merged to develop) Branch: feature/phase2-governance-core

SDD Artifacts

  • Spec: .speckit/features/rulez-ui/spec.md
  • Tasks: .speckit/features/rulez-ui/tasks.md
  • Status: M1 Complete, M2-M8 Pending

User Stories (Phase 1 MVP)

  • US-RUI-01: YAML Editor with Syntax Highlighting
  • US-RUI-02: Real-time Schema Validation
  • US-RUI-03: Multi-file Configuration Management
  • US-RUI-04: Debug Simulation
  • US-RUI-05: Rule Tree Visualization
  • US-RUI-06: Theme Support

Milestone Progress

  • M1: Project Setup (Tauri + React + Bun scaffold) - Complete
  • M2: Monaco Editor
  • M3: Schema Validation
  • M4: File Operations
  • M5: Rule Tree View
  • M6: Debug Simulator
  • M7: Theming
  • M8: Playwright Tests

Technology Stack

  • Runtime: Bun (TypeScript/React operations)
  • Frontend: React 18 + TypeScript + Tailwind CSS 4
  • Editor: Monaco Editor + monaco-yaml
  • Desktop: Tauri 2.0 (Rust backend)
  • State: Zustand + TanStack Query
  • Testing: Bun test (unit) + Playwright (E2E)

Implementation Phases

Phase Description Est. Days
Phase 1 MVP (Editor, Validation, Files, Simulator, Tree, Theme) 9.5
Phase 2 Log Viewer 5-7
Phase 3 Advanced Features (templates, regex tester) 7-10
Phase 4 Distribution (installers, auto-update) 3-5

Platform Support

  • macOS (Intel + Apple Silicon)
  • Linux (x86_64 + ARM64)
  • Windows (x86_64)

phase2-governance (Complete)

Status: Complete Priority: P2 (Enterprise Readiness) Description: Policy governance layer with modes, metadata, priorities, and enhanced explainability Location: cch_cli/ (Rust implementation extension) PRD: docs/prds/phase2_prd.md PR: #72 (merged to develop) Branch: feature/phase2-governance-core Completion Date: 2026-01-25

SDD Artifacts

  • Spec: .speckit/features/phase2-governance/spec.md
  • Tasks: .speckit/features/phase2-governance/tasks.md
  • Plan: .speckit/features/phase2-governance/plan.md
  • Status: Complete (All phases implemented)

User Stories

  • US-GOV-01: Rule Metadata (Provenance)
  • US-GOV-02: Policy Modes (enforce | warn | audit)
  • US-GOV-03: Rule Priority
  • US-GOV-04: Policy Conflict Resolution
  • US-GOV-05: Enhanced cch explain rule Command
  • US-GOV-06: Enhanced Logging Schema
  • US-GOV-07: Validator Trust Levels (Informational)

Implementation Phases

Phase Description Est. Days Status
P2.1 Core Governance (modes, priority, metadata) 3-4 Complete
P2.2 Enhanced Logging 1-2 Complete
P2.3 CLI Enhancements 1-2 Complete
P2.4 Trust Levels 0.5-1 Complete

All phases complete. 68 tests pass.

Design Philosophy

  • Backward Compatible: All new features are optional
  • Auditable: Full provenance in logs and explain output
  • Gradual Rollout: audit mode for testing, warn for soft rules
  • Enterprise Ready: SOC2 evidence, governance dashboards

enhanced-logging (Completed)

Status: Completed Priority: P2 (Observability enhancement) Description: Enhanced logging with structured event details, response summaries, and debug mode Location: cch_cli/ (Rust implementation) Branch: 002-enhanced-logging

SDD Artifacts

  • Spec: .speckit/features/enhanced-logging/spec.md
  • Plan: .speckit/features/enhanced-logging/plan.md
  • Tasks: .speckit/features/enhanced-logging/tasks.md (backfilled)
  • Commit: b9faa44

User Stories Completed

  • ✅ Typed Event Details (Bash, Write, Edit, Read, Glob, Grep, Session)
  • ✅ Response Summary Logging (continue, reason, context_length)
  • ✅ Debug Mode Support (raw_event, rule_evaluations)
  • ✅ Backward Compatibility (Option fields with skip_serializing_if)
  • ✅ CLI & Environment Variable Configuration

Technical Implementation

  • EventDetails enum with 9 variants for different tool types
  • ResponseSummary struct for response metadata
  • RuleEvaluation tracking for debug mode
  • DebugConfig struct with CLI/env/config sources
  • Extended LogEntry with optional fields

mastering-hooks (Completed)

Status: Completed Priority: P3 (IDE integration) Description: Claude Code skill for CCH mastery - installation, configuration, debugging, and optimization Location: mastering-hooks/ (skill implementation)

User Stories Completed

  • ✅ Install & Initialize CCH (binary verification, config init, registration)
  • ✅ Create Hook Rules (event types, matchers, actions, validation)
  • ✅ Explain Configuration (rule analysis, precedence, conflicts)
  • ✅ Troubleshoot Hook Issues (diagnostics, common issues, log analysis)
  • ✅ Optimize Configuration (consolidation, performance tips)

Skill Structure

  • SKILL.md (226 lines) - Overview with TOC and decision tree
  • references/quick-reference.md - Events, matchers, actions tables
  • references/hooks-yaml-schema.md - Complete YAML configuration reference
  • references/cli-commands.md - All CLI commands with examples
  • references/rule-patterns.md - Common patterns and recipes
  • references/troubleshooting-guide.md - Diagnostic procedures
  • assets/ - Templates and example scripts

cch-binary-v1 (Feature Complete)

Status: Feature Complete (64 tests pass) Priority: P1 (Core functionality) Description: Claude Code Hook binary providing safety and productivity features Location: cch_cli/ (Rust implementation)

User Stories Completed

  • ✅ Block Dangerous Operations (git push --force blocking) - 4 tests
  • ✅ Inject Context for Skill Triggers (directory-based context injection) - 3 tests
  • ✅ Run Custom Validators (Python script execution) - 3 tests
  • ✅ Explain Commands Before Permission (structured command explanations) - 3 tests
  • ✅ Query Logs for Troubleshooting (log querying and rule explanation) - 6 tests
  • ✅ Installation Quality - 7 tests
  • ✅ Performance Requirements - 5 tests

CLI Commands (All Implemented)

  • ✅ cch init - Create default hooks.yaml with examples - 4 tests
  • ✅ cch install - Register CCH with Claude Code settings - 2 tests
  • ✅ cch uninstall - Remove CCH from Claude Code settings - 1 test
  • ✅ cch debug - Simulate events to test rules - 5 tests
  • ✅ cch repl - Interactive debug mode - 1 test
  • ✅ cch validate - Validate configuration file
  • ✅ cch logs - Query and display logs
  • ✅ cch explain - Explain why rules fired

CI/CD (Complete)

  • ✅ CI workflow (.github/workflows/ci.yml) - fmt, clippy, tests, coverage, cross-platform builds
  • ✅ Release workflow (.github/workflows/release.yml) - triggered by v* tags
  • ✅ Cross-platform builds: Linux (x86_64, aarch64), macOS (x86_64, aarch64), Windows (x86_64)

Ready for Release

To create a release:

git tag v1.0.0
git push origin v1.0.0

Technical Implementation

  • Rust 2024 binary with tokio async runtime
  • JSON Lines logging for audit trail
  • YAML configuration-driven behavior
  • Sub-10ms performance verified (<3ms actual)
  • Zero unsafe code blocks

Dependencies

  • serde (JSON/YAML processing)
  • clap (CLI parsing)
  • regex (pattern matching)
  • tokio (async operations)
  • tracing (structured logging)

Project Architecture

Technology Stack

  • Language: Rust 2024 edition
  • Runtime: tokio (current_thread flavor)
  • Configuration: YAML files
  • Logging: JSON Lines format
  • Build: Cargo workspace

Module Structure

  • models/: Core data types (Event, Rule, Response, LogEntry)
  • config/: YAML configuration loading and validation
  • hooks/: Rule matching and action execution
  • logging/: JSON Lines logging infrastructure
  • cli/: Command-line interface (init, install, debug, validate, logs, explain)

Claude Code JSON Protocol

CCH communicates with Claude Code via stdin/stdout JSON. Key field mappings:

  • Event field: Claude Code sends hook_event_name (CCH accepts both hook_event_name and event_type via serde alias)
  • Response field: CCH serializes continue (not continue_) via #[serde(rename = "continue")]
  • Timestamp: Claude Code may not send timestamp; CCH defaults to Utc::now()
  • Event types: PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, PostToolUseFailure, SubagentStart, SubagentStop, Notification, Setup, PermissionRequest, UserPromptSubmit, PreCompact

Key Patterns

  • Async-first design for performance
  • Configuration-driven behavior (no hardcoded rules)
  • Comprehensive error handling with anyhow
  • Structured logging with tracing
  • Cross-platform compatibility

Reverse Engineering Summary

Source Analysis: specs/001-cch-binary-v1/ directory

  • Found detailed specification document with 5 user stories
  • Identified implementation plan and task breakdown
  • Located JSON schema contracts for data validation
  • Discovered comprehensive test fixtures and examples

Codebase Analysis: cch_cli/ directory

  • Rust workspace with single binary crate
  • Well-structured module organization
  • Performance-optimized dependencies
  • Comprehensive test coverage with fixtures

Feature Maturity: High

  • All user stories implemented and tested
  • Performance requirements met (<10ms processing)
  • Production-ready error handling and logging
  • Cross-platform compatibility verified

Integration Points:

  • Claude Code hook system integration
  • YAML configuration file loading
  • External script execution (Python validators)
  • JSON Lines log file management
  • Directory-based context file injection

cch-advanced-rules (Backlog)

Status: Backlog Priority: P3 (Future Enhancement) Description: Advanced rule features removed from skill docs during schema fix — never implemented in CCH binary Location: cch_cli/ (future Rust implementation) Completion: 0% - Spec only

SDD Artifacts

  • Spec: .speckit/features/cch-advanced-rules/spec.md

User Stories (Backlog)

  • US-ADV-01 (P2): enabled_when conditional matcher
  • US-ADV-02 (P3): prompt_match regex matcher
  • US-ADV-03 (P3): require_fields action type
  • US-ADV-04 (P2): Inline content injection (inject_inline)
  • US-ADV-05 (P2): Command-based context generation (inject_command)
  • US-ADV-06 (P3): Inline script blocks in run:
  • US-ADV-07 (P3): Context variables for expressions

Clone this wiki locally