a0_software_orchestrator/help/handover/help.md

# handover_to_specialist – Tool Documentation

> **Status:** Phase 1 (read-only spike). The tool prepares a stage-1 handover
> package and appends a per-specialist briefing file. It does **not** yet
> invoke the subagent – the orchestrator follows up with `call_subordinate()`.

---

## Purpose

The Software-Orchestrator plugin exposes a single specialist hand-off tool
that follows the **3-stage context-transfer pattern** documented in
`/usr/workdir/handover-spike.md` (sections 4 and 5):

1. **Stage 1 (default):** token-bounded package = `summary` + last N turns +
   decisions + artifacts. Cost ≈ 1 500 – 4 000 tokens.
2. **Stage 2 (opt-in):** specialist calls `request_full_history()` for the
   full chat context, capped at 50 000 tokens with automatic compaction.
3. **Stage 3 (persistent):** briefing file in
   `<project_root>/.a0proj/handover/<specialist>-<topic>-<date>.md`,
   append-only Markdown, readable on demand by the specialist.

The goal is to give the user the experience of talking to a named specialist
(frontend designer, planner, architect, …) while keeping token usage low and
context safe.

---

## Tool signature

```python
handover_to_specialist(
    specialist_profile: str,        # required, must be in the allow-list
    topic: str,                     # required, short slug for the briefing file
    summary: str,                   # LLM-curated summary of the older turns
    recent_turns: list[str],        # verbatim last turns (auto-trimmed to N)
    decisions: list[str],           # decisions made so far
    artifacts: list[str],           # paths / references to relevant files
    return_condition: str,          # when the specialist should hand back
    handover_reason: str,           # logged into the briefing file
    project_root: str,              # absolute path to the project root
    max_context_tokens: int,        # default 3000; warning if exceeded
    include_recent_turns: int,      # default 5
)
```

### Argument notes

| Argument | Required | Notes |
|----------|----------|-------|
| `specialist_profile` | ✅ | One of the 12 known profiles (see below). |
| `topic` | ✅ | Short slug. Used in the briefing filename. |
| `summary` | recommended | LLM-curated; max 300 tokens recommended. |
| `recent_turns` | optional | Auto-trimmed to `include_recent_turns`. |
| `decisions` | optional | Free-form bullet points. |
| `artifacts` | optional | File paths or other references. |
| `return_condition` | optional | Default `user_request`. |
| `handover_reason` | optional | Logged in the briefing. |
| `project_root` | ✅ | Must be absolute. Used for the briefing file path. |
| `max_context_tokens` | optional | Default 3000. |
| `include_recent_turns` | optional | Default 5. |

---

## Known specialist profiles

The tool accepts only the following profile names. This is an explicit
allow-list (defence-in-depth): a typo in the profile name produces a clear
`ERROR` response, not a silent miss.

- `a0_software_orchestrator`
- `codebase_explorer`
- `implementation_engineer`
- `quality_reviewer`
- `release_auditor`
- `requirements_analyst`
- `runtime_devops_engineer`
- `security_data_engineer`
- `solution_architect`
- `ui_design_specialist`
- `test_debug_engineer`
- `hacker`

`frontend_designer` is **not** a known profile. Use `ui_design_specialist` instead for UI design tasks.

---

## Return value

The tool returns a JSON object with three top-level keys:

```json
{
  "status": "ok",
  "persona_marker": "[frontend designer]",
  "package": {
    "specialist": "frontend_designer",
    "topic": "landing-page-hero",
    "summary": "...",
    "briefing_file": "/abs/path/.a0proj/handover/frontend-designer-landing-page-hero-2026-06-05.md",
    "estimated_tokens": 2143,
    "max_context_tokens": 3000,
    "oversize_warning": false
  },
  "briefing": {
    "path": "/abs/path/.a0proj/handover/frontend-designer-landing-page-hero-2026-06-05.md",
    "existed_before": false,
    "newly_created": true,
    "size_bytes": 1789
  },
  "next_step": "Orchestrator: review the package, then call_subordinate(...)"
}
```

If the package exceeds `max_context_tokens`, a `WARNING:` line is appended
to the response so the orchestrator can decide whether to truncate.

---

## Errors

The tool never raises an unhandled exception. All error paths return a
`Response(message="ERROR: …", error=True)` so the orchestrator can decide
how to react.

Common error cases:

| Error | Cause |
|-------|-------|
| `specialist_profile is required` | missing or empty |
| `unknown specialist profile` | not in the allow-list |
| `topic is required` | missing or empty |
| `project_root is required` | missing or empty |
| `project_root must be absolute` | relative path |
| `max_context_tokens must be positive` | ≤ 0 |
| `failed to append briefing file` | OSError (permissions, disk full, …) |

---

## What the tool does NOT do (Phase 1 limits)

- ❌ Does **not** call `call_subordinate()`. The orchestrator is expected to
  do that in a follow-up reasoning step.
- ❌ Does **not** LLM-summarise the older turns. The orchestrator must pass a
  pre-computed `summary` argument.
- ❌ Does **not** update the `state_store`. A future phase will add a
  `state_store.snapshot()` call before the briefing is written.
- ❌ Does **not** modify the chat loop or any framework core.
- ❌ Does **not** expose a UI persona marker yet. Phase 3 will add the
  `🖌️ Designer` style marker to the chat output.

---

## Phase-2 plan (forward-looking)

- `request_full_history()` tool for specialists (stage 2).
- `call_subordinate()` wired into the orchestrator flow with persona marker.
- Loop guard: `max_handover_depth = 3` to prevent bouncing.
- Integration with `state_store.snapshot()` for crash safety.
- Add `frontend_designer` (and any other missing) profile to the allow-list.
- UI persona marker in the webui chat output.

---

## Related files

- Helper: `helpers/handover_protocol.py`
- Helper: `helpers/briefing_file.py`
- Tool: `tools/handover_to_specialist.py`
- Spike design doc: `/usr/workdir/handover-spike.md`
- Memory-protection rules: enforced inside `handover_protocol.py`
  (no mid-subagent compaction, no overwrite, briefing ≠ chat history).