Skip to content

README.md

Latest commit

 

History

History
121 lines (85 loc) · 4.84 KB

README.md

File metadata and controls

121 lines (85 loc) · 4.84 KB

MAP Framework for Claude Code

PyPI version Python 3.11+

Structured AI development workflows that replace ad-hoc prompting with plan → execute → validate loops.

Based on MAP cognitive architecture (Nature Communications, 2025) — 74% improvement in planning tasks.

Why MAP?

  • Structured workflows — 11 specialized agents instead of single-prompt chaos
  • Quality gates — automatic validation catches errors before they compound
  • 40-60% cost savings — prevents circular reasoning and scope creep
  • Learning system — captures patterns for reuse across projects
  • Persistent artifacts — /map-plan, /map-efficient, and /map-check keep branch-scoped research, session, review, QA, and verification artifacts inside .map/<branch>/

Quick Start

1. Install

uv tool install mapify-cli

# or with pip
pip install mapify-cli

2. Initialize (in your project)

cd your-project
mapify init

3. Start Claude Code and run your first workflow

claude
/map-efficient implement user authentication with JWT tokens

You'll know it's working when: Claude spawns specialized agents (TaskDecomposer → Actor → Monitor) with structured output instead of freeform responses.

Core Commands

Command Use For
/map-efficient Production features, refactoring, complex tasks (recommended)
/map-debug Bug fixes and debugging
/map-fast Small, low-risk changes
/map-review Pre-commit code review
/map-check Quality gates and verification
/map-plan Task decomposition without implementation
/map-task Execute a single subtask from an existing plan
/map-tdd Test-first implementation workflow
/map-release Package release workflow
/map-resume Resume interrupted workflows
/map-learn Extract lessons after workflow completion; optional [workflow-summary]

Detailed usage and options →

Canonical MAP flows:

  • Standard: /map-plan -> /map-efficient -> /map-check -> /map-review -> /map-learn (when you want to pay the learning cost)
  • Full TDD: /map-plan -> /map-tdd -> /map-check -> /map-review -> /map-learn
  • Targeted subtask TDD: /map-plan -> /map-tdd ST-001 -> /map-task ST-001 -> ... -> /map-check -> /map-review -> /map-learn

/map-plan now records a workflow-fit decision first, so trivial work can exit early with a direct edit or /map-fast recommendation instead of forcing full MAP planning.

These workflows maintain branch-scoped artifacts like code-review-001.md, qa-001.md, verification-summary.md, pr-draft.md, artifact_manifest.json, and run dossiers under .map/<branch>/. Targeted TDD flows also persist test_contract_ST-00N.md and test_handoff_ST-00N.json so /map-task can resume implementation from a clean red-phase handoff.

LEARN is still the philosophical end of the MAP cycle, but runtime keeps it soft: /map-efficient, /map-debug, /map-check, and /map-review now write learning-handoff.md / .json under .map/<branch>/, so /map-learn [workflow-summary] can run immediately with an explicit summary or later with no argument by auto-loading the generated handoff.

How It Works

MAP orchestrates specialized agents through slash commands:

TaskDecomposer → breaks goal into subtasks
     ↓
   Actor → generates code
     ↓
  Monitor → validates quality (loop if needed)
     ↓
 Predictor → analyzes impact (for risky changes)

The orchestration lives in .claude/commands/map-*.md prompts created by mapify init.

Architecture deep-dive →

Documentation

Guide Description
Installation All install methods, PATH setup, troubleshooting
Usage Guide Workflows, examples, cost optimization, playbook
Architecture Agents, MCP integration, customization
Platform Spec Platform refactor roadmap, codebase analysis

Case Study

Trouble?

  • Command not found → Run mapify init in your project first
  • Agent errors → Check .claude/agents/ has all 11 shipped agent .md files
  • More help →

Contributing

Improvements welcome: prompts for specific languages, new agents, CI/CD integrations.

License

MIT

MAP brings structure to AI-assisted development. Start with /map-efficient and see the difference.