Planning Skill — Design

Status: Design complete; skill built 2026-06-08 (skills/planning/SKILL.md). This document consolidates a design that was worked out incrementally across several sessions and previously lived distributed across working/current-plan.md (the "Planning-skill design — in progress," "Next build," and Design-decisions catalog sections) and working/2026-06-05-list-hygiene-design.md §5.6. It is an extraction of already-committed content into one durable artifact — nothing here is new design. The authoritative spec is the SKILL.md; this is the why behind it.

Provenance note: unlike a normal /brainstorming → /planning flow, this design was not produced into a dedicated design doc up front — it accreted in the living plan doc. This consolidation is the retroactive design artifact (and a worked example of the in-flight-design durability concern: design that churns inside current-plan.md benefits from extraction into a stable dated doc).

1. Identity & purpose

  • Name: planning (gerund), invoked /planning. The flagship Yggdrasil skill.
  • Role: consumes a validated /brainstorming design doc → produces an executable, checkpoint-able plan. Domain-agnostic (code, a trip, a budget, a document), human-in-the-loop, no autonomous execution.
  • Lineage: borrows structure from superpowers' writing-plans (C:\Projects\superpowers\skills\writing-plans\SKILL.md); drops its TDD / autonomous-execution wrapper. Tasks are sized to a meaningful human review checkpoint, not the smallest agent-executable unit.
  • Grounding: the recursive plan mechanism (catalog) — one act, a markdown plan walked through with an agent, human-in-the-loop, git-backed, repeated at every altitude. Domain knowledge lives in toolkits, never in Yggdrasil.

2. Settled design decisions

2.1 Task anchor = verifiable outcome (the spine)

Each task is a concrete, checkable result + how you'll confirm it, domain-translated (code: exact paths/commands; trip: "lodging booked Jun 26–28, confirm by confirmation email"). A machine check is evidence brought to the human review, never a substitute for it; a task whose outcome is fully machine-confirmable on its own is usually too small to stand alone (fold it up, unless it warrants its own designated review step). Keeps writing-plans' portable kernel (exact targets, per-task verification, no untracked placeholders); drops the code/test/commit machinery.

  • Rejected: domain-detected templates (push domain knowledge into Yggdrasil — violates the agnostic/driven split); a generic fixed task schema (too heavy/form-like — bookmarked as a possible upper-layer/toolkit feature).

2.2 No-Placeholders + the ## Deferred carve-out

Forbid the untracked gap, not the honest "not yet." Deliberate deferrals live in a dedicated ## Deferred section in the plan doc. What makes an item tracked is placement in that section, not the trigger's quality. Self-Review enforces only the masquerade (a vague "TBD" posing as a ready task), never the motivation for a deferral. Triggers are encouraged-not-required; soft ones ("no spoons," "didn't feel like it today") are first-class. Exits: promote → task / demote → bookmarks.md (offered, never forced) / prune → archive. Full mechanism: working/2026-06-05-list-hygiene-design.md §5.6 (the plan-deferral descendant of the list-hygiene type system). Maintenance/review of the section rides on the session bookends + hygiene routine, not the skill.

2.3 Isolation — git-backed by default

The skill names the domain-neutral kernel — isolate in-progress execution from the source of truth — and assumes git-backed by default (most work wants revision history; most output is markdown, trivially git-friendly), with the bare kernel as fallback for the rare thing that can't live in git. Git mechanism = a worktree (or branch) under .worktrees/, isolated from main, merged back when the work checks out. Adopts the using-git-worktrees isolation kernel (detect-existing-isolation first; prefer the native worktree tool; gitignore .worktrees/; never write on main without consent). The worktree lifecycle belongs to the session bookends (/good-morning create-or-resume, /save-progress merge/keep/discard), not the skill.

  • Rejected: pushing worktrees up to the domain-driven layer — wouldn't serve Yggdrasil planning its own git-backed work.

