Work on a Map
Use :map-start <map-id> [step-id], /map-start <map-id> [step-id], or $map-start <map-id> [step-id] through the host's MapForge skills. These are agent workflow entry points, not shell executables. There is no mapforge start CLI operation.
Read Working safely, Map format and operations, and the status, update, and test workflows as needed.
Invocation requests implementing the selected Map's in-scope work and running its declared checks. Respect narrower user instructions. It does not request a commit, push, merge, deployment, package publication, or execution of a separate migration plan. Creating or editing this skill is not an invocation to implement an example Map.
Select and inspect
Resolve the implementation repository root and one existing Map with the shared library/CLI. With no Map ID, list available Maps and ask which to work on; do not create a new Map or guess across repositories. Read its overview, graph, step documents, acceptance criteria, evidence, operation receipts, and work logs. Inspect repository guidance, source, staged and unstaged changes, and relevant running processes before implementation.
Use mapforge status <implementation-repo> <map-id> and mapforge show <implementation-repo> <map-id>, or node /absolute/MapForge/dist/cli.js in place of mapforge for a built source checkout. The returned workspace identifies the managed planning worktree. App changes belong in the implementation checkout; Map changes go through the shared updater. Never write Map documents directly or switch the development branch to the planning branch.
If a step ID is supplied, select only that executable step and stop after it; report unmet prerequisites rather than implementing them implicitly. Without a step ID, work through the Map's ready unfinished steps and continue as legitimate completion unlocks downstream work. Groups organize work and derive completion from children; do not assign them status or evidence. A completed Map needs a status report, not automatic reopening or rerunning of every check.
For an existing in_progress step, inspect its latest checkpoint and establish whether resuming it is appropriate. Status is not an exclusive claim or proof that another worker has stopped. Preserve another worker's changes; resolve ownership or overlapping source edits before taking over. Do not spawn other agents merely because the Map has parallel steps.
Record an attempt and implement
Before changing source, use map-update to set the selected ready step to in_progress and append an entry under ## Work log in its steps/<id>/step.md. Preserve the step's instructions, acceptance criteria, previous logs, and all evidence. Use current expectedHead and expectedFingerprint; every progress update must produce its normal operation receipt.
Use this lightweight record, adapting the detail to the work:
### <UTC timestamp> — Started / Resumed / Checkpoint / Blocked / Completed
Worker: <person or agent label; session ID if actually available>
Attempt: <generated UUID; retain it across this attempt's checkpoints>
Source: <implementation checkout and source HEAD>
Work: <what changed or was learned, with relevant paths>
Verification: <actual check outcome and evidence/receipt reference, or not run>
Blockers: <unresolved issue, or none>
Next: <concrete action for the next worker, or none>
Worker labels and attempt IDs aid handoff; they are not authenticated identities, ownership leases, or automatic agent/session tracking. If identity is unavailable, say so rather than inventing a session ID. Do not add unsupported fields to schema v1's map.yaml.
Implement the step within its agreed scope. Preserve unrelated edits and acceptance tests. Do not weaken checks or alter acceptance criteria to manufacture a pass. If a real contract ambiguity prevents progress, record it and seek the needed decision. Checkpoint at meaningful boundaries and before yielding; record enough context for another worker to resume without a full chat transcript. Keep secrets and raw terminal/session logs out of the Map.
Re-read and reconcile stale preconditions rather than blindly retrying with fresh tokens. The common-directory writer lock protects individual Map mutations; it does not reserve a step or coordinate source changes across clones or machines.
Verify and record completion
Run the selected step's declared checks through map-test:
mapforge test /absolute/implementation-repo <map-id> <step-id>
The runner executes checks against the implementation checkout and appends actual evidence, including the tested source revision/dirty digest and planning preconditions. Read the result and refresh the Map before the next update. A failed check is a failure to retain and address, not passing evidence to rewrite. Fix in-scope implementation problems and rerun when justified. If blocked, checkpoint the failure and next action instead of looping indefinitely or bypassing dependency gates.
Passing checks do not automatically mark the step done. Review all acceptance criteria and the latest required evidence, then use map-update to set done and append a completion entry summarizing changes and identifying the actual tested revision and evidence/receipt references. A step without automated checks needs real manual acceptance evidence identifying who reviewed what; if that review is unavailable, leave it unfinished. A work-log assertion alone is not verification evidence.
After relevant source or check changes, rerun affected verification and reset affected completion as needed. Schema v1 does not automatically invalidate evidence after arbitrary source changes. If changes affect a previously done prerequisite, reset that prerequisite and downstream completion together through the updater before continuing. Never leave a step done based on results for an earlier implementation.
On a pause or unresolved blocker, record the current situation, changed paths, verification state, and next action. Preserve honest status: use in_progress for started unfinished work, or todo if deliberately returning it to the queue. Neither paused nor blocked is a stored schema-v1 step status; dependency blocking is derived, and other blockers belong in the work log.
Handoff
Report completed, in-progress, ready, and blocked steps; implementation paths changed; actual checks and tested revisions; Map update receipts; and the next action or unresolved decision. If no work is ready, explain why rather than claiming success. Do not stage, commit, or push source or Map changes. Completing this workflow leaves reviewable local changes; publication remains a separate user-requested workflow.