@theglitchking/persistent-planning 3.0.0 → 3.0.1

package/.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Official marketplace for persistent-planning - Persistent markdown-based planning for Claude Code. Context engineering pattern with task directories, progress tracking, and working memory that persists across sessions.",
-    "version": "3.0.0"
+    "version": "3.0.1"
   },
   "plugins": [
     {
       "name": "persistent-planning",
       "description": "Persistent markdown-based planning for Claude Code. Uses on-disk markdown files as working memory for planning, progress tracking, and knowledge storage. Plans persist across sessions and support multiple concurrent tasks.",
-      "version": "3.0.0",
+      "version": "3.0.1",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "persistent-planning",
-  "version": "3.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",
   "author": {
     "name": "TheGlitchKing"

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.0.1] - 2026-05-08
+
+### Fixed
+- **Critical: lg-mode init scripts and templates were excluded from the npm package.** The 3.0.0 release had `scripts/link-skills.js` (singular file) in the package.json `files` array instead of `scripts/` (whole dir), and `templates/` was missing entirely. As a result, users installing v3.0.0 got the slash command markdown but the underlying `init-phase.sh`, `init-task.sh`, `init-atom.sh`, `detect-mode.sh`, `lib/planning.sh`, and the four lg-mode templates (`phase.md`, `task.md`, `atom.md`, `notes.md`) were all missing — meaning lg mode silently broke on first invocation.
+
+  This patch updates the `files` array to include `scripts/` and `templates/` directories, and bumps to 3.0.1. v3.0.0 should be considered broken; consumers should upgrade to 3.0.1 immediately.
+
+### How this happened
+The `files` array was the legacy v2 contents (which only needed `scripts/link-skills.js`). When v3.0 added new scripts and templates I missed updating the array. Caught when verifying the published 3.0.0 tarball contents.
+
 ## [3.0.0] - 2026-05-07
 
 ### Added — Lg-mode (large/team) layered planning

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/persistent-planning",
-  "version": "3.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/",

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

package/scripts/init-phase.sh

@@ -0,0 +1,141 @@
+#!/bin/bash
+###############################################################################
+# init-phase.sh - Create a new phase in lg-mode persistent-planning
+#
+# Usage:
+#   bash scripts/init-phase.sh "Phase Name"
+#
+# Creates:
+#   .planning/<phase-slug>/phase.md         (HEWTD-frontmattered phase template)
+#   .planning/<phase-slug>/notes.md         (cross-cutting notes for the phase)
+#   .planning/.meta/workspace.json          (mode = lg, on first phase init)
+#
+# Refuses to run unless mode is lg. Run init-planning.sh for sm-mode tasks.
+###############################################################################
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/lib/planning.sh"
+
+case "${1:-}" in
+  -h|--help)
+    cat <<EOF
+Usage: bash scripts/init-phase.sh "Phase Name"
+
+Creates:
+  .planning/<phase-slug>/phase.md
+  .planning/<phase-slug>/notes.md
+  .planning/.meta/workspace.json (on first phase init, with mode=lg)
+
+Refuses to run unless mode is lg. Run init-planning.sh for sm-mode tasks.
+
+Examples:
+  bash scripts/init-phase.sh "Foundation"
+  bash scripts/init-phase.sh "Multi-corpus refactor"
+EOF
+    exit 0
+    ;;
+  "")
+    planning_err "Phase name required."
+    echo ""
+    echo "Usage: bash scripts/init-phase.sh \"Phase Name\""
+    echo "       bash scripts/init-phase.sh --help"
+    exit 1
+    ;;
+esac
+
+PHASE_NAME="$1"
+PHASE_SLUG=$(planning_slugify "$PHASE_NAME")
+
+if [[ -z "$PHASE_SLUG" ]]; then
+  planning_err "Phase name must contain at least one alphanumeric character."
+  exit 1
+fi
+
+# Refuse to run in sm mode
+MODE=$(planning_mode)
+if [[ "$MODE" != "lg" ]]; then
+  planning_err "Current mode is '$MODE' but init-phase.sh requires lg mode."
+  echo ""
+  echo "Switch to lg mode by running:"
+  echo "  /start-planning --mode lg \"<phase name>\""
+  echo "or by editing .planning/.meta/workspace.json directly."
+  exit 1
+fi
+
+ROOT=$(planning_root)
+PLANNING="$(planning_dir)"
+META="$(planning_meta_dir)"
+WORKSPACE_JSON="$(planning_workspace_json)"
+TODAY=$(planning_today)
+PHASE_DIR="${PLANNING}/${PHASE_SLUG}"
+TEMPLATE_DIR="${ROOT}/templates/lg"
+
+# Fallback: when run from the installed plugin location, templates live in the
+# plugin's own directory, not the project root.
+if [[ ! -d "$TEMPLATE_DIR" ]]; then
+  TEMPLATE_DIR="${SCRIPT_DIR}/../templates/lg"
+fi
+if [[ ! -d "$TEMPLATE_DIR" ]]; then
+  planning_err "Cannot locate templates/lg directory. Tried:"
+  echo "  ${ROOT}/templates/lg"
+  echo "  ${SCRIPT_DIR}/../templates/lg"
+  exit 1
+fi
+
+planning_log "Initializing phase: ${PHASE_NAME}"
+
+# Bootstrap .planning/.meta/workspace.json if missing
+mkdir -p "$META"
+if [[ ! -f "$WORKSPACE_JSON" ]]; then
+  CONTRIB=0
+  if command -v git >/dev/null 2>&1 && git -C "$ROOT" rev-parse --git-dir >/dev/null 2>&1; then
+    CONTRIB=$(git -C "$ROOT" log --since="90 days ago" --format='%ae' 2>/dev/null | sort -u | wc -l | tr -d ' ')
+  fi
+  cat > "$WORKSPACE_JSON" <<EOF
+{
+  "schema_version": "1.0",
+  "mode": "lg",
+  "auto_detected": true,
+  "detected_contributors": ${CONTRIB},
+  "created_at": "$(date -Iseconds)"
+}
+EOF
+  planning_ok "Created .planning/.meta/workspace.json (mode=lg, contributors=${CONTRIB})"
+fi
+
+# Create phase directory
+mkdir -p "$PHASE_DIR"
+
+# Render phase.md
+planning_render_and_log \
+  "${TEMPLATE_DIR}/phase.md" \
+  "${PHASE_DIR}/phase.md" \
+  "phase.md at ${PHASE_DIR}/phase.md" \
+  "PHASE_TITLE_PLACEHOLDER=${PHASE_NAME}" \
+  "PHASE_SLUG_PLACEHOLDER=${PHASE_SLUG}" \
+  "PHASE_DATE_PLACEHOLDER=${TODAY}"
+
+# Render notes.md (scoped to the phase)
+planning_render_and_log \
+  "${TEMPLATE_DIR}/notes.md" \
+  "${PHASE_DIR}/notes.md" \
+  "notes.md at ${PHASE_DIR}/notes.md" \
+  "NOTES_TITLE_PLACEHOLDER=${PHASE_NAME} — Notes" \
+  "NOTES_SCOPE_PLACEHOLDER=${PHASE_SLUG}" \
+  "NOTES_DATE_PLACEHOLDER=${TODAY}"
+
+# Add .planning/ to .gitignore if missing (preserve existing behavior)
+GITIGNORE="${ROOT}/.gitignore"
+if [[ -f "$GITIGNORE" ]] && ! grep -q "^\.planning/" "$GITIGNORE"; then
+  echo ".planning/" >> "$GITIGNORE"
+  planning_ok "Added .planning/ to .gitignore"
+fi
+
+echo ""
+planning_ok "Phase '${PHASE_NAME}' ready at .planning/${PHASE_SLUG}/"
+echo ""
+echo "Next steps:"
+echo "  1. Edit .planning/${PHASE_SLUG}/phase.md to describe the phase goal"
+echo "  2. Add tasks with: /start-task \"<task name>\" --parent ${PHASE_SLUG}"
+echo "  3. Add cross-cutting context to .planning/${PHASE_SLUG}/notes.md"

