Metadata-Version: 2.5
Name: mapify-cli
Version: 3.34.0
Summary: MAP Framework installer - Modular Agentic Planner for Claude Code
Project-URL: Homepage, https://github.com/azalio/map-framework
Project-URL: Repository, https://github.com/azalio/map-framework.git
Project-URL: Issues, https://github.com/azalio/map-framework/issues
Author: MAP Framework Contributors
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx>=0.25.0
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: readchar>=4.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
Requires-Dist: jsonschema>=4.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pyright>=1.1.400; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.26.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.1.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: truststore>=0.9.0; extra == 'dev'
Provides-Extra: ssl
Requires-Dist: truststore>=0.9.0; extra == 'ssl'
Provides-Extra: test
Requires-Dist: hypothesis>=6.0.0; extra == 'test'
Requires-Dist: jsonschema>=4.0.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.26.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.1.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: pyyaml>=6.0.0; extra == 'test'
Description-Content-Type: text/markdown

<p align="center">
  <img src="./assets/readme/hero.svg" width="100%" alt="MAP Framework — Plan-then-build AI coding. You approve the plan before the model writes a line of code.">
</p>

<p align="center">
  <a href="https://pypi.org/project/mapify-cli/"><img src="https://badge.fury.io/py/mapify-cli.svg" alt="PyPI version"></a>
  <img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"></a>
  <a href="https://github.com/azalio/map-framework"><img src="https://img.shields.io/github/stars/azalio/map-framework?style=social" alt="GitHub stars"></a>
</p>

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.

<p align="center">
  <img src="./assets/readme/loop.svg" width="100%" alt="Without MAP: idea, prompt, code, hope. With MAP: SPEC, PLAN, TEST, CODE, REVIEW, LEARN — a closed loop.">
</p>

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](docs/USAGE.md#skill-description-optimization)).

## Quick Start

<p align="center">
  <img src="./assets/readme/section-quickstart.svg" width="100%" alt="Quick Start — install, init, run the loop">
</p>

**1. Install**

```bash
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](docs/INSTALL.md#why-python3-on-path-matters)).
For Go projects requiring build tags, set `checks.go.tags: integration,netgo` in
`.map/config.yaml` for the Stop hook's build check ([configuration](docs/USAGE.md#end-of-turnsh-stop)).

**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](docs/USAGE.md#cross-ai-peer-review---cross-ai-runtime)).
An [offline historical review corpus](docs/USAGE.md#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](docs/USAGE.md#bounded-subscription-review-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:

```bash
cd your-project
mapify init
claude
```

Codex CLI:

```bash
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:

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

Codex CLI:

```text
$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](docs/USAGE.md#reorder-pending-subtasks)
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](docs/USAGE.md#codex-cli-provider).

**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:

```text
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](docs/USAGE.md#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 →](https://github.com/azalio/devopsconf-ai-develop)

## When To Use MAP

| Good fits | Poor fits |
|-----------|-----------|
| Complex backend features | Typos and tiny edits |
| Kubernetes controllers and operators | Small one-off scripts |
| Internal platform tooling | Product ideas where behavior is still unknown |
| API, CRD, or domain-model changes with invariants | Broad rewrites without clear boundaries |
| Refactoring with a meaningful test harness | Tasks cheaper to do directly than to plan |

## Core Commands

| Command | Use For |
|---------|---------|
| `/map-auto` | Single-entry autonomous autopilot: routes a task through existing MAP workflows and drives the chain to a committed branch |
| `/map-plan` | **Start here** for non-trivial work; clarify behavior and decompose tasks |
| `/map-prd-review` | Review a PRD with a 0-10 readiness score, strengths, risks, and uncovered edge cases |
| `/map-wayfind` | Too foggy to plan? Resolve design decisions on a durable map *before* `/map-plan` |
| `/map-efficient` | **Implement** an approved plan or already-scoped task |
| `/map-fast` | Small, low-risk changes where full planning is overhead |
| `/map-check` | Quality gates, verification, and artifact checks |
| `/map-review` | Pre-commit semantic review against the plan, tests, and diff |
| `/map-learn` | Capture project memory and reusable lessons |
| `/map-understand` | Interactive teaching and quiz mode for code, diffs, and workflow results |
| `/map-debug` | Bug fixes and debugging |
| `/map-task` | Execute a single subtask from an existing plan |
| `/map-tdd` | Test-first implementation workflow |
| `/map-release` | Package release workflow; Codex `$map-release` shares the same commit-bound CI gates |
| `/map-resume` | Resume interrupted workflows |

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 →](docs/USAGE.md)

