@theglitchking/persistent-planning 1.0.1 → 3.0.0

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/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "description": "persistent-planning SessionStart hook — nudges/auto-updates per policy.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.js\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-start.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// persistent-planning SessionStart hook.
+// Delegates entirely to @theglitchking/claude-plugin-runtime — this plugin
+// has no mcp.json wiring or project-side reconcile, so only the update
+// check runs.
+
+import { runSessionStart } from "@theglitchking/claude-plugin-runtime";
+
+await runSessionStart({
+  packageName: "@theglitchking/persistent-planning",
+  pluginName: "persistent-planning",
+  configFile: "persistent-planning.json",
+});

package/package.json

@@ -1,43 +1,42 @@
 {
   "name": "@theglitchking/persistent-planning",
-  "version": "1.0.1",
+  "version": "3.0.0",
   "description": "Persistent markdown-based planning with task directories, progress tracking, and context engineering for multi-step Claude Code workflows",
-  "type": "commonjs",
+  "type": "module",
   "bin": {
     "persistent-planning": "bin/persistent-planning.js"
   },
   "scripts": {
-    "postinstall": "node postinstall.js"
+    "postinstall": "node scripts/link-skills.js"
   },
   "files": [
     "bin/",
+    "commands/",
+    "hooks/",
+    "scripts/link-skills.js",
     "skills/",
-    "scripts/",
     "docs/",
-    ".claude/",
     ".claude-plugin/",
-    "postinstall.js",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
   ],
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=20.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "keywords": [
     "claude-code",
+    "plugin",
     "planning",
     "persistent",
     "markdown",
     "context-engineering",
     "task-tracking",
     "working-memory",
-    "goal-tracking",
-    "manus",
-    "plugin"
+    "goal-tracking"
   ],
   "author": {
     "name": "TheGlitchKing",
@@ -51,5 +50,12 @@
   "bugs": {
     "url": "https://github.com/TheGlitchKing/persistent-planning/issues"
   },
-  "homepage": "https://github.com/TheGlitchKing/persistent-planning#readme"
+  "homepage": "https://github.com/TheGlitchKing/persistent-planning#readme",
+  "dependencies": {
+    "@theglitchking/claude-plugin-runtime": "^0.1.0",
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@theglitchking/semantic-pages": "^0.10.0"
+  }
 }

package/scripts/link-skills.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Postinstall — delegates to @theglitchking/claude-plugin-runtime.
+// See https://github.com/TheGlitchKing/claude-plugin-runtime/blob/main/docs/PLUGIN_AUTHORING_SCAFFOLD.md
+
+import { runPostinstall } from "@theglitchking/claude-plugin-runtime";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+try {
+  runPostinstall({
+    packageName: "@theglitchking/persistent-planning",
+    pluginName: "persistent-planning",
+    configFile: "persistent-planning.json",
+    skillsDir: "skills",
+    packageRoot,
+    hookCommand:
+      "node ./node_modules/@theglitchking/persistent-planning/hooks/session-start.js",
+  });
+} catch (err) {
+  console.warn(`[persistent-planning] postinstall failed: ${err?.message || err}`);
+}

package/.claude/commands/start-planning.md

@@ -1,65 +0,0 @@
----
-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."
----
-
-# /start-planning
-
-Initialize the persistent planning structure for a task.
-
----
-
-## Usage
-
-```
-/start-planning "Your task name here"
-```
-
-## Examples
-
-```
-/start-planning "Refactor authentication system"
-/start-planning "Build REST API with JWT"
-/start-planning "Fix memory leak in worker process"
-```
-
----
-
-## What To Do
-
-When the user runs `/start-planning "Task Name"`:
-
-1. Run the init script:
-```bash
-bash "$(dirname "$(readlink -f "$0")")/../scripts/init-planning.sh" "Task Name"
-```
-
-If the script is not found at that path, try these fallbacks in order:
-```bash
-bash scripts/init-planning.sh "Task Name"
-bash ~/.claude/skills/persistent-planning/scripts/init-planning.sh "Task 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
-
----
-
-## What It Creates
-
-```
-.planning/
-└── [task-slug]/
-    ├── task_plan.md    # Track phases and progress
-    └── notes.md        # Store research and findings
-```
-
-## Task Slug Conversion
-
-Task names are converted to URL-friendly slugs:
-- "Refactor Authentication" -> `refactor-authentication`
-- "Build REST API" -> `build-rest-api`
-- "Fix Bug #123" -> `fix-bug-123`

package/.claude/settings.local.json

@@ -1,13 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(bash:*)",
-      "Bash(echo:*)",
-      "Bash(./install.sh:*)",
-      "Bash(/mnt/e/docker-containers/persistent-planning/uninstall.sh:*)",
-      "Bash(chmod:*)",
-      "Bash(node:*)",
-      "Bash(python3:*)"
-    ]
-  }
-}

package/postinstall.js

@@ -1,34 +0,0 @@
-#!/usr/bin/env node
-
-const colors = {
-  reset: '\x1b[0m',
-  green: '\x1b[32m',
-  blue: '\x1b[34m',
-  yellow: '\x1b[33m',
-  cyan: '\x1b[36m'
-};
-
-console.log(`
-${colors.cyan}persistent-planning installed successfully!${colors.reset}
-
-${colors.green}+${colors.reset} Package installed: ${colors.blue}@theglitchking/persistent-planning${colors.reset}
-
-${colors.yellow}Next Steps:${colors.reset}
-
-  1. Run the installer to set up the plugin:
-     ${colors.cyan}persistent-planning install --scope user${colors.reset}
-
-     ${colors.blue}Scopes:${colors.reset}
-       user    - Install globally (~/.claude/) for all projects
-       project - Install locally (./.claude/) for this project only
-
-  2. Check installation status:
-     ${colors.cyan}persistent-planning status${colors.reset}
-
-  3. After installation, use this Claude Code command:
-     ${colors.cyan}/start-planning "Your task name"${colors.reset}
-
-${colors.yellow}Documentation:${colors.reset}
-  ${colors.blue}https://github.com/TheGlitchKing/persistent-planning${colors.reset}
-
-`);

package/scripts/init-planning.sh

@@ -1,233 +0,0 @@
-#!/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 ""