# Initialize Atlas > Bind this project to a vault Workspace and scaffold or self-heal it. Use when setting up atlas in a repo, when the user says "initialize my workspace", or when start-session reports no Project Binding (.atlas.toml). - Skill: `dbtlr/initialize-atlas` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add dbtlr/initialize-atlas` - Raw SKILL.md: https://api.skillmd.com/api/skills/dbtlr/initialize-atlas/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: dbtlr (https://skillmd.com/u/dbtlr) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/dbtlr/initialize-atlas --- # initialize-atlas Bind a project to its vault **Workspace** and ensure that workspace is scaffolded correctly. Idempotent and self-healing — safe to run repeatedly. > **Primary agent only.** If you were dispatched as a subagent, stop here. ## 1. Resolve the vault The vault is always the **atlas vault**; its location is the `ATLAS_PATH` environment variable — there is no registry and no per-repo vault config. - If `ATLAS_PATH` is set and the directory exists, use it as the vault root. - If `ATLAS_PATH` is unset, ask the user to `export ATLAS_PATH=` (offer `~/vaults/atlas` as the conventional default), then continue. Scaffold the vault skeleton if missing (see `resources/vault-structure.md`): - `.norn/config.yaml` — **norn is the vault-write authority** for Atlas knowledge and consolidation, so the vault must carry a norn config. If missing, seed it from `templates/norn-config.yaml`; never overwrite an existing config. - `artifacts/scratch/` (no `generated/`; Session Summaries live in Mimir). - `Workspaces/shared/` with `user.md` (User Profile) and `memory.md` (Shared Memory). **Create each missing one through norn** so it carries its dedicated schema type from birth (`NOW=$(date +%Y-%m-%dT%H:%M)`): ```bash norn -C "$ATLAS_PATH" new "Workspaces/shared/user.md" \ --field title="User Profile" --field description="" \ --field type=user-profile --field workspace=shared \ --field created="$NOW" --field modified="$NOW" --body-from-stdin --yes < # memory.md → --field type=shared-memory ``` Seed `user.md`/`memory.md` bodies lightly; a short user-profile interview can fill `user.md` later. If an older profile exists, offer to copy and curate it into the two files rather than migrating in place. ## 2. Resolve the workspace name - Use the `` argument if given; else infer from the repo directory name and **confirm**. - A Workspace maps 1:1 to a project, bound by name + path. ## 3. Elevator-pitch description Get a 2–3 sentence description of the project, in priority order: 1. From an existing Workspace Brief (if re-initializing). 2. From the repo's `CLAUDE.md` / `AGENTS.md`. 3. Else scan the repo and infer one. Confirm it with the user (offer to edit). It becomes the Brief's `description` and opening paragraph. ## 3b. Workspace type Pick the Brief's `workspace_type` — the vault's `workspace-note` rule requires it, and it has no safe default. Propose the best fit from the repo, then confirm with the user (on re-init, keep the existing value unless it's wrong): | `workspace_type` | When it fits | |---|---| | **product** | A single shippable system (app, site, service, infra) with **one** roadmap and task board. | | **library** | Reusable code consumed by other projects — no standalone runtime, a single publishable surface. | | **monorepo** | One repo housing **multiple products**, each with its own roadmap and task board. | | **incubator** | Holding area for early ideas/sketches/tests before they graduate to their own workspace or are dropped. | ## 4. Scaffold / heal the workspace Under `$ATLAS_PATH/Workspaces//`, ensure these exist — **create only what's missing; never overwrite existing content**: - `.md` — Workspace Brief. Compose the body from `templates/workspace-brief.md` (substitute `{{WORKSPACE}}`, `{{ELEVATOR_PITCH}}`), then create it through norn: `norn -C "$ATLAS_PATH" new "Workspaces//.md" --field title= --field description="" --field type=note --field kind=workspace --field workspace="[[]]" --field status=active --field workspace_type= --field domain=Workspaces --field created="$NOW" --field modified="$NOW" --body-from-stdin --yes < `. The `status`/`workspace_type`/`domain` fields and the wikilink `workspace` satisfy the vault's `workspace-note` rule (`status=active` for a new binding; `workspace_type` from §3b; `domain` is always `Workspaces`). After creating it, stamp an initial `brief_baseline` into its frontmatter — its own scaffolded size — so a brand-new workspace starts within budget and `start-session` doesn't recommend a consolidation that has no logs to process. Measure it the same way `consolidate-workspace` does (code-point count, not `wc -m`): `python3 -c 'import pathlib,sys; print(len(pathlib.Path(sys.argv[1]).read_text(encoding="utf-8")))' ""`, then stamp it with norn (pin the vault — norn resolves from `$NORN_ROOT`/cwd, never `ATLAS_PATH`): `norn -C "$ATLAS_PATH" set "Workspaces//.md" --field-json brief_baseline= --yes` (an `unknown field` warning is benign). `consolidate-workspace` refreshes it on every groom thereafter. - `glossary.md` — Generated by the `domain-modeling` skill (replaces `CONTEXT.md` if present). If that skill isn't installed, create a placeholder through norn (`norn -C "$ATLAS_PATH" new "Workspaces//glossary.md" --field title="Glossary" --field description="Domain terms for " --field type=note --field kind=glossary --field workspace="[[]]" --field created="$NOW" --field modified="$NOW" --body-from-stdin --yes`) with a note to run `domain-modeling`. - `decisions/`, `notes/`, `archive/` > **Local override.** If the repo sets `decisions = "local"` (or a path) in `.atlas.toml`, scaffold `decisions/` + `glossary.md` at that in-repo target instead of in the vault workspace. If everything already exists and is consistent, report: *"Your workspace is already initialized to `` and everything looks correct."* Otherwise apply only the missing pieces and say what you added. ## 5. Write the Project Binding Write `.atlas.toml` at the repo root: ```toml workspace = "" # decisions = "local" # optional: keep decisions/glossary in-repo instead of the vault workspace ``` Ask whether to commit it to git (**default: no** — ensure it's in `.gitignore`). ## 6. Permissions (harness-specific) Ensure the agent can read/write the vault paths. In Claude Code, add the vault globs to `.claude/settings.local.json`. Re-running `initialize-atlas` under a different harness adds that harness's needs. ## 7. Finish - **Fresh init:** hand off to **start-session** to load the new context. - **Heal:** just report what changed.