Skip to content

USAGE.md

Latest commit

 

History

History
1916 lines (1436 loc) · 59 KB

USAGE.md

File metadata and controls

1916 lines (1436 loc) · 59 KB

MAP Framework Usage Guide

Complete usage examples, best practices, and optimization strategies for the MAP Framework.

For long-running work, the canonical MAP flows maintain branch-scoped artifacts directly inside .map/<branch>/, so research, code-review lineage, verification summaries, PR drafts, and run dossiers survive context resets.

Canonical Flows

Standard flow

/map-plan clarify scope and decompose the task
/map-efficient implement the approved plan
/map-check
/map-review

Full TDD flow

/map-plan define the behavior and subtasks
/map-tdd implement with test-first phases enabled
/map-check
/map-review

Targeted subtask TDD flow

/map-plan decompose work into subtasks
/map-tdd ST-001
/map-task ST-001
/map-tdd ST-002
/map-task ST-002
/map-check
/map-review

The full TDD flow is the primary test-first path. The targeted subtask flow is the fine-grained variant when you want to drive one subtask at a time.

Navigation

📚 Usage Examples

Feature Development

/map-efficient implement user profile page with avatar upload.
Include validation, error handling, and tests.

Bug Fixing

/map-debug debug why payment processing fails for amounts over $1000

Refactoring

/map-efficient refactor OrderService to use dependency injection.
Maintain all existing functionality.

Library Integration

/map-efficient integrate Stripe payment processing.
Use deepwiki to get latest Stripe docs.

Learning from Open Source

/map-efficient implement rate limiter.
Study express-rate-limit via deepwiki, then create optimized version.

🧬 Self-MoA: Solution Synthesis

Self-MoA (Self-Mixture of Agents) is an advanced pattern that generates 3 implementation variants and synthesizes the best parts into an optimal combined solution.

How Self-MoA Works

  1. Actor×3 generates variants with different optimization focuses:

    • V1 (Security): Input validation, OWASP compliance, defensive coding
    • V2 (Performance): Algorithm efficiency, caching, async patterns
    • V3 (Simplicity): Readability, standard patterns, clear structure

  2. Monitor×3 validates each variant and extracts:

    • Key design decisions (3-8 per variant)
    • Compatibility features (error handling, concurrency model, etc.)
    • Strengths and weaknesses

  3. Synthesizer combines the best parts:

    • Extracts all decisions from viable variants
    • Resolves conflicts using priority precedence
    • Generates fresh unified code (not copy-paste)

  4. Final Monitor validates the synthesized solution

Activation

Explicit activation:

/map-efficient --self-moa implement JWT authentication with refresh tokens

Automatic activation: When TaskDecomposer marks a subtask as:

  • complexity: high
  • security_critical: true

When to Use Self-MoA

Use Self-MoA for:

  • Security-critical implementations (auth, data validation, encryption)
  • Complex algorithms with multiple valid approaches
  • Tasks requiring balance of security, performance, and maintainability
  • High-risk features where quality justifies higher token cost

Skip Self-MoA for:

  • Simple CRUD operations
  • Configuration changes
  • Documentation updates
  • Token-constrained workflows

Example Synthesis

Input Variants:
  V1 (security): Strong input validation, comprehensive error handling
  V2 (performance): Efficient O(n) algorithm, smart caching
  V3 (simplicity): Clean structure, readable code

Synthesis Result:
  - Structure: from V3 (clearest separation of concerns)
  - Validation: from V1 (OWASP-compliant input checks)
  - Algorithm: from V2 (O(n) instead of O(n²))

Output: Clean, secure, AND fast (better than any single variant)

Token Cost Considerations

Self-MoA uses ~4x tokens per subtask:

  • 3 Actor calls (parallel)
  • 3 Monitor calls (parallel)
  • 1 Synthesizer call
  • 1 Final Monitor call

Recommendation: Use Self-MoA selectively for critical subtasks, not for every task. The /map-efficient workflow automatically determines eligibility based on subtask complexity and security flags.

⚠️ Common CLI Mistakes

This section documents frequently encountered CLI command errors and their corrections. These validations are enforced by:

  • Pre-commit hooks (.git/hooks/pre-commit)
  • E2E tests (tests/test_agent_cli_correctness.py)
  • Agent template CLI reference sections

Wrong Operation Field Name

❌ Incorrect JSON ✅ Correct JSON
{"op": "ADD", "section": "...", "content": "..."} {"type": "ADD", "section": "...", "content": "..."}
{"op": "UPDATE", "bullet_id": "..."} {"type": "UPDATE", "bullet_id": "..."}
{"op": "DEPRECATE", "bullet_id": "..."} {"type": "DEPRECATE", "bullet_id": "..."}

Explanation: Delta operations use the field name "type", not "op". This is enforced in agent templates and validated by workflow contracts.

Quick Reference Resources

For comprehensive CLI documentation, see:

  • Quick reference skill: .claude/skills/map-cli-reference/SKILL.md

    • Auto-suggests when CLI errors occur
    • Provides immediate corrections
    • ~250 lines, follows 500-line skill rule

  • Complete CLI guide: docs/CLI_COMMAND_REFERENCE.md

    • Full command reference with examples
    • FTS5 query syntax guide
    • Exit codes and troubleshooting

  • Machine-readable spec: docs/CLI_REFERENCE.json

    • JSON schema for all commands
    • Parameter types and validation rules
    • Error pattern definitions

Validation Tools

Pre-commit hook (.git/hooks/pre-commit):

  • Blocks commits with incorrect CLI commands in agent templates
  • Validates template variables aren't removed
  • Runs automatically on git commit

E2E test (tests/test_agent_cli_correctness.py):

  • 6 test cases covering common mistakes
  • Runs in CI on every PR
  • Validates agent templates use correct CLI syntax

Skip validation (if absolutely necessary):

git commit --no-verify  # NOT RECOMMENDED

🔄 Handling Context Compaction

MAP workflows automatically save progress to the .map/ directory, which persists across context compactions. This ensures your work is never lost, even if the conversation context is cleared.

What is Context Compaction?

Context compaction occurs when Claude's conversation memory reaches its limit. When this happens:

  • The conversation history is cleared to free up space
  • But your work files on disk remain intact
  • MAP automatically restores your workflow state in the new session

Checkpoint Recovery with /map-resume

How it works:

MAP Framework uses a /map-resume command to recover interrupted workflows. When you start a new session after context exhaustion:

  1. Run /map-resume - Simple command to check for incomplete workflow
  2. View progress summary - Shows completed and remaining subtasks
  3. Confirm Y/n - Resume workflow or clear checkpoint and start fresh

