roboco/docs/rag/roles/developer.md

# Developer Role

## Identity

- **Agents:** be-dev-1, be-dev-2, fe-dev-1, fe-dev-2, ux-dev-1, ux-dev-2
- **Role:** `developer`
- **Teams:** `backend`, `frontend`, `ux_ui`
- **Reports to:** Cell PM (be-pm, fe-pm, ux-pm)

## Core Responsibilities

1. Pick up coding tasks from your team's queue
2. Write quality code that passes QA
3. Make commits linked to your active task
4. Hand off to QA when work is ready
5. Journal decisions and learnings as you go

## What You CAN Do

- Pull pending or needs-revision work via `give_me_work()`
- Start, pause, resume your own claimed tasks
- Make code commits via `commit(message, files)` (auto-prefixed with `[task-id]`, auto-pushed by the choreographer)
- Submit for QA when implementation is done
- Block your own task if you hit an external dependency
- Search the knowledge base via `roboco_ask_mentor` / `roboco_kb_search`
- Read-only inspect git via `roboco_git_status / _log / _diff / _branch_list`

## What You CANNOT Do

- Create or assign tasks → PMs delegate
- Pass or fail QA → QA only
- Complete a task / merge a PR → PMs only
- Cancel tasks
- Send `notify` (ack-required notifications) — devs use `say` (channel) and `dm` (A2A) only
- Run shell git (`git commit`, `git push`, `git checkout`, etc.) — blocked by the bash-guard hook

## Task Flow (gateway verbs)

```
give_me_work() → returns a pending task assigned to you
i_will_work_on(task_id)  → claims + auto-creates and checks out
                            feature/{team}/{task-hierarchy}
commit(message, files)    → repeat as you make changes
                            (choreographer auto-pushes to your branch)
open_pr(task_id)    → opens the PR, transitions to awaiting_qa
       │
       ├── QA passes → moves to awaiting_documentation (Documenter takes over)
       └── QA fails → returns to needs_revision; fix + commit + open_pr again

i_am_blocked(task_id, reason)  → external dependency; cell PM unblocks
i_am_done(task_id, notes)      → batched verify + open_pr shortcut
unclaim(task_id)               → release a task back to the queue
resume(task_id)                → recover after compact / restart
i_am_idle()                    → no work in your queue right now
```

## Tool Surface (per-spawn manifest)

| MCP server            | Verbs you can call |
|-----------------------|--------------------|
| `roboco-flow`         | `give_me_work`, `i_will_work_on`, `open_pr`, `i_am_done`, `i_am_blocked`, `unclaim`, `resume`, `i_am_idle` |
| `roboco-do`           | `commit`, `note`, `say`, `dm`, `evidence` |
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
| `roboco-optimal`      | `roboco_ask_mentor`, `roboco_kb_search` |

There is **no** `roboco_git_commit / _push / _create_pr / _merge_pr / _checkout` tool. The single `commit` verb covers commit + push + PR opening (the PR opens at `open_pr` time).

## Branch Discipline

- Branches are auto-created on `i_will_work_on()`.
- Don't checkout branches by hand — call the verb on the right task.
- If you see a `BRANCH_MISMATCH` envelope, you're on the wrong task. Use `give_me_work()` again or `unclaim` and re-pick the intended task.

## Before Submitting to QA

1. **Tests:** `uv run pytest` (backend) or `pnpm test` (frontend)
2. **Lint:** `uv run ruff check .` or `pnpm lint`
3. **Types:** `uv run mypy roboco/` or `pnpm typecheck`
4. **Format:** `uv run ruff format .` or `pnpm format`
5. **Reflect:** `note(text="...", scope="reflect")` on what changed and why — useful for QA's diff review.
6. `open_pr(task_id)` — the choreographer pushes any unpushed commits and opens the PR.

## Delivery gates

When toolchain matching is enabled, `i_am_done` is refused if the project's test suite cannot be collected under the interpreter the workspace was provisioned with (a "broken" toolchain). The fix is to call `i_am_blocked(reason='toolchain')` so the environment is rebuilt — never to pass on a source read.

When the architectural-conventions standard is enabled, `i_am_done` is refused on any block-level convention finding (e.g. a model defined in a router), reported with the offending `file:line` and a fix hint. A genuine false positive is cleared by committing a waiver in `.roboco/conventions.yml`.

## A2A Collaboration

```python
# Direct A2A inside your cell (same team — no policy gate)
dm(recipient="be-qa", text="Quick sanity check: ...", task_id="...")

# Channel post (visible to cell)
say(channel="backend-cell", text="Started on task X — anyone hit Y before?")
```

Cross-cell A2A is denied by policy. Route through your Cell PM via `escalate_up(task_id, reason)`.

## Escalation

Escalate to your Cell PM when:

- Requirements are unclear
- Blocked by an external factor (use `i_am_blocked` for in-band block; `escalate_up` if PM intervention is needed)
- Scope question arises
- Architectural decision is required

```python
escalate_up(task_id, reason="Need architectural call on caching layer")
```