# Hedgehog 🦔

A Model Context Protocol (MCP) server for structured spike investigations and Architecture Decision Record (ADR) generation.

## What It Does

Manages technical spike investigations with:

- **Enforced 4-phase workflow**: Meta-design → Divergent exploration → Adversarial challenge → Synthesis
- **State machine**: Prevents skipping phases or invalid transitions
- **Checkpoint/rollback**: Save and restore investigation state
- **ADR generation**: Auto-generates ADRs from exploration artifacts
- **Dead-end tracking**: Documents abandoned approaches for future reference

## Installation

```bash
git clone https://github.com/jpalmerr/Hedgehog.git
cd Hedgehog
pip install .
```

Then add to your Claude Code MCP settings (`~/.claude.json`):

```json
{
  "mcpServers": {
    "hedgehog": {
      "command": "hedgehog",
      "args": []
    }
  }
}
```

Or via the CLI:

```bash
claude mcp add hedgehog --scope user -- hedgehog
```

## Example Flow

Here's how a real investigation looks in Claude Code. You talk to Claude naturally — Hedgehog manages the structure behind the scenes.

### Session 1: Frame the problem

> **You:** I need to investigate options for migrating our Kafka topic IDs from numeric to string-based. Create a spike for this.

Claude calls `spike_create("kafka-topic-migration", "Evaluate approaches for migrating Kafka topic IDs from numeric to string-based identifiers")` and generates a meta-design template covering the problem statement, key questions, success criteria, and constraints.

> **You:** The meta-design looks good. The key constraint is zero downtime — we can't stop consumers during migration. Approve it and let's start exploring.

Claude calls `spike_approve_meta` → advances to Phase 1. State is checkpointed automatically.

> **You:** Let's explore three approaches: dual-write, shadow topics, and a proxy translation layer.

Claude registers all three branches and starts investigating the first one — reading docs, considering trade-offs, and documenting findings for each branch as it goes.

### Session 2: Continue exploration (next day)

> **You:** Pick up the kafka-topic-migration spike. Where did we leave off?

Claude calls `spike_get_state` → sees Phase 1 with one branch explored, two remaining. Continues investigating the remaining branches.

When the third branch is completed, Hedgehog automatically advances to Phase 2 (adversarial challenge) and checkpoints the state.

### Session 3: Challenge and synthesize

> **You:** Continue the spike. Challenge each approach — focus on failure modes and hidden assumptions.

Claude systematically challenges each branch: What happens during a dual-write if one write fails? What's the rollback story for shadow topics? How does the proxy handle schema evolution?

When all branches are challenged, Hedgehog auto-advances to Phase 3. Claude synthesizes the findings, generates an ADR with the recommendation, and you approve it.

### The tools behind the scenes

Throughout this flow, Claude is calling Hedgehog tools:

```
spike_create / spike_approve_meta          → Phase 0 (framing)
spike_add_branch / spike_complete_branch   → Phase 1 (exploration)
spike_add_challenge                        → Phase 2 (adversarial)
spike_synthesize / spike_generate_adr      → Phase 3 (synthesis)
spike_approve_adr                          → Complete
```

Checkpoints are created automatically at each phase transition. Use `spike_checkpoint` for manual saves and `spike_rollback` to revert if an exploration path goes nowhere.

## Usage Guidance

### Investigations span multiple sessions

A full spike investigation is a significant piece of work — comparable to a multi-day task you'd do at work. Hedgehog persists all state to disk (`~/.claude/spikes/`), so you can spread an investigation across as many Claude Code sessions as you need.

Natural session boundaries:
- **Session 1:** Frame the problem (Phase 0), start exploration
- **Session 2-3:** Complete branch explorations (Phase 1)
- **Session 4:** Adversarial challenges + synthesis (Phases 2-3)

Use `spike_get_state` at the start of any session to pick up where you left off.

### Right-sizing your investigation

Not every technical question needs a full spike. Use Hedgehog when:
- The decision is hard to reverse (infrastructure, data model, core architecture)
- There are genuinely 3+ viable approaches worth comparing
- You need a defensible ADR for your team

For smaller questions, just ask Claude directly — no ceremony needed.

### Pro plan considerations

Hedgehog's own overhead is minimal (small JSON tool calls). The tokens go on Claude thinking about your problem — reading code, researching approaches, writing analysis. A full 3-branch investigation is token-intensive because the *work* is intensive.

On a Pro plan, lean into the multi-session workflow. Do one branch per session if needed. The checkpoint system means you never lose progress.

## The Four Phases

### Phase 0: Meta-Design
Define the investigation scope, key questions, and success criteria. Forces you to think about whether you're solving the right problem.

### Phase 1: Divergent Exploration
Explore at least 3 distinct approaches. Don't converge prematurely—document advantages, disadvantages, and open questions for each.

### Phase 2: Adversarial Challenge
For each branch, systematically identify failure modes, challenge assumptions, and find second-order effects.

### Phase 3: Synthesis
Compare branches, produce a recommendation with uncertainty bounds, and generate an ADR documenting the decision.

## Available Tools

| Tool | Description |
|------|-------------|
| `spike_create` | Create new spike investigation |
| `spike_list` | List all spikes |
| `spike_get_state` | Get current spike state |
| `spike_approve_meta` | Approve meta-design, advance to Phase 1 |
| `spike_add_branch` | Register a branch for exploration |
| `spike_complete_branch` | Mark branch as explored with findings |
| `spike_mark_dead_end` | Document abandoned approach |
| `spike_add_challenge` | Add adversarial challenge to branch |
| `spike_synthesize` | Create synthesis document |
| `spike_generate_adr` | Generate ADR from artifacts |
| `spike_approve_adr` | Mark spike complete |
| `spike_checkpoint` | Save current state |
| `spike_rollback` | Restore to checkpoint |
| `spike_archive` | Archive completed spike |
| `spike_delete` | Delete spike |

## Available Resources

| URI | Description |
|-----|-------------|
| `spike://{name}/state` | Current spike state as JSON |
| `spike://{name}/meta-design` | Meta-design document |
| `spike://{name}/branches` | List of branch documents |
| `spike://{name}/branches/{branch}` | Specific branch content |
| `spike://{name}/challenges/{branch}` | Challenge document for branch |
| `spike://{name}/adr` | Generated ADR |

## Development

```bash
# Clone and setup
git clone https://github.com/jpalmerr/Hedgehog
cd Hedgehog
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Type check
mypy src

# Lint
ruff check src tests
```

## License

MIT