@theglitchking/persistent-planning 2.0.0 → 3.0.1

package/docs/atom-granularity.md

@@ -0,0 +1,156 @@
+---
+title: Atom Granularity (anti-pattern guide)
+tier: standard
+domains:
+  - planning
+status: active
+last_updated: 2026-05-07
+version: 1.0.0
+audience:
+  - developers
+purpose: When to spawn a standalone atom file vs. add an inline atom checkbox to task.md. The atom layer is load-bearing for subagent hand-off; this doc keeps it from being misused.
+---
+
+# Atom Granularity
+
+This is anti-pattern guidance for **lg-mode** planning. Sm-mode users can ignore this — sm has only `task_plan.md` with inline checkboxes throughout.
+
+## The two kinds of atoms
+
+In lg mode, "atom" can mean two different artifacts:
+
+1. **Inline atom checkbox** in `task.md`:
+   ```markdown
+   ## Atoms
+   - [ ] Bump version to 3.0.0 in package.json
+   - [ ] Update CHANGELOG entry
+   - [ ] Run npm publish
+   ```
+
+2. **Standalone atom file** at `.planning/<phase>/<task>/atoms/<atom-slug>.md`:
+   ```markdown
+   ---
+   title: Bump version to 3.0.0
+   tier: plan
+   plan_kind: atom
+   parent: release-3-0-0
+   sequence: 1
+   status: ready
+   ---
+
+   # Atom: Bump version to 3.0.0
+
+   ## What to do
+   ...
+   ## Inputs
+   ...
+   ## Expected outputs
+   ...
+   ## Acceptance criteria
+   ...
+   ```
+
+Both are valid. The question is **when to use which**.
+
+## The rule
+
+**Inline checkbox**: simple, self-contained step that doesn't need its own context file.
+The active agent handles it directly while working through the task.
+
+**Standalone atom file**: a step that will be **handed off to a subagent**.
+Subagents need explicit inputs / outputs / acceptance criteria they can read
+structured rather than parse from prose. Standalone atoms exist to make the
+hand-off contract explicit and machine-readable.
+
+## Examples
+
+### ✅ Use inline checkbox
+
+```markdown
+## Atoms
+- [ ] Bump package.json to 3.0.0
+- [ ] Add CHANGELOG entry under "## [3.0.0]"
+- [ ] Run `npm test` and confirm all pass
+```
+
+These are mechanical, self-evident, and don't need their own files. The active
+agent reads task.md, executes them, and ticks them off.
+
+### ✅ Use standalone atom file
+
+```markdown
+## Atoms
+(see atoms/ for files)
+```
+
+With:
+
+```
+atoms/
+├── 01-extract-embedder-to-shared-package.md
+├── 02-refactor-vault-indexer-to-registry-driven.md
+└── 03-add-corpora-json-schema.md
+```
+
+Each of these is a meaty, multi-step refactor with non-obvious context (which
+files to touch, what shape the resulting code should take, how to verify).
+Subagents picking these up need explicit briefing — that's what the standalone
+atom file provides.
+
+## Anti-patterns
+
+### 🚫 Standalone atom for a one-liner
+
+If the atom file ends up being mostly empty (`## What to do` is one sentence,
+`## Acceptance criteria` is "ran the command"), it's overhead. Use an inline
+checkbox.
+
+### 🚫 Inline checkboxes for multi-step subagent work
+
+If the checkbox is `- [ ] Refactor the indexer to support multi-corpus`, you've
+pushed too much into one inline checkbox. A subagent picking up "refactor the
+indexer" has no idea what scope, what files, or what success looks like. Spawn
+a standalone atom (or several — one per logical refactor step).
+
+### 🚫 Mixing — inline checkboxes that are subagent hand-offs
+
+Don't have inline checkboxes that say "subagent: do X" without an atom file.
+Either it's small enough for the active agent (inline) or it's big enough for
+hand-off (atom file). The line between them is "is the subagent going to need
+to ask questions?"
+
+## Heuristic
+
+Ask: **could a fresh subagent walk into this and complete the work without
+asking the user a clarifying question?**
+
+- If yes → inline checkbox is fine
+- If no → spawn an atom file with explicit Inputs / Outputs / Acceptance
+  criteria
+
+## Sequence semantics
+
+Standalone atoms have explicit `sequence:` ordering. The planning MCP's
+`next_atom(task)` verb returns the next `status: ready` atom in sequence order.
+
+Sequential matches the single-agent reality. If you have N atoms in a task,
+they hand off one at a time, in order. This eliminates filesystem race
+conditions on claim and matches how agentic coding actually flows today.
+
+If you have a genuinely parallel-atom workload (multiple subagents working
+simultaneously on independent atoms within one task), that's a Phase 4.x
+conversation — today, atoms hand off one at a time.
+
+## Reopen semantics
+
+A `done` atom can be reopened to `in_progress` if a follow-up correction is
+needed. The frontmatter gets a `reopened_at: <iso-timestamp>` audit field.
+Don't use this for "the work was wrong, redo it" — for that, the cleaner move
+is to add a NEW atom that explains what to fix and why. Reopening is for "this
+was almost done but missed a small detail."
+
+## See also
+
+- `/start-atom` — slash command to spawn a standalone atom file
+- `templates/lg/atom.md` — the atom file template
+- `templates/lg/task.md` — the task template (inline checkbox section)

