MapCmd

See the structure. See the value. Get the next move, with reasons.

MapCmd turns a multi-component product into a YAML map (status, value, dependencies) and answers next, gaps, impact, and why. Scoring is deterministic: value x incompleteness x dependents. Every next includes a counter-argument.

Not a diagram tool. Not Jira. Not an agent OS.

Adjacent categories (LikeC4, Backstage, Wardley, ADRs, radars, RICE CLIs) and what we copy vs refuse: docs/FEATURE-CLARITY.md.

How to write an honest map (evidence: known|inferred): docs/AUTHORING.md.

Results (synthetic Atlas map)

Question	Before (typical)	After (mapcmd)
What should we build next?	Portal polish, notifications	policy-engine
Why?	Opinion	Critical, 35% complete, 3 direct dependents
What could be wrong?	Unstated	evidence-collector is the other bottleneck
Time to a shared next	Meeting	One command

Numbers are from the bundled Atlas example. Label: synthetic.

Quick start

python -m pip install -e .
python -m mapcmd next --map examples/atlas-compliance.map.yaml

Cold path under a minute after Python is available. No API key.

Commands

Command	Job
mapcmd validate	Ids, deps, status range
mapcmd status	Counts, avg completeness, top gap
mapcmd list / show <id>	Inventory
mapcmd next	What to build (unlocks others). 0-dep / outcome holes print as GAP (not next)
mapcmd gaps	High-value incomplete
mapcmd impact <id>	Upstream / downstream
mapcmd why <id>	Transparent formula for one node

--format json for agents. --map path to point at a file (default: ./map.yaml or bundled Atlas).

The Atlas use case

Read docs/CASE_STUDY.md. Short version: a compliance platform keeps polishing the client portal. The map says the first bottleneck is the policy engine, with evidence-collector as the honest challenge.

What this repo is / is not

Public (this repo)	Private (not here)
YAML model + deterministic CLI	Agent harness / loop runtime
Atlas synthetic map + case	Real client maps
Reasons you can read	Production eval gates

See docs/PUBLIC-PRIVATE.md.

Formula

score = value_num * value_weight * (1 - status) * status_weight
        * (1 + n_dependents * dependency_weight)

critical=1.0 high=0.75 medium=0.5 low=0.25. Weights live on the map (scoring:).

Limitations

• The map is only as honest as the humans who typed status and value. It does not scan your git repo.
• This is not Wardley (no evolution axis) and not LikeC4 (no architecture views).
• Loop names (sense / prioritize / challenge / decide) are a later private layer. Public next already includes one challenge line.

License

MIT. See LICENSE.