Documentation / Agent workflows

Map

Read Working safely, repository guidance, and Map format and operations. Maps are tracked under maps/<id>/ in a managed planning worktree on map/<id>, with independent history. Pass the development repository root to the helper; it resolves the worktree. Never write Maps into the development checkout or create/switch branches manually.

Use /map [id] [intent] (Claude) or $map (Codex). These invoke this agent workflow; they are not shell executables.

  • Inspect existing maps and relevant source before proposing changes. With no ID or intent, list maps and ask which outcome to plan.
  • For a new Map, clarify consequential ambiguities, describe the intended outcome, split executable work into stable step IDs, and define checks before implementation. Use groups for outcomes composed of children; dependencies belong to executable steps. Multiple prerequisites use AND semantics.
  • A folder is storage, not a dependency. Keep step folders flat; use parent for grouping and depends_on for execution order. Define acceptance criteria in each step's Markdown.
  • Use the shared Map service/CLI described in the reference to create a map. Refine it with /map-update; never silently commit, push, run declared checks, or execute the planned implementation just because the user asks for a map.
  • Report the resulting paths, ready/blocked steps, verification approach, operation receipt, and unresolved decisions.

To implement an existing Map, use /map-start <id> [step-id]. For progress/sync inspection use /map-status. For a deterministic local mutation use /map-update. Only /map-commit requests committing and publishing a Map to GitHub.