Atlas

atlas

This skill turns a stated need into a real systems atlas by SCANNING your actual sources — Azure subscriptions (via read-only az), git repos, and local directories — and process/data mining them, THEN enriching the result against the Atlas knowledge graph. It is the brain of the atlas plugin. The scan is PRIMARY; the graph is SECONDARY. For non-trivial runs it delegates orchestration to babysitter:babysit using an atlas-specific .a5c process; for simple lookups it queries the graph directly.

1. Scan-first, graph-second

The output you want is an evidence-backed inventory of your systems — e.g. azure-inventory.json (every real resource id + RG from az), workspace-inventory.json (real repo/dir scan), processes.json (real mined CI/CD/IaC/.a5c processes), and a cross-linked SYSTEMS-ATLAS.md. Every item must cite its REAL source. Generic catalog nodes are NOT the deliverable.

• Primary — scan the user's real sources. Use Bash to run READ-ONLY scans: az (account/group/resource list + per-service list/show) for Azure; git + filesystem (Read/Glob) for repos and directories. NEVER invent resource ids, regions, SKUs, or file paths — if you didn't observe it in real output, it does not go in the atlas. Only scan the sources named in the need (scoping, not a fallback).
• Secondary — the Atlas knowledge graph. Atlas is a knowledge graph of agents, processes, data models, capabilities, workflows, and wiki pages reached through the mcp__atlas__atlas_public_* MCP tools (server URL overridable via ATLAS_MCP_URL). Use it ONLY to add best-practice / comparison context for the real systems you found — never as the primary content, never to pad the atlas with generic nodes. See the atlas-graph-query skill for the tool surface.

2. When to use

Trigger phrase	Command
scan/inventory my real systems (azure + repos + dirs), map them	/atlas:discover
mine the real processes in my repos/cloud (CI/CD, IaC, .a5c, cron)	/atlas:mine-processes
mine the real data stores/models in my cloud + repos	/atlas:mine-data
collect the real constraints/gotchas of my scanned systems	/atlas:collect-nuances

3. The need → real atlas pipeline (core method)

1. Parse sources — interpret the stated need into concrete SOURCES: Azure subscription(s), git repos, local directories, URLs, plus the output dir. If the sources are genuinely ambiguous, run a short interview (AskUserQuestion). Per repo policy, interview ONLY when truly unclear.
2. Scan cloud (primary) — for each Azure source, run read-only az and write a real cloud inventory citing resource ids/RGs. Skip cleanly (record a reason) if no cloud source is in scope — only scan what's named.
3. Scan local (primary) — for each repo/dir, scan the filesystem + git (structure, submodules, manifests, languages, services, IaC) and write a real inventory citing real paths.
4. Enrich (secondary) — map the discovered real systems against the Atlas graph for comparison context. Clearly secondary; never the headline.
5. Synthesize — assemble a real, cross-linked layered atlas (components / processes / data / integrations / nuances) where EVERY item cites its real source, like SYSTEMS-ATLAS.md, plus a machine mirror.
6. Converge (TDD) — each phase asserts its own checkable outputs before proceeding (see the atlas processes), iterating until the assertions pass.

4. How to delegate

For any non-trivial run, hand off to babysitter:babysit (via the Skill tool) naming the matching atlas process:

• /atlas:discover → atlas-systems-discovery
• /atlas:mine-processes → atlas-process-mining
• /atlas:mine-data → atlas-data-mining
• /atlas:collect-nuances → atlas-collect-nuances

Do not hand-roll orchestration when a process exists.

5. Guardrails

• No fallbacks (repo rule). Skipping an out-of-scope source class (e.g. no cloud named) is correct scoping and must be recorded with a reason — it is NOT a silent fallback to the public graph. If you find yourself writing a real fallback, stop and fix the root cause.
• Scan-first: every system/item in the atlas MUST cite a REAL source (an az resource id / RG, or a file path). Never invent resource ids, regions, SKUs, or file paths. Never invent graph node ids either — only reference ids returned by the Atlas tools, and keep graph content strictly secondary.
• Read-only scanning only: az read verbs, git status/remote/log, filesystem reads. Never run mutating cloud/git/fs commands and never read secret values.
• Keep breakpoints sparse; use them only when the sources to scan are genuinely ambiguous.
• The real scanning is done BY the agent via its Bash tool inside the agent task prompt. Do not emit kind: 'shell' subtasks unless the user explicitly asks for a shell-oriented workflow.