stack/docs/plans/2026-09-07_agent-context-templates-and-migration.md

Agent context, templates, and staged migration

Plan ID: ACT-1 Date: 2026-09-07 Recorder: Codex, at Jason's request Status: owner decisions captured; execution sequence proposed; runtime migration deferred Acceptance owner: Jason Coordinator, implementers, and independent reviewers: unassigned

Purpose and authority

/home/jwoltje/src/mosaic-stack-dev-test is the next-generation development leg of /mnt/storage/src/mosaic-stack, being rewritten from the ground up to replace that codebase. Earlier descriptions of this repository as only a standalone POC do not fully describe its intended destination.

Jason requested a durable shared plan after agreeing to the context-file responsibilities, personality improvements, template approach, and behavioral evaluation described below. This request authorizes recording the plan. It does not activate the implementation tasks or assign work to existing agents.

The current demo path must remain usable until Jason verifies it and the transition is coordinated. Darkwing, Rocko, and Filbert have ongoing tmux work; this plan must not change their sessions, launch inputs, assignments, or frozen review candidates. Broad codebase organization for scaling comes AFTER demo validation. Do not implement a monorepo move as preliminary cleanup.

At capture, CURRENT.md records a pending inspector correction and independent review before owner demo acceptance. Read that live record on every handoff; this document is not a competing next-action queue. Checkout HEAD was 9a5fbdbda74b16adf488fe28138b2ba69ea5e669, with substantial uncommitted work. That SHA alone does not identify the working files or an accepted demo baseline.

Agreed owner decisions