package/docs/lg-mode.md

@@ -0,0 +1,135 @@
+---
+title: Lg-Mode Layered Planning Guide
+tier: guide
+domains:
+  - planning
+status: active
+last_updated: 2026-05-07
+version: 1.0.0
+audience:
+  - developers
+purpose: Full guide to lg-mode (large/team) persistent-planning — phase / task / atom / notes layered model, scheduling defaults, subagent contract, and integration with semantic-memory MCP.
+---
+
+# Lg-Mode (Layered Planning)
+
+Lg mode was introduced in **persistent-planning 3.0.0**. It complements the original sm-mode flow without replacing it — solo devs and quick spikes still get the v2 single-task experience.
+
+## When to use lg mode
+
+- 2+ contributors over the last 90 days (auto-detected → lg)
+- Multi-week or multi-task project with strategic boundaries (phases)
+- Subagent hand-off needed for parallel or sequenced work
+- Wanting the plan to integrate with semantic-memory's MCP (lg plans carry HEWTD frontmatter)
+
+If none of those apply, sm mode is faster and lighter. You can always run `/start-planning --mode lg "name"` to switch.
+
+## The four layers
+
+| Layer | File | Purpose |
+|---|---|---|
+| **Phase** | `<phase-slug>/phase.md` | Strategic grouping; multi-task boundary |
+| **Task** | `<phase-slug>/<task-slug>/task.md` | Bounded deliverable; mid-level summary |
+| **Atom** | `<phase-slug>/<task-slug>/atoms/<atom-slug>.md` | Subagent hand-off unit |
+| **Notes** | `<phase-slug>/notes.md` or `<task-slug>/notes.md` | Cross-cutting references |
+
+Notes are scoped to either a phase or a task (or both). Notes are NOT part of the hierarchy — they're cross-cutting context.
+
+## Directory layout
+
+```
+.planning/
+├── .meta/
+│   └── workspace.json              # {mode: "lg", auto_detected: true, ...}
+├── archive/
+│   └── <archived-phase-slug>/      # phases moved here on status: archived
+└── <phase-slug>/
+    ├── phase.md                    # the phase
+    ├── notes.md                    # phase-scoped notes
+    └── <task-slug>/
+        ├── task.md                 # the task
+        ├── notes.md                # task-scoped notes
+        └── atoms/
+            ├── <atom-slug>.md      # sequence: 1
+            └── <atom-slug>.md      # sequence: 2
+```
+
+A standalone task (without a phase) lives at `.planning/<task-slug>/` — same as sm mode but with HEWTD frontmatter and the new templates.
+
+## Lifecycle status
+
+Each layer has a status enum tracked in frontmatter:
+
+- **phase.status**: `draft | active | paused | done | archived`
+- **task.status**: same enum
+- **atom.status**: `ready | in_progress | done | blocked`
+
+Status transitions are explicit. Atoms additionally support **reopen** (`done → in_progress`) with a `reopened_at: <iso-timestamp>` audit field for legitimate post-completion fixes.
+
+When a phase is marked `archived`, the entire `<phase-slug>/` directory moves to `archive/<phase-slug>/`. Atoms and tasks within move with it.
+
+## Scheduling: dependencies-first, then parallelism
+
+Tasks declare scheduling intent in frontmatter:
+
+```yaml
+plan_kind: task
+parent: foundation
+depends_on: [hewtd-schema-extension]   # this task waits for that one
+parallelizable: false                  # only true if no inter-deps
+```
+
+The planning MCP's `next_task(phase)` verb (added in semantic-memory 1.0) walks the `depends_on` graph and returns the next ready task respecting the order. Tasks with `parallelizable: true` and no inter-deps can be returned in any order — perfect for subagent teams picking up work concurrently.
+
+**Atoms within a task default to sequential** (`sequence: 1, 2, 3...`). Atom-level parallelism is a Phase 4.x conversation.
+
+## Subagent contract
+
+Lg-mode plans are designed to be **read by subagents via semantic-memory MCP verbs**, not by parsing markdown. The contract:
+
+- `read_phase(slug)`, `read_task(slug)`, `read_atom(slug)`, `read_notes(scope?)`
+- `list_phases(status?)`, `list_tasks(phase?, status?)`, `list_atoms(task?, status?)`
+- `next_task(phase, exclude_in_progress?)` — respects depends_on + parallelizable
+- `next_atom(task)` — returns the next ready atom in sequence
+- `update_atom_status(slug, status)`, `update_task_status(slug, status)`, `update_phase_status(slug, status)`
+- `get_planning_context(scope, slug)` — bundles parent chain + sibling status + relevant notes for one read; the subagent's primary "load my context" verb
+- `append_notes(scope, slug, content)` — append-only writer for notes during execution
+
+These verbs ship in semantic-memory 1.0 (registered conditionally on the `plans` corpus being active). When semantic-memory is absent, persistent-planning falls back to filesystem-based reads — slash commands still work; subagent comprehension degrades.
+
+## HEWTD frontmatter
+
+Every layer carries HEWTD-aligned frontmatter (`tier: plan`). The `version` field is intentionally omitted — HEWTD 2.2.0 makes it conditionally optional for plan-tier docs (plans use lifecycle status, not semver).
+
+This means lg-mode plans:
+- Validate against HEWTD's metadata schema
+- Are searchable + filterable by HEWTD's domain / load_priority / status fields
+- Get indexed by semantic-memory's `plans` corpus for free
+- Get drift-detected against the codebase by semantic-memory's drift verb (when both code corpus + plans corpus are active)
+
+## Migration from v2 (sm)
+
+Existing `.planning/<task-slug>/{task_plan.md, notes.md}` directories continue to work without changes. They're treated as sm-mode tasks. The first time you run `/start-planning` on a project that auto-detects to lg, a `.planning/.meta/workspace.json` is written and lg-mode flow begins for new plans. Existing v2 plans aren't migrated — they coexist.
+
+To explicitly migrate a v2 plan to lg, manually:
+1. `mkdir .planning/<phase-slug>` and create `phase.md` with the high-level goal
+2. Move the existing `<task-slug>/` under it
+3. Convert `task_plan.md` → `task.md` (rename + add HEWTD frontmatter)
+
+## Slash commands
+
+| Command | Mode | Creates |
+|---|---|---|
+| `/start-planning "<name>"` | sm or lg (auto-detect) | sm: task; lg: phase |
+| `/start-planning "<name>" --mode lg` | lg (explicit) | phase |
+| `/start-planning "<name>" --mode sm` | sm (explicit) | task |
+| `/start-task "<name>" --parent <phase>` | lg only | task under phase |
+| `/start-atom "<name>" --parent <task>` | lg only | atom under task |
+
+## See also
+
+- `docs/workspace-json.md` — workspace.json schema reference
+- `docs/atom-granularity.md` — when to spawn an atom file vs. inline checkbox
+- `templates/lg/{phase,task,atom,notes}.md` — frontmatter shapes
+- `scripts/detect-mode.sh` — mode resolution logic
+- `scripts/init-{phase,task,atom}.sh` — init script implementations

