feat: agent templates / forking (save good context, reuse later) #372

Summary

Agent templates (aka agent forking): when a session has a good context window — the agent is doing the right things, vibe is right, procedure is working — let the user save that pre-loaded text as a reusable template and start future conversations from it, without hand-authoring a skill from scratch.

Manual skills management (#331) is fine for deliberate playbooks. This is the complementary path: capture emergent good context as text and reuse it.

Product

Why (problem)

• A “good agent turn sequence” is often just the right pre-loaded text (constraints, examples, working decisions) — not a carefully designed skill file.
• Writing skills by hand is slow when the model already produced useful context in the session.
• Users want: “this session is working — freeze it and reuse.”

Vs skills vs personas

Templates should compose with skills and personas, not replace them. Ideal long-term: save-as-template → optional “promote to skill” once skills CRUD exists.

Scope notes (open design)

What exactly is snapshotted needs a product pick (document in plan later):

Hard requirements regardless of option:

• Size caps and honest overflow policy (ties to harness: show live context size from model usage (not client math) #327 context usage chrome).
• Redaction of secrets / tokens / sandbox paths that must not become standing injects.
• Tenancy-safe user-scoped storage (same class as skills/personas).
• No dual-chat; template picker is host Settings or harness chrome that still runs product turns in Wasm.

Constraints

Dependencies

Blocked by #548 (agent session architecture — model-context memory, compaction, viewport).

A template is a snapshot of a good context window. Today that window is lobotomized (tool runs omitted, 400-row / 3.5M-char fold, no working notes). Saving/forking it before A1–A4 would freeze crumbs, not the work. Tracked on agent session architecture (project 3), not the #408 session-object board (project 2).

Also needs the skills inject/attach surface (#331) so New-from-template reuses the same assembly path (no second mystery system prompt). Personas (#329) compose; they are not the hard block.

Also related:

• agent session architecture — model-context memory, compaction, and viewport #548 parent + agent memory: structured truncated tool_result on the wire (not Tool: crumbs) #549–spike: viewport hydrate — latest-page F5 (#924), slim local, scrollbar (A5 rebase) #553 (memory, budget, compaction, viewport)
• feat: user/agent skills library (attachable playbooks) #331 skills inject (reuse attach path)
• feat: user agent personas (AGENTS.md profiles) + New session inject #329 personas / New session inject
• harness: show live context size from model usage (not client math) #327 live context size (templates cost tokens; UI should show it)
• feat: built-in meta MCP — agent manages personas, skills, sandboxes #332 meta-MCP (later: manage templates too)

Acceptance (product-level)

• User can save a session (or selected window) as a named template.
• User can start a new session from a template with that content pre-loaded under documented caps.
• Templates are listed/manageable (rename/delete); tenancy-safe.
• Overflow / redaction policy documented and enforced.
• Docs: how templates differ from skills/personas; when to promote template → skill.
• Later / stretch: compact multiple templates (or windows) into one new template.

Non-goals (MVP)

• Public template marketplace / share graph
• Automatic “this session was good” scoring without user action
• Mid-session full transcript rewrite as a template (unless it falls out of compact design)
• Replacing skill authoring for deliberate playbooks

This is a product issue, not an implementation plan. Plan work after #548 A1–A4 (and #331 inject) are real enough to snapshot.

Peer harness notes

A template should snapshot the model-facing window (structured messages

• notes + skill catalog + compact checkpoint), not the 8 MiB display Blob
  and not today’s flattened 3.5M crumb.

Pi retainedTail + working notes (#550) + #549 tool results are the honest
“this session is working — freeze it.” Skill bodies stay referenced by slug
(#557), not inlined again.

Orrery (2026-08-15)

Snapshot the durable-spec + notes + skill slugs + retained tail, not the display Blob. A template is a warm prefix for a new session — it should be cache-shaped (#558), not an 8 MiB transcript fork.