map-state

name	map-state
version	3.1.0
description	Branch-scoped MAP planning in `.map/`. Use when the user needs a persistent task plan, progress tracking, or resume support across sessions. Keeps focus synced before edits. Do NOT use for tiny one-shot tasks.
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
    ├── research/
    │   └── plan__discovery.md   # Plan-scope research, decisions, key files
    ├── progress_<branch>.md     # Action log, errors, test results
    ├── step_state.json          # Canonical orchestrator step + subtask state

Example: On branch feature-auth:

• .map/feature-auth/task_plan_feature-auth.md
• .map/feature-auth/research/plan__discovery.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.

Constraints (NEVER)

These are hard rules — each one protects shared, persistent state. If a task seems to require violating one, STOP and ask the user.

• NEVER write task_plan **Status:** from any agent other than Monitor. task-decomposer creates the plan; Monitor owns every subsequent status transition (see Single-Writer Governance). An agent that needs a status change must surface it, not write it.
• NEVER hand-edit step_state.json. It is the canonical orchestrator state — mutate it only through .map/scripts/ orchestrator calls. If the API cannot express what you need, STOP and ask; do not write the file as a fallback.
• NEVER read, write, or delete another branch's .map/<other-branch>/ tree. Scope is strictly the current branch.
• NEVER set a **Status:** outside the defined vocabulary — phase statuses are pending, in_progress, complete; terminal states are listed under "Terminal States". Unknown values break the Stop-hook terminal-state check.
• NEVER commit secrets, tokens, or credentials into plan / progress / research files.

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

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>/research/plan__discovery.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: 3.1.0

References:

• planning-with-files - Original pattern