package/docs/workspace-json.md

@@ -0,0 +1,85 @@
+---
+title: workspace.json schema
+tier: standard
+domains:
+  - planning
+status: active
+last_updated: 2026-05-07
+version: 1.0.0
+audience:
+  - developers
+purpose: Document the .planning/.meta/workspace.json schema introduced in v3.0 for sm/lg mode tracking
+---
+
+# `workspace.json` schema (v3.0)
+
+Introduced in persistent-planning **3.0.0**. Tracks per-project planning mode and
+detection state. Lives at `.planning/.meta/workspace.json`.
+
+## Schema
+
+```json
+{
+  "schema_version": "1.0",
+  "mode": "sm" | "lg",
+  "auto_detected": true | false,
+  "detected_contributors": <integer>,
+  "created_at": "<ISO 8601 timestamp>"
+}
+```
+
+## Field reference
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `schema_version` | string | yes | Schema version of this file. Currently `"1.0"`. |
+| `mode` | `"sm"` \| `"lg"` | yes | Active planning mode for this project. |
+| `auto_detected` | boolean | yes | `true` if mode was determined by the heuristic, `false` if explicitly set via `--mode`. |
+| `detected_contributors` | integer | yes (when `auto_detected=true`) | Distinct git author email count over the last 90 days at detection time. |
+| `created_at` | string (ISO 8601) | yes | When this workspace.json was first written. |
+
+## Mode determination
+
+`detect-mode.sh` resolves the active mode using this precedence (first match wins):
+
+1. **Explicit override**: if `workspace.json` exists with a `"mode"` field, that value wins.
+2. **Auto-detect**: count distinct git author emails over the last 90 days. ≥ 2 → `"lg"`. Otherwise → `"sm"`.
+3. **Fallback**: if neither applies (no git repo, git fails), default to `"sm"`.
+
+The override is sticky — once written, future runs read `workspace.json` and skip
+re-detection. Override the override by editing `workspace.json` directly or by passing
+`--mode sm` / `--mode lg` to `/start-planning` (which rewrites the file).
+
+## Mode behavior
+
+### `sm` (small / solo)
+- Single-task model — `.planning/<task-slug>/{task_plan.md, notes.md}`
+- Identical to v2 behavior; existing v2 plans continue to work without migration
+- No HEWTD frontmatter on plans (frontmatter is plain text)
+- Single slash command: `/start-planning "Task name"`
+
+### `lg` (large / team)
+- Layered model: phase → task → atom + cross-cutting notes
+- Directory layout: `.planning/<phase-slug>/<task-slug>/{task.md, notes.md, atoms/<atom-slug>.md}`
+- HEWTD frontmatter on every layer (`tier: plan`, conditionally version-exempt per HEWTD 2.2.0)
+- Three slash commands: `/start-planning` (phase), `/start-task --parent <phase>`, `/start-atom --parent <task>`
+- Sequential atom hand-offs; tasks can declare `depends_on` + `parallelizable` for subagent team scheduling
+
+## Backwards compatibility
+
+Existing `.planning/<task-slug>/` folders without `.meta/` continue to work as `sm`.
+Mode detection only writes `workspace.json` when `/start-planning` is run after v3.0
+upgrade — pure read operations don't trigger writes.
+
+## Manual editing
+
+Safe to edit by hand. Common changes:
+
+- Switch mode: change `"mode"`, set `"auto_detected": false`
+- Reset auto-detection: delete the file; the next `/start-planning` will re-detect
+
+## See also
+
+- `scripts/detect-mode.sh` — the resolution logic
+- `templates/lg/{phase,task,atom,notes}.md` — frontmatter shape per layer
+- `~/workspace/the-glitch-kingdom/persistent-planning/.planning/layered-planning-with-mcp-and-hewtd-frontmatter/task_plan.md` — the meta-plan that drove this design

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/persistent-planning",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
     "bin/",
     "commands/",
     "hooks/",
