@theglitchking/persistent-planning 2.0.0 → 3.0.1

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.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.1",
+      "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.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,73 @@
 
 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
+
+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