What you'll see:

When running /map-resume with an existing checkpoint (.map/progress.md):

## Found Incomplete Workflow

**Task:** Implement JWT authentication
**Current Phase:** implementation
**Turn Count:** 12

### Progress Overview
3/5 subtasks completed (60%)

### Completed Subtasks ✅
- [x] **ST-001**: Create User model
- [x] **ST-002**: Implement login endpoint
- [x] **ST-003**: Add token validation middleware

### Remaining Subtasks 📋
- [ ] **ST-004**: Add refresh token logic
- [ ] **ST-005**: Write integration tests

Resume from last checkpoint? [Y/n]

Simple recovery - Press Y to continue:

User: Y

Claude: Resuming workflow from ST-004...
        [continues Actor→Monitor loop for remaining subtasks]

Benefits:

  • ✅ Explicit recovery - User controls when to resume
  • ✅ Progress visibility - See exactly what's done and remaining
  • ✅ Simple Y/n prompt - No complex options
  • ✅ Cross-session continuity - Resume in any new conversation

Security Design

The checkpoint format (.map/progress.md) is designed with security in mind:

  1. Path Traversal Prevention

    • Only allows files within .map/ directory
    • Resolves symlinks and ../ paths to prevent escaping
    • Rejects absolute paths outside project

  2. Size Bomb Protection

    • Maximum file size: 256KB (prevents memory exhaustion)
    • Validates size before reading file content
    • Rejects oversized files with clear error message

  3. UTF-8 Encoding Validation

    • Enforces strict UTF-8 encoding
    • Handles decoding errors gracefully
    • Prevents binary file injection

  4. Content Sanitization

    • Strips control characters (terminal escape codes, NULL bytes)
    • Preserves newlines and tabs (formatting)
    • Removes: \x00-\x08, \x0b-\x0d, \x0e-\x1f, \x7f (DELETE), Unicode control chars

Why this matters:

  • Path traversal attacks - Malicious checkpoint could try to inject /etc/passwd or ~/.ssh/id_rsa
  • Size bombs - Large files could exhaust memory, causing Claude Code to crash
  • Control character injection - Terminal escape codes could manipulate Claude's output
  • Encoding exploits - Binary data could contain executable payloads

Mitigation:

The checkpoint format (.map/progress.md) is designed with security in mind:

  • YAML frontmatter with simple key-value pairs (no code execution)
  • Human-readable markdown body (can be visually inspected)
  • Small file sizes (workflow state only, not code)
  • /map-resume command validates checkpoint before resuming

Manual Recovery (Fallback)

When to use manual recovery:

  • Corrupted checkpoint - /map-resume can't parse checkpoint
  • Debugging - Want to verify checkpoint contents before resuming
  • Explicit control - Prefer to manually reference files

Steps:

  1. Locate checkpoint files (auto-saved during workflow):

    .map/progress.md         - Workflow state (YAML frontmatter + markdown)
.map/*/task_plan_*.md    - Task decomposition with validation criteria

  2. After compaction, manually reference files:

    User: continue MAP workflow
      @.map/progress.md
      @.map/map-to-enchance/task_plan_map-to-enchance.md

Claude: [reads files]
        Resuming subtask 4: "Add refresh token logic"
        [continues implementation from saved state]

Before/After Comparison

Without MAP Recovery With /map-resume ✨
Lose all workflow context Context preserved in checkpoint
Start over from scratch Resume from last completed subtask
Copy file paths manually Single command recovery
Paste paths with @ prefix Simple Y/n confirmation
Workflow abandoned Workflow continues

Example Workflow:

Without MAP Recovery:

[Context gets low]
[Compaction happens]
[New session starts]
User: what was I working on?
Claude: I don't have context from your previous session...
[User has to explain everything again]

With /map-resume:

[Context gets low]
[Compaction happens]
[New session starts]
User: /map-resume
Claude: ## Found Incomplete Workflow
        3/5 subtasks completed (60%)
        Resume from last checkpoint? [Y/n]
User: Y
Claude: Resuming workflow from ST-004...
        [continues Actor→Monitor loop]

Troubleshooting

/map-resume not working?

Symptoms:

  • /map-resume says "No Workflow in Progress"
  • Checkpoint exists but won't load

Diagnosis:

  1. Check if checkpoint file exists:

    ls -lh .map/progress.md
    • If missing: No checkpoint to restore (expected for new projects)
    • If exists: Proceed to step 2

  2. Check checkpoint file contents:

    head -20 .map/progress.md
    • Should contain valid YAML frontmatter with task_plan:, current_phase:, etc.
    • If malformed: Delete and start fresh with /map-efficient

  3. Resume workflow:

    /map-resume
    • Shows progress summary and asks for confirmation
    • Y to resume, n to clear checkpoint and start fresh

Common issues:

Issue Cause Solution
No checkpoint found Workflow not started or completed Start new workflow with /map-efficient
YAML parse error Corrupted checkpoint Delete .map/progress.md and start fresh
Missing task plan Task plan file deleted Delete checkpoint and restart workflow

Fallback:

If /map-resume continues to fail, use Manual Recovery workflow.

Safe re-initialization with merge behavior

Key Feature: Running mapify init preserves your customizations when updating MAP Framework hooks.

What gets preserved:

  • ✅ Your custom hooks (UserPromptSubmit, PreToolUse, Stop, etc.)
  • ✅ Your permissions settings
  • ✅ Your top-level configuration keys (description, customKey, etc.)

What gets added:

  • ✅ New MAP Framework hooks (if they don't already exist)
  • ✅ Updated hook scripts from templates

How it works:

# Safe to run multiple times - your customizations won't be lost
mapify init --force

Deduplication strategy:

MAP Framework uses the matcher field to identify duplicate hook groups:

Hook Scenario Behavior
User has matcher: "custom-pattern" Preserved (not in template)
Template has matcher: "Bash\\(.*\\)" Added only if user doesn't have this matcher
Both have same matcher: "Edit\|Write" User's version preserved, template not added
Hook has no matcher or matcher: "" Full JSON comparison used for deduplication

Example:

Your existing .claude/settings.json:

{
  "permissions": {
    "allow": ["Bash(git status:*)", "Bash(custom-command:*)"]
  },
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "custom-pattern",
        "description": "User's custom hook",
        "hooks": [{"type": "command", "command": "python3 /custom/script.py"}]
      }
    ]
  }
}

After mapify init:

{
  "permissions": {
    "allow": ["Bash(git status:*)", "Bash(custom-command:*)"]  // ✅ Preserved
  },
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "custom-pattern",  // ✅ Your custom hook preserved
        "description": "User's custom hook",
        "hooks": [{"type": "command", "command": "python3 /custom/script.py"}]
      },
      {
        "matcher": "",  // ✅ MAP Framework hook added
        "description": "Enhance prompts with clarification and pattern context",
        "hooks": [
          {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/improve-prompt.py"}
        ]
      }
    ]
  }
}

When to re-run mapify init:

  • ✅ After MAP Framework updates (to get new hooks)
  • ✅ If hooks are not working (safe to repair)
  • ✅ To update hook scripts without losing customizations
  • ⚠️ Your customizations are ALWAYS preserved

How to verify auto-recovery is working

Test sequence:

  1. Create a test task:

    /map-efficient "add test function to app.py"

  2. Wait for first subtask completion - Checkpoint should be created at .map/progress.md

  3. Start NEW conversation (simulate compaction):

    • Open new chat or use "Clear conversation" (if available)

  4. Run recovery command:

    /map-resume

  5. Verify restoration:

    • Look for "Found Incomplete Workflow" header
    • Check plan shows correct progress (e.g., "1/3 completed")
    • Press Y to continue

Expected behavior:

  • ✅ /map-resume detects checkpoint file
  • ✅ Progress summary shows completed/remaining subtasks
  • ✅ Y/n prompt allows user control
  • ✅ Workflow continues from last incomplete subtask

Key Points

  • ✅ Explicit recovery - /map-resume command to restore workflow state
  • ✅ Progress auto-saves - Every workflow step saves to disk
  • ✅ Simple checkpoint format - YAML frontmatter + markdown body
  • ✅ No manual checkpointing required - Files update automatically during workflow
  • ✅ Files persist forever - They're on your filesystem, not in conversation memory
  • ✅ Cross-session recovery - Resume in any new conversation with /map-resume
  • ✅ Manual fallback available - Reference .map/ files directly if needed

Architecture

MAP uses file-based persistence with automatic injection:

Files:

  • .map/progress.md - Workflow checkpoint with YAML frontmatter (machine-readable) + markdown body (human-readable)
  • .map/*/task_plan_*.md - Task decomposition with validation criteria
  • .map/dev_docs/context.md - Project context
  • .map/dev_docs/tasks.md - Task checklist

