helix

# Helix

When: Multi-step implementation requiring exploration.
Not when: Simple edits, questions, single-file changes.

**Core Principle:** 9 primitives, my judgment, graph connects knowledge.

## Environment

```bash
HELIX="${HELIX_PLUGIN_ROOT:-$(cat .helix/plugin_root 2>/dev/null)}"
```

## States

```
INIT -> EXPLORING -> EXPLORED -> PLANNING -> PLANNED -> BUILDING -> DONE
                                                  |
                                               STALLED -> (replan | skip | abort)
```

State is implicit in conversation flow.

---

## 1. EXPLORE

**Input:** User objective.
**Output:** Merged exploration with non-empty `targets.files`.

### Step 1: Discover structure

```bash
git ls-files | head -80
```

**Judgment:** Identify 3-6 natural partitions using these heuristics:

| Codebase Signal | Partition Strategy |
|-----------------|-------------------|
| Clear directory structure (src/, lib/, tests/) | One partition per top-level directory |
| Microservices/modules | One partition per service/module |
| Frontend/backend split | Separate partitions for each |
| Monolith with layers | Partition by layer (data, business, presentation) |
| Framework-organized (Rails, Django) | Follow framework conventions |

**Always include**: A `memory` scope to recall relevant failures/patterns.

Partition count guidance:
- **3 partitions**: Small, focused objective touching 1-2 areas
- **4-5 partitions**: Medium objective, typical feature work
- **6 partitions**: Large objective spanning the system

Avoid: More than 6 partitions (diminishing returns, token cost).

### Step 2: Spawn explorer swarm

```python
# Launch in parallel for each identified partition (single message, multiple Task calls)
Task(subagent_type="helix:helix-explorer", prompt="SCOPE: src/api/\nFOCUS: route handlers\nOBJECTIVE: {objective}", model="haiku", run_in_background=True)
Task(subagent_type="helix:helix-explorer", prompt="SCOPE: src/models/\nFOCUS: data schemas\nOBJECTIVE: {objecti