CLAUDE.md - AI Assistant Context for ICR Plugin

This file provides context for Claude (or other AI assistants) when working with this codebase.

Acknowledgement

This project is inspired by the YouTube video "The AI Failure Mode Nobody Warned You About (And how to prevent it from happening)". The video brilliantly articulates the "intent problem" in AI agents - the gap between what users mean and what AI interprets - which this plugin aims to solve.

Project Overview

ICR (Intent-Check-Receipt) is a Claude Code plugin that implements a safety layer for AI agent operations. It addresses the "intent problem" - the gap between what users mean and what AI interprets.

The Three Phases

Intent: Before executing an action, generate a structured document showing what the AI believes the user wants
Check: Pause for verification (human and/or AI reviewer) based on action severity and confidence
Receipt: Log the full audit trail including interpretation, approval, and outcome

Repository Structure

icr/
├── .claude-plugin/
│   └── plugin.json              # Plugin manifest - defines hooks, commands, skills
│
├── commands/                     # Slash commands (user-invocable)
│   ├── receipts.md              # /icr:receipts - View receipt history
│   ├── config.md                # /icr:config - View/edit configuration
│   ├── check.md                 # /icr:check - Manual check trigger
│   ├── trust.md                 # /icr:trust - Trust mode toggle
│   ├── audit.md                 # /icr:audit - Deep receipt analysis
│   ├── export.md                # /icr:export - Export receipts
│   ├── stats.md                 # /icr:stats - Session statistics
│   ├── debug.md                 # /icr:debug - Confidence debugging
│   └── simulate.md              # /icr:simulate - Dry-run intent check
│
├── skills/
│   └── intent-analysis/
│       └── SKILL.md             # AI-invocable intent analysis skill
│
├── hooks/
│   └── hooks.json               # Hook event configuration
│
├── scripts/                      # Bash scripts (hook implementations)
│   ├── pre-tool-check.sh        # Main PreToolUse hook handler
│   ├── permission-check.sh      # PermissionRequest hook
│   ├── subagent-check.sh        # SubagentStop hook
│   ├── statusline.sh            # Status line display
│   └── lib/                     # Core library scripts
│       ├── common.sh            # Shared utilities (logging, JSON helpers)
│       ├── severity.sh          # Severity classification (LOW/MEDIUM/HIGH/CRITICAL)
│       ├── confidence.sh        # Confidence scoring (0.0-1.0)
│       ├── decision.sh          # Decision tree (AUTO_APPROVE/AI_REVIEW/HUMAN_REVIEW)
│       ├── intent.sh            # Intent document generation
│       ├── receipt.sh           # Receipt logging and rotation
│       └── checkpoint.sh        # Checkpoint management for rollback
│
├── config/
│   └── defaults.json            # Default configuration (Conservative preset)
│
├── schemas/                      # JSON Schema validation
│   ├── config.json              # Configuration schema
│   ├── receipt.json             # Receipt format schema
│   └── intent-doc.json          # Intent document schema
│
├── prompts/                      # LLM prompt templates
│   ├── intent-generation.md     # Template for generating intent documents
│   ├── self-critique.md         # AI self-review template
│   └── devils-advocate.md       # Adversarial safety review template
│
├── docs/                         # Documentation
│   ├── ICR_PLUGIN_SPEC.md       # Full specification (4700+ lines)
│   ├── SUMMARY.md               # Original intent problem research
│   ├── QUICK_START.md           # Quick start with 10 use cases
│   ├── USER_GUIDE.md            # Comprehensive user documentation
│   ├── DEVELOPER_GUIDE.md       # Comprehensive developer documentation
│   ├── ARCHITECTURE.md          # System architecture overview
│   ├── CONTRIBUTING.md          # Contribution guidelines
│   └── TROUBLESHOOTING.md       # Common issues and solutions
│
├── README.md                     # Project overview and quick reference
├── CHANGELOG.md                  # Version history
├── LICENSE                       # MIT License
└── CLAUDE.md                     # This file

Key Technologies

Technology	Purpose	Documentation
Bash	All scripts are written in Bash	Scripts use `set -euo pipefail` for safety
jq	JSON processing in shell scripts	Used for parsing/generating JSON
JSON	Configuration, receipts, schemas	Standard JSON format throughout
JSON Schema	Validation	Draft-07 JSON Schema
Markdown	Commands, skills, prompts	Frontmatter YAML + Markdown content

Common Development Tasks

Adding a New Slash Command

Create commands/<name>.md with frontmatter:

---
description: Brief description for help text
user_invocable: true
---

# Command Name

[Command documentation...]

Add command to plugin.json:

{
  "commands": [
    {"name": "icr:<name>", "path": "commands/<name>.md"}
  ]
}

Adding a New Severity Rule

Edit config/defaults.json:

{
  "severity": {
    "userRules": [
      {
        "pattern": "ToolName",
        "condition": "args.property === 'value'",
        "severity": "CRITICAL",
        "reason": "Why this is critical"
      }
    ]
  }
}

Modifying Confidence Weights

