Library and agent integration
Maps are tools for agents to plan work, inspect dependencies, execute declared verification checks, and record results. MapForge exports an ESM TypeScript library alongside its CLI so agent hosts can expose these operations as tools without spawning shell commands. The current package is private; build from the repository and integrate through a local package or a package artifact in your own development environment.
Core operations
import {
listMaps,
inspectMap,
createMap,
updateMap,
statusMap,
testMap,
commitMap,
commitAndSyncMap,
} from '@mapforge/core'
const repository = '/absolute/project'
const maps = await listMaps(repository)
const current = await inspectMap(repository, 'api-release')
console.log(maps, current.head, current.map.fingerprint)
| Export | Purpose |
|---|---|
parseMap |
Parse and validate Map documents |
listMaps, inspectMap |
Discover and inspect Maps |
createMap, updateMap |
Create and update managed planning documents |
statusMap |
Inspect work and cached sync state |
testMap |
Execute declared checks and record evidence |
commitMap |
Commit a selected Map locally |
commitAndSyncMap |
Commit and verify publication to GitHub |
Use the generated declarations in dist/ and source types for exact request and result interfaces.
Preconditions are part of the API
await updateMap(repository, {
id: current.map.id,
expectedHead: current.head,
expectedFingerprint: current.map.fingerprint,
files: {
'map.md': '# Release the API\n\nUpdated scope and acceptance criteria.\n',
},
})
The writer validates repository identity, planning history, paths, graph invariants, and preconditions. Conflicts require reconciliation, rather than silently refreshing the expected tokens.
Load the agent catalog
import { loadSkillCatalog } from '@mapforge/core/skills'
const catalog = await loadSkillCatalog()
console.log(catalog.version, catalog.commands)
// catalog.files contains canonical command and reference text.
Hosts own provider registration, instruction injection, and user interface. The catalog supplies the workflow instructions, and the library enforces supported operations. MapForge has no dependency on BuildOS, Electron, or React.
Preserve execution boundaries
Reading a Map does not run scripts. Updating a Map does not publish it. Test commands run in the implementation checkout and receive MAP_ROOT and MAP_SOURCE_ROOT; planning documents remain in the managed worktree. Publication requires a separate, explicitly requested operation.