package/scripts/init-planning.sh

@@ -0,0 +1,233 @@
+#!/bin/bash
+
+###############################################################################
+# init-planning.sh - Persistent Planning Directory Setup
+#
+# Part of the persistent-planning plugin by TheGlitchKing
+# https://github.com/TheGlitchKing/persistent-planning
+#
+# Usage:
+#   bash scripts/init-planning.sh [task-name]
+#   bash scripts/init-planning.sh "Refactor database layer"
+#
+# What it does:
+#   1. Creates .planning/[task-slug]/ directory (separate per task)
+#   2. Creates task_plan.md with templates
+#   3. Creates notes.md with templates
+#   4. Adds .planning/ to .gitignore (optional)
+#   5. Confirms creation and provides next steps
+#
+# Multiple tasks example:
+#   /start-planning "Refactor auth"      -> .planning/refactor-auth/
+#   /start-planning "Debug memory leak"  -> .planning/debug-memory-leak/
+#   Both plans coexist without conflicts!
+###############################################################################
+
+set -e
+
+# Validate that task name was provided
+if [ -z "$1" ]; then
+    echo "Error: Task name required"
+    echo ""
+    echo "Usage: bash scripts/init-planning.sh \"Your Task Name\""
+    echo ""
+    echo "Examples:"
+    echo "  bash scripts/init-planning.sh \"Refactor authentication\""
+    echo "  bash scripts/init-planning.sh \"Debug API performance\""
+    exit 1
+fi
+
+TASK_NAME="$1"
+
+# Convert task name to slug
+# "Refactor Authentication" -> "refactor-authentication"
+task_name_to_slug() {
+    local name="$1"
+    name=$(echo "$name" | tr '[:upper:]' '[:lower:]')
+    name=$(echo "$name" | sed 's/[[:space:]_]\+/-/g')
+    name=$(echo "$name" | sed 's/[^a-z0-9-]//g')
+    name=$(echo "$name" | sed 's/^-\+\|-\+$//g')
+    name=$(echo "$name" | sed 's/-\+/-/g')
+    echo "$name"
+}
+
+TASK_SLUG=$(task_name_to_slug "$TASK_NAME")
+
+# Validate slug
+if [ -z "$TASK_SLUG" ]; then
+    echo "Error: Task name must contain at least one alphanumeric character"
+    echo "Provided: $TASK_NAME"
+    exit 1
+fi
+
+# Determine project root
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PLANNING_DIR="${PROJECT_ROOT}/.planning"
+TASK_DIR="${PLANNING_DIR}/${TASK_SLUG}"
+
+# Color codes
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+echo -e "${BLUE}Initializing Planning Structure${NC}"
+echo ""
+
+# Step 1: Create .planning directory
+if [ ! -d "$PLANNING_DIR" ]; then
+    mkdir -p "$PLANNING_DIR"
+    echo -e "${GREEN}+${NC} Created .planning/ directory"
+else
+    echo -e "${YELLOW}*${NC} .planning/ directory exists"
+fi
+
+# Step 2: Create task directory
+if [ ! -d "$TASK_DIR" ]; then
+    mkdir -p "$TASK_DIR"
+    echo -e "${GREEN}+${NC} Created task directory: ${CYAN}.planning/${TASK_SLUG}/${NC}"
+else
+    echo -e "${YELLOW}*${NC} Task directory already exists: ${CYAN}.planning/${TASK_SLUG}/${NC}"
+fi
+
+# Step 3: Create task_plan.md
+TASK_PLAN_FILE="${TASK_DIR}/task_plan.md"
+if [ ! -f "$TASK_PLAN_FILE" ]; then
+    cat > "$TASK_PLAN_FILE" << 'EOF'
+# Task Plan: TASK_NAME_PLACEHOLDER
+
+## Goal
+[One sentence describing the end state]
+
+## Phases
+- [ ] Phase 1: Plan and setup
+- [ ] Phase 2: Research/gather information
+- [ ] Phase 3: Execute/build
+- [ ] Phase 4: Review and deliver
+
+## Key Questions
+1. [Question to answer]
+2. [Question to answer]
+
+## Decisions Made
+- [Decision]: [Rationale]
+
+## Errors Encountered
+- [Error]: [Resolution]
+
+## Status
+**Currently in Phase 1** - Setting up planning structure
+
+---
+
+## Notes
+- This file persists across sessions
+- Update status after each phase
+- Mark completed phases with [x]
+- Save research to notes.md instead of stuffing context
+EOF
+
+    sed -i "s/TASK_NAME_PLACEHOLDER/${TASK_NAME}/g" "$TASK_PLAN_FILE"
+    echo -e "${GREEN}+${NC} Created task_plan.md"
+else
+    echo -e "${YELLOW}*${NC} task_plan.md already exists (not overwritten)"
+fi
+
+# Step 4: Create notes.md
+NOTES_FILE="${TASK_DIR}/notes.md"
+if [ ! -f "$NOTES_FILE" ]; then
+    cat > "$NOTES_FILE" << 'EOF'
+# Notes: TASK_NAME_PLACEHOLDER
+
+## Key Findings
+- [Finding 1]
+- [Finding 2]
+
+## Research Sources
+- [Source 1]: [URL or reference]
+- [Source 2]: [URL or reference]
+
+## Synthesized Findings
+
+### [Category/Topic 1]
+- [Finding]
+- [Finding]
+
+### [Category/Topic 2]
+- [Finding]
+- [Finding]
+
+## Decisions Made
+- [Decision]: [Rationale]
+- [Decision]: [Rationale]
+
+## Errors & Solutions
+- [Error]: [Resolution]
+- [Error]: [Resolution]
+
+---
+
+## Append-Only Log
+Store findings here as you discover them. This builds a searchable history.
+
+### [Date/Time]
+- [What I found/did]
+EOF
+
+    sed -i "s/TASK_NAME_PLACEHOLDER/${TASK_NAME}/g" "$NOTES_FILE"
+    echo -e "${GREEN}+${NC} Created notes.md"
+else
+    echo -e "${YELLOW}*${NC} notes.md already exists (not overwritten)"
+fi
+
+# Step 5: Update .gitignore
+if [ -f "${PROJECT_ROOT}/.gitignore" ]; then
+    if ! grep -q "^\.planning/" "${PROJECT_ROOT}/.gitignore"; then
+        echo ".planning/" >> "${PROJECT_ROOT}/.gitignore"
+        echo -e "${GREEN}+${NC} Added .planning/ to .gitignore"
+    else
+        echo -e "${YELLOW}*${NC} .planning/ already in .gitignore"
+    fi
+else
+    echo -e "${YELLOW}*${NC} No .gitignore found (not added)"
+fi
+
+# Step 6: List other active tasks
+OTHER_TASKS=$(find "$PLANNING_DIR" -maxdepth 1 -type d -not -name ".planning" -not -path "$TASK_DIR" 2>/dev/null | wc -l)
+if [ "$OTHER_TASKS" -gt 0 ]; then
+    echo ""
+    echo -e "${CYAN}Other active tasks:${NC}"
+    find "$PLANNING_DIR" -maxdepth 1 -type d -not -name ".planning" -not -path "$TASK_DIR" | sort | while read dir; do
+        task_slug=$(basename "$dir")
+        echo "   .planning/${task_slug}/"
+    done
+fi
+
+# Step 7: Confirmation
+echo ""
+echo -e "${GREEN}=====================================${NC}"
+echo -e "${GREEN}Task Plan Ready${NC}"
+echo -e "${GREEN}=====================================${NC}"
+echo ""
+
+echo -e "${BLUE}Task:${NC} ${TASK_NAME}"
+echo -e "${BLUE}Location:${NC} .planning/${TASK_SLUG}/"
+echo ""
+
+echo -e "${BLUE}Files:${NC}"
+echo "  task_plan.md   (your task plan)"
+echo "  notes.md       (research & findings)"
+echo ""
+
+echo -e "${BLUE}Next steps:${NC}"
+echo "  1. Edit .planning/${TASK_SLUG}/task_plan.md to define your phases"
+echo "  2. As you work, update the Status section"
+echo "  3. Save findings to .planning/${TASK_SLUG}/notes.md"
+echo "  4. Re-read task_plan.md before major decisions"
+echo ""
+
+echo -e "${BLUE}Cleanup:${NC}"
+echo "  rm -rf .planning/${TASK_SLUG}/  # Remove this task"
+echo "  rm -rf .planning/               # Remove all tasks"
+echo ""

