@theglitchking/persistent-planning 2.0.0 → 3.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,45 @@
+{
+  "name": "persistent-planning-marketplace",
+  "owner": {
+    "name": "TheGlitchKing",
+    "email": "theglitchking@users.noreply.github.com"
+  },
+  "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"
+  },
+  "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",
+      "author": {
+        "name": "TheGlitchKing"
+      },
+      "homepage": "https://github.com/TheGlitchKing/persistent-planning",
+      "repository": "https://github.com/TheGlitchKing/persistent-planning.git",
+      "license": "MIT",
+      "keywords": [
+        "planning",
+        "persistent",
+        "markdown",
+        "context-engineering",
+        "task-tracking",
+        "working-memory",
+        "goal-tracking",
+        "claude-code"
+      ],
+      "category": "productivity",
+      "tags": [
+        "planning",
+        "context-engineering",
+        "working-memory"
+      ],
+      "source": {
+        "source": "npm",
+        "package": "@theglitchking/persistent-planning"
+      },
+      "strict": true
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "persistent-planning",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "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,63 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.0.0] - 2026-05-07
+
+### Added — Lg-mode (large/team) layered planning
+
+v3.0 introduces a new **layered planning mode** alongside the existing single-task flow. The mode is auto-detected (90-day git-author-count heuristic; ≥2 distinct authors → lg) and is sticky once chosen.
+
+**Four layers** in lg mode:
+
+- **Phase** — strategic grouping of related tasks (top)
+- **Task** — bounded deliverable; declares `depends_on` + `parallelizable` for subagent team scheduling
+- **Atom** — subagent hand-off unit; sequential within a task; status: `ready | in_progress | done | blocked` with reopen support
+- **Notes** — cross-cutting references scoped to a phase or task
+
+All four layers carry HEWTD-aligned frontmatter (`tier: plan`). `version` is intentionally omitted — HEWTD 2.2.0+ makes it conditionally optional for plan-tier docs.
+
+### Added — `/start-task` and `/start-atom` slash commands
+
+- `/start-task "<name>" --parent <phase>` — adds a task under an existing phase (lg only)
+- `/start-atom "<name>" --parent <task>` — adds an atom (subagent hand-off unit) under a task (lg only); auto-resolves the parent phase by walking `.planning/`; auto-assigns sequence number
+- `/start-planning` updated to dispatch sm vs lg based on detect-mode.sh; accepts `--mode sm|lg` for explicit override
+
+### Added — `.planning/.meta/workspace.json`
+
+Per-project mode tracker. Fields: `schema_version`, `mode`, `auto_detected`, `detected_contributors`, `created_at`. Bootstrapped on first lg-mode init. See `docs/workspace-json.md` for the full schema.
+
+### Added — Documentation
+
+- `docs/lg-mode.md` — full lg-mode guide
+- `docs/atom-granularity.md` — anti-pattern guide for inline-checkbox-vs-standalone-atom
+- `docs/workspace-json.md` — workspace.json schema reference
+
+### Added — Scripts
+
+- `scripts/detect-mode.sh` — sm/lg resolution
+- `scripts/lib/planning.sh` — shared bash helpers
+- `scripts/init-phase.sh`, `scripts/init-task.sh`, `scripts/init-atom.sh` — lg-mode init scripts
+
+### Added — Templates
+
+- `templates/lg/{phase,task,atom,notes}.md` — HEWTD-frontmattered layer templates
+
+### Subagent contract (requires semantic-memory 1.0)
+
+Lg-mode plans are designed to be read by subagents via semantic-memory's MCP verbs (registered conditionally on the `plans` corpus). When semantic-memory is absent, persistent-planning falls back to filesystem-based reads — slash commands still work; subagent comprehension degrades.
+
+### Backwards compatibility
+
+- **Sm mode preserved exactly**: existing `.planning/<task-slug>/{task_plan.md, notes.md}` directories continue to work without changes. The original `/start-planning "Task name"` flow is identical to v2.
+- **Auto-detection is non-disruptive**: existing v2 plans aren't migrated. New `/start-planning` invocations auto-detect mode and create new artifacts using the resolved mode.
+
+### Optional dependencies
+
+- `@theglitchking/hit-em-with-the-docs ^2.2.0` — required for `hewtd validate` to accept lg-mode plan frontmatter (introduces `tier: "plan"` + conditional `version`)
+- `@theglitchking/semantic-memory ^1.0.0` (formerly `semantic-sidekick`) — required for the planning MCP verbs that subagents use to read/mutate lg-mode plans
+
+When neither is installed, lg mode still works as a pure file-authoring flow.
+
 ## [2.0.0] - 2026-04-18
 
 ### ⚠️ Breaking changes

