User Asides (parallel work tracks)

Consumer guide

Start with Parallel Work Tracks for the full Grok Build + worktree + aside mental model. This page is the MCP/state reference.

User asides are parallel work tracks you declare to the lead agent — like git worktrees for agent work. They are not AsideContext (internal orchestrator observation registry).

Concepts

Term	Meaning
User aside	Scoped goal with its own plan, branch/worktree metadata, a.* todos
AsideContext	In-memory MCP subcontext (spawnAside) — implementation detail

State layout

.xray/state/
  lead-dev-plan.json          # main thread
  asides/
    suit-nft.json             # aside definition + plan
    _active.json              # which aside receives spawns

Todo ids are namespaced: suit-nft.a.1.1 (not global a.1.1).

MCP usage (no new tools)

Intake

xray-orchestrator → analyze-complexity:

{
  "userAsideId": "suit-nft",
  "userAsideTitle": "Suit-certified NFT mint",
  "worktree": "../suit-nft-worktree",
  "branch": "feat/aside-suit-nft",
  "tasks": [
    { "description": "Groover registration proof", "type": "research" }
  ]
}

Activate existing aside

orchestrate-task:

{ "description": "work aside", "userAsideId": "suit-nft" }

Resume main thread

{ "description": "resume main", "clearActiveAside": true }

Spawn routing

When an aside is active, PreToolUse spawn gate matches todos on {asideId}.a.*. Session-boot exposes activeAside, asideWorktree, asideTrapSignals, asideConferRecommended.

Config

features.json → multi_agent_orchestration.user_asides.enabled (default true).

Accepted limitations

Limitation	Rationale
Worktree cwd enforced on spawn	PreToolUse denies aside spawns without cwd / working_directory matching aside.worktree when project root ≠ worktree. Lead must pass cwd on Task/spawn_subagent.
Single active aside per workspace	_active.json is workspace-scoped; one parallel track at a time. Use clearActiveAside before switching.
Unscoped activation	If setActiveAsideId runs without sessionId, any session may route to that aside until cleared (discouraged; always pass sessionId on intake).
Synthesis writes still blocked	Aside spawns bypass main synthesis checkpoint; main-track writes remain blocked until synthesis clears.

Related

• Parallel Work Tracks — end-user guide (Grok Build + worktrees)
• AsideContext — internal orchestrator subcontexts (different concept)
• Features since 3.1