Atlas compact

Compact AI Context

Overview

Use this skill when atlas doctor reports context-size advisories or AI-facing context files grow oversized. The published CLI owns deterministic measurement — which files count, their sizes, thresholds, and statuses. This skill owns semantic judgment — what to cut, move, merge, or keep. Never reimplement measurement, guess sizes, or invent thresholds.

Call the CLI through npx, preferring a locally installed @blazity-atlas/core (npx --no-install @blazity-atlas/core …) and falling back to the published package only when none is installed. Every npx --yes @blazity-atlas/core@latest … command in this skill is the fallback spelling of that rule, not an instruction to skip the local copy.

This skill edits content only. Structure repair — directories, config, symlinks, managed files — stays with doctor --fix.

Run the phases below in order.

Phase 1 — Deterministic Measurement

From the repository root, run:

npx --no-install @blazity-atlas/core doctor

Follow the result before compacting anything:

• Manual findings (exit 2): summarize the conflicts and stop.
• Fixable drift (exit 1): offer npx --yes @blazity-atlas/core@latest doctor --fix first — structure repair precedes compaction. If --fix refuses because of a dirty worktree, ask the user whether to commit, stash, or explicitly rerun with --force; never use --force automatically.
• No context-size advisory and no user-named target: report that the AI context is within thresholds and stop.

Capture the authoritative per-file worklist:

npx --no-install @blazity-atlas/core doctor --handoff context-size

Treat its entry lines as the worklist; do not re-measure by hand.

Phase 2 — Read and Classify

Resolve every path through the workspace config — never hardcode .ai/: read .ai/config.json, or when absent, follow the .atlas repo-root pointer to <root>/config.json.

Read each flagged file and bucket its content:

• Commands, invariants, and safety rules → stay in root instructions.
• Durable product, architecture, stack, and lesson detail → configured memory files.
• Decisions and rationale → configured decisions/ADR paths.
• Canonical terms → the configured language file.
• Duplicated content → keep one canonical location and reference it from the rest.
• Stale content contradicted by the repository (with evidence) → delete.

Managed Atlas skill files are report-only: never hand-edit them — the byte-equality drift check reverts any edit on the next doctor --fix. An oversized managed skill is package-maintenance work; record it, do not fix it locally.

Phase 3 — Propose

Present a per-file plan before touching anything: exact moves (source section → destination path), merges, deletions with reasons, and expected size deltas. Never rewrite silently; get explicit approval, whole-plan or per-file.

Everything relocated or rewritten follows the durable-documentation rules: record needs, decisions, and reasons — never individuals or internal process. Keep personal names, private schedules, internal-only references, and absolute local paths out of workspace artifacts.

Phase 4 — Apply

Apply approved edits only. Preserve the AGENTS.md managed block, user rules, commands, and safety boundaries. Do not create new documentation roots and do not touch config or structure — that is the CLI's job.

Phase 5 — Re-verify

1. Rerun npx --no-install @blazity-atlas/core doctor — actually run it, never assume the result.
2. Show before/after context-size lines. The exit code must be unchanged or better.
3. Advisories never affect exit codes; do not chase zero warnings at the cost of deleting real guidance. If a file still warns after one bounded iteration, record the residual as accepted with a reason.
4. Suggest a commit of the compaction result.

Boundaries

• Missing or thin context (empty vocabulary, empty memory, setup pending) → the atlas-setup skill.
• Reviews, gates, and verdicts on AI tools and changes → the atlas-review skill.
• Workspace structure, managed skills, and config → the Atlas CLI (init, doctor --fix).