# Groove Team: Delegate/Yield Tag Extraction from Planner Telemetry

## Context

The Hummingbird chassis is being trained on Groove planner telemetry data to learn orchestration — decomposing tasks, sequencing work, dispatching to specialists. The chassis already learns this well from the existing ReAct tag format (thought, action, observation, resolution).

We're adding two new coordination tags to the protocol:

| Tag | Purpose | Example |
|-----|---------|---------|
| `<delegate>` | "This needs a different specialist — re-route" | `<delegate>Create a PostgreSQL schema for user auth with sessions table</delegate>` |
| `<yield>` | "My part is done, here's my artifact for the next agent" | `<yield path="phase_01/api.py">Flask REST API with auth endpoints</yield>` |

The delegation behavior already exists in Groove planner sessions — it just isn't captured with these tags. Every time a planner agent reads `recommended-team.json` and dispatches work to a specialist agent, that's a delegation. Every time an agent produces an artifact that the next agent consumes, that's a yield.

## What We Need

### 1. Retroactive Tagging of Existing Planner Telemetry

Go through existing planner session trajectory_logs and identify two patterns:

**Pattern A — Delegation (dispatch to specialist):**

Look for sequences where the planner:
1. Reads `recommended-team.json` or `AGENTS_REGISTRY.md`
2. Reasons about which specialist to use (in a thought step)
3. Dispatches work to a specialist agent

The dispatch moment should become a `<delegate>` step. The content is the rewritten task — what the planner told the specialist to do.

Before (current format):
```json
{"step": 4, "type": "thought", "content": "This needs a backend specialist to implement the API endpoints..."}
{"step": 5, "type": "action", "tool": "Agent", "content": "Dispatch to backend-2: Implement REST endpoints for user authentication with JWT tokens and session management"}
{"step": 6, "type": "observation", "content": "Agent dispatched to backend-2"}
```

After (with delegate tag):
```json
{"step": 4, "type": "thought", "content": "This needs a backend specialist to implement the API endpoints..."}
{"step": 5, "type": "delegate", "content": "Implement REST endpoints for user authentication with JWT tokens and session management"}
```

Key rules:
- The delegate content is the TASK, not "dispatch to backend-2." The delegating agent doesn't choose the target — the router does.
- Strip any agent ID references (backend-2, fullstack-7, etc.) from the content — just the task description.
- The thought step before the delegate should contain the reasoning about WHY this needs a different specialist.
- A delegate is a terminal step — it replaces resolution. Nothing comes after it in that firing.

**Pattern B — Yield (artifact handoff):**

Look for sequences where an agent:
1. Produces a file or artifact (Write, Edit)
2. That artifact is subsequently read by a different agent in the same pipeline

The artifact production should become a `<yield>` step.

Before (current format):
```json
{"step": 7, "type": "action", "tool": "Write", "content": "Writing api.py with Flask endpoints..."}
{"step": 8, "type": "observation", "content": "File written successfully"}
{"step": 9, "type": "resolution", "content": "API endpoints implemented. The backend agent can now build on this."}
```

After (with yield tag):
```json
{"step": 7, "type": "action", "tool": "Write", "content": "Writing api.py with Flask endpoints..."}
{"step": 8, "type": "observation", "content": "File written successfully"}
{"step": 9, "type": "yield", "content": "Flask REST API with auth endpoints", "path": "api.py"}
```

Key rules:
- The yield content is a SHORT summary (~10-20 tokens) of what the artifact is — enough for the next agent's prompt.
- The path field is the file path of the artifact.
- A yield is a terminal step — it replaces resolution. The agent's work is done; the next agent picks up.
- Only tag as yield if another agent actually consumed the artifact. If the agent resolved directly to the user, keep it as resolution.

### 2. Step Format

Both new step types follow the same shape as existing steps:

```json
{
  "step": 5,
  "type": "delegate",
  "content": "The rewritten task for the next specialist",
  "timestamp": 1777412000.5,
  "token_count": 15
}
```

```json
{
  "step": 9,
  "type": "yield",
  "content": "Short artifact summary",
  "path": "phase_01/output_file.py",
  "timestamp": 1777412001.2,
  "token_count": 8
}
```

They flow through the same `_processStep -> EnvelopeBuilder.addStep -> envelope -> Central Command` path as all other steps.

### 3. Future Telemetry Capture

Once nano agents are running and producing `<delegate>` and `<yield>` tags in their output, the chassis parser should emit these as step objects into the trajectory capture:

- When parser sees `<delegate>task</delegate>` → emit `{"type": "delegate", "content": "task"}`
- When parser sees `<yield path="...">summary</yield>` → emit `{"type": "yield", "content": "summary", "path": "..."}`

Same as how the current parser emits thought/action/observation/resolution steps.

### 4. What NOT to Do

- Do NOT add empty delegate/yield steps to sessions where they don't occur. If a session resolves normally, it ends with resolution. The absence of delegate/yield is correct.
- Do NOT change the thought or resolution content. Only add/modify the terminal step (replacing resolution with delegate or yield where the pattern matches).
- Do NOT invent delegation where it didn't happen. Only tag real dispatch-to-specialist moments.

### 5. Output

Deliver the retroactively tagged sessions as:
- Same JSONL format as current planner telemetry
- Same file location (ingestion/ directory)
- Filename convention: `2026-05-09-planner-delegated-{hash}.jsonl` or similar

We'll run these through the standard `build_production_data.py` pipeline.

### 6. Estimated Yield

From the 139 organic planner sessions currently in the training set:
- Most sessions involve at least one specialist dispatch → expect 80-120 delegate examples
- Many multi-agent sessions involve artifact handoffs → expect 40-80 yield examples

This organic data is highest quality — real frontier model orchestration decisions. It sets the standard that our synthetic generation will match.
