map-framework

Why MAP Exists

Most AI agents rush straight to code — fast wrong answers, silent rework.

Common failure modes MAP eliminates:

• AI silently makes architecture decisions you did not approve.
• One prompt produces a large diff that is hard to review.
• Tests are written around the generated implementation, including its mistakes.
• The output compiles, but you cannot explain why the design is correct.
• The next session forgets the gotchas you already paid to discover.

MAP moves engineering judgment earlier: write down the behavior, split the work into small contracts, verify each stage, review against the spec, and save lessons for the next run.

Quick Start

1. Install

uv tool install mapify-cli

# or with pip
pip install mapify-cli

2. Initialize your project

Claude Code is the default provider:

cd your-project
mapify init
claude

Codex CLI:

cd your-project
mapify init . --provider codex
codex

Then enable the Codex hook: run /hooks, select PreToolUse, press t to toggle on, then Esc. If your Codex version does not support the hooks feature key yet, start with codex --enable codex_hooks or upgrade first.

3. Run the loop

/map-plan      define the behavior and split the task
/map-efficient implement the approved plan
/map-check
/map-review
/map-learn

That's the whole golden path.

• Start with /map-plan for anything non-trivial — it clarifies behavior and splits the work into contract-sized subtasks.
• Already scoped? Go straight to /map-efficient.
• Tiny edit? /map-plan off-ramps you to a direct edit or /map-fast instead of forcing full planning.
• Too foggy to plan? /map-wayfind resolves open design decisions one at a time on a durable map, then hands settled decisions to /map-plan.
• Want one entry point? /map-auto routes and drives the chain autonomously; hard-stops only on dangerous_action/safety_guardrail holds.

Codex CLI users invoke the same skills with $: $map-plan, $map-efficient, $map-check. See the Usage Guide.

Framework updates. Automatic stable updates are enabled by default. Normal MAP skills check at most once per project every 24 hours, apply eligible patch and minor releases, and ask before a major release after showing its official feature highlights. Rejecting a major offer is remembered per project for that exact version, so it is not offered again; any different patch, minor, or major version is offered normally. Use these project controls and provider-specific manual skills when needed:

mapify init . --no-auto-update   # persist updates.auto: false
mapify init . --auto-update      # re-enable automatic checks
/map-upgrade                     # Claude manual check/upgrade
$map-upgrade                     # Codex manual check/upgrade

Automatic failures stay silent so they do not block the requested workflow; manual checks report errors explicitly. The public mapify upgrade command is separate and unchanged: it upgrades only the CLI and does not refresh project files. See Automatic and manual framework updates.

Case Study: 90 days → 7 days

The DevOpsConf 2026 case study applies this process to a production Kubernetes Project Operator:

• human estimate: 90 days
• MAP-style delivery: 7 days
• workflow: SPEC → PLAN → TEST → CODE → REVIEW → LEARN
• small reviewable PRs instead of one giant generated diff
• tests before implementation for critical pieces
• semantic bugs caught in review before merge

DevOpsConf 2026 case study →

When To Use MAP

Core Commands

Detailed usage and options →

Why Engineers Stick With It

• Daily-driver speed — optimized for repeated use, not occasional demos. Structured enough to prevent chaos, lightweight enough to keep token and time cost under control.
• Reviewable diffs — /map-plan and /map-efficient require per-subtask size, concern, and constraint metadata, then validate blueprint.json before implementation, so oversized or mixed-concern plans fail early.
• Gates that check the plan, not vibes — /map-check and /map-review validate against the spec, tests, and diff instead of asking whether code "looks fine".
• Clean-room review — /map-review auto-bundles spec, plan, tests, verification, and coverage evidence into a single durable input (.map/<branch>/review-bundle.json); --detached opens a read-only worktree for inspection without touching your branch.
• Project memory — /map-learn turns hard-won fixes and gotchas into reusable context, so the next session doesn't relearn them.

• Calibrated workflow effort — each shipped slash skill declares a thinking_policy and parallel_tool_policy, so lightweight commands stay direct while planning, review, and release workflows reserve deeper reasoning and parallel fan-out for the stages that benefit.
• Mutation boundary constraints — write-capable Claude and Codex surfaces tell agents not to edit unrelated files, add or upgrade dependencies, or refactor neighboring code unless the current subtask requires it.
• Context-first prompt envelopes — high-context prompts wrap branch artifacts in XML-style <documents>, then state the <task> and <expected_output>, so specs, diffs, logs, and schemas stay separated for the model.
• Contract-sized subtasks — blueprints require expected_diff_size, concern_type, one_logical_step, hard_constraints, soft_constraints, and coverage_map. Hard constraints must be owned in coverage_map and cited in the owning subtask.
• Token budget and research ROI reports — Actor and review prompt builders append active-path budget decisions to .map/<branch>/token_budget.json, while token_accounting.json and /map-tokenreport separate research-agent/researcher cost from Actor/Monitor cost.
• Clean retry quarantine — after repeated Monitor rejection, write-capable workflows switch the next attempt into clean-retry mode using .map/<branch>/retry_quarantine.json instead of raw failed-session context.
• Run health report — workflows write .map/<branch>/run_health_report.json during closeout: terminal status, step progress, retry counters, artifact presence, hook-injection status, and advisory signals. CI can fail inconsistent closeouts with python3 .map/scripts/map_step_runner.py validate_run_health_report.
• Compact recovery surface — /map-resume keeps the active recovery flow short and moves low-frequency notes to resume-reference.md, so recovery after /clear or context exhaustion gives the next checkpoint action without loading the whole appendix.
• Skill IR audit — release checks lower shipped Claude and Codex SKILL.md files into a typed SkillIR, verify content hashes, catch unsupported frontmatter, reject missing supporting-file links, and block injection-like instructions before mapify init copies surfaces into user repos.

How It Works

MAP orchestrates specialized roles through slash commands and skills:

TaskDecomposer → breaks goals into subtasks
Actor