package/scripts/init-task.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+###############################################################################
+# init-task.sh - Create a new task under a phase in lg-mode persistent-planning
+#
+# Usage:
+#   bash scripts/init-task.sh "Task Name" --parent <phase-slug>
+#
+# Creates:
+#   .planning/<phase-slug>/<task-slug>/task.md
+#   .planning/<phase-slug>/<task-slug>/notes.md
+#   .planning/<phase-slug>/<task-slug>/atoms/   (empty dir for future atoms)
+#
+# Refuses if mode is not lg, or if --parent doesn't reference an existing phase.
+###############################################################################
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/lib/planning.sh"
+
+# Parse arguments
+TASK_NAME=""
+PARENT_PHASE=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --parent)
+      PARENT_PHASE="$2"
+      shift 2
+      ;;
+    -h|--help)
+      cat <<EOF
+Usage: bash scripts/init-task.sh "Task Name" --parent <phase-slug>
+
+Examples:
+  bash scripts/init-task.sh "HEWTD schema extension" --parent foundation
+  bash scripts/init-task.sh "Multi-corpus refactor" --parent semantic-memory-core
+EOF
+      exit 0
+      ;;
+    *)
+      if [[ -z "$TASK_NAME" ]]; then
+        TASK_NAME="$1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [[ -z "$TASK_NAME" || -z "$PARENT_PHASE" ]]; then
+  planning_err "Both task name and --parent <phase-slug> are required."
+  echo "Usage: bash scripts/init-task.sh \"Task Name\" --parent <phase-slug>"
+  exit 1
+fi
+
+TASK_SLUG=$(planning_slugify "$TASK_NAME")
+
+if [[ -z "$TASK_SLUG" ]]; then
+  planning_err "Task name must contain at least one alphanumeric character."
+  exit 1
+fi
+
+# Refuse non-lg
+MODE=$(planning_mode)
+if [[ "$MODE" != "lg" ]]; then
+  planning_err "Current mode is '$MODE' but init-task.sh requires lg mode."
+  exit 1
+fi
+
+ROOT=$(planning_root)
+PLANNING="$(planning_dir)"
+TODAY=$(planning_today)
+PHASE_DIR="${PLANNING}/${PARENT_PHASE}"
+TASK_DIR="${PHASE_DIR}/${TASK_SLUG}"
+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
+
+# Validate parent phase exists
+if [[ ! -f "${PHASE_DIR}/phase.md" ]]; then
+  planning_err "Parent phase not found: .planning/${PARENT_PHASE}/phase.md"
+  echo "Create the phase first with:"
+  echo "  /start-planning \"<phase name>\"     (which runs init-phase.sh in lg mode)"
+  exit 1
+fi
+
+planning_log "Initializing task: ${TASK_NAME} (parent: ${PARENT_PHASE})"
+
+mkdir -p "${TASK_DIR}/atoms"
+
+planning_render_and_log \
+  "${TEMPLATE_DIR}/task.md" \
+  "${TASK_DIR}/task.md" \
+  "task.md at ${TASK_DIR}/task.md" \
+  "TASK_TITLE_PLACEHOLDER=${TASK_NAME}" \
+  "TASK_SLUG_PLACEHOLDER=${TASK_SLUG}" \
+  "PHASE_SLUG_PLACEHOLDER=${PARENT_PHASE}" \
+  "TASK_DATE_PLACEHOLDER=${TODAY}"
+
+planning_render_and_log \
+  "${TEMPLATE_DIR}/notes.md" \
+  "${TASK_DIR}/notes.md" \
+  "notes.md at ${TASK_DIR}/notes.md" \
+  "NOTES_TITLE_PLACEHOLDER=${TASK_NAME} — Notes" \
+  "NOTES_SCOPE_PLACEHOLDER=${PARENT_PHASE}/${TASK_SLUG}" \
+  "NOTES_DATE_PLACEHOLDER=${TODAY}"
+
+echo ""
+planning_ok "Task '${TASK_NAME}' ready at .planning/${PARENT_PHASE}/${TASK_SLUG}/"
+echo ""
+echo "Next steps:"
+echo "  1. Edit .planning/${PARENT_PHASE}/${TASK_SLUG}/task.md to describe the goal"
+echo "  2. Add atoms with: /start-atom \"<atom name>\" --parent ${TASK_SLUG}"
+echo "     (or add inline atom checkboxes in task.md for simple atoms)"

