@a5c-ai/atlas-genty 5.0.1-staging.28347f861706

package/AGENTS.md

@@ -0,0 +1,6 @@
+# AGENTS.md
+
+This file was generated by @a5c-ai/extensions-adapter for target `genty`.
+
+The plugin manifest for `atlas` does not declare a dedicated AGENTS.md source file.
+Add `agents` and/or `contextFiles.genty` in `plugin.json` to replace this placeholder with real target guidance.

package/README.md

@@ -0,0 +1,35 @@
+# Atlas Plugin for Genty
+
+Atlas turns a stated need into a full system design by mining the Atlas
+knowledge graph. This is the Genty harness surface for the `atlas` plugin.
+
+## What's Included
+
+- **Skills**: `atlas` (the need → design brain) and `atlas-graph-query`
+  (a reference for the Atlas MCP tool surface).
+- **Commands**: `/atlas:discover`, `/atlas:mine-processes`,
+  `/atlas:mine-data`, `/atlas:collect-nuances` — each delegates orchestration
+  to the `babysitter:babysit` skill using an atlas-specific `.a5c` process.
+- **MCP**: the Atlas knowledge-graph server (`atlas`), wired natively into
+  Genty's own MCP config format.
+
+## Atlas MCP
+
+The Atlas MCP server is wired natively for Genty — no manual setup. It
+defaults to `https://atlas-staging.a5c.ai/api/mcp` and is overridable at
+runtime via the `ATLAS_MCP_URL` environment variable. The
+`mcp__atlas__atlas_public_*` tools are then available to the atlas skills.
+
+## Installation
+
+Atlas commands delegate orchestration to Babysitter, so install the Babysitter
+CLI once, then install this plugin for Genty:
+
+```bash
+npm install -g @a5c-ai/babysitter
+babysitter harness:install-plugin genty
+```
+
+## License
+
+See the repository license.

package/bin/cli.cjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+let shared;
+try { shared = require('./install-shared'); } catch {}
+
+function printUsage() {
+  console.error([
+    'Usage:',
+    '  atlas-genty install [--global]',
+    '  atlas-genty install --workspace [path]',
+    '  atlas-genty uninstall',
+  ].join('\n'));
+}
+
+function parseInstallArgs(argv) {
+  let scope = 'global';
+  let workspace = null;
+  const passthrough = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--global') {
+      scope = 'global';
+      continue;
+    }
+    if (arg === '--workspace') {
+      scope = 'workspace';
+      const next = argv[i + 1];
+      if (next && !next.startsWith('-')) {
+        workspace = path.resolve(next);
+        i += 1;
+      } else {
+        workspace = process.cwd();
+      }
+      continue;
+    }
+    passthrough.push(arg);
+  }
+
+  return { scope, workspace, passthrough };
+}
+
+function runNodeScript(scriptPath, args, extraEnv = {}) {
+  const result = spawnSync(process.execPath, [scriptPath, ...args], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+    env: { ...process.env, ...extraEnv },
+  });
+  process.exitCode = result.status ?? 1;
+}
+
+function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || command === '--help' || command === '-h' || command === 'help') {
+    printUsage();
+    process.exitCode = command ? 0 : 1;
+    return;
+  }
+
+  if (command === 'install') {
+    if (shared && typeof shared.harnessCliRoute === 'function' && shared.harnessCliRoute(rest, PACKAGE_ROOT, runNodeScript)) {
+      return;
+    }
+    const parsed = parseInstallArgs(rest);
+    if (parsed.scope === 'workspace') {
+      const args = [];
+      if (parsed.workspace) {
+        args.push('--workspace', parsed.workspace);
+      }
+      args.push(...parsed.passthrough);
+      runNodeScript(
+        path.join(PACKAGE_ROOT, 'scripts', 'team-install.cjs'),
+        args,
+        { PLUGIN_PACKAGE_ROOT: PACKAGE_ROOT },
+      );
+      return;
+    }
+    runNodeScript(path.join(PACKAGE_ROOT, 'bin', 'install.cjs'), parsed.passthrough);
+    return;
+  }
+
+  if (command === 'uninstall') {
+    runNodeScript(path.join(PACKAGE_ROOT, 'bin', 'uninstall.cjs'), rest);
+    return;
+  }
+
+  printUsage();
+  process.exitCode = 1;
+}
+
+main();

