ProjectAtlas / templates

# ProjectAtlas Startup Snippet

## Startup
0. Read the complete installed/version-matched ProjectAtlas skill at startup and after compaction. For one exact checkout, prefer its short `atlas` CLI and read the skill's short-command guide for each command's function and trigger; `projectatlas` is the same native command surface. Use `atlas_*` MCP tools for registered worktree aliases, compact session briefs/typed continuations, and cross-worktree federation. A hook may remind you but cannot prove the skill was read.
1. Establish the project root and run ProjectAtlas from that root so `.projectatlas/projectatlas.db` is project-local.
2. Refresh with `atlas watch --once` locally or `atlas_watch_once` for an MCP-routed worktree only when the index may be stale; scan only on typed full-refresh guidance, never merely because a session started.
3. For one exact checkout, call `atlas next <task>` once, then a bounded summary/search/relation and exact slice. For MCP-routed work, call `atlas_session_brief` once with `compact: true` and the exact root selector; follow its typed next call directly.
4. Use the returned compact summary, search, relation, health, or slice call. Copy returned selectors and continuations instead of guessing or restarting discovery.
5. Use compact summary connections for an ordinary trusted direct caller or dependency. Call detailed relations only when resolution, completeness, ambiguity, an omitted connection, or an exact occurrence matters.
6. Run `atlas slice <file> --start-line <n> --end-line <m>` locally or `atlas_slice` through MCP for the smallest exact source range.
7. Use `atlas overview`, then folders and files, when `next` has no actionable candidate or broader structure is the task. For MCP, use the corresponding overview fallback when the brief cannot select a candidate. Use `atlas files --file-pattern <glob>` when the path pattern is known.
8. Run `atlas outline <file>` or bounded `atlas search <pattern>` when selected-file context is insufficient; use MCP equivalents only on an MCP-routed worktree.
9. Run `atlas health` for cleanup/refactor work, with `atlas_health` as the MCP equivalent.
10. Run `atlas lint --report-untracked --purpose-level low`; low fails stale, duplicate, and temporary-folder health but keeps first-pass purpose curation advisory. Use `atlas purpose queue` for the next curation actions; use `medium` only when all source files must be agent-reviewed and `strict` only when every indexed file and folder must be agent-reviewed. MCP has equivalent lint and purpose tools for routed work.
11. Only then use language-server lookups or broad file reads on selected files.
13. Run `atlas token` when asked for token savings; use `atlas token --view tui` only when a human asks for the terminal dashboard. Use `atlas_token_report` for an MCP-routed worktree.
14. After ProjectAtlas plugin/runtime updates, verify Codex plugin drift with `codex plugin list --marketplace projectatlas --json` and global MCP registry drift with `codex mcp get projectatlas` or `codex mcp list` when `codex` is available. A stale official `projectatlas` marketplace/plugin cache, stale Codex ProjectAtlas skill artifact, stale global `projectatlas` MCP entry pointing at an old runtime, wrong version, or invalid config, or old ProjectAtlas release pin in an official downstream workflow, is a bug; rerun the ProjectAtlas installer so it repairs or reports the drift automatically. The installer also verifies Claude Code/OpenCode generated MCP configs against the verified runtime, version guard, selected DB/config, and host-specific fields; when those host CLIs are installed, smoke their config readers too. A global entry whose default DB belongs to another repository can still serve the current repository through process-scoped `atlas_set_project_path` or per-call `project_path`; prefer per-call `project_path` for shared or concurrent hosts. Use `PROJECTATLAS_SKIP_CODEX_PLUGIN_UPDATE=1` only for intentionally managed Codex ProjectAtlas plugin marketplaces, and `PROJECTATLAS_SKIP_CODEX_MCP_REGISTRY_UPDATE=1` only for intentionally managed global registries.
15. If work moves outside the selected ProjectAtlas root, switch with `atlas_set_project_path` in a single-client stdio session or per-call `project_path` when isolation matters. Root-level MCP paths may route to another repository only when that addressed root already has `.projectatlas/projectatlas.db`; otherwise use normal filesystem tools such as `rg`, `Get-Content`, or targeted shell reads instead of ProjectAtlas for out-of-project files.
16. For planned folder and file purpose creation or correction, including initial creation and broad refreshes, delegate the work through bounded isolated subagent execution at the lowest reliable reasoning and cost tier the host supports when that execution is available; otherwise process the same bounded work in the main agent. Give the subagent bounded ProjectAtlas queue rows, summaries, outlines, or exact snippets, and have it write through `atlas_purpose_set`, `atlas_purpose_review`, `projectatlas purpose set`, or `projectatlas purpose review --from-file <json> --apply`; never edit SQLite directly. A purpose written by an agent or subagent through those ProjectAtlas APIs is agent-approved and does not need a second approval pass. If any agent notices a wrong, vague, generic, or genuinely repurposed accepted purpose during normal work, correct it explicitly with the same ProjectAtlas APIs. Purpose entries live in SQLite and are preserved across scans; source/hash/summary/symbol/graph changes never demote or invalidate an accepted purpose. An absent or excluded path leaves its purpose dormant, an exact-path reappearance restores it, and a rename does not transfer approval automatically.
17. When a GitHub issue has an OpenSpec change, mirror `openspec/changes/<id>/tasks.md` into exactly one visible `Implementation Tasks` section and add exactly one canonical five-row `Acceptance and Review Tasks` section. Implementation tasks are live progress: check each row immediately after its behavior and required task-level proof pass, and reopen it immediately when review finds the implementation partial, resetting all acceptance/review rows. Keep acceptance unchecked until implementation completes, then use a checked prefix. Existing implementation rows remain unchanged, including historical architecture-review rows. Every open mapped issue uses the current two-list contract; already closed mapped issues are inert historical state and are not body-migrated or repeatedly task-validated, while reopening an old issue requires migration before work proceeds. Every open issue carries exactly one accepted `complexity:*` label, including unmapped backlog issues, without fabricated task fields. Use `(Implementation tasks: <task IDs>)` for open mapped mitigations, keep `openspec/issue-map.json` current, and run `.github/scripts/issue-checklists.py` for release/check-in validation. Pull-request checks resolve exactly one referenced owner, compare its candidate task slice with live state, require unrelated open slices to match the accepted base, exclude closed unrelated history, and fail closed on missing or ambiguous ownership/base; `main` and release checks remain global and use native closed state for closure/release. Treat local/GitHub checklist drift as a check-in blocker; random checkboxes outside explicit task sections must not satisfy the gate.
## Rust/Dependency Discipline
- Prefer official or canonical Rust crates and standard implementations for protocols, formats, parsers, storage, watchers, token tooling, and platform integration before writing custom code.
- Keep custom Rust code focused on ProjectAtlas-specific product logic, agent workflow policy, and composition between proven libraries.
- Document any exception to the official/canonical crate preference and cover it with tests.
- Architecture reviews must explicitly check for unnecessary reimplementation, cross-platform path issues, performance bottlenecks, and drift from agent-first ProjectAtlas workflows.
- Do not scatter protocol, schema, status, command, event, or mode strings as inline literals in Rust logic or payload builders. Centralize them at the smallest owning boundary: adapter-local constants/enums/types for adapter-only contracts, service-local constants/enums for service-owned rules, and shared crate modules only for cross-crate public contracts.
- Prefer typed structs plus `Serialize` enums for JSON/TOON payload schemas and status values. Use constants for repeated command/event keys and match strings; keep one-off human diagnostics or test fixture prose inline when that avoids false abstraction.