Projectatlas

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 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 and restore the exact selected project/worktree from live state, not remembered database binding.

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. ProjectAtlas discovers existing Git structure but never creates, switches, moves, prunes, or deletes a Git worktree or branch.

1. Call atlas_worktree_list(include_retired: false) from the control MCP process. Select a returned stable selector; do not reconstruct a full path or guess from a colliding directory or branch name. A row blocked because its common, administrative, or source path is not lossless UTF-8 has no registrable selector or root and must not be addressed through replacement-character display text.
2. Register an existing checkout with atlas_worktree_add(worktree: "<selector>", alias: "issue-430"). The alias is optional only when the target directory name is already a valid unique alias. Registration changes only the control atlas catalog; it does not create the target .projectatlas directory or mutate Git or source files.
3. Initialize an absent target with atlas_init(worktree: "issue-430"). A complete compatible control atlas seeds a private candidate, removes control identity, telemetry, task, and runtime state, reconciles the candidate against the target branch and dirty files, and publishes it atomically. A valid existing target database is preserved. An unsuitable baseline produces an explicit ordinary-init fallback; cancellation or integrity failure leaves the destination absent or unchanged.
4. Route ordinary calls without changing directory or mutable process selection: atlas_session_brief(worktree: "issue-430", compact: true), atlas_watch_once(worktree: "issue-430"), atlas_file_summary(worktree: "issue-430", file: "src/lib.rs", compact: true), or a purpose/health call with the same alias. Each admitted call captures its exact root, database, project identity, registration identity, and alias, and refuses a recreated database whose project identity differs, so interleaved main and worktree calls cannot retarget one another.
5. For a cross-worktree graph question, use one detailed or analysis atlas_symbol_relations call with worktrees: ["main", "issue-430"]. The first alias is primary. ProjectAtlas opens two to eight exact databases read-only, labels every participant/result/blocker/continuation, and never persists or merges sibling graphs. Do not also send legacy roots.
6. Request repository totals with atlas_token_report(worktree: "main") or run atlas token / atlas token --view tui from the control checkout. The existing TUI layout combines native-control plus active and retired registered-worktree aggregates. atlas_token_report(worktree: "issue-430") stays exact to that target's local detail. Alias-routed MCP usage is recorded once in control; independent local usage synchronizes monotonically without copying raw per-session events.
7. Retire only the ProjectAtlas registration with atlas_worktree_remove(worktree: "issue-430"). ProjectAtlas holds a short local SQLite writer-exclusion scope while it atomically final-syncs and retires the control registration, retains the accepted aggregate, and leaves the checkout, Git registration, branch, files, .projectatlas, and SQLite database untouched.

Use the returned typed recovery state rather than switching to paths: ambiguous returns bounded selectors; init_required returns the exact alias init call; refresh_required names the stale alias; invalid or mismatched Git evidence fails closed; worktree_required asks for an exact active checkout when a bare/common manager cannot select one. If Git externally removes a registered checkout, atlas_worktree_list retains its active alias, last validated root, accepted telemetry revision, and typed missing state so atlas_worktree_remove(worktree: "<alias>") can retire it without reconstructing a path. A manager with core.worktree, an enabled config.worktree override, or unresolved config includes never guesses its parent. Add revalidates the selected root and lifecycle immediately before registration, and a moved-root refresh cannot reactivate an alias retired by a concurrent remove. If Git recreates a worktree administrative directory at a previously registered path, remove the stale ProjectAtlas alias and add the replacement explicitly; ProjectAtlas will not let the replacement inherit the alias or touch its atlas through that stale mapping. Lifecycle identity requires creation time plus platform file-object identity (Unix device/inode or Windows retained-handle volume/128-bit file ID), and every persisted common, administrative, and source path must be lossless UTF-8 for SQLite metadata and MCP JSON. If the filesystem or path cannot provide the complete evidence, alias registration fails closed; never reuse a replacement-character display path as project_path. project_path remains the compatibility route for unregistered and older workflows when the path is lossless UTF-8, while alias routing is the normal concurrent-agent path.

Classified Documentation Navigation