package/README.md

@@ -43,43 +43,48 @@ For every complex task, create three files:
 
 ## Installation
 
-### Option 1: NPM (Recommended)
+> **v1 → v2 breaking change**: the hand-rolled `persistent-planning install --scope ...` flow was removed. Skills and slash commands are now placed automatically — either by the Claude Code plugin marketplace, or by npm's postinstall symlinking. See [CHANGELOG.md](./CHANGELOG.md) for the full migration guide.
 
-```bash
-# Install globally
-npm install -g @theglitchking/persistent-planning
-persistent-planning install --scope user
+### Option A: Claude Code Plugin Marketplace (Recommended)
 
-# Or via npx (no global install)
-npx @theglitchking/persistent-planning install --scope user
 ```
+/plugin marketplace add TheGlitchKing/persistent-planning
+/plugin install persistent-planning@persistent-planning-marketplace
+```
+
+### Option B: Project-level npm install
 
-### Option 2: Installer Script
+Pins the exact version in `package.json`, visible to teammates, CI, and LLMs reading the repo. Postinstall symlinks `skills/persistent-planning/` into `<project>/.claude/skills/`, writes a default `.claude/persistent-planning.json` (update policy `nudge`), and registers a SessionStart hook in `.claude/settings.json` if one is present. Dedup: if the plugin marketplace version is already enabled in `~/.claude/settings.json`, the npm hook registration is skipped.
 
 ```bash
-git clone https://github.com/TheGlitchKing/persistent-planning.git
-cd persistent-planning
-./install.sh --scope user       # Available in all projects
-# OR
-./install.sh --scope project    # Current project only
+npm install --save-dev @theglitchking/persistent-planning
 ```
 
-### Option 3: Claude Marketplace
+### Option C: Try it (no install)
 
-```
-/plugin install TheGlitchKing/persistent-planning
+```bash
+npx @theglitchking/persistent-planning status
 ```
 
-### Option 4: Manual Installation
+## Update management
+
+Each install ships with an update policy. By default the plugin checks npm at session start and prints a one-liner when a newer version is available — no changes made. Opt into automatic updates or silence the check entirely:
 
 ```bash
-mkdir -p ~/.claude/skills
-cp -r persistent-planning/skills/SKILL.md ~/.claude/skills/persistent-planning/SKILL.md
-cp -r persistent-planning/scripts ~/.claude/skills/persistent-planning/scripts
-cp -r persistent-planning/docs ~/.claude/skills/persistent-planning/docs
-cp persistent-planning/.claude/commands/start-planning.md ~/.claude/commands/start-planning.md
+# Slash commands
+/persistent-planning:policy auto    # auto-update on session start
+/persistent-planning:policy nudge   # one-liner nudge only (default)
+/persistent-planning:policy off     # silent
+
+# CLI equivalents
+npx --no @theglitchking/persistent-planning policy auto
+npx --no @theglitchking/persistent-planning status     # installed, latest, policy, hook state
+npx --no @theglitchking/persistent-planning update     # runs npm update + relinks skills
+npx --no @theglitchking/persistent-planning relink     # re-symlink skills only
 ```
 
+Policy resolution order: `PERSISTENT_PLANNING_UPDATE_POLICY` env var → `<project>/.claude/persistent-planning.json` → default `nudge`.
+
 ## Usage
 
 ### Quick Start
