/projectatlas

name: projectatlas
description: Use ProjectAtlas before broad source reads, preferring the installed short atlas CLI for an exact checkout and MCP for registered worktree routing, compact session briefs, or federated graph evidence.

ProjectAtlas

Goal

For an exact local checkout, prefer the installed, version-matched short `atlas` CLI:

`atlas next <task> -> atlas summary <file> or atlas symbols relations/search -> atlas slice <file> --start-line <n> --end-line <m>`

`atlas` is the installer-managed forwarder to the same native command surface as `projectatlas`, not a second index. Use `projectatlas` to inspect the native runtime directly or when the short forwarder is unavailable. Use MCP when its per-call registered-worktree routing, compact session brief/typed continuation, or cross-worktree federation is needed. [Short CLI command routing](references/short-cli.md) lists every public command family, its function, and when to call it; read it when selecting a CLI command.

ProjectAtlas is an agent orientation layer. It combines reviewed folder/file responsibility, current source summaries, parser trust, and bounded graph connections so agents select the right source before opening it. TOON is the default agent format; current saved bytes are authoritative, including dirty and non-Git trees.

Task Startup

At startup and after compaction, read this complete installed skill before Atlas calls. Every agent restores its exact selected project/worktree from its own live checkout, not another agent's remembered database binding. A hook reminder does not prove the skill was read. On Windows, the packaged automatic hook requires PowerShell; if Codex launches it through CMD, hooks are disabled or untrusted, or a resumed subagent has no fresh reminder after compaction, follow this recovery step manually before Atlas use.

1. Select the exact checkout. On first use there, run `atlas init` only if project-local state is absent; if an MCP read returns `init_required`, use its exact `atlas_init` next call. For a registered worktree that needs safe control-atlas hydration, use `atlas_init(worktree: "<alias>")`. Never choose a database filename or reuse another root's writable state. Every project root owns its own `.projectatlas/projectatlas.db`, config, generated host configs, and exact index. Do not substitute scan, symbol build, or hand-written MCP config for init. 2. For ordinary single-checkout work, run `atlas` from that checkout. For registered-worktree MCP use, keep the control checkout selected and pass `worktree` on each root-scoped call; for an unregistered root pass `project_path`. Use `atlas_set_project_path` only as a single-client process default. Never send both selectors. 3. Refresh only when needed: `atlas watch --once` for ordinary changed files, or `atlas_watch_once` on an MCP-routed worktree. Use `atlas scan` / `atlas_scan` only when an initialized project has no published index or typed guidance requires a full refresh. Never scan merely because a session started. 4. For a local CLI task, call `atlas next <task query>` once, follow its ranked file/folder recommendation, then use a bounded `atlas summary`, `atlas search`, or `atlas symbols relations` as needed. Use `atlas overview` and `atlas folders` before `atlas files` when broad structure is the question or `next` has no actionable candidate. For MCP-routed work, call `atlas_session_brief` once with `query`, the exact root selector, and `compact: true`; for a focused question start with `file_limit: 3`, `folder_limit: 3`, `blocker_limit: 1`, and `purpose_limit: 1`, then follow its typed next call. When the task has a content role, carry `content_selection: "source"`, `"documentation"`, or `"both"` on the returned files, search, summary, slice, symbol, and detailed-relation calls that expose it. Use `source` for ordinary implementation work, `documentation` for specification or guidance discovery, and `both` only when the task crosses the two. Omit the field only when the legacy candidate universe, including configuration/data and other text, is intentionally required. 5. For MCP, call a returned `atlas_file_summary` recommendation with `compact: true`; use full/default output only when complete totals or coverage state matter. For CLI, use `atlas summary <file>`. 6. Use a selected summary's direct caller/dependency facts without reconfirming them. Use outline or symbols only when summary context is insufficient. Use detailed relations when resolution, incompleteness, ambiguity, or an unshown path matters (`atlas symbols relations` locally, `atlas_symbol_relations` for MCP). Follow any MCP `next_call` unchanged; do not reconstruct its cursor. 7. Use `atlas slice` or `atlas symbols slice` locally, `atlas_slice` for MCP, for the smallest exact source range. Copy returned disambiguators rather than guessing a symbol line. 8. Stop once exact evidence answers the task. For external reachability, verify the owning module, re-export, package, or route boundary once; a public nested declaration alone is not proof, but do not repeat a boundary already established by a trusted export or exact declaration. Public exposure is not an inbound-caller question: use the trusted export or a bounded module/re-export declaration, not a relation query on the entrypoint. 9. For MCP, fall back to `atlas_overview` only when the brief is unavailable, has no actionable candidate, or broader structure is itself the task; then use `atlas_folders` before `atlas_files`.

`connections_truncated` describes the compact sample. It means more relationships exist, not that the selected next call is wrong. Use the returned detailed-relations call only when those additional relationships matter.

Worktree MCP Workflow

Treat `main` as the reserved alias for the explicitly selected control atlas, not as a branch or directory name. The control checkout may itself be linked, live under `.worktrees`, or live anywhere else on the filesystem. Pro