Recovery command:

  • /map-resume - Detects checkpoint and offers to resume incomplete workflow

These files survive compaction because they're stored on disk, not in conversation memory.

Technical Details:

For implementation details on checkpoint format and compaction resilience architecture, see:

  • ARCHITECTURE.md - Context Engineering - Recitation Pattern and Compaction Resilience
  • src/mapify_cli/templates/map/scripts/map_orchestrator.py - StepState class with step_state.json persistence

🔍 Dependency Validation

The dependency validation utility (scripts/validate-dependencies.py) ensures TaskDecomposer output has valid dependency graphs before execution. It prevents workflow failures by detecting:

  • Circular dependencies — Tasks that create impossible execution loops (A → B → C → A)
  • Forward references — Dependencies on non-existent tasks
  • Self-dependencies — Tasks that depend on themselves
  • Orphaned tasks — Isolated tasks with no incoming or outgoing dependencies

Basic Usage

Recommended (after pip install mapify-cli):

# Validate from file
mapify validate graph decomposer-output.json

# Output in text format (human-readable)
mapify validate graph decomposer-output.json -f text

# JSON format (default, for CI/CD)
mapify validate graph decomposer-output.json -f json

# Validate from stdin
cat decomposer-output.json | mapify validate graph

For development (using script directly):

# Validate from stdin
cat decomposer-output.json | python scripts/validate-dependencies.py

# Validate from file
python scripts/validate-dependencies.py decomposer-output.json

# Output in text format (human-readable)
python scripts/validate-dependencies.py -f text decomposer-output.json

# JSON format (default, for CI/CD)
python scripts/validate-dependencies.py -f json decomposer-output.json

Visualization Mode

Display ASCII dependency tree to understand task execution order:

Recommended (mapify CLI):

# Show dependency tree with colors
mapify validate graph decomposer-output.json --visualize

# Show tree without colors (for logs/CI)
mapify validate graph decomposer-output.json --visualize --no-color

For development (direct script):

# Show dependency tree with colors
python scripts/validate-dependencies.py --visualize decomposer-output.json

# Show tree without colors (for logs/CI)
python scripts/validate-dependencies.py --visualize --no-color decomposer-output.json

Example visualization output:

Task Dependency Tree:
Task 1: Setup environment
├─ Task 2: Install dependencies
│  └─ Task 4: Run tests
└─ Task 3: Configure database
   └─ Task 4: Run tests

Exit Codes

The validator uses standard exit codes for automation:

Exit Code Meaning CI/CD Action
0 Valid graph (no critical errors) Continue workflow
1 Invalid graph (critical errors found) OR warnings with --strict flag Fail build
2 Invalid input (malformed JSON or missing required fields) Fix input format

Note: By default, warnings (e.g., orphaned tasks) result in exit code 0 and do not fail CI/CD builds. Only critical errors (circular dependencies, forward references, self-dependencies) cause exit code 1. To enforce strict validation where warnings also fail the build, use the --strict flag. Use --format text to see issue severity levels.

CI/CD Integration Examples:

# Default mode: Only critical errors fail the build
mapify validate graph plan.json || exit 1
echo "✓ Task graph has no critical errors"

# Strict mode: Warnings also fail the build
mapify validate graph --strict plan.json || exit 1
echo "✓ Task graph is perfect (no warnings or errors)"

# Alternative: using direct script (for development/testing)
python scripts/validate-dependencies.py plan.json || exit 1
echo "✓ Task graph validated successfully"

Integration with TaskDecomposer

Validate TaskDecomposer output before starting workflow:

# Step 1: Decompose task
/map-efficient implement user authentication

# Step 2: Review TaskDecomposer output
# (orchestrator saves to .claude/decomposer-output.json)

# Step 3: Validate before execution (recommended)
mapify validate graph .claude/decomposer-output.json

# Alternative (for development): use direct script
python scripts/validate-dependencies.py .claude/decomposer-output.json

# Step 4: If valid, orchestrator proceeds automatically

Note: MAP Framework orchestrators can integrate this validation step to prevent execution of invalid task graphs.

Sample TaskDecomposer JSON