@@ -151,23 +156,29 @@ Each task gets its own directory. No conflicts, no overwrites.
 ```
 persistent-planning/
 ├── .claude-plugin/
-│   └── plugin.json          # Plugin manifest
-├── .claude/
-│   └── commands/
-│       └── start-planning.md    # /start-planning command
-├── skills/
-│   └── SKILL.md             # Core skill definition
+│   └── plugin.json          # Plugin manifest (marketplace loader)
+├── bin/
+│   └── persistent-planning.js  # CLI (update/policy/status/relink)
+├── commands/
+│   ├── start-planning.md    # /start-planning slash command
+│   ├── update.md            # /persistent-planning:update
+│   ├── policy.md            # /persistent-planning:policy
+│   ├── status.md            # /persistent-planning:status
+│   └── relink.md            # /persistent-planning:relink
+├── hooks/
+│   ├── hooks.json           # SessionStart hook manifest
+│   └── session-start.js     # Runtime-delegated hook
 ├── scripts/
-│   └── init-planning.sh     # Automated setup script
+│   └── link-skills.js       # Postinstall (runtime-delegated)
+├── skills/
+│   └── persistent-planning/
+│       └── SKILL.md         # Core skill definition
 ├── docs/
 │   ├── reference.md         # Manus context engineering principles
 │   └── examples.md          # Worked examples
-├── install.sh               # Plugin installer
-├── uninstall.sh             # Plugin uninstaller
-├── plugin.json              # Root plugin metadata
-├── README.md                # This file
-├── LICENSE                  # MIT license
-└── CHANGELOG.md             # Version history
+├── README.md
+├── LICENSE
+└── CHANGELOG.md
 ```
 
 ## Cleanup

package/commands/start-atom.md

@@ -0,0 +1,93 @@
+---
+name: start-atom
+description: "Add an atom (subagent hand-off unit) under an existing task in lg-mode persistent-planning. Creates .planning/<phase>/<task>/atoms/<atom-slug>.md with auto-incremented sequence. Requires --parent <task-slug>. Lg mode only."
+---
+
+# /start-atom
+
+Add an atom — the smallest unit of planning, designed for subagent hand-off — under an existing task. **Lg mode only.**
+
+---
+
+## Usage
+
+```
+/start-atom "Atom name" --parent <task-slug>
+```
+
+## Examples
+
+```
+/start-atom "Update zod schema" --parent hewtd-schema-extension
+/start-atom "Add plan-tier tests" --parent hewtd-schema-extension
+/start-atom "Bump to 2.2.0" --parent hewtd-schema-extension
+```
+
+---
+
+## What To Do
+
+When the user runs `/start-atom "<name>" --parent <task-slug>`:
+
+1. Run the init script:
+```bash
+SCRIPT_DIR="$(dirname "$(readlink -f "$0")")/../scripts"
+bash "${SCRIPT_DIR}/init-atom.sh" "<name>" --parent "<task-slug>"
+```
+
+The script auto-resolves which phase contains the task (no need to specify the phase). It auto-assigns the next sequence number based on existing atoms in the same task's `atoms/` directory.
+
+If the script isn't found at that path, try:
+```bash
+bash scripts/init-atom.sh "<name>" --parent "<task-slug>"
+bash ~/.claude/skills/persistent-planning/scripts/init-atom.sh "<name>" --parent "<task-slug>"
+```
+
+2. After completion, remind the user:
+   - Edit `.planning/<phase>/<task>/atoms/<atom-slug>.md` to define:
+     - `## What to do` — the atomic action
+     - `## Inputs` — files / state the atom depends on
+     - `## Expected outputs` — files / commands / state changes
+     - `## Acceptance criteria` — how to verify completion
+   - The atom starts with `status: ready`. A subagent will claim it (status → `in_progress`) and complete it (status → `done`).
+
+---
+
+## What It Creates
+
+```
+.planning/<phase-slug>/<task-slug>/atoms/
+└── <atom-slug>.md   # HEWTD-frontmattered atom (parent: <task-slug>, sequence: N)
+```
+
+The atom file includes the structured sections needed for subagent comprehension. It's the contract a subagent reads to know exactly what to do.
+
+## Atoms vs. inline checkboxes
+
+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.
+
+## Sequence semantics
+
+Atoms within a task default to **sequential** processing. The `sequence:` frontmatter field is auto-assigned (1 + max existing). The planning MCP's `next_atom(task)` verb returns the next `status: ready` atom in sequence order.
+
+Sequential matches the single-agent reality and eliminates filesystem race conditions on claim. If you have a genuine parallel-atom workload, that's a Phase 4.x conversation; today, atoms hand off one at a time.
+
+## Lg-mode-only
+
+This command refuses to run if the project is in sm mode. To switch:
+
+```
+/start-planning "<phase name>" --mode lg
+```
+
+## See also
+
+- `/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

package/commands/start-planning.md

@@ -1,65 +1,115 @@
 ---
 name: start-planning
-description: "Initialize persistent planning structure for a task. Creates .planning/[task-slug]/ with task_plan.md and notes.md for on-disk working memory that persists across sessions."
+description: "Initialize persistent planning structure. In sm mode (solo/small) creates .planning/[task-slug]/ with task_plan.md + notes.md (v2 behavior). In lg mode (team/large), creates a phase: .planning/[phase-slug]/{phase.md, notes.md} and bootstraps .planning/.meta/workspace.json. Mode auto-detects via 90-day git author count (≥2 = lg) or can be forced with --mode."
 ---
 
 # /start-planning
 
-Initialize the persistent planning structure for a task.
+Initialize the persistent planning structure. Mode (sm vs lg) determines what gets created.
 
 ---
 
 ## Usage
 
 ```
