Vrataski — Design (working)

What this is. The single living design for Vrataski — the full pivot of the Yggdrasil restructure into "build Vrataski, a personal AI-workflow toolkit that ships in three modes." It carries the umbrella subproject map (the plates spinning) and the settled detailed designs in one doc. Supersedes the pre-pivot yggdrasil-restructure-design.md (retired) and absorbs vrataski-modes-design.md. Feasibility backing: claude-code-loading-research.md. Direction/why: vrataski-vision.md + vrataski-pitch.md. Mid-effort — the Modes subproject is settled; 0/A/B/C/R are still in progress.

Purpose & scope

Pivot Yggdrasil into Vrataski and, in one effort:

1. Rename Yggdrasil → Vrataski (repo, paths, GitHub remote, ~/.claude wiring).
2. Three modes — Standalone / Jacket / Mimic — over one canonical layout (the Modes subproject).
3. Replace the current-plan.md monolith with an audience-routed root-doc architecture (0).
4. A collections system for the homestyle lists (index + per-item md files) (A).
5. Deterministic tooling (scripts) for the collections (B).
6. A lean, always-loaded CLAUDE.md core (C).
7. Simplified 2-layer model (exec-partner layer killed) (I).

In scope now: the rename + the three-mode/layout design (settled below). Deferred within this effort: exact activation mechanics + INSTALL content (→ planning); Jacket self-update (future).

Subproject map (the plates)

Status key: ✅ settled · 🟡 partly designed · ⬜ not yet designed · ⏸️ parked

Understanding Lock — Vrataski modes (settled 2026-06-21)