-    "scripts/link-skills.js",
+    "scripts/",
+    "templates/",
     "skills/",
     "docs/",
     ".claude-plugin/",
@@ -54,5 +55,8 @@
   "dependencies": {
     "@theglitchking/claude-plugin-runtime": "^0.1.0",
     "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@theglitchking/semantic-pages": "^0.10.0"
   }
 }

package/scripts/detect-mode.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+###############################################################################
+# detect-mode.sh - Sm/lg mode detection for persistent-planning v3.0
+#
+# Usage:
+#   bash scripts/detect-mode.sh [--explain]
+#
+# Output:
+#   "sm" or "lg" on stdout. With --explain, also prints a one-line decision
+#   banner to stderr explaining which signals fired.
+#
+# Heuristic:
+#   - If $CLAUDE_PROJECT_DIR/.planning/.meta/workspace.json exists with a
+#     "mode" field, that wins (override is sticky).
+#   - Otherwise count distinct git authors over the last 90 days. Two or
+#     more distinct emails → "lg". Otherwise "sm".
+#   - If the repo isn't a git repo or git fails for any reason, default
+#     to "sm" (the safer/less-surprising option for solo flows).
+#
+# Why this design:
+#   - Solo devs get the historical sm experience with zero ceremony.
+#   - Multi-contributor projects get the layered model surface immediately.
+#   - The decision banner avoids "magic" — the user sees what fired.
+#   - The workspace.json override means a single --mode flag sticks for
+#     all subsequent runs (no flag needed every time).
+###############################################################################
+set -e
+
+EXPLAIN=0
+if [[ "${1:-}" == "--explain" ]]; then
+  EXPLAIN=1
+fi
+
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+WORKSPACE_JSON="${PROJECT_ROOT}/.planning/.meta/workspace.json"
+
+# 1. Override wins if workspace.json exists
+if [[ -f "$WORKSPACE_JSON" ]]; then
+  # Naive jq-free read: grep the mode line. workspace.json is small/structured.
+  MODE_FROM_JSON=$(grep -oE '"mode"[[:space:]]*:[[:space:]]*"(sm|lg)"' "$WORKSPACE_JSON" | sed -E 's/.*"(sm|lg)".*/\1/')
+  if [[ "$MODE_FROM_JSON" == "sm" || "$MODE_FROM_JSON" == "lg" ]]; then
+    echo "$MODE_FROM_JSON"
+    if [[ $EXPLAIN -eq 1 ]]; then
+      echo "[mode] $MODE_FROM_JSON (from .planning/.meta/workspace.json)" >&2
+    fi
+    exit 0
+  fi
+fi
+
+# 2. Auto-detect via git author count over 90 days
+DETECTED="sm"
+CONTRIB=0
+if command -v git >/dev/null 2>&1 && git -C "$PROJECT_ROOT" rev-parse --git-dir >/dev/null 2>&1; then
+  CONTRIB=$(git -C "$PROJECT_ROOT" log --since="90 days ago" --format='%ae' 2>/dev/null | sort -u | wc -l | tr -d ' ')
+  if [[ "$CONTRIB" -ge 2 ]]; then
+    DETECTED="lg"
+  fi
+fi
+
+echo "$DETECTED"
+if [[ $EXPLAIN -eq 1 ]]; then
+  if [[ "$DETECTED" == "lg" ]]; then
+    echo "[mode] lg (auto-detected: $CONTRIB distinct git authors over the last 90 days; threshold ≥ 2)" >&2
+  else
+    echo "[mode] sm (auto-detected: $CONTRIB distinct git authors over the last 90 days; threshold for lg is ≥ 2)" >&2
+  fi
+fi

