Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
397 lines (289 loc) · 7.08 KB

CONTRIBUTING.md

File metadata and controls

397 lines (289 loc) · 7.08 KB

Contributing to Continuous Claude

Thank you for your interest in contributing! This guide covers how to add skills, agents, hooks, and extend TLDR.

Table of Contents

Development Setup

# Clone (your fork) of the repository
cd Continuous-Claude-v3/opc

# Install Python dependencies
uv sync

# Install hook dependencies (TypeScript)
cd ../.claude/hooks && npm install && npm run build && cd ../../opc

# Verify installation
claude
> /help

Adding Skills

Skills are modular capabilities defined in .claude/skills/<skill-name>/SKILL.md.

Skill Structure

.claude/skills/my-skill/
├── SKILL.md          # Main skill definition (required)
└── templates/        # Optional templates

SKILL.md Format

# my-skill

Short description of what this skill does.

## When to Use

- Trigger condition 1
- Trigger condition 2

## Workflow

1. Step one
2. Step two
3. Step three

## Commands

| Command | Description |
|---------|-------------|
| `/my-skill` | Main invocation |
| `/my-skill --option` | With options |

## Example

User: "do my-skill thing"
Claude: [executes skill workflow]

Registering Skill Triggers

Add to .claude/skills/skill-rules.json:

{
  "skill": "my-skill",
  "keywords": ["my-skill", "specific trigger"],
  "intentPatterns": ["do.*my.*skill"],
  "priority": 50
}

Quick Skill Creation

> /skill-developer

This interactive skill walks you through creating new skills.

Creating Agents

Agents are specialized AI workers defined in .claude/agents/<agent-name>.md.

Agent Structure

# Frontmatter
---
name: <name of agent>
description: <one line description of agent>
model: <preferred model: opus | sonnet | haiku>
tools: <list tools agent needs (optional): Read | Grep | Glob | etc...>
---

## Prompt

<system>
You are the agent-name agent for Continuous Claude.

Your job is to:
1. Specific task
2. Another task

## Constraints

- Constraint 1
- Constraint 2

## Output Format

Return results as:
[format description]
</system>

Agent Types

Type Model Use Case
Orchestrator Opus Coordinate multi-agent workflows
Researcher Sonnet/Opus Explore codebase or external sources
Implementer Opus Write/modify code
Reviewer Opus Analyze and critique
Specialist Varies Domain-specific tasks

Spawning Agents

Agents are spawned via the Task tool:

Task({
  subagent_type: "my-agent",
  prompt: "Do the thing",
  description: "Doing the thing"
})

Developing Hooks

Hooks intercept Claude Code at lifecycle points. Located in .claude/hooks/.

Hook Types

Lifecycle When it runs
SessionStart Session begins
SessionEnd Session ends
PreToolUse Before tool execution
PostToolUse After tool execution
UserPromptSubmit User sends a message
PreCompact Before context compaction
SubagentStart Subagent spawned
SubagentStop Subagent completes
Stop LLM generation stops

Shell Hook Template

#!/bin/bash
# .claude/hooks/my-hook.sh

# Read input from stdin (JSON)
INPUT=$(cat)

# Parse relevant fields
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // empty')

# Your logic here
if [[ "$TOOL_NAME" == "Read" ]]; then
    # Do something
    echo '{"result": "modified content"}'
else
    # Pass through
    echo "$INPUT"
fi

TypeScript Hook Template

// .claude/hooks/src/my-hook.ts
interface HookInput {
  tool_name?: string;
  tool_input?: Record<string, unknown>;
  session_id?: string;
}

interface HookOutput {
  result?: string;
  permissionDecision?: 'allow' | 'deny';
  reason?: string;
}

async function hook(input: HookInput): Promise<HookOutput> {
  // Your logic here
  return { result: 'success' };
}

// Entry point
const input: HookInput = JSON.parse(
  require('fs').readFileSync(0, 'utf-8')
);
hook(input).then(output => console.log(JSON.stringify(output)));

Registering Hooks

Add to .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "command": ".claude/hooks/my-hook.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Hook Development Workflow

> /hook-developer

Or debug existing hooks:

> /debug-hooks

Extending TLDR

TLDR is the 5-layer code analysis system in opc/packages/tldr-code/.

Architecture

tldr/
├── api.py              # Unified API (all layers)
├── ast_extractor.py    # L1: AST extraction
├── hybrid_extractor.py # Multi-language support
├── cross_file_calls.py # L2: Call graph
├── cfg_extractor.py    # L3: Control flow
├── dfg_extractor.py    # L4: Data flow
└── pdg_extractor.py    # L5: Program dependence

Adding Language Support

  1. Add tree-sitter grammar:
uv pip install tree-sitter-<language>
  1. Update hybrid_extractor.py:
LANGUAGE_CONFIGS = {
    'mylang': LanguageConfig(
        extension='.ml',
        tree_sitter_lang='mylang',
        function_patterns=['function_definition'],
        class_patterns=['class_definition']
    )
}
  1. Add tests in tests/test_mylang.py

Running TLDR Tests

cd opc/packages/tldr-code
source .venv/bin/activate
python -m pytest tests/ -v

Code Style

Python

  • Use type hints
  • Format with ruff
  • Follow PEP 8

TypeScript

  • Use strict mode
  • Format with Prettier
  • Follow existing patterns

Markdown

  • Use CommonMark
  • Keep lines under 100 chars
  • Use tables for structured data

Testing

Running All Tests

# TLDR tests
cd opc/packages/tldr-code && pytest tests/ -v

# Hook tests (TypeScript)
cd .claude/hooks && npm test

Testing Skills

# Manual test in Claude
> /my-skill

# Check skill-rules.json triggers
> "trigger phrase that should activate my-skill"

Testing Hooks

# Test hook directly
echo '{"tool_name": "Read", "tool_input": {"file_path": "test.py"}}' | .claude/hooks/my-hook.sh

Pull Request Process

  1. Fork the repository
  2. Create branch: git checkout -b feature/my-feature
  3. Make changes following the guidelines above
  4. Test your changes
  5. Commit with clear message
  6. Push to your fork
  7. Open PR with:
    • Description of changes
    • Testing done
    • Any breaking changes

PR Checklist

  • Tests pass
  • Documentation updated
  • No breaking changes (or documented)
  • Follows code style

Getting Help

  • Open an issue for bugs or feature requests
  • Use /help in Claude for usage questions
  • Check existing skills/agents for patterns

Thank you for contributing!