| name | session-orchestration |
| description | Protocol for running work through parent/child agent sessions (e.g., the GitHub Copilot app's session tree, or any orchestrator dispatching cloud-agent runs). Use this whenever a session spawns or reports to another session, when starting work on a Task issue in a new session, when writing a completion/blocked/failed report, or when deciding what belongs in plan.md versus GitHub. |
Session Orchestration
Session trees and inter-session messages are powerful but app-local: a
cloud agent, a teammate, another machine, or you-next-week cannot see them.
GitHub is the only shared memory. Every rule below exists to keep the durable
record on GitHub while using sessions for speed.
Mapping (the 1:1:1:1 rule)
| Plan object | Session object | Workspace object |
|---|
| Epic issue | Parent (orchestrator) session | — |
| Task issue | One child session | One worktree + branch task/<n>-<slug> (or accepted tool-prefixed variant) + one PR |
One Task issue per child session — never batch several issues into one
session (reports become unattributable) and never split one issue across
sessions without replanning first. Use a separate worktree per concurrent
child so parallel sessions cannot write to the same checkout.
Child session protocol
Start ritual (do this before touching any file):
gh issue view <n> — read the full brief: Objective, Context & references,
Acceptance criteria, Out of scope, File ownership, Verification, Routing.- Open every referenced agreement (
REQ-###, ADR links). If a reference is
missing or contradicts the issue, stop and apply the Ambiguity rule
(AGENTS.md §6) — do not fill gaps with guesses.
- Write in the worktree root: restate the acceptance criteria, the
ownership paths, the verification commands, and your step plan.
is a — convenient, disposable, never authoritative, and
never a substitute for updating the issue. Do not commit it
(add to if needed).
