map-project

Map a Project

Create a compact authority map that lets another agent orient itself without rediscovering the repository. Keep current state in the project map, durable atomic knowledge in memory, long-form material in RAG, and work chronology in session logs.

1. Resolve the canonical project

1. Call project_list; reuse the canonical name when the repo is already represented.
2. Call project_get(name) before changing an existing map. Treat list fields such as modules, decisions, and next_steps as full replacements.
3. Use one project map for one product/system even when it has several working-tree paths. Record private/public/OS paths in paths; do not create duplicate project maps for repository aliases.
4. Do not model people, professional profiles, machines, learning collections, clients, or environments as projects. Use profile_get/profile_update, machine tools, global memory, or the learning RAG namespace instead.

2. Gather evidence before writing

Inspect the current worktree and verify:

• repository remote, branch, dirty state, package manifests, lockfiles, and runtime requirements;
• AGENTS.md/CLAUDE.md, README, ADRs, operations docs, and deployment configuration;
• actual entry points, module boundaries, dependency direction, persistence/sync paths, and external services;
• commands by running the relevant help/build/test command where safe;
• current focus from live task/issue/runtime evidence, not from code shape alone.

For serious architecture work, call prompt_get("senior-software-architect") before mapping. State unknowns explicitly; never invent ownership, runtime proof, or completion status.

3. Write the project map

Call project_update with the fields that evidence supports:

• summary: one paragraph describing the product and its users.
• status: active, paused, done, or idea based on current evidence.
• stack: only technologies actually used.
• repo and paths: canonical remote plus known checkout/deployment aliases.
• current_focus: the single active outcome, not a history dump.
• next_steps: concrete, ordered, verifiable actions.
• architecture: 3–5 sentences covering layers, data flow, authority, and boundaries.
• modules: the complete module list. For each module provide name, repo-relative path, one-sentence purpose, key_files, and depends_on using other module names.
• entry_points: role to repo-relative file mappings.
• commands: named commands that were verified or are directly authoritative from manifests.
• conventions: non-obvious written invariants; omit generic coding advice.
• data_model: main entities/tables, ownership, lifecycle, and important relations.
• notes: risks, operational constraints, and unresolved gaps that do not fit elsewhere.