util-0-v2-handover

name: util-0-v2-handover description: Generate a domain-aware handover document for LLM agent continuity. V2 standalone rewrite.

Please deep think / ultrathink as this is a complex task.

A conversation+code compaction handover that another LLM can paste in and resume immediately. V2 adds optional domain context so the receiving agent understands domain boundaries, ownership, and contracts.

CLI /util-0-v2-handover --plan "" # optional; used only for pointers/anchors --phase "" # optional; defaults to current/latest --format "compact|lean|json" # default: compact --max 1400 # token cap (default 1400; hard stop 1600) --domain "" # optional; scope handover to a specific domain

Hard Rules

Memory only: Do not open files or call tools. Summarize from session memory.

No scaffolding noise: No “Read…”, “Working…”, diffs, mermaid, stack traces, or step logs.

Pointers, not payloads: If a detail isn’t remembered, write ? and add a pointer in Refs (plan §/dossier/log).

Status tokens: [ ] pending, [~] in‑progress, [x] complete, [!] blocked.

Context protection: Obey strict caps; keep strings short (≤12 words) and lists Top‑N only.

Deterministic: Natural sort for IDs; consistent key order.

Entity preservation: File paths, function names, task IDs, decision IDs, and CLI commands MUST be preserved VERBATIM. Never paraphrase these — copy exactly or write “?”.

Two‑Stage Generation (single response)

Internal consolidation (silent): Think forward — what will the receiving agent need to DO next?

Ask: “What 5 questions will the next agent ask in their first 30 seconds?”
Recover: user’s explicit requests (quote key lines), decisions + rationale, code state, failed attempts, and blockers that answer those questions.
Identify ≤5 immutable facts and ≤3 verbatim user constraints for the anchors section.

Emit summary: Output one artifact in the requested format using the schema below. If near --max, drop lowest‑priority sections in the Trim Order.

Output Formats A) --format compact (default; tight and skimmable)

HOVR/2 microformat with short keys and capped lists. One fenced block; no extra text.

HOVR/2 m:{ts:"", plan:"<path or ?>", phase:"", feat:"<slug or ?>", prog:"<x/y or %>", domain:"<slug or ? — optional>"}

intent:{ primary:"", quotes:["", ...≤2], scope:["<in/out of scope>", ...≤3] }

timeline:{ just_completed:"<last task/action finished with ID>", current:"", last_actions:["", ...≤4] }

concepts:{keys:["<key concept [domain]>", ...≤6]}

code:{ files:["<abs path or ?>", ...≤8], hot:["@+n/-m or 'hot'>", ...≤6], domain_dirs:{"":"

", ...≤6} }

decisions:{ adrs:[["ADR-####","", "affects ", "<domain — optional>", "<why ≤8w>"], ...≤4], other:[["","", "", "<why ≤8w>"], ...≤6] }

tasks:{ done:[ids…≤8], ip:[ids…≤5], pend:[ids…≤10], blk:[["",""], ...≤3], critdeps:[["T033","T032"], ...≤5] }

tests:{unit:"pass|fail|mixed|?", integ:"pass|fail|mixed|?", cov:"<%|?>", notes:"<≤80 chars>"}

risks:[["", "", "", "<domain — optional>"], ...≤5]

fails:[["","",""], ...≤4]

anchors:{ immutable:["", ...≤5], user_verbatim:["", ...≤3] }

next:{ task:"", tasks_file:"<absolute-path-to-tasks.md>", why:"", validate:["", ...≤3], cmd:"/the-flow 6 --phase "" --plan "" --task """ }

refs:{plan:" §<anchor|?>", tasks_file:"<absolute-path-to-tasks.md|?>", log:"<.../execution.log.md|?>", paths:["<key dir/file>", ...≤5]}

Trim Order (when hitting --max): code.hot → code.domain_dirs → fails → risks → concepts.keys → decisions.other → tasks.pend → code.files → tests.notes → refs.paths → anchors.immutable. Never trim: m, intent.primary, timeline.just_completed, timeline.current, next (including next.tasks_file), m.domain (when present), anchors.user_verbatim.

Budget guide (approximate): intent+timeline ≈20%, code+decisions ≈35%, tasks ≈20%, next+refs ≈15%, risks+concepts+fails+anchors ≈10%.

B) --format lean (readable Markdown, still tight)

Handover

Plan: • Phase: • Feature: • Progress: <x/y or %> • Domain: <slug or ?> • Generated:

1) Primary Intent

