# Cleave

Recursive task decomposition for Claude Code. Split complex directives along domain boundaries, execute in parallel, reunify with conflict detection.

## Etymology

"Cleave" holds contradictory meanings: to split apart AND to hold fast together. This duality captures the tool's essence—we cleave tasks into independent pieces, then cleave the results back into a unified whole.

## Installation

Both the CLI tool and Claude Code skill are required for full functionality.

```bash
# 1. Clone the repo
git clone git@github.com:styrene-lab/cleave.git ~/projects/cleave

# 2. Install the CLI (editable mode for easy updates)
pip install -e ~/projects/cleave

# 3. Symlink the skill definition to Claude Code's discovery path
ln -sf ~/projects/cleave/src/cleave/skill ~/.claude/skills/cleave

# 4. Verify
cleave --help
```

To update later:
```bash
cd ~/projects/cleave && git pull
# CLI updates automatically (editable install)
# Skill symlink remains valid
```

## Usage

### Within Claude Code

Invoke via `/cleave` in any Claude Code session:

```
/cleave

Implement user authentication with JWT tokens, ensuring backwards
compatibility with existing session-based auth. Include migration
path and tests.
```

Claude will:
1. Assess complexity
2. Split into 2-3 child tasks if needed
3. Execute children (parallel or sequential)
4. Reunify results with conflict detection

### CLI Commands

```bash
# Assess complexity of a directive
cleave assess --directive "Add user auth with JWT"

# Match against known patterns
cleave match --directive "Add Stripe payments"

# Initialize workspace for manual execution
cleave init --directive "Add auth" --children '["Backend", "Frontend"]'

# Detect conflicts between task results
cleave conflicts --results ".cleave/0-task.md,.cleave/1-task.md"

# Reunify completed tasks
cleave reunify --workspace .cleave
```

## Concepts

### Complexity Assessment

**Formula**: `complexity = (1 + systems) × (1 + 0.5 × modifiers)`

- **Systems**: Distinct architectural boundaries (UI, API, DB, external services)
- **Modifiers**: State coordination, error handling, concurrency, security, etc.

If `complexity > threshold`, the directive gets cleaved.

### Splitting Strategy

- **Binary (2)**: Clean frontend/backend or data/logic seams
- **Ternary (3)**: Multi-layer stacks (UI/API/DB)
- **Never 4+**: Coordination overhead exceeds benefits

### Workspace Structure

```
.cleave/
├── manifest.yaml      # Intent, ancestry, children, assessment
├── siblings.yaml      # Sibling coordination, file claims
├── 0-task.md          # Child 0 task file
├── 1-task.md          # Child 1 task file
├── metrics.yaml       # Telemetry
├── merge.md           # Reunification report
└── review.md          # Adversarial review
```

### Conflict Detection

Four conflict types detected during reunification:

1. **File Overlap** - Multiple children modified same file
2. **Decision Contradiction** - Incompatible choices (Redis vs Memcached)
3. **Interface Mismatch** - Different signatures for same function
4. **Assumption Violation** - Child assumption contradicts sibling decision

## Configuration

### Modes

- **Lean** (default): Terse output, fast-path assessment
- **Robust**: Verbose reasoning, sequential thinking for all assessments

### Flags

- `--no-tdd`: Skip TDD workflow instructions in task files
- `--no-review`: Skip adversarial review during reunification
- `--infer-permissions`: Detect required bash permissions upfront

## Requirements

- Python 3.11+
- Claude Code CLI (for skill usage)
- Sequential Thinking MCP server (recommended for complex assessments)

## License

MIT
