@a5c-ai/atlas-codex 5.1.1-staging.5fdee5a9ea21 → 5.1.1-staging.776f6e05efe8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/.codex-plugin/plugin.json +1 -1
  2. package/bin/install-shared.js +1 -1
  3. package/package.json +1 -1
  4. package/skills/atlas/SKILL.md +67 -41
  5. package/skills/atlas-graph-query/SKILL.md +14 -4
  6. package/skills/collect-nuances/SKILL.md +4 -2
  7. package/skills/discover/SKILL.md +4 -2
  8. package/skills/mine-data/SKILL.md +4 -2
  9. package/skills/mine-processes/SKILL.md +4 -2
package/.codex-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "atlas",
3
- "version": "5.1.1-staging.5fdee5a9ea21",
3
+ "version": "5.1.1-staging.776f6e05efe8",
4
4
  "description": "Turn a stated need into a full system design by mining the Atlas knowledge graph.",
5
5
  "author": {
6
6
  "name": "a5c.ai",
package/bin/install-shared.js CHANGED
@@ -104,7 +104,7 @@ function ensureMarketplaceEntry(marketplacePath, pluginRoot) {
104
104
  name: PLUGIN_NAME,
105
105
  source: relSource,
106
106
  description: "Turn a stated need into a full system design by mining the Atlas knowledge graph.",
107
- version: "5.1.1-staging.5fdee5a9ea21",
107
+ version: "5.1.1-staging.776f6e05efe8",
108
108
  author: { name: "a5c.ai" },
109
109
  };
110
110
  if (idx >= 0) marketplace.plugins[idx] = entry;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@a5c-ai/atlas-codex",
3
- "version": "5.1.1-staging.5fdee5a9ea21",
3
+ "version": "5.1.1-staging.776f6e05efe8",
4
4
  "description": "Turn a stated need into a full system design by mining the Atlas knowledge graph.",
5
5
  "scripts": {
6
6
  "test": "npm run validate:ci",
package/skills/atlas/SKILL.md CHANGED
@@ -1,56 +1,74 @@
1
1
  ---
2
2
  name: atlas
3
3
  description: >
4
- Turn a stated need into a full system design by mining the Atlas knowledge
5
- graph. Use this skill when asked to design a system from a goal, discover the
6
- components/processes/data a domain needs, mine processes or data models, or
7
- collect domain nuances. (atlas, design a system, what does X need, system
8
- discovery, process mining, data mining, collect nuances, blueprint from a need,
9
- graph-driven design)
4
+ Atlas turns your STATED NEED into a real systems atlas by SCANNING your actual
5
+ sources (Azure via `az`, git repos, local dirs) and process/data mining them,
6
+ THEN enriching against the Atlas knowledge graph. Use this skill when asked to
7
+ inventory/map your real systems, scan your cloud + repos + directories, mine the
8
+ real processes or data they contain, or collect their real constraints/gotchas.
9
+ (atlas, scan my systems, inventory our azure account, map my repos, real systems
10
+ atlas, process mining, data mining, collect nuances, system discovery)
10
11
  allowed-tools: Read, Grep, Glob, Write, Edit, Task, Bash, AskUserQuestion, TodoWrite, Skill, mcp__atlas__atlas_public_search, mcp__atlas__atlas_public_record, mcp__atlas__atlas_public_neighbors, mcp__atlas__atlas_public_kinds, mcp__atlas__atlas_public_kind, mcp__atlas__atlas_public_clusters, mcp__atlas__atlas_public_stats, mcp__atlas__atlas_public_wiki_page
11
12
  version: 0.1.0
12
13
  ---
13
14
 
14
15
  # atlas
15
16
 
16
- This skill turns a stated need into an entire system design by mining the Atlas
17
- knowledge graph. It is the brain of the `atlas` plugin. For non-trivial runs it
18
- delegates orchestration to `babysitter:babysit` using an atlas-specific `.a5c`
19
- process; for simple lookups it queries the graph directly.
17
+ This skill turns a stated need into a **real systems atlas** by SCANNING your
18
+ actual sources — Azure subscriptions (via read-only `az`), git repos, and local
19
+ directories — and process/data mining them, THEN enriching the result against the
20
+ Atlas knowledge graph. It is the brain of the `atlas` plugin. The scan is
21
+ PRIMARY; the graph is SECONDARY. For non-trivial runs it delegates orchestration
22
+ to `babysitter:babysit` using an atlas-specific `.a5c` process; for simple
23
+ lookups it queries the graph directly.
20
24
 
21
- ## 1. What Atlas is
25
+ ## 1. Scan-first, graph-second
22
26
 
23
- Atlas is a knowledge graph of agents, processes, data models, capabilities,
24
- workflows, clusters, and wiki pages. You reach it through the
25
- `mcp__atlas__atlas_public_*` MCP tools, which this plugin wires natively into
26
- your harness (see the plugin README "Atlas MCP" section; the server URL is
27
- overridable via `ATLAS_MCP_URL`). Never assume the graph's shape — discover it
28
- through the tools.
27
+ The output you want is an evidence-backed inventory of **your** systems — e.g.
28
+ `azure-inventory.json` (every real resource id + RG from `az`),
29
+ `workspace-inventory.json` (real repo/dir scan), `processes.json` (real mined
30
+ CI/CD/IaC/.a5c processes), and a cross-linked `SYSTEMS-ATLAS.md`. Every item must
31
+ cite its REAL source. Generic catalog nodes are NOT the deliverable.
32
+
33
+ - **Primary — scan the user's real sources.** Use `Bash` to run READ-ONLY scans:
34
+ `az` (account/group/resource list + per-service list/show) for Azure;
35
+ `git` + filesystem (`Read`/`Glob`) for repos and directories. NEVER invent
36
+ resource ids, regions, SKUs, or file paths — if you didn't observe it in real
37
+ output, it does not go in the atlas. Only scan the sources named in the need
38
+ (scoping, not a fallback).
39
+ - **Secondary — the Atlas knowledge graph.** Atlas is a knowledge graph of
40
+ agents, processes, data models, capabilities, workflows, and wiki pages reached
41
+ through the `mcp__atlas__atlas_public_*` MCP tools (server URL overridable via
42
+ `ATLAS_MCP_URL`). Use it ONLY to add best-practice / comparison context for the
43
+ real systems you found — never as the primary content, never to pad the atlas
44
+ with generic nodes. See the `atlas-graph-query` skill for the tool surface.
29
45
 
30
46
  ## 2. When to use
31
47
 
32
48
  | Trigger phrase | Command |
33
49
  |----------------|---------|
34
- | design a system, blueprint from a need, graph-driven design | `/atlas:discover` |
35
- | process mining, what processes does X need | `/atlas:mine-processes` |
36
- | data mining, what data does X need | `/atlas:mine-data` |
37
- | collect nuances, edge cases/constraints for X | `/atlas:collect-nuances` |
50
+ | scan/inventory my real systems (azure + repos + dirs), map them | `/atlas:discover` |
51
+ | mine the real processes in my repos/cloud (CI/CD, IaC, .a5c, cron) | `/atlas:mine-processes` |
52
+ | mine the real data stores/models in my cloud + repos | `/atlas:mine-data` |
53
+ | collect the real constraints/gotchas of my scanned systems | `/atlas:collect-nuances` |
38
54
 
39
- ## 3. The need → design pipeline (core method)
55
+ ## 3. The need → real atlas pipeline (core method)
40
56
 
41
- 1. **Frame the need** — restate the goal as a domain + concrete outcomes. If the
42
- request is ambiguous, run a short interview (`AskUserQuestion`). Per repo
43
- policy, interview ONLY when requirements are genuinely unclear.
44
- 2. **Locate anchors** — `atlas_public_search(q=<need terms>)` to find seed nodes;
45
- `atlas_public_clusters` / `atlas_public_kinds` to scope the domain.
46
- 3. **Expand the graph** — `atlas_public_neighbors(id, depth, edges, kinds)` from
47
- the anchors to gather the system's parts: components, workflows, processes,
48
- data models, capabilities.
49
- 4. **Read detail** — `atlas_public_record(id, expandNeighbors)` for fields and
50
- edges; `atlas_public_wiki_page` for narrative context.
51
- 5. **Synthesize the design** — assemble the discovered nodes into a layered
52
- system design (components, processes, data, integrations, nuances) and write a
53
- design artifact under `.a5c/atlas/<run>/design.md` plus a machine mirror.
57
+ 1. **Parse sources** — interpret the stated need into concrete SOURCES: Azure
58
+ subscription(s), git repos, local directories, URLs, plus the output dir. If
59
+ the sources are genuinely ambiguous, run a short interview
60
+ (`AskUserQuestion`). Per repo policy, interview ONLY when truly unclear.
61
+ 2. **Scan cloud (primary)** — for each Azure source, run read-only `az` and write
62
+ a real cloud inventory citing resource ids/RGs. Skip cleanly (record a reason)
63
+ if no cloud source is in scope — only scan what's named.
64
+ 3. **Scan local (primary)** — for each repo/dir, scan the filesystem + git
65
+ (structure, submodules, manifests, languages, services, IaC) and write a real
66
+ inventory citing real paths.
67
+ 4. **Enrich (secondary)** — map the discovered real systems against the Atlas
68
+ graph for comparison context. Clearly secondary; never the headline.
69
+ 5. **Synthesize** — assemble a real, cross-linked layered atlas (components /
70
+ processes / data / integrations / nuances) where EVERY item cites its real
71
+ source, like `SYSTEMS-ATLAS.md`, plus a machine mirror.
54
72
  6. **Converge (TDD)** — each phase asserts its own checkable outputs before
55
73
  proceeding (see the atlas processes), iterating until the assertions pass.
56
74
 
@@ -68,10 +86,18 @@ Do not hand-roll orchestration when a process exists.
68
86
 
69
87
  ## 5. Guardrails
70
88
 
71
- - No fallbacks (repo rule). If you find yourself writing a fallback, stop and fix
72
- the root cause.
73
- - Never invent graph node ids — only reference ids returned by Atlas tools.
74
- - Keep breakpoints sparse; use them only when user input is genuinely critical or
89
+ - No fallbacks (repo rule). Skipping an out-of-scope source class (e.g. no cloud
90
+ named) is correct scoping and must be recorded with a reason — it is NOT a
91
+ silent fallback to the public graph. If you find yourself writing a real
92
+ fallback, stop and fix the root cause.
93
+ - Scan-first: every system/item in the atlas MUST cite a REAL source (an `az`
94
+ resource id / RG, or a file path). Never invent resource ids, regions, SKUs, or
95
+ file paths. Never invent graph node ids either — only reference ids returned by
96
+ the Atlas tools, and keep graph content strictly secondary.
97
+ - Read-only scanning only: `az` read verbs, `git` status/remote/log, filesystem
98
+ reads. Never run mutating cloud/git/fs commands and never read secret values.
99
+ - Keep breakpoints sparse; use them only when the sources to scan are genuinely
75
100
  ambiguous.
76
- - Do not emit `kind: 'shell'` subtasks unless the user explicitly asks for a
77
- shell-oriented workflow.
101
+ - The real scanning is done BY the agent via its `Bash` tool inside the agent
102
+ task prompt. Do not emit `kind: 'shell'` subtasks unless the user explicitly
103
+ asks for a shell-oriented workflow.
package/skills/atlas-graph-query/SKILL.md CHANGED
@@ -1,10 +1,12 @@
1
1
  ---
2
2
  name: atlas-graph-query
3
3
  description: >
4
- Reference for querying the Atlas knowledge graph through its MCP tools. Use
5
- when you need to look up nodes, edges, kinds, clusters, stats, or wiki pages in
6
- Atlas. (atlas graph, query atlas, atlas mcp, search the graph, graph neighbors,
7
- atlas record, atlas kinds)
4
+ Reference for querying the Atlas knowledge graph through its MCP tools — the
5
+ SECONDARY enrichment/comparison layer that adds best-practice context to systems
6
+ you have ALREADY scanned from your real sources (`az`, repos, dirs). Use when
7
+ you need to look up nodes, edges, kinds, clusters, stats, or wiki pages in Atlas
8
+ to compare against your real inventory. (atlas graph, query atlas, atlas mcp,
9
+ search the graph, graph neighbors, atlas record, atlas kinds, enrichment layer)
8
10
  allowed-tools: mcp__atlas__atlas_public_search, mcp__atlas__atlas_public_record, mcp__atlas__atlas_public_neighbors, mcp__atlas__atlas_public_kinds, mcp__atlas__atlas_public_kind, mcp__atlas__atlas_public_edge_kinds, mcp__atlas__atlas_public_edge_kind, mcp__atlas__atlas_public_clusters, mcp__atlas__atlas_public_stats, mcp__atlas__atlas_public_wiki_page
9
11
  version: 0.1.0
10
12
  ---
@@ -16,6 +18,14 @@ A thin reference for the Atlas knowledge-graph MCP tool surface so any agent
16
18
  server URL is wired natively by the `atlas` plugin and is overridable via
17
19
  `ATLAS_MCP_URL`. Never invent node ids — only use ids returned by these tools.
18
20
 
21
+ > **Position: this is the SECONDARY / enrichment layer.** The `atlas` plugin is
22
+ > scan-first — it inventories your REAL systems by scanning your actual sources
23
+ > (Azure via read-only `az`, git repos, local directories) and process/data
24
+ > mining them. The graph queries below are used ONLY to add best-practice /
25
+ > comparison context to those already-discovered real systems. Do NOT use the
26
+ > graph as the primary content, and never pad a real inventory with generic
27
+ > catalog nodes. Tie every graph lookup back to a real scanned system.
28
+
19
29
  ## Tools
20
30
 
21
31
  ### `mcp__atlas__atlas_public_search`
package/skills/collect-nuances/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: collect-nuances
3
- description: Collect nuances — gather domain-specific edge cases, constraints, and gotchas from the Atlas graph.
3
+ description: Collect the REAL constraints/gotchas of your scanned systems (IaC drift, orphaned resources, RBAC quirks, region splits), each cited; Atlas-graph comparison secondary.
4
4
  ---
5
5
 
6
6
  # collect-nuances
@@ -11,7 +11,9 @@ Invoke the babysitter:babysit skill (using the Skill tool) and follow its instru
11
11
  ${PLUGIN_ROOT}/processes/atlas-collect-nuances.mjs#process
12
12
  ```
13
13
 
14
- (e.g. `babysitter run:create --process-id atlas-collect-nuances --entry "${PLUGIN_ROOT}/processes/atlas-collect-nuances.mjs#process" --harness <this-harness>`, then iterate.) Pass the user arguments below as the run's stated need / process inputs. Continue executing in this same turn; do not stop after the Skill tool returns. Use the atlas skill and the Atlas MCP tools (mcp__atlas__atlas_public_*) for all graph queries.
14
+ (e.g. `babysitter run:create --process-id atlas-collect-nuances --entry "${PLUGIN_ROOT}/processes/atlas-collect-nuances.mjs#process" --harness <this-harness>`, then iterate.) Pass the user arguments below as the run's stated need / process inputs. Continue executing in this same turn; do not stop after the Skill tool returns.
15
+
16
+ This process is SCAN-FIRST: it parses the stated sources, then runs READ-ONLY scans (Bash `az` + git/fs) of the user's REAL systems to collect actual constraints/gotchas/edge-cases — IaC-as-survey drift, orphaned cloud resources, RBAC/visibility quirks, region splits, tenant/descriptor mismatches, externally-deployed systems with no in-repo pipeline — each cited to its real resource id / RG / file path (or a concrete missing-thing observation). The Atlas knowledge graph (mcp__atlas__atlas_public_*) is used only as SECONDARY comparison. Never invent constraints; only inspect the sources named in the arguments.
15
17
 
16
18
  User arguments for this command:
17
19
 
package/skills/discover/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: discover
3
- description: Interactive systems discovery — turn a stated need into a full system design via the Atlas graph.
3
+ description: Scan your real systems (Azure + repos + dirs) and map them into a layered, source-cited atlas; enrich against the Atlas graph (secondary).
4
4
  ---
5
5
 
6
6
  # discover
@@ -11,7 +11,9 @@ Invoke the babysitter:babysit skill (using the Skill tool) and follow its instru
11
11
  ${PLUGIN_ROOT}/processes/atlas-systems-discovery.mjs#process
12
12
  ```
13
13
 
14
- (e.g. `babysitter run:create --process-id atlas-systems-discovery --entry "${PLUGIN_ROOT}/processes/atlas-systems-discovery.mjs#process" --harness <this-harness>`, then iterate.) Pass the user arguments below as the run's stated need / process inputs. Continue executing in this same turn; do not stop after the Skill tool returns. Use the atlas skill and the Atlas MCP tools (mcp__atlas__atlas_public_*) for all graph queries.
14
+ (e.g. `babysitter run:create --process-id atlas-systems-discovery --entry "${PLUGIN_ROOT}/processes/atlas-systems-discovery.mjs#process" --harness <this-harness>`, then iterate.) Pass the user arguments below as the run's stated need / process inputs. Continue executing in this same turn; do not stop after the Skill tool returns.
15
+
16
+ This process is SCAN-FIRST: it parses the stated sources, then runs READ-ONLY scans of the user's REAL systems — Azure via `az` (Bash), git repos, and local directories — and synthesizes a cross-linked, source-cited atlas where every item cites a real resource id / RG / file path. The Atlas knowledge graph (mcp__atlas__atlas_public_*) is used only as SECONDARY enrichment/comparison, never as the primary content. Never invent resource ids or file paths; only scan the sources named in the arguments.
15
17
 
16
18
  User arguments for this command:
17
19
 
package/skills/mine-data/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: mine-data
3
- description: Data mining — discover the data models/entities a domain requires from the Atlas graph.
3
+ description: Mine the REAL data stores/models in your sources (cloud DBs via az, schemas/migrations, package types), each cited; Atlas-graph comparison secondary.
4
4
  ---
5
5
 
6
6
  # mine-data
@@ -11,7 +11,9 @@ Invoke the babysitter:babysit skill (using the Skill tool) and follow its instru
11
11
  ${PLUGIN_ROOT}/processes/atlas-data-mining.mjs#process
12
12
  ```
13
13
 
14
- (e.g. `babysitter run:create --process-id atlas-data-mining --entry "${PLUGIN_ROOT}/processes/atlas-data-mining.mjs#process" --harness <this-harness>`, then iterate.) Pass the user arguments below as the run's stated need / process inputs. Continue executing in this same turn; do not stop after the Skill tool returns. Use the atlas skill and the Atlas MCP tools (mcp__atlas__atlas_public_*) for all graph queries.
14
+ (e.g. `babysitter run:create --process-id atlas-data-mining --entry "${PLUGIN_ROOT}/processes/atlas-data-mining.mjs#process" --harness <this-harness>`, then iterate.) Pass the user arguments below as the run's stated need / process inputs. Continue executing in this same turn; do not stop after the Skill tool returns.
15
+
16
+ This process is SCAN-FIRST: it parses the stated sources, then runs READ-ONLY scans to mine the REAL data — cloud databases/storage/AI-Search via `az` (Bash), and schemas/migrations/ORM models/package types in the repos/dirs — binding models to the stores that back them, each cited to its real resource id / file path. The Atlas knowledge graph (mcp__atlas__atlas_public_*) is used only as SECONDARY comparison. Never invent stores or models; only mine the sources named in the arguments. Never read secret values.
15
17
 
16
18
  User arguments for this command:
17
19
 
package/skills/mine-processes/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: mine-processes
3
- description: Process mining — discover the processes/workflows a domain requires from the Atlas graph.
3
+ description: Mine the REAL processes in your sources (CI/CD, npm scripts, IaC, Dockerfiles, .a5c, cron), each cited to its file; Atlas-graph comparison secondary.
4
4
  ---
5
5
 
6
6
  # mine-processes
@@ -11,7 +11,9 @@ Invoke the babysitter:babysit skill (using the Skill tool) and follow its instru
11
11
  ${PLUGIN_ROOT}/processes/atlas-process-mining.mjs#process
12
12
  ```
13
13
 
14
- (e.g. `babysitter run:create --process-id atlas-process-mining --entry "${PLUGIN_ROOT}/processes/atlas-process-mining.mjs#process" --harness <this-harness>`, then iterate.) Pass the user arguments below as the run's stated need / process inputs. Continue executing in this same turn; do not stop after the Skill tool returns. Use the atlas skill and the Atlas MCP tools (mcp__atlas__atlas_public_*) for all graph queries.
14
+ (e.g. `babysitter run:create --process-id atlas-process-mining --entry "${PLUGIN_ROOT}/processes/atlas-process-mining.mjs#process" --harness <this-harness>`, then iterate.) Pass the user arguments below as the run's stated need / process inputs. Continue executing in this same turn; do not stop after the Skill tool returns.
15
+
16
+ This process is SCAN-FIRST: it parses the stated sources, then runs READ-ONLY scans (Bash) of the REAL repos/dirs/cloud automation and mines the processes that actually exist — `.github/workflows`, npm scripts, terraform/bicep/helm/k8s, Dockerfiles, babysitter `.a5c` processes, and cron/scheduled jobs — each cited to its real file path. The Atlas knowledge graph (mcp__atlas__atlas_public_*) is used only as SECONDARY comparison. Never invent files or processes; only mine the sources named in the arguments.
15
17
 
16
18
  User arguments for this command:
17
19