Agents working in this repo

This is Yggdrasil, the plan & workflow design partner — and the base layer everything else composes on. Its job is active: brainstorm, author, and refine plans/workflows/roadmaps with Brad (domain-agnostic — code, game design, budgets, trips), which then hand off to an execution partner. See README.md for the full philosophy.

Orientation

• Not a target codebase. There's no application code here. This repo is tooling: skills, commands, and metadata that get symlinked into ~/.claude/.
• Designer, not executor. Yggdrasil designs plans; execution partners — domain-driven toolkits like ../odin-codin/ — carry them out, plan-driven and human-in-the-loop. The plan is the artifact that hands off between them. The same plan-walked-with-an-agent act recurs at every layer: Yggdrasil's native plans are meta/build (planning a toolkit's construction, or itself — working/current-plan.md); a toolkit's plans are domain-driven concrete instances; domain knowledge lives in the toolkits, never here. See the README's recursive plan section.
• This is the base layer. Design & planning skills are Yggdrasil-native. Other general-purpose primitives also live here. Execution-partner-specific things live in their own repos.
• Live, not a skeleton. Unlike Odin Codin' at this stage, the skills here are in active use. Changes have immediate effect once symlinked.
• Composes, doesn't fork. Yggdrasil sits below the personal layer (CLAUDE.md) and above workflows. They compose via symlinks into ~/.claude/ rather than by merging or subclassing. See README for the layering scheme.

What this repo contains

Conventions

