@theglitchking/persistent-planning 3.0.0 → 3.1.0

package/commands/archive-plan.md

@@ -0,0 +1,66 @@
+---
+name: archive-plan
+description: "Retire a completed plan into the gitignored .planning/.archive/ directory. Refuses to archive a plan that still has unchecked boxes unless --force is passed. Works in both sm and lg mode."
+---
+
+# /archive-plan
+
+Move a finished plan out of the active tree so `.planning/` only ever shows work
+that is still live. Nothing is deleted — archiving is a move plus a status stamp,
+and is reversed by moving the directory back.
+
+---
+
+## Usage
+
+```
+/archive-plan <plan-slug>
+/archive-plan --all-complete
+/archive-plan <plan-slug> --force      # archive a plan that is not finished
+/archive-plan <plan-slug> --dry-run
+```
+
+## What To Do
+
+When the user runs `/archive-plan`:
+
+1. Run the script:
+
+```bash
+SCRIPT_DIR="$(dirname "$(readlink -f "$0")")/../scripts"
+bash "${SCRIPT_DIR}/archive-plan.sh" "<plan-slug>"
+```
+
+If the script isn't found at that path, try in order:
+
+```bash
+bash scripts/archive-plan.sh "<plan-slug>"
+bash ~/.claude/skills/persistent-planning/scripts/archive-plan.sh "<plan-slug>"
+```
+
+2. If the script refuses because the plan is incomplete, **do not reach for
+   `--force` on your own.** Run `/plan-status`, tell the user what is still
+   unchecked, and let them decide.
+
+## What it does
+
+1. Verifies the plan is complete (every checkbox checked, or `status: done`).
+2. Ensures `.planning/.archive/` exists and is listed in `.gitignore` — completed
+   plans are local history, not something every clone carries.
+3. Moves `.planning/<slug>/` to `.planning/.archive/<slug>/`, using `git mv` when
+   the plan is tracked so history follows it.
+4. Stamps the plan's top-level artifact: `status: archived` plus `archived_on`
+   (frontmatter), or a dated footer for sm plans that have no frontmatter.
+
+## Restoring
+
+```bash
+mv .planning/.archive/<slug> .planning/<slug>
+```
+
+Then set `status:` back to `active` and drop the `archived_on` stamp.
+
+## See also
+
+- `/plan-status` — see which plans are complete
+- `.documentation/procedures/plan-completion-and-archive.md` — the full completion protocol

package/commands/plan-status.md

@@ -0,0 +1,62 @@
+---
+name: plan-status
+description: "Show completion status for every plan under .planning/ — which are in progress, blocked, or complete and ready to archive. Works in both sm and lg mode."
+---
+
+# /plan-status
+
+Report where every plan stands. Completion is derived from the plan artifacts
+themselves (checkbox state + frontmatter `status:`), so it cannot drift away from
+what the plan actually says.
+
+---
+
+## Usage
+
+```
+/plan-status
+```
+
+## What To Do
+
+Run the status script:
+
+```bash
+SCRIPT_DIR="$(dirname "$(readlink -f "$0")")/../scripts"
+bash "${SCRIPT_DIR}/plan-status.sh"
+```
+
+If the script isn't found at that path, try in order:
+
+```bash
+bash scripts/plan-status.sh
+bash ~/.claude/skills/persistent-planning/scripts/plan-status.sh
+```
+
+Then read the table back to the user. If any plan is listed `COMPLETE`, offer to
+archive it with `/archive-plan <slug>`.
+
+## Verdicts
+
+| Verdict | Meaning |
+|---|---|
+| `in progress` | Unchecked boxes remain |
+| `blocked` | An atom in the plan carries `status: blocked` |
+| `COMPLETE` | Every box checked, or the top-level artifact says `status: done` — ready to archive |
+| `empty` | Plan artifact exists but has no checkboxes yet |
+| `archived` | Already retired (only visible if left in the active tree) |
+
+## Machine-readable forms
+
+```bash
+bash scripts/plan-status.sh --complete   # one complete plan slug per line
+bash scripts/plan-status.sh --nudge      # one-line notice, or silence
+```
+
+`--nudge` is what the SessionStart hook uses, so a finished plan gets mentioned
+at the top of the next session rather than being rediscovered later.
+
+## See also
+
+- `/archive-plan` — retire a completed plan into `.planning/.archive/`
+- `.documentation/procedures/plan-completion-and-archive.md` — the full completion protocol