ID	Decision
D1	Each instruction file has a defined responsibility; avoid duplicating personality, governance, procedures, and runtime facts across layers.
D2	Agent personality should produce concrete behavior: direct answers, evidence-backed recommendations, early challenges to flawed assumptions, useful brevity, and natural optional humor. Confidence must not erase uncertainty.
D3	The agent's SOUL.md is the ONLY SOUL injected. Each agent has one canonical SOUL file. No shared default SOUL fallback or personality layering in the target system.
D4	System bootstrap and agent bootstrap use a SOUL template to initialize each agent's own file. Templates also create appropriate agent-specific and deployed versions of other context files/contracts.
D5	docs/reference/templates/ was imported whole-cloth as an example. It is reference material to adapt, not an approved deployment source. Existing contracts/* are initial-session boilerplate; their eventual placement needs incremental treatment.
D6	Evaluate behavior using test agents; Darkwing, Filbert, Heffer, and Rocko are available candidates. Their active sessions must be preserved.
D7	Preserve the existing option through Jason's demo verification and a properly coordinated migration.
D8	Organize for a scalable monorepo after demo validation; avoid premature source moves.
D9	Annex adopted concepts as Mosaic documentation in docs/concepts; remove upstream runtime nomenclature rather than retaining foreign product instructions. Supporting source lineage and required license attribution remain in docs/reference/concepts.

Proposed lifecycle details requiring design/review: templates initialize instances without silently overwriting later edits; template updates are explicit migrations; launch snapshots preserve historical bytes without becoming editable canonical SOULs. These details implement the ownership intent and must be reconciled with the existing foundation contracts before runtime changes.

File responsibilities

Resource	Intended responsibility	Must not become
CONSTITUTION.md	Shared boundaries, principles, authority relationships	Agent personality or a substitute for runtime permission enforcement
STANDARDS.md	Quality expectations and evidence requirements	A startup-marker-only contract or repeated repository procedures
Agent SOUL.md	Voice, temperament, judgment, and interaction style	A mission, capability grant, operational history, or second workflow manual
AGENTS.md	Repository procedures and working conventions	A universal worker prompt injected into every scope regardless of authority
USER.md / scoped user context	Relevant authorized preferences and personal context	Automatic distribution of the whole user profile to every agent
Runtime launch context	Actual identity, workspace, tools, skills, session semantics	Unverified capability claims or permanent persona instructions
Template sources	Reviewed defaults and bootstrap inputs	Live runtime fallbacks or competing editable agent identities
Execution snapshots	Evidence of exactly what an execution loaded	A second canonical configuration source

Final paths, packaging, and update authority are intentionally unresolved. File names and Markdown section order alone do not enforce precedence or security.

Current behavior to preserve and then migrate

These are source observations from the preceding groundwork, not proof of full runtime conformance. Reinspect the relevant files before preparing a candidate.

• scripts/agent.sh defaults to the existing container lifecycle. Explicit leading --host-dev delegates to scripts/agent-host-dev.sh.
• Container context comes from src/load-contracts.sh: image-baked governance, a default contract SOUL or a seat override, optional identity, live user Markdown, and mission context. The current fallback conflicts with D3 and needs a deliberate migration, not immediate removal.
• The native helper loads the selected agent SOUL, repository governance, deployment USER.md, repository AGENTS.md, and agent CONTEXT.md. It keeps launch snapshots and separate native sessions. It is a host development path, not proof of managed workspace isolation or role enforcement.
• Root SOUL.md is not loaded by these inspected paths. Do not delete it or contracts/SOUL.md until consumer inventory and evidence-preservation needs are resolved. Their presence does not make them authoritative in the target.
• POC startup-marker behavior is embedded in existing contracts and verification expectations. Any separation into explicit test fixtures must preserve valid health checks and cannot relabel skipped checks as passed.

Relation to existing plans

• Agent/project/workspace foundation: R16 already requires canonical agent SOUL and current approved context at Resume/Fresh launch; R17 describes configuration fingerprints and mismatch notices; R28 scopes personal context; R30 requires explicit legacy adoption. Extend and reconcile these decisions rather than designing a parallel lifecycle.
• Phase-2 contract and workspace/schema/audit discussion: reuse identity, revision, scope, and evidence concepts after checking their current approval state. A document reference is not runtime enforcement.
• Installation/onboarding requirements: bootstrap must integrate personality/style choices, trait compatibility, resumable initialization, and user privacy without granting extra permissions.
• Monorepo source layout: build on its source/build/install/state separation and component migration method. Reconcile historical milestone sequencing with Jason's explicit demo-first direction.
• SOUL concept guide: use as personality design input; do not import its rewrite prompt as an instruction to modify deployed agents.

Phases and gates

Concept documentation is maintained in Mosaic Stack concepts. These are Mosaic explanations with current/proposed status, not a mirrored product manual. Provenance records original lineage separately from current content identity. Documentation adoption does not waive the runtime migration gates below.

Phase A — documentation and candidate design before demo acceptance

Record owner decisions, inventory context consumers, and define a migration and evaluation proposal in separate planning artifacts. Any additional groundwork requires a recorded assignment; this capture does not dispatch workers.

Outputs: source-backed loading/ownership matrix, candidate template responsibilities, compatibility cases, isolated test design, and unresolved decisions. Preserve active contracts, bootstraps, launchers, generated installations, session state, credentials, and the current demo/review candidate.

Exit evidence: reviewed plan with owners, affected paths, current consumer list, and concrete acceptance checks. This is planning readiness, not demo acceptance.

Gate G1 — Jason verifies the current demo

Record Jason's acceptance and the exact candidate/evidence it covers in the existing demo records, then link it here. Do not infer acceptance from green tests, an agent verdict, or elapsed time. Acceptance of that demo does not automatically activate every task in this plan; reconcile the next bounded scope.

Phase B — bounded context/bootstrap migration

After G1 and assignment of the implementation increment, create reviewed template sources and bootstrap-owned instances. Implement agent-only SOUL resolution with clear missing/invalid-agent errors. Separate verification fixtures from normal personality. Reuse existing config, lifecycle, and launch interfaces where suitable.

Prove idempotence, preservation of existing edits, interrupted-bootstrap recovery, Resume/Fresh behavior, context provenance, and rollback in isolated fixtures. Freeze a candidate, obtain independent review, and let Jason test the increment before promoting it or retiring the old path. No running session silently reloads.

Phase C — personality evaluation and controlled promotion

Use isolated test registrations/workspaces or distinct test identities derived from the approved Darkwing/Filbert/Heffer/Rocko definitions. Decide the mechanism before launch; a familiar name does not permit reusing live session directories. Record model/harness settings, context hashes, scenario inputs, actual outputs, reviewer findings, and Jason's preference verdict. Record model-call scope and budget before live evaluations. Failed candidates remain evidence, not deployments.

Offline evaluation preparation may accompany Phase A; live trials and promotion require their assigned scope. This phase must not become an unattended self-rewrite loop or an automatic template rollout to all agents.

Phase D — monorepo organization after validated behavior

Use the existing source-layout plan to define package boundaries, declarative resource ownership, dependency directions, development installations, and release artifacts. Move one component at a time with compatibility entry points and verified rollback. Do not select a new package manager or copy the legacy tree merely to give the repository a monorepo appearance.

Collaboration work register

ACT-01 is complete. A later owner request authorized reference import and test preparation under ACT-04; its draft pack is ready for review, not live execution. Other tasks remain unassigned. Readiness does not dispatch another agent.

Task	Deliverable	Dependency / gate	Status
ACT-01	Capture owner decisions and staged shared plan	Current user request	Recorded by Codex
ACT-02	Inventory all bootstrap, launch, health-check, retry, and packaging context consumers	Assigned documentation scope	Unassigned
ACT-03	Specify template ownership, instance creation/update, provenance, and conflict rules	ACT-02; reconcile onboarding/foundation	Unassigned
ACT-04	Define isolated behavioral scenarios, fixture identities, scoring, and model budget	Owner-authorized preparation; reconcile ACT-02/03 before trials	Draft prepared by Codex: test package; live budget and evaluation binding unset
ACT-05	Freeze bounded migration candidate, compatibility checks, and rollback procedure	G1; ACT-03; implementation assignment	Deferred
ACT-06	Implement and independently review context/bootstrap migration	ACT-05	Deferred
ACT-07	Run approved test-agent evaluations and obtain Jason's acceptance	ACT-04/06; evaluation assignment	Deferred
ACT-08	Reconcile and execute component layout migration	Validated demo and affected behavior; layout assignment	Deferred

For each assignment record task ID, author, independent reviewer, exact file scope, workspace/worktree, baseline plus dirty-file identities where relevant, deliverable path, dependencies, and acceptance owner. Do not preassign the active demo agents.

Use one designated editor for this plan's status and decisions. Concurrent authors should write separate task notes named 2026-09-07_act-XX-<topic>.md in this folder and submit evidence pointers to the coordinator. A written assignment is not a filesystem lock; source work requires coordinated ownership and isolated worktrees where necessary. Preserve the shared Git index ownership recorded in CURRENT.md. Direct communications and worker dispatch require actual assignment/authorization; merely storing this file does not deliver it to another tmux session.

Acceptance and evaluation cases

• Single identity: exactly one agent SOUL in effective context; root/default SOUL absent. Missing agent SOUL refuses launch rather than using another persona.
• Bootstrap ownership: initial system agent and subsequent agents each receive their own canonical instance. Rerun, interruption, and template revision never silently discard approved edits or create duplicate identities.
• Stable execution: record the approved inputs used by Resume and Fresh; changes to source do not alter already-loaded context. Historical snapshots remain immutable evidence and are not offered as editable canonical files.
• Compatibility: exercise every affected launch/verification consumer from ACT-02. Preserve session history and startup verification; demonstrate rollback without restoring or overwriting an active agent's conversation or work records.
• Personality: a simple question gets a direct answer; a flawed proposal gets a respectful challenge; an uncertain fact is labeled honestly; a failed action is reported accurately; an out-of-scope request does not gain authority from tone.
• Style adaptation: technical depth follows the task; humor is optional; public/shared communication fits its audience. Avoid rewarding profanity, contrarianism, verbosity, or confident guesses as evidence of personality.
• Evaluation integrity: compare baseline and candidate under recorded settings, retain actual responses, separate subjective style judgments from hard requirements, and repeat ambiguous cases. A few good responses are not a guarantee of behavior or security enforcement.

Open design decisions

1. Final template source and deployed instance locations, including eventual ownership of constitution/standards and preservation of current contract fixtures.
2. Version/provenance representation and who may approve instance edits or upgrades; align with foundation context fingerprints instead of inventing a second scheme.
3. Explicit context precedence and consistent behavior across container and host modes, including scoped user information and all affected headless workers.
4. Trait composition during bootstrap, required versus optional template inputs, handling of contradictory choices, and existing-instance migration rules.
5. Concrete test-agent isolation, writer/reviewer allocation, evaluation rubric, budget, and sufficient evidence for owner acceptance.
6. Exact compatibility lifetime and rollback triggers before retiring boilerplate paths, followed by component layout decisions under the monorepo plan.

Decision and handoff history

• 2026-09-07 — Jason agreed to responsibility separation, concrete personality, template-based instances, and evaluations; explicitly required one agent SOUL, demo compatibility, and post-validation structural work. Codex recorded ACT-1. No runtime implementation, agent launch, worker message, or task reassignment performed for this capture. Next planning task is ACT-02 when assigned; the operational next action remains in CURRENT.md.
• 2026-09-07 — Jason requested pulling the selected OpenClaw concepts and preparing testing with Darkwing. Copied twelve reference documents plus LICENSE with a source manifest; created eleven synthetic review scenarios, a candidate SOUL, NOT_RUN results and a preparation utility. See Darkwing handoff. node scripts/prepare-concept-tests.mjs --check verified thirteen imported files and eleven cases. Existing launcher regressions passed two tests in isolated fixtures. Prepared /tmp/mosaic-act1-l2id7s with 22 NOT_RUN baseline/candidate rows and mode 0700. This temporary workspace is reproducible, not durable test evidence. No model trials, active-session changes, demo-candidate changes, messages or migration implementation followed. Darkwing readiness review is prepared but not delivered or assigned automatically.
• 2026-09-07 — Owner directed full annexation and Mosaic nomenclature. Rewrote the twelve imported references plus the existing SOUL guide as thirteen Mosaic concept pages in docs/concepts, with an index and explicit implementation status. Replaced the old reference copies; source lineage and LICENSE now live under docs/reference/concepts. Renamed the benchmark concept to agent-behavior-tests. Updated ACT-1's cases and preparation utility to validate current Mosaic hashes, preserve original-source metadata and stage concepts/provenance separately. Thirteen concepts, license attribution, eleven scenarios and fifty local links verified; fresh review workspace /tmp/mosaic-act1-xVwXtF prepared with behavioral results still NOT_RUN. Earlier import/history records retain their original facts. No runtime launcher, deployed context, active session, or demo candidate changed.