• Skill names: gerund form (bookmarking, learning-new-skills).
• Command names: imperative (/learn-new-skills). Commands are pure ergonomic sugar — only add one when the shortcut earns the extra file.
• Skill descriptions: third-person; must state both what the skill does and when to use it. This is the single biggest factor in trigger reliability.
• disable-model-invocation + allowed-tools are a design vocabulary, not just flags. For every skill ask: "is this safe to auto-fire?" and "which tools should be pre-approved for frictionless use?" allowed-tools is pre-approval only — it does not restrict the skill's tool access; unlisted tools follow normal session permission rules. Deliberately omit Write/Edit/Bash from allowed-tools when you want those mutations to keep prompting for human approval — omitting is not a restriction, it's just not pre-approving. Invocation gotcha: disable-model-invocation: true blocks all Claude-side invocation — not just unprompted auto-fire, but one skill invoking another via the Skill tool — and drops the skill's description from context entirely. Only a human typing /name can reach a disabled skill. So any skill that must be reachable by an orchestrating workflow or a skill-to-skill handoff has to leave it off. (This and the allowed-tools notes are the kind of guidance that will migrate into the future creating-workflow-skills skill once it exists; AGENTS.md is their interim home.)
• Lean SKILL.md, heavy references/. Keep the main file under ~400 lines; push detail into reference files that load only when needed (progressive disclosure).
• Self-housekeeping commands may auto-commit. Commands whose entire purpose is managing the toolkit itself (checkpoint saves, symlink management, etc.) are exempt from the "never auto-commit" rule — the commit is the point. Note the auto-commit explicitly in the command file so the behavior is transparent. See the personal CLAUDE.md "commit" convention for the full rule and exception. Consider this pattern for any future command that manages Yggdrasil's own state.
• Accumulating-list hygiene. Yggdrasil's growing lists (bookmarks, backburner, session lessons, the design catalog, the Done log) are curated by /hygiene-check, with state in .meta/ledger.yaml. The tunable knobs — bloat thresholds, the item-aging window, review cadences — live in ledger.yaml → config (the only human-edited section; the hygiene restamp writes only skills/lists). A bloat-nudge escalates by bookmark count through the bands in config.bloat (heads-up → warn → firm) to keep the list pruned. Retired items are never deleted — they append to archive/. Archive-file convention: when a hygiene pass drains a source that isn't one of the four canonical list-archives (bookmarks / session-lessons / done-log / catalog), name the file kebab-case after its source, give it the standard archive header, and add its line to archive/README.md — as archive/hygiene.md already does for the consistency-check drift scratchpad (the first such file). The convention travels to descendent scopes.
• Session worktrees & disposition. Yggdrasil work is git-backed by default; every session runs in its own session-YYYY-MM-DD worktree under .worktrees/ off main (never editing main directly). /good-morning creates/resumes; /save-progress disposes via merge / keep / discard. Branch prefixes are the detection spine: session-* are ours; xrepo-* (cross-repo) and native worktree-* are reserved. Disposition is always prompted — a deliberate AskUserQuestion, outside the self-housekeeping auto-commit exception above (the pin auto-commits; the disposition never does). "commit" house-style: a bare "commit" means the git op; in worktree mechanics lean on the domain words pin (the checkpoint write+commit) and disposition (merge / keep / discard), and write "the commit convention" when you mean the personal-CLAUDE.md rule — so an ambiguous bare "commit" rarely appears.
• Tone is calibrated, not fixed. Yggdrasil's design/planning skills use a calm, firm voice: keep firm markers only at genuine gates (where compliance actually matters) and de-shout the rest; skip decorative emoji. Forceful "you MUST / not allowed" phrasing measurably improves model adherence (the superpowers approach), so treat it as a deliberate tool to reach for in high-structure execution contexts — e.g. an Odin Codin' crawl of a big, complex codebase — not the default for collaborative design work. House style for firm markers: mark a genuine hard stop with a blockquoted bold-label directive — > **Gate:** for a checkpoint (confirm or verify before proceeding) or > **Hard rule:** for a standing invariant — and leave soft checkpoints (ones the user may wave through) as plain prose. The marker's presence then reliably means "hard stop," its absence "soft."
• Refer to phases and steps by name, not bare number, when talking to Brad. Numbered labels (Phase 5, step 3) are fine as internal anchors in working/current-plan.md, but Brad doesn't hold the numbers in his head — translate them when you surface them ("the planning-skill build," "the constraints step," "the Odin Codin' methodology phase"). Once a topic's been covered recently in-session, it's fine to be more succinct.
• Discipline rule (a promotion guard): something is promoted up into Yggdrasil from a workflow only after it has proven general across two or more workflows. When in doubt, build it downstream first and promote later on evidence. This guards against drift while working downstream; it does not gate design/planning skills, which are native to the base layer (build those here directly, just stay mindful of bloat). (Brad can override case-by-case — it's a default guard, not a hard gate.)
• Advisory subagents & design-review lenses. Yggdrasil rejects agent autonomy, not agent parallelism. Independent subagents are allowed as critique lenses when all hold: read-only/read-mostly, their product is critique (findings, risks, sharper questions — never decisions, writing, or actions), output routes through Claude → Brad, and the spawn is earned by genuine independence (if one context could honestly produce the perspective, don't spawn). Design/plan review draws on four orthogonal lenses — Skeptic (failure), User Advocate (human experience), Steward (durability across a /clear or a year), Constraint Guardian (the stated bar) — each a distinct axis so they don't collapse into agreement. Two forms: forward, woven single-thread into brainstorming's steps; backward, the finished-plan audit as a 3-way opt-in (skip / single-thread roleplay / independent subagents), scaled to how much the work matters. Shipped in the planning skill; full rationale in the working/current-plan.md decisions catalog.
• Standards posture: agentskills.io for skill structure (frontmatter, directory layout); Claude/Anthropic conventions for subagents, commands, and hooks where no open standard exists. "Married to Claude where it counts, open where it's cheap."
• Norse-mythology naming where it adds flavor (Yggdrasil the world-tree as the base; workflows like Odin Codin' hang off it). Not forced.

External references and known patterns

• obra/superpowers — a well-established agentic skills framework built around brainstorming → writing-plans → subagent-driven-development. For any software/coding project, check Superpowers — its design-spec workflow, plan structure, debugging patterns, and other skills may be worth porting or adapting regardless of whether TDD or autonomous execution is wanted. Brad decides what to keep when setting up each new project. Yggdrasil's defaults remain domain-agnostic and human-in-the-loop; Superpowers is a reference to consult, not a default to inherit. Bookmarks in bookmarks.md track specific skills worth reading before designing OC's subagent layer.

For deeper context

• README.md — this repo, in human-facing prose
• working/current-plan.md — the live, multi-session implementation plan
• ../odin-codin/README.md — the first workflow built on this base
• The personal layer (CLAUDE.md, symlinked from the claude-personal sibling repo) sits above this repo and is not committed here.