2.4 Design-review lenses (four, orthogonal) + placement

Selection principle: a lens earns its place only if it catches a class of holes the others miss (each a distinct axis — no hallucinated consensus). Lenses: Skeptic (robustness/failure), User Advocate (human experience), Steward (durability over time — our addition, fits the /clear-reliance), Constraint Guardian (the stated bar). Harvested from the community multi-agent-brainstorming skill, run our way; the Arbiter is the human.

  • Forward (woven single-thread into brainstorming Steps 2/4/5) — sharpens existing steps, no ceremony.
  • Backward (the finished-plan audit, in the planning skill) — a 3-way opt-in scaled to how much the work matters: skip / single-thread roleplay / independent subagents. Never mandatory.

2.5 Advisory subagents — allowed; autonomous ones not

Independent subagents permitted as critique lenses only when: read-only/read-mostly; product is critique (never decisions/writing/actions); facilitator-mediated (routes through Claude → Brad); independence is the justification. Yggdrasil rejects agent autonomy, not agent parallelism. First realized use = the backward lens audit.

2.6 Handoff seam

planning ships disable-model-invocation: true — blocks programmatic/Skill-tool invocation, so brainstorming can only recommend /planning and Brad invokes it explicitly. The convention (recommend, don't chain) and the mechanism agree. allowed-tools: [Read, Glob, Grep] mirrors brainstorming (frictionless reads; Write/Edit/Bash omitted so plan-doc writes, commits, and git ops keep prompting).

2.7 writing-plans walk verdicts (keep / adapt / drop)

  • Keep: the zero-context-executor kernel (drop "engineer/codebase/TDD"); Scope Check; Self-Review; the "spell it out" rigor.
  • Adapt: File-Structure → "units/artifacts the plan touches"; the plan header (drop Tech Stack / "for agentic workers"; add a Design source back-pointer); save-path → mirror brainstorming's "save to the context the plan belongs to" (drop hardcoded docs/superpowers/plans/).
  • Drop: the subagent/inline autonomous Execution-Handoff fork → replaced with human-in-the-loop "walk the plan together, task by task."

3. The resulting artifact

skills/planning/SKILL.md (built 2026-06-08, ~373 lines), section order: Frontmatter · Overview · Start from the validated design · Scope Check · Map what the plan touches · Plan document header · Tasks (verifiable-outcome anchor + Task shape) · No untracked placeholders · The Deferred section · Isolate execution from the source of truth · Save the plan · Self-Review · Lens audit · Execution handoff · Exit Criteria · Key Principles. Authored via a section-by-section wording walk with Brad; coherence-polished (superpowers-provenance trimmed from the operative text; Map→Header→Tasks order; sizing deduped).

4. Open / deferred

  • Archival location once feature-complete (Brad, 2026-06-08). Decide where this design doc (and its siblings) ultimately live once Yggdrasil is judged feature-complete — an archive scheme for settled design docs. Folds into the bookmarked design-doc organization-scheme thread. Until then it stays in working/.
  • AGENTS.md / README.md methodology mention — the advisory-subagent + review-lens methodology was deferred "until the planning skill ships" (now due); tracked as a [priority] bookmark for a focused docs pass next.
  • Checkbox progress-tracking for tasks — bookmarked future revision.
  • Git-by-default in the bookend worktree wiring — bookmarked; make the assumption explicit there when that wiring is built.

5. Decision-trail references

  • working/current-plan.md — "Planning-skill design," "Next build," and Design- decisions catalog (recursive plan mechanism, advisory subagents, design-review lenses, borrowed-from-superpowers). The incremental decision log.
  • working/2026-06-05-list-hygiene-design.md §5.6 — the ## Deferred mechanism.
  • superpowers writing-plans — C:\Projects\superpowers\skills\writing-plans\SKILL.md.
  • multi-agent-brainstorming (sickn33/antigravity-awesome-skills) — the lens lineage.