**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 ```bash ${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 `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 | --- **Version**: 1.0.0 (2025-01-10) **References**: - [planning-with-files](https:\/\/github.com\/OthmanAdi\/planning-with-files) - Original pattern </article></body></html>

--- name: map-planning version: "1.0.0" description: Implements file-based planning for MAP Framework workflows with branch-scoped task tracking in .map\/ directory. Prevents goal drift via automatic plan synchronization before tool use and validates completion state on exit. allowed-tools: Read, Write, Edit, Bash, Glob, Grep 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\/` directory with branch-based naming: ``` .map\/ ├── task_plan_.md # Primary plan with phases and status ├── findings_.md # Research findings, decisions, key files └── progress_.md # Action log, errors, test results ``` **Example**: On branch `feature-auth`: - `.map\/task_plan_feature-auth.md` - `.map\/findings_feature-auth.md` - `.map\/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 ```markdown # Task Plan: ## Goal ## Current Phase ST-001 ## Phases ### ST-001: **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 ```bash ${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 `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 | --- **Version**: 1.0.0 (2025-01-10) **References**: - [planning-with-files](https:\/\/github.com\/OthmanAdi\/planning-with-files) - Original pattern </article></body></html>