package/scripts/init-atom.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+###############################################################################
+# init-atom.sh - Create a new atom (subagent hand-off unit) under a task in lg mode
+#
+# Usage:
+#   bash scripts/init-atom.sh "Atom Name" --parent <task-slug>
+#
+# Creates:
+#   .planning/<phase-slug>/<task-slug>/atoms/<atom-slug>.md
+#
+# The atom's sequence number is auto-assigned: 1 + (max existing sequence in
+# the same task's atoms/ directory). Atoms within a task default to sequential
+# processing.
+#
+# --parent must be a task-slug. The phase is auto-resolved by walking the
+# .planning/ tree to find the task.
+###############################################################################
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/lib/planning.sh"
+
+# Parse arguments
+ATOM_NAME=""
+PARENT_TASK=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --parent)
+      PARENT_TASK="$2"
+      shift 2
+      ;;
+    -h|--help)
+      cat <<EOF
+Usage: bash scripts/init-atom.sh "Atom Name" --parent <task-slug>
+
+Examples:
+  bash scripts/init-atom.sh "Update zod schema" --parent hewtd-schema-extension
+  bash scripts/init-atom.sh "Add plan-tier tests" --parent hewtd-schema-extension
+EOF
+      exit 0
+      ;;
+    *)
+      if [[ -z "$ATOM_NAME" ]]; then
+        ATOM_NAME="$1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [[ -z "$ATOM_NAME" || -z "$PARENT_TASK" ]]; then
+  planning_err "Both atom name and --parent <task-slug> are required."
+  echo "Usage: bash scripts/init-atom.sh \"Atom Name\" --parent <task-slug>"
+  exit 1
+fi
+
+ATOM_SLUG=$(planning_slugify "$ATOM_NAME")
+
+if [[ -z "$ATOM_SLUG" ]]; then
+  planning_err "Atom name must contain at least one alphanumeric character."
+  exit 1
+fi
+
+MODE=$(planning_mode)
+if [[ "$MODE" != "lg" ]]; then
+  planning_err "Current mode is '$MODE' but init-atom.sh requires lg mode."
+  exit 1
+fi
+
+ROOT=$(planning_root)
+PLANNING="$(planning_dir)"
+TODAY=$(planning_today)
+TEMPLATE_DIR="${ROOT}/templates/lg"
+
+if [[ ! -d "$TEMPLATE_DIR" ]]; then
+  TEMPLATE_DIR="${SCRIPT_DIR}/../templates/lg"
+fi
+if [[ ! -d "$TEMPLATE_DIR" ]]; then
+  planning_err "Cannot locate templates/lg directory."
+  exit 1
+fi
+
+# Find the parent task — walk .planning/<phase>/<task>/task.md
+TASK_DIR=""
+for phase_path in "${PLANNING}"/*/; do
+  candidate="${phase_path%/}/${PARENT_TASK}"
+  if [[ -f "${candidate}/task.md" ]]; then
+    TASK_DIR="$candidate"
+    break
+  fi
+done
+
+if [[ -z "$TASK_DIR" ]]; then
+  planning_err "Parent task '${PARENT_TASK}' not found under .planning/<phase>/."
+  echo ""
+  echo "Available tasks:"
+  for phase_path in "${PLANNING}"/*/; do
+    phase_slug=$(basename "$phase_path")
+    [[ "$phase_slug" == ".meta" || "$phase_slug" == "archive" ]] && continue
+    for task_path in "${phase_path%/}"/*/; do
+      task_slug=$(basename "$task_path")
+      if [[ -f "${task_path}task.md" ]]; then
+        echo "  --parent ${task_slug}     (in phase: ${phase_slug})"
+      fi
+    done
+  done
+  exit 1
+fi
+
+ATOMS_DIR="${TASK_DIR}/atoms"
+mkdir -p "$ATOMS_DIR"
+
+# Auto-assign sequence: 1 + max existing sequence in the atoms/ dir
+NEXT_SEQUENCE=1
+if compgen -G "${ATOMS_DIR}/*.md" >/dev/null 2>&1; then
+  MAX_SEQ=$(grep -h '^sequence:' "${ATOMS_DIR}"/*.md 2>/dev/null | grep -oE '[0-9]+' | sort -n | tail -1)
+  if [[ -n "$MAX_SEQ" ]]; then
+    NEXT_SEQUENCE=$((MAX_SEQ + 1))
+  fi
+fi
+
+planning_log "Initializing atom: ${ATOM_NAME} (parent: ${PARENT_TASK}, sequence: ${NEXT_SEQUENCE})"
+
+planning_render_and_log \
+  "${TEMPLATE_DIR}/atom.md" \
+  "${ATOMS_DIR}/${ATOM_SLUG}.md" \
+  "atom at ${ATOMS_DIR}/${ATOM_SLUG}.md (sequence: ${NEXT_SEQUENCE})" \
+  "ATOM_TITLE_PLACEHOLDER=${ATOM_NAME}" \
+  "TASK_SLUG_PLACEHOLDER=${PARENT_TASK}" \
+  "ATOM_DATE_PLACEHOLDER=${TODAY}" \
+  "ATOM_SEQUENCE_PLACEHOLDER=${NEXT_SEQUENCE}"
+
+echo ""
+planning_ok "Atom '${ATOM_NAME}' ready"
+echo ""
+echo "Next steps:"
+echo "  1. Edit ${ATOMS_DIR}/${ATOM_SLUG}.md to define what to do, inputs, outputs, and acceptance criteria"
+echo "  2. A subagent will pick up this atom when status: ready"
+echo "  3. Status transitions: ready → in_progress → done (or → blocked)"