Edit config/defaults.json:

{
  "confidence": {
    "weights": {
      "ambiguityAnalysis": 0.30,
      "intentToActionDistance": 0.25,
      "historicalPatterns": 0.20,
      "uncertaintyMarkers": 0.25
    }
  }
}

Adding a New Hook

Create script in scripts/<hook-name>.sh

{
  "hooks": {
    "HookEventName": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/<hook-name>.sh"
      }]
    }]
  }
}

Code Patterns

Script Structure

All scripts follow this pattern:

#!/bin/bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
LIB_DIR="${SCRIPT_DIR}/lib"

source "${LIB_DIR}/common.sh"

main() {
    require_jq
    local input
    input=$(read_json_input)
    # ... processing ...
    echo "$result"
}

if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
    main "$@"
fi

JSON I/O Pattern

Hooks receive JSON via stdin
Hooks output JSON to stdout

Use jq for all JSON operations:

# Reading
local value=$(echo "$json" | jq -r '.field')

# Writing
jq -n --arg f "$field" '{"field": $f}'

Error Handling

Scripts use set -euo pipefail for strict error handling
Graceful degradation: if component fails, escalate to HUMAN_REVIEW
All errors are logged to .claude/icr/errors.log

Testing

Manual Testing

# Test severity classification
echo '{"tool_name": "Bash", "tool_input": {"command": "rm -rf /"}}' | \
  bash scripts/lib/severity.sh

# Test confidence calculation
bash scripts/lib/confidence.sh "delete old files" "Bash" '{"command": "rm"}' '{}' ".claude/icr/receipts"

Integration Testing

Use Claude Code with --plugin-dir ./icr to test the full plugin.

Runtime Data

ICR stores runtime data in .claude/icr/:

.claude/icr/
├── config.json           # User overrides (merged with defaults)
├── session-state.json    # Current session state
├── errors.log            # Error log
├── receipts/             # Audit trail
│   └── YYYY-MM-DD/
│       └── session-xxx/
│           ├── session-meta.json
│           └── 001-receipt.json
├── exports/              # Exported receipts
└── checkpoints/          # Checkpoint metadata

Key Concepts

Severity Levels

Level	Risk	Examples	Default Behavior
LOW	Minimal	Read, Glob, Grep	Auto-approve
MEDIUM	Moderate	Write, Edit	Confidence-based
HIGH	Significant	Bash	Usually review
CRITICAL	Dangerous	Delete, rm -rf	Always human review

Confidence Score (0.0 - 1.0)

Calculated from 4 weighted signals:

Ambiguity Analysis (30%): How many valid interpretations exist
Intent-to-Action Distance (25%): Semantic gap between request and action
Historical Patterns (20%): Similarity to past successful actions
Uncertainty Markers (25%): Hedging language in the request

Decision Routes

AUTO_APPROVE: Confidence ≥ auto threshold → proceed immediately
AI_REVIEW: Confidence between AI and auto thresholds → AI validates
HUMAN_REVIEW: Confidence < human threshold → user must approve

Important Files to Understand

scripts/pre-tool-check.sh: Main entry point, orchestrates the full ICR flow
scripts/lib/decision.sh: Decision tree logic for routing
config/defaults.json: All configurable options with defaults
docs/ICR_PLUGIN_SPEC.md: Complete specification (reference for any questions)

Common Pitfalls

JSON escaping: Always use jq for JSON generation, never string concatenation
Variable quoting: Always quote variables in Bash: "$variable"
Exit codes: Hook scripts must exit 0 for success
Stdin consumption: Read stdin once and store in variable

Getting Help

Full Spec: docs/ICR_PLUGIN_SPEC.md has exhaustive details
User Guide: docs/USER_GUIDE.md for end-user documentation
Developer Guide: docs/DEVELOPER_GUIDE.md for implementation details
Troubleshooting: docs/TROUBLESHOOTING.md for common issues

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLAUDE.md - AI Assistant Context for ICR Plugin

Acknowledgement

Project Overview

The Three Phases

Repository Structure

Key Technologies

Common Development Tasks

Adding a New Slash Command

Adding a New Severity Rule

Modifying Confidence Weights

Adding a New Hook

Code Patterns

Script Structure

JSON I/O Pattern

Error Handling

Testing

Manual Testing

Integration Testing

Runtime Data

Key Concepts

Severity Levels

Confidence Score (0.0 - 1.0)

Decision Routes

Important Files to Understand

Common Pitfalls

Getting Help

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md - AI Assistant Context for ICR Plugin

Acknowledgement

Project Overview

The Three Phases

Repository Structure

Key Technologies

Common Development Tasks

Adding a New Slash Command

Adding a New Severity Rule

Modifying Confidence Weights

Adding a New Hook

Code Patterns

Script Structure

JSON I/O Pattern

Error Handling

Testing

Manual Testing

Integration Testing

Runtime Data

Key Concepts

Severity Levels

Confidence Score (0.0 - 1.0)

Decision Routes

Important Files to Understand

Common Pitfalls

Getting Help