Contributing to ICR

Thank you for your interest in contributing to ICR! This guide will help you get started with contributing to the project.

Acknowledgement: ICR is inspired by the YouTube video "The AI Failure Mode Nobody Warned You About (And how to prevent it from happening)". Before contributing, we recommend watching this video to understand the core problem ICR solves.

Getting Started
Development Setup
Code Style Guidelines
Making Changes
Testing Your Changes
Submitting Changes
Types of Contributions
Getting Help

Getting Started

Prerequisites

Before contributing, make sure you have:

Git installed and configured
jq installed (version 1.6 or higher)
Claude Code installed for testing
ShellCheck installed (optional, for linting)
A text editor with Bash and JSON support

Understanding the Codebase

Before making changes, please read:

ARCHITECTURE.md - Understand the big picture
DEVELOPER_GUIDE.md - Learn implementation details
ICR_PLUGIN_SPEC.md - Full specification

First-Time Contributors

Good first issues include:

Adding new severity patterns
Improving error messages
Adding documentation
Writing tests
Fixing typos

Development Setup

Step 1: Clone the Repository

git clone <repository-url>
cd icr

Step 2: Verify Prerequisites

# Check jq
jq --version
# Should output: jq-1.6 or higher

# Check ShellCheck (optional but recommended)
shellcheck --version

Step 3: Make Scripts Executable