{
  "subtasks": [
    {
      "id": 1,
      "title": "Setup authentication middleware",
      "description": "Create Express middleware for JWT validation",
      "dependencies": []
    },
    {
      "id": 2,
      "title": "Implement login endpoint",
      "description": "POST /api/login with email/password",
      "dependencies": [1]
    },
    {
      "id": 3,
      "title": "Add refresh token logic",
      "description": "Implement token refresh endpoint",
      "dependencies": [1, 2]
    }
  ]
}

Validation Output Examples

Valid graph (JSON format):

{
  "valid": true,
  "issues": [],
  "summary": {
    "total_tasks": 3,
    "critical_issues": 0,
    "warnings": 0
  }
}

Invalid graph with circular dependency (JSON format):

{
  "valid": false,
  "issues": [
    {
      "type": "circular_dependency",
      "severity": "critical",
      "affected_tasks": [1, 2, 3],
      "message": "Circular dependency detected: 1 → 2 → 3 → 1"
    }
  ],
  "summary": {
    "total_tasks": 3,
    "critical_issues": 1,
    "warnings": 0
  }
}

Text format output:

⚠️  Validation Failed

Issues Found:
  [CRITICAL] Circular dependency detected: 1 → 2 → 3 → 1
    Affected tasks: 1, 2, 3

Summary:
  Total tasks: 3
  Critical issues: 1
  Warnings: 0

Command-Line Flags Reference

Flag Short Values Default Description
--format -f json, text json Output format for validation results
--visualize — — — Display ASCII dependency tree
--no-color — — — Disable ANSI colors in visualization
--strict — — — Fail on warnings (e.g., orphaned tasks), not just critical errors
--help -h — — Show help message and examples

Validation Best Practices

  1. Always validate in CI/CD — Add validation step before task execution
  2. Use JSON format for automation — Machine-readable output for scripts
  3. Use text format for debugging — Human-readable output for investigation
  4. Visualize complex graphs — Use --visualize to understand execution order
  5. Check exit codes — Use $? in shell scripts for automated validation

🔀 Workflow Variants

MAP Framework offers three primary implementation workflows with different trade-offs between token usage, quality assurance, and learning. A fourth workflow (/map-tdd) adds test-first development. A fifth (/map-task) executes a single subtask from an existing plan. Additional supporting workflows (/map-debug, /map-review, /map-check, /map-plan, /map-release, /map-resume, /map-learn) are documented in their respective sections.

Comparison Table

Feature /map-efficient ⭐ /map-fast ⚠️
Agents Used 3-4 (task-decomposer, actor, monitor, final-verifier)) 3 (minimal)
Token Cost Baseline 40-50% less
Learning Via /map-learn ❌ None
Quality Gates Essential agents + Final-Verifier Basic only
Impact Analysis ✅ Conditional (Predictor) ❌ Never
Multi-Variant ⚠️ Conditional (Self-MoA) ❌ Never
Synthesis Model Synthesizer (sonnet) N/A
Knowledge Updates Via /map-learn ❌ None
Best For Most tasks Throwaway only
Production Ready ✅ Yes ❌ NO

Decision Guide: Which Workflow Should I Use?

Use /map-efficient (RECOMMENDED) ⭐

When:

  • ✅ Production code where token costs matter
  • ✅ Well-understood features with low-medium risk
  • ✅ Iterative development with frequent workflows
  • ✅ You want learning without excessive token usage
  • ✅ Standard CRUD operations, UI components
  • ✅ Refactoring with clear scope

Why it's better than /map-fast:

  • Learning available via /map-learn after workflow (Reflector)
  • Conditional Predictor catches high-risk issues
  • Final-Verifier provides adversarial verification
  • Only 10% less token savings but much safer

Example use cases:

# Standard feature development
/map-efficient implement user profile editing with form validation

# API development
/map-efficient create REST API endpoints for product management

# UI components
/map-efficient build responsive navigation menu with mobile support

Use /map-efficient --self-moa (High-Quality Mode)

When:

  • 🔒 Security-critical functionality (authentication, authorization)
  • 🔒 Complex features with multiple valid approaches
  • 🔒 High-risk changes affecting many files/modules

What --self-moa adds:

  • Generates 3 variants (security/performance/simplicity focus)
  • Synthesizes best parts from each variant
  • Higher quality for critical code

Example use cases:

# Security-critical
/map-efficient --self-moa implement JWT authentication with refresh tokens

# Complex feature
/map-efficient --self-moa build real-time chat system with WebSocket support

Use /map-fast (Minimal) ⚠️

ONLY when:

  • ✅ Small, low-risk changes with clear acceptance criteria
  • ✅ Localized fixes with minimal blast radius
  • ✅ Time-sensitive changes where you still require production-quality output

⚠️ AVOID for:

  • ❌ Security-sensitive functionality
  • ❌ Broad refactors or multi-module changes
  • ❌ Ambiguous requirements or high uncertainty
  • ❌ Changes requiring careful impact analysis

Why it's dangerous:

  • No impact analysis → Breaking changes undetected
  • No learning → Knowledge base stays empty, same mistakes repeated
  • No quality scoring → Security/performance issues missed
  • No knowledge integration → Knowledge lost forever

Example use cases (acceptable):

# Small UI tweak
/map-fast Adjust button spacing in settings page

# Localized bug fix
/map-fast Fix nil check in request handler

# Minor docs automation
/map-fast Update CLI help text formatting

Use /map-tdd (Test-Driven Development)

When: Correctness-critical features where you need tests to validate behavior independently of implementation.

Key insight: When AI writes tests alongside code, tests tend to confirm the implementation (including its bugs) rather than validate the specification. TDD mode separates test authoring from implementation.

Flow:

DECOMPOSE → TEST_WRITER (tests from spec) → TEST_FAIL_GATE (verify Red) → ACTOR (code only) → MONITOR

Usage:

# Standalone TDD workflow
/map-tdd Add payment processing with refund support

# Or via --tdd flag on /map-efficient
/map-efficient --tdd Add JWT authentication with refresh tokens

Best for:

  • Auth, payments, data integrity features
  • Features with clear acceptance criteria in the spec
  • When previous AI-generated tests missed real bugs

Token cost: ~20-30% higher than /map-efficient (extra Actor call for test-writing phase).

Use /map-task (Single Subtask Execution)

When: You have a plan from /map-plan and want to execute just one specific subtask.

Prerequisites: Run /map-plan first to create a task decomposition.

Usage:

# Execute a single subtask from the plan
/map-task ST-001

# Write TDD tests for a specific subtask
/map-tdd ST-001

# Typical workflow: plan first, then pick subtasks
/map-plan Add user authentication
/map-task ST-001   # implement first subtask
/map-tdd ST-002    # TDD for second subtask
/map-task ST-003   # implement third subtask

