# Migrating from 0.22.5 to 0.22.6

## Breaking changes

| Change | Impact | Error if you skip | § |
|--------|--------|-------------------|---|
| `branch.instruct()` removed | **High** | `AttributeError: 'Branch' object has no attribute 'instruct'` | §1 |
| `lionagi.operations.instruct` removed | **High** | `ModuleNotFoundError` | §2 |
| Persistence: `logs/agents/` → `runs/{run_id}/` | **Medium** | Resume finds nothing | §3 |
| `last_branch.json` schema | **Low** | None (auto-normalized) | §4 |
| Flat artifact dumps removed | **Medium** | `FileNotFoundError` on old paths | §5 |
| DAG op name `"instruct"` → `"operate"` | **Medium** | Orchestrator ignores op | §6 |
| `"codex/gpt-5.4"` fallback removed | **Low** | `ValueError: Provider must be provided` | §7 |
| `TEAM_WORKER_SYSTEM` composition | **Low** | Wrong prompt composition (silent) | §8 |

---

## §1 `branch.instruct()` → `branch.operate()`

```text
AttributeError: 'Branch' object has no attribute 'instruct'
```

```bash
grep -rn "\.instruct(" --include="*.py" .
```

```python
# before: await branch.instruct(instruction="...", stream_persist=True, persist_dir="./runs")
# after:  await branch.operate( instruction="...", stream_persist=True, persist_dir="./runs")
```

- ✓ Rename `.instruct(` → `.operate(`; all kwargs unchanged; `Instruct(...)` objects unchanged
- ✓ New optional `middle=` kwarg — omit to auto-dispatch (API→`communicate`, CLI→`run_and_collect`)

## §2 `lionagi.operations.instruct` module removed

```text
ModuleNotFoundError: No module named 'lionagi.operations.instruct'
```

```bash
grep -rn "from lionagi.operations.instruct\|import instruct" --include="*.py" .
```

```python
from lionagi.operations.instruct import instruct  # 0.22.5
from lionagi.operations.operate  import operate   # 0.22.6
```

- ✓ `Instruct` dataclass unchanged — only module path and function name changed

## §3 Persistence layout: `logs/agents/` → `runs/{run_id}/`

```text
# 0.22.5: ~/.lionagi/logs/agents/{provider}/{branch_id}.json

# 0.22.6: ~/.lionagi/runs/{YYYYMMDDTHHMMSS-uuid6}/
    ├── run.json
    ├── branches/{branch_id}.json
    ├── stream/{branch_id}.buffer.jsonl
    └── artifacts/{agent_id}/
```

`li agent -r {branch_id}` unchanged — `find_branch()` falls back to `logs/agents/` for pre-0.22.6 branches.

```bash
grep -rn "logs/agents" --include="*.py" .
```

- ✓ Replace `~/.lionagi/logs/agents/{provider}/` references → `~/.lionagi/runs/*/branches/`
- ✓ Pass `LIONAGI_RUN_ID=$run_id` when spawning CLI subprocesses to inherit the parent run

## Minor changes (§4–§8)

**§4 `last_branch.json` schema** — auto-normalized; direct parsers only.
`{"provider": "...", "branch_id": "..."}` → `{"run_id": "...", "branch_id": "..."}`.
Grep: `grep -rn "last_branch.json" --include="*.py" .`

- ✓ Replace `data["provider"]` with `data["run_id"]` in direct JSON parsers

**§5 Flat artifact dumps** — path format changed.
`./artifacts/r1_research.md` → `./artifacts/r1/research.md`
Grep: `grep -rn "artifact" --include="*.py" . | grep "_\.md"`

- ✓ Update: `{id}_{name}.md` → `{agent_id}/{name}.md`

**§6 DAG op name** — `"instruct"` → `"operate"` in `run.json` manifests; end-user CLI unaffected.
Grep: `grep -rn '"instruct"' --include="*.py" --include="*.json" .`

- ✓ Replace `operation.type == "instruct"` with `"operate"` in custom flow plugins
**§7 `"codex/gpt-5.4"` fallback** — `ValueError: Provider must be provided` if model unset.

- ✓ Add `--model codex/gpt-5.4` or `export LIONAGI_CHAT_MODEL=codex/gpt-5.4`
**§8 `TEAM_WORKER_SYSTEM`** — now `BARE_WORKER_SYSTEM + TEAM_COORD_SECTION`; may double-include base.
Grep: `grep -rn "TEAM_WORKER_SYSTEM\|TEAM_COORD_SECTION" --include="*.py" .`

- ✓ Use `TEAM_COORD_SECTION` for coordination-only block; audit custom prompts for duplicate base
*See also: [`CHANGELOG.md`](../../CHANGELOG.md) — 0.22.6 entry.*
