shynlee04/hivemind-plugin/hm-l2-planning-persistence

Overview

Three-file external memory system for persisting task state across sessions and context resets. Use when planning complex multi-step work, recovering after context loss, or handing off between agents. Produces durable task plans, findings logs, and progress trackers in session-isolated directories under .hivemind/state/planning/.

This skill replaces the disabled hm-planning-with-files with session isolation, structured YAML frontmatter, explicit pipeline integration contracts (D-09), and a clean architecture that works across any skills-compatible platform.

The Iron Law

The filesystem IS persistent memory. Before any non-trivial change, read the plan.

Why This Skill Exists

LLM context windows are volatile RAM. When orchestrating a multi-step task — especially one involving subagent delegation, multiple sessions, or recovery from interruptions — external memory is essential. The filesystem IS that memory.

This skill provides a 3-file system that acts as persistent brain:

• task_plan.md — Where you're going (goal + phases + decisions + errors)
• findings.md — What you've learned (research + technical discoveries)
• progress.md — What you've done (session log + errors + handoffs)

Any agent can pick up exactly where work left off by reading these 3 files from the session directory.

What Changed from hm-planning-with-files

Reference Map

Tiered Response — Not Everything Needs Full Ritual

Different situations need different ceremony levels:

About to do something? Ask yourself:
|
+-- Am I starting a new complex task?
|   +-- YES --> INIT: Create all 3 files (see First Action)
|
+-- Did I just complete a phase or make a significant discovery?
|   +-- YES --> CHECKPOINT: Update all 3 files with current state
|
+-- Did a subagent return with results?
|   +-- YES --> ABSORB: Write findings.md, update task_plan.md phase status
|
+-- Did something fail or change direction?
|   +-- YES --> PIVOT: Log error, update findings.md, add new phase if needed
|
+-- Just doing routine work within current phase?
    +-- LIGHT: Update progress.md only. No full checkpoint needed.

First Action — When Skill Loads

1. Determine session ID:

• Check .hivemind/state/session-continuity.json for active session
• If no session: generate UUID v4 as session ID
• Set SESSION_DIR=.hivemind/state/planning/<session-id>/

1. Check for `.hivemind/` directory:

• If exists: use .hivemind/state/planning/<session-id>/ (canonical)
• If absent: use .session/<session-id>/ (fallback)
• Note: if using fallback, log warning in progress.md

1. Check for existing planning files:

``bash ls $SESSION_DIR/task_plan.md $SESSION_DIR/findings.md $SESSION_DIR/progress.md 2>/dev/null ``

1. If all 3 exist — Read all 3. Resume from the current phase.

1. If some exist — Read what's there. Create missing files using templates from templates/.

1. If none exist — Create all 3 using templates. Fill in the Goal from user's request.

1. Create the session directory if it doesn't exist:

``bash mkdir -p $SESSION_DIR ``

Gate: Do not proceed with execution until task_plan.md has a Goal and at least one phase defined.

The Core Discipline: Read Before Write

Before making any non-trivial change, read task_plan.md (at minimum the Goal and Current Phase sections).

Context compaction, subagent returns, and user interruptions all cause drift. The plan file is the anchor.

Re-read the plan when:

• After a subagent returns with results
• After switching to a new phase
• After the user changes requirements
• When uncertain about what to do next
• After context compaction or session interruption

Delegation Protocol — Subagent Handoffs

The planning files ARE the handoff mechanism:

1. Before dispatch: Ensure task_plan.md reflects what the subagent will do.
2. After return: Subagent findings go into findings.md. Completed work logged in progress.md.
3. If subagent fails: Log the error in task_plan.md Errors table. Do NOT re-dispatch with the same approach.

Subagent Envelope Pattern

Tell the subagent exactly which files to read and write:

Read: $SESSION_DIR/task_plan.md (Goal + Phase N), $SESSION_DIR/findings.md (## Requirements section)
Write to: $SESSION_DIR/findings.md (append ## Research Findings)
Do NOT modify: $SESSION_DIR/task_plan.md (coordinator owns this)

Envelope Configuration Table

Session Recovery

After /clear, interruption, or new session:

1. Read all 3 files from the session directory
2. Cross-reference with reality — git diff --stat to see what actually changed
3. Reconcile — Update planning files to match current state
4. Update timestamps — Set last_updated in frontmatter to current time
5. Resume — Continue from the current phase

Recovery Decision Tree

Recovery needed?
|
+-- All 3 files exist AND last_updated < 1 hour ago?
|   +-- YES --> Quick resume: read current phase, continue
|
+-- All 3 files exist AND last_updated > 1 hour ago?
|   +-- Stale state. Cross-reference with git diff. Reconcile differences.
|
+-- Some files missing?
|   +-- Create missing from templates. Log what was missing.
|
+-- No files exist?
    +-- Fresh start. Create all 3 from templates.

Error Discipline

When something fails:

1. Log it — Add to task_plan.md Errors Encountered table with timestamp
2. Try once more — Sometimes transient (network, rate limit, race condition)
3. If it fails again, CHANGE APPROACH — Different tool, library, method, or strategy
4. If a third approach fails, ESCALATE — Present what was tried and what's blocking

Do NOT silently retry the same failing action. The error table is accountability.

Fallback Behavior — When .hivemind/ is Unavailable

This skill is designed for Hivemind projects but works everywhere:

The fallback ensures this skill is useful in any skills-compatible environment, not just Hivemind-initialized projects.

Anti-Patterns

Cross-References

Pipeline Integration

NOT Coupled

Kit Bundle Contents