Best for:

  • Fine-grained control over execution order
  • Parallelizing subtasks across multiple sessions
  • Resuming work on a specific subtask after context reset
  • Cherry-picking which subtasks to implement now vs. later

Real-World Token Usage Examples

Small Task (1-2 subtasks):

  • /map-efficient: ~12-20K tokens (baseline)
  • /map-efficient --self-moa: ~25-35K tokens (3 variants)
  • /map-fast: ~8-12K tokens (minimal)

Medium Task (3-5 subtasks):

  • /map-efficient: ~45-60K tokens (baseline)
  • /map-efficient --self-moa: ~100-130K tokens (3 variants)
  • /map-fast: ~25-35K tokens (minimal)

Large Task (6-8 subtasks):

  • /map-efficient: ~90-120K tokens (baseline)
  • /map-efficient --self-moa: ~200-260K tokens (3 variants)
  • /map-fast: ~50-70K tokens (minimal)

Cost at $3/M input, $15/M output (Claude Sonnet):

Task Size /map-efficient /map-fast
Small $0.18-0.30 $0.12-0.18
Medium $0.68-0.90 $0.38-0.53
Large $1.35-1.80 $0.75-1.05

For teams running 10 workflows/day with /map-efficient:

  • Daily cost: ~$13.50
  • /map-fast would save ~40% but loses learning

How /map-efficient Works

Key Optimizations:

  1. Conditional Predictor (5-10% savings)

    • TaskDecomposer assigns risk_level to each subtask
    • Predictor only called if risk_level='high' or Monitor flags issues
    • Low-risk tasks (simple CRUD, UI updates) skip impact analysis

  2. Learning Decoupled to /map-learn (token savings during main workflow)

    • Reflector is NOT called during /map-efficient execution
    • Run /map-learn after workflow completes to extract patterns
    • Reflector then analyzes ALL subtasks together (batched, more holistic insights)

  3. Evaluator Not Invoked (8-12% savings)

    • Monitor provides sufficient validation for most tasks
    • The Evaluator agent is skipped entirely (not just its scoring)
    • Evaluator only runs in /map-debug and /map-review
    • Quality still ensured by Monitor's comprehensive checks

What's Preserved:

  • ✅ Learning available via /map-learn (Reflector, optional after workflow)
  • ✅ Tests gate + Linter gate per subtask
  • ✅ Final-Verifier (adversarial verification at end)
  • ✅ Essential quality gates (Monitor validation)
  • ✅ Impact analysis (conditional Predictor when needed)

Workflow Selection Flowchart

START: I need to implement a feature
  |
  ├─ Is it a small, low-risk change?
  |    └─ YES → /map-fast
  |    └─ NO → Continue
  |
  ├─ Is it security-critical or first-time complex feature?
  |    └─ YES → /map-efficient (maximum QA)
  |    └─ NO → Continue
  |
  ├─ Do I care about token costs?
  |    └─ NO → /map-efficient (best quality)
  |    └─ YES → /map-efficient ⭐ (RECOMMENDED)

When to Use --self-moa Flag

Add --self-moa to /map-efficient for:

  • First implementation of authentication/authorization
  • Database migrations affecting multiple tables
  • Breaking API changes
  • Any feature where failure is costly
# Standard feature
/map-efficient implement user dashboard

# High-risk feature (use --self-moa for 3-variant synthesis)
/map-efficient --self-moa implement user dashboard with role-based access

Common Misconceptions

❌ Misconception: "/map-fast is 50% cheaper, so it's always better for saving money" ✅ Reality: /map-fast defeats MAP's purpose (no learning = repeat mistakes = waste tokens long-term). Use /map-efficient instead.

❌ Misconception: "/map-efficient skips quality checks" ✅ Reality: Monitor still validates every subtask. Evaluator is not invoked (it only runs in /map-debug and /map-review), but Tests gate, Linter gate, and Final-Verifier ensure quality.

❌ Misconception: "Learning via /map-learn is inferior to per-subtask learning" ✅ Reality: /map-learn runs Reflector after the workflow completes, analyzing ALL subtasks together. This batched approach sees patterns ACROSS subtasks, often producing better insights than isolated per-subtask analysis.

🎯 Best Practices

1. Actor Quality Checklist (NEW in v2.3.0)

The Actor agent now includes a 10-item Quality Checklist for self-review before submitting implementations to Monitor. Using this checklist reduces iteration cycles by 30-40%.

Benefits:

  • Catches common issues early (before Monitor validation)
  • Reduces Monitor iterations from 2-3 down to 1
  • Speeds up overall workflow completion
  • Trains Actor to internalize quality criteria

The checklist covers:

  1. Code style compliance (follows project standards)
  2. Explicit error handling (no silent failures)
  3. Security review (SQL injection, XSS, sensitive data)
  4. Test case identification (happy path + edge cases)
  5. MCP tools usage (deepwiki, sequential-thinking)
  6. Template variable preservation (orchestration compatibility)
  7. Trade-offs documentation (decision rationale)
  8. Complete implementations (no ellipsis or placeholders)
  9. Dependency justification (no unnecessary libraries)

How it works:

  • Actor performs self-review before submission
  • Critical Reminders section references the checklist
  • Monitor validation is faster (fewer common issues)

Learn more: See .claude/agents/actor.md lines 1102-1142 for the complete checklist.

2. Clear Requirements

Always provide specific, detailed requirements to get the best results.

# Good ✅
"Implement registration with email validation, password strength check (8+ chars, 1 number), send confirmation"

# Bad ❌
"Add registration"

Why it matters:

  • Clear requirements lead to better task decomposition
  • Reduces Actor-Monitor retry cycles
  • Produces more maintainable code

2. Incremental Approach

Break large features into phases to maintain focus and quality:

  • Phase 1: Core functionality
  • Phase 2: Edge cases and error handling
  • Phase 3: Optimization

Example workflow:

# Phase 1: Core implementation
/map-efficient implement basic user authentication with login/logout

# Phase 2: Enhanced security
/map-efficient add password reset and email verification to authentication

# Phase 3: Performance tuning
/map-efficient optimize authentication to use Redis session caching

3. Provide Context

Always specify relevant project context to improve solution quality:

Include:

  • Technology stack (e.g., "using Express.js with TypeScript")
  • Existing patterns (e.g., "follow the service-repository pattern used in UserService")
  • Constraints (e.g., "must work with PostgreSQL 12+")
  • Performance requirements (e.g., "handle 1000 requests/second")