package/scripts/lib/planning.sh

@@ -0,0 +1,161 @@
+#!/bin/bash
+###############################################################################
+# scripts/lib/planning.sh - Shared helpers for persistent-planning init scripts
+#
+# Source this file from init-phase.sh, init-task.sh, init-atom.sh, and any
+# other planning-related script that needs slug, root, mode, or template
+# rendering helpers.
+#
+# Usage:
+#   #!/bin/bash
+#   set -e
+#   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+#   source "${SCRIPT_DIR}/lib/planning.sh"
+#
+# Provides:
+#   - planning_slugify "Some Name"   →  "some-name" (echoed)
+#   - planning_root                  →  prints project root (CLAUDE_PROJECT_DIR or pwd)
+#   - planning_dir                   →  prints "<root>/.planning"
+#   - planning_meta_dir              →  prints "<root>/.planning/.meta"
+#   - planning_workspace_json        →  prints "<meta>/workspace.json"
+#   - planning_mode                  →  prints active mode (sm | lg) via detect-mode.sh
+#   - planning_today                 →  prints today's date as YYYY-MM-DD
+#   - planning_render_template "<src>" "<dest>" "PLACEHOLDER1=value1" "PLACEHOLDER2=value2" ...
+#       Renders a template file by sed-substituting PLACEHOLDER tokens.
+#       Refuses to overwrite existing dest unless PLANNING_FORCE=1 in env.
+#   - planning_color_<name>          →  ANSI color codes (green, blue, yellow, cyan, red, reset)
+#                                       (only set when stdout is a tty; empty otherwise)
+#   - Color-coded log helpers: planning_log, planning_ok, planning_warn, planning_err
+###############################################################################
+
+# Color codes (only when stdout is a tty)
+if [[ -t 1 ]]; then
+  planning_color_green='\033[0;32m'
+  planning_color_blue='\033[0;34m'
+  planning_color_yellow='\033[1;33m'
+  planning_color_cyan='\033[0;36m'
+  planning_color_red='\033[0;31m'
+  planning_color_reset='\033[0m'
+else
+  planning_color_green=''
+  planning_color_blue=''
+  planning_color_yellow=''
+  planning_color_cyan=''
+  planning_color_red=''
+  planning_color_reset=''
+fi
+
+planning_log()  { printf "${planning_color_blue}[planning]${planning_color_reset} %s\n" "$*"; }
+planning_ok()   { printf "${planning_color_green}[planning]${planning_color_reset} %s\n" "$*"; }
+planning_warn() { printf "${planning_color_yellow}[planning]${planning_color_reset} %s\n" "$*"; }
+planning_err()  { printf "${planning_color_red}[planning]${planning_color_reset} %s\n" "$*" >&2; }
+
+planning_slugify() {
+  local name="$1"
+  name=$(echo "$name" | tr '[:upper:]' '[:lower:]')
+  name=$(echo "$name" | sed 's/[[:space:]_]\+/-/g')
+  name=$(echo "$name" | sed 's/[^a-z0-9-]//g')
+  name=$(echo "$name" | sed 's/^-\+\|-\+$//g')
+  name=$(echo "$name" | sed 's/-\+/-/g')
+  echo "$name"
+}
+
+planning_root() {
+  echo "${CLAUDE_PROJECT_DIR:-$(pwd)}"
+}
+
+planning_dir() {
+  echo "$(planning_root)/.planning"
+}
+
+planning_meta_dir() {
+  echo "$(planning_dir)/.meta"
+}
+
+planning_workspace_json() {
+  echo "$(planning_meta_dir)/workspace.json"
+}
+
+planning_today() {
+  date '+%Y-%m-%d'
+}
+
+planning_mode() {
+  # Resolve via detect-mode.sh (in the same scripts/ dir as the caller's library).
+  local lib_dir
+  lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  local detect="${lib_dir}/../detect-mode.sh"
+  if [[ -x "$detect" ]]; then
+    bash "$detect"
+  else
+    echo "sm"
+  fi
+}
+
+# planning_render_template <template_src> <dest_path> <PLACEHOLDER1=value1> ...
+# Renders a template file by sed-substituting placeholders.
+#
+# Return codes:
+#   0  → rendered fresh
+#   2  → skipped (dest already exists; pass PLANNING_FORCE=1 to overwrite)
+#   1  → error (template not found, etc.)
+#
+# Callers can branch on the return code to log accurately.
+planning_render_template() {
+  local src="$1"
+  local dest="$2"
+  shift 2
+
+  if [[ ! -f "$src" ]]; then
+    planning_err "Template not found: $src"
+    return 1
+  fi
+
+  if [[ -f "$dest" && "${PLANNING_FORCE:-0}" != "1" ]]; then
+    planning_warn "Destination already exists, skipping: $dest"
+    planning_warn "  (re-run with PLANNING_FORCE=1 to overwrite)"
+    return 2
+  fi
+
+  # Copy template to dest
+  cp "$src" "$dest"
+
+  # Apply substitutions
+  for kv in "$@"; do
+    local key="${kv%%=*}"
+    local value="${kv#*=}"
+    # Use a safe delimiter (~) since values may contain /
+    # Escape & and ~ in value
+    local escaped_value
+    escaped_value=$(printf '%s\n' "$value" | sed -e 's/[\&~]/\\&/g')
+    sed -i "s~${key}~${escaped_value}~g" "$dest"
+  done
+  return 0
+}
+
+# planning_render_and_log <template_src> <dest_path> <relative_label> <PLACEHOLDER=val> ...
+# Wraps planning_render_template with accurate logging:
+#   - Prints "Created <relative_label>" only when the template was actually rendered
+#   - Prints nothing extra when skipped (the warn from render_template already covered it)
+#   - Lets the script continue (set -e tolerant) regardless of skip vs render
+planning_render_and_log() {
+  local src="$1"
+  local dest="$2"
+  local label="$3"
+  shift 3
+
+  local rc=0
+  planning_render_template "$src" "$dest" "$@" || rc=$?
+  case $rc in
+    0)
+      planning_ok "Created ${label}"
+      ;;
+    2)
+      # Already covered by the warn inside planning_render_template
+      ;;
+    *)
+      planning_err "Failed to render ${label} (rc=$rc)"
+      return $rc
+      ;;
+  esac
+}