package/commands/start-atom.md

@@ -69,7 +69,7 @@ Not every step needs a standalone atom file. The rule of thumb:
 - **Inline checkbox in `task.md`**: simple, self-contained step that doesn't need its own context file. The user (or the active agent) handles it directly.
 - **Standalone atom file via `/start-atom`**: a step that will be **handed off to a subagent**. Atoms get their own files because subagents need explicit inputs / outputs / acceptance criteria they can read structured rather than parse from prose.
 
-See `docs/atom-granularity.md` for full anti-pattern guidance with examples.
+See `.documentation/standards/atom-granularity.md` for full anti-pattern guidance with examples.
 
 ## Sequence semantics
 
@@ -89,5 +89,5 @@ This command refuses to run if the project is in sm mode. To switch:
 
 - `/start-planning` — initialize the planning structure (phase in lg)
 - `/start-task` — add a task under a phase
-- `docs/lg-mode.md` — full lg-mode layer model
-- `docs/atom-granularity.md` — when to spawn an atom file vs. inline checkbox
+- `.documentation/architecture/lg-mode.md` — full lg-mode layer model
+- `.documentation/standards/atom-granularity.md` — when to spawn an atom file vs. inline checkbox

package/commands/start-planning.md

@@ -111,5 +111,5 @@ Names are converted to URL-friendly slugs:
 
 - `/start-task` — add a task under a phase (lg mode only)
 - `/start-atom` — add an atom (subagent hand-off unit) under a task (lg mode only)
-- `docs/workspace-json.md` — workspace.json schema reference
-- `docs/lg-mode.md` — full lg-mode guide (phase / task / atom / notes layer model)
+- `.documentation/reference/workspace-json.md` — workspace.json schema reference
+- `.documentation/architecture/lg-mode.md` — full lg-mode guide (phase / task / atom / notes layer model)

package/commands/start-task.md

@@ -79,5 +79,5 @@ That writes `.planning/.meta/workspace.json` with `mode: "lg"` and creates the f
 
 - `/start-planning` — initialize the planning structure (phase in lg, task in sm)
 - `/start-atom` — add an atom under a task
-- `docs/lg-mode.md` — full lg-mode layer model
-- `docs/atom-granularity.md` — when to spawn an atom file vs. add an inline checkbox
+- `.documentation/architecture/lg-mode.md` — full lg-mode layer model
+- `.documentation/standards/atom-granularity.md` — when to spawn an atom file vs. add an inline checkbox

package/hooks/session-start.js

@@ -1,13 +1,84 @@
 #!/usr/bin/env node
 // persistent-planning SessionStart hook.
