# Setup Guide — Multi-Model Workspace Operating Model **Audience:** an AI assistant asked to set up a new project workspace that runs the way this operating model describes. **What this file is:** a portable description of *how work is done and handed off* between AI sessions and models. It contains no subject-matter content from the workspace it was derived from — no facts, no objectives, no decisions, no organizational detail. Everything below is method. **What you are being asked to build:** a folder that any AI model — any provider, any size, local or cloud — can be dropped into cold, and be productive in without the operator re-explaining anything, while producing a durable, auditable, honest record of what was and was not actually accomplished. --- ## 0. The four ideas the whole model rests on Understand these before you create any file. Every mechanic below is one of these four made concrete. 1. **One file is the memory.** Models don't retain anything between sessions. A single Markdown handoff file is the only cross-session memory. Everything else in the folder is deliverables. 2. **History is append-only; state is edited in place.** A log of what happened never changes. A description of what is currently true is corrected the moment it goes stale. Never mix the two. 3. **Authorship is attributed, and disagreement survives.** Different models record different conclusions under their own names. No session rewrites another's judgment. 4. **Existence is not proof.** A drafted artifact proves only that someone drafted it. Approval, validation, operation, and completion are separate claims requiring separate evidence, tracked separately. Idea 4 is the one that most setups get wrong, and the one that makes this model worth the overhead. An AI workspace naturally accumulates confident-looking documents that nobody approved. The mechanics in Sections 6–9 exist entirely to stop that. --- ## 1. Bootstrap sequence Do these in order. Steps 1–4 are the minimum viable setup; 5–8 add rigor and can be deferred until the workspace has real work in it. | Step | Create | Purpose | |---|---|---| | 1 | `.md` | The single memory file (Section 2) | | 2 | Provider pointer stubs | Auto-discovery by each AI tool (Section 3) | | 3 | A working-documents subfolder | Where model-produced artifacts live | | 4 | Handoff Sections 1–6, populated | Protocol + a real folder map | | 5 | `_ARCHIVE.md` | Overflow for the session log (Section 2.4) | | 6 | Objective program + closure rule | Section 5 | | 7 | Acceptance/evidence matrix | Section 7 | | 8 | Structural verifier script | Section 8 | Ask the operator only three things before you start: - What is the workspace's scope, and who is the human operator/decision authority? - Are multiple models expected to work here, and is any of them meant to be independent of the others? - Do binary/human-authored source files exist that models must never edit? Everything else you can infer from the folder and record as you go. --- ## 2. The handoff file Name it something unmissable and provider-neutral — e.g. `LLM_HANDOFF.md`. Put it at the folder root. Open it with a directive block: ```markdown # LLM HANDOFF — Workspace > **READ THIS FIRST if you are an AI assistant working in this folder.** > This file is the shared memory between AI sessions. Different models > (frontier or open-source, local or cloud) work here at different times. > None of them retain memory between sessions — except through this file. ``` ### 2.1 Section layout Use exactly this structure. The numbering matters, because other files and work orders cite sections by number. | § | Contents | Mutability | |---|---|---| | 1 | Protocol — how to use this file | Rarely changes | | 1a | Isolation rule | Fixed | | 1b | Independent voices rule | Fixed | | 1c | Suitability gate | Fixed | | 2 | What this workspace is — scope, operator, recurring parties, key terms | In place | | 3 | Folder map — annotated tree, dated | In place | | 4 | Current state — what is true now, by topic | **In place** | | 5 | Open items / known issues — numbered, resolutions logged | **In place** | | 5a | Objective program + closure rule + per-objective status | In place | | 6 | **SESSION LOG** — newest at top | **Append-only** | Sections 4 and 5 answer "what is true right now." Section 6 answers "what happened." A reader who needs to act reads 1–5a; a reader who needs to audit reads 6. ### 2.2 Protocol text (Section 1) Write it as numbered rules a small model can follow literally: 1. Read this entire file before doing any work in this folder. 2. At the end of your session, append a new entry to the SESSION LOG (Section 6, newest at the top). Never edit or delete prior entries. 3. Log entry format (copy exactly): ``` ### YYYY-MM-DD — () — - TASK: what you were asked to do - DID: what you actually did (files created/modified/moved, with paths) - FOUND: notable discoveries, decisions, or state changes - OPEN: anything unfinished or handed off to the next session ``` 4. Update Sections 4 and 5 **in place** when facts change — the body reflects *now*; the log reflects *history*. 5. Rules for all models: - Plain Markdown only. No provider-specific syntax, no embedded tool calls. - Absolute dates (`2026-08-15`), never "yesterday" or "last month". - Refer to files by path relative to this folder. - Do not delete or overwrite human-authored files without explicit operator instruction. Log every file move/rename here. - **If this file contradicts the actual folder contents, trust the folder, fix this file, and note the correction in your log entry.** - Keep this file under ~N lines so small-context models can load it. If the log grows too long, move the oldest entries verbatim to the archive file and note that you did so. The four-field log format (TASK/DID/FOUND/OPEN) is load-bearing. `DID` with paths is what makes the record verifiable; `OPEN` is what makes the handoff a handoff rather than a diary. The "trust the folder" rule is the model's self-healing mechanism. Without it, one stale line propagates through every future session. ### 2.3 The three fixed rules (1a, 1b, 1c) **1a — Isolation: the memory is a sealed silo.** State it as a deliberate operator decision, not an oversight, or models will "helpfully" breach it: - **Do not import.** No knowledge, conclusions, preferences, or memory from other projects, other folders, or provider-level memory features (a chat product's account memory, a global user-memory directory) enters this file or the work done here. If the operator pastes outside material in, that is their call — but you do not fetch it on your own. - **Do not export.** Do not copy this file's contents, or facts learned here, into memory stores for other projects or any provider-level memory. - **One silo, one file.** This file (plus its archive) is the *only* sanctioned cross-session memory. Do not create additional memory files, and do not read another project's handoff file even if you know one exists. - **If this pattern is replicated** in other folders, each handoff file is fully independent. Never reference, link, copy from, or reconcile between them. Why it matters: modern agents ship with cross-session memory features that default to blending contexts. In a workspace where provenance is the product, silent cross-contamination is a correctness bug — you can no longer say where a "fact" came from. **1b — Independent voices: disagreement is preserved, not resolved.** - Log entries state what you did and what you found, **attributed to your model**. They are not the project's official position. - **Never rewrite, soften, or "correct" another session's logged analysis or stance.** If you disagree, append your own entry stating your position and reasoning. Both entries stand. - The in-place sections hold only **verifiable facts** — what exists, what it contains, what state it is in — not judgments. If a "fact" there is actually a contested judgment, move it into the log as an attributed position. - Inheriting a prior session's conclusions is optional; inheriting its factual record is not. Verify facts against the folder when they matter. This makes the workspace usable for deliberately polling several models on the same question and comparing them, instead of getting one laundered consensus. **1c — Suitability gate: confirm fit before performing an objective.** - Assignment does not imply suitability. Before substantive work on an objective, assess whether you are well suited to it. Other sessions' attributed positions are input; make your own assessment for your own model. - If you are not well suited, **say so plainly before starting**, point the operator to better-suited options (other models or human owners), and ask how to proceed. - The operator may choose to continue with you anyway — their call — but you must obtain that explicit approval first, and record in your log entry that the concern was raised and approval was given. ### 2.4 Size discipline Pick a line cap (500–600 lines is a reasonable band) and enforce it, so small-context and local models can still load the whole file. When the log overflows, move the **oldest** entries verbatim into `_ARCHIVE.md` and note the move in both files. Never summarize an entry to save space — move it whole. Changing the cap is an operator decision and gets logged like any other. --- ## 3. Provider pointer stubs Each AI tool auto-discovers a differently-named instruction file. Create one stub per tool your operator uses, all pointing at the same handoff file: - `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, and any other convention in play. Each stub is ~15 lines and says only: read the handoff file in full first, append a session-log entry at the end, update state sections in place, the handoff is the single source of truth — **do not store memory in this stub** — plus a one-paragraph restatement of the isolation rule. Two rules about stubs: 1. **They are pointers, never memory.** The instant a stub accumulates project facts, you have two sources of truth and the model is broken. Say this inside the stub itself. 2. **Restate the isolation rule in every stub.** It is the one rule a model may violate before it ever opens the handoff file. Note the same in the handoff's folder map, so nobody later "helpfully" consolidates the stubs into the handoff or vice versa. --- ## 4. Artifact conventions **Naming.** Prefix by the objective or workstream, then the artifact type, then status/date: ``` ---. O2-Data_Handling_Standard-CANDIDATE-v2.md O4-Candidate_Tracker-BUILD_RECORD-20260816.md ``` Status tokens that appear in filenames and headers carry real meaning and should be defined once in the handoff: `DRAFT`, `CANDIDATE`, `COMPLETED`, `BLANK`, `LOCK`, `SUPERSEDED`, `CORRECTED`. **Every model-produced artifact carries a header block:** ```markdown Status: DRAFT — prepared by a model; not an approved deliverable Authority: Precedence: .md is the single source of truth. If this file conflicts with it or with the folder contents, the handoff and the folder win. Boundary: ``` The `Boundary` line does the heavy lifting. A standard that has been drafted but not ratified must say so on its own face, because it will be read in isolation by a future session that never opens the handoff. **Standing labels.** Define a small vocabulary and use it verbatim, so it is greppable and verifiable: | Label | Meaning | |---|---| | `NOT EXECUTED` | Steps are prepared; nothing was performed | | `NOT VERIFIED AGAINST CONTROLLED SOURCE` | Built from an uncontrolled copy | | `UNCERTIFIED` | No owner has confirmed the facts in it | | `PROTOTYPE` | Produced under a relaxed-gate framing; not production | | `SUPERSEDED` | Replaced; retained for provenance, not deleted | | `NOT FOR SEND` | Communication-ready but not authorized to send | **Never edit human-authored or binary sources** (`.docx`, `.xlsx`, `.pptx`, PDFs). When a source is wrong, do one of three additive things: 1. Produce a **corrected controlled copy** as a new file, with a correction-to-copy map and a notice inside it that it is not approved for use; leave the source byte-unchanged. 2. Place a **sidecar** README beside the source describing the defect, quarantine, or canonical/duplicate designation. The source stays untouched. 3. If deletion is genuinely required, get explicit operator authorization, **record the file's SHA-256 before deleting**, and log the hash and the authorizing decision ID. Additive-by-default is what lets a model work unsupervised in a folder of real human documents without the operator having to audit it. --- ## 5. The objective program and the closure rule If the workspace has multi-session goals, enumerate them in handoff Section 5a as `O1…On`. Each objective gets: ```markdown #### O — - Status: NOT STARTED | IN PROGRESS | BLOCKED | AWAITING ACCEPTANCE - Objective: - Acceptance criteria: - Evidence/next task: ``` **The closure rule — write it verbatim into Section 5a:** > An objective may be marked COMPLETE only when (1) its listed acceptance > criteria are supported by artifacts or other verifiable evidence, (2) a > working model has reviewed that evidence and found no material gap, and > (3) the operator explicitly agrees it is accomplished. Until all three > occur, use one of: NOT STARTED, IN PROGRESS, BLOCKED, or AWAITING > ACCEPTANCE. Log disagreement rather than erasing it. Also record the overall count (`Overall completion: 0/12`) so the number is visible and mechanically checkable against the individual statuses. Two corollaries worth stating explicitly, because models drift on both: - **Direction is not evidence.** An operator authorizing work, or approving a plan, changes no acceptance criterion. Only the work landing and being verified does. - **An authorization is not an execution.** Track them as separate states. --- ## 6. Decisions: the ledger pattern When an operator has to decide many things at once, don't capture it in prose. Use a four-artifact pattern: 1. **Decision packet** (`...-PACKET--DRAFT.md`) — every open question, each with a stable ID (`A01`, `E03`, `G07`, `X02`…), the options, the recommendation, and the consequence of each option. Grouped by category so the operator can move through it fast. 2. **Blank response ledger** (`...-BLANK.md`) — the same IDs, dispositions `PENDING`. This is the reusable template. 3. **Completed ledger** (`...--COMPLETED.md`) — the filled copy. This is authoritative. 4. **Per-session decision records** (`...-Decision_Record--SESSION.md`) for decisions made in later interactive sessions. Rules that make the pattern hold: - **The packet and blank template are preserved byte-unchanged**, forever. They will still read `PENDING` after the decisions are made — that is correct. The completed ledger is authoritative. Never backfill dispositions into the packet to make it "look current." - **Every decision gets a permanent unique ID** in one monotonic series: `-DEC--0NN`. IDs are never reused or renumbered. - **Quote decisions verbatim** wherever they are reproduced. Never paraphrase a disposition when recording it into a register. - **Decision records are immutable.** End each one with: `*End of record. Do not edit; append corrections as new decisions.*` A reversal is a *new* decision that supersedes an old one by ID; the old text stays. - **Each record states its own boundaries** at the top: whether it was a convened meeting or a working session, whether it produces minutes or merely a decision record, and what it explicitly does *not* approve. **Threading.** After a decision session, its dispositions must be propagated into every affected register — verbatim, with IDs. Treat threading as its own tracked work item with its own verification, not as something that happens implicitly. A decision that lives only in the ledger will be missed by the next session reading a register. --- ## 7. The acceptance/evidence matrix One file, separate from the handoff, that audits every acceptance criterion for every objective. This is the primary defense against drafted-equals-done. **Three states only:** - **PROVEN** — authoritative current evidence directly satisfies the criterion for its stated scope. May later expire after material change. - **PARTIAL** — useful design or implementation evidence exists, but approval, completeness, operating proof, validation, or scope is missing. - **NOT PROVEN** — evidence is absent, contradictory, expressly unapproved, or too indirect. **Write the audit rule into the file:** > Drafts, synthetic tests, templates, agendas, plans, recommendations, silence, > and proposed owners do not prove approval or operation. File existence does > not prove correctness. Receipt does not prove validation, and a direction to > pilot does not prove pilot completion or outcome. Add a per-objective summary table (criteria audited / proven / partial / not proven / closure finding) whose counts the verifier can check against the rows. When something happens that changes what is *reachable* rather than what is *proven* — an evidence channel closes, an authority posture changes — record it as a dated update block at the top of the matrix, attributed to the recording model, and explicitly state that **no criterion state changes**, because approval is not evidence. Distinguishing "pending" from "unreachable by design" is one of the most useful things this matrix does for the operator. --- ## 8. The structural verifier A shell script that mechanically checks the workspace's internal consistency. Run it at the end of any session that changed structure. **What it should check:** - The handoff is within its line cap and contains all N objective sections. - The handoff's stated completion total matches its objective status rows. - Every acceptance criterion has exactly one recognized state, and the summary counts match the underlying rows. - Any objective marked COMPLETE has all its criteria marked PROVEN. - Decision IDs are covered exactly once, in order, with no `PENDING` left in a completed ledger. - Required boundary strings still appear verbatim in the artifacts that carry them (this catches a model silently softening a caveat). - Structural counts that should be stable (scenario counts, register rows, rule counts) still hold; JSON companions still parse. - Markdown table widths are internally consistent. - **Protected human-authored source files still match their SHA-256 baseline.** **Design rules for the script:** - `set -u`, `pass`/`fail` helpers, a running count, exit 0/1, and every failure printed with expected-vs-found. - Prefer `rg`, fall back to `grep -E`, and run identical checks either way. - Print a banner on every run stating what a pass does **not** mean. **Write this into the script's header and its README:** ``` A passing run proves only that named workspace artifacts remain internally consistent with these structural checks. It does NOT prove approval, operating effectiveness, objective completion, model acceptance, or operator acceptance. ``` **The anti-gaming rule** — put it in the README verbatim: > An authorized change may correctly fail a check. Do not weaken the test just > to make it green. First verify the authority and evidence, update the > affected artifacts and the handoff, then deliberately update the > test/baseline and record why. Keep a **"Baseline changes on record"** section in the README: every time a check or a protected hash changes, one dated paragraph explaining what underlying fact changed and why the check was not merely weakened. For a protected-source hash change, require the exact file, the approval record, the expected new hash, and the canonical/superseded disposition first — and note that a hash match proves byte identity, nothing more. --- ## 9. Multi-model orchestration ### 9.1 Division of labour Record it as an operator decision in the handoff, with a companion framework file. A workable split: - **Frontier model:** task decomposition, work-order authoring, verification design, cross-checking executed work, handoff integrity. Does not execute work orders assigned to other models. - **Open-source / other models:** execute bounded work orders, one at a time, exactly as scoped. - **Human operator and owners:** everything requiring authority — approvals, sending communications, appointments, publication, and any factual claim only a named owner can make. The suitability gate (1c) applies per work order. Assignment never overrides it. ### 9.2 Work orders Each order states, in this order: **ID; objective served; assigned model class; authorization basis (decision ID or handoff citation); inputs (exact paths); scope; out of scope; definition of done; verification step; logging requirement.** Ground rules for executing models, stated once in the framework file: 1. Read the handoff in full before starting any work order. 2. One work order per session unless the operator says otherwise. 3. Never move, rename, or delete files; never edit binary sources; never send communications. If an order appears to require any of these, **stop and log the conflict** instead of improvising. 4. Quote decisions verbatim with their IDs. 5. Plain Markdown, absolute dates, relative paths. 6. At session end, append a session-log entry naming the work-order ID, what changed with paths, what was found, what remains. 7. **If the folder contradicts a work order's stated inputs, trust the folder, log the discrepancy, and stop rather than improvise.** Maintain an **execution status** section listing every order's real state, including the ugly ones: executed, reverted, withdrawn, not started, superseded. When an order is executed by a different model than assigned — because the operator said so — say that explicitly, and say what verification consequence follows. ### 9.3 Cross-family verification > Every executed work order is verified by a model from a **different model > family** than the executor before the operator relies on it. Findings are > logged as attributed session-log entries; disagreement is preserved, never > reconciled by editing. No completed work order makes anything "approved" or > "complete." Family independence matters because same-family models share failure modes: the verifier reproduces the executor's blind spots and reports clean. ### 9.4 Blind calibration When you need to know whether a rule set is actually applicable by a human or a model — not just whether it is well written — run a blind test: 1. Build a **scenario set** and a separate **answer key**. Mark the key SEALED and do not open it before responses are locked. 2. Assign **two independent reviewers**, from different model families. The model that authored the rules and the key is **disqualified** from reviewing. 3. Each reviewer completes a controlled copy without opening the key. 4. **Lock and hash each submission** (SHA-256, recorded in the lock file) before any comparison. 5. Compare responses against each other and the key. Report exact agreement rates. Adjudicate disagreements against the authoritative source text first, the candidate artifact second, most-protective answer where sources are silent. 6. Record findings with IDs (`CAL-F-01`…) and a conclusion that states what the result does and does not authorize. If a designated reviewer is unavailable and the operator substitutes another, record the substitution and confirm the independence properties still hold. ### 9.5 Evidence requests and owner acceptances Facts that only a named human owner can supply must never be silently invented. Track them explicitly: - An **evidence request pack** with one entry per request: ID, addressee (or "owner unidentified"), what is asked for, why, and send-ready status. Models prepare; **only the operator sends**. - **Owner-acceptance rows** (`OWA-01`…) recording, per role, whether an owner has actually confirmed something or whether the claim is an operator assertion. Never let "the operator says X agreed" become "X agreed." - When a request channel is closed without sending, record it as a decision, and mark all dependent work with `NOT VERIFIED AGAINST CONTROLLED SOURCE` or `UNCERTIFIED` rather than letting it proceed silently. ### 9.6 The prototype-to-production gate Real programs hit a point where the operator says "proceed without waiting." Handle it honestly with a single named gate: - Work may proceed under a `PROTOTYPE` framing with gates waived. - Everything waived is **listed** in a gate brief with IDs (`D-PTP-01`…), stating exactly what re-enters at the prototype-to-production boundary. - Nothing produced under the waiver may claim it was reviewed, validated, or approved. Terminal or externally-visible releases stay separate. This gives the operator speed without laundering the record. --- ## 10. Session mechanics **At session start:** 1. Read the handoff file in full. 2. Read any framework/work-order file it points to. 3. Verify against the folder anything you're about to rely on — the handoff can be stale, and the folder wins. 4. Apply the suitability gate before substantive work. **During:** - Absolute dates, relative paths, plain Markdown. - Quote decisions verbatim with IDs. - Additive changes; never edit binary sources; log every move or rename. **At session end:** 1. Update Sections 4 / 5 / 5a in place for any changed facts. 2. Run the structural verifier if structure changed; record counts. 3. Append the session-log entry (TASK/DID/FOUND/OPEN) at the top of Section 6. 4. If the file exceeded its cap, archive the oldest entries verbatim and say so. **When a session is long or gets summarized:** the handoff file, not your context, is the record. Write state changes into it as they happen rather than batching them at the end. --- ## 11. Anti-patterns These are the specific ways this model degrades. Name them in your setup so future sessions recognize them. | Anti-pattern | Why it's fatal | Guard | |---|---|---| | Memory in a pointer stub | Two sources of truth | Stubs say "never store memory here" | | Editing a prior log entry | Destroys the audit trail | Append-only, stated twice | | Rewriting another model's conclusion | Launders disagreement into false consensus | Rule 1b | | Judgments in the state sections | "Facts" become contested and unfixable | State sections hold verifiable facts only | | Paraphrasing a decision | Drift compounds across registers | Verbatim + ID, always | | Backfilling a preserved template | Erases the before-state | Packet and blank ledger byte-unchanged | | Weakening a failing check | Turns the verifier into decoration | Anti-gaming rule + baseline-changes record | | Treating a draft as done | The single biggest failure mode | Acceptance matrix + closure rule | | Same-family verification | Shared blind spots, clean report | Cross-family requirement | | Relative dates | Unreadable a month later | Absolute dates rule | | Silently improvising past a contradiction | Corrupts the record invisibly | "Trust the folder, log it, stop" | | Importing other-project memory | Destroys provenance | Isolation rule, restated in every stub | --- ## 12. Scaling down Not every workspace needs all of this. The overhead is justified when work spans many sessions and models, when the record may be audited, and when drafted artifacts could be mistaken for approved ones. Minimum viable version: - The handoff file with Sections 1, 2, 3, 4, 5, 6. - The TASK/DID/FOUND/OPEN log format, append-only. - Pointer stubs for the tools in use. - The isolation rule and the "trust the folder" rule. - Additive-only handling of human-authored files. Add the objective program when work spans sessions; the acceptance matrix when someone might mistake a draft for a decision; the verifier when the artifact count exceeds what a person will re-read; the work-order framework and cross-family verification when more than one model is executing. --- *End of setup guide. This file describes method only. Do not add project-specific content to it — copy it into a new workspace and populate that workspace's own handoff file instead.*