package/templates/lg/atom.md

@@ -0,0 +1,45 @@
+---
+title: ATOM_TITLE_PLACEHOLDER
+tier: plan
+domains:
+  - planning
+status: ready
+last_updated: "ATOM_DATE_PLACEHOLDER"
+plan_kind: atom
+parent: TASK_SLUG_PLACEHOLDER
+sequence: ATOM_SEQUENCE_PLACEHOLDER
+---
+
+# Atom: ATOM_TITLE_PLACEHOLDER
+
+**Task**: `TASK_SLUG_PLACEHOLDER`
+**Sequence**: `ATOM_SEQUENCE_PLACEHOLDER` (atoms within a task are processed sequentially)
+
+## What to do
+[Describe the atomic action a subagent should take. Single focused step. If the work
+spans more than one logical operation, split into multiple atoms with sequential ordering.
+
+This file IS the contract a subagent reads to know exactly what to do. Be specific.]
+
+## Inputs
+[Files, data, or prior atom outputs this atom depends on.]
+
+## Expected outputs
+[Files modified, files created, commands run, or state changed.]
+
+## Acceptance criteria
+[How a subagent (or human reviewer) confirms this atom is done. Should be concrete
+and verifiable.]
+
+## Status
+**Currently ready** — waiting for a subagent to claim it.
+
+Status enum: `ready | in_progress | done | blocked`
+
+Status transitions:
+- `ready → in_progress`: a subagent claims this atom
+- `in_progress → done`: the subagent completes the work and verifies acceptance criteria
+- `in_progress → blocked`: the subagent hits an obstacle (add a note explaining why
+  in a `## Blocker` section)
+- `done → in_progress` (reopen): allowed when a follow-up correction is needed; adds
+  `reopened_at: <iso-timestamp>` field to frontmatter for audit