## 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](docs/USAGE.md#session-memory) for limits and recovery behavior.

<details>
<summary><b>More under the hood</b> — calibrated effort, mutation boundaries, token budgets, retry quarantine, run-health diagnostics, skill IR audit</summary>

- **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. With `worktree.isolation: off`, Actor write checks inspect main even when a recovery worktree remains on disk.
- **Live isolation dispatch gate** — before concurrent Actor fan-out, `auto` isolation falls back to sequential on dirty or unsupported checkouts; `required` isolation stops dispatch instead. Wave guidance forwards the live decision and warning.
- **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`. All runner subcommands support read-only `--help` / `-h`; for example, `python3 .map/scripts/map_step_runner.py write_run_health_report --help`.
- **Lossless serial blocker repair** — standalone repositories and linked Git worktrees are supported; independently approved repairs run in a private checkout with their own Monitor and full gate, preserving the paused task's phase, results, retries and dirty files. Concurrent waves and overlapping repair paths fail closed; see [the repair protocol](docs/USAGE.md#independent-serial-blocker-repair).
- **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.

</details>

## How It Works

MAP orchestrates specialized roles through slash commands and skills:

```text
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](https://github.com/Shanka123/MAP) (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 →](docs/ARCHITECTURE.md)

## 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

<details>
<summary>Minimality doctrine, context-compression policy, SOFA, and other init flags</summary>

**Minimality doctrine** (controls how strongly MAP pushes Actor/Monitor/Evaluator toward the smallest sufficient safe change):

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

Allowed values: `off`, `lite`, `full`, `ultra`. The global default is `lite`. `lite` is conservative: Actor prefers the fewest moving parts, Monitor blocks scope drift only when it affects required behavior, and Evaluator scores simplicity without letting it hide missing required work. `/map-review` also adds an advisory what-to-delete lens when minimality is not `off`; its `net: -N` estimate is informational, not a gate. In `full`/`ultra`, the decomposer may place speculative omissions in `blueprint.deferred_yagni`; those items must be shown during plan approval and can be restored with `python3 .map/scripts/map_orchestrator.py restore_deferred_yagni YG-NNN`. Maintainers can inspect local rollout telemetry with `mapify minimality-report --json`.

**Context-compression policy** (controls the `/compact` nudge; default `never` — opt-in):

```bash
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
```

Actor and reviewer prompts always carry the full bundled context — context-block truncation was removed. When a policy other than `never` is active, MAP offloads large tool outputs to `.map/<branch>/compacted/` before `/compact` drops them, so a dropped output is re-read from its sidecar instead of re-running broad discovery (these sidecars can hold secrets — they are `0o600` and self-ignored from git; never push `.map/`). See [docs/USAGE.md#context-budget-policy](docs/USAGE.md).

**Stack Overflow for Agents (SOFA)** read-only prior-art search — **off by default**, no network or credentials unless you enable it:

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

This writes `sofa.enabled: true` to `.map/config.yaml` and adds `.sofa/` to your `.gitignore`. Without the flag, no SOFA code path runs. See the [SOFA usage guide](docs/USAGE.md#stack-overflow-for-agents-sofa).

**Autonomy posture** (`--autonomy`, claude provider) — **off by default**, opt-in "YOLO-minus-git":

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

`--autonomy` writes a broad auto-approve allowlist plus a `git commit`/`push` deny into the **per-user, gitignored** `.claude/settings.local.json` (the committed team `.claude/settings.json` stays the secure baseline). The git block is enforced by the `safety-guardrails.py` PreToolUse hook. Omit the flag to leave existing local settings untouched on re-init. See the [autonomy usage guide](docs/USAGE.md#autonomy-posture-yolo-minus-git).

</details>

## Documentation

| Guide | Description |
|-------|-------------|
| [Installation](docs/INSTALL.md) | All install methods, PATH setup, troubleshooting |
| [Usage Guide](docs/USAGE.md) | Workflows, examples, cost optimization, playbook |
| [Prompt Library](docs/PROMPT_LIBRARY.md) | Copyable prompt recipes by SDLC phase and role |
| [Architecture](docs/ARCHITECTURE.md) | Agents, MCP integration, customization |
| [Platform Spec](docs/MAP_PLATFORM_SPEC.md) | Platform refactor roadmap, codebase analysis |

## 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](docs/INSTALL.md#why-python3-on-path-matters)).
- **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 →](docs/INSTALL.md#troubleshooting)

## 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.