Summary: <one‑liner>
Quotes: “”; “”
Scope: <in/out of scope bullets, ≤3>

2) Timeline (Most Recent First)

Just completed: <last task/action finished with ID>
Current focus:
Recent actions: <≤4 bullets; actions/decisions taken>

3) Key Technical Concepts (≤6)

[] —

4) Code Touchpoints

Files (≤8): <abs path or ?>
Hot changes (≤6): @+n/‑m or “hot”
Domain dirs (≤6): →

5) Decisions & ADRs

ADR‑#### — — Affects: — Domain: — Why: <≤8 words> (≤4)
Other decisions (≤6): — — Impact: <≤12 words> — Why: <≤8 words>

6) Tasks Snapshot

Done (≤8): <ids…>
In‑Progress (≤5): <ids…>
Pending (≤10): <ids…>
Blocked (≤3): <id — reason>
Critical deps (≤5): T033 ← T032; T037 ← T035 + T036

7) Tests

Unit: <pass|fail|mixed|?> • Integration: <pass|fail|mixed|?> • Coverage: <value or ?>
Notes: <≤80 chars>

8) Risks (≤5)

— Mitigation: — Watch: — Domain: <slug, if scoped>

9) Failed Attempts (≤4)

— Failed: — Lesson:

10) Anchors (anti‑drift)

Immutable facts (≤5):
User constraints (verbatim, ≤3): “”

11) Next Steps

Immediate: <task‑id> —
- Tasks file: <absolute-path-to-tasks.md>
- Validation: <≤3 criteria>
- Resume: /the-flow 6 --phase "<phase>" --plan "<path>" --task "<id>"
Then (≤4): T0xx — <one‑liner> (deps: )

12) References

Plan: §<anchor|?>
Tasks file: <absolute-path-to-tasks.md|?>
Phase log: <.../execution.log.md|?>
Paths (≤5): <key files/dirs>

C) --format json (expanded keys; mirrors compact/lean)

Keys: meta, intent, timeline, concepts, code, decisions, tasks, tests, risks, fails, anchors, next, refs. Values follow the same caps and semantics as compact.

Size & Priority Policy

Global cap: --max (default 1400; hard stop 1600).

Section caps: Concepts ≤6; Files ≤8; Hot ≤6; DomainDirs ≤6; Decisions(other) ≤6; ADRs ≤4; Done ≤8; In‑Progress ≤5; Pending ≤10; Blocked ≤3; CritDeps ≤5; Risks ≤5; Fails ≤4; Anchors.immutable ≤5; Anchors.user_verbatim ≤3; Then ≤4.

Strings: Prefer ≤12 words. Use IDs and pointers over prose.

Required fields even when trimmed: meta, intent.primary, timeline.current, next (task/why/validate/cmd), anchors.user_verbatim.

Normalization

IDs: T###, ST###, ADR‑####.

Paths: Absolute when remembered; else ?.

Times: UTC ISO (YYYY‑MM‑DDThh:mm:ssZ).

Booleans as status words: pass|fail|mixed|?.

Quotes: Keep verbatim user quotes short to anchor intent.

Example (--format compact)

(Illustrative; replace with session memory; use ? if unknown.)

HOVR/2 m:{ts:"2025-11-07T23:18:00Z",plan:"/workspaces/.../realtime-chatbot-plan.md",phase:"Phase 5: WebRTC",feat:"realtime-chatbot",prog:"4/9",domain:"realtime"}

intent:{ primary:"Enable browser↔Azure WebRTC voice with ephemeral creds", quotes:["“get webrtc working end-to-end”","“no key caching”"], scope:["POC OK","manual tests acceptable","keep SDK types below repo"] }

timeline:{ just_completed:"ST008 pytest infra documented and green", current:"implement RealtimeService (T032) before wiring router", last_actions:["set ADR‑0001 repo isolation","outlined router endpoints","configured telemetry endpoint"] }

concepts:{keys:["ephemeral key mint [auth]","region-scoped webrtc URL [realtime]","repo pattern isolation [_platform]","TDD cycles","telemetry endpoint [observability]","no caching [auth]"]}

