mapify-cli 2.2.0__tar.gz → 2.3.0__tar.gz

{mapify_cli-2.2.0/src/mapify_cli/templates → mapify_cli-2.3.0/.claude}/skills/README.md

@@ -2,9 +2,9 @@
 
 ## What are Skills?
 
-**Skills** = Passive documentation modules (NOT agents!)
+**Skills** = Opt-in modules (NOT agents!)
 
-Skills provide specialized guidance without executing code. They help users understand MAP Framework concepts and make informed decisions.
+Most skills provide specialized guidance (passive documentation). Some skills may also include optional workflow automation (e.g., hooks + scripts) when explicitly loaded.
 
 ## Skills vs Agents
 
@@ -59,6 +59,21 @@ MAP: [Shows decision tree and comparison matrix]
 
 ---
 
+### map-planning
+
+**Purpose:** Persistent session state for long MAP workflows using file-based planning in `.map/`.
+
+**What it provides:**
+- Branch-scoped files: `task_plan_<branch>.md`, `findings_<branch>.md`, `progress_<branch>.md`
+- Optional hooks (PreToolUse + Stop) to reduce goal drift and prevent premature stop
+
+**How to use:**
+```bash
+.claude/skills/map-planning/scripts/init-session.sh
+```
+
+---
+
 ## Creating New Skills
 
 See [docs/P1_SKILLS_SYSTEM_IMPLEMENTATION.md](../docs/P1_SKILLS_SYSTEM_IMPLEMENTATION.md) for:

{mapify_cli-2.2.0 → mapify_cli-2.3.0}/.gitignore

@@ -93,3 +93,4 @@ docs/claude-code-prompt-improver
 .mcp.json
 .chunkhound.json
 .chunkhound/
+docs/planning-with-files.txt