• Scope = FULL PIVOT. Yggdrasil→Vrataski; rename in scope; Mimic un-parks the held puppet/scry rework.
• Identity = SPLIT BY REACH. Personal preferences stay global in claude-personal (symlinked into ~/.claude); 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). "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. Content layer identical; wiring layer necessarily mode-specific.
• Jacket = FROZEN VENDORED COPY (self-update parked; contrast anywhere-agents' live-pull).
• Commands → skills — only skills travel via --add-dir/plugins (skills.md:160); "commands merged into skills" (skills.md:16). Vrataski expresses everything as skills.
• Jacket needs TWO wires (constraint; levers → planning): (a) skills/commands activation (skills-dir plugin or --add-dir); (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 incidental). Stays in Vrataski's own tree, so it sidesteps the subagent-cwd wall (anthropics/claude-code#31940). Idiosyncratic — weakest prior art of the three.

Brainstorming ↔ planning boundary

Brainstorming settles shape + decisions (incl. shape-level findings like commands-as-skills, frozen-vs-live). Planning settles exact mechanics (activation lever, INSTALL steps, install menu).

Decisions log

M — Modes & layout (settled 2026-06-21)

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. Overrides subproject A's earlier .jacket/-as-collections use. Why: the mode needs the name more.
7. Scry rework + decouple from Mimic. .scry/ (ephemeral: repo clones + scratchpad, gitignored) vs research/ (durable: kept deliverables, committed). Scry usable in any mode. Why: portability; sidesteps #31940 (clones into its own tree).
8. dot/non-dot convention. Leading-dot = not project content — infra (committed) or scratch (gitignored, e.g. .scry//.mimic/); non-dot = durable/kept (research/, working/, bookmarks/, …). Exception: .claude/ (externally-mandated plumbing). .meta/ = our committed infra dot-dir. The dot is Unix-conventional (infra/scratch) and is NOT the ship/no-ship signal — product-vs-instance is declared separately (decision 13).
9. Research placement = soft edges. Defaults to research/; model suggests location, user disposes. Recommend-not-directive (no-demand ethos).
10. .meta/ — retire workflow.yaml (git archaeology: original layer-manifest from the killed exec-partner model, authored first commit aacd6eb 2026-05-27, never changed, never read by logic). This design claims nothing new in .meta/; a deployment-identity manifest is parked until a real consumer appears (likely Jacket-install in planning). Ledger/config → A; durable-docs manifest (overlaps INDEX.md) → 0.
11. Mimic = semi-sandboxed examination, not drive. Mirror in own scratch; target not add-dir'd; driving incidental. Preserves Puppet behavior; sidesteps #31940. Mirror mechanism → planning.
12. Scratch dot-dirs never ship. .scry//.mimic/ gitignored + created on-demand; not part of any placement — they materialize where/when a capability runs.

M — addenda (2026-06-21 design review)

13. Product vs instance — declared, not dotted. The tree holds the product (what is Vrataski, identical in every install: root docs, .claude/skills, conventions) and instance- private content (Brad's accumulated state + workspace: the collections, research/, working/, archive/, scratch). The boundary is declared explicitly — a distribution manifest (git export-ignore in .gitattributes + a per-dir ship / stub / exclude policy), not encoded in dot prefixes. Why: "ships?" is a packaging policy, not a naming fact; the dot is already overloaded (.claude/ is dotted yet is the shipped product's heart); a manifest can express ship-as-empty-stub, which a dot can't; git's export-ignore is the built-in tool for "tracked in my repo, absent from the distributed archive." Dirnames stay clean (bookmarks/, not .bookmarks/). Specifics → planning.
14. Each collection is its own top-level dir — bookmarks/, backburner/, session-lessons/, done-log/, deferred/ (not lumped, not under .jacket/). In-context ones pull in via @import, but which import is a lean-core call (deferred ✓ · done-log out, it's history · session-lessons TBD) → A/C. Why: parallel structure; each collection's items + index stay self-contained.
15. Hugin/Munin (raven) theming retired — a Yggdrasil relic; a future code-crawling skill names its agent/memory split functionally, not after the ravens.

0 — Doc architecture

• current-plan.md's content migrates into CLAUDE.md (the always-loaded self-doc). Temporary JACKET.md rename idea dropped.

• Audience-routed docs; duplication across them is fine — each consumer reads exactly one.

• Root-file roster:

  File	Audience	Job	Auto-loads?
  CLAUDE.md	self/model	Lean, function-over-prose: operative conventions + live state	Yes
  AGENTS.md	foreign agents	Very technical: what Vrataski does + how	No
  README.md	humans	Human-oriented intro to the same capabilities	No
  FIRMWARE.md	all	Curated "what & why" — role/behavior, inert-without-a-driver	via import
  INDEX.md	all / reference	Auto-maintained file/dir map	via import
  SYSTEM.md	self + agents (+humans)	How the plumbing works now (current-only)	No
  INSTALL.md	setup	One-time bootstrap + per-mode activation methods	No

• FIRMWARE.md is final (was PHILOSOPHY→SOUL→FIRMWARE) — "inert without a human driving it" (firmware = baked-in behavior needing a driver; pairs with the .jacket/ exosuit metaphor).

• Three-way operational split: SYSTEM.md = what is · INSTALL.md = how to build it · FIRMWARE.md = why/how it behaves. SYSTEM ↔ INSTALL cross-reference (result ↔ recipe).

• Links/imports matrix (⟼ @import/transclude · → plain link):

  FROM ↓ \ TO →	FIRMWARE	INDEX	SYSTEM	INSTALL
  CLAUDE.md (auto-loads)	⟼	→	→	→
  AGENTS.md	⟼	⟼	→	→
  README.md	⟼	⟼	→	→

• Key mechanism (verified, claude-code-loading-research.md): a bare @path imports + eager-loads only inside CLAUDE.md (the sole auto-loaded doc), recursively up to 4 hops. In never-auto-loaded AGENTS.md/README.md, @import costs zero context. Guardrail: never @-import an audience doc into CLAUDE.md; reference docs there as markdown links/backticks.

• Conventions: audience YAML frontmatter on every root doc + a top orientation block; CLAUDE.md links (not imports) SYSTEM/INDEX/INSTALL so it knows it maintains them; SYSTEM.md is current-only (stale infra archives out).

I — Identity & layer reframe

• Execution-partner layer killed. Odin Codin' (the only instance, a never-built skeleton) folded in. New model: Personal → Vrataski → Project-specific (two layers).
• Designer/executor demotes to a phase pair within Vrataski (design → hand off a plan → execute); the plan stays the bridge; both phases human-in-the-loop.
• Promotion guard dies → "build natively, stay bloat-aware." Bloat discipline = navigable/lean/ tidy (housekeeping), not domain-pure.
• Odin's residue: the FFXI-RE backlog stays its own project; the odin-codin repo isn't on this host anyway. Hugin/Munin (raven) theming retired (decision 15) — a future code-crawling skill names its agent/memory split functionally, not after the ravens.

A — Collections

• "Collections" (Laravel nomenclature) = the indexed item-group stores. Each is its own top-level dir (decision 14): bookmarks/, backburner/, session-lessons/, done-log/, deferred/ — not under .jacket/ (now the deploy dir, decision 6), not lumped together. Markdown item-files are the source of truth; the YAML index is derived (<collection>/index.yaml: config + items index), regenerated by rebuild-index.
• In-context collections via @import, but mind the lean core (C): @import only eager-loads inside CLAUDE.md, so importing a collection spends always-loaded budget. deferred/ is in-context by design (import ✓); done-log/ is history → stays OUT of the lean core (C extracts history out); session-lessons/ TBD. Which import — and how a multi-file collection is imported (the index? a rendered view?) — is an A/C call.
• Undesigned: per-collection frontmatter schemas; the Done-log/history collection; archive interplay; the config/ledger's new home (was .meta/).

C — Lean CLAUDE.md core

• Principle only: always-loaded core = checkpoint ("where we are") + collection pointers + operative conventions; completed design/build narrative and history extract out into collections/archive. The ~800 lines of finished decision-trail in current-plan.md is the big extraction target (disposition = the "spent worklists" thread).

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                 [P] auto-loads · lean self-doc + live checkpoint (current-plan.md folds in)
├── AGENTS.md                 [P] foreign-agent technical doc
├── README.md                 [P] human intro
├── FIRMWARE.md               [P] why/behavior (transcluded leaf)
├── INDEX.md                  [P] auto-maintained file/dir map
├── SYSTEM.md                 [P] current plumbing reference
├── INSTALL.md                [P] bootstrap + per-mode activation methods
├── LICENSE.md                [P]
├── .claude/
│   ├── settings.json         [P] project-scoped perms
│   └── skills/               [P] 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/                [i] collection — md source of truth + derived index.yaml
├── backburner/               [i] collection
├── session-lessons/          [i] collection
├── done-log/                 [i] collection (history — stays out of the lean core)
├── deferred/                 [i] collection (in-context; @import into CLAUDE.md)
├── research/                 [i] durable Scry deliverables (external-topic research)
├── archive/                  [i] drained/retired items + history
├── working/                  [i] Vrataski's OWN design/build/handoff docs
├── .meta/                    [P/i] committed infra · product config + instance state · workflow.yaml RETIRED;
│                             ·   ledger/config → subproject A; durable-docs manifest → subproject 0
├── .scry/                    [i] scratch (gitignored) · Scry's repo clones + research scratchpad
├── .mimic/                   [i] scratch (gitignored, Mimic-gated) · per-target examination/mirror; on-demand
├── .gitignore                [P]
└── .gitattributes            [P] · also declares the dist export-ignore boundary (decision 13)

Legend: [P] = product (ships to every install) · [i] = instance-private (Brad's; excluded-from or stubbed-in distribution per the manifest, decision 13) · [P/i] = mixed. The tree is byte-identical across the three modes (decision 3); only .mimic/ is Mimic-gated; scratch (.scry//.mimic/) is also gitignored + created on-demand. Embedded decisions: .claude/ skills-only; each collection its own top-level dir; Scry split .scry/(scratch) vs research/(durable); working/ = Vrataski's own design docs, research/ = Scry's external-research output; product/instance declared, not dotted (decision 13).

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 tree is byte-identical in all three; only the surroundings differ.

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 needing 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 in an examination posture: target kept semi-sandboxed, examined from within Vrataski's own scratch (.mimic/<target>/, .scry/) — not add-dir'd, not driven. Mimicking the target is the point; driving (mutating) it is incidental. Preserves Puppet behavior. Sidesteps #31940 (subagents stay in cwd). 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: wires range from zero host-file edits but ephemeral (--add-dir at launch) to persistent but touches a host-tracked file (@import in host CLAUDE.md). Self-containment preference → smallest, most reversible host footprint (ideally only the gitignored .jacket/ + one config entry; avoid editing the host's committed CLAUDE.md). Exact wire menu (the install-method AskUserQuestion) → planning.
  • Scratch never ships — a minted jacket starts with neither .scry/ nor .mimic/; .scry/ arises if Scry runs; .mimic/ doesn't (examination posture isn't a jacket's purpose).
  • Uninstall: delete .jacket/ + remove the wire(s). Clean by construction.

Open questions & parking lot

Ongoing design (upcoming subprojects):

• ⬜ A: per-collection frontmatter schemas; the Done-log/history collection; the config/ledger home (was .meta/); ## Deferred (in-context) vs ledger-tracked; which collections @import into the lean core (deferred ✓ · done-log out · session-lessons TBD — ties to C).
• ⬜ 0: authoring SYSTEM.md + INSTALL.md content (migration record + bootstrap/activation); whether INDEX.md subsumes the durable-docs manifest; whether FIRMWARE.md names Vrataski yet.
• ⬜ C: the actual lean-core structure + how "where we've been" is tracked (ties to A).
• ⬜ R: the command/skill review pass — now also carries the commands→skills conversion.

Modes — deferred to planning:

• ⏸️ Exact activation levers + INSTALL.md content + the install-method menu.
• 🔸 Distribution manifest (decision 13) — format (git export-ignore + per-dir ship/stub/exclude) and how the jacket-mint honors it.
• ⬜ From-source follow-up: can a skills-dir plugin also pull in root docs (→ Jacket = one wire)?
• ⏸️ Jacket self-update — future; Jacket vendors a frozen copy for now.
• 🔸 Deployment-identity manifest in .meta/ — build when a consumer appears (likely Jacket-install).
• ⏸️ skill-wiring / new-machine-setup home — decide post-install-design.

Parked — shippable-Vrataski curation:

• ⏸️ Domain-agnosticism → parked for later. Brad's call (2026-06-21): the Vrataski name is adopted now, but a shippable Vrataski needs domain-specific / personal bits stripped out — and that curation is deferred. The working Vrataski stays a permissive personal workshop for now; revisit the agnostic discipline when prepping a shippable cut.

Verification / Kingdom (later):

• ⬜ Can CommonMark autolinks be customized so @import renders hoverable (for Kingdom)?
• ⬜ Verify frontmatter doesn't disturb CLAUDE.md auto-load.
• ⏸️ Kingdom.md dotfile-visibility + the @path transclusion-render feature.

Cashed-in backlog (items this effort resolves)

• Deferred 2026-06-09 — "review the design of current-plan.md itself" (the anchor).
• bookmark 2026-06-18 — re-aim AGENTS.md external; migrate conventions to auto-loading CLAUDE.md.
• bookmark 2026-06-18 — fold Odin Codin' into Yggdrasil/Vrataski.
• bookmark 2026-06-19 — SYSTEM.md doc (references/role settled; content parked).
• bookmark 2026-06-19 — disposition convention for spent worklists/completed docs.
• bookmark 2026-06-06 — design-doc organization scheme.
• Deferred 2026-06-16 — convert by-hand markdown management into scripts (= subproject B).
• Deferred 2026-06-10 — puppet/scry checkpoint recording (un-parked → Mimic).

Assumptions

• Frontmatter loads harmlessly in CLAUDE.md (to verify).
• @FIRMWARE.md importing every session is acceptable (curated/short).
• Odin Codin' is fully captured in archive/odin-codin-source.md + empty skeleton.
• Activation findings in claude-code-loading-research.md hold at current Claude Code version.