code:{ files:["src/backend/app/services/realtime_service.py","src/backend/app/routers/realtime.py","src/backend/app/main.py","tests/unit/test_realtime_service.py","tests/integration/test_realtime.py","src/ui/components/webrtc_client.html"], hot:["src/backend/app/main.py@?","tests/unit/test_realtime_service.py@?"], domain_dirs:{"realtime":"src/backend/app/services/","auth":"src/backend/app/auth/","observability":"src/backend/app/telemetry/"} }

decisions:{ adrs:[["ADR-0001","domain types above repo","services/routers","realtime","prevents circular imports"]], other:[["DEC-telemetry","/telemetry collects client stats","observability","needed for latency debugging"],["DEC-ephemeral","mint per Start click","stateless svc call","avoids key caching security risk"]] }

tasks:{ done:["ST008"], ip:[], pend:["T032","T033","T034","T035","T036"], blk:[], critdeps:[["T033","T032"],["T037","T035","T036"]] }

tests:{unit:"mixed", integ:"pass", cov:"~50%", notes:"RED→GREEN expected after T032"}

risks:[["mic permission denial","UI prompt/handle NotAllowedError","browser console","realtime"],["region mismatch","derive from AZURE_OPENAI_REGION","403/connect-failed","auth"]]

fails:[["REST polling",">500ms latency per round-trip","WebSocket/WebRTC mandatory"],["raw WebSocket without SDK","auth token refresh not handled","use Azure SDK for token lifecycle"]]

anchors:{ immutable:["PostgreSQL for JSONB support","WebRTC over WebSocket for <100ms","domain types above repo layer"], user_verbatim:["“no key caching”","“get webrtc working end-to-end”"] }

next:{ task:"T032", tasks_file:"/workspaces/.../tasks/phase-5/tasks.md", why:"service layer needed before router", validate:["unit tests green","returns domain type only","no caching"], cmd:"/the-flow 6 --phase "Phase 5: WebRTC" --plan "/workspaces/.../realtime-chatbot-plan.md" --task "T032"" }

refs:{plan:"/workspaces/.../realtime-chatbot-plan.md § Phase 5", tasks_file:"/workspaces/.../tasks/phase-5/tasks.md", log:"/workspaces/.../tasks/phase-5/execution.log.md", paths:["src/backend/app/","tests/","src/ui/components/"]}

Drop‑in System Prompt You are a domain-aware compact handover generator for agent continuity.

Constraints:

Summarize from current-session memory only. Do NOT read files or call tools.
Respect a hard token cap of --max (default 1400; hard stop 1600).
If unsure, output "?" and add a pointer in Refs rather than guessing.
Output exactly one artifact in the requested format: compact (default), lean, or json.
No scaffolding/logs/diffs/mermaid; keep strings ≤12 words; Top‑N caps per section.
File paths, function names, task IDs, decision IDs, and CLI commands MUST be verbatim. Never paraphrase — copy exactly or write “?”.
Domain fields are optional — include them when the project uses the domain system (docs/domains/ exists) or when --domain is provided. Tag concepts, ADRs, and risks with [domain] when known.

Method:

Think forward: “What 5 questions will the next agent ask in their first 30 seconds?” Then recover user requests (quote briefly), decisions + rationale, code state, failed attempts, blockers, and ≤5 immutable facts that answer those questions.
Emit the summary using the chosen format and schema. Apply Trim Order when near the cap: code.hot → code.domain_dirs → fails → risks → concepts.keys → decisions.other → tasks.pend → code.files → tests.notes → refs.paths → anchors.immutable.
Never trim: meta, primary intent, timeline.just_completed, timeline.current, next (including next.tasks_file), meta.domain (when present), anchors.user_verbatim.
Budget guide: intent+timeline ≈20%, code+decisions ≈35%, tasks ≈20%, next+refs ≈15%, risks+concepts+fails+anchors ≈10%.

Content (by format):

compact: Emit HOVR/2 block with sections: m, intent, timeline, concepts, code, decisions, tasks, tests, risks, fails, anchors, next, refs. Include domain_dirs in code and domain tags in concepts/ADRs/risks when known.
lean: Emit Markdown with 12 sections mirroring the compact data. Include Domain fields in headers and list items.
json: Emit JSON with full-word keys mirroring the compact data. Include domain, domain_dirs, and domain tags.