Example:

/map-efficient implement product search using Elasticsearch.
Stack: Node.js + Express + PostgreSQL.
Follow existing repository pattern in ProductRepository.
Must handle 500 concurrent searches with <200ms response time.

💰 Cost Optimization

MAP Framework supports intelligent model selection per agent to balance capability and cost.

Model Distribution Strategy (Updated Nov 2025)

Note: In v3.0+, Predictor and Evaluator were upgraded from haiku to sonnet for better analysis quality.

Agent Model Reason Cost Impact
Predictor sonnet Impact analysis requires complex reasoning (upgraded from haiku) ➡️
Evaluator sonnet Evaluation requires nuanced judgment (upgraded from haiku) ➡️
Actor sonnet Code generation quality is critical ➡️
Monitor sonnet Quality validation requires thoroughness ➡️
TaskDecomposer sonnet Requires good understanding of requirements ➡️
Reflector sonnet Pattern extraction needs reasoning ➡️
DocumentationReviewer sonnet Documentation analysis needs thoroughness ➡️

Cost Impact of Model Upgrades

The upgrade of Predictor and Evaluator from haiku to sonnet provides:

  • Better analysis quality: More accurate impact predictions and quality evaluations
  • Higher costs: ~12x increase per agent call for predictor/evaluator
    • Input tokens: $0.25/1M (haiku) → $3/1M (sonnet)
    • Output tokens: $1.25/1M (haiku) → $15/1M (sonnet)
  • Per-workflow impact: ~$0.03 → ~$0.36 for typical 4-subtask feature

Cost Mitigation Strategies

1. Use /map-efficient workflow (RECOMMENDED)

  • Skips Evaluator per subtask (Monitor provides sufficient validation)
  • Conditional Predictor (only called for high-risk changes)
  • Reflector available via /map-learn after workflow
  • Token savings: 30-40%

2. Use /map-fast for small, low-risk changes

  • Minimal agent sequence: TaskDecomposer → Actor → Monitor
  • Skips: Predictor, Evaluator, Reflector
  • Token savings: 40-50% (but no learning!)

How It Works

Agents automatically use their configured model when invoked via slash commands:

# Standard workflow - conditional predictor, optional learning via /map-learn
/map-efficient implement authentication  # Recommended for most tasks

# Fast workflow - minimal agents, no learning
/map-fast Update error message wording

Cost Comparison Example

Scenario: Implement a feature with 4 subtasks

Workflow TaskDecomposer Actor Monitor Predictor Synthesizer Total Cost*
/map-efficient sonnet sonnet (4x) sonnet (4x) sonnet (0-2x) skip ~$0.22
/map-efficient --self-moa sonnet sonnet (12x) sonnet (12x) sonnet (0-2x) sonnet (4x) ~$0.45
/map-fast sonnet sonnet (4x) sonnet (4x) skip skip ~$0.12

*Approximate costs based on typical token usage. Learning via /map-learn adds ~$0.05-0.10.

Key differences:

  • /map-efficient: Standard workflow, conditional Self-MoA
  • /map-efficient --self-moa: Forces 3-variant generation + synthesis
  • /map-fast: Minimal, NO learning support

Additional Resources

📚 Skills System

MAP includes interactive skills to help you navigate workflows and understand the framework.

Available Skills

map-planning

Persistent session state for MAP workflows using file-based planning.

When to use planning:

  • 📋 Long workflows — Tasks with 50+ tool calls where context may reset
  • 📋 Multi-phase projects — Work spanning multiple sessions or days
  • 📋 Complex features — 5+ subtasks that need explicit tracking
  • 📋 Team handoffs — When another person may need to continue your work
  • 📋 Compliance/audit — When you need documented decision trail

When NOT to use:

  • Quick bug fixes (1-3 subtasks)
  • Single-session tasks that complete in <30 minutes
  • Exploratory work where the goal may change frequently

How it works:

  • Creates .map/ directory with branch-scoped plan files
  • Files: task_plan_<branch>.md, findings_<branch>.md, progress_<branch>.md
  • Prevents goal drift in long workflows (50+ tool calls)
  • Enables resumption after context reset

Initialization:

.claude/skills/map-planning/scripts/init-session.sh

Plan file structure:

# Task Plan: [goal]

## 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]

## Terminal State
**Status:** pending

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

Note: MAP workflows (/map-efficient, etc.) automatically use this skill. The .map/ directory is gitignored.

map-workflows-guide

Get help choosing the right workflow for your task.

How to access:

User: "Which workflow should I use?"
MAP: [Loads map-workflows-guide skill automatically]

What you get:

  • Quick decision tree - Answer 5 questions to find your workflow
  • Comparison matrix - Token cost, learning, agents, best-for columns
  • Detailed guides - When to use each workflow, trade-offs, examples
  • 8 deep-dive resources - Progressive disclosure for comprehensive learning

Skills vs Agents:

  • Skills provide passive guidance (documentation)
  • Agents execute active tasks (code generation)
  • Skills load via Skill tool, agents execute via Task tool

Auto-Activation

Skills automatically suggest themselves when relevant:

Keywords that trigger map-workflows-guide:

  • "which workflow"
  • "difference between workflows"
  • "when to use map-efficient"
  • "workflow comparison"

Example flow:

User: "I need to add a feature"
MAP: 🎯 "Consider /map-efficient"

User: "What's the difference between efficient and debate?"
MAP: 📚 "Loading map-workflows-guide skill"
[Shows comparison: efficient = production, debate = reasoning transparency]

Progressive Disclosure

Skills follow the 500-line rule:

  • Main SKILL.md (<500 lines) - High-level overview, quick decisions
  • Resources/ (8 files) - Deep-dive topics loaded on demand

Benefits:

  • Fast scanning (5-10 min for main skill)
  • Comprehensive when needed (25+ min with all resources)
  • Prevents context limit issues

Resources Available

Workflow deep-dives:

  • map-fast-deep-dive.md - Skip conditions, when to avoid
  • map-efficient-deep-dive.md - Optimization strategy, recommended default
  • map-debug-deep-dive.md - Debugging strategies, error analysis
  • map-learn-deep-dive.md - Lesson extraction, knowledge base updates
  • map-release-deep-dive.md - Release workflow, validation gates

System architecture:

  • agent-architecture.md - How 12 agents orchestrate

Creating Custom Skills

See .claude/skills/README.md for:

  • Skill structure (SKILL.md + resources/)
  • Trigger configuration (skill-rules.json)
  • Integration with auto-activation
  • Best practices and examples

🔒 Security Model: Three-Layer Defense