package/bin/install-shared.cjs

@@ -0,0 +1,156 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PLUGIN_NAME = "atlas";
+const PLUGIN_CATEGORY = 'Coding';
+
+function getUserHome() {
+  return os.homedir();
+}
+
+function getHarnessHome() {
+  return path.join(os.homedir(), '.a5c');
+}
+
+function getHomePluginRoot(scope) {
+  if (scope === 'workspace') return path.join(process.cwd(), '.a5c', 'plugins', PLUGIN_NAME);
+  return path.join(path.join(getHarnessHome(), 'plugins'), PLUGIN_NAME);
+}
+
+function getHomeMarketplacePath() {
+  return path.join(getHarnessHome(), 'plugins', 'marketplace.json');
+}
+
+function writeFileIfChanged(filePath, contents) {
+  try {
+    const existing = fs.readFileSync(filePath, 'utf8');
+    if (existing === contents) return false;
+  } catch (e) { process.stderr.write('[extensions-adapter] file read failed for ' + filePath + ', overwriting: ' + (e instanceof Error ? e.message : String(e)) + '\n'); }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, contents);
+  return true;
+}
+
+function copyRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyRecursive(s, d);
+    } else {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function copyPluginBundle(packageRoot, pluginRoot) {
+  const bundleEntries = fs.readdirSync(packageRoot).filter(
+    e => !['node_modules', '.git', 'test', 'dist'].includes(e)
+  );
+  fs.mkdirSync(pluginRoot, { recursive: true });
+  for (const entry of bundleEntries) {
+    const src = path.join(packageRoot, entry);
+    const dest = path.join(pluginRoot, entry);
+    const stat = fs.statSync(src);
+    if (stat.isDirectory()) {
+      copyRecursive(src, dest);
+    } else {
+      fs.copyFileSync(src, dest);
+    }
+  }
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2) + '\n');
+}
+
+function ensureExecutable(filePath) {
+  try {
+    fs.chmodSync(filePath, 0o755);
+  } catch (e) { process.stderr.write('[extensions-adapter] chmod failed for ' + filePath + ': ' + (e instanceof Error ? e.message : String(e)) + '\n'); }
+}
+
+function normalizeMarketplaceSourcePath(source, marketplacePath) {
+  if (typeof source === 'string') {
+    return path.relative(path.dirname(marketplacePath), source).replace(/\\/g, '/');
+  }
+  return source;
+}
+
+function ensureMarketplaceEntry(marketplacePath, pluginRoot) {
+  let marketplace = readJson(marketplacePath) || {
+    name: "a5c.ai",
+    plugins: [],
+  };
+  if (!Array.isArray(marketplace.plugins)) marketplace.plugins = [];
+  const idx = marketplace.plugins.findIndex(p => p.name === PLUGIN_NAME);
+  const relSource = './' + normalizeMarketplaceSourcePath(pluginRoot, marketplacePath);
+  const entry = {
+    name: PLUGIN_NAME,
+    source: relSource,
+    description: "Turn a stated need into a full system design by mining the Atlas knowledge graph.",
+    version: "5.0.1-staging.28347f861706",
+    author: { name: "a5c.ai" },
+  };
+  if (idx >= 0) marketplace.plugins[idx] = entry;
+  else marketplace.plugins.push(entry);
+  writeJson(marketplacePath, marketplace);
+}
+
+function removeMarketplaceEntry(marketplacePath) {
+  const marketplace = readJson(marketplacePath);
+  if (!marketplace || !Array.isArray(marketplace.plugins)) return;
+  marketplace.plugins = marketplace.plugins.filter(p => p.name !== PLUGIN_NAME);
+  writeJson(marketplacePath, marketplace);
+}
+
+function warnWindowsHooks() {
+  if (process.platform === 'win32') {
+    console.warn('[' + PLUGIN_NAME + '] Windows detected — shell hooks (.sh) require Git Bash or WSL.');
+  }
+}
+
+function runPostInstall(pluginRoot) {
+  const postInstall = path.join(pluginRoot, 'scripts', 'post-install.js');
+  if (fs.existsSync(postInstall)) {
+    spawnSync(process.execPath, [postInstall], {
+      cwd: pluginRoot, stdio: 'inherit',
+      env: { ...process.env, PLUGIN_ROOT: pluginRoot, CLAUDE_PLUGIN_ROOT: pluginRoot },
+    });
+  }
+}
+
+module.exports = {
+  PLUGIN_NAME,
+  PLUGIN_CATEGORY,
+  getUserHome,
+  getHarnessHome,
+  getHomePluginRoot,
+  getHomeMarketplacePath,
+  writeFileIfChanged,
+  copyRecursive,
+  copyPluginBundle,
+  readJson,
+  writeJson,
+  ensureExecutable,
+  normalizeMarketplaceSourcePath,
+  ensureMarketplaceEntry,
+  removeMarketplaceEntry,
+  warnWindowsHooks,
+  runPostInstall,
+};

