⛔ ARCHIVED 2026-06-21 — historical, do not use as current. The standalone three-mode sub-design, fully absorbed into working/vrataski-design.md (the single source of truth) the same day it was written. Kept for history. Reconstructed from session context (it was never committed to git), so trust vrataski-design.md if they ever disagree.

Vrataski — Three-Mode Distribution Design (working)

What this is. The design for Vrataski's three deployment/operation modes — Standalone, Jacket, Mimic — and the single canonical layout they all share. A sub-design of the broader Yggdrasil→Vrataski restructure (see yggdrasil-restructure-design.md, now under "full pivot"). Feasibility research that grounds it lives in claude-code-loading-research.md. Mid-brainstorm — not finished.

Understanding Lock (settled 2026-06-21)

• Scope = FULL PIVOT. This is the restructure now: Yggdrasil→Vrataski. The rename (repo, paths, GitHub remote, ~/.claude wiring) is in scope. Restructure subprojects 0 (doc arch) / A (collections) / I (identity) are re-aimed at Vrataski; Mimic un-parks the previously-held puppet/scry rework.
• Identity = SPLIT BY REACH. Personal preferences (how Brad works) stay global in claude-personal, still symlinked into ~/.claude (travel to every project). Cross-project skills that benefit from traveling migrate INTO Vrataski (first mover: project-conventions). skill-wiring + new-machine-setup stay personal for now — revisit once install is designed.
• Model = ONE ARTIFACT, THREE PLACEMENTS (modes are not forks):
  • Standalone — the canonical artifact at home; works on itself / starts new native projects.
  • Mimic — the same Standalone install operating on an external target; Vrataski stays cwd, keeps work in its own .mimic/ + .scry/. (Renames today's Puppet/.puppet.)
  • Jacket — the same artifact copied into a host project at <host>/.jacket/; travels into a project you'll cwd into. Gitignored; uninstall = delete dir + unwire.
  • "As identical as possible" = the files are literally the same; the only legitimate differences are (a) where the root sits, (b) the activation wiring, and (c) what it points at. The content layer is identical; the activation/wiring layer is necessarily mode-specific.
• Jacket = FROZEN VENDORED COPY (self-update parked as a future enhancement; contrast anywhere-agents' live-pull).
• Commands → skills (design-level): only skills travel via --add-dir/plugins (skills.md:160), and "custom commands have been merged into skills" (skills.md:16), so Vrataski expresses everything as skills for portability + uniformity.
• Jacket needs TWO wires (a known constraint, exact levers deferred to planning): (a) skills/commands activation (skills-dir plugin or --add-dir), and (b) root-docs activation (@import in host CLAUDE.md, or --add-dir + CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1).
• Mimic feasibility: examines a semi-sandboxed mirror of the target from within Vrataski's own scratch — not add-dir'd, not driven (driving is incidental). Because work stays in Vrataski's own tree, it sidesteps the subagent-cwd wall (anthropics/claude-code#31940), which only bites if you reach for the incidental drive-the-live-target capability. Idiosyncratic — weakest prior art of the three. (See decision 11 + per-mode shape.)

Brainstorming ↔ planning boundary

Brainstorming settles shape + decisions (incl. shape-level findings like commands-as-skills and frozen-vs-live). Planning settles exact mechanics (which activation lever, precise INSTALL steps, the install-method menu). We deliberately do NOT pin the exact wiring here.

Open questions / parking lot

• ✅ Canonical layout — settled (below).
• ✅ .jacket/ naming collision — resolved: the mode wins the name (deployment dir); collections move to top-level.
• ✅ dot vs non-dot convention — adopted (decision 8 below), with .claude/ as the externally-mandated exception.
• 🔸 .meta/ contents — workflow.yaml retired (dead/never-read); this design claims nothing new. Deployment-identity manifest parked (build when a consumer appears, likely Jacket-install in planning). Ledger/config → subproject A; durable-docs vs INDEX.md → subproject 0.
• ⏸️ skill-wiring / new-machine-setup home — decide post-install-design.
• ⏸️ Jacket self-update — future; Jacket vendors a frozen copy for now.
• ⏸️ Exact activation levers + INSTALL.md content + install-method menu — planning.
• ⬜ From-source follow-up: can a skills-dir plugin also pull in root docs (→ Jacket = one wire)?

Decisions log

(running; appended as design sections firm up)

1. Full pivot (Yggdrasil→Vrataski). Alts: hybrid design-ahead / pure capture. Why: Brad's call.
2. Split-by-reach identity. Alts: keep-separate / absorb-personal. Why: precision; keeps personal prefs out of a possibly-public Vrataski while letting cross-project skills travel.
3. One-artifact/three-placements. Why: maximizes the "identical layout" goal; modes = position.
4. Jacket frozen-vendored. Why: self-update deferred; simplest durable install.
5. Commands→skills. Why: only skills travel; "merged into skills"; uniformity.
6. .jacket/ name → the mode (deployment dir); collections move top-level. Why: the mode needs the name more than the collections container did. Overrides subproject A's earlier use.
7. Scry rework + decouple from Mimic. Scry splits into .scry/ (ephemeral: repo clones + scratchpad, gitignored) and research/ (durable: kept markdown deliverables, committed). Scry becomes a standalone capability usable in any mode (not Puppet/Mimic's arm). Alts: keep Scry inside Mimic. Why: portability/modularity; the dot/non-dot split lets you gitignore scratch and keep output; sidesteps the subagent-cwd wall (#31940) since Scry clones into its own tree.
8. dot/non-dot convention. Leading-dot dir = not project content — either infra (committed) or scratch (gitignored); gitignore the scratch ones (.scry/, .mimic/). Non-dot dir = durable/kept content (research/, working/, bookmarks/, backburner/, archive/). Exception: .claude/ — externally-mandated plumbing we don't control (dot is Claude Code's choice; it's committed). .meta/ = our committed infra dot-dir.
9. Research placement = soft edges. Scry research defaults to research/; the model suggests the location (recommends research/ most of the time, but may propose working/ or elsewhere) and the user disposes. No hard rule — recommend-not-directive, per the no-demand ethos.
10. .meta/ — retire workflow.yaml; claim nothing new now. .meta/ stays as Vrataski's committed self-metadata dir (dot-exception). Git archaeology (2026-06-21): workflow.yaml is the original layered-composition layer-manifest (role: base + downstream dependency declaration), authored in the first commit (aacd6eb, 2026-05-27), never changed, never read by any logic (purely descriptive in docs), and premised on the now-killed exec-partner layer → retire it. This modes-design claims nothing new in .meta/. A deployment-identity manifest (mode / provenance / upstream pointer) is parked — build it only when a real consumer appears (most likely the Jacket install/self-detection design in planning), NOT pre-built for parked features (self-update) or undesigned behavior (mode-specific conduct). Avoids re-creating exactly what workflow.yaml was: a manifest described in docs, read by no one. Remaining tenants: ledger/config → subproject A; durable-docs manifest (overlaps INDEX.md) → subproject 0.
11. Mimic = semi-sandboxed examination, not drive. The target is examined closely from within Vrataski's own scratch (mirror), kept semi-sandboxed; the target is not add-dir'd and driving (mutating) it is incidental, not the posture. Preserves current Puppet behavior. Sidesteps #31940 (subagents stay in cwd). Mirror mechanism → planning.
12. Scratch dot-dirs never ship. .scry/, .mimic/ are gitignored + created on-demand; they are not part of any placement (Standalone repo or minted Jacket) — they materialize where/when a capability runs.

Canonical layout (settled 2026-06-21)

One tree, placed three ways. Only .mimic/ is mode-gated (Mimic). .jacket/ is not in the tree — it's the directory name the whole tree is copied INTO for a Jacket deployment.

vrataski/                     ← canonical home (Standalone); copied wholesale → <host>/.jacket/ (Jacket)
├── CLAUDE.md                 SHARED · auto-loads · lean self-doc + live checkpoint (current-plan.md folds in)
├── AGENTS.md                 SHARED · foreign-agent technical doc
├── README.md                 SHARED · human intro
├── FIRMWARE.md               SHARED · why/behavior (transcluded leaf)
├── INDEX.md                  SHARED · auto-maintained file/dir map
├── SYSTEM.md                 SHARED · current plumbing reference
├── INSTALL.md                SHARED · bootstrap + per-mode activation methods
├── LICENSE.md                SHARED
├── .claude/
│   ├── settings.json         SHARED · project-scoped perms
│   └── skills/               SHARED · EVERYTHING is a skill (commands collapsed in, invocation-controlled)
│       ├── brainstorming/ planning/ bookmarking/ good-morning/ save-progress/
│       ├── hygiene-check/ mimic/ (was puppet) scry/ project-conventions/ …
├── bookmarks/                SHARED · collection — md source of truth + derived index.yaml
├── backburner/               SHARED · collection (+ other collections per subproject A)
├── research/                 SHARED · durable Scry deliverables (kept/committed; external-topic research)
├── archive/                  SHARED · drained/retired items + history
├── working/                  SHARED · Vrataski's OWN design/build/handoff docs
├── .meta/                    SHARED · committed infra (dot-exception) · workflow.yaml RETIRED; no new manifest now;
│                             ·   ledger/config → subproject A; durable-docs manifest → subproject 0
├── .scry/                    SCRATCH (gitignored) · Scry's repo clones + research scratchpad; any mode
├── .mimic/                   MODE-GATED (Mimic, gitignored) · per-target examination/mirror work; on-demand
├── .gitignore
└── .gitattributes

Embedded decisions: (1) .claude/ skills-only; (2) collections + research/ top-level, .jacket/ reserved for the deploy dir; (3) Scry split .scry/ (scratch) vs research/ (durable), decoupled from Mimic; (4) working/ = Vrataski's own design docs, research/ = Scry's external-research output — distinct kinds of durable doc.

Per-mode placement shape (settled 2026-06-21)

Frame: each mode = (where the tree sits) + (cwd) + (what it points at) + (activation wiring) + (active scratch). The canonical tree is byte-identical in all three; only the surrounding facts differ.

Scratch dirs (.scry/, .mimic/) are gitignored, created on-demand, and never ship with any placement. The column shows which come into play in normal use of a mode — not what's bundled.

Key insight: activation is entirely a Jacket problem. Standalone & Mimic put Vrataski at the cwd, so .claude/skills/ + CLAUDE.md load by native discovery — zero wiring. Jacket is the only placement where Vrataski isn't the cwd, so it's the only one that needs activation. (Reaffirms Mimic ⊂ Standalone: Mimic = the home placement pointed at a target, plus .mimic/.)

• Standalone — baseline; tree is the repo, is the cwd, all native. Also the source instance: where Vrataski is developed and from which jackets are minted.
• Mimic — Standalone operating in an examination posture: the external target is kept semi-sandboxed and examined closely from within Vrataski's own scratch (.mimic/<target>/, .scry/) — not add-dir'd, not driven. Mimicking/emulating the target (the name) is the point; the ability to "drive" (mutate) the live target is incidental, not the default. Preserves today's Puppet behavior under the rename. Vrataski needs no activation (native cwd). Bonus: because examination happens inside Vrataski's own tree, subagents stay within cwd — sidesteps the subagent-cwd wall (#31940), which only bites if you reach for the incidental drive capability. (Exact mirror mechanism → planning.)
• Jacket — the only wired mode. Frozen copy at <host>/.jacket/, gitignored, host is cwd.
  • Wire 1 — skills/commands activation (host cwd's .claude/ doesn't see the jacket's skills).
  • Wire 2 — docs activation (the jacket's CLAUDE.md / root docs must reach context).
  • Footprint↔persistence axis (design-level): wires range from zero host-file edits but ephemeral/per-session (e.g. --add-dir at launch) to persistent but touches a host-tracked file (e.g. @import in the host's CLAUDE.md). Brad's self-containment preference → prefer the smallest, most reversible host footprint; ideally the host's only footprint is the gitignored .jacket/ + one config entry, avoiding edits to the host's committed CLAUDE.md where possible. The exact wire menu (the install-method AskUserQuestion: hard-install settings / @import / manual / future GitHub) is planning.
  • Scratch never ships. .scry//.mimic/ are gitignored + created on-demand, so a minted jacket starts with neither. .scry/ arises if you run Scry while working the host; .mimic/ simply doesn't arise — Mimic's examination posture isn't what a jacket is for (you're embedded in the host, working it natively).
  • Uninstall: delete .jacket/ + remove the wire(s). Clean by construction.