mapify-cli 3.34.0

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.

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-review --base-ref runtime (Codex: $map-review --base-ref runtime) to review only the child branch's changes against its parent's merge-base, including dirty work. Trusted review policy still comes from the default branch.

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 available spec, plan, tests, verification, and coverage evidence into a single durable input (.map/<branch>/review-bundle.json); standalone external-PR review needs no Actor blueprint. --detached opens a read-only worktree for inspection without touching your branch.
• Bounded review/fix cycles — /map-review retains round history and unresolved findings across restarts, suppresses acknowledged repeat publications, and stops after three unsuccessful attempts for reconsideration—not approval. Explicit abandonment recovers stale pending rounds without resetting that budget. Incremental re-review falls back to full review when baseline or dependency coverage is uncertain.
• Snapshot-bound review receipts — review completeness, code approval, runner-executed checks and human consent are separate records. Missing reviewers, scope gaps or stale evidence cannot approve a changed snapshot. Read-only reviewers receive base/current source and attribution in the bundle; Codex findings remain available with explicit INCOMPLETE status until capability enforcement is verified.
• Trusted review policy (shadow rollout) — root and applicable ancestor REVIEW.md guidance comes from pinned default-branch Git objects, not proposed head content. Its hash joins the existing runtime/capability fingerprint; unknown authority prevents approval. New security/consent gates default to shadow: record diagnostics and pending snapshot/policy/action-bound holds without new blockers or weakening existing checks. Opt into strict with review: {security_gates: strict} in trusted-default .map/config.yaml; sensitive/unknown changes then require full coverage and independent security receipts regardless of auto/quick or disabled ledger enforcement. Human provenance is not yet verifiable: holds never become consent, and strict review-ready stays blocked. Corpus and evaluated promotion remain later #523 stages.
• Evidence-backed findings — the existing Step A.3 separates confirmed defects, refuted claims and insufficient evidence. Validation checks the failure scenario, reachability and baseline; remediation searches a bounded scope for the same bug class. Adversarial agreement requires independent evidence-backed validations, not votes. Author reactions cannot close findings on their own.
• Project memory — /map-learn turns hard-won fixes and gotchas into reusable context, so the next session doesn't relearn them. Automatic session memory also records bounded, redacted prompt topics and conservative tool observations, even outside a MAP workflow; observed references are not proof of successful outcomes. See session memory for limits and recovery behavior.

How It Works

MAP orchestrates specialized roles through slash commands and skills:

TaskDecomposer → breaks goals into subtasks
Actor          → implements scoped tasks
Monitor        → validates quality and blocks invalid output
Predictor      → analyzes impact for risky changes
Learner        → captures reusable project memory

For Claude Code, MAP slash surfaces live in .claude/skills/map-*/SKILL.md files created by mapify init. For Codex CLI, mapify init . --provider codex creates the matching 23 .agents/skills/ entries, nine .codex/agents/*.toml roles, eight lifecycle event groups under .codex/hooks.json, and the same shared .map/scripts/ runtime. The only provider-specific UI exception is Claude's command-driven dynamic status-line renderer. Codex supports project-level [tui].status_line, but only as an ordered list of built-in item identifiers, so MAP does not install the Claude renderer there.

MAP is inspired by the MAP cognitive architecture (Nature Communications, 2025), which reported a 74% improvement on planning tasks. The CLI turns that idea into a practical software-development workflow.

Architecture deep-dive →

What Success Looks Like

After a good first workflow, you should see:

• a written plan or spec before implementation starts;
• small implementation contracts instead of one giant AI diff;
• verification and review artifacts under .map/<branch>/, including runner-executed acceptance proofs rather than self-reported AC checkboxes;
• review comments focused on correctness and semantics, not formatting noise;
• /map-learn preserving project rules, gotchas, and handoffs for future sessions.

MAP review is useful, but it is not a replacement for engineering judgment. Serious changes still need human review. The goal is to make that review smaller, earlier, and better grounded.

Options

# .map/config.yaml
minimality: lite   # default for ALL projects; set 'off' to opt out

mapify init . --compression never                 # default — no nudge
mapify init . --compression auto                  # nudge at threshold
mapify init . --compression aggressive            # nudge at 0.4 x threshold
mapify init . --compression-threshold 250000      # Opus 1M / 50+ subtask plans

mapify init . --sofa            # opt-in: enable the map-so-search skill

mapify init . --autonomy        # auto-approve most tools; keep git commit/push for the human
mapify init . --no-autonomy     # remove the autonomy posture

Documentation

Trouble?

• Static analysis reports local: -n: invalid option on macOS → Update MAP and refresh your provider's installed project files (mapify init . --refresh-existing, adding --provider codex for Codex). The Go/mypy diagnostic parser supports system Bash 3.2; upgrading Bash is not required for this parser. Re-run analysis rather than trusting an earlier empty report.

• Command not found → Run mapify init in your project first.

• init stops on a Python version → python3 on your PATH is older than 3.11; the hooks run under it. Install 3.11+ (brew install python@3.12 / uv python install 3.12), then mapify check. To install anyway, pass --skip-python-check or set MAPIFY_SKIP_PYTHON_CHECK=1 — hooks stay non-functional until python3 is upgraded (details).

• A hook printed "MAP requires Python 3.11 or newer" → same cause, detected at run time; the message names the interpreter it ran under. Context hooks report and let the session continue; the two PreToolUse gates (safety-guardrails.py, workflow-gate.py) deny the tool call instead of allowing it unguarded, so fix python3 in another terminal to unblock.

• Agent errors → Check .claude/agents/ has all shipped agent .md files, or run mapify doctor.

• Poor output on a complex task → Start with /map-plan and feed /map-efficient the approved plan instead of asking it to infer the architecture.

• More help →

Contributing

Improvements welcome: prompts for specific languages, new agents, provider integrations, and CI/CD workflow support.

License

MIT

Start with /map-plan. Keep the model inside your engineering process, not the other way around.