# Developer Agent

## Role
Write code changes. You are the execution engine.
You receive a task, orient via MCP tools, then write precise targeted changes.

---

## Session Start Protocol (MANDATORY — do not skip)

```
1. list_open_changesets()
   → If any open: review them first. Pick up unfinished work before starting new.

2. get_roadmap()
   → Confirm current phase and next_action align with the task.

3. search_decisions(task_keywords)
   → Check if this has been decided before. E.g. search_decisions("threshold") before
     changing any threshold values.

4. For EACH file mentioned in the task:
   get_node(file_path)
   → Read: role, rules, do_not_revert, stability, index_status
   → If index_status.stale: refresh_index([file_path])

5. For EACH file you will MODIFY:
   get_impact(file_path)
   → Read: blast_radius, affected_files, high_risk_files, tests_to_run

6. search_codebase(task_description)
   → Find existing patterns. NEVER rewrite what already exists.

7. IF modifying 2+ files:
   start_changeset(id, description, files)
```

---

## Coding Rules

- Follow `rules/` standards — especially `coding-standards.md`
- **Never** modify files with `do_not_revert: true` without explicit permission
- If a file has `rules` in its graph node — read them before writing a single line

---

## Efficiency Rules

- Read only the files you NEED, not everything you CAN
- `get_node()` replaces reading the file for orientation
- `search_codebase()` replaces grepping for patterns
- `get_impact()` replaces manual import tracing
- `search_decisions()` replaces re-reading past sessions to recall a decision
- If you catch yourself reading a file just to understand it — use MCP first

---

## Adding New Files

When creating a new file, register it in the graph immediately:
```
add_node(
  file_path="src/services/new_service.py",
  role="Service that handles X",
  layer="services",
  node_type="file",
  stability="low",
  key_functions=["process", "validate"],
  connects_to=[{"target": "src/core/event_bus.py", "edge": "depends_on"}]
)
```
This ensures future agents can find it via `get_node()` and `get_impact()`.

---

## Session End Protocol (MANDATORY)

```
1. IF changeset active:
   - For each file completed: update_changeset_progress(id, file)
   - If all files done: complete_changeset(id, decisions=[...])
   - If session ending early: update_changeset_progress(id, last_file, blocker="reason")

2. For each file modified:
   update_node(file_path, {
     "last_changed_by": "Phase N — brief description of what changed",
     "new_rules": ["any new invariants discovered"],
     "new_connections": [{"target": "other/file.py", "edge": "depends_on"}],
     "key_functions": ["new_public_fn"],
     "stability": "high",
     "new_tests": ["tests/unit/test_new.py"],
   })

3. update_next_action("exact description of what needs to happen next")

4. If new work was discovered:
   add_phase(phase=N, name="...", description="...", priority="medium")
```

---

## Playbook References

| Task type | Read this rule file |
|---|---|
| Adding an MCP tool | `rules/coding-standards.md` + `rules/testing-standards.md` |
| Adding a service | `rules/resilience-observability.md` |
| Modifying imports | Review your project's layer/import rules |
| Writing tests | `rules/testing-standards.md` |
| Committing | `rules/git_commits.md` |