MAP Framework implements defense-in-depth security via three complementary layers.

Layer 1: Behavioral Rules (CLAUDE.md)

Guidelines in .claude/CLAUDE.md that guide agent behavior:

  • NEVER write code as orchestrator
  • NEVER commit .env files

Enforcement: Soft (relies on agent compliance)

Layer 2: Permissions (settings.json)

Access control rules in .claude/settings.json:

{
  "permissions": {
    "deny": [
      "Write(./.env*)",
      "Write(**/*credentials*)",
      "Write(**/*secret*)",
      "Bash(rm:-rf)",
      "Bash(git:push:--force:origin:main)"
    ],
    "allow": [
      "Bash(mapify:*)",
      "Bash(pytest:*)",
      "Bash(make:lint)"
    ]
  }
}

Enforcement: Medium (tool-level blocking with bypass risk)

Layer 3: Hooks (Deterministic Enforcement)

PreToolUse and Stop hooks that run before/after tool execution:

Hook Type Purpose
block-secrets.py PreToolUse Blocks access to .env, credentials, private keys
block-dangerous.sh PreToolUse Blocks rm -rf, force push to main, git reset --hard
end-of-turn.sh Stop Lints code, scans for secrets in staging

Enforcement: Hard (deterministic exit codes)

How the Layers Work Together

User: "Edit .env file"

Layer 1 (CLAUDE.md): Agent should know not to edit .env
    ↓ (but agent might miss this)
Layer 2 (settings.json): permissions.deny blocks Edit(./.env*)
    ↓ (but might be bypassed via path traversal)
Layer 3 (block-secrets.py): Hook intercepts, returns exit 2
    → BLOCKED with clear error message

Security Hooks in Detail

block-secrets.py (PreToolUse)

Blocks Read/Edit/Write operations on sensitive files:

Blocked patterns:

  • .env, .env.local, .env.production
  • credentials.json, secrets.yaml
  • Private keys (id_rsa, *_private.key)
  • AWS credentials, GCP service accounts

Example:

# Attempting to read .env
Read('.env')
→ Exit 2: "Blocked: sensitive file detected (.env)"

block-dangerous.sh (PreToolUse)

Blocks dangerous Bash commands:

Blocked patterns:

  • rm -rf / or rm -rf *
  • git push --force origin main
  • git push --force origin master
  • git reset --hard

Allowed:

  • rm -rf ./node_modules (scoped deletion)
  • git push --force origin feature-branch (non-main branch)
  • git reset --soft (non-hard reset)

end-of-turn.sh (Stop)

Quality gate that runs after Claude finishes responding:

Checks performed:

  1. Language-specific linting:

    • Python: runs ruff if available
    • Node.js: runs npm run lint if available
    • Go: runs go vet and staticcheck
    • Rust: runs cargo clippy

  2. Secret scanning: Detects hardcoded secrets in staged files

  3. .env check: Warns if .env files are staged for commit

Exit codes:

  • 0 = No issues
  • 1 = Warnings (non-blocking)
  • 2 = Critical issues (blocks and feeds to Claude)

Customizing Security

Per-project customization:

Edit .claude/settings.json for project-specific rules:

{
  "permissions": {
    "allow": [
      "Bash(docker:*)",  // Allow docker commands
      "Edit(./config/*)" // Allow editing config
    ]
  }
}

User overrides:

Create .claude/settings.local.json (gitignored) for personal overrides.

📊 Verification Results and Early Termination

MAP Framework tracks verification results from hooks and supports early workflow termination with the won't_do status.

Verification Results Tracking

The end-of-turn hook (end-of-turn.sh) records verification results to .map/verification_results_<branch>.json. This provides machine-readable verification status for CI/CD integration.

File location: .map/verification_results_<branch>.json

Example content:

{
  "overall": "pass",
  "recipes": [
    {
      "id": "check_ruff",
      "status": "pass",
      "summary": "ruff passed",
      "duration_ms": 1200
    },
    {
      "id": "check_secrets",
      "status": "skipped",
      "summary": "No staged files to check",
      "duration_ms": 50,
      "skip_reason": "No staged files"
    },
    {
      "id": "check_mypy",
      "status": "fail",
      "summary": "mypy failed",
      "duration_ms": 3500
    }
  ]
}

Recipe Status Values

Status Meaning Example
pass Check completed successfully Linter found no issues
fail Check found problems Type errors detected
skipped Check was intentionally skipped No staged files to scan

Overall Status Aggregation

The overall field follows strict aggregation rules:

Condition Overall Status
ANY recipe is fail fail
ALL recipes are pass pass
Otherwise (mixed, empty, all skipped) unknown

Skipped Status Explained

Checks return skipped when they cannot run due to missing prerequisites:

Common skip scenarios:

  • check_secrets: No staged files to check
  • check_mypy: No mypy configuration found
  • npm lint: node_modules directory missing
  • cargo clippy: Not in a Rust project

Example skipped result:

{
  "id": "check_secrets",
  "status": "skipped",
  "summary": "No staged files to check",
  "duration_ms": 50,
  "skip_reason": "No files were staged for commit"
}

Hooks Contract: When Hooks Block

Critical: Hooks only return exit code 2 (blocking) for security-critical issues:

Blocking (Exit 2) Non-Blocking (Exit 0-1)
Hardcoded secrets in staged files Linting failures
.env file staged for commit Type errors
Dangerous commands (rm -rf /, force push main) Formatting issues
Access to credential files Test failures

Why this matters:

  • Exit 2 stops Claude and feeds stderr back for correction
  • Exit 1 shows warning but continues
  • Exit 0 passes silently

Design principle: Quality checks (linting, types) should inform, not block. Only security violations warrant blocking.

Early Termination with won't_do Status

When a user decides to end a workflow early (before all subtasks complete), MAP Framework uses the won't_do terminal status.