package/templates/lg/notes.md

@@ -0,0 +1,40 @@
+---
+title: NOTES_TITLE_PLACEHOLDER
+tier: plan
+domains:
+  - planning
+status: active
+last_updated: "NOTES_DATE_PLACEHOLDER"
+plan_kind: notes
+scope: NOTES_SCOPE_PLACEHOLDER
+---
+
+# Notes: NOTES_TITLE_PLACEHOLDER
+
+**Scope**: `NOTES_SCOPE_PLACEHOLDER` (which phase / task this notes file is attached to)
+
+## Key Findings
+[Findings that emerged during plan implementation. Things that didn't fit cleanly into
+a task or atom but matter for context.]
+
+## Research Sources
+[External references, internal docs, conversations that informed decisions.]
+
+## Synthesized Findings
+[Patterns, themes, distilled understanding from the research.]
+
+## Decisions Made
+[Notes-level decisions that affect the parent task or phase. Promote to the parent's
+Decisions Made section if they have wider impact.]
+
+## Errors & Solutions
+[Errors encountered + how they were resolved. Useful for future similar work.]
+
+---
+
+## Append-Only Log
+[Chronological record of progress. Each entry is dated. Useful for handoff and
+reconstructing context after time away.]
+
+### NOTES_DATE_PLACEHOLDER — Initialized
+- Notes file created

