# Configuration Reference

Legionnaire uses convention over configuration. This reference documents the naming rules, path conventions, and invariants.

---

## ID Naming Rules

Parent and child IDs are transformed and validated before use.

### Slugification

Whitespace is converted to dashes:

| Input | Output |
|-------|--------|
| `perf logging` | `perf-logging` |
| `schema v2` | `schema-v2` |
| `team a/perf logging` | `team-a/perf-logging` |

Slashes (`/`) are preserved for hierarchy.

### Validation

IDs are rejected if they contain:

| Pattern | Reason |
|---------|--------|
| Empty string | Invalid |
| Leading `/` | Invalid path |
| Trailing `/` | Invalid path |
| `//` | Empty segment |
| `.` segment | Path traversal |
| `..` segment | Path traversal |
| `.lock` suffix | Git ref hazard |
| `@{` | Git ref hazard |
| `~`, `^`, `:`, `?`, `*`, `[`, `\` | Git ref hazards |
| Control characters | Invalid |
| Spaces (after slugify) | Should not occur |

---

## Path Layout

### Worktrees Root

Located as a sibling to the repository root:

```
/path/to/my-repo/           # Repository root
/path/to/my-repo_worktrees/ # Worktrees root
```

### Parent Directory

```
<worktrees_root>/<parent_id>/
```

Example: `/path/to/my-repo_worktrees/feature-x/`

### Parent Worktree

```
<worktrees_root>/<parent_id>/parent/
```

Example: `/path/to/my-repo_worktrees/feature-x/parent/`

### Child Worktree

```
<worktrees_root>/<parent_id>/<child_id>/
```

Example: `/path/to/my-repo_worktrees/feature-x/task-a/`

---

## Branch Naming

### Parent Branch

```
<parent_id>/parent
```

Example: `feature-x/parent`

### Child Branch

```
<parent_id>/<child_id>
```

Example: `feature-x/task-a`

---

## tmux Configuration

### Session Name

```
<parent_id>
```

Session is marked with `@legion_managed=1` to prevent conflicts.

### Window Naming

| Window | Name | Index |
|--------|------|-------|
| Parent | `parent` | 0 |
| Children | `<child_id>` | 1, 2, 3, ... |

### Window Colors

Windows are colored deterministically:

| Window | Color |
|--------|-------|
| Parent | Red (`colour196`) |
| Child 1 | Blue (`colour27`) |
| Child 2 | Cyan (`colour33`) |
| Child 3 | Light cyan (`colour39`) |
| ... | Cycles through palette |

Color palette:

```
colour27, colour33, colour39, colour45, colour51,
colour50, colour49, colour48, colour47, colour46,
colour82, colour118
```

---

## Agent Configuration

### PID File

Each child stores agent PID in:

```
<child_worktree>/.legion-agent.pid
```

### Launch Commands

**Claude:**
```bash
bash -lc 'export LEGION_AGENT_NAME="<parent>/<child>"; echo $$ > .legion-agent.pid; exec claude'
```

**Cursor:**
```bash
bash -lc 'export LEGION_AGENT_NAME="<parent>/<child>"; echo $$ > .legion-agent.pid; exec cursor agent'
```

### Environment Variable

Agents receive:

```
LEGION_AGENT_NAME=<parent_id>/<child_id>
```

---

## Invariants

1. **Children always base from parent HEAD** - No original spawn base mode
2. **Parent window is always index 0** - Named `parent`
3. **Child windows are lexicographically sorted** - Indices 1..N
4. **Stateless design** - Only PID files on disk
5. **Session ownership** - Sessions without `@legion_managed=1` are not touched