package/bin/install.cjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const shared = require('./install-shared');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+function main() {
+  const pluginRoot = shared.getHomePluginRoot();
+  const marketplacePath = shared.getHomeMarketplacePath();
+
+  console.log(`[${shared.PLUGIN_NAME}] Installing plugin to ${pluginRoot}`);
+
+  try {
+    shared.copyPluginBundle(PACKAGE_ROOT, pluginRoot);
+    shared.ensureMarketplaceEntry(marketplacePath, pluginRoot);
+    if (typeof shared.harnessInstall === 'function') {
+      shared.harnessInstall(PACKAGE_ROOT, pluginRoot);
+    }
+    shared.runPostInstall && shared.runPostInstall(pluginRoot);
+    console.log(`[${shared.PLUGIN_NAME}] Installation complete!`);
+    console.log(`[${shared.PLUGIN_NAME}] Restart your IDE/CLI to pick up the plugin.`);
+  } catch (err) {
+    console.error(`[${shared.PLUGIN_NAME}] Failed to install: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+main();

package/bin/uninstall.cjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const shared = require('./install-shared');
+
+function main() {
+  const pluginRoot = shared.getHomePluginRoot();
+
+  if (!fs.existsSync(pluginRoot)) {
+    console.log(`[${shared.PLUGIN_NAME}] Plugin not installed at ${pluginRoot}`);
+    return;
+  }
+
+  try {
+    fs.rmSync(pluginRoot, { recursive: true, force: true });
+    console.log(`[${shared.PLUGIN_NAME}] Uninstalled from ${pluginRoot}`);
+  } catch (err) {
+    console.error(`[${shared.PLUGIN_NAME}] Failed to uninstall: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+main();

package/commands/collect-nuances.md

@@ -0,0 +1,11 @@
+---
+description: Collect nuances — gather domain-specific edge cases, constraints, and gotchas from the Atlas graph.
+argument-hint: The domain/system to collect nuances for.
+allowed-tools: Read, Grep, Write, Task, Bash, Edit, Glob, 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_clusters, mcp__atlas__atlas_public_wiki_page
+---
+
+Invoke the babysitter:babysit skill (using the Skill tool) and follow its instructions (SKILL.md) to run the atlas process `atlas-collect-nuances`. Pass the user arguments below as the run's stated need. Then continue executing the returned instructions 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.
+
+User arguments for this command:
+
+$ARGUMENTS

package/commands/discover.md

@@ -0,0 +1,11 @@
+---
+description: Interactive systems discovery — turn a stated need into a full system design via the Atlas graph.
+argument-hint: The system/need to design.
+allowed-tools: Read, Grep, Write, Task, Bash, Edit, Glob, 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_clusters, mcp__atlas__atlas_public_wiki_page
+---
+
+Invoke the babysitter:babysit skill (using the Skill tool) and follow its instructions (SKILL.md) to run the atlas process `atlas-systems-discovery`. Pass the user arguments below as the run's stated need. Then continue executing the returned instructions 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.
+
+User arguments for this command:
+
+$ARGUMENTS

package/commands/mine-data.md

@@ -0,0 +1,11 @@
+---
+description: Data mining — discover the data models/entities a domain requires from the Atlas graph.
+argument-hint: The domain or goal to mine data for.
+allowed-tools: Read, Grep, Write, Task, Bash, Edit, Glob, 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_clusters, mcp__atlas__atlas_public_wiki_page
+---
+
+Invoke the babysitter:babysit skill (using the Skill tool) and follow its instructions (SKILL.md) to run the atlas process `atlas-data-mining`. Pass the user arguments below as the run's stated need. Then continue executing the returned instructions 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.
+
+User arguments for this command:
+
+$ARGUMENTS

package/commands/mine-processes.md

@@ -0,0 +1,11 @@
+---
+description: Process mining — discover the processes/workflows a domain requires from the Atlas graph.
+argument-hint: The domain or goal to mine processes for.
+allowed-tools: Read, Grep, Write, Task, Bash, Edit, Glob, 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_clusters, mcp__atlas__atlas_public_wiki_page
+---
+
+Invoke the babysitter:babysit skill (using the Skill tool) and follow its instructions (SKILL.md) to run the atlas process `atlas-process-mining`. Pass the user arguments below as the run's stated need. Then continue executing the returned instructions 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.
+
+User arguments for this command:
+
+$ARGUMENTS

package/extensions/index.ts

@@ -0,0 +1,37 @@
+// Programmatic extension for genty
+// Generated by extensions-adapter compiler
+
+import { execSync } from "child_process";
+import * as path from "path";
+
+const PLUGIN_ROOT = path.resolve(__dirname, "..");
+
+function runProxiedHook(
+  scriptName: string,
+  inputData?: Record<string, unknown>
+): Record<string, unknown> {
+  const scriptPath = path.join(PLUGIN_ROOT, "hooks", scriptName);
+  try {
+    const result = execSync(`node "${scriptPath}"`, {
+      input: inputData ? JSON.stringify(inputData) : undefined,
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 30000,
+      env: {
+        ...process.env,
+        GENTY_PLUGIN_ROOT: PLUGIN_ROOT,
+        CLAUDE_PLUGIN_ROOT: PLUGIN_ROOT,
+      },
+    });
+    return JSON.parse(result.toString("utf8").trim());
+  } catch {
+    return {};
+  }
+}
+
+const COMMANDS = [
+  "atlas-graph-query", "collect-nuances", "discover", "mine-data", "mine-processes"
+] as const;
+
+export function activate(api: unknown): void {
+  // Register commands via target-specific API
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@a5c-ai/atlas-genty",
+  "version": "5.0.1-staging.28347f861706",
+  "type": "module",
+  "description": "Turn a stated need into a full system design by mining the Atlas knowledge graph. — genty",
+  "keywords": [
+    "genty",
+    "atlas",
+    "orchestration"
+  ],
+  "genty": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@a5c-ai/genty-core": "*"
+  },
+  "scripts": {
+    "test": "npm run validate:ci",
+    "test:integration": "node --test test/integration.test.js",
+    "test:packaged-install": "node test/packaged-install.test.cjs",
+    "validate:ci": "npm run test:integration && npm run test:packaged-install",
+    "deploy": "npm publish --access public",
+    "deploy:staging": "npm publish --access public --tag staging"
+  },
+  "bin": {
+    "atlas-genty": "bin/cli.cjs"
+  },
+  "files": [
+    "bin/",
+    "package.json",
+    "versions.json",
+    "README.md",
+    "AGENTS.md",
+    "extensions/",
+    "skills/",
+    "commands/",
+    "scripts/"
+  ],
+  "author": "a5c.ai",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/a5c-ai/atlas-genty.git"
+  },
+  "homepage": "https://github.com/a5c-ai/atlas-genty#readme",
+  "bugs": {
+    "url": "https://github.com/a5c-ai/atlas-genty/issues"
+  }
+}

package/scripts/create-release-tag.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+
+function run(command, args) {
+  const result = spawnSync(command, args, { encoding: 'utf8', stdio: 'inherit' });
+  if (result.status !== 0) process.exit(result.status || 1);
+}
+
+const branch = process.env.GITHUB_REF_NAME || 'develop';
+const sha = (process.env.GITHUB_SHA || '').slice(0, 12);
+const version = existsSync('package.json') ? JSON.parse(readFileSync('package.json', 'utf8')).version : JSON.parse(readFileSync('versions.json', 'utf8')).sdkVersion;
+const normalized = String(version).replace(/[^0-9A-Za-z._-]/g, '-');
+const tag = 'release/' + branch + '/v' + normalized + '-' + sha;
+run('git', ['config', 'user.name', 'github-actions[bot]']);
+run('git', ['config', 'user.email', 'github-actions[bot]@users.noreply.github.com']);
+run('git', ['tag', tag]);
+run('git', ['push', 'origin', tag]);

package/scripts/publish-from-tag.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { stdio: options.stdio || 'inherit', encoding: options.encoding });
+  if (result.status !== 0 && !options.allowFailure) process.exit(result.status || 1);
+  return result;
+}
+
+function npmView(packageSpec) {
+  return run('npm', ['view', packageSpec, 'version'], { allowFailure: true, stdio: 'pipe', encoding: 'utf8' }).status === 0;
+}
+
+const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
+const ref = process.env.GITHUB_REF_NAME || '';
+const branch = ref.split('/')[1] || 'develop';
+const tag = branch === 'main' ? 'latest' : branch;
+
+if (!process.env.NODE_AUTH_TOKEN) {
+  console.log('NODE_AUTH_TOKEN is not configured; skipping npm publish.');
+  process.exit(0);
+}
+
+if (npmView(pkg.name + '@' + pkg.version)) {
+  console.log(pkg.name + '@' + pkg.version + ' already exists; ensuring dist-tag ' + tag + '.');
+  run('npm', ['dist-tag', 'add', pkg.name + '@' + pkg.version, tag], { allowFailure: true });
+  process.exit(0);
+}
+
+for (const field of ['dependencies', 'peerDependencies', 'optionalDependencies']) {
+  for (const [name, version] of Object.entries(pkg[field] || {})) {
+    if (!name.startsWith('@a5c-ai/') || version.startsWith('^') || version.startsWith('~') || version === '*' || version.startsWith('workspace:')) continue;
+    if (!npmView(name + '@' + version)) {
+      console.log('Required internal dependency ' + name + '@' + version + ' is not published yet; skipping npm publish.');
+      process.exit(0);
+    }
+  }
+}
+
+run('npm', ['publish', '--access', 'public', '--tag', tag]);

