Yggdrasil Current Plan

⚡ Active effort (2026-06-21): the Vrataski full pivot — see the Checkpoint + working/vrataski-design.md. The Phase-4 / Odin-Codin' / 3-layer framing below is pre-pivot, to be reframed by subprojects 0 + I. Trust the Checkpoint where they disagree.

Status: Phase 4 (Yggdrasil polish) effectively wrapped — its last active item, the GitHub-remote push, is resolved (private remotes live for yggdrasil + claude-personal by 2026-06-19); the planning skill is built (the flagship — skills/planning/SKILL.md, wording walk done 2026-06-08, wired in; design consolidated to working/2026-06-08-planning-skill-design.md), completing the coupled brainstorming-review effort; the parked-items/bookmark-unification thread is design-complete (see working/2026-06-05-list-hygiene-design.md); the git working-tree discipline thread design-complete — and the list-hygiene + bookend-worktrees build is COMPLETE (all 16 tasks executed + verified, merged to main 2026-06-09 — the accumulating-list hygiene system, the 7-step /hygiene-check, and the bookend worktree lifecycle are live; plan at working/2026-06-08-list-hygiene-plan.md with all ## Progress boxes checked, design at working/2026-06-05-list-hygiene-design.md). Yggdrasil and Odin Codin' are local git repos; the personal layer (now claude-personal) is wired in (Seafile fully retired 2026-06-18 — Phase A+B complete; the three repos relocated to flat C:\Projects\, old tree deleted; see the checkpoint); the harness is now onboarded onto the always-on Ubuntu cloud host at /var/projects (wiring + hooks live, line endings normalized to LF — see the checkpoint). Yggdrasil is the plan/design partner (see the design-decisions catalog); Odin Codin' build-out is Phases 5–11, the full-stack verification capstone is Phase 12. The date below the Checkpoint header is this doc's single "last touched" timestamp.

Versioning note: This is a single living document. When starting a new significant phase, consider renaming this file to YYYY-MM-DD-handoff.md and creating a fresh current-plan.md to preserve session history. For now, edit in place.

Current Checkpoint — 2026-06-21 (Vrataski full pivot; three-mode design settled + consolidated)

Just finished: A /brainstorming session that pivoted the restructure into building Vrataski (Yggdrasil→Vrataski rename now in scope). Designed the three modes — Standalone / Jacket / Mimic — over one canonical layout, settled subproject M (modes & layout), and consolidated everything into a single source-of-truth at working/vrataski-design.md (old umbrella + modes sub-design absorbed and archived with tombstones). Verified Claude Code's loading/discovery rules from raw source (working/claude-code-loading-research.md). Headline decisions: split-by-reach identity · one-artifact/three-placements · commands→skills · Scry decoupled from Mimic (.scry/ scratch vs durable research/) · dot/non-dot convention · workflow.yaml retired · Mimic = semi-sandboxed examination. Vrataski name adopted; domain-agnosticism parked for a shippable cut.

In progress: Vrataski design — subproject M settled; 0/A/B/C/R still open (subproject map in vrataski-design.md). All design; nothing half-built in code.

Next step: Either scope a /planning pass on the mode-independent parts (Scry split, commands→skills, workflow.yaml/.meta retirement), or resume /brainstorming on subproject 0 (doc architecture) or A (collections) — both gate the rest.

References: working/vrataski-design.md (single source of truth — read first) · working/claude-code-loading-research.md (loading feasibility) · working/vrataski-vision.md + vrataski-pitch.md (why/direction) · archive/2026-06-20-yggdrasil-restructure-design.md + archive/2026-06-21-vrataski-modes-design.md (superseded history) · archive/odin-codin-source.md.

Quick orientation for fresh-Claude

This document is the handoff between sessions of a multi-session project to build a layered AI workflow toolkit. Before continuing, read this whole document. The user (Brad) is iterative and prefers /clear between sessions, so each session picks up from this file rather than from prior conversation context. If something here seems wrong or stale when you sit down, trust your present-session judgment over what's written and update the doc accordingly.

The project has three current layers:

Personal layer (CLAUDE.md, personal preferences)
    |
    v
Yggdrasil (the plan/design partner + shared primitives)
    |
    v
Execution partners (Odin Codin' is the first — skeleton exists, content lands Phase 5+)

Yggdrasil exists, is wired up, and works. Odin Codin' has its architectural skeleton (README, AGENTS.md, .meta/workflow.yaml, empty subdirs) — skill/agent/command contents land in Phases 5–7.

State of Yggdrasil

Location and structure

Repo lives at /var/projects/yggdrasil/ and contains:

yggdrasil/
├── README.md
├── .meta/
│   ├── workflow.yaml                  (declares Yggdrasil as base, v0.1.0)
│   └── learning-new-skills.yaml       (last_run tracking; YAML owns the date)
├── skills/
│   ├── bookmarking/
│   │   └── SKILL.md
│   ├── brainstorming/                  (moved in from personal layer 2026-05-29)
│   │   └── SKILL.md
│   ├── learning-new-skills/
│   │   └── SKILL.md
│   └── planning/                        (the flagship — built 2026-06-08)
│       └── SKILL.md
├── commands/
│   ├── consistency-check.md           (mid-session doc-drift check)
│   ├── good-morning.md                (session-start bookend)
│   ├── learn-new-skills.md
│   ├── puppet.md                      (adopt a foreign project's toolkit; read-only)
│   ├── save-progress.md               (session-end bookend)
│   └── scry.md                        (puppet-mode research arm)
├── .claude/
│   └── settings.json                 (project-scoped perms: .puppet/** writes + git clone)
├── .gitignore                        (ignores .puppet/ workspace + settings.local.json)
└── bookmarks.md                       (active backlog, pruned regularly)

Links (working, as of the 2026-05-28 symlink realignment)

/var/projects/ holds the sibling repos claude-personal/ and yggdrasil/. ~/.claude/skills/ and ~/.claude/commands/ are real aggregation directories; each skill/command links in individually from its home repo, so every repo owns its own content and none nests under another:

~/.claude/CLAUDE.md → claude-personal/CLAUDE.md (symlink)
~/.claude/skills/<skill> → <repo>/skills/<skill> (one symlink per skill)
~/.claude/commands/<file> → <repo>/commands/<file> (one symlink per file)

This is the "subdirectory-level symlinks" design from the catalog. The skill-wiring skill creates/repairs the whole wiring idempotently — the single source of truth for ~/.claude/ setup.

Invocation patterns

/bookmarking <thing> — appends a dated entry to bookmarks.md. Skill-direct invocation works.
"bookmark this" or similar natural language — also triggers the bookmarking skill via description matching.
/learn-new-skills — invokes the command which invokes the skill (gives an ergonomic shortcut for a deliberate periodic action).
/save-progress and /good-morning — the session bookends: /save-progress pins state to current-plan.md at session end; /good-morning rehydrates it at the start. Both are standalone procedures (disable-model-invocation: true), not skill wrappers.
/consistency-check — mid-session (or invoked from within /save-progress) drift check across the durable docs; produces a cleanup list, never edits or commits. Standalone procedure (disable-model-invocation: true).
/puppet <target-dir> and /scry — foreign-project adoption (see the "Foreign-project adoption — /puppet + /scry" section). Standalone procedures (disable-model-invocation: true); read-only by default.
All other skills are invoked directly as /<skill-name> in gerund form, with no command wrappers needed.

Modifications already applied to skills

learning-new-skills/SKILL.md has disable-model-invocation: true (won't auto-fire) and allowed-tools: [WebSearch, Read].
bookmarking/SKILL.md has allowed-tools: [Read]. Write is intentionally omitted so file mutations still prompt for approval.

Hook infrastructure (scripts in the personal repo; registration host-local)

Custom hooks registered in ~/.claude/settings.json:

Stop-hook quality gate — Haiku evaluates whether a user question went unanswered or a promised action was skipped at turn end. Returns {"continue": false} to block stop and inject a reminder. (Pathless prompt hook.)
PreToolUse WebFetch guard — claude-personal/hooks/webfetch-github-guard.sh denies WebFetch on GitHub source-file URLs (the source-fidelity backstop).

The scripts live in the claude-personal repo (paths under /var/projects/). The registration (settings.json itself) is host-local but snapshotted to claude-personal/claude-config/settings.json, installed onto a fresh host as part of bootstrap (→ SYSTEM.md). The convention lives in claude-personal/CLAUDE.md → Machine Setup → "Settings sync (hand-managed, by choice)". (Retired Windows-era hook scripts are archived under claude-personal/hooks/archive/ — see its README.)

Git status

Local git repo initialized 2026-05-27; active with regular commits since (Phase 2 skeleton, plus the 2026-05-28 polish pass — AGENTS.md, plan restructure, bookmark hygiene).

GitHub private remotes live (confirmed 2026-06-19). yggdrasil and claude-personal each push to a private remote at git@github.com:clanofartisans/<repo>.git — both the host's reach-in path and the durable off-host backup. odin-codin is not yet migrated to this host. The long-deferred remote-push item is resolved (its ## Deferred bullet was drained to archive/bookmarks.md earlier 2026-06-19; local-first held until the Linux-host move made remotes worthwhile).

Plan progress

Done

Phase 0 — Lean research pass on agentskills.io standards, Claude Code skill/command conventions, public skill repos. Findings folded into design decisions.
Phase 1 — Personal CLAUDE.md cleanup. Separated personal preferences from project-specific stuff. Now lives at C:\Seafile\Claude\personal\CLAUDE.md (after the personal layer moved into a dedicated personal/ subdirectory), linked to ~/.claude/CLAUDE.md.
Phase 2 — Yggdrasil skeleton: README, .meta/, bookmarking skill, learning-new-skills skill, /learn-new-skills command, all symlinked, all verified working. First real /learn-new-skills run completed during session, findings applied back to skills.
Phase 3 — Odin Codin' architecture skeleton. New repo at C:\Seafile\Claude\odin-codin\ with README (Hugin/Munin framing), AGENTS.md, .meta/workflow.yaml declaring loose Yggdrasil dependency, and empty skills/agents/commands/templates/ directories preserved with .gitkeep stubs. Both repos now local-git-initialized; no remotes. Yggdrasil bookmark migration completed in commit 0511144. Odin Codin' initial commit d426931.

In progress (Phase 4) — Yggdrasil polish

Inserted 2026-05-28: get Yggdrasil and the personal layer into a polished, coherent state before resuming Odin Codin' build-out. Odin Codin' stays frozen as a skeleton until this is done.

Goal: tighten the base layer and the personal skills that sit alongside it.

Still open:

Bookmark hygiene as items resolve.

(The GitHub-remote push — once Phase 4's last open item — is resolved 2026-06-19: private remotes are live for yggdrasil + claude-personal. See the Git status section.)

Done 2026-06-19 (de-Windows doc sweep — COMPLETE): A /good-morning-resumed session on the session-2026-06-19 worktree, run as a section-by-section collaborative walk. Rewrote every live convention/operational doc across claude-personal + yggdrasil to the Linux-host reality (paths → /var/projects; Windows symlink mechanics → ln -s + skill-wiring; relink.ps1 → skill-wiring/relink.sh; bell hook + GitKraken/Seafile premises removed); CLAUDE.md, current-plan.md (Location/Links/Hooks), claude-config/README.md, and minor repoints (durable-docs.md, laravel.md, backburner.md, .gitignore, skill-wiring/SKILL.md). Archived the two dead Windows hook scripts to claude-personal/hooks/archive/ (retired-headers + README index). Historical docs left intact by design; the spent worklist drained to archive/de-windows-sweep.md (disposition-convention bookmarked). Surfaced that GitHub private remotes are live (plan's ## Deferred GitHub-remote item now stale) and the Bash-cwd-resets-between-calls trap (session lesson). Merged to main. (No plan-phase change — a toolkit-wide cleanup pass.)

Done 2026-06-19 (skill-wiring built + migration follow-ons): Built skill-wiring — a live, model-invocable claude-personal skill (SKILL.md + relink.sh) that symlink-syncs ~/.claude to the config repos (the Linux successor to new-machine-setup's relink.ps1; self-wired on first run; design in claude-personal/working/skill-wiring-design.md). Plus: git identity → Brad Turner <bradturner43@gmail.com> (global); GitKraken dropped; stale new-machine-setup/evals.json deleted; decided migration → a SYSTEM.md doc (bookmarked); hygiene bookmark drains + a permission-posture-audit bookmark. (Graduated from the prior checkpoint.)

Done 2026-06-18 (Seafile retirement Phase B executed + verified; GitHub-remotes thread opened): A /good-morning-resumed session that ran on main (no session worktree). Confirmed the Phase B relocation (relocate-claude.ps1) landed correctly — repos at C:\Projects\, memory migrated, hooks repointed, relink.ps1 re-run, C:\Seafile\Claude deleted; self-check-claude.ps1 didn't truly hang (slow recursive check #6) and shows all structural checks PASS. Scrubbed two stale Seafile permission leftovers the relocate's hook-only repoint missed (live settings.json Read(//C/Seafile/...); two settings.local.json Bash(... C:/Seafile ...) entries). Researched the GitKraken Claude-Code-hooks churn (v12.0.0 auto-installed them; v12.0.1 added the Preferences→External Tools off-switch + stopped auto-reinstall; this box is on 12.2.1) — but Brad wants the integration ON, so it's not churn to clean. Opened the GitHub private remotes thread (host-relocation foundation step): established gk CLI isn't installed, no GitHub credential is cached, GCM is the system helper; path narrows to install gh or web-create-then-push. (No plan-phase change — Seafile cleanup + thread kickoff.)

Done 2026-06-17 (Kingdom.md — demo-kingdom landing shipped + Mercury designed; separate repo): A /good-morning-resumed session (no Yggdrasil worktree; all work in the kingdom-md repo, consolidated on main). Shipped the Wiki landing — a standalone first-person KINGDOM.md overview essay (what it is / why built / ideas for use / where it's headed / honest current state), brainstormed then authored, registered as the first kingdom so / → /kingdom.md, merged to kingdom-md main (1beb12f design, 1c50a6d page+config). Then designed Mercury (the agent-memory kingdom) via /brainstorming → committed working/mercury-design.md (0ad828f): a believable, largely-straight fictional ~/.hermes-shaped corpus of an autonomous agent's mind — owner = semi-fictional "Chad", landing on SOUL.md, metadata.mercury reflavor, executive-functioning-partner spine, autonomy lean with one scoped wink — superseding the demo-kingdoms "Apollo" foil blueprint. Build-time gate logged: read canonical Hermes source + clone real profile distributions / skill taps first; the fiction contract (Chad/Karen/Sophia/Olivia; Last Dream XI / YonderXI / OSB; Project Yggdrasil + Kingdom.md the only real proper nouns) lives in the design doc. (No Yggdrasil plan-phase change — a separate project advanced via Yggdrasil tooling.)

Done 2026-06-17 (Kingdom.md — MVP COMPLETE: Tasks 6+7 built + merged; separate repo): A /good-morning-resumed session that finished the MVP. Task 6 (Blade views) landed earlier in the day (Warm Editorial viewer: recursive Blade tree + Alpine subnav + @alpinejs/collapse, reading pane, frontmatter card/hovercards, Decision-10 lineage; a ~10× Docker dev-loop speedup). This session built Task 7 (Pest feature tests) — the verification gate — and merged: 8 HTTP-layer feature tests in KingdomViewerTest (root redirect, README auto-open, file render w/ GFM table + frontmatter card, tree-omits-dotfiles, unknown/missing 404s, empty state, path-traversal rejection in raw + URL-encoded forms), an empty-kingdom fixture, a fixed fixture-broken unit assertion, and scaffold-ExampleTest cleanup → 27 tests green. Ran the plan's mandated negative control — bypassed the path guard, confirmed the traversal test flips to 200 (serving an out-of-root .md), then restored → 404 — proving the security check is real, not vacuous. Also fixed Laravel Boost's MCP server wiring for the Windows host: .mcp.json spawned vendor/bin/sail (a bash script the native host can't exec when Claude Code launches the stdio server), now docker compose exec -T -u sail laravel.test php artisan boost:mcp (handshake verified; needs user approval + a session restart to go live — worth harvesting into working/laravel.md). Two commits + a --no-ff merge of session-2026-06-15 → kingdom-md main (9c0c64a). A later same-session viewer polish + cleanup pass merged too, after which the worktree was disposed (merged + removed) and the dev stack verified from the main checkout (the full fresh-checkout bootstrap — env seed, vendor chown, npm, migrate — captured in kingdom-md's CLAUDE.md and harvested to working/laravel.md). (No Yggdrasil plan-phase change — a separate project advanced via Yggdrasil tooling.)

Done 2026-06-16 (Kingdom.md — design prototype finalized + accessibility + settings snapshot; separate repo): A /good-morning-resumed session that finalized the prototype as the locked Task-6 reference. Type system settled via a live in-prototype font switcher (built, then removed): body Newsreader, headings Spectral, mono IBM Plex Mono, chrome Figtree; Fraunces parked as a theme/display face (DESIGN.md). Nav/interaction: always-on frontmatter label, breadcrumb optical nudge, stronger folder/file hierarchy, furl/unfurl on folders + the inline subnav (in-place grid-rows, both directions), full-name title tooltips. Accessibility pass (made a standing habit at Brad's steer): tree/subnav rows are semantic <button>s with aria-expanded/aria-current, labelled tree, aria-hidden icons, and prefers-reduced-motion now neutralizes transitions too. nav-design.md: Decision 10 (collapse preserves the open doc's lineage — deferred to Task 6) + an accessibility baseline recorded as Task-6 must-preserve. Personal layer: reconciled the claude-config settings snapshot to live (added frontend-design, kept GitKraken out, skipWorkflowUsageWarning=false). Commits: kingdom-md dcc5c8d/b8eb1e0/de5c235, personal 2814978. (No Yggdrasil plan-phase change — a separate project advanced via Yggdrasil tooling.)

Done 2026-06-16 (Kingdom.md — design pass: frontend-design install + DESIGN.md + nav prototype; separate repo): A /good-morning-resumed design session doing the "UI research first" the 2026-06-15 checkpoint called for (kingdom-md repo, session-2026-06-15 worktree). Scoped /learn-new-skills → surveyed frontend-design skills + comparable markdown-app UIs (Obsidian/iA Writer/Sublime); installed Anthropic's frontend-design plugin (documented in new-machine-setup) and drained the research bookmark. Built a Warm Editorial DESIGN.md, a responsive standalone HTML prototype (design-prototype.html), and — via /brainstorming — a navigation design: brainstormed auto-promote re-rooting, then pivoted in-prototype to an inline-subnav model (deep folders open an in-place breadcrumb+contents panel; vertical single-column Miller; no re-rooting/horizontal scroll); nav-design.md + DESIGN.md reconciled to the validated model. All committed in kingdom-md (prototype still being polished — a fonts pass + minor tweaks pending). Yggdrasil-side: new ## Deferred task (script the hand-done markdown-doc upkeep, gated behind formalizing current-plan.md); frontend-design bookmark drained (29→28). (No Yggdrasil plan-phase change — a separate project advanced via Yggdrasil tooling.)

Done 2026-06-16 (hygiene-check — re-enabled model invocation): Removed disable-model-invocation: true from commands/hygiene-check.md so the command is Claude-invocable again — it can run directly when /save-progress offers it (or auto-fire when list-curation is clearly due), rather than requiring Brad to type it. It had been incorrectly grouped with the workspace-mutating bookends (/good-morning, /save-progress), which stay user-only. Safe to auto-invoke because every hygiene step is itself gated by an AskUserQuestion offer and prompting writes, so invocation alone mutates nothing (the AGENTS.md invocation-gotcha note is the mechanism: disable-model-invocation: true blocks one skill invoking another, which is exactly what broke the bookend offer→run flow). Surfaced live this session when /save-progress offered /hygiene-check but couldn't run it. (Yggdrasil-internal toolkit fix.)

Done 2026-06-15 (Kingdom.md — MVP Tasks 1–5 built; separate repo): A /good-morning-resumed build session that walked Yggdrasil's /planning-produced mvp-plan.md (Tasks 1–5 of 7) in the C:/Projects/kingdom-md repo with per-task commits on a session-2026-06-15 worktree: Laravel 13.15 scaffold in a Docker/Laravel Sail dev env (app-only, PHP 8.4, SQLite dormant, Pest + Tailwind v4/Alpine; Laravel Boost added for version-aware guidance); kingdom config + fail-loud boot validation; KingdomService (file-tree + the security-critical path-safety guard — hidden/.md/traversal/symlink gates, test-first with a negative control); MarkdownRenderer (commonmark + frontmatter + GFM); three routes + controller; and a landing-file refinement (researched the agent-instruction-file landscape — the AGENTS.md/CLAUDE.md/GEMINI.md/etc. that survive the hidden/.md filter — into a priority findLanding lookup map led by kingdom.md). Surfaced a reusable Sail-on-Windows gotcha worth a future working/laravel.md harvest: root-owned bootstrap files vs the sail web user → tempnam/500; fix = chown + run -u sail. Next: Task 6 (Blade views) after Brad does UI/visual design research; then Task 7 (feature tests) = merge gate. (No Yggdrasil plan-phase change — a separate project advanced via Yggdrasil tooling, like the 2026-06-10/-11 Kingdom.md entries.)

Done 2026-06-12 (Yggdrasil hygiene — methodology docs pass + hygiene.md drain): A /good-morning-resumed cleanup session. Resolved the long-deferred 2026-06-04 drift item (#5/#6): the advisory-subagent + review-lens methodology (deferred "until the planning skill ships" — shipped 2026-06-08) is now encoded into durable docs — AGENTS.md gained the "Advisory subagents & design-review lenses" Conventions bullet (parallelism-yes / autonomy-no

the four orthogonal lenses and where they run), README.md gained the "Parallel, never autonomous" note in Designer and executor; the concurrent-sessions cluster cross-ref (#7) was refreshed to note the carve-out's graduation into the durable docs. Drained working/hygiene.md completely — all three runs moved to archive/hygiene.md as concise per-run dispositions (summarized, not verbatim, since redundant); scratchpad back to empty. The deferred 2026-06-06 puppet posture/.claude/settings.json items were left riding on the puppet design-review bookmark (already archived). Resolved bookmark L34 drained to archive/bookmarks.md. (No Yggdrasil plan-phase change — a cleanup session.) Bookmarks 30→29; ledger restamped at session end via /hygiene-check.

Done 2026-06-11 (Kingdom.md — MVP plan built via /planning; separate repo): A second 2026-06-11 session that took up parked item (a). Dogfooded Yggdrasil's /planning on the validated MVP design (C:/Projects/kingdom-md/working/mvp-design.md) → a committed, executable 7-task plan (working/mvp-plan.md, kingdom-md c0014fc): scaffold → kingdom config → KingdomService (path-safe tree + traversal guard) → MarkdownRenderer (commonmark + frontmatter + GFM) → controllers/routes → Blade views (Tailwind Typography baseline) → Pest tests, on a worktree with Task 7's suite as the merge gate. Ran the planning skill's Self-Review + a single-thread lens audit (Skeptic/User-Advocate/Steward/Constraint-Guardian), dispositioning every finding. Resolved the four design open-items inline; per Brad's steers: dropped the default config key (→ first configured kingdom), hardcoded kingdom paths for MVP (the real config mechanism — env prefix-scan vs JSON + the Docker entrypoint config:cache detail — parked in the plan's ## Deferred with research preserved), simplified the tree filter to dotfiles-only, and adopted a hybrid test approach (test-first for the logic units; a red-before-green negative control on every test, incl. the traversal-rejection check). Yggdrasil-side captures: created working/laravel.md — a deliberately light notebook toward a future generic Laravel-project agent (harvest reusable patterns; a project's own design-doc decision log is the primary mine) (b9edb39) — plus two bookmarks: Vrataski.ai (proposed name if Yggdrasil is ever published; Edge of Tomorrow — human-driven exosuit vs autonomous robots, "live/die/repeat" iteration; cross-linked to the backburner public-release item) and research the popular frontend-design skills (7ad216b). (No Yggdrasil plan-phase change — a separate project advanced via Yggdrasil tooling, like the 2026-06-10 kickoff below.)

Done 2026-06-11 (list-cleanup — bookmark triage + /hygiene-check + catalog review): A /good-morning-resumed cleanup session; committed the orphaned Kingdom.md pin to main first (1d84061). Bookmark triage walked 7 items (33→28): pruned 4 to archive/ (general self-check command, Stop-hook re-tune, new-machine-setup polish, "commit"-disambiguation [already shipped in AGENTS.md]); demoted the Learning project to backburner.md; promoted "Option A/B labels" into a personal/CLAUDE.md convention ("Substance over placeholder labels", committed there 4efd4a5); resolved the "Bookends & doc-hygiene refactor" cluster (command-structure + scratchpad parts had shipped; folder-layout lives in the design-doc org bookmark; extracted the PreCompact/SessionStart hooks sub-item as a standalone bookmark). Commits b539d6d (triage) + 3b05ab3 (census + 4 dangling-ref fixes). /hygiene-check — ran the consistency check only (prune/demote/backburner/ session-lessons/catalog-drain steps were not due or held); durable docs clean, 4 dangling cluster cross-refs reworded, full census added to .meta/ledger.yaml. Catalog review (on-demand): archived the "Recap" terminology note (38→37, → archive/catalog.md); the rest are standing conventions or needed by pending work. Mid-graduation review found the catalog largely duplicates AGENTS.md and surfaced two held items (bookmark #38 + the bucket-C four-flag staleness) — folded into the ## Deferred redesign item as input. (No Yggdrasil plan-phase change — a cleanup session.)

Done 2026-06-10 (Kingdom.md — separate project kicked off; design complete): Used Yggdrasil's /brainstorming to spin up Kingdom.md, the roll-your-own self-hosted Laravel markdown viewer bookmarked the same day — now its own repo at C:/Projects/kingdom-md (git-init, main) with a validated, committed MVP design (working/mvp-design.md, e4af60f). Lean MVP — Laravel 13, Blade/Alpine/Tailwind, reads filesystem "kingdoms" (file-tree + kingdom dropdown), full-page league/commonmark render + a frontmatter card via Tailwind prose, login-less, no cache — with a sequenced additive roadmap (auth via Fortify→OAuth→OIDC, per-kingdom RBAC, wikilinks/ backlinks, theming, Docker). Mid-session research settled the Laravel 12+ starter-kit model (fresh-install-only full templates → chose clean install + Fortify/Socialite-later) and Laravel 13 as the target. Whole design walked verbatim section-by-section with Brad before commit. Next there: /planning → working/mvp-plan.md, run in that repo. (No Yggdrasil plan-phase change — a separate project spun up via Yggdrasil tooling.)

Done 2026-06-10 (line-ending fix + sync-substrate brainstorm — research/design, no build): Two things. (1) Obsidian phantom-diff fix — a *.md text eol=lf .gitattributes carve-out in all three repos (committed: personal f76c35e, odin-codin 11933a6, yggdrasil on the session branch; working trees renormalized to LF, scripts unaffected), with a personal/CLAUDE.md note recording the carve-out from the autocrlf policy. Stops Obsidian's LF saves showing as phantom M, enabling Obsidian-as-viewer. (2) Sync-substrate brainstorm — set out to replace Seafile (the planned Dropbox move), but research surfaced that any file-syncer over a live .git/ is a corruption anti-pattern, reframing the question to where the Claude environment should live. Converged (via /brainstorming, paused pre-lock) on a self-hosted always-on Ubuntu host + Remote Control + GitHub private remotes; rejected Seafile, Dropbox, Obsidian Sync, and cloud-web (each with reasons). Captured in working/host-relocation-design.md. Bookmarked the roll-your-own Laravel markdown viewer (OAuth + RBAC) as a separate project; updated the Seafile-phaseout bookmark to point at the design. (No plan-phase change — this was research/design, not a build.)

Done 2026-06-10 (in-Yggdrasil scrying — research + skill tweak + packet-RE PoC): A research/ tinkering session (no build). Filed 2 research notes to working/research/: closest-analogs-to-yggdrasil.md (Yggdrasil's HITL brainstorm/plan stance vs. the SDD movement — Spec Kit/Kiro/Agent OS/BMAD — with superpowers as its direct ancestor, plus the orchestration-not-autonomy camp; verdict: distinctive in combination/stance, not parts) and closest-analogs-to-odin-codin.md (the codebase-doc-generator landscape — DeepWiki/Swimm/PocketFlow/ Inkeep; Odin Codin's edge = collaborative HITL crawl + AI-facing SKILL.md output). Tweaked learning-new-skills: fixed 2 drifts (retired-YAML → .meta/ledger.yaml stamp; stale research\ path → working/research/) and made skills.sh the primary skill-index source (mined for ideas, not installed). Dogfooded it on a targeted run — cloned spec-driven + RE skills (addyosmani/agent-skills, dceoy/speckit-agent-skills, vgrichina/re-skill) to working/research/repos/ (newly gitignored) and sketched a "better RE spec-gen approach" (XI-RE SKILL template + SDD gates + re-skill scaffolding, Odin-Codin'-compatible). FFXI packet-RE proof-of-concept: cloned atom0s/XiPackets, decoded PacketViewer/Kouseki captures, and wrote working/research/specs/hnm-fafnir-immunities/SKILL.md — a packet-spec (Fafnir status-immunity profile) for private-server dev handoff. Gitignored working/research/{repos,artifacts}/ (cloned repos + 30 MB captures stay local). Backburnered: the find-skills quality heuristics + the two FFXI-RE expansion directions (Ghidra-MCP binary/DLL RE + packet-crawl mode). New ## Deferred task: rethink how puppet/scry research sessions record their checkpoint (tied to the current-plan.md redesign). Post-session: all this session's research output was relocated out of the repo to C:/Projects/yggdrasil-research/ (local-only) and working/research/ + its gitignore rules were removed — re-pointing the tooling that writes there is now the Next step.

Done 2026-06-09 (list-cleanup — triage sweep + list census): A /good-morning-resumed continuation. Ran a bookmark triage sweep (a lighter lever than doing each item's work — defer cold items instead): backburnered 3 (/skill-eval, journaling agent, FFXI client-RE), consolidated creating-workflow-skills into its existing backburner entry, drained 2 superseded one-liners (.meta schema-evolution, markdown-companion) to archive/bookmarks.md, and sharpened the model-effort bookmark's intent (push model/effort routing into the toolkit substrate; step one is a research pass — parked). Bookmarks 39→33, backburner 5→8. Recorded the trailing-newline list-delete session lesson (an Edit-technique gotcha that mashed adjacent bullets, caught by a bullet-count cross-check). Closed with a full list census — Bookmarks 33 · Backburner 8 · Session-lessons 34 · Catalog 38 · Done-log 13 — flagging Catalog (no bloat band) and Session-lessons (nothing graduated yet) as the quiet growers.

Done 2026-06-09 (list-cleanup — Yggdrasil-core edits ✅): A /good-morning-launched bookmark/list-cleanup session (prioritized for quick wins + Yggdrasil-core improvements). Config-driven bloat bands in /hygiene-check [L53]; four-flag skill-config vocabulary + commands==skills merge in the catalog [L45]; design/plan filename convention in both skills [L42 suffix half — dateless-active, date-on-archive]. Personal-layer: AskUserQuestion → low-cardinality rule [L16] + therapy-model seed [L15] + a CLAUDE.md Working-Style boundary line. Bookmarks 41→39 (L45/L53 drained to archive/, L42 trimmed); ledger restamped. Two new ## Deferred tasks: review current-plan.md's own design, and the /good-morning concurrent-session gap.

Done 2026-06-09 (list-hygiene + bookends — first live shakedown ✅):

A normal /good-morning → work → /save-progress session doubled as the first real-world test of the just-merged mechanisms — all passed, no build defects:

✅ /good-morning (C1) — created session-2026-06-09 off HEAD (no remote needed); ledger surfacing correct (flagged the 38-bookmark firm band; no due cadences, no ripe deferrals); surfaced working/hygiene.md's lingering 2026-06-04/06 runs (look post-C4 drainable — a /hygiene-check candidate).
✅ Scope-aware /bookmarking (A6) — routed a cross-project interaction preference to personal/bookmarks.md, not Yggdrasil's store.
✅ ## Deferred tier (A7) — first real demotion (GitHub-remote push: Phase-4 "Still open" → ## Deferred with reason + soft trigger; 5 references reconciled).
✅ /save-progress (C2) — this session's pin + merge disposition.
Process refinement (not a defect): the deferral exposed reason-synthesis vs. -elicitation → the 2026-06-09 "elicit the reason" session lesson + the "lean on AskUserQuestion less" personal bookmark.
Not yet exercised live (future session, no obligation): /good-morning resuming a kept worktree, and the multi-worktree disambiguation path — this run created fresh and disposes via merge.

Done 2026-06-09 (list-hygiene + bookend-worktrees build — EXECUTED + merged):

Walked the full 16-task build (A1–A7 · B1–B4 · C1–C5) on a session-2026-06-09 worktree — per-task commits + Confirm-by verification, closed by a clean C5 final pass — then merged to main via the C2 merge disposition (the first live exercise of the mechanism the build itself created).
Phase A — the accumulating-list hygiene system: backburner.md, archive/ (4 source files + README + the non-canonical hygiene.md), .meta/ledger.yaml (config + stamps, retiring learning-new-skills.yaml), flattened ## Session lessons, dated catalog, capture-only scope-aware /bookmarking, the canonical ## Deferred.
Phase B — the 7-step /hygiene-check command; banked a real test bookmark prune (39→38) and the first Done-log age-drain (2 aged blocks → archive/done-log.md).
Phase C — /good-morning + /save-progress rewritten (worktree lifecycle, ledger surfacing, pin + merge/keep/discard disposition); puppet bootstrap decoupled (C3); AGENTS.md / .meta/durable-docs.md / personal CLAUDE.md house-style consolidated (C4).
Two follow-ups parked in bookmarks.md: the bloat-band config-driven cleanup; the bookend git-permission pre-approval review. The puppet [priority] good-morning-reuse bug is now resolved (C3).

Done 2026-06-09 (list-hygiene + bookend-worktrees build fully planned):

Built the complete build plan by dogfooding /planning → working/2026-06-08-list-hygiene-plan.md: 16 tasks (A1–A7 · B1–B4 · C1–C5), ## Progress checklist + resumption convention, self-reviewed, lens-audited via four independent subagents with every finding dispositioned. The list-hygiene + bookend-worktree designs merged into one cohesive, executable plan (Phase A independent migrations → Phase B /hygiene-check → Phase C the /good-morning+/save-progress convergence + puppet fix + final verification). Build not started; next session walks it from A1.
master → main across all three repos (git branch -m, local-only), with every lingering doc reference reconciled.
Design-doc updates (working/2026-06-05-list-hygiene-design.md): the archive/ directory (renamed from history/) with its README index + verbatim standard-header + the non-canonical-file convention (§5.5); the ## Deferred plan-deferral wiring; the §7 config-in-ledger decision logged in §11 (Constraint-Guardian-lens catch).
Resolved the worktree location to .worktrees/ (not .claude/worktrees/) via canonical native-worktree research; settled the four bookend write-time details; reclassified the puppet fix to a real plan task (C3).
Captured for durability: the planning-skill-improvements bookmark (checkboxes / resumption / final-pass / lens-cost — fold back into the skill) and the lens-audit token-cost session lesson.

Next build — the planning skill + brainstorming review (one coupled effort)

DONE 2026-06-08. The planning skill is built (skills/planning/SKILL.md) and the coupled brainstorming review is complete. Kept below as the decision trail; the build is finished. Design consolidated to working/2026-06-08-planning-skill-design.md.

This is the headline next Yggdrasil build. Its two halves are coupled — do them as one effort, not as separate backlog items. (This section consolidates what used to be scattered across the checkpoint "Next step" and two standalone brainstorming bookmarks.)

The planning skill (flagship). A writing-plans-style skill Yggdrasil doesn't have yet — the engine that turns a validated design into an executable, checkpoint-able plan: domain-agnostic, generic-template-aware, human-in-the-loop, no autonomous execution, tasks sized to a meaningful review checkpoint. Distinct from this current-plan.md (a handoff-state doc, not a plan-authoring skill). Borrow structure from superpowers' writing-plans (cloned at C:\Projects\superpowers\skills\writing-plans\SKILL.md); drop its TDD/autonomous-execution wrapper.

The brainstorming review (the front of the pipe). brainstorming is the skill that feeds the planning skill, so it gets reviewed as part of this build, not separately. It's a superpowers-lineage import that needs work, split by dependency:

Independent of the planning skill — can groom anytime: diff against the canonical superpowers brainstorming SKILL.md to see what drifted; decide whether to drop or keep the emoji headers + "you are not allowed" Cialdini-style pressure-language (deferred mid-walkthrough 2026-06-02 — revisit); ~~remove the dangling multi-agent-brainstorming reference~~ (confirmed already gone from both our copy and canonical superpowers as of 2026-06-02); confirm its home now that it has moved into Yggdrasil.
Coupled to the planning skill — settle together: the handoff seam (what brainstorming produces must match what the planning skill consumes); and re-add the dropped Non-Functional-Requirements step in a domain-general form — a "constraints & success criteria" prompt, since a trip or a budget has no "scale" and the old performance/scale/security checklist didn't fit a domain-agnostic partner.
Reviewer lenses (harvested from multi-agent-brainstorming, single-thread form): the community multi-agent-brainstorming skill (sickn33/antigravity- awesome-skills) decomposes design review into constrained roles — Skeptic ("assume it fails — why?"), Constraint Guardian (the NFR pass), User Advocate (cognitive load / usability), Arbiter (resolve & decide). We're not importing it — it's genuinely multi-agent, which belongs to the parked subagent / agent-teams cluster, not Yggdrasil's single-thread, human-in-the- loop stance. But the roles work as review passes one facilitator walks a design through, no agents needed: the Constraint Guardian pass is the natural source for the domain-general "constraints & success criteria" step above, and the others are candidate lenses for brainstorming's incremental design review. Open question to settle in the build: which lenses belong in brainstorming, in the planning skill, or both. (Update 2026-06-02: the Constraint Guardian lens is now realized as Step 2's "Constraints & success criteria" focus. Skeptic / User Advocate remain genuinely OPEN — candidates for brainstorming Step 5 (Present the Design, as pressure-test passes) or the planning skill; deliberately NOT pre-routed to planning. Decide during the planning-skill design. Arbiter = Brad himself — the human who reviews and approves each pass; keep the term and concept in the design docs as attribution to the lens lineage (the multi-agent-brainstorming skill, credited as the source). Source skill is cloned at C:\Projects\antigravity-awesome-skills\skills\multi-agent-brainstorming\SKILL.md — read the per-role May/May-NOT mandates from source before deciding, not this paraphrase.)

Sequencing. The planning skill defines the handoff target, and we'll use /brainstorming itself to design it — so: do the independent brainstorming cleanups first (quick, no dependencies), then design the planning skill via /brainstorming, settling the handoff seam + the constraints step in the same pass. The two finish together. Likely its own phase ahead of resuming Odin Codin'; don't renumber the phases until the work starts.

Walkthrough decisions (2026-06-02; complete). Went through the brainstorming skill section by section with Brad (his first full read of it), frontmatter through Exit Criteria.

Applied (frontmatter through Step 3):

Frontmatter. Kept the description as-is. Added allowed-tools: [Read, Glob, Grep] (read-only context pre-approved; Write/Edit/Bash omitted so the design-doc write + commit keep prompting). Left model-invocation ON.
Opening consent gate. New subsection at the top of The Process: on auto-fire, name what's being designed and ask brainstorm-or-proceed; on explicit invocation, treat as a quick subject confirmation. Keeps the safety net but makes auto-fire consented rather than silent.
Anti-Pattern. Softened "This Is Too Simple to Need a Design" from no-exceptions to "strong default, not a mandate" (the gate may wave a genuinely trivial item through).
Scope Check. Added a non-software decomposition example (finances) for domain-agnosticism.
Step 2 constraints. Re-added the dropped NFR step in domain-general form (a "Constraints & success criteria" focus with cross-domain examples) — realizes the Constraint Guardian lens. Named AskUserQuestion as the multiple-choice vehicle.
Step 3 Understanding Lock. "built" → "designed"; lifted the closing directive into a > **Gate:** marker.
Gate-marking house style (AGENTS.md). Hard stops use a blockquoted > **Gate:** / > **Hard rule:** directive; soft checkpoints stay prose.

Applied (Step 4 through Exit Criteria):

Step 4 (Approaches). Genericized the trade-off axes (cost / effort / risk / flexibility / reversibility / maintenance + translate-to-domain note); restored "explain why it's your recommendation"; added an explicit "present conversationally, not a multiple-choice pick" note (kept discussion-shaped on purpose — AskUserQuestion deliberately not used here).
Step 5 (Present the Design). Adopted canonical's scale-to-complexity section sizing over the hard word cap; genericized the software-only "Cover:" list (main parts / how they connect / failure & edge cases / how you'll know it works + translate note). Lenses deliberately NOT placed — left open (see the lens bullet above).
Step 6 (Decision Log). No change — already domain-general; an addition over canonical, which has no explicit decision-log step.
After the Design. Added a commit-timing note (save now, commit at final review); added a new Final Review (with the user) step — a collaborative section-by-section read of the finished design, distinct from the solo Self-Review; reworded Implementation Handoff to recommend /planning and let Brad invoke it (modeled on save/commit recommendations — no auto-chain).
Exit Criteria. Added "design documented and walked through with the user" to tie the gate to the new Final Review step.
Tone call (SETTLED). Keep the calm > **Gate:** / > **Hard rule:** house style — no emoji headers, no Cialdini "you MUST / not allowed" pressure-language. (Was deferred twice; now closed.)
Visual Companion (CUT — deliberate; do not re-raise). Canonical superpowers brainstorming carries a browser-based Visual Companion (mockups/diagrams). We cut it wholesale on purpose: not general-purpose enough for the Yggdrasil / personal layer (browser-heavy, token-intensive, terminal-first stance). A visual-aid capability could resurface as a project-specific feature if a domain ever needs it — but not at this layer. Recorded so the diff-against- canonical task doesn't flag it as drift.

Carried into the planning-skill design (the remaining build):

All three bullets below were SETTLED 2026-06-04 — see the Design-decisions catalog ("Design-review lenses" + "Advisory subagents") and the "Planning-skill design" SETTLED line. They're kept here as the decision trail that led to those entries; they no longer read as open. The catalog is authoritative.

Lens placement & form. Skeptic / User Advocate are OPEN as to where they live — brainstorming Step 5 or the planning skill — decided next session from the cloned source. Brad's lean on their form (save it; not hard-decided; revised 2026-06-03): the two lenses (Skeptic + User Advocate) are combined into a single review pass — Claude internally roleplays both perspectives, then presents one consolidated response for Brad to review alongside Claude, rather than running them as separate sequential passes. (The earlier lean was sequential, one-lens-at-a-time passes; Brad revised it because with only two lenses a single combined pass is simpler — the sequential form made more sense back when he mis-remembered there being three unassigned lenses.) Still collaborative and human-in-the-loop — Brad reviews the combined output — and still explicitly NOT multi-agent and NOT parallel. The source's per-role May / May NOT mandates must be significantly softened, not kept wholesale: keep them only as focus hints (what each lens looks at), drop the rigid prohibition framing — those hard limits existed to police separate agents (we have none) and clash with the settled calm house style. This pass form is the collaborative walk (now named in personal CLAUDE.md → Working Style). Agreed: lens passes are offered/scaled — run when the design's weight justifies it, light or skipped for trivial ones (governed by the Anti-Pattern gate), never mandatory.
Constraint Guardian — two positions (bookends). Already realized as Step 2's upfront constraint elicitation (define the bar before designing). Open question: also add a back-end audit pass that checks the finished design against those stated constraints (catches "we forgot our own requirement")? Same offered/scaled logic applies.
Handoff seam / invocation. disable-model-invocation: true blocks programmatic/Skill-tool invocation (confirmed from canonical Claude Code docs). Brad's lean: planning ships with that flag set, so brainstorming can only recommend /planning and Brad invokes it explicitly — the convention and the mechanism agree. A lean, not a hard rule; formalize when the planning skill is built.

Planning-skill design — COMPLETE (built 2026-06-08)

COMPLETE 2026-06-08. Skill built (skills/planning/SKILL.md); design consolidated to working/2026-06-08-planning-skill-design.md (the authoritative design record). Kept below as the decision trail. Archival TODO (Brad): once Yggdrasil is judged feature-complete, move the consolidated design doc (and siblings) to a settled-design archive — folds into the design-doc organization-scheme bookmark.

Designing the planning skill via /brainstorming (its first real dogfood), section-by-section against superpowers' writing-plans (keep / adapt / drop). Borrow its structure; drop the code/TDD/autonomous wrapper. See the catalog's recursive plan mechanism for the reframing that grounds all of this.

Settled:

Identity. planning (gerund), /planning. Consumes a validated /brainstorming design doc → produces an executable, checkpoint-able plan. Domain-agnostic, human-in-the-loop, no autonomous execution. Tasks sized to a meaningful human review checkpoint (not the smallest agent unit); section detail scales to complexity.
Task anchor (the §9 spine) = verifiable outcome per task. Each task is a concrete, checkable result + how you'll confirm it's done, domain-translated (code: exact file paths/commands; trip: "lodging booked Jun 26–28, verify by confirmation email"). Keeps writing-plans' portable kernel — exact targets, per-task verification, no untracked placeholders — drops the code/test/commit machinery. Rejected: domain-detected templates (would push domain knowledge into Yggdrasil — violates the agnostic/driven split); generic fixed schema (too heavy/form-like — bookmarked as a possible upper-layer/toolkit feature).
Worktrees — an optional git affordance. The skill names the domain-neutral kernel — isolate in-progress execution from the source of truth — and offers git-worktree isolation when the plan's domain is a git repo. Because Yggdrasil's first-class work is git-backed (toolkit-builds, self-improvement) — and even one-off exceptions get a local git — this affordance fires often, so build it well. Ties to the parallelism bookmark. Rejected: pushing worktrees up to the domain-driven layer — that wouldn't serve Yggdrasil planning its own git-backed work.
No-Placeholders carve-out (§10). Allow deliberate, structured bookmarks/deferrals as first-class (Brad bounces around); forbid only untracked "TBD." The tracked-deferral mechanism shape is still open.
writing-plans walk verdicts. Keep the zero-context-executor kernel (drop "engineer/codebase/TDD"); keep Scope Check, Self-Review, and the "spell it out" rigor; adapt File-Structure (files → units/artifacts the plan touches), the plan header (drop Tech Stack / "for agentic workers"), and the save-path (drop hardcoded docs/superpowers/plans/; mirror brainstorming's "save to the context the plan belongs to"); drop the subagent/inline autonomous Execution-Handoff fork → replace with human-in-the-loop "walk the plan together, task by task."
Lens placement, Constraint Guardian audit, handoff seam — SETTLED 2026-06-04 (see the Design-decisions catalog: "Design-review lenses" + "Advisory subagents"). Lens placement: forward pass woven single-thread into brainstorming (Steps 2/4/5); backward finished-plan audit as a 3-way opt-in (skip / single-thread roleplay / independent subagents), scaled to how much the project matters; lens set = four orthogonal lenses (Skeptic, User Advocate, Steward, Constraint Guardian). Constraint Guardian audit: folded into that backward pass. Handoff seam: planning ships disable-model-invocation: true; brainstorming recommends, Brad invokes.

Tracked-deferral mechanism — SETTLED 2026-06-08:

The §10 tracked-deferral mechanism is the plan-deferral descendant of the list-hygiene type system, designed in full and written up in working/2026-06-05-list-hygiene-design.md §5.6. Shape: a dedicated ## Deferred section in the plan doc (in-context); base dated-prose bullets carrying a revival trigger that is encouraged, never required (soft triggers like "no spoons for this" are first-class); what makes an item tracked is placement in the section, not the trigger's quality; the No-Placeholders Self-Review enforces only that no vague "TBD" masquerades as an active task (it never polices a deliberate deferral's motivation); exits = promote → task / demote → bookmarks.md (an offered, never forced cool-down) / prune → archive; review resurfaces hard triggers by condition, soft triggers by age (~14d), informationally. This also extended the list-hygiene design with the out-of-context bookmark revision and a per-item aging anti-rot primitive — see that doc's §4 #8, §5.1, §5.6, §8, and the decision log. Nothing left open for the wording walk here.

Process agreement: once the rough shapes are settled, do a final section-by-section walk of the actual SKILL.md wording (an exact-text fine-tuning pass). It lands just past brainstorming's design lock and doubles as a live test of the handoff seam.

Parked-items / bookmark-unification design — design-complete (2026-06-05)

SUPERSEDED 2026-06-05 — design-complete. Full design in working/2026-06-05-list-hygiene-design.md (reviewed + committed 4306794); it expanded to subsume session lessons, the Done log, the catalog, and the archive. The bullets below are the decision trail that fed it; the design doc is authoritative. Build deferred to the §9 migrations + /hygiene-check.

A coupled-but-separate design thread, spun out of the planning-skill §10 deferral work when it became clear "deferred tasks" and "bookmarks" are the same underlying thing. Tracked here so the planning walk doesn't carry it; resume as its own effort. Couples to the planning skill at the in-plan deferral section.

Settled so far:

One primitive, scoped by altitude. A parked item is date · what · why · depends-on/blocks · status, one lifecycle (capture → triage → promote / prune); only the scope varies.
Three tiers, no global. (1) plan-internal deferral (a "not-yet" task in the active plan); (2) project-level out-of-scope / future-enhancement (belongs to the project, not this plan); (3) ~~truly global~~ — cut. Everything is project/layer-scoped: personal → personal bookmarks, Yggdrasil → Yggdrasil bookmarks, each toolkit → its own. Today's bookmarks.md is really Yggdrasil's store, not a global one (mirrors "domain knowledge lives in toolkits"). Parked items recur per-project the way plans do.
Future-enhancements are a consequence of human-in-the-loop. An autonomous system (superpowers) has no "build it later" tier; a human choosing not yet creates it — so tier 2 is expected, not a gap.
Flow: project-level → plan-deferral → task (promote toward action), and the reverse (a deferral bigger than this plan promotes up to project-level). bookmark → deferral → task is the middle of that spectrum.
/recap cut. Triage lives in the session bookends (/save-progress sweep, /good-morning) plus the lightweight human habits that already work — Brad asking "what's in bookmarks?" and Claude proactively flagging relevant ones; don't replace those with a heavier command. (Recap references removed from the docs 2026-06-03.)
Homes — SETTLED 2026-06-03: per-project single doc; personal stands alone. Each project keeps one document holding its plan + tasks + deferred items + project bookmarks together. The personal layer keeps a standalone personal/bookmarks.md — it has no plan doc, and bookmarks must never sit in always-loaded CLAUDE.md (would bloat the context every turn). Rationale: project bookmarks are capped small (~20 max, see the nudge), so keeping them in the plan doc costs a bounded ~5K tokens and buys single-file simplicity plus in-file promotion (bookmark→deferred→task becomes a move within the one doc). The rejected alternative — a separate bookmarks file per project — would shave that bounded cost but adds a second file per project and cross-file moves. Update 2026-06-08 — single-doc SUPERSEDED; separate out-of-context bookmarks.md stands. Designing the tracked-deferral mechanism flipped this: bookmarks are now out-of-context, on-demand (list-hygiene §5.1), so the "bounded ~5K in the plan doc" cost isn't bounded enough for Brad — a quick low-spoon session shouldn't load bookmarks at all. So bookmarks live in a separate bookmarks.md per layer/project and are surfaced only via the ledger (count/aged flags) or on explicit request; the plan's ## Deferred section (the hot tier) stays in the plan doc, and promote/demote between it and bookmarks is a deliberate cross-file move that doubles as load/unload (heat ↔ context-load). personal/bookmarks.md was stood up 2026-06-08 with its first entry. No bookmarks→plan migration needed.
Bookmark-bloat nudge — SETTLED, baked into the bookends, counted per-project. Escalating by count: <10 celebrate (especially a prune pass dropping from 10+ back to single digits) · 10+ heads-up · 15+ warn · 20+ firm > **Gate:**-style push to prune (and /good-morning flags a high count strongly — most of it can usually move into the plan/deferred). Calm-firm house style, not literal theatrics. The nudge automates the discipline so the cap holds without relying on memory. "Been a while" = 7 days: the extra celebrate/attention fires when the count has sat at 10+ for ≥7 days — long enough that Brad's likely been away, so the bookmark review doubles as reacclimation to the project. Needs a small .meta date stamp (when the count entered the 10+ band, or last-review date); low cost, doable.
Bookmark entry format — SETTLED: keep as-is. Dated freeform prose (- **YYYY-MM-DD** — text); not formalizing the other primitive fields (why · depends-on/blocks · status) — keep it light (2026-06-03).

Open:

Where promotions land and how (deferral→bookmark, bookmark→task, deferral→its own sub-project design); /bookmarking becomes scope-aware ("capture at the right project's store").
Pruned-items archive (idea). Instead of deleting pruned items, keep them forever in an append-only log kept out of context — e.g. an archive/ directory (archive/bookmarks-archive.md or similar). Git history already preserves deletions, so the value-add is a readable, browsable record vs. diff archaeology. Decide if it's worth the machinery and where it lives per scope. (Brad's idea, 2026-06-03.)

To build (when this thread resumes):

Merge Yggdrasil's bookmarks.md into current-plan.md (a Bookmarks section); retire the standalone file at this altitude.
Stand up personal/bookmarks.md; move any personal-scoped items currently in Yggdrasil's bookmarks over to it.
Make /bookmarking scope-aware (the right store per project/layer).
Bake the per-project bloat nudge into /save-progress + /good-morning.
Update .meta/durable-docs.md + any docs referencing bookmark locations.
Reconcile/replace the existing ## Bookmarks to fold into bookmarks.md staging section in current-plan.md — a hand-rolled promotion-staging mechanism that predates this design.

Git working-tree discipline — design-complete (2026-06-04)

Partly superseded 2026-06-08. The bookend-worktree wiring was revised this session: native-first reversed to raw git worktree across the board, plus a branch-prefix detection scheme and a two-moment cleanup split. See "Bookends — the active build (2026-06-08)" below for the current design. The decisions here remain the base (the un-fusing, the division of labor, the merge/keep/discard menu, the pin-vs-disposition split) except where that update says otherwise — chiefly the create/enter/cleanup mechanism, which is now raw, not native.

Settling how Yggdrasil's own git-backed work flows, using superpowers' worktree / parallel-agent model as the starting point and letting our methodology (human- in-the-loop, advisory-only subagents) reshape it. Source skills read from the clone at C:\Projects\superpowers\skills\ (using-git-worktrees, dispatching-parallel-agents, subagent-driven-development, finishing-a-development-branch); 2026 best-practice web pass also done (URLs not saved, per Brad). Ties to the catalog's Advisory subagents + Design-review lenses entries and the Parallel execution & concurrent sessions bookmark cluster. GitHub deliberately kept out of scope — everything here is local-only.

Settled:

The un-fusing (the load-bearing idea). superpowers fuses "parallel agents" and "git worktrees" into one mechanism because its agents write code (an implementer subagent mutates files → needs an isolated tree). Our two use cases pull that apart: concurrent Claude Code instances write → need worktrees; read-only subagents don't write → need no worktree. A read-only agent has nothing to isolate. So in our world worktrees serve writers; subagents ride on commits, not worktrees. superpowers can't see this split because it has no read-only agents.
Read-only lens subagents — snapshot = a clean committed state. Soft pin is the default: lenses use native Read/Glob/Grep on the live tree; stability comes from short-lived + clean-committed + (any concurrent writers isolated in their own worktrees, so the main tree doesn't move). Hard pin (git show <SHA>:<path>, or a detached worktree) is a documented backup — drift-proof but each flavor costs (git-plumbing reads lose native tools; the worktree flavor re-adds the machinery we cut), and nothing currently bookmarked needs it. A bracket-check (record HEAD+clean before dispatch, re-check after) stays available as near-free insurance if soft ever feels loose. The artifact-under- review is handed in-prompt; surrounding context is read live. Lenses need none of the worktree machinery.
Division of labor (the clean line). Writes ← human-driven sessions; subagents only ever read/critique. Parallel writing = Brad running N Claude Code instances (Mode A), each a full human-in-the-loop walk on its own worktree/branch — not autonomous implementer subagents. Within any instance we never spin a mutating worker (that would re-import the autonomy). Coordination ← durable on-disk state (plan doc, bookmarks, .meta/, git isolation), because concurrent instances can't see each other's context — the same /clear discipline we use across sessions, run in parallel instead of in sequence.
Adopt from superpowers near-as-is: the isolation kernel of using-git-worktrees (detect-existing-isolation-first; prefer native worktree tool; never fight the harness; gitignore the worktree dir; never write on main without consent) and the recombination menu of finishing-a-development-branch minus the PR option — i.e. merge-back locally (default) / keep branch / discard. Local merge needs no remote — this is exactly what de-couples us from the deferred GitHub-remote question.
Reject: subagent-driven-development's autonomous wrapper — "don't check in between tasks, execute continuously" + writing implementer subagents. That's the autonomy we don't want; our instances check in constantly (each one is the collaborative walk).
Parallel ceiling ~2–3, bottlenecked by Brad's attention (human-in-the-loop in every loop), deliberately lower than the research's 5–8 for autonomous fan-out. We trade raw throughput for never having unsupervised writes — a feature.
Bookend-worktree wiring (shape agreed; detailed design still pending). /good-morning creates or resumes a session worktree (new branch from main, or pick up an in-progress session-branch kept from last time); /save-progress offers merge-back / keep / discard (the finishing menu minus PR), collapsing a session's checkpoint commits into one clean merge. Two payoffs: bootstraps Mode A for free (each concurrent instance just runs /good-morning) and makes every session an atomic clean merge even when solo. Seafile = a non-issue: one-machine-at-a-time kills the cross-machine risk; a seafile-ignore.txt (added 2026-06-04, library root) excludes worktrees and pre-empts the Windows git worktree remove handle-race; and Seafile is being phased out anyway (bookmarked).
Domain-agnostic generalization — SETTLED 2026-06-04. The merge gate is the one substantive code-ism. superpowers' finishing-a-development-branch gates the whole menu on an automated pytest/npm test STOP ("cannot proceed until tests pass"). We generalize it on two axes: (1) wording — "tests pass" → "the work checks out" (softer than "verification," covers both machine-checkable cases like a confirmation email and pure-judgment cases like "the journal entry reads right"); (2) character — superpowers' gate is automated/binary/blocking because its verification is always machine-checkable and it runs autonomously; ours can't be, because soft-domain done-checks have no exit code, so it becomes a question Brad answers inside the collaborative walk, not a CI block. The done-check is authored in the plan (the planning skill's per-task "how you'll know it's done"), not invented at merge time — so at the bookend we're only confirming it held. Verification-status picks the recombination option: checks-out → merge-back; not-yet (mid-task) → keep branch; dead-end → discard (fits our session-as-unit model vs superpowers' feature-as-unit STOP). Sweep of the rest: git vocabulary (worktree/branch/commit/merge) is kept — it's Yggdrasil's substrate, not a code-ism. Only two other touches: "feature/ development branch" → "session branch" naming, and keep the re-verify-on-merge principle, reworded — "after merging, re-confirm the work still checks out on the combined state" (earns its keep mainly in the parallel Mode A case, where a branch clean in isolation can break once combined). Everything else (un-fusing, soft-pin lens snapshots, writes←instances/reads←subagents, reject-autonomy, ~2–3 ceiling) was already domain-neutral.

Bookend-worktree wiring — SETTLED 2026-06-04 (all four sub-questions closed):

(a) /good-morning new-vs-resume. Detect in-progress session-branches with git worktree list (sees sibling worktrees, unlike git status); cut a fresh session-branch off main if none, resume the in-progress one if present.
(b) /save-progress disposition menu. Presented as an AskUserQuestion (merge-back / keep / discard), the recommended option pre-pointed by the drafted checkpoint's shape — verification status is read off the "Next step" field, not asked as a cold menu. Mechanics: merge = cd to main, merge the session branch, re-confirm it still checks out on the combined state, remove the worktree, delete the branch; keep = leave branch + worktree, next /good-morning resumes; discard = "Are you sure?" AskUserQuestion, then write a fresh "abandoned X" breadcrumb to main's current-plan.md, remove the worktree, force-delete the branch.
(c) Squaring with the self-housekeeping auto-commit — the pin-vs-disposition split. /save-progress is two jobs: pin the handoff (write+commit the checkpoint — self-housekeeping, auto, no prompt) and dispose the work (merge/keep/discard — always asks). The auto-commit line falls between them: the pin auto-commits; the disposition (which deletes branches / destroys commits) is always human-gated, deliberately outside the auto-commit exception. Ordering: decide disposition right after the checkpoint draft is confirmed, so the pin is written once, to wherever /good-morning reads it next (keep→branch, merge→main, discard→fresh breadcrumb on main). Governing rule: the pin must live wherever /good-morning will next read it.
(d) Where worktrees physically live. .worktrees/ at each repo root, gitignored (verify with git check-ignore before creating; if not, add to .gitignore + commit first); adopt Step 0 isolation detection (detect existing isolation first; submodule guard; prefer a native worktree tool; never fight the harness). Dropped superpowers' legacy global path.

Fork decisions (2026-06-04):

Worktree-always (not branch-only-for-solo): uniform mechanism, parallel-ready for free, overhead already mitigated (seafile-ignore.txt, the handle-race).
Commit granularity Claude-managed at commit-time as broad topic/session-scoped commits — no hunk-level precision (interactive rebase is unavailable here; file-level staging is available, but Brad doesn't need fine git history, especially with a future self-maintained history artifact in mind). Merge-time lever is binary keep-or-squash, AskUserQuestion when ambiguous.
Discard confirmation = an "Are you sure?" AskUserQuestion (not typed "discard"); recoverable via reflog + the main breadcrumb.
Doc-hygiene-on-discard (Loose End 1) = accept the gap. Consistency-check fixes entangled in a discarded session die with it; the next consistency-check re-finds them (idempotent, self-healing). The cherry-pick-rescue alternative was dropped — it needed isolated doc-fix commits, which fights the broad-commits call.

Parked / bookmarked from this pass:

Loose End 2 → bookmarked: a uniform per-layer repo-maintenance routine (personal, Yggdrasil, each toolkit), not Yggdrasil-only.
Loose End 3 → parked for build time: the AGENTS.md / CLAUDE.md note that the disposition actions are prompted, not auto (so they sit outside the self-housekeeping auto-commit exception).
"commit" terminology collision (git op vs. the commit convention) → bookmarked; candidate house-style rule: bare "commit" = the git op, always qualify "the commit convention", lean on pin / disposition in mechanics.

To build (when this thread resumes): wire the session-worktree lifecycle into /good-morning (create-or-resume) and /save-progress (the disposition menu). (Update 2026-06-08: superseded — this is now its own build, not a rider on the planning-skill walk, and the mechanism reversed to raw git worktree. See "Bookends — the active build" immediately below.) Touches the Bookends & doc-hygiene refactor bookmark cluster.

Bookends — the active build (2026-06-08)

The session bookends (/good-morning, /save-progress) are the active focus now that the planning skill has shipped. This is the live design + open-question record for finishing them. It revises the 2026-06-04 "Git working-tree discipline" section above — most importantly reversing native-first to raw git worktree across the board. Build not started.

Mechanism — raw git worktree, sole-owned (REVERSES the 2026-06-04 native-first call). /good-morning + /save-progress own the whole worktree lifecycle via raw git; the native EnterWorktree / --worktree tools are dropped from the session lifecycle. Why the reversal: native's auto-cleanup is built for ephemeral worktrees, but ours are persistent + human-disposed; native can't re-enter a worktree from a cold start anyway (so resume is raw regardless); raw avoids native's exit-time keep/remove prompt (the friction behind "save-and-commit-everything, leave it open"); and raw is uniform with the cross-repo case. Cost accepted: no native auto-relocation, so Claude carries the discipline of always targeting the worktree's paths.

Native worktree behavior (researched 2026-06-08 — claude-code-guide agent, canonical docs; recorded so we don't re-investigate): EnterWorktree relocates the session into the worktree (cwd + Bash follow); native auto-cleanup only silently deletes a pristine worktree, otherwise prompts keep/remove at session exit; no merge-back affordance (merge is always manual git); the tools are single-repo bound; location is hardcoded to .claude/worktrees/; worktree.baseRef = fresh (origin/HEAD) | head (local HEAD). These are the facts that make native a poor fit for our model.

Settled worktree-lifecycle decisions:

Location: .worktrees/ at repo root (already in seafile-ignore.txt; add to each repo's .gitignore). Corrected 2026-06-08 from .claude/worktrees/ after canonical native-worktree research: .claude/worktrees/ is native's hardcoded, native-owned dir (and the target of native's cleanup sweep), so co-locating our raw worktrees there risks native's lifecycle touching them (undocumented whether its sweep would). .worktrees/ keeps ours physically separate — native owns .claude/worktrees/ entirely, ours are path-distinguishable before branch names even matter — and aligns with the shipped planning skill. The earlier .claude/worktrees/ value had drifted in from the 2026-06-04 native-first design and wasn't re-examined when native was dropped 2026-06-08.
Branch from local HEAD explicitly in our git worktree add — so worktree.baseRef is moot (it was a native knob) and no-remote repos need no setting.
Naming = the detection spine: reserve worktree-* for native (subagent isolation: worktree can still spawn those); our raw worktrees use session-* (same-repo) and xrepo-* (cross-repo reach-in). Existence via git worktree list (any repo via -C, so cross-repo checks work); type via branch prefix — read from git, no registry to drift.
Resume: /good-morning detects via git worktree list and adopts ours by working against its paths. The native cold-start re-enter limitation is irrelevant since we never use native enter.
Disposition (/save-progress): merge / keep / discard, all manual git via git -C / absolute paths (never cd — the Bash tool resets cwd between calls and cd can trip a prompt). Keep = leave it, frictionless (nothing auto-touches it). Pin lands wherever /good-morning reads next (keep→branch, merge→main, discard→breadcrumb on main) — the (c) pin-vs-disposition split from the 2026-06-04 section still holds.
Creation timing: worktree-always at /good-morning (uniform, parallel-ready). An empty leftover is reused, not stacked on — so worktree-always doesn't breed empties.
Footgun mitigation: /good-morning cds Bash into the worktree; Claude targets absolute worktree paths (raw doesn't auto-relocate).

Two-moment cleanup split (settles the creation-timing / clutter question):

/good-morning (entry) = necessity-only cleanup: run git worktree list, read the landscape, and do only what's needed to land cleanly on the right session branch — resume the lone session-*, take over an xrepo-* leftover, clear a broken/half-made one in the way. Surfaced/offered, not silent (no-demand-character house style); it does not hunt for tidiness.
Hygiene-check / /save-progress sweep (exit) = proactive prune: the discretionary "N empty leftover worktrees — remove them?" pass, offered and skippable.
Why the split works: the two moments cover each other. Skip the exit sweep (in a hurry) → the next /good-morning does the reactive necessity-cleanup. Proactive when there are spoons, reactive when not, neither nags. (Worktree-prune lives in /save-progress's current inline sweep for now; migrates to /hygiene-check when that parked refactor lands — a tendril into Tier 3. Hygiene prune stays scoped to this repo; cross-repo xrepo-* cleanup is parked Loose End 2.)

/good-morning character shift: from "only reads and orients" → "reads, orients, and sets up / cleans the workspace" — the one write it now does. Still does not execute the plan's work; reconcile its "no work execution" framing to draw that line when wiring.

Altitude difference (settled — leave as-is): the planning skill says isolation is "a git worktree (or at least a branch)" — a domain-agnostic floor; the bookends commit to worktree-always — Yggdrasil's concrete default. Floor vs. default, not a contradiction — don't harmonize; just state worktree-always plainly in /good-morning so it doesn't inherit the softer floor.

Write-time details — SETTLED 2026-06-08 (all four closed):

Naming format: session-YYYY-MM-DD, with collision detection — if today's name already exists when a new same-day worktree is needed, append an incrementing suffix (session-2026-06-08-2, -3). (The only path that creates a second same-day worktree is choosing "start fresh" while today's already has live work — interlocks with the disambiguation below.)
Trunk name: main. Yggdrasil's trunk was renamed master → main 2026-06-08 (git branch -m, local-only, no remote to coordinate — ideal timing). All disposition text now reads merge→main, discard→breadcrumb on main. Sibling repos (personal/, odin-codin/) also renamed master → main 2026-06-09 for layer-uniformity (done — no longer a ride-along).
Multi-session-* disambiguation: AskUserQuestion, listing each session-* worktree as an option plus "start fresh." Before presenting, good-morning tries to derive a short summary of what each session is about (from recent commit messages / the branch's checkpoint, etc.) so the options are meaningful, not just bare branch names + dates. Picking "start fresh" triggers the -2 collision suffix above.
Empty-worktree rule — date-honest: a session-* worktree that is empty (clean tree, no commits beyond base) is reused only if its date is today; an empty, stale-dated one gets nuked (necessity-cleanup removes it, then creates today's) and good-morning tells Brad it did so. Keeps the date in the name meaningful and feeds the two-moment cleanup model.

Tracked / coupled to the build:

⏸️ Puppet [priority] good-morning-reuse bug — DEFERRED, blocked on the bookend build (reclassified 2026-06-08 from "MUST land with this build"). The fix replicates good-morning's read-only bootstrap bits and sheds its worktree/pin bits — so it can't be finalized until good-morning's new shape exists; you can't decide what to replicate against a shape that isn't built. Hard trigger — due the moment the good-morning worktree/pin wiring lands, before /puppet is next used: the bug is inert today but armed the instant good-morning gains worktree-creation (puppet would then spin a session-* worktree and pin Yggdrasil's plan on entry, violating its own read-only gate). This is blocked-then-immediately-due, not "revisit someday" — a fresh-Claude must not read "deferred" as "safe to ignore." Fix: shed worktree-creation from puppet's bootstrap, keep the plan-load (see the [priority] bookmark).
Cross-repo worktree disposition stays parked (Loose End 2); the pre-reach-in warning ("repo X has an unclosed Claude-managed worktree — load it as main and close it out first") nudges the right workflow.
Git-by-default (from the planning skill) + worktree-always wording must be explicit in the bookend text.

Loose-end inventory — the full "finish the bookends" scope:

Tier 1 (in the build): the two command edits (good-morning create-or-resume; save-progress disposition menu); git-by-default + worktree-always wording; .worktrees/ gitignore; the pin-vs-disposition auto-commit boundary + the AGENTS/CLAUDE note that disposition is prompted (Loose End 3); the "commit" git-op-vs-convention house-style call (lean on pin / disposition). (The puppet fix moved out of Tier 1 → deferred; see "Tracked / coupled" above.)
Tier 2 (bundle-or-defer): the bookmark-bloat nudge baked into both bookends (per-project count thresholds + a .meta date stamp); /good-morning actually surfacing working/consistency-check.md.
Tier 3 (separate threads, parked): the /hygiene-check refactor (merge /sweep + /consistency-check); scratchpad home + cleanliness; PreCompact / SessionStart hooks; the per-layer maintenance routine (Loose End 2).

Foreign-project adoption — `/puppet` + `/scry` (built 2026-06-05; intents recorded 2026-06-06, formal review deferred)

Status: built/committed (96153c1) in a since-cleared session, first-run verification complete (2026-06-06 / clone-half 2026-06-07; scorecard below), and expected to evolve a lot — so this records design intents (which nearly didn't survive that session's /clear; no design doc was ever persisted — see the 2026-06-06 session lesson), not formal feature docs. A proper section-by-section design review + dated design doc is bookmarked for when the design settles.

Core idea — an asymmetry. Yggdrasil is the active toolkit (the real cwd: conventions, primitives, the disciplined workflow); a foreign/legacy project is adopted as a read-only knowledge base to work from — you mine it, you don't develop it. /puppet turns on this "puppet mode" for one such project.

Why (intent). Triggered by wanting Yggdrasil's conveniences while mining a borrowed legacy project to finish a client-side binary-data RE task (FFXI DAT files) — but puppet is intended to be multipurpose: a way to sandbox-explore foreign toolkits generally, including community/public skill sets from public repos. This serves the larger goal of developing portable skill libraries (a thread through Odin Codin', the RE work, etc.) — puppet is a safe sandbox to try such toolkits on. It also dogfoods, by hand, the project-layer adoption Odin Codin' will later do natively — doing it manually teaches what the native mechanism needs.

The RE/DAT work has no real home — it's a legacy project Brad is borrowing via puppet right now, not a planned Yggdrasil/Odin-Codin phase. Explicitly NOT Odin Codin': Odin Codin' = server source-code comprehension (LSB), which does not touch DAT files; puppet/RE = client binary-data. Separate tracks, shared franchise only.

Key design decisions (intent-level):

Read-only by default — the foreign project is a source, not a worktree; the only writable surface is the gitignored .puppet/<label>/ bookkeeping.
Full Yggdrasil bootstrap on purpose — puppet loads Yggdrasil's current-plan.md and inherits its skills/commands deliberately, so puppet sessions get recorded in Yggdrasil's logs/lessons and ride the real toolkit. The wall: the foreign work product stays in gitignored .puppet/; the meta-lessons about puppet-as-a-tool are legit Yggdrasil self-improvement and get logged.
Multi-target .puppet/<label>/ is purposeful (not speculative): puppet expects to adopt several foreign toolkits over time — Brad's legacy projects and community/public skill sets. /scry's repo-cloning feeds this (pull a public toolkit in, explore it sandboxed).
Emulation is lossy by design (it reads the target's skills as inert markdown and acts them out — Claude Code can't live-load foreign skills) but mitigated here: the legacy skills are highly specific/technical and Brad drives manually.
/scry = puppet mode's research arm (Hugin). Robust by intent — clone whole repos, save research docs into .puppet/<label>/research/. Slated to graduate to the personal layer (global, not Yggdrasil-only) and needs formalizing (bookmarked).

Artifacts: commands/puppet.md, commands/scry.md, a committed project-scoped .claude/settings.json (pre-approves .puppet/** writes + git clone), .gitignore (+.puppet/).

Open / deferred (all bookmarked): the [priority] good-morning-reuse bug (keep the plan-load, shed the coming worktree-creation) · Finding #1 RESOLVED 2026-06-06: writes work via the committed .puppet/** whitelist (PUPPET.md, .scratch/, and /scry's git clone all landed, no refusal); allowed-tools: [Read,Glob,Grep] does not constrain — enforcement is the whitelist + Gate prose, not the frontmatter. Open choice RESOLVED 2026-06-07 — keep + document. Confirmed from canonical docs that (a) custom commands are now merged into skills, so puppet's frontmatter is live, not inert; (b) allowed-tools is pre-approval-only, never a restriction; (c) widening it to declare Write/Bash would be worse — bare Write,Bash pre-approves them globally (broader than the scoped .puppet/** + git clone whitelist, weakening the read-only model), and a scoped form would just duplicate settings.json (drift). So kept [Read, Glob, Grep] (genuine value: frictionless reads anywhere puppet scans, even outside the path whitelists) and added a "Permissions model" note to commands/puppet.md documenting the real mechanism: reads←frontmatter type-hint; git clone + .puppet/** writes←settings.json; everything else prompts (every real-project Write/Edit + every non-git clone Bash) — the human-in-the-loop boundary Brad wanted. (Prompt-vs-no-prompt watched check done — writes #1/#2 closed 2026-06-06, clone #2 closed 2026-06-07.) · lifespan (graduate into Odin Codin' / become its own thing) · scry→personal-layer · label-encoding edge cases · design-doc organization scheme · fresh-eyes zero-context subagent review.

First-run test plan (Brad's — preserved so it survives /clear):

First run after a /clear (settings load at session start; the project settings.json was created mid-session, so its perms aren't active until then).
Do the .puppet/** writes (writing PUPPET.md) and the first /scry git clone go through without a prompt? If either prompts, the pattern isn't matching — flip .puppet/** to the relative form.
Cache build→hit cycle: first run scans + writes PUPPET.md; a second /puppet loads the cache instead of re-scanning. Verify both branches.
Bootstrap behaves: good-morning-as-text loads Yggdrasil's plan, skips the briefing, and doesn't do Yggdrasil work or pin/commit its plan.
Read-only gate holds: writes land only in .puppet/, never the target's files or Yggdrasil's real content; no auto-commit.
Skill emulation actually fires: hand it a task matching a target skill and confirm it opens that SKILL.md and follows it rather than winging it from memory (the squishiest, most important behavioral check).
Lean PUPPET.md: the notable-files index stays notable, not an exhaustive dump (calibration may need tuning after run one).
/scry detection: /scry mid-puppet just works; /scry with no target adopted warns.

First-run test — results (2026-06-06): Ran /puppet C:\Projects\XI-RE-VibeTesting

/scry for the first time. Scorecard against the 8-point plan:

#	Test	Status	If pending — how
1	first-run / settings active	✅ (2026-06-06, fresh target `janet`)	Closed on a genuinely fresh, uncached target: `/puppet C:\Projects\janet` ran a full scan and wrote a brand-new-label `.puppet/C-Projects-janet/PUPPET.md`. The never-before-written label matched the committed `.puppet/` whitelist and the write landed with no permission prompt** (Brad confirmed from the console — the desired outcome).
2	`.puppet/` writes + `git clone` no-prompt	✅ (writes 2026-06-06 / clone 2026-06-07)	Writes: confirmed on a fresh uncached target — the scan's `PUPPET.md` write to a never-before-written label landed with no permission prompt (Brad confirmed from the console). Clone (closed 2026-06-07): ran `/scry` against the adopted `janet` target; a watched `git clone <url> <absolute-dest>` auto-approved with zero prompts (Brad-confirmed). Note: a chained `cd && mkdir && git clone` does prompt (prefix-rule miss) — `scry.md` now mandates the bare atomic form.
3	cache build → hit	✅ (2026-06-06)	build ✓ (prior session wrote `PUPPET.md`) + hit ✓ — this session's `/puppet` loaded the cache at startup (globbed `PUPPET.md`, read it instead of re-scanning the target tree).
4	bootstrap (Yggdrasil plan, skip briefing, no Yggdrasil pin/commit)	✅	—
5	read-only gate (writes only in `.puppet/`, no auto-commit)	✅	clean `git status` + `check-ignore`
6	skill emulation fires	✅ (2026-06-06)	Hand-fed the `57.DAT` compare task; emulation opened `ffxi-status-info/SKILL.md` and drove off its documented structure (640×0x1800, icon_size@+0x280) rather than winging it. Ran `compare_xiview.py` + an enhanced `compare_xiview_full.py` (full 3-way Backup/Normal/Widescreen against the scry'd repo); results in `PUPPET.md`. Hash mislabel-check passed.
7	lean `PUPPET.md`	Brad's judgment	eyeball the notable-files index calibration
8	`/scry` detection + clone	✅ (2026-06-06)	target-in-play + clone ✓ (prior run); no-target warning closed — ran `/scry` with nothing adopted and the gate fired correctly (warned + halted; nothing searched/written/cloned, read-only gate held, Brad-confirmed)

Built .puppet/C-Projects-XI-RE-VibeTesting/ (PUPPET.md cache + .scratch/ probe); /scry cloned research/repos/{XiView (KenshiDRK), Caradog-XI-View} from source (≈163 MB, --depth 1). Refinements applied this session: scry URL-discovery rule (saved-refs-first, search-if-not-found, don't-guess); puppet "don't stress" rule (call out a Yggdrasil-side change, then continue as directed); WebSearch whitelisted at the personal layer (live + snapshot; active next session). New findings → bookmarked: scry clone-hygiene (size/shallow/nested-.git); gh not on the Bash PATH (+ a new-machine-setup "Brad does this" STOP pattern).

Second first-run test — fresh uncached target (2026-06-06): Ran /puppet C:\Projects\janet purely to exercise the fresh-target branches #1/#2 the XI-RE run couldn't reach (re-puppeting that dir was always a cache hit). Janet (a Laravel 13 / PHP 8.5 API + Node/TS Discord bot) had no prior .puppet/ cache, so the full first-time path ran: scan → wrote .puppet/C-Projects-janet/PUPPET.md (kit = laravel-best-practices + bullmq, emulated). Brad confirmed no permission prompts fired (the desired outcome). Closed #1 and the writes half of #2; the git clone half of #2 closed 2026-06-07 via a live /scry clone against this same janet target (zero prompts, Brad-confirmed). #8 (scry no-target warning) closed 2026-06-06 in a separate no-target gate test. Read-only gate held — no writes outside .puppet/, no commits. PUPPET.md cache at .puppet/C-Projects-janet/.

Scry mode coverage (2026-06-07): Beyond the 8-point scorecard, two /scry modes were still unexercised. Save-summary mode now closed — a /scry research run produced a durable, credibility-tagged literature review saved to .puppet/C-Projects-janet/research/ai-assistants-for-autism-and-adhd.md (peer-reviewed / credentialed sources on how a personalized AI assistant helps autism/ADHD — effect sizes, the externalize-EF mechanism, the CHI-2024 autistic-workers benefit/harm tension, crisis/masking risks, the "nothing about us without us" co-design mandate; directly informs Janet's persona/UX). The research/<topic>.md save branch works end-to-end, and the run also exercised multi-query WebSearch + WebFetch full-text extraction with no-invented-citation discipline. Also cloned three mineable skillsets to research/repos/ (claude-adhd-skills, founder-skills, ASD-AuDHD-PAI-Skills).

Handed-over artifact mode — CLOSED 2026-06-07. The lone remaining unexercised /scry flow, exercised on the FFXI target: Brad dropped HorizonXI 57.DATs into research/artifacts/, and puppet (emulating ffxi-status-info) MD5-scanned + compared them against the retail reference. The run exposed a gap — the artifacts drop-path existed only as plan-intent here, never wired into commands/puppet.md, so it was never surfaced to Brad — now fixed: puppet.md step 3a names research/artifacts/ as the standing drop location and step 5 surfaces the absolute workspace paths on every run. All /scry modes are now exercised.

Real-world dogfood (2026-06-08): a full FFXI-RE puppet session put /puppet + /scry through heavy sustained use on XI-RE-VibeTesting — multiple bare git clone scry runs (LandSandBoat, FFXIDat, ResourceExtractor) + Wayback / GitHub-release-asset artifact pulls, save-summary research notes, and emulated-skill RE that solved two target format questions (flag field, icon alpha) which Brad approved porting to the target repo. Confirmed the workflow holds up under real investigation, not just first-run smoke tests; also surfaced the "accumulate here, port later" arrangement (findings live in the puppet workspace, port to the target in one consolidated pass) — recorded in that target's PUPPET.md, and the "build a proper FFXI client-RE project in Yggdrasil" roadmap item is now bookmarked.

After Phase 4 — Odin Codin' build-out (shifted +1 from the old numbering)

Phase 5 — Odin Codin' methodology skills. Populate odin-codin/skills/. Probable initial set: code-crawling-methodology (the spine — branch-by-branch traversal, evidence capture, when to stop), confidence-and-evidence, output-authoring, decomposition. Open design questions: which lands first (recommend code-crawling-methodology); disable-model-invocation + allowed-tools per skill; where the methodology (skill) vs. process (subagent/command) boundary sits. Also do the deferred voice-pass on the Odin Codin' README and AGENTS.md here — they're first-draft sketches, not yet Brad-voice.
Phase 6 — Odin Codin' subagents and commands. Probable subagents: branch-crawler, source-verifier, decomposer. Probable commands: /crawl-branch.
Phase 7 — Output templates (separate from skills). Modernized version of the existing FFXI TEMPLATE.md, aligned to agentskills.io.
Phase 8 — Per-codebase output repo template (the skeleton any new target repo starts from).
Phase 9 — Wire up Odin Codin' symlinks; design and build the consolidated new-machine-setup skill that supersedes the current one.
Phase 10 — Dry run on something small. (Corrected 2026-06-06: the earlier "single FFXI DAT file" target was a conflation with the separate client-binary RE / puppet track — Odin Codin' is server-side source-code comprehension and doesn't touch DAT files. The dry-run target should be a small server-side source artifact; specific target TBD.)
Phase 11 — LSB pilot (only after the LSB social-license conversation, which is also bookmarked).
Phase 12 — Full-stack verification capstone. With everything wired (personal + Yggdrasil + Odin Codin' + per-project layers, symlinks, hooks, docs), re-verify the entire stack end-to-end one more time: every layer consistent, every symlink resolving, every doc matching reality, every skill discoverable. The closing sign-off that the build is stable — effectively a deliberate repeat of the 2026-05-28 review pass, run as a gate.

Deferred

Yggdrasil-wide hot parked-item store — things deliberately deferred out of active work but kept tracked (design §5.6). In-context (heat ↔ context-load: the hottest parked items live with the work they may promote into). Dated prose bullets, each carrying an optional, encouraged-not-required revival trigger (a dependency, an event, a judgment call, or an honest soft one like "no spoons for this right now"). Re-deferring appends **Update YYYY-MM-DD:** and resets the age clock; no soon tag. /good-morning surfaces ripe deferrals (hard triggers by condition, soft by ~14d age), always as informational offers. Exits: promote → active task · demote → bookmarks.md (offered cool-down) · prune → archive. Counts toward the bloat thresholds.

(Sub-plans keep their own ## Deferred for plan-scoped deferrals, which merge up to here — or to bookmarks.md — when the sub-plan resolves. v1: good-morning scans this section only.)

2026-06-09 — Review the design of current-plan.md itself — it's never had a deliberate design pass. The file has grown by accretion — building and curating a few sections at a time — without anyone ever stepping back to design its overall structure: the section taxonomy, and how its parts (Checkpoint, ## Deferred, the decisions catalog, session lessons, the various build-status blocks) should relate. Worth a deliberate look at whether the current shape is right or just the one that accumulated. Revival trigger (soft): none forced — when there's appetite to step back from building in the plan and look at it (a natural /brainstorming fit). Surfaced 2026-06-09 during list-cleanup, noticing we'd never actually designed this doc. Update 2026-06-11 — promoted to next-up + enriched. This is the chosen next-session focus, with a concrete trigger: the file is ~125k words and loads on every fresh session — a real context/token cost. Findings to feed the redesign (from the 2026-06-11 catalog + mid-graduation review): (1) the Design decisions catalog largely duplicates AGENTS.md — skill-authoring conventions, composition-not-forking, the promotion-guard discipline rule, standards posture, and Norse naming all live in both; the redesign must settle whether the catalog is a permanent rationale record distinct from AGENTS.md's operative conventions, or a staging area that empties as entries graduate up. (2) The Done log (17 blocks), session-lessons (25), and catalog (37) are the bulk of the wordcount — decide each one's retention/home (e.g. aggressive Done-log drain, graduating proven lessons out). (3) Bucket-C: AGENTS.md's skill-config convention trails the catalog's 2026-06-07 four-flag vocab — a half-done graduation to complete while there. Approach as a /brainstorming pass. Update 2026-06-20 — now ACTIVE. Brainstorm started; design captured to working/yggdrasil-restructure-design.md (umbrella + subproject map). Subprojects 0 (doc architecture: the CLAUDE/AGENTS/README/FIRMWARE/INDEX/SYSTEM/INSTALL roster + links-imports matrix) and I (identity/layer reframe: execution-partner layer killed, Odin folded in, domain-agnosticism deferred to Vrataski) are settled; A (.jacket/ collections) is the next design target.
2026-06-09 — /good-morning auto-resumes a same-day session worktree instead of offering a parallel session — the concurrent-session gap. When good-morning's step 3 finds exactly one session-* worktree it resumes it (the resume-after-/clear path); the "start fresh / start a parallel session" escape hatch only exists in the more-than-one disambiguation branch. So a genuinely concurrent second same-day session silently piggybacks onto the first's worktree/branch rather than getting its own. Two roots: (1) the bookend model assumes sequential sessions (prior session ended + disposed/kept its worktree), with no concept of a live concurrent one; (2) there's no liveness/ownership signal — git worktree list can't distinguish "my kept worktree to resume" from "another session is live in this worktree right now." Fix direction: in the single-worktree case, offer the same resume-vs-start-parallel (session-…-2) choice the multi-worktree case already gives — plus, longer-term, a liveness marker so good-morning can tell live-concurrent from kept-to-resume. Related: the scaffolding also doesn't yet distinguish a read-only / low-spoon side-session (research that only produces notes/bookmarks — arguably shouldn't spin a worktree or run the bookend at all) from a full build session. This is the concrete good-morning slice of the parallel-execution / concurrent-sessions cluster (bookmarks.md 2026-05-28/29 + 2026-06-04), which is settled-direction-but-not-yet-designed. Revival trigger (soft): when that cluster is taken up, or sooner if concurrent sessions start biting in daily use. Parked now (not tackled) because it's one slice of that larger deliberately-deferred capability. Surfaced live 2026-06-09 when a second research session piggybacked onto this one.
2026-06-10 — Rethink how puppet/scry (research/tinkering) sessions record their checkpoint in current-plan.md. This session was "in-Yggdrasil scrying" — research + learning with nothing to resume — yet it still flowed through the normal /save-progress checkpoint machinery built for build sessions (Just finished / In progress / Next step), leaving the latter two as "n/a." A research/tinkering session's value is its artifacts (research notes, bookmarks, session lessons, specs), not a "resume here" pin — so it may want a lighter record, a separate log, or a "tinkering" disposition that drops the forward-looking fields. Figure out what puppet/scry sessions should write, and how a scry-style session is recognized. Revival trigger (soft): fold into the current-plan.md design pass (the "Review the design of current-plan.md itself" deferred item above) — same family (how the doc is structured and what records what). Surfaced 2026-06-10 after a scrying session whose checkpoint had no real "next step."
2026-06-16 — Convert some of the markdown-document management Claude now does by hand (in-prose, judgment-driven) into runnable scripts Claude invokes — for precision and repeatability. A lot of the durable-doc upkeep (pinning the checkpoint, draining Done-log blocks to archive/, restamping .meta/ledger.yaml, the hygiene moves) is currently done as freeform editing each session, which is flexible but imprecise and easy to do slightly differently each time. Scripting the mechanical parts would make them deterministic and less error-prone (the "pay the complexity cost out of Brad's sight" philosophy — push the upkeep into the substrate). Hinges on current-plan.md being formalized first: you can't script edits to a document whose structure is still accreting by hand — the section taxonomy and the per-section rules have to be pinned down before a script can safely manipulate them. Revival trigger (soft): gated behind the "Review the design of current-plan.md itself" deferred item above (and the related puppet/scry-checkpoint item) — once the doc's structure is formalized, reassess which markdown-management chores are mechanical enough to script. Surfaced 2026-06-16 by Brad as a /good-morning deferred-task note.

Design decisions catalog

These are settled. Don't re-litigate them unless something genuinely changes.

Yggdrasil's purpose and the planning model (reframed 2026-05-29)

Yggdrasil is the plan/design partner, not just a substrate. Its reason to exist is to help design plans/workflows/roadmaps — domain-agnostic (code, game design, budgets, trips). The "shared primitives" framing was scaffolding; plan design is the actual purpose. Operationally, "you are Yggdrasil" while we work on it — a role, not just a folder.
Dogfooding is the root motivation. Beneath "plan/design partner," Yggdrasil exists for Brad to dogfood AI — to de-black-box it by building and living in his own tooling, and so teach Claude to think the way that works best for his autism (reasoning surfaced, implicit made explicit). Shipping for others is incidental. See the personal CLAUDE.md "Dogfooding to de-black-box AI" design-philosophy note; favor transparency/hands-on-mechanism trades that serve this goal.
Designer / executor split. Yggdrasil designs; execution partners (Odin Codin' first, not the only one, not all code) carry the plan out — both human-in-the-loop, neither autonomous. The plan is the hand-off artifact.
Planning altitudes. Generic template (Yggdrasil) → tailored per-project instance (execution partner does early recon, then adapts; the instance lives in the project layer alongside output) → meta/build (current-plan.md is Yggdrasil planning itself). The template prescribes its own specialization as an early task ("survey the target, then adapt this plan").
The recursive plan mechanism (sharpened 2026-06-03). One artifact, one act, repeated at every layer: a markdown plan walked through with an agent, human-in-the-loop, git-backed. Three altitudes of the same mechanism: (1) Yggdrasil (domain-agnostic) — its first-class output is the blueprint for building a plan-designing toolkit (Travel Planner, Budget Designer 3000, Odin Codin'); current-plan.md is exactly this shape. (2) A plan-designing toolkit (domain-driven) — built by executing a Yggdrasil blueprint; specialized to one domain and carrying its own domain-driven planning. (3) A concrete plan artifact — generated by a toolkit for one instance (a Chicago trip: lodging, travel method, itinerary, packing list, day-of checklist). A toolkit builds concrete plans the same way Yggdrasil builds toolkits the same way we're building Yggdrasil now — turtles all the way down. First-class Yggdrasil usage = planning toolkit-builds + Yggdrasil self-improvement; direct one-off concrete plans are an allowed exception for small things not worth a toolkit (still git-backed — you still end up with artifacts). Domain knowledge belongs in the toolkits, never in Yggdrasil — that is what "domain-agnostic" means here: "design a toolkit that plans domain X" is itself a domain-neutral act, with the domain knowledge injected into the toolkit. "plan" and "workflow" are synonyms; canonical term = "plan."
Borrowed from superpowers' writing-plans, done our way. Take the plan structure (exact targets, per-task verification, no placeholders); drop the autonomous-execution wrapper. Size tasks to a meaningful human review checkpoint, not the smallest agent-executable unit. We walk the plan together, task by task, human-in-the-loop at every step.

Advisory subagents — allowed; autonomous ones not (refines the single-thread stance) (2026-06-04)

Yggdrasil rejects agent autonomy, not agent parallelism. The earlier "no multi-agent" call (why multi-agent-brainstorming wasn't imported) was really "no autonomous multi-agent" — that skill bundled independence and autonomy together; we only meant to reject the autonomy. Independent subagents are permitted as critique lenses when all hold:

Read-only / read-mostly — may inspect (Read/Glob/Grep the artifact and what it references); no significant mutating tooling, no world-acting.
Product is critique — findings, risks, sharper questions; never decisions, writing, or executed actions.
Facilitator-mediated — output routes through Claude → Brad; the human-in-the-loop gate is undisturbed.
Independence is the justification — if a single context could honestly produce the perspective, don't spawn an agent.

They exist to help Claude ask Brad better questions, not to plan, write, or act — which is why this isn't "automation" in the sense Yggdrasil avoids. First realized use: the planning skill's back-end lens audit (below).

Design-review lenses (four, orthogonal) and where they run (2026-06-04)

Review uses a small set of perspective lenses, harvested from multi-agent-brainstorming (credited) but run our way. Selection principle: a lens earns its place only if it catches a class of holes the others miss — each is a distinct axis, so they don't collapse into voices agreeing ("hallucinated consensus").

Lens	Axis	Asks
Skeptic	robustness / failure	"assume it fails — why?"
User Advocate	human experience	"is this clear and bearable for whoever lives with it?"
Steward	durability over time	"after a `/clear` or a year out, does this still make sense and hold up?"
Constraint Guardian	the stated bar	"does this still meet the limits/criteria we set up front?" (softened from the source's perf/security checklist to a domain-general bar-check)

Steward is our addition (not from the source) — the time axis the other three miss, and a fit for Brad's /clear-between-sessions reliance on durable docs. Considered and excluded: Minimalist/YAGNI (overlaps brainstorming's pervasive YAGNI), Pragmatist/Executor (redundant with the planning skill's verifiable-outcome task anchor), Stakeholder/Externalities (too situational — inject per-domain in an execution partner).

Placement — two bookends, different forms:

Forward (single-thread, woven in): during brainstorming the lenses sharpen existing steps, not add ceremony — Step 4 (compare approaches by failure mode + who-lives-with-it) and Step 5; Constraint Guardian's forward form is already Step 2. Light, offered/scaled per the Anti-Pattern gate.
Backward (the finished-plan audit) — a 3-way opt-in, scaled to how much the project matters:
- Skip — trivial work; no lens pass.
- Single-thread — Claude roleplays the lenses (lighter; accepts some echo-chamber risk); for work that needn't be bulletproof.
- Subagents — independent lens-subagents (per the carve-out above) attack the finished plan and report findings Claude synthesizes for Brad; this is what eliminates the echo chamber. For work that matters. Textbook subagent fit (complete artifact, one-shot fan-out, independence buys hole-finding).
The planning skill presents these three as the choice; never mandatory.

Architecture (2026-05-27)

Composition, not forking. Yggdrasil and workflows live in separate repos that compose via symlinks into ~/.claude/. Updates to Yggdrasil flow naturally to all workflows; no merge conflicts. OO analogy: dependency injection rather than subclassing.
Subdirectory-level symlinks within ~/.claude/skills/, ~/.claude/agents/, ~/.claude/commands/. Each individual skill/agent/command links separately because multiple repos contribute to the same logical directory.
Per-codebase output repos are separate from the target codebase. No documentation tooling lives inside the codebase being studied — preserves social-license flexibility and keeps the target tree clean.
Three+ layers planned long-term: personal / Yggdrasil / workflows / per-project. Eventually a per-project layer lives committed in the target's .claude/, but only with permission.

Yggdrasil-specific (2026-05-27)

Discipline rule (a promotion guard): things are pulled up into Yggdrasil from a workflow only after proving general across two or more workflows. When in doubt, build it downstream first; promote later on evidence. It guards drift while working downstream — it does not gate design/planning skills, which are native to the base layer and built here directly (stay bloat-aware regardless). This is what keeps Yggdrasil from becoming a junk drawer without freezing its core purpose. Brad can override this case-by-case — it's a default guard, not a hard gate. When he explicitly says to make an exception, honor it without re-litigating.
.meta/ directory for structured state (YAML files, minimal schemas, grow on evidence). Markdown companion files allowed when prose tracking earns its place.

Skill authoring conventions (2026-05-27)

Names in gerund form (bookmarking, learning-new-skills, code-crawling-methodology). Commands stay imperative (/bookmark, /learn-new-skills).
Description point-of-view: third-person. Must include both what the skill does AND when to use it. Per Anthropic guidance, this is the #1 factor in trigger reliability.
disable-model-invocation: true when accidental triggering could cause real work to happen against user intent. Treat this as a design question for every new skill: "is this safe to auto-fire?"
allowed-tools is pre-approval only — listing a tool means it runs without a permission prompt while the skill is active; it does not restrict the skill to only those tools. Unlisted tools follow normal session permission rules. Deliberately omit Write/Edit/Bash when you want those mutations to keep prompting. Treat as design vocabulary: "which tools should be frictionless, and which mutations deserve human-in-the-loop friction?"
disallowed-tools is the inverse of allowed-tools and stronger: it removes a tool from the pool entirely while the skill is active (whereas allowed-tools only grants pre-approval, never restricts). Reach for it when an autonomous skill must never call a tool — e.g. excluding AskUserQuestion from a background loop. With user-invocable (whether the skill is exposed as /name), the per-skill config vocabulary is four flags: disable-model-invocation (safe to auto-fire?), allowed-tools (which tools are frictionless?), disallowed-tools (which are forbidden outright?), user-invocable (exposed as a slash command?). (Confirmed from code.claude.com/docs 2026-06-07.)
Commands are skills (merged). A .claude/commands/foo.md and a .claude/skills/foo/SKILL.md both create /foo and honor the same frontmatter — so Yggdrasil's commands/*.md files are skills for frontmatter purposes; their allowed-tools / disable-model-invocation / disallowed-tools are live, not inert. (Confirmed from code.claude.com/docs/en/slash-commands 2026-06-07.)
Lean SKILL.md, heavy references/. Keep main SKILL.md under ~400 lines; push detail to references/ files that load only when needed (progressive disclosure).
Skills auto-invoke as /<skill-name>. Commands are pure ergonomic sugar; only build them when the shortcut is worth the extra file.

Standards posture (2026-05-27)

agentskills.io for portable skill structure (frontmatter, directory layout).
AGENTS.md at every repo root as universal entry point for non-Claude agents (Codex, Cursor, etc.). Cheap portability tax for outsized compatibility benefit.
Claude/Anthropic conventions for everything else (subagents, commands, hooks) where no open standard exists.
"Married to Claude where it counts, open where it's cheap" is the explicit posture.

Naming and flavor (2026-05-27)

Norse mythology theme for infrastructure and workflows where it adds flavor: Yggdrasil (base), Odin Codin' (code-crawling workflow), Hugin/Munin (agent/memory split inside Odin Codin'). Coherent but not forced.

Terminology (2026-05-27)

"Reflect" is reserved for conversational use ("can you reflect on this?"). Casual, ad-hoc.
"Briefing" is the /good-morning step that gets the user up to speed at session start — a short playback of current state, offered (never forced). Chosen to avoid colliding with "reflect" (casual mid-work) and the structured end-of-session review (now /save-progress).

Collaboration patterns (2026-05-27)

/clear discipline. Each session is a fresh start. Persist state to disk (this file is exactly that). Workflows should not assume cross-session memory.
Iterative work over big-bang execution. Break things into steps, persist between them.
Two-way feedback in recaps. Honest about user-side misunderstandings, not just AI-side. The user prefers learning over coddling.
Collaborative authoring vs. LLM generation: human-drafted-then-LLM-refined CLAUDE.md and similar context files are fine; fully LLM-generated context files reduce agent success rates per recent research. Keep the human-review discipline.

Session lessons

Carry these forward; they're meta-observations worth not relearning. Flat dated entries, chronological; graduated/pruned via /hygiene-check (drains to archive/session-lessons.md).

2026-05-27 — disable-model-invocation + allowed-tools is a design vocabulary, not just two flags. "Is this skill safe to auto-fire?" and "What tools does this skill actually need?" should be deliberate questions when authoring any skill. Update 2026-06-07: the vocabulary is four flags, not two — add disallowed-tools (forbid a tool outright) and user-invocable (expose as /name); and since custom commands are now merged into skills, commands/*.md honor the same frontmatter. See the Skill-authoring-conventions catalog entry for the full set.
2026-05-27 — Hook calibration matters. A too-strict quality gate trains the user to ignore it. If a hook starts feeling like noise, retune the prompt rather than removing the hook.
2026-05-27 — Collaborative authoring is different from LLM generation. Research caution against LLM-generated CLAUDE.md applies to fully generated files. Drafts that the human reviews, edits, and commits deliberately are fine.
2026-05-27 — Wire as you go, not all at once. Wiring symlinks immediately after each repo is created surfaces problems at the smallest possible cost rather than at the end of a long build.
2026-05-27 — Yggdrasil's first /learn-new-skills run was the first real test of the system. It produced actionable findings (the hook patterns above) and validated the freshness-research workflow. Worth using regularly.
2026-05-28 — A blocking quality-gate hook needs to model whose turn it is, not just "are there open questions." The Stop hook's continue: false doesn't merely nag — it prevents the turn from ending and re-invokes Claude. With questions addressed to the user sitting in the transcript, the gate fired on every stop and never handed control back, deadlocking the session. Fixed by sharpening the gate prompt to only flag questions the user asked that Claude left unanswered, and to treat handing back to the user as a complete end-of-turn state.
2026-05-28 — Prune skills that duplicate an enabled plugin. Personal skill-creator and mcp-builder shadowed maintained official plugins. Stale local copies compete for triggering and drift out of date. Prefer the plugin; remove the local snapshot.
2026-05-28 — This session's review pass is the template for the Phase 12 capstone. A full-stack walk — every layer, symlink, doc, and skill — is a repeatable closing gate, not a one-off.
2026-06-04 — Unbundle parallelism from autonomy. The "no multi-agent" stance had silently glued two things together; separating them ("reject autonomy, permit independence") turned a blocked idea into a clean carve-out. When a settled "no" feels too broad, check whether it's bundling distinct axes.
2026-06-04 — Subagents fit one-shot audits, not interactive selection. The lens idea was right but aimed one step too early — Step 4 is a conversation (subagents can't participate); the finished-plan audit is a serializable one-shot (textbook fit).
2026-06-04 — DRY a procedure into a reusable unit, then dogfood it. Extracting /save-progress's doc-sync sweep into /consistency-check cost almost nothing (known-good logic) and immediately found real drift — including pre-existing drift unrelated to the triggering change.
2026-06-04 — Generalizing a borrowed mechanism is often about its character, not its wording. superpowers' merge gate wasn't just "tests" — it was automated, binary, blocking. The real generalization was recognizing that character can't survive in a human-in-the-loop, soft-domain world (no exit code), so it becomes a question in the walk. When porting a mechanism across contexts, ask what kind of thing it is, not just what it says.
2026-06-06 — Work committed outside the /save-progress flow silently drifts the plan from the repo. /puppet + /scry were built and committed as a direct manual commit (96153c1) after a checkpoint, with no following /save-progress to reconcile — so a whole feature plus its design intent landed in git while the plan never mentioned it, and the design write-up evaporated with that session's /clear. A clean git history does not mean the plan reflects reality. The bookends assume they bracket the session; out-of-band commits (hacky direct commits, or puppet-mode's deliberate "no Yggdrasil checkpoint") break that assumption. Be careful auditing or relying on save+commit — and consider a guard (the bookmarked fresh-eyes review pass, or a /good-morning reconcile check).
2026-06-06 — Derive "today" from the session date, not the last checkpoint's header. Early drafts this session were dated 2026-06-05 by anchoring to the prior checkpoint; the actual date was 2026-06-06. Copying the last header silently back-dates new entries — caught and corrected here.
2026-06-06 — A read habit, not just a write habit: we both assume shared context. Phrasing like "that /clear" reads fine in-session but is opaque to a fresh Claude — exactly the trigger for the bookmarked zero-context subagent review.
2026-06-07 — A convention recorded as design intent isn't real until it's wired into the command that must perform it. The artifacts drop-path lived in the plan's scry-coverage notes but never in commands/puppet.md, so it was never surfaced — dogfooding the actual handoff (Brad handing over real files) is what exposed the gap. Intent in the plan ≠ behavior in the command.
2026-06-08 — Design without a demand character — flexibility and anti-rot are accessibility, not polish. Designing the tracked-deferral mechanism, the load-bearing move was making the revival trigger encouraged, never required and the No-Placeholders check catch only the masquerade (a vague TBD posing as an active task), never the motivation for a deliberate deferral. "I didn't feel like it today" is a first-class valid reason; the mandatory date is the follow-up hook so it resurfaces gently without ever being pushed. This isn't calm-house-style aesthetics — it's an accommodation for how Brad's brain works (autonomy/PDA + variable "spoons"): rules framed as demands trigger avoidance, so tooling here must inform and offer, never force. Generalizes well past deferrals — the anti-rot aging signal is itself informational (surface what's stale, don't mandate a review), and the demote-to-cooler-store valve is an offer, not an auto-action. Now a standing personal-layer principle (personal/CLAUDE.md → Design Philosophy → "Design without a demand character"); the soft-trigger deferral is the canonical worked example.
2026-06-09 — Elicit the reason for a deferral; don't synthesize one. Demoting the GitHub-remote push I asked where it should go but invented the why — recycling "pure procrastination" from old plan text and inventing an off-machine-backup motivation that was never Brad's (his real reason: GitHub's a headache to add when he's single-machine ~99% of the time and portability hasn't bitten yet). The ## Deferred format carries a reason + revival-trigger slot precisely because the motivation is the human's to give — the "why" governs when an item revives, so a fabricated one quietly mis-aims the trigger and then reads as fact in the plan. Same failure mode as a partial source that "looks complete." Fix: when capturing any parked item (deferral or bookmark), ask the reason as part of the capture, the same way where? already gets asked. Kin to "design without a demand character" — the reason is Brad's, not mine to assume.
2026-06-08 — A settled design is allowed to re-open when a better idea lands. The list-hygiene design was "complete"; this session deliberately extended it (the plan-deferral descendant, out-of-context bookmarks, per-item aging) because closing out the tracked-deferral question surfaced genuine improvements. "Settled" means "don't re-litigate without cause," not "frozen" — Brad's own aging-for-all-lists catch was the clearest win.
2026-06-08 — Authoring-walk rationale leaks into the operative artifact. Walking the planning SKILL.md section-by-section, the presentation voice ("here's what we kept/dropped from superpowers and why") bled into the skill text itself — design-rationale a future executor doesn't need, referencing a skill it may not have. Caught in the final coherence read and trimmed to self-contained attributions only. The walk's explanatory voice is design-doc material, not skill text — strip derivation commentary from the operative artifact, keep only what the executor needs. (Relevant to the future creating-workflow-skills skill.)
2026-06-09 — Parallel subagent lens audits are thorough but token-expensive — reserve for work that genuinely matters. Running the four review lenses (Skeptic / User Advocate / Steward / Constraint Guardian) as independent subagents over the list-hygiene plan burned a lot of tokens — four full plan-plus-design reads with reasoning, in parallel. It paid off (convergent, high-quality findings the single-thread pass would have missed), but it's not a default move. This is exactly why the planning skill frames the lens audit as a 3-way opt-in scaled to the stakes (skip / single-thread roleplay / independent subagents): reach for the subagent fan-out only when the artifact is high-stakes and worth the spend; default to single-thread for lighter work. Candidate to graduate into the planning skill's lens-audit section as an explicit cost note.
2026-06-09 — Delete a whole list item by matching its trailing newline, not its leading one. Pruning six bookmarks via Edit with each old_string prefixed by the item's leading \n worked for isolated entries but mashed adjacent ones onto a single line — removing entry N's leading newline fused entry N−1 to N+1, and a follow-on removal then failed to match because the newline it expected was already gone. Three bullets silently fused; caught only by a post-edit bullet-count cross-check coming up short. Fix: match the trailing newline (<entry text>\n → ``) so each deletion consumes its own separator and never disturbs its neighbours. General habit: after any multi-delete on a list, re-count the items as a cheap integrity check before trusting it.
2026-06-09 [planning-dogfood] — First real execution of a /planning-produced plan — the structure held; a few friction points to fold back into the skill. Walking the 16-task list-hygiene plan was the planning skill's first true dogfood. Worked well: the per-task Confirm-by + ## Progress checklist + per-task commit rhythm kept the walk clean and /clear-resumable, with the Confirm-by as ground truth. Friction to fold back: (a) the plan didn't specify a commit cadence, so we decided it at execution start — the execution handoff should ask up front; (b) several Confirm-bys assumed a live run that couldn't happen at build time (cadence-gated steps not yet due; new commands not yet symlinked; the bootstrap commands can't run inside the very session/worktree they manage) — the skill should bless a "verify by walkthrough / defer to first real use" fallback rather than imply every Confirm-by is a live run; (c) the final-verification step needs care authoring its checks — an over-broad regex false-positived on stale checkpoint prose (the check was wrong, not the build).
2026-06-09 [planning-dogfood] — A semi-automatic exit must announce what it did, not just that it ran. The Done-log age-drain is the one mechanism that rotates a batch out without per-item review; the catch was that its callout needs a content hint (a phrase of substance per drained entry), not just dates, so the human stays oriented. Generalizes: any non-reviewed automatic mutation should report its substance — legibility is the price of automation.
2026-06-09 [planning-dogfood] — A periodic "best-effort" stamp lagging live state is by design, not a bug. The ledger's bookmark count is refreshed by /hygiene-check, not by every add, so it lags the live file — the final verification correctly treated that as expected ("as fresh as the last hygiene pass"), not a dangling reference. When a value is explicitly a periodic stamp, don't "fix" its lag inline — that conflates capture with hygiene.
2026-06-19 — allowed-tools is a no-prompt pre-approval list, not a tool-availability gate. A skill/command can call any tool regardless; listing one in allowed-tools makes it run without a permission prompt, while an omitted tool still works but prompts every time (the bookmarking skill proves it: [Read] listed, Write omitted so writes still prompt). So allowed-tools: [Bash] silently pre-approves all bash — never grant it casually; list only narrow, safe pre-approvals. Caught designing skill-wiring. Sharpens the 2026-05-27 four-flag design-vocabulary lesson with the actual semantics; feeds the 2026-06-19 permission-posture-audit bookmark.
2026-06-19 — The Bash tool's cwd resets to the repo root between calls — worktree git ops need explicit git -C <worktree> / absolute paths. During the de-Windows sweep, bare/relative commands (a git mv, plus a file edit) twice landed on main instead of the session-2026-06-19 worktree, because the shell cwd doesn't persist across Bash calls on this host. This conflicts with the bookend convention's "use bare git from the worktree cwd, not git -C" — that guidance assumes a persistent cwd, which doesn't hold here. On this host, always target the worktree by absolute path. Worth reconciling into the good-morning/save-progress worktree convention during the current-plan.md/docs refactor.
2026-06-20 — Dates drift mid-session; best-guess + flag, don't sweat exactness. Brad often works past midnight, so the calendar can roll over during a session and the worktree/checkpoint/ file dates won't always line up — and that's fine, by design (Brad's explicit calibration). Take the best guess (run date when it actually matters), tell Brad the assumption you're making, and don't burn effort chasing perfect date hygiene. Calibrates the 2026-06-06 "derive today from the session date" lesson: still derive thoughtfully and flag it, but over-correcting for a one-day slip isn't worth it. (Surfaced 2026-06-20 — good-morning named the worktree session-2026-06-19 off the prior checkpoint while the real date was 2026-06-20.)

File locations reference

This doc: /var/projects/yggdrasil/working/current-plan.md
Personal layer repo: /var/projects/claude-personal/ (CLAUDE.md at claude-personal/CLAUDE.md; personal skills under claude-personal/skills/)
Yggdrasil repo: /var/projects/yggdrasil/
Bookmarks: /var/projects/yggdrasil/bookmarks.md
Hook config: ~/.claude/settings.json (machine-local, not synced)
Hook scripts: claude-personal/hooks/ (scripts in-repo; registration in ~/.claude/settings.json is machine-local, snapshotted to claude-personal/claude-config/settings.json)
Existing FFXI/RE project: /var/projects/ (per personal CLAUDE.md convention)
Odin Codin' repo: /var/projects/odin-codin/ (skeleton; git-initialized — not yet migrated to this host)
Future per-codebase output repos: location TBD (independent of target codebase locations)