-/start-planning "Your task name here"
+/start-planning "Your name here"                    # auto-detect mode
+/start-planning "Your name here" --mode sm          # force small mode (single task)
+/start-planning "Your name here" --mode lg          # force large mode (phase)
 ```
 
+## Mode behavior
+
+- **sm mode** (solo / small): creates `.planning/<slug>/{task_plan.md, notes.md}`. Single-task flow. Identical to v2 behavior.
+- **lg mode** (team / large): creates `.planning/<phase-slug>/{phase.md, notes.md}` — the new top-layer "phase" artifact. Add tasks under it with `/start-task`, atoms with `/start-atom`. Bootstraps `.planning/.meta/workspace.json`.
+
+Mode is auto-detected via 90-day git author count (≥2 distinct authors → lg, else sm), with a printed decision banner. Once detected (or explicitly set with `--mode`), the choice is sticky in `.planning/.meta/workspace.json` for all subsequent runs.
+
 ## Examples
 
 ```
-/start-planning "Refactor authentication system"
-/start-planning "Build REST API with JWT"
-/start-planning "Fix memory leak in worker process"
+/start-planning "Refactor authentication system"        # solo: makes a task plan
+/start-planning "Foundation"                            # team: makes a phase
+/start-planning "Multi-corpus refactor" --mode lg       # force lg
+/start-planning "Quick spike" --mode sm                 # force sm
 ```
 
 ---
 
 ## What To Do
 
-When the user runs `/start-planning "Task Name"`:
+When the user runs `/start-planning "<name>" [--mode sm|lg]`:
 
-1. Run the init script:
+1. **Resolve mode**:
 ```bash
-bash "$(dirname "$(readlink -f "$0")")/../scripts/init-planning.sh" "Task Name"
+SCRIPT_DIR="$(dirname "$(readlink -f "$0")")/../scripts"
+# Honor explicit --mode flag if given; otherwise detect.
+if [ -n "$EXPLICIT_MODE" ]; then
+    MODE="$EXPLICIT_MODE"
+else
+    MODE=$(bash "${SCRIPT_DIR}/detect-mode.sh" --explain)
+fi
 ```
 
-If the script is not found at that path, try these fallbacks in order:
+2. **Dispatch by mode**:
+
+If `MODE=sm`:
 ```bash
-bash scripts/init-planning.sh "Task Name"
-bash ~/.claude/skills/persistent-planning/scripts/init-planning.sh "Task Name"
+bash "${SCRIPT_DIR}/init-planning.sh" "<name>"
 ```
 
-2. After the script completes, remind the user:
-   - Edit `.planning/[task-slug]/task_plan.md` to define phases
-   - Update the Status section as they work
-   - Save findings to `.planning/[task-slug]/notes.md`
-   - Re-read `task_plan.md` before major decisions
+If `MODE=lg`:
+```bash
+bash "${SCRIPT_DIR}/init-phase.sh" "<name>"
+```
+
+If `--mode lg` was passed but workspace.json already exists with `mode: sm` (or vice versa), update workspace.json to the new mode (the override sticks).
+
+3. **After the script completes**:
+   - sm mode: remind the user to edit `task_plan.md`, update `Status`, save to `notes.md`
+   - lg mode: remind the user to add tasks via `/start-task "<task name>" --parent <phase-slug>`
+
+If a script isn't found at the resolved path, try these fallbacks in order:
+```bash
+bash scripts/init-phase.sh "<name>"          # for lg
+bash scripts/init-planning.sh "<name>"        # for sm
+bash ~/.claude/skills/persistent-planning/scripts/init-phase.sh "<name>"
+bash ~/.claude/skills/persistent-planning/scripts/init-planning.sh "<name>"
+```
 
 ---
 
 ## What It Creates
 
+### sm mode
 ```
 .planning/
