Get started with MapForge
Maps are planning tools that agents can use. Each Map gives an agent a structured outcome, stable steps, explicit dependencies, acceptance criteria, and checks it can execute. People can review the same plan and its recorded evidence in Git.
MapForge provides the Node.js library, CLI, and skill catalog that agents and their hosts use to inspect and update those plans.
Build from source
The current package is private and version 0.1.0. Use a local checkout; a public npm release is not required for this walkthrough. You need Node.js 22.22 or newer, npm, and Git.
git clone https://github.com/BillingsTechnology/MapForge.git
cd MapForge
npm ci
npm run build
node dist/cli.js --help
Run the following from the MapForge checkout. Replace /absolute/project with the root of an existing Git implementation repository. Keep using the absolute path to this CLI if you change directories.
Create your first Map
node dist/cli.js create /absolute/project api-release "Release the API"
node dist/cli.js show /absolute/project api-release
node dist/cli.js status /absolute/project api-release
Creation establishes an independent planning history in a managed worktree on map/api-release. The development checkout and its staging index stay separate. The returned workspace identifies the planning location; head is the planning HEAD.
Define work and checks
Use show to read the current documents, planning HEAD, and fingerprint. Prepare an update request with complete replacement file contents, then run:
node dist/cli.js update /absolute/project /absolute/request.json
node dist/cli.js validate /absolute/project api-release
A request contains id, expectedHead, expectedFingerprint, and a files object. Add each step's Markdown document and YAML entry together. See Map format for the schema and request example.
Define checks before implementation. Dependencies control which steps are ready; groups organize the outline. A step with multiple prerequisites waits for all of them.
Execute checks and review evidence
node dist/cli.js test /absolute/project api-release
node dist/cli.js status /absolute/project api-release
The agent explicitly invokes test execution; opening or updating a Map does not run its checks. Tests run the Map's declared checks in the implementation checkout and record evidence through the updater. Review commands before execution. Passing checks do not automatically mark steps done. Checks, evidence, and completion have separate meanings; evidence must be reviewed again after relevant source or check changes.
Read Testing & validation for the full flow from declared checks to execution, recorded results, and completion review.
Work with an agent
The repository includes workflows for planning, implementation, updates, status, verification, and publication. Provider adapters live in .agents/ and .claude/; the canonical instructions live in skills/.
Agent workflow names and shell CLI operations differ. /map is an agent workflow; create is a CLI operation. Host applications own command registration and instruction injection.
Publish deliberately
Local authoring does not publish a Map. The CLI's commit operation takes an explicit request and commits and syncs only the selected map/<id> branch to a verified GitHub remote. Read the publication workflow before using it.