Make the outcome concrete.
Give the agent a clear goal, stable step IDs, and acceptance criteria before implementation begins.
Plan a Map ↗Planning tools that agents can use
Maps are tools for agents: structured, Git-native plans they can read, update, and use to guide work. Give your agent explicit dependencies, executable checks, and acceptance criteria you can review together.
Node.js + TypeScript · CLI + library + agent skills
Read the plan. Find ready work. Verify results.
The schema is complete. An agent can work on authentication and verify it against the declared acceptance criteria.
FROM INTENT TO EVIDENCE
A Map gives an agent the context to choose ready work, follow dependencies, and check results. People define the outcome and review progress in the same plan.
Give the agent a clear goal, stable step IDs, and acceptance criteria before implementation begins.
Plan a Map ↗Let the agent inspect which steps are ready and which are blocked. Each step waits for all its prerequisites.
Explore the format ↗Have the agent run declared checks against the implementation and record the tested revision. Review that evidence before marking a step done.
See verification ↗TESTING, VALIDATION & EXECUTION
Testing belongs in the plan from the start. Each step can declare the checks an agent should run and the criteria a person should review.
MapForge validates the plan’s structure. The agent explicitly invokes test execution against the implementation, then uses the recorded results to assess completion.
Explore testing & validation ↗Attach test commands and acceptance criteria to steps before implementation. Use unit tests, integration checks, or project-specific validation scripts.
Check the graph, required documents, and completion evidence. Invalid references, dependency cycles, and unmet prerequisites stop invalid plan updates.
The agent calls mapforge test to run declared checks in the implementation checkout. Blocked steps are skipped; each check has a two-minute timeout.
Keep passes, failures, and the tested revision with the plan. Passing checks leave completion for review; failed reruns reset affected steps and dependent completion. Revalidate after relevant changes.
See the execution and evidence workflow ↗GIT-NATIVE, BY DESIGN
Maps live on their own map/<id> branches in managed planning worktrees. Keep developing in your checkout while the plan keeps its own history.
maps/api-release/
├── map.md the outcome
├── map.yaml the graph
├── steps/
│ ├── schema/step.md
│ ├── auth/step.md
│ └── verify/
│ ├── step.md
│ └── verify.sh the check
└── operations/ the receiptsReadable files. Explicit updates. Reviewable history.
ONE PLANNING SYSTEM. THREE WAYS IN.
Give agents and scripts a JSON-speaking CLI to inspect plans, update steps, and run verification.
CLI reference ↗Expose Map operations as tools in your agent host through the TypeScript library.
Library & integrations ↗Load workflows that guide an agent through planning, updates, status, verification, and explicitly requested publication.
Agent workflows ↗START SMALL. BUILD WITH DIRECTION.
Build from source and give your agent a plan it can inspect, update, and verify.
Read the getting started guide ↗git clone https://github.com/BillingsTechnology/MapForge.git
cd MapForge
npm ci
npm run build
node dist/cli.js --helpv0.1.0 · In active development · Build locally today