-> **Plan-then-build AI coding for Claude Code & Codex CLI.** `/map-plan` decomposes your task into small, reviewable subtasks you approve *before* any code is written; `/map-efficient` implements the approved plan, subtask by subtask. The AI still writes the code — you keep the architecture, scope, and review.
+
+
+
+
+
+
-
-
-## The MAP loop
-
-Most AI agents rush straight to code before they understand the task — so you get fast wrong answers and silent rework. MAP inserts a plan you approve first, then implements it in reviewable steps:
+## Why MAP Exists
-```text
-idea -> prompt -> code -> hope # without MAP
-SPEC -> PLAN -> TEST -> CODE -> REVIEW -> LEARN # with MAP
-```
+Most AI agents rush straight to code — fast wrong answers, silent rework.
-You drive the whole loop with two core commands plus three gates:
+
+
+
-```text
-/map-plan "add rate limiting to the public API" # 1. PLAN — decompose the task; you approve before any code
-/map-efficient # 2. BUILD — implement the approved plan, subtask by subtask
-/map-check # 3. CHECK — quality gates against the plan
-/map-review # 4. REVIEW — semantic review vs spec, tests, and diff
-/map-learn # 5. LEARN — save the gotchas for next session
-/map-understand # optional - teach and quiz until the workflow makes sense
-```
+Common failure modes MAP eliminates:
-- **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 the open design decisions one at a time on a durable map, then hands the settled decisions to `/map-plan`.
+- 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.
-> Codex CLI users invoke the same skills with `$`: `$map-plan`, `$map-efficient`, `$map-check`. See the [Usage Guide](docs/USAGE.md#codex-cli-provider).
+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**
```bash
@@ -57,7 +54,7 @@ mapify init
claude
```
-Codex CLI is also supported:
+Codex CLI:
```bash
cd your-project
@@ -65,7 +62,7 @@ mapify init . --provider codex
codex
```
-Then enable the Codex hook manually: run `/hooks`, select `PreToolUse`, press `t` to toggle it on, then press `Esc`. If your Codex version does not support the `hooks` feature key yet, start it with `codex --enable codex_hooks` or upgrade Codex first (upgrading is recommended).
+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**
@@ -75,24 +72,29 @@ Then enable the Codex hook manually: run `/hooks`, select `PreToolUse`, press `t
/map-check
/map-review
/map-learn
-/map-understand # optional learning/quiz mode
```
-That's the whole golden path. Everything below explains *why* it works and *when* to reach for it.
+That's the whole golden path.
-## Why MAP Exists
+- **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`.
+
+> Codex CLI users invoke the same skills with `$`: `$map-plan`, `$map-efficient`, `$map-check`. See the [Usage Guide](docs/USAGE.md#codex-cli-provider).
-Ad-hoc prompting feels fast on simple tasks. On complex systems it creates a different problem: code appears quickly, but the engineering process disappears.
+## Case Study: 90 days → 7 days
-Common failure modes:
+The DevOpsConf 2026 case study applies this process to a production Kubernetes Project Operator:
-- 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.
+- 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
-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.
+[DevOpsConf 2026 case study →](https://github.com/azalio/devopsconf-ai-develop)
## When To Use MAP
@@ -100,43 +102,18 @@ MAP moves engineering judgment earlier: write down the behavior, split the work
|-----------|-----------|
| Complex backend features | Typos and tiny edits |
| Kubernetes controllers and operators | Small one-off scripts |
-| Internal platform tooling | Product ideas where the desired behavior is still unknown |
+| 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 |
-## 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//`;
-- 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.
-
-## Case Study: 90 days → 7 days
-
-The DevOpsConf 2026 case study applies this process to a production Kubernetes Project Operator, not a toy CRUD app:
-
-- 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)
-
## Core Commands
| Command | Use For |
|---------|---------|
| `/map-plan` | **Start here** for non-trivial work; clarify behavior and decompose tasks |
-| `/map-wayfind` | Too foggy to plan? Resolve open design decisions on a durable map *before* `/map-plan` |
+| `/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 would be overhead |
+| `/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 |
@@ -147,34 +124,26 @@ The DevOpsConf 2026 case study applies this process to a production Kubernetes P
| `/map-release` | Package release workflow |
| `/map-resume` | Resume interrupted workflows |
-[Detailed usage and options ->](docs/USAGE.md)
-
-Canonical MAP flows:
-
-- **Standard:** `/map-plan` -> `/map-efficient` -> `/map-check` -> `/map-review` -> `/map-learn`
-- **Full TDD:** `/map-plan` -> `/map-tdd` -> `/map-check` -> `/map-review` -> `/map-learn`
-- **Targeted subtask TDD:** `/map-plan` -> `/map-tdd ST-001` -> `/map-task ST-001` -> ... -> `/map-check` -> `/map-review` -> `/map-learn`
-
-These flows maintain branch-scoped artifacts under `.map//` — `blueprint.json` (subtask size/concern contracts), `code-review-001.md`, `verification-summary.md`, `pr-draft.md`, run dossiers, and more — so research, review lineage, and verification survive context resets.
+[Detailed usage and options →](docs/USAGE.md)
## Why Engineers Stick With It
-- **Daily-driver speed** — optimized for repeated use, not occasional demo workflows. 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 instead of surprising reviewers later.
+- **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//review-bundle.json`); `--detached` opens a read-only worktree for inspection without touching your branch. With `minimality` enabled, review also runs an advisory what-to-delete lens for over-engineering cuts.
+- **Clean-room review** — `/map-review` auto-bundles spec, plan, tests, verification, and coverage evidence into a single durable input (`.map//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.
-More under the hood (calibrated effort, mutation boundaries, token budgets, retry quarantine, run-health diagnostics, skill IR audit)
-
-- **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. Non-release prompts use targeted guardrails instead of blanket all-caps prohibition blocks, reducing over-triggered agents and tool calls while keeping true hard stops explicit.
-- **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. Broader scope is reported as a blocker or tradeoff instead of silently expanding the diff.
-- **Context-first prompt envelopes** — high-context `/map-plan`, `/map-efficient`, `/map-debug`, and `/map-review` prompts wrap branch artifacts in XML-style ``, then state the `` and ``, 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; soft constraints can be traded off only with explicit `tradeoff_rationale`.
-- **Token budget and research ROI reports** — Actor and review prompt builders append active-path budget decisions to `.map//token_budget.json`, while `token_accounting.json` and `/map-tokenreport` separate research-agent/researcher cost from Actor/Monitor cost so operators can see whether delegated research paid for itself.
-- **Clean retry quarantine** — after repeated Monitor rejection, write-capable workflows switch the next attempt into clean-retry mode using `.map//retry_quarantine.json` (constraints, required evidence, do-not-repeat feedback) instead of raw failed-session context.
-- **Run health report** — workflows write `.map//run_health_report.json` during closeout: terminal status, step progress, retry counters, artifact presence, hook-injection status, and advisory research artifact/ROI signals. CI can fail inconsistent closeouts with `python3 .map/scripts/map_step_runner.py validate_run_health_report`.
+More under the hood — calibrated effort, mutation boundaries, token budgets, retry quarantine, run-health diagnostics, skill IR audit
+
+- **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 ``, then state the `` and ``, 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//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//retry_quarantine.json` instead of raw failed-session context.
+- **Run health report** — workflows write `.map//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.
@@ -185,32 +154,44 @@ These flows maintain branch-scoped artifacts under `.map//` — `bluepri
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
+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 `.agents/skills/`, `.codex/agents/`, `.codex/config.toml`, hooks, and shared `.map/scripts/`.
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)
+[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//`;
+- 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
-Minimality doctrine, context-compression policy, Stack Overflow for Agents (SOFA), and other init flags
+Minimality doctrine, context-compression policy, SOFA, and other init flags
**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 incl. keyless configs (#183); set 'off' to opt out
+minimality: lite # default for ALL projects; set 'off' to opt out
```
-Allowed values: `off`, `lite`, `full`, `ultra`. The global default is `lite` (Phase 3 flip, #183 — keyless configs included; set `off` to opt out). `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 before execution with `python3 .map/scripts/map_orchestrator.py restore_deferred_yagni YG-NNN`. Maintainers can still inspect local rollout telemetry with `mapify minimality-report --json`, which compares complete `off` and opt-in run-health cohorts, reports sample gaps and cohort branch names, lists next telemetry actions, and emits a candidate-only `manual_review_gate` with opt-in branches plus a clarity/underscope checklist.
+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):
@@ -221,7 +202,7 @@ 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. If the conversation grows beyond your model's window, opt into `/compact` via `--compression auto` or trigger it manually. When a policy other than `never` is active, MAP also offloads large tool outputs (grep/test/file-read results) to `.map//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).
+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//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:
@@ -238,7 +219,7 @@ mapify init . --autonomy # auto-approve most tools; keep git commit/push
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) and gitignores that file. The git block is enforced by the `safety-guardrails.py` PreToolUse hook (the permission deny alone is bypassable under a broad `Bash(*)` allow). 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).
+`--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).
@@ -254,10 +235,10 @@ mapify init . --no-autonomy # remove the autonomy posture
## Trouble?
-- **Command not found** -> Run `mapify init` in your project first.
-- **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)
+- **Command not found** → Run `mapify init` in your project first.
+- **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
diff --git a/assets/readme/hero.svg b/assets/readme/hero.svg
new file mode 100644
index 00000000..40e9e1c4
--- /dev/null
+++ b/assets/readme/hero.svg
@@ -0,0 +1,86 @@
+
diff --git a/assets/readme/loop.svg b/assets/readme/loop.svg
new file mode 100644
index 00000000..a839d082
--- /dev/null
+++ b/assets/readme/loop.svg
@@ -0,0 +1,68 @@
+
diff --git a/assets/readme/section-quickstart.svg b/assets/readme/section-quickstart.svg
new file mode 100644
index 00000000..3da56f83
--- /dev/null
+++ b/assets/readme/section-quickstart.svg
@@ -0,0 +1,11 @@
+
+
+ 
+ 
+ 
+
+