• Treat classification as a derived file role, not parser trust, purpose authority, or runtime truth. documentation is guidance; confirm implementation claims in current source summaries, symbols, or exact slices.
• Start with classified files or search. Use source for code-only work, documentation for docs-only discovery, and both when finding an explicit bridge. The closed selections exclude configuration/data, other text, and opaque rows; omission preserves the broader legacy behavior.
• Follow an explicit document bridge with atlas_symbol_relations using view: "detailed", relation: "documents", and the exact file or heading anchor. Outbound traversal moves from documentation to its validated repository target. Inbound traversal from source returns the same stored relation under the read-only documented_by view; no inverse fact is stored.
• Inspect parser provenance, coverage, completeness, resolution, and typed unresolved reason together with classification. Missing, ignored, outside-root, case-conflicting, unsupported, and non-static targets are evidence to narrow or repair the navigation request, never permission to guess.
• Submit the returned next_call unchanged. It preserves the exact file or heading selector, content selection, generation, and bounds; finish at current source evidence before making an implementation claim.
• In linked-worktree or shared-host sessions, pass the exact checkout project_path on every call. Each checkout owns its ignored writable database and classified graph; never substitute a sibling database or combine sibling graph generations.

PHP Navigation

Use this profile only when the selected runtime's language capabilities report built-in PHP support and its version matches the installed plugin. Read the PHP row in the bundled generated language-support reference for capability and parser identities; do not infer support from the .php extension or a release label alone. Regenerate that reference with the existing render_language_support example when the registry changes; its bytes must match the repository's generated language-support document.

1. Start with atlas next <task> from the exact checkout, or a compact session brief when MCP alias routing is needed. Follow its ranked file recommendation; use overview, folders, and files when the repository layout or ownership is still unclear. In a Composer repository, inspect the actual source roots and ignore policy before selecting application code. Composer autoload declarations are configuration evidence, not proof that a runtime class or framework binding resolves.
2. Read the selected file summary with content_selection: "source". Inspect parser_kind, summary_status, and coverage together. PHP grammar-produced facts can retain Tree-sitter provenance while unsupported or dynamic regions make the summary fallback and coverage partial. A rescued declaration with fallback provenance has weaker evidence. Neither state makes omitted declarations or calls absent at runtime.
3. Use outline for declaration ownership and bounded search for exact names or source syntax. Named namespaces, types, functions, and members provide navigation anchors where returned; copy the exact file, kind, parent, and span selector to distinguish duplicate names. A declaration's presence does not prove conditional code executed.
4. For a dependency or caller question, request detailed graph evidence and inspect each relation's resolution, coverage, and source context. Static include/require paths and namespace imports have different meanings even when represented by the same import relation family. An extracted call is not necessarily a resolved target. Follow returned continuations and exact resolved selectors; inspect an unresolved call's source instead of inventing a destination.
5. Finish with an exact slice and check the current bytes. Refresh after edits using the normal freshness route, then repeat only the affected query. Keep the same worktree or project selector on every call.

Abstain from claims about variable calls, object dispatch, runtime include expressions, eval, framework containers, Composer autoload execution, or generated runtime behavior unless separate evidence establishes them. Mixed HTML/PHP and malformed recovery trees may leave valid PHP spans navigable while other regions remain partial or fallback; a PHP graph does not prove HTML or template semantics. Search and exact slices can establish literal text in these cases, not runtime execution or complete reachability.

For generated or vendored source, verify the repository's ownership and ignore policy and locate the authored input before proposing a change. A generated file's static symbols do not establish its generator, regeneration command, or safe edit target. If the authored source or relation evidence is unavailable, state that limit and stop the unsupported inference.

Indexing Strategy

• First use with no project-local index, or typed init_required: atlas init locally; use atlas_init for a registered alias or returned MCP next call. Do not repeat init for an existing valid index.
• Fresh existing index: make no indexing call. Start locally with atlas next <task> or use atlas_session_brief when MCP routing is needed.
• Changed files: use atlas watch --once locally or atlas_watch_once with an MCP alias; both incrementally refresh affected facts.
• Full refresh: use atlas scan / atlas_scan only for an initialized project with no published index, an intentional rebuild, or typed full-refresh guidance.
• Deep symbol/graph rebuild: use atlas symbols build / atlas_symbols_build only when the projection is reported missing/stale/incomplete or explicitly requested.
• Continuous editing: a human may keep atlas watch running; agents use bounded one-pass refreshes.

Never reset or replace an incompatible database as an orientation shortcut. Follow its typed recovery guidance and preserve authored purpose state.

MCP Routing When Needed

Use this table after selecting MCP for its alias, compact-brief, or federation behavior. For an exact local checkout, use the short CLI command guide first.

Search is lexical by default. Literal/token acceleration must preserve exact results; regex, fuzzy, short, punctuation-sensitive, or Unicode-unsafe queries may use bounded persisted-text fallback. Inspect searched files/bytes, completeness, and truncation before widening. Semantic or hybrid retrieval is explicit and may return typed unavailable/stale lifecycle state.