map-planning

name	map-planning
version	1.0.0
description	File-based planning for MAP Framework with branch-scoped task tracking in .map/ directory. Use when user says "create a plan", "track progress", "show task status", or needs persistent planning across agent sessions. Prevents goal drift via automatic plan synchronization. Do NOT use for workflow selection (use map-workflows-guide) or CLI errors (use map-cli-reference).
allowed-tools	Read, Write, Edit, Bash, Glob, Grep
metadata	{"author":"azalio","version":"3.1.0"}
hooks	{"PreToolUse":[{"matcher":"Write|Edit|Bash","hooks":[{"type":"command","command":"${CLAUDE_PLUGIN_ROOT}/scripts/show-focus.sh"}]}],"Stop":[{"hooks":[{"type":"command","command":"${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"}]}]}

MAP Planning Skill

Implements Manus-style file-based planning adapted for MAP Framework workflows. Uses branch-scoped persistent files to track goals, tasks, progress, and learnings across agent sessions.

Core Concept

Instead of relying solely on conversation context (limited window), this skill externalizes planning artifacts to the filesystem. The agent reads/writes structured files that survive context resets, enable progress resumption, and provide explicit traceability.

Key Principle: Filesystem as Extended Memory

• Plan defines "what to do" (phases, dependencies, criteria)
• Notes capture "what learned" (findings, errors, decisions)
• Progress tracked via checkboxes (visual state)
• Branch-specific scope (isolation between features/bugs)

File Structure

All files reside in .map/<branch>/ directory with branch-based naming:

.map/
└── <branch>/
    ├── task_plan_<branch>.md    # Primary plan with phases and status
    ├── findings_<branch>.md     # Research findings, decisions, key files
    ├── progress_<branch>.md     # Action log, errors, test results
    ├── workflow_state.json      # Subtask completion tracking
    ├── step_state.json          # Orchestrator step state
    └── evidence/                # Artifact-gated validation evidence

Example: On branch feature-auth:

• .map/feature-auth/task_plan_feature-auth.md
• .map/feature-auth/findings_feature-auth.md
• .map/feature-auth/progress_feature-auth.md

Hook Behavior

PreToolUse Hook (Before Write/Edit/Bash)

Runs show-focus.sh → extracts only the in_progress section (~200 tokens) and displays Goal + current phase. Purpose: Re-anchors agent to original goal before taking action, prevents goal drift.

Stop Hook (Before Agent Exit)

Runs check-complete.sh → validates all phases have terminal state before allowing exit.

Terminal States: complete, blocked, won't_do, superseded

Plan File Structure

# Task Plan: <Brief Title>

## Goal
<One sentence describing end state>

## Current Phase
ST-001

## Phases

### ST-001: <Title>
**Status:** in_progress
Risk: low|medium|high
Complexity: 1-10
Files: <paths>

Validation:
- [ ] <criterion 1>
- [ ] <criterion 2>

### ST-002: <Title>
**Status:** pending
...

## Terminal State
**Status:** pending
Reason: [Not yet complete]

Workflow Integration

Initialization

${CLAUDE_PLUGIN_ROOT}/scripts/init-session.sh

Creates .map/ directory and skeleton files for current branch.

Progress Tracking

• PreToolUse hook auto-displays focus before Write/Edit/Bash
• Update Status: in_progress → Status: complete as phases finish
• Check validation criteria checkboxes [x] when done

3-Strike Error Protocol

Log errors to .map/<branch>/progress_<branch>.md after attempt 3+. After 3 failed attempts:

1. Escalate to user (CONTINUE/SKIP/ABORT options)
2. If SKIP: mark phase blocked, move to next subtask
3. If ABORT: mark workflow blocked, exit

Terminal State

Update ## Terminal State with final status before exiting. Stop hook validates this.

MAP Workflow Integration

When /map-efficient runs:

1. init-session.sh creates .map/ skeleton
2. task-decomposer populates phases from blueprint
3. Actor implements → PreToolUse hook shows focus
4. Monitor validates → outputs status_update field
5. Orchestrator updates task_plan using Monitor's status_update
6. Stop hook validates terminal state before exit

/map-fast skips planning — hooks are no-op if plan missing.

Single-Writer Governance

Only Monitor agent updates task_plan status (via status_update output field).

Agent	Read task_plan	Write task_plan
task-decomposer	No	Yes (creates)
Actor	Yes	No
Monitor	Yes	Yes (status only)
Predictor	Yes	No
Orchestrator	Yes	No (applies Monitor output)

Why: Prevents race conditions, ensures consistent state, clear ownership.

Best Practices

• Goal clarity: Specific, measurable outcomes
• Granular phases: Each phase = 1 agent action
• Checkpoint frequently: Update status immediately after completion
• Terminal state early: Mark blocked as soon as blocker identified

Error Handling

Issue	Fix
Plan not found	Run init-session.sh
Stop hook warns "No terminal state"	Update ## Terminal State section
Branch name with /	Scripts sanitize: feature/auth → feature-auth

Terminal States

State	When
complete	All phases finished, criteria met
blocked	Needs external input (human, resource)
won't_do	Task intentionally cancelled
superseded	Replaced by different approach

---

Examples

Example 1: Starting a new feature plan

User says: "Create a plan for implementing user notifications"

Actions:

1. Run init-session.sh to create .map/ skeleton for current branch
2. Populate .map/<branch>/task_plan_<branch>.md with phases: research, design, implement, test
3. Set Goal: "Implement user notification system with email and in-app channels"
4. Mark ST-001 as in_progress

Result: Persistent plan files created in .map/ directory, PreToolUse hook keeps agent focused on current phase.

Example 2: Resuming work after context reset

User says: "Show task status" or "What was I working on?"

Actions:

1. Read .map/<branch>/task_plan_<branch>.md to find current phase
2. Read .map/<branch>/progress_<branch>.md for recent action log
3. Read .map/<branch>/findings_<branch>.md for accumulated decisions

Result: Agent resumes from last checkpoint without losing context, even after conversation window reset.

Example 3: Handling repeated failures

User says: "The database migration keeps failing"

Actions:

1. Log error to .map/<branch>/progress_<branch>.md (attempt count tracked)
2. After 3 failed attempts, trigger 3-Strike Protocol
3. Present CONTINUE/SKIP/ABORT options to user

Result: Phase marked blocked, agent moves to next subtask or exits cleanly.

---

Troubleshooting

Issue	Cause	Solution
"Plan not found" warning	.map/ directory not initialized	Run init-session.sh or start a MAP workflow
Stop hook warns "No terminal state"	## Terminal State section not updated	Update Terminal State to complete, blocked, won't_do, or superseded
Branch name causes file errors	Branch has / characters	Scripts auto-sanitize: feature/auth becomes feature-auth
PreToolUse hook shows stale focus	Plan file not updated after phase completion	Update **Status:** to complete and advance ## Current Phase
/map-fast ignores planning	By design — /map-fast skips planning	Use /map-efficient for planning support

---

Version: 1.0.0 (2025-01-10)

References:

• planning-with-files - Original pattern