@theglitchking/persistent-planning 1.0.1 → 3.0.0

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

@@ -0,0 +1,115 @@
+---
+name: start-planning
+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. Mode (sm vs lg) determines what gets created.
+
+---
+
+## Usage
+
+```
+/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"        # 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 "<name>" [--mode sm|lg]`:
+
+1. **Resolve mode**:
+```bash
+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
+```
+
+2. **Dispatch by mode**:
+
+If `MODE=sm`:
+```bash
+bash "${SCRIPT_DIR}/init-planning.sh" "<name>"
+```
+
+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/
+└── <slug>/
+    ├── task_plan.md    # Track phases inline + progress
+    └── notes.md        # Store research and findings
+```
+
+### 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
+
+- `/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/commands/status.md

@@ -0,0 +1,6 @@
+---
+description: Show installed version, latest available version, current update policy, and hook registration state
+allowed-tools: Bash(npx:*)
+---
+
+Run `npx --no @theglitchking/persistent-planning status` and relay the output to the user verbatim.

package/commands/update.md

@@ -0,0 +1,6 @@
+---
+description: Update persistent-planning to the latest version (runs npm update + re-links skills)
+allowed-tools: Bash(npx:*)
+---
+
+Run `npx --no @theglitchking/persistent-planning update` and report the before/after versions to the user. If the project doesn't have a local install, fall back to `npx -y @theglitchking/persistent-planning update` and note that in your summary.

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