package/scripts/team-install.cjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+'use strict';
+
+var path = require('path');
+var shared = require('../bin/install-shared.cjs');
+
+var workspace = process.cwd();
+for (var i = 0; i < process.argv.length; i++) {
+  if (process.argv[i] === '--workspace' && process.argv[i + 1]) {
+    workspace = path.resolve(process.argv[i + 1]);
+  }
+}
+
+var src = process.env.PLUGIN_PACKAGE_ROOT || path.resolve(__dirname, '..');
+var dest = shared.getHomePluginRoot('workspace');
+console.log('[atlas] Team install to ' + dest);
+
+shared.copyPluginBundle(src, dest);
+if (typeof shared.harnessTeamInstall === 'function') {
+  shared.harnessTeamInstall(src, dest, workspace);
+}
+shared.runPostInstall(dest);
+console.log('[atlas] Team install complete.');

package/skills/atlas/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: atlas
+description: >
+  Turn a stated need into a full system design by mining the Atlas knowledge
+  graph. Use this skill when asked to design a system from a goal, discover the
+  components/processes/data a domain needs, mine processes or data models, or
+  collect domain nuances. (atlas, design a system, what does X need, system
+  discovery, process mining, data mining, collect nuances, blueprint from a need,
+  graph-driven design)
+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
+version: 0.1.0
+---
+
+# atlas
+
+This skill turns a stated need into an entire system design by mining the Atlas
+knowledge graph. It is the brain of the `atlas` plugin. 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. What Atlas is
+
+Atlas is a knowledge graph of agents, processes, data models, capabilities,
+workflows, clusters, and wiki pages. You reach it through the
+`mcp__atlas__atlas_public_*` MCP tools, which this plugin wires natively into
+your harness (see the plugin README "Atlas MCP" section; the server URL is
+overridable via `ATLAS_MCP_URL`). Never assume the graph's shape — discover it
+through the tools.
+
+## 2. When to use
+
+| Trigger phrase | Command |
+|----------------|---------|
+| design a system, blueprint from a need, graph-driven design | `/atlas:discover` |
+| process mining, what processes does X need | `/atlas:mine-processes` |
+| data mining, what data does X need | `/atlas:mine-data` |
+| collect nuances, edge cases/constraints for X | `/atlas:collect-nuances` |
+
+## 3. The need → design pipeline (core method)
+
+1. **Frame the need** — restate the goal as a domain + concrete outcomes. If the
+   request is ambiguous, run a short interview (`AskUserQuestion`). Per repo
+   policy, interview ONLY when requirements are genuinely unclear.
+2. **Locate anchors** — `atlas_public_search(q=<need terms>)` to find seed nodes;
+   `atlas_public_clusters` / `atlas_public_kinds` to scope the domain.
+3. **Expand the graph** — `atlas_public_neighbors(id, depth, edges, kinds)` from
+   the anchors to gather the system's parts: components, workflows, processes,
+   data models, capabilities.
+4. **Read detail** — `atlas_public_record(id, expandNeighbors)` for fields and
+   edges; `atlas_public_wiki_page` for narrative context.
+5. **Synthesize the design** — assemble the discovered nodes into a layered
+   system design (components, processes, data, integrations, nuances) and write a
+   design artifact under `.a5c/atlas/<run>/design.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). If you find yourself writing a fallback, stop and fix
+  the root cause.
+- Never invent graph node ids — only reference ids returned by Atlas tools.
+- Keep breakpoints sparse; use them only when user input is genuinely critical or
+  ambiguous.
+- Do not emit `kind: 'shell'` subtasks unless the user explicitly asks for a
+  shell-oriented workflow.

package/skills/atlas-graph-query/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: atlas-graph-query
+description: >
+  Reference for querying the Atlas knowledge graph through its MCP tools. Use
+  when you need to look up nodes, edges, kinds, clusters, stats, or wiki pages in
+  Atlas. (atlas graph, query atlas, atlas mcp, search the graph, graph neighbors,
+  atlas record, atlas kinds)
+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
+version: 0.1.0
+---
+
+# atlas-graph-query
+
+A thin reference for the Atlas knowledge-graph MCP tool surface so any agent
+(including sub-agents) can query the graph without re-deriving conventions. The
+server URL is wired natively by the `atlas` plugin and is overridable via
+`ATLAS_MCP_URL`. Never invent node ids — only use ids returned by these tools.
+
+## Tools
+
+### `mcp__atlas__atlas_public_search`
+Full-text/semantic search over the graph. Key params: `q` (query), optional
+`kind` filter, `limit`. Prefer it to find seed/anchor nodes from need terms.
+
+### `mcp__atlas__atlas_public_record`
+Fetch one node's full record by `id` (fields + edges). Use `expandNeighbors` to
+pull immediate relations in one call. Prefer it to read detail once you have ids.
+
+### `mcp__atlas__atlas_public_neighbors`
+Traverse the graph from a node. Key params: `id`, `depth`, `edges` (edge-kind
+filter), `kinds` (node-kind filter). Prefer it to expand a subsystem from anchors.
+
+### `mcp__atlas__atlas_public_kinds`
+List all node kinds in the graph. Use to scope a domain to relevant kinds.
+
+### `mcp__atlas__atlas_public_kind`
+Describe a single node kind (schema/fields). Use before relying on a kind's shape.
+
+### `mcp__atlas__atlas_public_edge_kinds`
+List all edge kinds. Use to understand how nodes relate.
+
+### `mcp__atlas__atlas_public_edge_kind`
+Describe a single edge kind. Use to interpret a specific relation type.
+
+### `mcp__atlas__atlas_public_clusters`
+List graph clusters (thematic groupings). Use to scope a domain to cluster(s).
+
+### `mcp__atlas__atlas_public_stats`
+Graph-level counts/metrics. Use for sizing and sanity checks.
+
+### `mcp__atlas__atlas_public_wiki_page`
+Fetch a narrative wiki page for context. Use to capture human-readable nuance.
+
+## Query recipes
+
+- **Find by need** — `atlas_public_search(q=<need terms>)` → take top ids.
+- **Expand a subsystem** — `atlas_public_neighbors(id, depth=2, kinds=[...])`.
+- **Inspect a node** — `atlas_public_record(id, expandNeighbors=true)`.
+- **Browse a cluster** — `atlas_public_clusters` → pick cluster → `search`/
+  `neighbors` scoped to it.

package/versions.json

@@ -0,0 +1,4 @@
+{
+  "sdkVersion": "5.0.1-staging.28347f861706",
+  "extensionVersion": "5.0.1-staging.28347f861706"
+}