Skip to content

README.md

Latest commit

 

History

History
202 lines (138 loc) · 8.25 KB

README.md

File metadata and controls

202 lines (138 loc) · 8.25 KB

MAP Framework

PyPI version Python 3.11+

A structured AI development workflow for engineers who need control, not just generated code.

MAP turns Claude Code and Codex CLI from ad-hoc coding assistants into a repeatable engineering loop with explicit artifacts, review points, and project memory.

Without MAP:

idea -> prompt -> code -> hope

With MAP:

SPEC -> PLAN -> TEST -> CODE -> REVIEW -> LEARN

AI already writes code quickly. MAP helps you keep the architecture, scope, tests, and review process under control while it does.

Why MAP Exists

Ad-hoc prompting feels fast on simple tasks. On complex systems, it often creates a different problem: code appears quickly, but the engineering process disappears.

Common failure modes:

  • 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 is a lightweight workflow for moving 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.

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 the desired 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

Quick Start

1. Install

uv tool install mapify-cli

# or with pip
pip install mapify-cli

2. Initialize your project

Claude Code is the default provider:

cd your-project
mapify init
claude

Codex CLI is also supported:

cd your-project
mapify init . --provider codex
codex

3. Use the golden path for serious work

When a task has unclear behavior, multiple files, or real review risk, run the full loop:

/map-plan define the behavior and split the task
/map-efficient implement the approved plan
/map-check
/map-review
/map-learn

Direct /map-efficient is for already-scoped tasks. If you are unsure, start with /map-plan.

Codex projects expose three MAP skills today: $map-plan, $map-fast, and $map-check. See the Usage Guide for provider details.

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>/;
  • 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.

Why Engineers Stick With It

  • Daily-driver speed - optimized for repeated use, not occasional demo workflows.
  • Low overhead - structured enough to prevent chaos, lightweight enough to keep token and time cost under control.
  • Reviewable diffs - planning and task contracts keep changes small enough to inspect.
  • Useful quality gates - /map-check and /map-review validate against the plan instead of just asking whether code "looks fine".
  • Project memory - /map-learn turns hard-won fixes and gotchas into reusable context for the next session.

Core Commands

Command Use For
/map-plan Start here for non-trivial work; clarify behavior and decompose tasks
/map-efficient Implement an approved plan or already-scoped task
/map-fast Small, low-risk changes where full planning would be 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-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
/map-resume Resume interrupted workflows

Detailed usage and options ->

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

/map-plan records a workflow-fit decision first, so trivial work can exit early with a direct edit or /map-fast recommendation instead of forcing full MAP planning.

These workflows maintain branch-scoped artifacts like code-review-001.md, qa-001.md, verification-summary.md, pr-draft.md, artifact_manifest.json, and run dossiers under .map/<branch>/. Targeted TDD flows also persist test_contract_ST-00N.md and test_handoff_ST-00N.json so /map-task can resume implementation from a clean red-phase handoff.

LEARN is the memory step of the MAP cycle. After implementation, checks, or review, MAP writes a learning handoff under .map/<branch>/ so /map-learn can run later without reconstructing context. Pass /map-learn [workflow-summary] when you want to provide an explicit summary.

Case Study

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

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, the orchestration lives in .claude/commands/map-*.md prompts created by mapify init.

For Codex CLI, mapify init . --provider codex creates .codex/skills/, .codex/agents/, .codex/config.toml, hooks, and shared .map/scripts/.

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

Architecture deep-dive ->

Documentation

Guide Description
Installation All install methods, PATH setup, troubleshooting
Usage Guide Workflows, examples, cost optimization, playbook
Architecture Agents, MCP integration, customization
Platform Spec Platform refactor roadmap, codebase analysis

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

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.