-// Delegates entirely to @theglitchking/claude-plugin-runtime — this plugin
-// has no mcp.json wiring or project-side reconcile, so only the update
-// check runs.
+//
+// Two jobs:
+//   1. The update check, delegated entirely to @theglitchking/claude-plugin-runtime.
+//   2. A completion nudge: if any plan under .planning/ has every box checked
+//      but is still sitting in the active tree, say so, so the agent archives it
+//      instead of rediscovering a finished plan next session.
 
 import { runSessionStart } from "@theglitchking/claude-plugin-runtime";
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
-await runSessionStart({
-  packageName: "@theglitchking/persistent-planning",
-  pluginName: "persistent-planning",
-  configFile: "persistent-planning.json",
-});
+const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function planNudge() {
+  try {
+    if (!existsSync(join(projectRoot, ".planning"))) return "";
+    const script = join(packageRoot, "scripts", "plan-status.sh");
+    if (!existsSync(script)) return "";
+    const r = spawnSync("bash", [script, "--nudge"], {
+      cwd: projectRoot,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
+      encoding: "utf8",
+      timeout: 5000,
+    });
+    return (r.stdout || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+const notice = planNudge();
+
+if (!notice) {
+  await runSessionStart({
+    packageName: "@theglitchking/persistent-planning",
+    pluginName: "persistent-planning",
+    configFile: "persistent-planning.json",
+  });
+} else {
+  // ponytail: the runtime owns the one SessionStart JSON response and exposes no
+  // hook for appending to it, and a second response line on stdout is invalid.
+  // So intercept its single write and merge the nudge into that same payload.
+  // Fails open — anything unexpected is written through untouched.
+  const realWrite = process.stdout.write.bind(process.stdout);
+  let merged = false;
+  process.stdout.write = (chunk, ...rest) => {
+    if (!merged) {
+      try {
+        const payload = JSON.parse(String(chunk));
+        const out = payload?.hookSpecificOutput;
+        if (out && out.hookEventName === "SessionStart") {
+          out.additionalContext = out.additionalContext
+            ? `${out.additionalContext}\n${notice}`
+            : notice;
+          merged = true;
+          return realWrite(JSON.stringify(payload) + "\n", ...rest);
+        }
+      } catch {
+        // Not the response payload — fall through and write it as-is.
+      }
+    }
+    return realWrite(chunk, ...rest);
+  };
+
+  await runSessionStart({
+    packageName: "@theglitchking/persistent-planning",
+    pluginName: "persistent-planning",
+    configFile: "persistent-planning.json",
+  });
+
+  // The runtime can return without emitting (e.g. it chdir-failed). Say our piece.
+  if (!merged) {
+    realWrite(
+      JSON.stringify({
+        hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: notice },
+      }) + "\n"
+    );
+  }
+}

package/package.json

@@ -1,21 +1,24 @@
 {
   "name": "@theglitchking/persistent-planning",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
   "type": "module",
   "bin": {
     "persistent-planning": "bin/persistent-planning.js"
   },
   "scripts": {
-    "postinstall": "node scripts/link-skills.js"
+    "postinstall": "node scripts/link-skills.js",
+    "test": "bash tests/run.sh"
   },
   "files": [
     "bin/",
     "commands/",
     "hooks/",
-    "scripts/link-skills.js",
+    "scripts/",
+    "templates/",
     "skills/",
-    "docs/",
+    ".documentation/",
+    "!.documentation/reports",
     ".claude-plugin/",
     "README.md",
     "LICENSE",
@@ -56,6 +59,7 @@
     "commander": "^14.0.0"
   },
   "devDependencies": {
+    "@theglitchking/hit-em-with-the-docs": "^2.9.0",
     "@theglitchking/semantic-pages": "^0.10.0"
   }
 }

package/scripts/archive-plan.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+###############################################################################
+# archive-plan.sh - Retire a completed plan into .planning/.archive/
+#
+# Usage:
+#   bash scripts/archive-plan.sh <plan-slug>
+#   bash scripts/archive-plan.sh --all-complete
+#   bash scripts/archive-plan.sh <plan-slug> --force     # archive an unfinished plan
+#   bash scripts/archive-plan.sh <plan-slug> --dry-run
+#
+# What it does:
+#   1. Refuses unless the plan is complete (every checkbox checked, or the
+#      top-level artifact declares `status: done`) -- override with --force.
+#   2. Ensures .planning/.archive/ exists and is gitignored.
+#   3. Moves .planning/<slug>/ to .planning/.archive/<slug>/ (git mv when the
+#      plan is tracked, so history follows it).
+#   4. Stamps the plan's top-level artifact with status: archived + archived_on.
+#
+# Nothing is ever deleted. Restore by moving the directory back out.
+###############################################################################
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/lib/planning.sh"
+
+SLUG=""
+ALL_COMPLETE=0
+FORCE=0
+DRY_RUN=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --all-complete) ALL_COMPLETE=1; shift ;;
+    --force)        FORCE=1; shift ;;
+    --dry-run)      DRY_RUN=1; shift ;;
+    -h|--help)      sed -n '2,20p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    -*)             planning_err "Unknown option: $1"; exit 1 ;;
+    *)              [[ -z "$SLUG" ]] && SLUG="$1"; shift ;;
+  esac
+done
+
+if [[ -z "$SLUG" && $ALL_COMPLETE -eq 0 ]]; then
+  planning_err "A plan slug is required (or --all-complete)."
+  echo "Usage: bash scripts/archive-plan.sh <plan-slug> [--force] [--dry-run]"
+  exit 1
+fi
+
+ROOT=$(planning_root)
+PLANNING="$(planning_dir)"
+ARCHIVE="${PLANNING}/.archive"
+TODAY=$(planning_today)
+
+# .planning/.archive/ must be gitignored: completed plans are local history, not
+# something every clone should carry. Idempotent.
+ensure_gitignored() {
+  local gitignore="${ROOT}/.gitignore"
+  grep -qE '^\.planning/?$' "$gitignore" 2>/dev/null && return 0   # whole tree already ignored
+  grep -qE '^\.planning/\.archive/?$' "$gitignore" 2>/dev/null && return 0
+  printf '\n# Completed plans retired by scripts/archive-plan.sh (local history)\n.planning/.archive/\n' >> "$gitignore"
+  planning_ok "Added .planning/.archive/ to .gitignore"
+}
+
+plan_root_artifact() {
+  for f in "$1/phase.md" "$1/task_plan.md" "$1/task.md"; do
+    [[ -f "$f" ]] && { echo "$f"; return; }
+  done
+}
+
+# Stamp the plan's top-level artifact so an archived plan reads as archived even
+# when someone opens the file directly, with no directory context.
+stamp_archived() {
+  local file="$1"
+  [[ -f "$file" ]] || return 0
+  if head -1 "$file" | grep -q '^---$'; then
+    # Frontmatter: flip status and add archived_on before the closing delimiter.
+    awk -v today="$TODAY" '
+      NR == 1 { print; next }
+      !done_fm && /^status:[[:space:]]*/ { print "status: archived"; seen_status = 1; next }
+      !done_fm && /^---$/ {
+        if (!seen_status) print "status: archived"
+        print "archived_on: \"" today "\""
+        print; done_fm = 1; next
+      }
+      { print }
+    ' "$file" > "${file}.tmp" && mv "${file}.tmp" "$file"
+  else
+    printf '\n---\n\n**Archived %s** — retired by `scripts/archive-plan.sh`.\n' "$TODAY" >> "$file"
+  fi
+}
+
+archive_one() {
+  local slug="$1"
+  local src="${PLANNING}/${slug}"
+  local dest="${ARCHIVE}/${slug}"
+
+  if [[ ! -d "$src" ]]; then
+    planning_err "No such plan: .planning/${slug}/"
+    return 1
+  fi
+  if [[ -e "$dest" ]]; then
+    planning_err "Already archived: .planning/.archive/${slug}/ exists. Move or rename it first."
+    return 1
+  fi
+
+  if [[ $FORCE -eq 0 ]]; then
+    local complete
+    complete=$(bash "${SCRIPT_DIR}/plan-status.sh" --complete | grep -Fx "$slug" || true)
+    if [[ -z "$complete" ]]; then
+      planning_err "Plan '${slug}' is not complete — refusing to archive."
+      echo "  Check what is outstanding with: bash scripts/plan-status.sh"
+      echo "  Archive anyway with:            bash scripts/archive-plan.sh ${slug} --force"
+      return 1
+    fi
+  fi
+
+  if [[ $DRY_RUN -eq 1 ]]; then
+    planning_log "[dry-run] would archive .planning/${slug}/ -> .planning/.archive/${slug}/"
+    return 0
+  fi
+
+  ensure_gitignored
+  mkdir -p "$ARCHIVE"
+
+  if git -C "$ROOT" rev-parse --git-dir >/dev/null 2>&1 \
+     && [[ -n "$(git -C "$ROOT" ls-files ".planning/${slug}" 2>/dev/null)" ]]; then
+    git -C "$ROOT" mv ".planning/${slug}" ".planning/.archive/${slug}"
+  else
+    mv "$src" "$dest"
+  fi
+
+  stamp_archived "$(plan_root_artifact "$dest")"
+  planning_ok "Archived .planning/${slug}/ -> .planning/.archive/${slug}/"
+}
+
+RC=0
+if [[ $ALL_COMPLETE -eq 1 ]]; then
+  mapfile -t SLUGS < <(bash "${SCRIPT_DIR}/plan-status.sh" --complete)
+  if [[ ${#SLUGS[@]} -eq 0 || -z "${SLUGS[0]}" ]]; then
+    planning_log "No complete plans to archive."
+    exit 0
+  fi
+  for s in "${SLUGS[@]}"; do archive_one "$s" || RC=1; done
+else
+  archive_one "$SLUG" || RC=1
+fi
+exit $RC

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)"