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

Requires Python 3.11+, and python3 on your PATH must be that interpreter — the installed hooks and .map/scripts/ runners execute through a #!/usr/bin/env python3 shebang, not through the interpreter that ran mapify. mapify init checks it up front and tells you what to fix (details).

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

The generated .codex/config.toml enables hooks. On first use, review and trust the project hook configuration when Codex prompts you; /hooks shows the eight installed lifecycle event groups.

3. Run the loop

Claude Code:

/map-plan → /map-efficient → /map-check → /map-review → /map-learn

Codex CLI:

$map-plan → $map-efficient → $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.
• Starting from a PRD? Run /map-prd-review directly, or accept /map-plan's optional readiness preflight. A non-ready result shows the gaps and asks whether to revise or continue planning anyway.
• 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 on a durable map. Evidence-first research is on by default: factual lookups stay light; uncertain decisions get independent investigations and targeted checks, with four attempts before asking to extend the budget. Research handoffs are checked before /map-plan; historical decisions retain explicit legacy provenance.
• Want one entry point? /map-auto routes and drives the chain autonomously; hard-stops only on dangerous_action/safety_guardrail holds.

Codex CLI ships the same 23 MAP skill entry points and invokes them with $: $map-plan, $map-efficient, $map-check, and so on. 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: