map-framework

After mapify upgrade, Claude can invoke any MAP skill through the Skill tool on your behalf except /map-release, which remains manual-only. Workflow confirmation gates still apply; /map-upgrade requires explicit consent for a major version.

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.

Skill maintainers can use mapify skill-eval optimize <skill> --provider claude|codex --apply to update only the selected provider's description in the shared template source; the opposite provider stays unchanged (details).

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). For Go projects requiring build tags, set checks.go.tags: integration,netgo in .map/config.yaml for the Stop hook's build check (configuration).

2. Initialize your project

Claude Code is the default provider. Cross-AI review compares explicit host and reviewer adapter vendors; same-vendor or unknown provenance is not labeled independent (details). An offline historical review corpus provides pinned introducing diffs, adjudicator-only labels and audited controls. It starts no reviewers and makes no evaluation or policy-promotion claims. An opt-in bounded subscription pilot adds offline preparation/reporting and a separately acknowledged, at-most-six-call Claude CLI runner. Its v2 inputs are complete allowlisted -U30 diffs; prompts estimated above 60,000 tokens are excluded, never truncated. Results require manual adjudication; historical v1 runs cannot be resumed. A paired offline evaluator measures precision/recall before and after verification, including real defects lost when dismissing findings.

Claude Code:

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.

Need to reorder unstarted work in an active run? Use the audited resequence_pending command without resetting the current step, retries, results or baselines.

• 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 no default attempt cap for authorized read-only work. Opt in at task start with configure_research --budget-limit N; existing caps remain binding and extensions require scoped user approval. Consequential or genuinely expensive actions still need separate consent. Stale open-ticket evidence can be explicitly refreshed without erasing history or resetting that 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:

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.

If a legacy map-debug skill cannot load its ../../references/ documents, refresh the project after upgrading the CLI: mapify init . --force --no-git --provider codex --refresh-existing (use --provider claude for Claude). This restores missing managed references; upgrading the CLI alone does not.

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

For stacked PRs, use `/map-revie