package/templates/lg/phase.md

@@ -0,0 +1,42 @@
+---
+title: PHASE_TITLE_PLACEHOLDER
+tier: plan
+domains:
+  - planning
+status: draft
+last_updated: "PHASE_DATE_PLACEHOLDER"
+plan_kind: phase
+parent: null
+---
+
+# Phase: PHASE_TITLE_PLACEHOLDER
+
+## Goal
+[One sentence describing what this phase achieves and the strategic boundary it represents.]
+
+## Tasks
+[Tasks created with `/start-task --parent PHASE_SLUG_PLACEHOLDER` will be tracked here.
+Each task is a bounded deliverable. Tasks default to dependencies-first scheduling.
+Tasks with no inter-dependencies can be marked `parallelizable: true` in their frontmatter
+so subagent teams can pick them up concurrently.]
+
+- [ ] (no tasks yet — run `/start-task "Task name" --parent PHASE_SLUG_PLACEHOLDER`)
+
+## Decisions Made
+[Phase-level decisions that affect multiple tasks. Format: `**Decision**: rationale`.]
+
+## Status
+**Currently draft** — phase has been initialized but no tasks defined.
+
+Status enum: `draft | active | paused | done | archived`
+
+When all tasks are `done`, mark this phase `done`. When archived, this directory and
+its tasks/atoms move to `.planning/archive/PHASE_SLUG_PLACEHOLDER/`.
+
+---
+
+## Layer reference (lg mode)
+- **Phase** (this file): strategic grouping of related tasks
+- **Task** (`.planning/PHASE_SLUG_PLACEHOLDER/<task-slug>/task.md`): bounded deliverable
+- **Atom** (`.planning/PHASE_SLUG_PLACEHOLDER/<task-slug>/atoms/<atom-slug>.md`): subagent hand-off unit
+- **Notes** (`.planning/PHASE_SLUG_PLACEHOLDER/notes.md` or per-task `notes.md`): cross-cutting references

