# Advanced Patterns Guide

Advanced techniques for using Cleave effectively in complex scenarios.

## Table of Contents

1. [Custom Pattern Creation](#custom-pattern-creation)
2. [Calibration Tuning](#calibration-tuning)
3. [Multi-Model Workflows](#multi-model-workflows)
4. [Fire-and-Forget Execution](#fire-and-forget-execution)
5. [Nested Cleaving](#nested-cleaving)
6. [Integration with CI/CD](#integration-with-cicd)

## Custom Pattern Creation

When the built-in patterns don't match your domain, create custom patterns.

### Pattern Structure

Patterns are defined in `src/cleave/core/assessment.py`:

```python
{
    "name": "Payment Integration",
    "keywords": ["payment", "stripe", "billing", "checkout", "subscription"],
    "systems_base": 3,  # API, Webhook Handler, Database
    "modifiers": {
        "error_handling": True,  # Payment failures, retries
        "external_api": True,     # Stripe SDK
        "state_coordination": True,  # Sync Stripe state with DB
        "security": True,         # API keys, webhook signatures
    },
    "confidence_threshold": 0.80
}
```

### Pattern Fields

- **name**: Human-readable pattern name
- **keywords**: List of terms that trigger this pattern
- **systems_base**: Baseline number of systems for this pattern
- **modifiers**: Expected complexity modifiers (boolean flags)
- **confidence_threshold**: Minimum confidence to match this pattern

### Adding a Custom Pattern

1. **Define the pattern** in your project-specific configuration
2. **Test with `cleave match`** to verify keyword matching
3. **Calibrate** using metrics from actual runs

Example custom pattern for data pipeline:

```python
{
    "name": "Data Pipeline",
    "keywords": ["etl", "pipeline", "transform", "ingest", "data processing"],
    "systems_base": 4,  # Ingestion, Transform, Storage, Monitoring
    "modifiers": {
        "state_coordination": True,  # Pipeline state management
        "performance_sla": True,      # Throughput requirements
        "error_handling": True,       # Retry, dead letter queues
        "data_migration": True,       # Schema evolution
    },
    "confidence_threshold": 0.75
}
```

### Testing Custom Patterns

```bash
# Test pattern matching
cleave match --directive "Build ETL pipeline for customer data ingestion"

# Expected output
Pattern Match: Data Pipeline (0.80)
Systems: 4 (Ingestion, Transform, Storage, Monitoring)
Modifiers: 4 (state, performance, errors, migration)
Complexity: 10.0
```

## Calibration Tuning

Over time, tune the complexity formula to match your project's reality.

### Collecting Calibration Data

Run cleave sessions and collect metrics:

```bash
# After each cleave run
cleave metrics --workspace .cleave

# Aggregate across multiple runs
find . -name 'metrics.yaml' -exec cat {} \;
```

### Analyzing Assessment Accuracy

Metrics track **predicted vs actual** complexity:

```yaml
assessment:
  predicted_complexity: 6.0
  predicted_effort: "medium"
  outcome:
    actual_effort: "high"  # Inferred from task result
    accuracy: 0.67  # Underestimated
```

### Adjusting the Formula

If assessments consistently under/overestimate:

**Option 1: Adjust threshold**
```bash
# Raise threshold to cleave less often
cleave config set execution.threshold 6.0
```

**Option 2: Adjust systems_base per pattern**

For patterns that consistently run high:
```python
# Increase systems_base for Authentication pattern
"Authentication System": {
    "systems_base": 4,  # Was 3, now 4 (more accurate)
    ...
}
```

**Option 3: Adjust modifier weights**

The formula uses `0.5` weight per modifier. If security always adds more complexity than expected:

```python
complexity = (1 + systems) * (1 + 0.7 * security_modifiers + 0.5 * other_modifiers)
```

### Calibration Workflow

1. **Run 10+ cleave sessions** on your project
2. **Export metrics**: `cleave metrics --export calibration.json`
3. **Analyze patterns** with low accuracy (< 0.70)
4. **Adjust** `systems_base` or modifier weights
5. **Re-run sessions** and measure improvement

### Example: Calibrating for Security-Heavy Projects

If security modifiers consistently add more work than expected:

```python
# Before
complexity = (1 + systems) × (1 + 0.5 × modifiers)

# After (security projects)
complexity = (1 + systems) × (1 + 0.5 × non_security_modifiers + 1.0 × security_modifiers)
```

Test with:
```bash
cleave assess --directive "Add OAuth2 authorization" --calibration security-heavy
```

## Multi-Model Workflows

Use different models for different phases of cleaving.

### Why Multi-Model?

- **Assessment**: Fast, cheap model (claude-haiku, gpt-3.5)
- **Execution**: Powerful model (claude-sonnet, gpt-4)
- **Review**: Critical reasoning model (claude-opus)

### Backend Switching

```bash
# Use lightweight model for assessment
cleave config set backend ollama
cleave assess --directive "$(cat feature.calf)"

# Switch to powerful model for execution
cleave config set backend claude
cleave config set backends.claude.default_model claude-sonnet-4-20250514
/cleave
$(cat feature.calf)
```

### Phase-Specific Models

Configure different models per phase (future feature):

```yaml
# ~/.cleave/settings.yaml
execution:
  models:
    assess: claude-haiku-20250514
    execute: claude-sonnet-4-20250514
    reunify: claude-opus-4-5-20251101
```

Usage:
```bash
cleave init --directive "..." --use-phase-models
```

### Cost Optimization

Run expensive models only when needed:

1. **Probe**: Local model (free, fast)
2. **Assessment**: Haiku (cheap, fast)
3. **Execution**: Sonnet (balanced)
4. **Review**: Opus (expensive, thorough) - only on conflicts

## Fire-and-Forget Execution

Enable autonomous cleave runs without permission interrupts.

### Permission Inference

Cleave can detect required bash permissions upfront:

```bash
# Assess with permission inference
cleave assess --directive "Build Python Flask API with PostgreSQL" --infer-permissions

# Output includes inferred permissions
Inferred Permissions:
  Bundles: [python, database, testing]
  Permissions:
    - Bash(python3:*)
    - Bash(pip:*)
    - Bash(pytest:*)
    - Bash(psql:*)
```

### Checking Permission Gap

Compare inferred vs configured permissions:

```bash
# Check what's missing
cleave check-permissions --directive "Build Python API"

# Output
Covered Permissions: 2/4
  - Bash(python3:*) ✓
  - Bash(pip:*) ✓

Missing Permissions: 2/4
  - Bash(pytest:*)
  - Bash(psql:*)

Add to ~/.claude/settings.local.json:
  "allowedCommands": [
    "Bash(pytest:*)",
    "Bash(psql:*)"
  ]
```

### Granting Permissions Upfront

Edit `~/.claude/settings.local.json`:

```json
{
  "allowedCommands": [
    "Bash(python3:*)",
    "Bash(pip:*)",
    "Bash(pytest:*)",
    "Bash(psql:*)"
  ]
}
```

### Fire-and-Forget Workflow

```bash
# 1. Assess with permissions
cleave assess -d "Build Flask API" --infer-permissions

# 2. Grant missing permissions (edit settings.local.json)

# 3. Initialize with permissions in manifest
cleave init -d "Build Flask API" \
  -c '["API", "Database"]' \
  --infer-permissions

# 4. Run via Claude Code - no interrupts
/cleave
Build Flask API with PostgreSQL
```

Claude will execute all child tasks without asking for bash permissions.

## Nested Cleaving

Children can cleave recursively if they exceed the complexity threshold.

### When to Use

Use nested cleaving when:
- Parent directive is very complex (complexity > 10)
- Child directives are independently complex
- Max depth allows (default: 5 levels)

### Example: Multi-Layer Application

```
Root: Build SaaS platform
├── Child 0: User Management System (complexity: 6.0) → cleaves
│   ├── 0.0: Authentication
│   ├── 0.1: Authorization
│   └── 0.2: User Profiles
├── Child 1: Payment System (complexity: 7.5) → cleaves
│   ├── 1.0: Checkout Flow
│   ├── 1.1: Webhook Handlers
│   └── 1.2: Subscription Management
└── Child 2: Admin Dashboard (complexity: 4.0) → executes directly
```

### Initiating Nested Cleave

Child tasks automatically trigger cleaving if their complexity exceeds threshold:

```markdown
## Child 0: User Management System

Implement user authentication, authorization, and profiles.

[Claude assesses this directive]
Complexity: 6.0 > threshold (5.0)
Decision: Cleave into 3 children
```

The child creates its own `.cleave/` subdirectory:

```
.cleave/
├── manifest.yaml        # Root
├── 0-task.md            # Child 0 (User Management)
└── 0/.cleave/           # Nested workspace for Child 0
    ├── manifest.yaml
    ├── 0-task.md        # 0.0: Authentication
    ├── 1-task.md        # 0.1: Authorization
    └── 2-task.md        # 0.2: User Profiles
```

### Depth Tracking

Each level tracks its depth:

```yaml
# Root: depth 0
ancestry:
  depth: 0
  node_id: "root"
  remaining_budget: 5

# Child 0: depth 1
ancestry:
  depth: 1
  node_id: "0"
  parent_chain: [{node_id: "root", depth: 0}]
  remaining_budget: 4

# Child 0.1: depth 2
ancestry:
  depth: 2
  node_id: "0.1"
  parent_chain: [{node_id: "root", depth: 0}, {node_id: "0", depth: 1}]
  remaining_budget: 3
```

### Max Depth Warning

At `depth == max_depth - 1`, Claude warns:

```
⚠ WARNING: At maximum depth (4/5). This task MUST be atomic.
No further cleaving allowed. Simplify or reduce scope if needed.
```

### Managing Deep Hierarchies

For very complex projects:

1. **Increase max_depth** temporarily:
   ```bash
   cleave config set execution.max_depth 7
   ```

2. **Pre-decompose** top-level manually:
   ```bash
   # Split into clear phases first
   cleave init -d "Build SaaS platform" \
     -c '["Phase 1: Core", "Phase 2: Payments", "Phase 3: Admin"]'
   ```

3. **Sequential execution** for deep trees:
   - Complete leaf nodes first (depth-first)
   - Reunify from bottom up

## Integration with CI/CD

Automate cleave in CI pipelines for consistent decomposition.

### Use Cases

1. **Automated complexity gating**: Reject PRs that should be split
2. **Documentation generation**: Auto-generate .cloven reports
3. **Metrics tracking**: Collect calibration data across team

### CI Workflow: Complexity Gating

```yaml
# .github/workflows/cleave-check.yml
name: Cleave Complexity Check

on: [pull_request]

jobs:
  complexity-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Install cleave
        run: pipx install styrene-cleave

      - name: Extract PR description as directive
        run: |
          gh pr view ${{ github.event.pull_request.number }} --json body \
            | jq -r '.body' > directive.txt

      - name: Assess complexity
        run: |
          cleave assess --directive "$(cat directive.txt)" > assessment.yaml

      - name: Check if should be split
        run: |
          DECISION=$(grep 'decision:' assessment.yaml | awk '{print $2}')
          if [ "$DECISION" = "cleave" ]; then
            echo "⚠ This PR is too complex and should be split"
            exit 1
          fi
```

### CI Workflow: Metrics Collection

```yaml
# .github/workflows/cleave-metrics.yml
name: Cleave Metrics Collection

on:
  push:
    branches: [main]

jobs:
  collect-metrics:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Find .cleave directories
        run: find . -type d -name '.cleave' > cleave-dirs.txt

      - name: Aggregate metrics
        run: |
          for dir in $(cat cleave-dirs.txt); do
            if [ -f "$dir/metrics.yaml" ]; then
              cat "$dir/metrics.yaml" >> all-metrics.yaml
            fi
          done

      - name: Upload metrics
        uses: actions/upload-artifact@v2
        with:
          name: cleave-metrics
          path: all-metrics.yaml
```

### CI Workflow: Auto-Documentation

```yaml
# .github/workflows/cleave-docs.yml
name: Generate Cleave Documentation

on:
  push:
    paths:
      - '**/.cleave/**'

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Generate reports
        run: |
          for manifest in $(find . -name 'manifest.yaml' -path '*/.cleave/*'); do
            workspace=$(dirname "$manifest")
            cleave report --workspace "$workspace" --format markdown \
              > "${workspace}/report.md"
          done

      - name: Commit generated docs
        run: |
          git config user.name "Cleave Bot"
          git config user.email "cleave@example.com"
          git add '**/.cleave/report.md'
          git commit -m "docs: update cleave reports" || true
          git push
```

## Best Practices

### 1. Start Simple, Calibrate Over Time

Don't over-tune patterns initially. Let metrics guide adjustments.

### 2. Use Robust Mode for Novel Patterns

When encountering unfamiliar domains:
```
cleave-robust

Implement blockchain smart contract with...
```

Verbose reasoning helps understand the assessment.

### 3. Pre-Grant Permissions for Autonomous Runs

For repeated workflows (testing, deployment):
```bash
# Grant broad permissions once
cleave check-permissions --directive "..." --snippet >> settings.local.json
```

### 4. Review Deep Hierarchies Carefully

Nested cleaving at depth 3+ increases coordination overhead. Consider manual decomposition at the top level.

### 5. Track Metrics Across the Team

Centralize metrics collection to calibrate patterns for your project/team's reality.

## Next Steps

- **Contributing**: [How to add patterns](contributing.md)
- **Architecture**: [Assessment Pipeline](../architecture/assessment-pipeline.md)
- **Examples**: [Pattern Library](../../examples/patterns/)