-└── [task-slug]/
-    ├── task_plan.md    # Track phases and progress
+└── <slug>/
+    ├── task_plan.md    # Track phases inline + progress
     └── notes.md        # Store research and findings
 ```
 
-## Task Slug Conversion
+### lg mode
+```
+.planning/
+├── .meta/
+│   └── workspace.json    # {mode: "lg", auto_detected: true, ...}
+└── <phase-slug>/
+    ├── phase.md          # HEWTD-frontmattered top-layer artifact
+    └── notes.md          # Cross-cutting notes for the phase
+```
+
+Add tasks under a phase with `/start-task "<name>" --parent <phase-slug>`.
+
+## Slug conversion
+
+Names are converted to URL-friendly slugs:
+- "Refactor Authentication" → `refactor-authentication`
+- "Multi-Corpus Refactor" → `multi-corpus-refactor`
+- "Fix Bug #123" → `fix-bug-123`
+
+## See also
 
-Task names are converted to URL-friendly slugs:
-- "Refactor Authentication" -> `refactor-authentication`
-- "Build REST API" -> `build-rest-api`
-- "Fix Bug #123" -> `fix-bug-123`
+- `/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)

package/commands/start-task.md

@@ -0,0 +1,83 @@
+---
+name: start-task
+description: "Add a task under an existing phase in lg-mode persistent-planning. Creates .planning/<phase>/<task-slug>/{task.md, notes.md, atoms/}. Requires --parent <phase-slug>. Lg mode only."
+---
+
+# /start-task
+
+Add a task under an existing phase. **Lg mode only** — refuses to run in sm mode.
+
+---
+
+## Usage
+
+```
+/start-task "Task name" --parent <phase-slug>
+```
+
+## Examples
+
+```
+/start-task "HEWTD schema extension" --parent foundation
+/start-task "Multi-corpus refactor" --parent semantic-memory-core
+/start-task "Drift detection algorithm" --parent ecosystem-extensions
+```
+
+---
+
+## What To Do
+
+When the user runs `/start-task "<name>" --parent <phase-slug>`:
+
+1. Run the init script:
+```bash
+SCRIPT_DIR="$(dirname "$(readlink -f "$0")")/../scripts"
+bash "${SCRIPT_DIR}/init-task.sh" "<name>" --parent "<phase-slug>"
+```
+
+If the script isn't found at that path, try:
+```bash
+bash scripts/init-task.sh "<name>" --parent "<phase-slug>"
+bash ~/.claude/skills/persistent-planning/scripts/init-task.sh "<name>" --parent "<phase-slug>"
+```
+
+2. After completion, remind the user:
+   - Edit `.planning/<phase>/<task-slug>/task.md` to define the task goal
+   - Add atoms with `/start-atom "<name>" --parent <task-slug>` (or inline checkboxes for simple atoms)
+   - Update task frontmatter: `depends_on: [<other-task-slug>]` for sequential dependencies, or `parallelizable: true` for tasks with no inter-dependencies
+
+---
+
+## What It Creates
+
+```
+.planning/<phase-slug>/
+└── <task-slug>/
+    ├── task.md            # HEWTD-frontmattered task artifact (parent: <phase-slug>)
+    ├── notes.md           # Cross-cutting notes scoped to this task
+    └── atoms/             # Empty dir for future atoms (subagent hand-off units)
+```
+
+## Frontmatter scheduling fields
+
+The `task.md` template includes two key scheduling fields:
+
+- `depends_on: []` — array of other task slugs (within the same phase) this task depends on. The planning MCP's `next_task()` verb respects this graph.
+- `parallelizable: false` — set to `true` for tasks that can be picked up in any order by subagent teams. Default `false` (conservative).
+
+## Lg-mode-only
+
+This command refuses to run if the project is in sm mode. To switch:
+
+```
+/start-planning "<phase name>" --mode lg
+```
+
+That writes `.planning/.meta/workspace.json` with `mode: "lg"` and creates the first phase.
+
+## See also
+
+- `/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

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.0",
   "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
   "type": "module",
   "bin": {
@@ -54,5 +54,8 @@
   "dependencies": {
     "@theglitchking/claude-plugin-runtime": "^0.1.0",
     "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@theglitchking/semantic-pages": "^0.10.0"
   }
 }