package/templates/lg/task.md

@@ -0,0 +1,54 @@
+---
+title: TASK_TITLE_PLACEHOLDER
+tier: plan
+domains:
+  - planning
+status: draft
+last_updated: "TASK_DATE_PLACEHOLDER"
+plan_kind: task
+parent: PHASE_SLUG_PLACEHOLDER
+depends_on: []
+parallelizable: false
+---
+
+# Task: TASK_TITLE_PLACEHOLDER
+
+**Phase**: `PHASE_SLUG_PLACEHOLDER`
+
+## Goal
+[One sentence describing the deliverable end-state for this task.]
+
+## Atoms
+[Atomic checkbox items that will be picked up by subagents. Each atom should be
+something a single subagent can complete in one focused pass.
+
+For complex atoms that need explicit subagent context, spawn a standalone atom file
+via `/start-atom "Atom name" --parent TASK_SLUG_PLACEHOLDER` — these become files
+under `atoms/` that subagents read via the planning MCP.
+
+Inline checkbox vs. standalone atom file — see anti-pattern doc:
+docs/atom-granularity.md.]
+
+- [ ] (no atoms yet — add inline checkboxes here for simple atoms,
+      or run `/start-atom "Atom name" --parent TASK_SLUG_PLACEHOLDER` for complex ones)
+
+## Decisions Made
+[Task-level decisions. Format: `**Decision**: rationale`.]
+
+## Status
+**Currently draft** — task has been initialized but no atoms defined.
+
+Status enum: `draft | active | paused | done | archived`
+
+## Dependencies
+This task does not currently depend on other tasks. Edit `depends_on:` in frontmatter
+to declare dependencies on other tasks within the same phase. Tasks with no
+inter-dependencies should set `parallelizable: true`.
+
+---
+
+## Layer reference
+- **Phase** (`../phase.md`): the strategic grouping this task belongs to
+- **This task**: the bounded deliverable
+- **Atoms** (`atoms/<atom-slug>.md`): subagent hand-off units (sequential within this task)
+- **Notes** (`notes.md`): cross-cutting references for this task's implementation