chmod +x scripts/*.sh
chmod +x scripts/lib/*.sh

Step 4: Set Up for Testing

Create a symlink to your plugins directory:

# macOS/Linux
ln -s $(pwd) ~/.claude/plugins/icr-dev

# Or copy for testing
cp -r . ~/.claude/plugins/icr-dev

Step 5: Verify Installation

Start Claude Code and run:

/icr:stats

You should see the statistics output.

Code Style Guidelines

Bash Scripts

File Header

Every script should start with:

#!/bin/bash
# Brief description of what this script does
# Additional context if needed

set -euo pipefail

Variable Naming

# Local variables: snake_case
local my_variable="value"

# Environment variables: UPPER_SNAKE_CASE
export ICR_CONFIG_PATH="/path/to/config"

# Constants (readonly): UPPER_SNAKE_CASE
readonly MAX_RETRIES=3

Function Naming

# Functions: snake_case
calculate_confidence() {
    # ...
}

# Private/internal functions: prefix with underscore
_internal_helper() {
    # ...
}

Quoting

Always quote variables to prevent word splitting:

# Good
echo "$my_variable"
local result="$other_variable"

# Bad
echo $my_variable
local result=$other_variable

Error Handling

# Use set -e to exit on errors
set -euo pipefail

# Check command success explicitly when needed
if ! result=$(some_command); then
    log_error "Command failed"
    return 1
fi

# Provide fallback for optional commands
value=$(risky_command 2>/dev/null || echo "default")

Comments

# Single-line comment for brief explanations

# Multi-line comments for complex logic:
# This section handles the edge case where
# the user has specified a custom threshold
# that conflicts with trust mode settings.

# TODO: Add feature X
# FIXME: Handle edge case Y

JSON Files

Formatting

Use 2-space indentation:

{
  "key": "value",
  "nested": {
    "inner": "value"
  },
  "array": [
    "item1",
    "item2"
  ]
}

Validation

All JSON files should be valid. Check with:

jq . filename.json > /dev/null

Markdown Files

Command Documentation

Follow this structure:

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

# Command Name

One paragraph explaining what the command does.

## Usage

- `/icr:command` - Basic usage
- `/icr:command arg` - With argument

## Examples

[Include practical examples]

## Notes

[Any important notes or warnings]

Making Changes

Step 1: Create a Branch

git checkout -b feature/my-feature
# or
git checkout -b fix/my-bugfix

Step 2: Make Your Changes

Edit the relevant files. Keep changes focused - one feature or fix per branch.

Step 3: Validate Your Changes

# Lint bash scripts
shellcheck scripts/*.sh
shellcheck scripts/lib/*.sh

# Validate JSON files
jq . config/defaults.json > /dev/null
jq . schemas/*.json > /dev/null

# Test individual scripts
echo '{"tool_name": "Bash"}' | bash scripts/lib/severity.sh

Step 4: Update Documentation

If your changes affect user-facing behavior:

Update the relevant command documentation in commands/
Update USER_GUIDE.md if needed
Update DEVELOPER_GUIDE.md if you changed implementation details
Add an entry to CHANGELOG.md

Step 5: Commit Your Changes

Write clear commit messages:

# Good
git commit -m "Add severity rule for 'sudo' commands

- Adds CRITICAL severity for Bash commands containing 'sudo'
- Updates defaults.json with new pattern
- Adds documentation in USER_GUIDE.md"

# Bad
git commit -m "fixed stuff"

Testing Your Changes

Manual Testing

Test Individual Components

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

# Expected output includes severity: "CRITICAL"

Test Full Flow

# Test the main hook
echo '{
  "tool_name": "Bash",
  "tool_input": {"command": "ls -la"},
  "session_id": "test-123",
  "user_prompt": "list files"
}' | bash scripts/pre-tool-check.sh

Test with Claude Code

Start Claude Code with your development plugin:
```
claude --plugin-dir ./
```
Test various scenarios:
- Low-risk actions (should auto-approve)
- High-risk actions (should prompt)
- Slash commands (/icr:stats, /icr:receipts)

Automated Checks

Before submitting, run all checks:

# Create a simple test script
#!/bin/bash
set -e

echo "Linting scripts..."
shellcheck scripts/*.sh scripts/lib/*.sh

echo "Validating JSON..."
for f in config/*.json schemas/*.json; do
  jq . "$f" > /dev/null
  echo "  $f OK"
done

echo "Testing severity classification..."
result=$(echo '{"tool_name": "Read"}' | bash scripts/lib/severity.sh)
echo "$result" | jq -e '.severity == "LOW"' > /dev/null
echo "  Severity test OK"

echo "All checks passed!"

Submitting Changes

Before Submitting

Ensure:

All scripts pass ShellCheck (or have documented exceptions)
All JSON files are valid
You've tested your changes manually
Documentation is updated
CHANGELOG.md has an entry for your change
Commit messages are clear and descriptive

Pull Request Guidelines

Title: Clear, concise description
- Good: "Add CRITICAL severity for sudo commands"
- Bad: "Fixed issue"

Description: Explain what and why

## What
Added automatic CRITICAL classification for Bash commands containing 'sudo'.

## Why
sudo commands can make system-wide changes and should always require human review.

## Testing
- Tested with `echo '{"tool_name": "Bash", "tool_input": {"command": "sudo apt install"}}' | bash scripts/lib/severity.sh`
- Verified CRITICAL severity is returned

## Documentation
- Updated USER_GUIDE.md with new pattern
- Added CHANGELOG entry

Keep it focused: One feature/fix per PR

Types of Contributions

Bug Fixes

Describe the bug in an issue first
Reference the issue in your PR
Add a test case that would have caught the bug

New Features

Discuss the feature in an issue first
Get agreement on the approach
Implement with tests and documentation

Documentation

Fix typos or unclear explanations
Add examples
Improve tutorials
Translate documentation

New Severity Patterns

Add to config/defaults.json:

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

New Commands

Create commands/mycommand.md
Add to plugin.json
Document in USER_GUIDE.md
Add to CHANGELOG.md

Getting Help

Questions?

Check existing documentation first
Look at similar code in the codebase
Ask in project discussions/issues

Found a Bug?

Check if it's already reported
Create a new issue with:
- Steps to reproduce
- Expected behavior
- Actual behavior
- Environment details

Have a Feature Idea?

Check if it's already proposed
Create an issue describing:
- The problem you're solving
- Your proposed solution
- Alternatives considered

Code of Conduct

Be respectful and inclusive
Focus on constructive feedback
Help others learn
Assume good intentions

Recognition

Contributors are recognized in:

CHANGELOG.md for each release
Contributors list in README.md

Thank you for contributing to ICR!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History