Adoption Checklist

Use this checklist when adding ProjectAtlas to an existing repo.

1. Install

pip install -e .

2. Initialize

projectatlas init --seed-purpose

projectatlas init auto-detects repo languages to seed scan.source_extensions and purpose.styles_by_extension. Use --no-detect-languages to keep the static template.

3. Fill folder summaries

  • Add a one-line summary to every .purpose file.
  • Keep summaries short and single-line.

4. Add Purpose headers

Add a Purpose: header to every tracked source file using the configured comment style. Python modules should use a module docstring with Purpose:.

5. Track non-source files

Add summaries for non-source files in .projectatlas/projectatlas-nonsource-files.toon (agent-maintained input).

6. Generate the map

projectatlas map

7. Lint

projectatlas lint --strict-folders --report-untracked

8. Wire into local scripts

Example package.json:

{
  "scripts": {
    "projectatlas:map": "projectatlas map",
    "projectatlas:lint": "projectatlas lint --strict-folders --report-untracked"
  }
}

Example Makefile:

projectatlas-map:
    @projectatlas map

projectatlas-lint:
    @projectatlas lint --strict-folders --report-untracked

9. Agent setup

  • Add the startup snippet from templates/AGENTS.md to your AGENTS.md.
  • Copy the Codex skill to ~/.codex/skills/ProjectAtlas.md if you use Codex.