@theglitchking/persistent-planning 3.0.0 → 3.1.0

package/scripts/plan-status.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+###############################################################################
+# plan-status.sh - Report completion status for every plan under .planning/
+#
+# Usage:
+#   bash scripts/plan-status.sh              # table of every active plan
+#   bash scripts/plan-status.sh --nudge      # one line if plans are archivable, else silence
+#   bash scripts/plan-status.sh --complete   # print the slug of each complete plan, one per line
+#
+# A plan is COMPLETE when every checkbox in it is checked, or when its
+# top-level artifact declares `status: done` in frontmatter. Completion is
+# derived from the artifacts themselves so no separate state file can drift
+# away from what the plan actually says.
+#
+# This is the single implementation of the scan: the SessionStart hook and the
+# /plan-status slash command both shell out to it.
+###############################################################################
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/lib/planning.sh"
+
+MODE="table"
+case "${1:-}" in
+  --nudge)    MODE="nudge" ;;
+  --complete) MODE="complete" ;;
+  -h|--help)
+    sed -n '2,18p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    exit 0
+    ;;
+  "") ;;
+  *)
+    planning_err "Unknown option: $1 (try --help)"
+    exit 1
+    ;;
+esac
+
+PLANNING="$(planning_dir)"
+[[ -d "$PLANNING" ]] || { [[ "$MODE" == "table" ]] && planning_warn "No .planning/ directory here."; exit 0; }
+
+# plan_root_artifact <plan-dir> -> path of the plan's top-level file, or empty
+plan_root_artifact() {
+  for f in "$1/phase.md" "$1/task_plan.md" "$1/task.md"; do
+    [[ -f "$f" ]] && { echo "$f"; return; }
+  done
+}
+
+# frontmatter_status <file> -> value of `status:` inside the leading --- block
+frontmatter_status() {
+  [[ -f "$1" ]] || return
+  awk 'NR==1 && $0 != "---" { exit }
+       NR>1 && $0 == "---" { exit }
+       /^status:[[:space:]]*/ { sub(/^status:[[:space:]]*/, ""); gsub(/["\047]/, ""); print; exit }' "$1"
+}
+
+# Emits "<total> <checked>" for every markdown file under a plan directory.
+count_boxes() {
+  local total checked
+  total=$(grep -rhoE '^[[:space:]]*- \[[ xX]\] ' --include='*.md' "$1" 2>/dev/null | wc -l | tr -d ' ')
+  checked=$(grep -rhoE '^[[:space:]]*- \[[xX]\] ' --include='*.md' "$1" 2>/dev/null | wc -l | tr -d ' ')
+  echo "$total $checked"
+}
+
+COMPLETE=()
+ROWS=()
+
+for plan_path in "$PLANNING"/*/; do
+  [[ -d "$plan_path" ]] || continue
+  slug=$(basename "$plan_path")
+  case "$slug" in .meta|.archive|archive) continue ;; esac
+
+  root=$(plan_root_artifact "${plan_path%/}")
+  [[ -n "$root" ]] || continue
+
+  read -r total checked <<<"$(count_boxes "${plan_path%/}")"
+  status=$(frontmatter_status "$root")
+  blocked=$(grep -rl '^status: blocked' --include='*.md' "${plan_path%/}" 2>/dev/null | wc -l | tr -d ' ')
+
+  if [[ "$status" == "archived" ]]; then
+    verdict="archived"
+  elif [[ "$status" == "done" ]] || { [[ "$total" -gt 0 ]] && [[ "$checked" -eq "$total" ]]; }; then
+    verdict="COMPLETE"
+    COMPLETE+=("$slug")
+  elif [[ "$blocked" -gt 0 ]]; then
+    verdict="blocked"
+  elif [[ "$total" -eq 0 ]]; then
+    verdict="empty"
+  else
+    verdict="in progress"
+  fi
+
+  ROWS+=("$(printf '%-38s %-12s %s/%s boxes' "$slug" "$verdict" "$checked" "$total")")
+done
+
+case "$MODE" in
+  complete)
+    printf '%s\n' "${COMPLETE[@]+"${COMPLETE[@]}"}"
+    ;;
+  nudge)
+    if [[ ${#COMPLETE[@]} -gt 0 ]]; then
+      printf 'persistent-planning: %d plan(s) complete but not archived — %s. Archive with: /archive-plan <slug>\n' \
+        "${#COMPLETE[@]}" "$(IFS=', '; echo "${COMPLETE[*]}")"
+    fi
+    ;;
+  table)
+    if [[ ${#ROWS[@]} -eq 0 ]]; then
+      planning_warn "No plans found under .planning/."
+      exit 0
+    fi
+    planning_log "Plans under .planning/"
+    echo ""
+    printf '  %-38s %-12s %s\n' "PLAN" "STATUS" "PROGRESS"
+    printf '  %s\n' "$(printf '%.0s-' {1..70})"
+    printf '  %s\n' "${ROWS[@]}"
+    echo ""
+    if [[ ${#COMPLETE[@]} -gt 0 ]]; then
+      planning_ok "${#COMPLETE[@]} plan(s) ready to archive:"
+      for s in "${COMPLETE[@]}"; do echo "    bash scripts/archive-plan.sh $s"; done
+    fi
+    ;;
+esac

package/skills/persistent-planning/SKILL.md

@@ -160,6 +160,16 @@ Create this file FIRST for any complex task:
 - [ ] Phase 2: Research/gather information
 - [ ] Phase 3: Execute/build
 - [ ] Phase 4: Review and deliver
+- [ ] Phase 5: Validate success through comprehensive testing (MANDATORY)
+- [ ] Phase 6: Documentation pass -- create/update/deprecate docs (MANDATORY)
+
+> Phases 5 and 6 are mandatory and MUST stay the last two phases of this plan.
+> Insert new work above them; never after. Renumber them if you add phases.
+>
+> - **Validate success**: prove the work with tests that fail if the change breaks.
+> - **Documentation pass**: create/update/deprecate every doc this change touches --
+>   what it is, where it lives, how to fix it, how to operate it, why it matters.
+>   If hit-em-with-the-docs is installed, use it for this pass.
 
 ## Key Questions
 1. [Question to answer]
@@ -217,17 +227,29 @@ Large outputs go to files, not context. Keep only paths in working memory.
 ### 5. Log All Errors
 Every error goes in the "Errors Encountered" section. This builds knowledge for future tasks.
 
-### 6. Easy Cleanup
-When a task is complete, delete the task directory:
-```bash
-rm -rf .planning/[task-name]/
-```
+### 6. Archive on Completion, Don't Delete
+A plan is **complete** when every checkbox in it is checked (or its top-level
+artifact declares `status: done`). Completion is derived from the artifacts, so
+checking the last box IS the completion signal -- there is no separate state to
+update and no way for it to drift.
 
-Or clean up everything:
+When a plan is complete, archive it rather than deleting it:
 ```bash
-rm -rf .planning/
+/plan-status                  # which plans are COMPLETE?
+/archive-plan [task-name]     # -> .planning/.archive/[task-name]/
 ```
 
+Archiving moves the plan to the gitignored `.planning/.archive/` and stamps it
+`status: archived` + `archived_on`. The active `.planning/` tree then shows only
+live work. Nothing is destroyed -- restore with
+`mv .planning/.archive/[task-name] .planning/[task-name]`.
+
+The SessionStart hook checks for complete-but-unarchived plans and says so at the
+top of the session, so a finished plan gets retired instead of rediscovered.
+
+Deleting is still available (`rm -rf .planning/[task-name]/`) but throws away the
+record of what was done and why. Prefer the archive.
+
 ## When to Use This Pattern
 
 **Use 3-file pattern for:**
@@ -254,14 +276,17 @@ rm -rf .planning/
 | Overwrite previous plans | Use `/start-planning` (auto-creates unique task dir) |
 | Start executing immediately | Run `/start-planning "task name"` FIRST |
 | Switch tasks without saving | Update task_plan.md before switching |
+| `rm -rf` a finished plan | `/archive-plan <slug>` -- keeps the record, clears the tree |
+| Leave finished plans in `.planning/` | Archive them; the active tree should show only live work |
+| Track completion in your head or in chat | Check the boxes -- the artifact is the status |
 
 ## Advanced Patterns
 
-See [reference.md](../docs/reference.md) for:
+See [Manus Context Engineering Principles](../../.documentation/architecture/context-engineering-principles.md) for:
 - Attention manipulation techniques
 - Error recovery patterns
 - Context optimization principles
 
-See [examples.md](../docs/examples.md) for:
+See [Worked Examples](../../.documentation/quickstart/examples.md) for:
 - Real task examples
 - Complex workflow patterns

package/templates/lg/atom.md

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

package/templates/lg/notes.md

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

package/templates/lg/phase.md

@@ -0,0 +1,58 @@
+---
+title: PHASE_TITLE_PLACEHOLDER
+tier: plan
+domains:
+  - planning
+status: draft
+last_updated: "PHASE_DATE_PLACEHOLDER"
+plan_kind: phase
+parent: null
+---
+
+# Phase: PHASE_TITLE_PLACEHOLDER
+
+## Goal
+[One sentence describing what this phase achieves and the strategic boundary it represents.]
+
+## Tasks
+[Tasks created with `/start-task --parent PHASE_SLUG_PLACEHOLDER` will be tracked here.
+Each task is a bounded deliverable. Tasks default to dependencies-first scheduling.
+Tasks with no inter-dependencies can be marked `parallelizable: true` in their frontmatter
+so subagent teams can pick them up concurrently.]
+
+- [ ] (no tasks yet — run `/start-task "Task name" --parent PHASE_SLUG_PLACEHOLDER`)
+- [ ] **Validate success through comprehensive testing** (MANDATORY — second-to-last)
+- [ ] **Documentation pass — create/update/deprecate docs** (MANDATORY — last)
+
+> The two mandatory closing tasks above MUST remain the last two tasks of this phase.
+> Add new tasks above them; never after. A phase cannot be marked `done` until both are
+> `done`, and neither may be `parallelizable` — they gate on everything before them.
+>
+> - **Validate success**: prove the phase's work with tests that fail if it breaks.
+> - **Documentation pass**: create/update/deprecate every doc this phase touches —
+>   what it is, where it lives, how to fix it, how to operate it, why it matters.
+>   If hit-em-with-the-docs is installed, use it for this pass.
+
+## Decisions Made
+[Phase-level decisions that affect multiple tasks. Format: `**Decision**: rationale`.]
+
+## Status
+**Currently draft** — phase has been initialized but no tasks defined.
+
+Status enum: `draft | active | paused | done | archived`
+
+When all tasks are `done`, mark this phase `done`. Checking every box in this phase
+IS the completion signal — `/plan-status` reads it straight off the artifacts.
+
+When complete, retire it with `/archive-plan PHASE_SLUG_PLACEHOLDER`: the whole
+directory (tasks and atoms with it) moves to the gitignored
+`.planning/.archive/PHASE_SLUG_PLACEHOLDER/` and the frontmatter above is stamped
+`status: archived` + `archived_on`. Nothing is destroyed.
+
+---
+
+## Layer reference (lg mode)
+- **Phase** (this file): strategic grouping of related tasks
+- **Task** (`.planning/PHASE_SLUG_PLACEHOLDER/<task-slug>/task.md`): bounded deliverable
+- **Atom** (`.planning/PHASE_SLUG_PLACEHOLDER/<task-slug>/atoms/<atom-slug>.md`): subagent hand-off unit
+- **Notes** (`.planning/PHASE_SLUG_PLACEHOLDER/notes.md` or per-task `notes.md`): cross-cutting references

package/templates/lg/task.md

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