Trigger phrases (Russian):

  • "закончили" (finished)
  • "остановимся" (let's stop)
  • "хватит" (enough)
  • "дальше не делай" (don't continue)
  • "прекращай" (stop it)
  • "закрываем" (we're closing)

Note: Currently only Russian trigger phrases are implemented in intent_detector.py. English equivalents are planned for a future release.

What happens:

  1. All pending and in_progress subtasks are marked won't_do
  2. Workflow state records ended_early metadata
  3. Completed subtasks remain complete

ended_early Structure

When a workflow terminates early, the state file includes:

{
  "terminal_status": "won't_do",
  "ended_early": {
    "by_user": true,
    "reason": "User requested early termination",
    "at_subtask_id": "ST-004"
  }
}
Field Type Description
by_user boolean Whether user initiated termination
reason string Human-readable reason for termination
at_subtask_id string ID of subtask that was active when terminated

Troubleshooting Verification Issues

Enable Verbose Hook Logging

export CLAUDE_HOOK_VERBOSE=true

This enables detailed logging from hooks, showing:

  • Which checks are running
  • Pass/fail status of each check
  • Duration of each check
  • Skip reasons for skipped checks

Artifact Locations

Artifact Path Purpose
Verification results .map/verification_results_<branch>.json Machine-readable check results
Workflow state .map/state_<branch>.json Current workflow status
Repo insight .map/repo_insight_<branch>.json Project language and suggested checks
Task plan .map/<branch>/task_plan_<branch>.md Subtask breakdown with validation
Progress checkpoint .map/progress.md Resume checkpoint for context recovery

Common Issues

Issue Cause Solution
Hook not recording results verification_recorder not installed Run pip install mapify-cli
Missing duration_ms SECONDS variable not working Ensure bash 4.0+
Wrong branch in filename Git not initialized Initialize git or results go to _default.json
overall: unknown unexpectedly All checks skipped Run checks manually to verify setup

Manual Verification Recording

For testing or debugging, you can record results manually:

python -m mapify_cli.verification_recorder <branch> <recipe_id> <status> <summary> [duration_ms]

# Example:
python -m mapify_cli.verification_recorder main check_custom pass "Custom check passed" 1500

⏸️ Workflow Recovery: /map-resume

Resume interrupted MAP workflows from the last checkpoint.

When to Use

  • After context window exhaustion mid-workflow
  • After accidental session termination
  • After /clear that interrupted a workflow
  • When returning to an unfinished task

How It Works

  1. Detects checkpoint: Checks for .map/progress.md
  2. Shows progress: Displays completed and remaining subtasks
  3. Asks confirmation: "Resume from last checkpoint?"
  4. Continues workflow: Resumes Actor→Monitor loop

Usage Example

/map-resume

Output:

## Found Incomplete Workflow

**Task:** Implement user authentication with JWT tokens
**Current Phase:** implementation
**Turn Count:** 12

### Progress Overview
3/5 subtasks completed (60%)

### Completed Subtasks ✅
- [x] **ST-001**: Create User model with SQLite schema
- [x] **ST-002**: Implement password hashing with bcrypt
- [x] **ST-003**: Create login API endpoint

### Remaining Subtasks 📋
- [ ] **ST-004**: Implement JWT token generation
- [ ] **ST-005**: Add logout and token refresh endpoints

How would you like to proceed?
[Continue (Recommended)] [View Details] [Abandon]

Auto-Checkpointing

MAP workflows automatically save progress to .map/progress.md:

  • After decomposition phase
  • After each subtask completion
  • Before each Actor call

Checkpoint format:

---
task_plan: "Implement authentication"
current_phase: implementation
turn_count: 12
completed_subtasks:
  - ST-001
  - ST-002
subtasks:
  - id: ST-001
    description: Create User model
    status: complete
  - id: ST-003
    description: Create login endpoint
    status: in_progress
---

# MAP Workflow Progress
[Human-readable markdown body]

Integration with /clear

If you run /clear during a workflow:

  • Checkpoint is preserved in .map/progress.md
  • Fresh context starts from checkpoint state
  • Use /map-resume to continue

🔌 Hooks System

MAP Framework uses Claude Code hooks to enhance your workflow experience.

Prompt Clarification (Prompt-Improver Hook)

Enabled by default - Automatically disambiguates vague prompts before execution.

What it does:

  1. Evaluates prompt clarity using conversation history
  2. For vague prompts (e.g., "fix the bug"):
    • Creates research plan (TodoWrite)
    • Gathers context from codebase, docs, web
    • Asks 1-6 grounded questions with specific options
  3. For clear prompts: Proceeds immediately

Example flow:

User: "fix the error"

MAP: [Prompt Improver Hook seeking clarification]
     [Research: Found 3 recent errors in logs]

     Which error needs fixing?
     ○ TypeError in src/components/Map.tsx (recent change)
     ○ API timeout in src/services/osmService.ts
     ○ Other (paste error message)

User: [Selects option]

MAP: [Proceeds with full context]

Bypass options:

  • * your prompt - Skip evaluation (remove * prefix)
  • /command - Slash commands bypass automatically
  • # memorize - Memorize feature bypasses automatically

Token overhead:

  • ~300 tokens per wrapped prompt
  • Only adds questions when genuinely needed
  • Better outcomes on first try = overall efficiency

Design philosophy:

  • Rarely intervene - Most prompts pass through
  • Trust user intent - Research before asking
  • Transparent - Evaluation visible in conversation
  • Max 1-6 questions - Focused clarification

Multi-Hook Processing

MAP uses multiple UserPromptSubmit hooks that run in parallel:

  1. Prompt-Improver – Disambiguates vague prompts (wraps prompt with evaluation instructions)
  2. Pattern Injection – Adds relevant patterns, and suggests workflows and skills

Note: Claude Code executes all matching hooks in parallel. Each hook's additionalContext output is concatenated and added to the prompt. The order is not guaranteed, but both enhancements are applied.

Implementation detail: Prompt improvement, pattern injection, and workflow suggestions are handled within the improve-prompt.py hook (.claude/hooks/improve-prompt.py).

Benefits:

  • Both hooks enhance the prompt with different types of context
  • Prompt-Improver adds evaluation wrapper, Pattern Injection adds patterns/workflows/skills
  • Modular design (hooks can be disabled independently)
  • Parallel execution (efficient)

Disabling Prompt-Improver

If you prefer direct execution without clarification:

Option 1: Use bypass prefix

* implement user authentication  # Skips improvement

Option 2: Remove from .claude/settings.json

{
  "hooks": {
    "UserPromptSubmit": [
      // Comment out or remove Prompt-Improver hook
      {
        "description": "Enhance prompts with clarification and pattern context",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/improve-prompt.py"
          }
        ]
      }
    ]
  }
}

Other Active Hooks

MAP Framework includes additional hooks for security and quality:

Hook Event Purpose
improve-prompt.py UserPromptSubmit Prompt clarification and enhancement
block-secrets.py PreToolUse Block access to sensitive files
block-dangerous.sh PreToolUse Block dangerous shell commands
end-of-turn.sh Stop Quality gates (linting, secret scanning)

Configuration: See .claude/settings.json for hook configuration (or manage via /hooks).

Security hooks: See Security Model: Three-Layer Defense for details.