docs: golden-agent adoption plan for the unified harness surface

[declan-scale]

The capstone plan for the unified harness surface workstream: how golden_agent (in agentex-agents) adopts the SDK taps + UnifiedEmitter, retiring its bespoke HarnessEvent/AgentexStreamAdapter + per-provider parsers while keeping all SGP-coupled orchestration (sandbox pool, secrets, MCP reauth, data-plane override).

Phased: prereqs (pin SDK) → claude-code → codex → delete the harness layer → optional in-process OpenAI-Agents. Implementation lands in agentex-agents, after this SDK stack merges + releases.

🤖 Generated with Claude Code

Greptile Summary

This PR adds a planning document for migrating the golden_agent in agentex-agents from its bespoke HarnessEvent/AgentexStreamAdapter layer to the SDK's unified harness surface (convert_<harness>_to_agentex_events taps + <Harness>Turn + UnifiedEmitter), while leaving all SGP-coupled concerns (sandbox pool, secrets, MCP reauth, data-plane override) untouched.

• The plan is phased (Phase 0 prereqs → Phase 1 claude-code → Phase 2 codex → Phase 3 delete bespoke layer → Phase 4 optional OpenAI-Agents), with each phase independently shippable and reversible until Phase 3.
• The timestamp and wire-shape behavior differences between the new SDK path and the prior dispenser are explicitly called out in the "Determinism / timestamps" and "Risks" sections, giving implementers the right caveats before they write a line of code.

Confidence Score: 5/5

Documentation-only change with no runtime code; safe to merge.

This is a planning document with no executable code. All three prior review concerns (phase label alignment, timestamp delta from old dispenser, OpenAI API surface) have been addressed in the current revision. The one remaining gap — HarnessTurn appearing as an undefined symbol alongside OpenAITurn in Phase 4 — is a minor naming inconsistency that would not block an implementer from understanding the intent.

No files require special attention; the single changed file is a markdown planning document.

Important Files Changed

Filename

Overview

docs/superpowers/plans/2026-06-22-golden-agent-unified-surface-adoption.md

New planning document describing a phased migration of golden_agent's bespoke harness layer to the SDK unified surface; well-structured with a clear disposition table, pseudocode target flow, and explicit risks section. One undefined symbol (HarnessTurn) in the Phase 4 description; all previous review concerns (phase label, timestamp delta, OpenAI API surface) have been addressed in the current revision.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    P0[Phase 0 — Prereqs\nMerge + release SDK stack\nPin scale-agentex version\nCommit uv.lock]
    P1[Phase 1 — claude-code\nKeep ClaudeProvider sandbox/spawn\nReplace _StreamJsonProcessor + HarnessEvent\nClaudeCodeTurn + UnifiedEmitter.auto_send_turn\nDelete _StreamJsonProcessor]
    P2[Phase 2 — codex\nSame pattern with CodexTurn\nDelete _CodexEventProcessor]
    P3[Phase 3 — retire bespoke harness\nDelete harness/events.py\nDelete harness/adapter.py\nShrink/delete harness/protocol.py\nSimplify harness/activity.py]
    P4[Phase 4 — optional OpenAI-Agents\nAdopt convert_openai_to_agentex_events\nOpenAITurn pending openai migration PR\nTrickiest — deferred]

    KEEP[(Keep unchanged\nSandbox pool/setup\nSecrets/MCP reauth\nData-plane override\nCapabilities/workflow/cron)]

    P0 --> P1
    P1 --> P2
    P2 --> P3
    P3 -.->|optional, later| P4
    P1 & P2 & P3 & P4 --- KEEP

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    P0[Phase 0 — Prereqs\nMerge + release SDK stack\nPin scale-agentex version\nCommit uv.lock]
    P1[Phase 1 — claude-code\nKeep ClaudeProvider sandbox/spawn\nReplace _StreamJsonProcessor + HarnessEvent\nClaudeCodeTurn + UnifiedEmitter.auto_send_turn\nDelete _StreamJsonProcessor]
    P2[Phase 2 — codex\nSame pattern with CodexTurn\nDelete _CodexEventProcessor]
    P3[Phase 3 — retire bespoke harness\nDelete harness/events.py\nDelete harness/adapter.py\nShrink/delete harness/protocol.py\nSimplify harness/activity.py]
    P4[Phase 4 — optional OpenAI-Agents\nAdopt convert_openai_to_agentex_events\nOpenAITurn pending openai migration PR\nTrickiest — deferred]

    KEEP[(Keep unchanged\nSandbox pool/setup\nSecrets/MCP reauth\nData-plane override\nCapabilities/workflow/cron)]

    P0 --> P1
    P1 --> P2
    P2 --> P3
    P3 -.->|optional, later| P4
    P1 & P2 & P3 & P4 --- KEEP

Loading

_{Reviews (8): Last reviewed commit: "docs: correct timestamp + OpenAI-tap cla..." | Re-trigger Greptile}

[danielmillerp]

hmm can we not put this under superpowers? if it is worthy of doc maybe in notion? or in https://agentex.sgp.scale.com/docs