{"id":51586664,"url":"https://github.com/blazity/atlas","last_synced_at":"2026-07-11T11:01:38.296Z","repository":{"id":363535865,"uuid":"1233154583","full_name":"Blazity/atlas","owner":"Blazity","description":"Framework-agnostic AI documentation scaffold — one command gives any repo the shared instructions, memory, and gates coding agents need to work safely.","archived":false,"fork":false,"pushed_at":"2026-07-07T11:05:27.000Z","size":7047,"stargazers_count":22,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-07T11:05:34.873Z","etag":null,"topics":["agents-md","ai","ai-agents","claude-code","cli","codex","cursor","developer-tools","documentation","scaffolding"],"latest_commit_sha":null,"homepage":"https://blazity.com/atlas","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Blazity.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-08T16:44:12.000Z","updated_at":"2026-07-06T11:47:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"3f4f7a2b-5cca-4477-815a-aef0f10fa7d9","html_url":"https://github.com/Blazity/atlas","commit_stats":null,"previous_names":["blazity/atlas"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Blazity/atlas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blazity%2Fatlas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blazity%2Fatlas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blazity%2Fatlas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blazity%2Fatlas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Blazity","download_url":"https://codeload.github.com/Blazity/atlas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blazity%2Fatlas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35360371,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents-md","ai","ai-agents","claude-code","cli","codex","cursor","developer-tools","documentation","scaffolding"],"created_at":"2026-07-11T11:01:37.277Z","updated_at":"2026-07-11T11:01:38.278Z","avatar_url":"https://github.com/Blazity.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://blazity.com/atlas\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/atlas-logo-dark.svg\"\u003e\n      \u003cimg alt=\"Atlas\" src=\"assets/atlas-logo-light.svg\" width=\"202\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eAtlas — repo-owned AI context for coding agents\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  One command gives every coding agent the same documentation structure, repo memory, and AGENTS.md —\u003cbr\u003e\n  and \u003ccode\u003eatlas doctor\u003c/code\u003e keeps that structure verified in CI with frozen exit codes.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@blazity-atlas/core\"\u003e\u003cimg alt=\"npm version\" src=\"https://img.shields.io/npm/v/%40blazity-atlas%2Fcore\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/Blazity/atlas/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://github.com/Blazity/atlas/actions/workflows/ci.yml/badge.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"package.json\"\u003e\u003cimg alt=\"node \u003e=20\" src=\"https://img.shields.io/node/v/%40blazity-atlas%2Fcore\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"MIT license\" src=\"https://img.shields.io/npm/l/%40blazity-atlas%2Fcore\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nEvery coding agent forgets your repo between sessions, and every tool wants its own config file. You re-explain the architecture, the vocabulary, the \"don't touch that\" list — per agent, per session, forever.\n\nAtlas (by [Blazity](https://blazity.com)) gives the repository one place for all of it: a unified documentation structure and plain-files workspace that Claude Code, Codex, Cursor, and anything that reads [AGENTS.md](https://agents.md) share — committed to git, reviewable in PRs, and checked for drift by a deterministic CLI.\n\n- ⚡ **One command** — `npx @blazity-atlas/core init` scaffolds AGENTS.md, CLAUDE.md, and a complete `.ai/` workspace\n- 🗂️ **One structure for everything** — plans, research, decisions, ADRs, memory, vocabulary, and review verdicts in predictable, config-defined locations\n- 🤝 **Every agent, one context** — Claude Code, Cursor, Codex, Copilot, and Gemini CLI share the same repo-owned files\n- 🧩 **Plays well with skills** — third-party and custom skills route their documentation output through `.ai/config.json` instead of inventing new folders\n- 📦 **Builds on what you have** — config-driven path aliases adopt your existing docs folders instead of replacing them\n- 🩺 **Machine-checked** — `atlas doctor` verifies the structure in CI with frozen exit codes; `--fix` repairs drift deterministically\n- 🔒 **Nothing leaves your repo** — no telemetry, no network calls, one dependency, plain files only\n\n## Feature showcase\n\nA short demo of `atlas init`, the handoff prompt, and `atlas doctor`.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cvideo src=\"https://github.com/user-attachments/assets/691767f7-8fc9-46fb-8864-42798fb77819\" width=\"600\" controls\u003e\u003c/video\u003e\n\u003c/div\u003e\n\n## Quickstart\n\n```bash\nnpx --yes @blazity-atlas/core@latest init\n```\n\nOne run scaffolds the workspace — config, vocabulary, memory, artifact directories, two managed skills, the AGENTS.md and CLAUDE.md entrypoints, and the agent symlinks — then prints a ready-to-paste handoff prompt. Your own coding agent takes it from there: it inspects the repository and fills the workspace with project-specific facts.\n\nIn a terminal, `init` runs interactively: it asks where the workspace should live (default `.ai`), previews every file before writing, and can launch a detected agent CLI (`claude`, `codex`, `cursor-agent`) with the handoff prompt.\n\n## Safe to run on an existing repo\n\nThese are behaviors you can verify in two minutes, not promises:\n\n- **Refuses dirty worktrees.** `init` and `doctor --fix` stop when you have uncommitted changes (and name the offending files); `--force` is the explicit override.\n- **Preserves your content.** An existing `AGENTS.md` gets one fenced managed block appended; everything you wrote stays. Repairs never touch content outside managed blocks.\n- **Idempotent.** A second `init` prints `Already up to date — nothing to write.`\n- **Previewable.** `init --dry-run` shows every planned write and touches nothing.\n- **Plain files only.** No database, no daemon; the only network call is the explicitly invoked update check (`atlas update` / `doctor --check-updates`). Uninstall = delete the workspace directory, the managed block in `AGENTS.md`, and three symlinks.\n\n## One structure, everything in it\n\nThe scaffold is the boring part. The point is what collects in it as you work: plans, research, ADRs, vocabulary, memory, and review verdicts — in predictable locations agents resolve through `.ai/config.json`, instead of dissolving into chat history.\n\nThat routing is not Atlas-only. The managed block Atlas writes into `AGENTS.md` tells any agent — and any skill it runs, third-party or custom — to resolve artifact destinations through the config before writing. A planning skill's plan lands in the plans directory, a research skill's report in research, a review's verdict in results: one tree, no matter which tool wrote it.\n\nThis repository runs on Atlas. Its own workspace is the demo:\n\n- [`.ai/LANGUAGE.md`](.ai/LANGUAGE.md) — vocabulary with an *Avoid* column that encodes real decisions (\"Template ≠ Preset\", the legacy name that is banned).\n- [`.ai/memory/lessons.md`](.ai/memory/lessons.md) — earned lessons, e.g.: *\"Bare managed-skill names collide in shared agent namespaces — Atlas's `review` collided with Claude Code's built-in PR-review skill in practice.\"*\n- [`.ai/decisions/adrs/`](.ai/decisions/adrs) — ADRs that record rejected options, not just winners.\n- [`.ai/results/`](.ai/results) — review verdicts from the `atlas-review` process gate.\n\nIf your repo already keeps docs in conventional places (`docs/adrs`, `docs/specs`, …), Atlas maps them into the workspace through config-driven `pathAliases` instead of inventing a parallel documentation system — `doctor --fix` performs the moves, and the config keeps routing future writes.\n\n## `doctor` in CI\n\n```yaml\n- name: Atlas structural gate\n  run: npx --yes @blazity-atlas/core@0.5.0 doctor   # pin the version your workspace was scaffolded with\n```\n\nThe exit codes are a frozen contract:\n\n| Exit | Meaning |\n| --- | --- |\n| `0` | Workspace clean — advisories never affect the exit code |\n| `1` | Fixable drift — `atlas doctor --fix` repairs it deterministically |\n| `2` | Manual conflicts that need a human |\n\nAdvisories (setup pending, empty memory, oversized context) inform and never fail a build. `doctor --json` emits the findings as structured data for scripting. Pin the version rather than `@latest`: managed skill files are byte-compared, so upgrading the package and running `doctor --fix` belong in the same change.\n\nContext-size advisories watch the files agents actually load — `AGENTS.md`, `CLAUDE.md`, vocabulary, memory, decisions, managed skills — against heuristic character budgets informed by documented agent caps (for example, Codex reads at most 32 KiB of project docs by default). They are hints to compact, not model limits. When one fires, `atlas doctor --handoff context-size` prints a safe cleanup prompt for any agent, and the `atlas-compact` managed skill runs the full loop: measure with the CLI, propose a per-file plan, apply approved edits, re-run `doctor` for before/after proof.\n\n## Updating\n\n`atlas update` checks npm for a newer release — the only Atlas command that touches the network, and only when you run it — and prints the pinned upgrade command. `doctor --check-updates` runs the same check as a non-blocking advisory. `doctor` itself never goes online, so CI stays deterministic and offline.\n\nThe workspace records how it was written, and `doctor` uses both records:\n\n- `config.json` carries `atlasVersion`, the package version that last wrote the workspace. A newer CLI reports a `atlas-version-behind` advisory until you run `doctor --fix`; an older CLI hits an `atlas-version-ahead` manual conflict instead of silently reverting newer managed files (`--force` is the explicit override).\n- `atlas.lock.json` records a content baseline for every managed skill file. A file that differs from the package but matches its baseline was never touched locally, so `--fix` updates it. A file that differs from both is a deliberate customization: `doctor` reports a `customized-skill` advisory and `--fix` leaves it alone. Keep the customization with `doctor --adopt-skills` (the advisory returns only when a later release changes that skill), or overwrite it with `doctor --fix --reset-skills`.\n\nWorkspaces scaffolded before the lockfile existed classify old skill content as customized once — run `doctor --fix --reset-skills` after upgrading if you never customized the managed skills.\n\n## Reviews that leave a verdict\n\nThe second managed skill, `atlas-review`, walks AI-assisted work through five modes — Intake, Plan, Review, Gate, Postmortem — and writes its verdict (pass / conditional pass / fail, with evidence, risks, and an owner) into `.ai/results/`, where the next agent run and the next human can find it. A review that leaves no artifact doesn't count as a review.\n\nClaude Code users run `/atlas-review`. Any other agent gets the same behavior from one instruction: *\"read `.ai/skills/atlas-review/SKILL.md`\"*.\n\n## Works with your agent\n\nAtlas writes the [AGENTS.md](https://agents.md) standard as its entrypoint, so most agents need zero configuration:\n\n| Agent | How it picks up Atlas |\n| --- | --- |\n| Claude Code | `CLAUDE.md` imports `AGENTS.md`; skills via `.claude/skills` symlink or the plugin |\n| Codex | Reads `AGENTS.md` natively |\n| Cursor | Reads `AGENTS.md` natively; `.cursor/skills` symlink provided |\n| GitHub Copilot | Reads `AGENTS.md` in the coding agent and VS Code |\n| Gemini CLI | One setting: `contextFileName: \"AGENTS.md\"` |\n| Anything else | One instruction: \"read AGENTS.md, resolve paths through .ai/config.json\" |\n\nClaude Code users can also install through the marketplace:\n\n```text\n/plugin marketplace add Blazity/atlas\n/plugin install atlas@blazity\n/atlas:atlas-setup\n```\n\n## Scope and non-goals\n\nAtlas Core ships two kinds of gates today:\n\n- **Structural gates** — `doctor`'s deterministic workspace checks with the frozen exit codes above.\n- **Process gates** — `atlas-review`'s evidence-based verdicts, written into the workspace.\n\nIt does **not** run your tests, evals, or policy checks (execution gates are where the standard points next, not what Core does today), it is not an agent runtime, and it does not generate code.\n\n## Privacy\n\nThe CLI runs locally, makes no network calls at runtime, sends no telemetry, and has exactly one dependency ([@clack/prompts](https://www.npmjs.com/package/@clack/prompts) for the interactive terminal UI). Everything it writes is a plain file in your repository. The scaffolded documentation rules also require durable artifacts to stay depersonalized — memory that is safe to commit and safe to publish.\n\n## Requirements\n\nNode.js ≥ 20 and a git repository. macOS and Linux supported; Windows untested.\n\n## Built with Atlas\n\nDeveloped on the Atlas standard by Blazity:\n\n- [Atlas Eve Starter](https://github.com/Blazity/atlas-eve-starter) — starter monorepo for production-style agents\n- [Next.js Migration Plugin](https://github.com/Blazity/nextjs-migration-plugin) — website → Next.js migrations with build gates and visual verification\n- [AI Workflow](https://github.com/Blazity/ai-workflow) — issue → plan → implementation → reviewed PR agent workflows\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports with `atlas doctor` output are triage-ready thanks to the bracketed finding codes. Security reports go through [SECURITY.md](SECURITY.md).\n\n## License\n\n[MIT](LICENSE) © [Blazity](https://blazity.com)\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://blazity.com\"\u003e\u003cimg src=\"https://github.com/Blazity.png\" width=\"72\" alt=\"Blazity\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eAtlas is built and maintained by \u003ca href=\"https://blazity.com\"\u003eBlazity\u003c/a\u003e — the standard behind our own AI tooling. More at \u003ca href=\"https://blazity.com/atlas\"\u003eblazity.com/atlas\u003c/a\u003e.\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblazity%2Fatlas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblazity%2Fatlas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblazity%2Fatlas/lists"}