{mapify_cli-2.2.0 → mapify_cli-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 2.2.0
+Version: 2.3.0
 Summary: MAP Framework installer - Modular Agentic Planner for Claude Code
 Project-URL: Homepage, https://github.com/azalio/map-framework
 Project-URL: Repository, https://github.com/azalio/map-framework.git
@@ -231,6 +231,7 @@ Edit `.claude/workflow-rules.json` to add project-specific trigger words and pat
 MAP includes interactive skills that provide specialized guidance:
 
 **map-workflows-guide** - Helps you choose the right workflow
+**map-planning** - Persistent file-based plans for long `/map-efficient` sessions (`.map/task_plan_<branch>.md`)
 
 **Auto-suggested when you ask:**
 - "Which workflow should I use?"
@@ -243,7 +244,7 @@ MAP includes interactive skills that provide specialized guidance:
 - 8 detailed resource guides (progressive disclosure)
 
 **Skills vs Agents:**
-- **Skills** = Passive documentation (guidance)
+- **Skills** = Optional modules (guidance and/or workflow automation via hooks)
 - **Agents** = Active execution (code generation)
 
 **See [docs/USAGE.md](docs/USAGE.md#skills-system) for full details.**

{mapify_cli-2.2.0 → mapify_cli-2.3.0}/README.md

@@ -201,6 +201,7 @@ Edit `.claude/workflow-rules.json` to add project-specific trigger words and pat
 MAP includes interactive skills that provide specialized guidance:
 
 **map-workflows-guide** - Helps you choose the right workflow
+**map-planning** - Persistent file-based plans for long `/map-efficient` sessions (`.map/task_plan_<branch>.md`)
 
 **Auto-suggested when you ask:**
 - "Which workflow should I use?"
@@ -213,7 +214,7 @@ MAP includes interactive skills that provide specialized guidance:
 - 8 detailed resource guides (progressive disclosure)
 
 **Skills vs Agents:**
-- **Skills** = Passive documentation (guidance)
+- **Skills** = Optional modules (guidance and/or workflow automation via hooks)
 - **Agents** = Active execution (code generation)
 
 **See [docs/USAGE.md](docs/USAGE.md#skills-system) for full details.**

{mapify_cli-2.2.0 → mapify_cli-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mapify-cli"
-version = "2.2.0"
+version = "2.3.0"
 description = "MAP Framework installer - Modular Agentic Planner for Claude Code"
 authors = [{ name = "MAP Framework Contributors" }]
 readme = "README.md"

{mapify_cli-2.2.0 → mapify_cli-2.3.0}/src/mapify_cli/__init__.py

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 import copy
 import os

{mapify_cli-2.2.0 → mapify_cli-2.3.0}/src/mapify_cli/templates/agents/monitor.md

@@ -1709,6 +1709,30 @@ Do NOT invent issues to justify review effort. Empty `issues` array is valid.
     "contract_compliant": {
       "type": "boolean",
       "description": "True if all validation_criteria contracts pass (NOT SpecificationContract compliance)"
+    },
+    "status_update": {
+      "type": "object",
+      "description": "Plan file update when subtask validation succeeds (map-planning integration)",
+      "properties": {
+        "subtask_id": {
+          "type": "string",
+          "description": "Subtask identifier (e.g., 'ST-001')"
+        },
+        "new_status": {
+          "type": "string",
+          "enum": ["complete", "blocked", "won't_do", "superseded"],
+          "description": "New status for the subtask"
+        },
+        "completed_criteria": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of validation criteria that were satisfied"
+        },
+        "next_subtask_id": {
+          "type": "string",
+          "description": "ID of next subtask to mark as in_progress (optional)"
+        }
+      }
     }
   }
 }
@@ -1740,6 +1764,10 @@ IF ≥1 MCP tool failed:
 
 IF recovery_mode == "manual_only":
   → recovery_notes MUST explain limitations
+
+IF map-planning workflow active AND valid === true:
+  → status_update SHOULD be present with subtask_id and new_status
+  → Orchestrator uses this to update task_plan file (Single-Writer Governance)
 ```
 
 **Required Structure**:

{mapify_cli-2.2.0 → mapify_cli-2.3.0}/src/mapify_cli/templates/agents/research-agent.md

@@ -180,6 +180,47 @@ IF ChunkHound tools fail or timeout:
 | 0.3-0.5 | Weak match | Actor proceeds with caution |
 | <0.3 | No good match | Escalate to user |
 
+# MAP-PLANNING INTEGRATION (Optional)
+
+When orchestrator provides `findings_file` path in prompt, append research results:
+
+**Input Signal** (from orchestrator):
+```
+Findings file: .map/findings_feature-auth.md
+```
+
+**Action**:
+1. After completing search, format findings as Markdown
+2. Append to findings file using Write tool (append mode via reading + concatenating)
+
+**Findings Format** (append to file):
+```markdown
+---
+
+## Research: [query summary]
+**Timestamp:** [ISO-8601]
+**Confidence:** [0.0-1.0]
+**Search Method:** [chunkhound_semantic|glob_grep_fallback|...]
+
+### Summary
+[executive_summary from JSON output]
+
+### Key Locations
+| Path | Lines | Signature | Relevance |
+|------|-------|-----------|-----------|
+| src/auth/service.py | 45-67 | `def validate_token(...)` | Core JWT validation |
+
+### Patterns Discovered
+- Pattern 1
+- Pattern 2
+```
+
+**Rules**:
+- Only append if `findings_file` provided in prompt
+- Always prepend `---` separator for append safety
+- Include timestamp for chronological tracking
+- Keep append content under 500 tokens
+
 # ON-DEMAND CODE READING
 
 Research Agent returns **pointers**, not full code:

{mapify_cli-2.2.0 → mapify_cli-2.3.0}/src/mapify_cli/templates/commands/map-efficient.md

@@ -17,6 +17,7 @@ description: Token-efficient MAP workflow with conditional optimizations
 
 ```
 1. DECOMPOSE → task-decomposer
+1.5. INIT PLANNING → generate .map/task_plan_<branch>.md from blueprint
 2. FOR each subtask:
    a. CONTEXT → playbook query (Actor will run `cipher_memory_search` per protocol; orchestrator MAY run extra cipher search to augment context)
    b. RESEARCH → if existing code understanding needed
@@ -50,8 +51,71 @@ Hard requirements:
 )
 ```
 
+## Step 1.5: Initialize Planning Session
+
+**REQUIRED**: Generate persistent plan file from task-decomposer blueprint.
+
+```bash
+# 1. Create .map/ directory and planning files
+.claude/skills/map-planning/scripts/init-session.sh
+```
+
+```
+# 2. Generate task_plan from blueprint JSON
+# Get branch-scoped plan path
+PLAN_PATH=$(.claude/skills/map-planning/scripts/get-plan-path.sh)
+
+# Write plan content from blueprint:
+# - Header: blueprint.summary as Goal
+# - For each subtask: ## ST-XXX section with **Status:** pending
+# - First subtask: **Status:** in_progress
+# - Terminal State: **Status:** pending
+```
+
+**Plan file format** (`.map/task_plan_<branch>.md`):
+
+```markdown
+# Task Plan: [blueprint.summary]
+
+## Goal
+[blueprint.summary]
+
+## Current Phase
+ST-001
+
+## Phases
+
+### ST-001: [subtask.title]
+**Status:** in_progress
+Risk: [risk_level]
+Complexity: [complexity_score]
+Files: [affected_files]
+
+Validation:
+- [ ] [validation_criteria[0]]
+- [ ] [validation_criteria[1]]
+
+### ST-002: [subtask.title]
+**Status:** pending
+...
+
+## Terminal State
+**Status:** pending
+```
+
+**Why required:**
+- Enables resumption after context reset
+- Prevents goal drift in long workflows
+- Provides explicit state tracking for orchestrator
+
 ## Step 2: Subtask Loop
 
+**Before each subtask**: Read current plan to prevent goal drift:
+```bash
+PLAN_PATH=$(.claude/skills/map-planning/scripts/get-plan-path.sh)
+# Read Goal and current in_progress phase from $PLAN_PATH
+```
+
 ### 2.0 Build AI-Friendly Subtask Packet (XML Anchors)
 
 Before calling any agents for the subtask, build a single **AI Packet** with unique XML-like tags (NO attributes).
@@ -114,6 +178,11 @@ Pass `context_patterns` with relevance scores to Actor for informed decision-mak
 **Call if:** refactoring, bug fixes, extending existing code, touching 3+ files
 **Skip for:** new standalone features, docs, config
 
+```bash
+# Get findings file path for map-planning integration
+FINDINGS_PATH=$(.claude/skills/map-planning/scripts/get-plan-path.sh | sed 's/task_plan/findings/')
+```
+
 ```
 Task(
   subagent_type="research-agent",
@@ -122,7 +191,8 @@ Task(
 File patterns: [relevant globs]
 Symbols: [optional keywords]
 Intent: locate
-Max tokens: 1500"
+Max tokens: 1500
+Findings file: [FINDINGS_PATH]"
 )
 ```
 
@@ -286,10 +356,59 @@ If validation_criteria present, include contract_compliance + contract_compliant
 )
 ```
 
-### 2.5 Retry Loop
+### 2.5 Retry Loop (3-Strike Protocol)
 
 If `valid === false`: provide feedback, retry Actor (max 5 iterations).
 
+**3-Strike Protocol** (for persistent failures):
+
+```bash
+# Get progress file path
+PROGRESS_PATH=$(.claude/skills/map-planning/scripts/get-plan-path.sh | sed 's/task_plan/progress/')
+```
+
+```
+FOR attempt = 1 to 5:
+  IF attempt >= 3:
+    # Log to progress file
+    Append to PROGRESS_PATH:
+    | Timestamp | Subtask | Attempt | Error | Resolution |
+    |-----------|---------|---------|-------|------------|
+    | [ISO-8601] | [ST-XXX] | [attempt] | [Monitor feedback summary] | [pending] |
+
+  Call Actor with Monitor feedback
+  Call Monitor to validate
+
+  IF valid === true:
+    Update progress log: Resolution = "Fixed on attempt [N]"
+    BREAK
+
+  IF attempt === 3:
+    # Escalate after 3 failed attempts
+    AskUserQuestion(
+      questions: [{
+        header: "3-Strike Limit",
+        question: "Subtask [ST-XXX] failed 3 attempts.\n\nLast error: [Monitor feedback]\n\nHow to proceed?",
+        multiSelect: false,
+        options: [
+          { label: "CONTINUE", description: "Try 2 more attempts (max 5 total)" },
+          { label: "SKIP", description: "Mark subtask as blocked, move to next" },
+          { label: "ABORT", description: "Stop workflow, await manual fix" }
+        ]
+      }]
+    )
+
+    IF user selects "SKIP":
+      Update task_plan: **Status:** blocked
+      Update progress log: Resolution = "Marked blocked after 3 attempts"
+      CONTINUE to next subtask
+
+    IF user selects "ABORT":
+      Update task_plan: **Status:** blocked
+      Update Terminal State: **Status:** blocked
+      EXIT workflow
+```
+
 ### 2.5b Escalation Gate (AskUserQuestion)
 
 If Monitor returns `escalation_required === true`, you MUST ask user for confirmation before proceeding (Predictor and/or Apply).
@@ -338,7 +457,21 @@ Return ONLY valid JSON following Predictor schema."
 
 ### 2.7 Apply Changes
 
-Apply via Write/Edit tools. Proceed to next subtask.
+Apply via Write/Edit tools.
+
+### 2.7.1 Update Plan Status
+
+After Monitor returns `valid === true`:
+
+```
+1. Read current task_plan from PLAN_PATH
+2. Update current subtask: **Status:** in_progress → **Status:** complete
+3. Check validation criteria checkboxes [x]
+4. Set next pending subtask to **Status:** in_progress
+5. Update "Current Phase" to next subtask ID
+```
+
+Proceed to next subtask.
 
 ### 2.8 Gate 2: Tests Available / Run
 
@@ -369,6 +502,12 @@ If none found: mark gate as skipped and proceed.
 ## Step 3: Summary
 
 - Run tests if applicable
+- **Update Terminal State** in task_plan:
+  ```markdown
+  ## Terminal State
+  **Status:** complete
+  Reason: All [N] subtasks implemented and validated.
+  ```
 - Create commit (if requested)
 - Report: features implemented, files changed
 

mapify_cli-2.3.0/src/mapify_cli/templates/skills/map-planning/SKILL.md

@@ -0,0 +1,169 @@
+---
+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_<branch>.md    # Primary plan with phases and status
+├── findings_<branch>.md     # Research findings, decisions, key files
+└── progress_<branch>.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: <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
+```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

mapify_cli-2.3.0/src/mapify_cli/templates/skills/map-planning/scripts/check-complete.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+#
+# check-complete.sh - Verify all phases have terminal state (Stop hook)
+#
+# Description:
+#   Called by Stop hook before agent session ends.
+#   Counts phases by status and verifies all have reached terminal state.
+#   Terminal states: complete, blocked, won't_do, superseded
+#
+# Usage:
+#   ${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh
+#
+# Exit codes:
+#   0 - All phases in terminal state (OK to stop)
+#   1 - Phases still pending/in_progress (do not stop)
+#   0 - No plan file (OK to stop - planning not used)
+
+# Get script directory for calling sibling scripts
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Get the branch-specific plan file path
+PLAN_FILE=$("$SCRIPT_DIR/get-plan-path.sh")
+
+# If no plan file exists, allow stop (planning not being used)
+if [ ! -f "$PLAN_FILE" ]; then
+    exit 0
+fi
+
+echo "=== Task Completion Check ==="
+echo "Plan: $PLAN_FILE"
+echo ""
+
+# Count phases by status
+# NOTE: grep -c outputs "0" but exits 1 on no matches, causing || to trigger
+# Use: VAR=$(grep ...) || VAR=0 pattern to avoid double output
+COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" 2>/dev/null) || COMPLETE=0
+BLOCKED=$(grep -cF "**Status:** blocked" "$PLAN_FILE" 2>/dev/null) || BLOCKED=0
+WONT_DO=$(grep -cF "**Status:** won't_do" "$PLAN_FILE" 2>/dev/null) || WONT_DO=0
+SUPERSEDED=$(grep -cF "**Status:** superseded" "$PLAN_FILE" 2>/dev/null) || SUPERSEDED=0
+IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" 2>/dev/null) || IN_PROGRESS=0
+PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" 2>/dev/null) || PENDING=0
+
+# TOTAL = sum of all status lines (not all ## headers, which includes Goal, Decisions, etc.)
+TOTAL=$((COMPLETE + BLOCKED + WONT_DO + SUPERSEDED + IN_PROGRESS + PENDING))
+
+# Calculate terminal states (complete + blocked + won't_do + superseded)
+TERMINAL=$((COMPLETE + BLOCKED + WONT_DO + SUPERSEDED))
+
+echo "Total phases:   $TOTAL"
+echo "Terminal:       $TERMINAL (complete: $COMPLETE, blocked: $BLOCKED, won't_do: $WONT_DO, superseded: $SUPERSEDED)"
+echo "In progress:    $IN_PROGRESS"
+echo "Pending:        $PENDING"
+echo ""
+
+# Check completion: all phases must be in terminal state
+if [ "$TERMINAL" -ge "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
+    echo "✅ ALL PHASES COMPLETE OR TERMINAL"
+    exit 0
+else
+    echo "⚠️  TASK NOT COMPLETE"
+    echo ""
+    echo "Do not stop until all phases reach terminal state:"
+    echo "  - complete: Phase finished successfully"
+    echo "  - blocked: Waiting on external dependency"
+    echo "  - won't_do: Decided not to implement"
+    echo "  - superseded: Replaced by different approach"
+    exit 1
+fi

mapify_cli-2.3.0/src/mapify_cli/templates/skills/map-planning/scripts/get-plan-path.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# get-plan-path.sh - Generate branch-scoped task plan file path
+#
+# Description:
+#   Detects current git branch and outputs path to branch-specific task plan file.
+#   Sanitizes branch names by replacing '/' with '-' for filesystem compatibility.
+#   Defaults to 'main' branch when not in a git repository.
+#
+# Usage:
+#   PLAN_PATH=$(bash .claude/skills/map-planning/scripts/get-plan-path.sh)
+#
+# Output:
+#   .map/task_plan_<sanitized_branch_name>.md
+#
+# Examples:
+#   Branch: feature/map-planning -> .map/task_plan_feature-map-planning.md
+#   Branch: main                 -> .map/task_plan_main.md
+#   Not in repo                  -> .map/task_plan_main.md
+
+set -euo pipefail
+
+# Detect current git branch, default to 'main' if not in git repo
+BRANCH=$(git branch --show-current 2>/dev/null || echo 'main')
+
+# Handle empty branch (detached HEAD or git issue)
+if [ -z "$BRANCH" ]; then
+    BRANCH="main"
+fi
+
+# Sanitize branch name: replace '/' with '-' for filesystem safety
+SANITIZED_BRANCH=$(echo "$BRANCH" | tr '/' '-')
+
+# Output the plan file path
+echo ".map/task_plan_${SANITIZED_BRANCH}.md"

mapify_cli-2.3.0/src/mapify_cli/templates/skills/map-planning/scripts/init-session.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+#
+# init-session.sh - Initialize planning files for new MAP session
+#
+# Description:
+#   Creates .map/ directory and copies templates for branch-scoped planning files.
+#   Idempotent: skips files that already exist.
+#
+# Usage:
+#   ${CLAUDE_PLUGIN_ROOT}/scripts/init-session.sh
+#
+# Created files:
+#   .map/task_plan_<branch>.md
+#   .map/findings_<branch>.md
+#   .map/progress_<branch>.md
+
+set -euo pipefail
+
+# Get script directory for accessing templates
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
+TEMPLATE_DIR="$SKILL_ROOT/templates"
+
+# Get branch name for file naming
+BRANCH=$(git branch --show-current 2>/dev/null || echo 'main')
+if [ -z "$BRANCH" ]; then
+    BRANCH="main"
+fi
+SANITIZED_BRANCH=$(echo "$BRANCH" | tr '/' '-')
+
+# Create .map directory
+MAP_DIR=".map"
+mkdir -p "$MAP_DIR"
+
+# Define file paths
+TASK_PLAN="$MAP_DIR/task_plan_${SANITIZED_BRANCH}.md"
+FINDINGS="$MAP_DIR/findings_${SANITIZED_BRANCH}.md"
+PROGRESS="$MAP_DIR/progress_${SANITIZED_BRANCH}.md"
+
+echo "=== MAP Planning Session Initialization ==="
+echo "Branch: $BRANCH (sanitized: $SANITIZED_BRANCH)"
+echo ""
+
+# Copy templates if files don't exist (idempotent)
+copy_if_missing() {
+    local src="$1"
+    local dst="$2"
+    local name="$3"
+
+    if [ -f "$dst" ]; then
+        echo "✓ $name already exists: $dst"
+    elif [ -f "$src" ]; then
+        cp "$src" "$dst"
+        echo "✓ Created $name: $dst"
+    else
+        echo "⚠ Template not found: $src (skipping $name)"
+    fi
+}
+
+copy_if_missing "$TEMPLATE_DIR/task_plan.md" "$TASK_PLAN" "task_plan"
+copy_if_missing "$TEMPLATE_DIR/findings.md" "$FINDINGS" "findings"
+copy_if_missing "$TEMPLATE_DIR/progress.md" "$PROGRESS" "progress"
+
+echo ""
+echo "=== Session Ready ==="
+echo "Edit $TASK_PLAN to define your phases."
+echo ""
+echo "Next steps:"
+echo "1. Define goal in task_plan"
+echo "2. Add phases with **Status:** pending"
+echo "3. Start working - PreToolUse hook will show focus"
+echo "4. Update status as phases complete"

mapify_cli-2.3.0/src/mapify_cli/templates/skills/map-planning/scripts/show-focus.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+#
+# show-focus.sh - Display current task plan focus (PreToolUse hook)
+#
+# Description:
+#   Called by PreToolUse hook before Write/Edit/Bash operations.
+#   Extracts ONLY the in_progress section (~200 tokens) to prevent goal drift.
+#   Shows: Goal + Current in_progress phase details.
+#
+# Usage:
+#   ${CLAUDE_PLUGIN_ROOT}/scripts/show-focus.sh
+#
+# Exit codes:
+#   0 - Always (even if plan file doesn't exist)
+
+# Get script directory for calling sibling scripts
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Get the branch-specific plan file path
+PLAN_FILE=$("$SCRIPT_DIR/get-plan-path.sh")
+
+# If no plan file, exit silently
+[ ! -f "$PLAN_FILE" ] && exit 0
+
+# Extract goal (line after "## Goal")
+GOAL=$(awk '/^## Goal/{getline; if(!/^#/ && !/^$/) print; exit}' "$PLAN_FILE")
+
+# Extract ONLY the current in_progress phase section.
+# Stop at the next phase (###) OR next top-level section (##) to avoid token bloat.
+# Cap output by lines as a simple proxy for token budget.
+FOCUS_MAX_LINES="${FOCUS_MAX_LINES:-40}"
+IN_PROGRESS_SECTION=$(
+    awk '
+        /^### / {
+            if (in_section) exit
+            header = $0
+            next
+        }
+        /^## / {
+            if (in_section) exit
+        }
+        /\*\*Status:\*\* in_progress/ {
+            in_section = 1
+            if (header != "") print header
+            print
+            next
+        }
+        in_section { print }
+    ' "$PLAN_FILE" | head -n "$FOCUS_MAX_LINES"
+)
+
+# Only output if we found an in_progress section
+if [ -n "$IN_PROGRESS_SECTION" ]; then
+    BRANCH=$(basename "$PLAN_FILE" .md | sed 's/task_plan_//')
+    echo "───── MAP FOCUS ($BRANCH) ─────"
+    [ -n "$GOAL" ] && echo "Goal: $GOAL"
+    echo ""
+    echo "$IN_PROGRESS_SECTION"
+    echo "─────────────────────────────────"
+fi
+
+exit 0

mapify_cli-2.3.0/src/mapify_cli/templates/skills/map-planning/templates/findings.md

@@ -0,0 +1,62 @@
+# Findings & Decisions
+<!--
+  WHAT: Your knowledge base for the task. Stores everything you discover.
+  WHY: Context windows are limited. This file is your "external memory."
+  WHEN: Update after ANY discovery, especially from research-agent output.
+-->
+
+## Requirements
+<!--
+  WHAT: What needs to be built, broken into specific requirements.
+  WHY: Keeps requirements visible so you don't forget what you're building.
+  WHEN: Fill this in during research phase.
+-->
+-
+
+## Research Findings
+<!--
+  WHAT: Key discoveries from codebase exploration, web searches, documentation.
+  WHY: Preserves knowledge that might be lost when context resets.
+  WHEN: Update after research-agent returns, or after exploring code.
+-->
+-
+
+## Technical Decisions
+<!--
+  WHAT: Architecture and implementation choices with reasoning.
+  WHY: You'll forget why you chose an approach. This table preserves that.
+  EXAMPLE:
+    | Use existing auth library | Reduces complexity, tested code |
+-->
+| Decision | Rationale |
+|----------|-----------|
+|          |           |
+
+## Key Files
+<!--
+  WHAT: Important files discovered during research.
+  WHY: Quick reference for relevant code locations.
+  EXAMPLE:
+    - src/auth/jwt.ts: Token generation logic
+    - src/middleware/auth.ts: Request validation
+-->
+-
+
+## Issues Encountered
+<!--
+  WHAT: Problems encountered and how they were solved.
+  WHY: Helps avoid repeating same mistakes.
+-->
+| Issue | Resolution |
+|-------|------------|
+|       |            |
+
+## Resources
+<!--
+  WHAT: URLs, file paths, API references found useful.
+  WHY: Easy reference for later.
+-->
+-
+
+---
+*Update after research-agent output or codebase exploration*

mapify_cli-2.3.0/src/mapify_cli/templates/skills/map-planning/templates/progress.md

@@ -0,0 +1,75 @@
+# Progress Log
+<!--
+  WHAT: Chronological record of what you did, when, and what happened.
+  WHY: Answers "What have I done?" Helps resume after breaks.
+  WHEN: Update after completing each phase or encountering errors.
+-->
+
+## Session: [DATE]
+<!--
+  WHAT: The date of this work session.
+  EXAMPLE: 2025-01-10
+-->
+
+### Phase 1: [Title]
+<!--
+  WHAT: Detailed log of actions during this phase.
+  WHY: Provides context for what was done, making it easier to resume.
+-->
+- **Status:** in_progress
+- **Started:** [timestamp]
+- Actions taken:
+  -
+- Files created/modified:
+  -
+
+### Phase 2: [Title]
+- **Status:** pending
+- Actions taken:
+  -
+- Files created/modified:
+  -
+
+## Test Results
+<!--
+  WHAT: Tests run, expected vs actual results.
+  WHY: Documents verification of functionality.
+-->
+| Test | Input | Expected | Actual | Status |
+|------|-------|----------|--------|--------|
+|      |       |          |        |        |
+
+## Error Log
+<!--
+  WHAT: Every error with timestamp and resolution attempts.
+  WHY: Detailed error history helps avoid repetition.
+
+  3-STRIKE PROTOCOL:
+  - Attempt 1: Diagnose & fix
+  - Attempt 2: Try different approach
+  - Attempt 3: Broader rethink
+  - After 3 failures: Escalate to user
+-->
+| Timestamp | Error | Attempt | Resolution |
+|-----------|-------|---------|------------|
+|           |       | 1       |            |
+
+## 5-Question Reboot Check
+<!--
+  If you can answer these, your context is solid:
+  1. Where am I? → Current phase
+  2. Where am I going? → Remaining phases
+  3. What's the goal? → Goal in task_plan
+  4. What have I learned? → See findings.md
+  5. What have I done? → See above
+-->
+| Question | Answer |
+|----------|--------|
+| Where am I? | Phase X |
+| Where am I going? | Remaining phases |
+| What's the goal? | [goal statement] |
+| What have I learned? | See findings.md |
+| What have I done? | See above |
+
+---
+*Update after completing each phase or encountering errors*

mapify_cli-2.3.0/src/mapify_cli/templates/skills/map-planning/templates/task_plan.md

@@ -0,0 +1,70 @@
+# Task Plan: [Brief Description]
+<!--
+  WHAT: Your roadmap for MAP workflow - "working memory on disk."
+  WHY: After 50+ tool calls, original goals get forgotten. This file keeps them fresh.
+  WHEN: Create FIRST via init-session.sh. Update after each phase completes.
+-->
+
+## Goal
+<!--
+  WHAT: One clear sentence describing end state.
+  EXAMPLE: "Implement JWT authentication for the API with refresh token support."
+-->
+[One sentence describing the end state]
+
+## Current Phase
+ST-001
+
+## Phases
+<!--
+  TERMINAL STATES (Stop hook accepts):
+  - complete: Phase finished successfully
+  - blocked: Waiting on external dependency
+  - won't_do: Decided not to implement
+  - superseded: Replaced by different approach
+-->
+
+### ST-001: [subtask.title]
+**Status:** in_progress
+Risk: [risk_level]
+Complexity: [complexity_score]
+Files: [affected_files]
+
+Validation:
+- [ ] [validation_criteria[0]]
+- [ ] [validation_criteria[1]]
+
+### ST-002: [subtask.title]
+**Status:** pending
+Risk: [risk_level]
+Complexity: [complexity_score]
+Files: [affected_files]
+
+Validation:
+- [ ] [validation_criteria[0]]
+- [ ] [validation_criteria[1]]
+
+## Decisions Made
+| Decision | Rationale |
+|----------|-----------|
+|          |           |
+
+## Errors Encountered
+| Error | Attempt | Resolution |
+|-------|---------|------------|
+|       | 1       |            |
+
+## Terminal State
+<!--
+  VALUES:
+  - pending: Task not finished (blocks exit)
+  - complete: All phases finished successfully
+  - blocked: Cannot proceed (needs external input)
+  - won't_do: Task intentionally cancelled
+  - superseded: Replaced by different approach
+-->
+**Status:** pending
+Reason: [Not yet complete]
+
+---
+*PreToolUse hook shows this before actions. Stop hook validates terminal state.*