session-flow/workflow: end-of-phase continuation router (continue / clear / handoff / subagent / compact)

[kyle-sexton]

Goal

session-flow:workflow already answers "what stage comes next"; add the missing router for "which continuation mechanism" at end of phase. Inspired by Matt Pocock's decision tree (x.com/mattpocockuk/status/2079879414297330146, 2026-07-22) — adapted, not copied; the sweep audit tightened what that must mean (below).

Outcome set — derive, don't inherit (sweep amendment 2026-07-26)

The first draft of this issue locked Pocock's five outcomes in his order — inheritance, not the promised re-derivation. Before implementation:

1. Derive the outcome set from the continuation mechanisms session-flow actually installs — including lanes his tree does not model: clean-stop (machine going away), reconcile/orient, background delegation, plus the built-ins (/clear, /compact).
2. Diff against his five; keep what survives on merit; add what our topology has and his lacks.
3. State the purpose behind each retained ordering edge — e.g. why disposable-context check precedes handoff (cheapest exit first), why compact is last (a model-written lossy summary produced at the least-intelligent point of the session — evidence now in context-guard: zone-crossing hooks (advisory/enforcing) + window-class token bands #1475's research); drop any edge whose only support is that the source diagram drew it.

Draft sequence to start from (zone-informed via the context-guard seam, presence-gated, conservative on unknown/absent):

1. Enough smart zone left, or task simple enough for degraded context? → continue in session.
2. Session context disposable? → /clear — cheapest path when available.
3. Work passes to another agent/directory/colleague, or context must survive? → session-flow:handoff.
4. Work can proceed without human input? → background delegation (session-flow:continue-in-background on explicit request / subagent). Source's node 4 has inverted header/subtitle polarity (verified against 2x crop); ours states the test positively.
5. Machine going away / day ending? → session-flow:clean-stop.
6. Fallthrough: /compact with a steering hint — phase boundary only; point at handoff SKILL.md's "Fork beats compaction when the window is deep" section (heading anchor, not line numbers) rather than restating it.

Handoff-relay orchestration convention (include as guidance)

Worker approaching zone boundary → writes its own handoff file → returns the PATH only; parent spawns a successor briefed "read this file, continue" — parent never reads the handoff itself. Converges independently with mattpocock/skills#647 (generic spawn skill). Candidate carrier for relay policy into workers: SubagentStart hook injection (see #1475's event survey / #1478). Cross-reference session-flow:orchestrate; its audit is #1479.

Constraints

• Cross-plugin references presence-gated with documented fallback (PLUGIN-PHILOSOPHY.md); router degrades gracefully when context-guard absent (no zone data → judgment-based questions still work).
• Zone vocabulary and inline floor values, if inlined, follow the reader contract's byte-identity + drift-check rule.
• Pointer-not-copy: compact-vs-clear tradeoff prose exists in handoff SKILL.md and playbooks; the router routes, it does not restate.

Acceptance criteria

• Invoking workflow at a phase end yields a mechanism recommendation with rationale, zone-informed when data present, conservative when not.
• Every terminal in the derived outcome set is reachable and points at its owning skill (or built-in) rather than duplicating its guidance.
• Each ordering edge carries a stated purpose in the skill body.
• Works with context-guard absent.

Related

• Companion: context-guard: zone-crossing hooks (advisory/enforcing) + window-class token bands #1475 (hook's injected message points here; likely same PR).

[kyle-sexton]

This was generated by AI during triage.

Triage

Classification

• Type: Feature (new router capability, not present today)
• Priority: priority: medium (left as-is — no blocking dependency or external deadline stated; assessed-default tier)
• Work class: C3 — scoped change (work-class: scoped). Adds a new decision router to an existing skill (session-flow:workflow) with a presence-gated cross-plugin reference to context-guard; blast radius is bounded to that skill's end-of-phase surface and the companion hook's injected pointer, tests/evals exist to gate it.

Redundancy / rejected-concept check

• No docs/out-of-scope/ ledger exists in this repo — skipped.
• session-flow:workflow's SKILL.md currently answers "what stage comes next" (stage sequencing) but has no mechanism for "which continuation mechanism" (continue / clear / handoff / subagent / compact) at phase end — confirmed by reading the skill body; no existing router found. Not a duplicate.

Cluster note

• This issue and context-guard: zone-crossing hooks (advisory/enforcing) + window-class token bands #1475 are explicit companions ("files together; likely one PR"), but each carries its own already-locked decisions from the 2026-07-25/26 interview (the router shape here, the hook/band design there) rather than sharing one open decision — so this is triaged as its own human-gated item, not linked as a cluster member blocked on a shared undecided question. Implementation sequencing between the two is an implementer concern, not a triage-time blocker.

Routing: human-gated

Per plugins/autonomy/reference/guardrails/admission-policy.md, work class C3 is human-gated under the shipped defaults (no repo-local security binding promotes that cell) regardless of how fully the router shape is already locked in the issue body.

Agent Brief

Type: Feature
Summary: Add an end-of-phase continuation router to session-flow:workflow that recommends a continuation mechanism (continue in session / /clear / session-flow:handoff / background delegation / /compact) as a decision sequence, zone-informed when context-guard's data seam is present, degrading gracefully to judgment-based questions when absent.

Current behavior:
session-flow:workflow recommends the next development stage (explore → research → plan → implement → test → review → verify → retro). It has no router for which continuation mechanism to use once a phase ends.

Desired behavior:
Invoking the workflow skill at a phase boundary walks the five-step decision sequence described in the issue body (smart-zone-remaining check → disposable-context check → handoff-worthy check → AFK-delegable check → compact fallback) and yields one mechanism recommendation with rationale. Zone-informed when context-guard's zone data is present (fail-open to conservative on unknown/absent per the locked decision); the router still functions with plain judgment-based questions when context-guard is not installed. Each of the five terminal outcomes points at the owning skill or built-in command rather than restating its guidance (pointer, not copy) — including the handoff-relay orchestration convention (worker writes its own handoff, returns only the path; parent never reads it).

Key interfaces:

• session-flow:workflow's stage-detection/recommendation surface — the router hooks in at phase-boundary detection
• context-guard's zone data seam — presence-gated read, documented fallback per PLUGIN-PHILOSOPHY.md
• Zone vocabulary and any inlined floor values — must follow the reader contract's byte-identity + drift-check rule (see companion context-guard: zone-crossing hooks (advisory/enforcing) + window-class token bands #1475)

Acceptance criteria:

• Invoking the workflow skill at a phase end yields a mechanism recommendation with rationale, zone-informed when data is present, conservative when not
• All five outcomes (continue / clear / handoff / subagent / compact) are reachable
• Each terminal points at its owning skill/command rather than duplicating guidance
• Works correctly with context-guard absent (no zone data → judgment-based questions still work)

Out of scope:

• Restating the compact-vs-clear tradeoff prose that already exists in session-flow:handoff's SKILL.md and playbooks — point at it
• session-flow:orchestrate imperative changes (audited separately per the issue's own note)
• The context-guard hook implementation itself (companion context-guard: zone-crossing hooks (advisory/enforcing) + window-class token bands #1475, likely same PR but a distinct brief)

Why human-gated: C3 work class per admission policy — new cross-plugin-referencing router behavior with real (if presence-gated) coupling to context-guard, shipped as a behavioral default other sessions will rely on.