⛔ ARCHIVED 2026-06-21 — historical, do not use as current. This is the pre-pivot Yggdrasil-restructure umbrella. On 2026-06-21 the effort became a full pivot to Vrataski; this doc's still-good content (subprojects 0/I/A/C, the doc roster + imports matrix, the cashed-in backlog) was merged into working/vrataski-design.md, the single source of truth. Kept for history (it has the original framing + the fuller pre-pivot subproject map).

Yggdrasil Restructure — Design (working)

What this is. The living design + tracker for the multi-subproject Yggdrasil restructure, worked via /brainstorming starting 2026-06-20. It captures settled decisions, maps the subprojects (the "plates spinning"), and tracks open threads so nothing evaporates between sessions. Mid-brainstorm — not a finished design. When a subproject's design firms up it may spin into its own *-design.md → *-plan.md pair; this doc stays the umbrella map.

Purpose & scope

Replace the current-plan.md monolith (1,649 lines, loaded every session) with:

1. an audience-routed multi-document architecture at the repo root,
2. a .jacket/ "collections" system (the homestyle lists, as index + per-item files),
3. deterministic tooling (scripts) for the collections, and
4. a folded-in, simplified layer model (the dead execution-partner layer killed).

This cashes in ~7 tracked items (see Cashed-in backlog below). It is not the Vrataski unification (deferred) and not the puppet/scry rework (held).

Subproject map (the plates)

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

Decisions log (settled)

0 — Doc architecture

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

• Audience-routed docs; duplication across them is fine — each consumer reads exactly one (except when working on Yggdrasil and updating intentionally). No dedup pressure.

• 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 Yggdrasil 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; history archives out)	No
  INSTALL.md	setup (human/self)	One-time fresh-host bootstrap procedure	No

• FIRMWARE.md is the final name (was PHILOSOPHY → SOUL → FIRMWARE). Chosen for inert without a human driving it — firmware = baked-in behavior that needs a driver; pairs with the .jacket/ exosuit metaphor. (SOUL rejected as too alive/autonomous.)

• Three-way operational split: SYSTEM.md = what is (steady-state plumbing reference) · INSTALL.md = how to build it (bootstrap procedure) · FIRMWARE.md = why/how it behaves (character). 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	⟼	⟼	→	→

  Plus: uniform audience-header cross-links among the big three; FIRMWARE is a transcluded leaf (no outbound imports); INDEX is the auto-generated map to everything.

• Key mechanism (verified against working/claude-code-memory-docs.md): a bare @path imports + eager-loads only inside CLAUDE.md (the sole auto-loaded doc), recursively up to 4 hops. In AGENTS.md/README.md (never auto-loaded) @import costs zero context — purely a Kingdom-render/reading choice. Guardrail: never @-import an audience doc into CLAUDE.md, or its imports recurse in. In CLAUDE.md, reference docs must be markdown links / backticked, not bare @, or they'd import.

• Conventions:

  • audience is a YAML frontmatter field on every root doc + a top-of-file orientation block with sibling pointers ("lost? see…"). Frontmatter doubles as Kingdom hovercard fuel (quick glance on hover). (Verify: frontmatter doesn't disturb CLAUDE.md auto-load — parking lot.)
  • CLAUDE.md self-awareness: links (not imports) SYSTEM/INDEX/INSTALL so Yggdrasil knows it maintains them — operative content, earns its place.
  • SYSTEM.md is current-only; stale infra facts archive out as they become irrelevant.

I — Identity & layer reframe

• Execution-partner layer killed. Odin Codin' was the only ever instance and is a never-built skeleton (two docs + empty dirs); even fully built it was "a couple skills." Yggdrasil now runs everything. New model: Personal → Yggdrasil → Project-specific (two layers).
• Designer/executor demotes from a layer to a phase pair within Yggdrasil (design → hand off a plan → execute). The plan stays the bridge; both phases human-in-the-loop.
• Domain-agnosticism is deferred, not enforced. Yggdrasil-now is a permissive personal workshop/playground — free to mix agnostic design tooling with domain-specific stuff. The agnostic discipline is a future Vrataski commitment (a curated subset extracted later; see working/vrataski-vision.md). So no methodology-vs-findings line is drawn now.
• Promotion guard dies (nothing downstream to promote from) → collapses to "build natively, stay bloat-aware." Bloat discipline now means navigable/lean/tidy (housekeeping), not domain-pure — those two were tangled in the old guard; they separate cleanly.
• Odin's residue: Hugin/Munin survive as naming for a future code-crawling skill's agent/memory split; the FFXI-RE backlog stays its own project (findings live in projects). The odin-codin repo isn't on this host anyway — "killing it" is doc/model-level.

A — Collections (.jacket/)

• .jacket/ is the official Yggdrasil directory name (dotfile/Kingdom-visibility wrinkle acknowledged + waved off by Brad).
• "Collections" (Laravel nomenclature) = the indexed item-group stores: bookmarks, backburner, session-lessons, done-log, deferred. (Not standalone docs.)
• Markdown item-files are the source of truth; the YAML index is derived, regenerated by rebuild-index. Shape (from Brad's exemplar): .jacket/<collection>.yaml (config + items index)
  • .jacket/<collection>/<slug>.md (frontmatter: name/title/description/tags/history + body).
• Undesigned: per-collection frontmatter schemas; how ## Deferred (in-context-by-design, not ledger-tracked) differs; how the Done-log/history collection works; archive interplay; the config/ledger's new home.

C — Lean CLAUDE.md core

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

Open questions & parking lot

Today's later-today pile:

• ⬜ Research whether CommonMark autolinks can be customized so @import renders as a hoverable link (for Kingdom). Add to end of today; not now.
• ⬜ Verify frontmatter doesn't break CLAUDE.md auto-load (claude-code-guide / docs).

Open design questions (for upcoming sessions):

• A: the per-collection schemas + the Done-log/history collection design.
• C: the actual lean-core structure + how "where we've been" is tracked (ties to A).
• I: whether FIRMWARE.md even names Vrataski yet (Brad's call — one-line gesture at most).

Parked threads (deliberately not today):

• ⏸️ SYSTEM.md + INSTALL.md content authoring (migration record + bootstrap) — bookmarked.
• ⏸️ Puppet/Scry checkpoint rework — held (Brad still cooking).
• ⏸️ Vrataski curation/separation — future.
• ⏸️ Kingdom.md dotfile-visibility + the @path transclusion-render feature.

Cashed-in backlog (items this refactor 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, update good-morning.
• bookmark 2026-06-18 — fold Odin Codin' into Yggdrasil.
• 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 (held, not cashed).

Understanding summary

• What: a multi-subproject restructure of how Yggdrasil stores its own state + describes itself.
• Why: current-plan.md is a 1.6k-line monolith loaded every session; conventions are stranded in non-auto-loaded AGENTS.md; the lists accumulate by hand; a phantom execution-partner layer adds fiction. The refactor makes the always-loaded surface lean, routes content by audience, makes the lists deterministic collections, and simplifies the layer model.
• Who for: primarily Yggdrasil-as-self (always-loaded behavior); plus foreign agents + humans who encounter the project; plus Brad maintaining it.
• Constraints: CLAUDE.md stays lean (function > prose); markdown = source of truth, indices derived; human-in-the-loop / no-demand-character; Kingdom-viewability held, not a current gate.
• Non-goals (this effort): the Vrataski unification; the puppet/scry rework; writing SYSTEM/INSTALL content; the command/skill review pass (own cycle, downstream).

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 (the two docs) + empty skeleton.