@hybridlabor-api/aos 4.7.0 → 4.7.1

package/bin/aos-doctor.mjs

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+// AOS System Checkup & Doctor: Verifies system dependencies, file placement,
+// cross-platform harness synchronization, daemons and hooks across macOS and Windows.
+// Usage:
+//   aos doctor
+//   node bin/aos-doctor.mjs [--json] [--net]
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { execFileSync, execSync } from 'node:child_process';
+import { connect } from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+const HOME = os.homedir();
+const JSON_OUT = process.argv.includes('--json');
+const NET = process.argv.includes('--net');
+const IS_MAC = process.platform === 'darwin';
+const IS_WIN = process.platform === 'win32';
+const IS_ARM64 = process.arch === 'arm64';
+
+const h = (...p) => path.join(HOME, ...p);
+const tilde = (p) => (p || '').replace(HOME, '~');
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
+
+const firstExisting = (candidates) => candidates.find((c) => existsSync(c)) || null;
+
+const MODULE_BASES = [
+  h('.agents'),
+  h('.claude'),
+  h('dev', 'bdb-dev'),
+  ...(process.env.npm_config_prefix ? [path.join(process.env.npm_config_prefix, 'lib', 'node_modules')] : []),
+  '/usr/local/lib/node_modules',
+  '/opt/homebrew/lib/node_modules',
+];
+const findModule = (name) => firstExisting(MODULE_BASES.map((b) => path.join(b, name)));
+
+const MCP_DIRS = [
+  h('.gemini', 'config', 'mcps'),
+  h('Library', 'Application Support', 'Claude', 'mcps'),
+  ...(process.env.APPDATA ? [path.join(process.env.APPDATA, 'Claude', 'mcps')] : []),
+  h('.cursor', 'mcps'),
+  h('.codex', 'mcps'),
+  h('.windsurf', 'mcps'),
+];
+
+const results = [];
+const add = (area, name, ok, detail, fix, warningOnly = false) => {
+  results.push({ area, name, ok, detail, fix, warningOnly });
+};
+
+const which = (bin) => {
+  const probe = IS_WIN ? 'where' : 'which';
+  try {
+    return tilde(execFileSync(probe, [bin], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim().split(/\r?\n/)[0]);
+  } catch {
+    return null;
+  }
+};
+
+const dirCount = (p) => {
+  try {
+    return readdirSync(p, { withFileTypes: true }).filter(d => d.isDirectory()).length;
+  } catch {
+    return 0;
+  }
+};
+
+function portOpen(port, timeout = 1200) {
+  return new Promise((resolve) => {
+    const s = connect({ host: '127.0.0.1', port });
+    const done = (v) => { s.destroy(); resolve(v); };
+    s.setTimeout(timeout);
+    s.once('connect', () => done(true));
+    s.once('timeout', () => done(false));
+    s.once('error', () => done(false));
+  });
+}
+
+// ---------------------------------------------------------------- 1. System Prereqs
+function checkPrereqs() {
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  add('prereq', 'Node.js runtime', nodeMajor >= 20, `v${process.versions.node} (${nodeMajor >= 22 ? 'optimal for OpenWiki' : '>= 20 required'})`,
+    'Update Node.js to v20 or v22+ via nvm or nodejs.org.');
+
+  const pyProbe = which('python3') || which('python') || (IS_WIN ? which('py') : null);
+  add('prereq', 'Python 3', !!pyProbe, pyProbe || 'missing — needed for memB venv & OpenWiki',
+    IS_WIN ? 'Install Python from python.org or winget install Python.Python.3.12' : 'brew install python3');
+
+  const gitProbe = which('git');
+  add('prereq', 'Git CLI', !!gitProbe, gitProbe || 'missing — required for AOS workflows and worktrees',
+    IS_WIN ? 'Install Git via git-scm.com or winget install Git.Git' : 'brew install git / xcode-select --install');
+
+  const uvProbe = which('uv');
+  add('prereq', 'uv package manager', !!uvProbe, uvProbe ? `${uvProbe} (fast venv seeding)` : 'optional — pip fallback will be used',
+    'curl -LsSf https://astral.sh/uv/install.sh | sh (or pip install uv)', true);
+
+  const ghProbe = which('gh');
+  add('prereq', 'GitHub CLI (gh)', !!ghProbe, ghProbe ? `${ghProbe}` : 'optional — needed for repo automation & release PRs',
+    'Install GitHub CLI: brew install gh / winget install GitHub.cli', true);
+}
+
+// ---------------------------------------------------------------- 2. AOS Core Placement & Store
+function checkAosCore() {
+  const manifestPath = h('.agents', '.bdb-manifest.json');
+  const manifest = readJson(manifestPath);
+  add('aos-core', 'Install Manifest', !!manifest,
+    manifest ? `v${manifest.version || '4.x'} · tier ${manifest.tier || 'full'} · modules: ${(manifest.installedModules || []).join(', ') || 'default'}` : `${manifestPath} missing or unreadable`,
+    'Run the AOS installer: npx @hybridlabor-api/aos@latest');
+
+  // Check store index
+  const storeIndexCandidates = [
+    path.join(path.dirname(new URL(import.meta.url).pathname), '..', 'lib', 'ecc-store-index.json'),
+    h('.agents', 'lib', 'ecc-store-index.json'),
+    h('dev', 'bdb-dev', 'bdb-dev-optimized-agent-skills', 'lib', 'ecc-store-index.json')
+  ];
+  const storeIndexPath = firstExisting(storeIndexCandidates);
+  let storeSkillsCount = 0;
+  if (storeIndexPath) {
+    try {
+      const idx = readJson(storeIndexPath);
+      storeSkillsCount = (idx?.skills ? Object.keys(idx.skills).length : 0);
+    } catch {}
+  }
+  add('aos-core', 'Offline Store Index', !!storeIndexPath && storeSkillsCount > 0,
+    storeIndexPath ? `${tilde(storeIndexPath)} (${storeSkillsCount} catalog skills indexed)` : 'Store index missing',
+    'Run scripts/build-ecc-store-index.mjs or re-run the AOS installer.');
+
+  // Check MCSC registration
+  const mcpConfigCandidates = [
+    path.join(path.dirname(new URL(import.meta.url).pathname), '..', 'mcp_config.json'),
+    h('.agents', 'mcp_config.json'),
+    h('dev', 'bdb-dev', 'bdb-dev-optimized-agent-skills', 'mcp_config.json')
+  ];
+  const mcpConfigPath = firstExisting(mcpConfigCandidates);
+  const mcpConfig = mcpConfigPath ? readJson(mcpConfigPath) : null;
+  const hasMcsc = !!mcpConfig?.mcpServers?.mcsc;
+  add('aos-core', 'MCSC Telemetry Registration', hasMcsc,
+    hasMcsc ? `Registered in ${tilde(mcpConfigPath)}` : 'mcsc missing from mcp_config.json',
+    'Re-run installer to register mcsc cross-harness adapter.');
+
+  // Retired module check (CDC bug prevention)
+  const retired = findModule('bdb-os-agent-workspace');
+  if (retired) {
+    add('aos-core', 'Retired AO module', false,
+      `${tilde(retired)} — archived predecessor with known CDC loop bug`,
+      `Remove directory: rm -rf ${tilde(retired)} — AO is now bdb-agent-orchestrator.`);
+  }
+}
+
+// ---------------------------------------------------------------- 3. Harness Placement & Skills Sync
+function checkHarnesses() {
+  const harnesses = [
+    { name: 'Claude Code', path: h('.claude', 'skills') },
+    { name: 'Gemini / Antigravity', path: firstExisting([h('.gemini', 'config', 'skills'), h('.gemini', 'antigravity-cli', 'skills')]) || h('.gemini', 'config', 'skills') },
+    { name: 'Codex', path: h('.codex', 'skills') },
+    { name: 'Cursor', path: h('.cursor', 'skills') },
+    { name: 'Roo Code', path: h('.roo', 'skills') },
+  ];
+
+  const SENTINEL = 'startcycle';
+  for (const hr of harnesses) {
+    const exists = existsSync(hr.path);
+    const count = dirCount(hr.path);
+    const hasSentinel = existsSync(path.join(hr.path, SENTINEL, 'SKILL.md'));
+    const ok = exists && count > 0 && hasSentinel;
+    add('harnesses', `${hr.name} Skills`, ok,
+      ok ? `${tilde(hr.path)} (${count} skills, sentinel verified)` : (exists ? `${tilde(hr.path)} (${count} skills, sentinel missing)` : `${tilde(hr.path)} not synced`),
+      `Run 'npx @hybridlabor-api/aos@latest' and select ${hr.name} to sync skills.`, !exists);
+  }
+
+  // OpenCode Plugin check
+  const opencodePlugin = firstExisting([
+    h('.opencode', 'plugins', 'bdb-aos.js'),
+    h('.config', 'opencode', 'plugins', 'bdb-aos.js')
+  ]);
+  add('harnesses', 'OpenCode Plugin', !!opencodePlugin,
+    opencodePlugin ? tilde(opencodePlugin) : 'bdb-aos.js not installed in OpenCode plugins',
+    'Run the AOS installer to wire OpenCode telemetry plugin.', true);
+}
+
+// ---------------------------------------------------------------- 4. Hooks & Security Gates
+function checkHooks() {
+  const claudeHooksDir = h('.claude', 'hooks');
+  const EXPECTED_VERSION = { 'memb-inject.mjs': 5 };
+  const versionOf = (text) => {
+    const m = /^\/\/\s*aos-hook-version:\s*(\d+)/m.exec(text);
+    return m ? Number(m[1]) : null;
+  };
+
+  for (const file of ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs']) {
+    const p = path.join(claudeHooksDir, file);
+    if (!existsSync(p)) {
+      add('hooks', file, false, 'missing from ~/.claude/hooks',
+        'Run the installer to wire Claude Code safety hooks.');
+      continue;
+    }
+    const want = EXPECTED_VERSION[file];
+    if (!want) {
+      add('hooks', file, true, tilde(p), '');
+      continue;
+    }
+    const got = versionOf(readFileSync(p, 'utf8'));
+    add('hooks', file, got === want,
+      got === want ? `${tilde(p)} (v${got})` : `${tilde(p)} (v${got || 'legacy'}, expected v${want})`,
+      'Run the AOS installer to update to latest hook version.');
+  }
+
+  // Claude settings.json wiring
+  const claudeSettings = readJson(h('.claude', 'settings.json'));
+  const wired = JSON.stringify(claudeSettings?.hooks || {});
+  const claudeWiredOk = wired.includes('go-gate.mjs') && wired.includes('memb-inject.mjs');
+  add('hooks', 'Claude settings.json wired', claudeWiredOk,
+    claudeWiredOk ? 'PreToolUse & UserPromptSubmit registered' : 'Hooks not fully registered in ~/.claude/settings.json',
+    'Run the AOS installer to wire hooks in settings.json.');
+
+  // Antigravity hooks
+  const agHooksFile = firstExisting([
+    h('.gemini', 'antigravity-cli', 'hooks.json'),
+    h('.gemini', 'config', 'hooks.json'),
+    h('.agents', 'hooks.json')
+  ]);
+  const agHooks = agHooksFile ? readJson(agHooksFile) : null;
+  const agWired = JSON.stringify(agHooks?.hooks || {});
+  add('hooks', 'Antigravity hooks', agWired.includes('memb-inject.mjs'),
+    agHooksFile ? `${tilde(agHooksFile)} (${agWired.includes('memb-inject.mjs') ? 'memb-inject wired' : 'unwired'})` : 'hooks.json not found',
+    'Run the AOS installer to configure Antigravity hooks.', true);
+
+  // Codex hooks
+  const codexConf = h('.codex', 'config.toml');
+  let codexToml = '';
+  try { codexToml = readFileSync(codexConf, 'utf8'); } catch {}
+  add('hooks', 'Codex config.toml hooks', codexToml.includes('AOS:HOOKS'),
+    existsSync(codexConf) ? `${tilde(codexConf)} (${codexToml.includes('AOS:HOOKS') ? 'AOS:HOOKS block wired' : 'no AOS:HOOKS'})` : `${tilde(codexConf)} missing`,
+    'Run the AOS installer to wire Codex hooks.', true);
+}
+
+// ---------------------------------------------------------------- 5. Daemons & Ecosystem Modules (Including AO)
+async function checkDaemonsAndModules() {
+  // memB
+  const membDir = findModule('memB');
+  const membListening = await portOpen(8088);
+  add('daemons', 'memB WebUI (:8088)', membListening,
+    membListening ? 'Active & listening on http://127.0.0.1:8088' : 'Not listening on port 8088',
+    IS_MAC ? 'launchctl load -w ~/Library/LaunchAgents/com.bdb.memb.webui.plist' : 'Start src/backend/server.py in memB module.');
+
+  // Synapse 3D
+  const synapseListening = await portOpen(7781);
+  add('daemons', 'Synapse 3D (:7781)', synapseListening,
+    synapseListening ? 'Active & listening on http://127.0.0.1:7781' : 'Not listening on port 7781',
+    IS_MAC ? 'launchctl load -w ~/Library/LaunchAgents/com.bdb.synapse.plist' : 'synapse serve --port 7781', true);
+
+  // BDB OS Remote Gateway
+  const remoteListening = await portOpen(9080);
+  add('daemons', 'Remote Gateway (:9080)', remoteListening,
+    remoteListening ? 'Active & listening on port 9080' : 'Not listening on port 9080',
+    'Start gateway via ~/dev/bdb-dev/bdb-os-remote/start-gateway.sh', true);
+
+  // BDB Agent Orchestrator (AO)
+  const aoBin = which('ao') || (existsSync(h('.local', 'bin', 'ao')) ? h('.local', 'bin', 'ao') : null);
+  let aoVer = null;
+  if (aoBin) {
+    try {
+      aoVer = execFileSync(aoBin, ['--version'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    } catch {}
+  }
+  const aoListening = await portOpen(3101);
+  let aoServiceInfo = 'Not running';
+  if (aoBin) {
+    try {
+      const statusOut = execFileSync(aoBin, ['service', 'status'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+      const runningLine = statusOut.split('\n').find(l => l.toLowerCase().includes('running'));
+      if (runningLine) aoServiceInfo = runningLine.trim();
+    } catch {}
+  }
+
+  const aoOk = !!aoBin;
+  add('daemons', 'AO Agent Orchestrator', aoOk,
+    aoBin ? `${tilde(aoBin)} (${aoVer || 'installed'}) · Daemon :3101: ${aoListening ? 'ONLINE' : 'STOPPED'} (${aoServiceInfo})` : 'ao binary not found',
+    IS_MAC && IS_ARM64
+      ? 'Enable AO in the installer or run: ao service install'
+      : 'AO binary is arm64 macOS native; build from source on other platforms: github.com/hybridlabor-api/bdb-agent-orchestrator', false);
+
+  // Code-signing check for AO on macOS
+  if (IS_MAC && aoBin) {
+    let signed = false;
+    try {
+      execSync(`codesign -v "${aoBin}"`, { stdio: 'ignore' });
+      signed = true;
+    } catch {}
+    add('security', 'AO Binary Signature (AMFI)', signed,
+      signed ? 'Binary code-signed (AMFI safe)' : 'Unsigned binary — AMFI might terminate on launch',
+      `Run: codesign -s - -f "${aoBin}"`);
+  }
+}
+
+// ---------------------------------------------------------------- 6. Output & Announcement
+function printAoAnnouncement() {
+  console.log(`
+╭──────────────────────────────────────────────────────────────────────────────╮
+│                                                                              │
+│   🚀 BDB AGENT ORCHESTRATOR APP — FINALE BETA JETZT VERFÜGBAR!              │
+│                                                                              │
+│   Die nächste Generation der Cross-Harness Multi-Agenten-Orchestrierung      │
+│   ist jetzt als finale Beta für alle User freigeschaltet.                    │
+│                                                                              │
+│   • Dashboard & WebUI:  http://localhost:3101                                │
+│   • Service-Befehl:     ao service install  (Hintergrunddienst aktivieren)   │
+│   • Quick Launch:       ao open  oder  ao service status                     │
+│   • Features:           Session-Telemetrie, Live-AgentTrail & Multi-Workspaces│
+│                                                                              │
+╰──────────────────────────────────────────────────────────────────────────────╯
+`);
+}
+
+function report() {
+  if (JSON_OUT) {
+    const ok = results.filter(r => !r.warningOnly).every(r => r.ok);
+    console.log(JSON.stringify({ ok, platform: process.platform, arch: process.arch, results }, null, 2));
+    return;
+  }
+
+  printAoAnnouncement();
+
+  console.log(`\n======================================================`);
+  console.log(`   🩺 AOS SYSTEM CHECKUP & DIAGNOSTIC REPORT`);
+  console.log(`   Platform: ${process.platform} (${process.arch}) · Node: ${process.version}`);
+  console.log(`======================================================`);
+
+  let currentArea = '';
+  for (const r of results) {
+    if (r.area !== currentArea) {
+      currentArea = r.area;
+      console.log(`\n[${currentArea.toUpperCase()}]`);
+    }
+    const icon = r.ok ? '✅' : (r.warningOnly ? '⚠️ ' : '❌');
+    console.log(`  ${icon} ${r.name.padEnd(28)} ${r.detail}`);
+    if (!r.ok && r.fix) {
+      console.log(`     ↳ Fix: ${r.fix}`);
+    }
+  }
+
+  const criticalFails = results.filter(r => !r.ok && !r.warningOnly);
+  const warnings = results.filter(r => !r.ok && r.warningOnly);
+
+  console.log(`\n------------------------------------------------------`);
+  if (criticalFails.length === 0) {
+    console.log(`🎉 ALL CRITICAL CHECKS PASSED (${results.length - warnings.length}/${results.length})! AOS is properly configured.`);
+    if (warnings.length > 0) {
+      console.log(`   (${warnings.length} optional warning(s) detected — see hints above).`);
+    }
+  } else {
+    console.log(`⚠️  ${criticalFails.length} critical check(s) need attention! Follow the fix instructions above.`);
+  }
+  console.log(`------------------------------------------------------\n`);
+}
+
+// ---------------------------------------------------------------- Run
+checkPrereqs();
+checkAosCore();
+checkHarnesses();
+checkHooks();
+await checkDaemonsAndModules();
+report();
+
+const hasCriticalFails = results.some(r => !r.ok && !r.warningOnly);
+process.exit(hasCriticalFails ? 1 : 0);

package/bin/aos-store.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const INDEX_PATH = join(ROOT, 'lib', 'ecc-store-index.json');
+const index = JSON.parse(readFileSync(INDEX_PATH, 'utf8'));
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const project = args.includes('--project');
+const positional = args.filter((arg) => !arg.startsWith('--'));
+const option = (name) => args.find((arg) => arg === name || arg.startsWith(`${name}=`))?.split('=').slice(1).join('=');
+
+function loadIndex() {
+  if (!index.pinned_commit || !index.skills || !index.subagents) throw new Error('Invalid AOS store index');
+  return index;
+}
+
+function allItems(type) {
+  const selected = type === 'agents' || type === 'subagents' ? 'subagents' : 'skills';
+  return Object.entries(index[selected] || {}).map(([name, item]) => ({ name, item, type: selected }));
+}
+
+function findItem(name) {
+  for (const type of ['skills', 'subagents']) {
+    if (index[type]?.[name]) return { name, item: index[type][name], type };
+  }
+  return null;
+}
+
+function localSkillNames() {
+  const names = new Set();
+  const visit = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) visit(fullPath);
+      else if (entry.name === 'SKILL.md') names.add(basename(dirname(fullPath)));
+    }
+  };
+  visit(join(ROOT, 'skills'));
+  return names;
+}
+
+function localAgentNames() {
+  const names = new Set();
+  for (const dir of [join(ROOT, '.claude', 'agents'), join(ROOT, '.agents', 'agents'), join(ROOT, 'agents')]) {
+    if (!existsSync(dir)) continue;
+    for (const entry of readdirSync(dir)) names.add(entry.replace(/\.md$/i, ''));
+  }
+  return names;
+}
+
+function globalRoots(type) {
+  const home = homedir();
+  return type === 'skills'
+    ? [
+      join(home, '.agents', 'skills'),
+      join(home, '.claude', 'skills'),
+      join(home, '.codex', 'skills'),
+      join(home, '.cursor', 'skills'),
+      join(home, '.roo', 'skills'),
+      join(home, '.gemini', 'config', 'skills'),
+    ]
+    : [
+      join(home, '.agents', 'agents'),
+      join(home, '.claude', 'agents'),
+      join(home, '.codex', 'agents'),
+      join(home, '.cursor', 'agents'),
+      join(home, '.roo', 'agents'),
+      join(home, '.gemini', 'config', 'agents'),
+    ];
+}
+
+function printItems(items) {
+  if (items.length === 0) {
+    console.log('No store items found.');
+    return;
+  }
+  for (const { name, item, type } of items) {
+    const kind = type === 'skills' ? 'skill' : 'agent';
+    console.log(`${kind}\t${name}\t${item.category}\t${item.description}`);
+  }
+  console.log(`\n${items.length} item(s).`);
+}
+
+async function download(upstreamPath) {
+  const url = `https://raw.githubusercontent.com/affaan-m/ECC/${index.pinned_commit}/${upstreamPath}`;
+  const response = await fetch(url, { headers: { 'user-agent': 'aos-store' } });
+  if (!response.ok) throw new Error(`Download failed (${response.status}): ${url}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+function targetsFor(type, name) {
+  if (project) {
+    return type === 'skills'
+      ? [join(process.cwd(), 'skills', name, 'SKILL.md')]
+      : [join(process.cwd(), 'agents', `${name}.md`)];
+  }
+  return globalRoots(type).map((root) => type === 'skills'
+    ? join(root, name, 'SKILL.md')
+    : join(root, `${name}.md`));
+}
+
+async function install(name) {
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) throw new Error(`Invalid store name: ${name}`);
+  const found = findItem(name);
+  if (!found) throw new Error(`Store item not found: ${name}`);
+  const { item, type } = found;
+  const coreNames = type === 'skills' ? localSkillNames() : localAgentNames();
+  if (coreNames.has(name)) {
+    console.log(`Skipped ${name}: AOS core already provides it.`);
+    return;
+  }
+  const targets = targetsFor(type, name);
+  if (dryRun) {
+    for (const target of targets) console.log(`[dry-run] write ${target}`);
+    return;
+  }
+  const content = await download(item.upstream_path);
+  const digest = createHash('sha256').update(content).digest('hex');
+  if (digest !== item.sha256) throw new Error(`SHA-256 mismatch for ${name}: expected ${item.sha256}, got ${digest}`);
+  for (const target of targets) {
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, content);
+    console.log(`Installed ${name} -> ${target}`);
+  }
+}
+
+function usage() {
+  console.log('Usage:');
+  console.log('  aos store list [--type=skills|agents]');
+  console.log('  aos store search <query>');
+  console.log('  aos store install <name> [--project] [--dry-run]');
+}
+
+async function main() {
+  loadIndex();
+  const command = positional[0] || 'list';
+  if (command === 'list') {
+    printItems(allItems(option('--type') || 'skills'));
+    return;
+  }
+  if (command === 'search') {
+    const query = (positional[1] || '').toLowerCase();
+    if (!query) throw new Error('Search requires a query.');
+    const items = allItems(option('--type') || '').filter(({ name, item }) => `${name} ${item.description} ${item.category}`.toLowerCase().includes(query));
+    printItems(items);
+    return;
+  }
+  if (command === 'install') {
+    if (!positional[1]) throw new Error('Install requires a store item name.');
+    await install(positional[1]);
+    return;
+  }
+  usage();
+  process.exitCode = 1;
+}
+
+main().catch((error) => {
+  console.error(`aos store: ${error.message}`);
+  process.exitCode = 1;
+});

package/docs/AUDIT_BRIEF_ECC_STORE.md

@@ -0,0 +1,122 @@
+# Audit Brief: AOS Skill, Subagent & Extras Store (ECC Fork Integration)
+
+**Datum:** 2026-09-24  
+**Projekt:** `@hybridlabor-api/aos` (AOS — Curated AI Agent OS)  
+**Dokumenttyp:** Architektur- & Sicherheits-Audit-Briefing für externe Reviewer- / Auditor-Agenten  
+**Status:** Vor Implementierung (Architektur-Review)
+
+---
+
+## 1. Executive Summary & Zielsetzung
+
+AOS (`@hybridlabor-api/aos`) ist ein multi-harness Agenten-Betriebssystem für autonome Coding-Pipelines (unterstützt Claude Code, Google Antigravity, Codex, Cursor, Roo Code und OpenCode). Aktuell liefert AOS ca. 185 kuratierte Kern-Skills und eine 7-Node-Graph-Architektur mit deterministischen Übergängen (Architect → TechLead → Build → Reviewer → Shipping).
+
+### Geplante Erweiterung
+Aufbau eines dezentralen **Skill-, Subagent- und Extras-Stores** als Fallback-Ebene auf Basis eines gepflegten Forks von **[affaan-m/ECC](https://github.com/affaan-m/ECC)** (Everything Claude Code, MIT-Lizenz):
+1. **Fallback in `/ask-tim`:** Wenn ein Nutzer nach einer Domäne oder einem Framework sucht (z. B. Spring Boot, Godot, Django), das nicht im 185-Skill-Kern von AOS liegt, soll `/ask-tim` automatisch passende Erweiterungen aus dem Store vorschlagen.
+2. **Fallback in `--skill=<name>`:** Bei Pipeline-Aufrufen wie `/startcycle-graph --skill=django-pro "Ziel"` soll ein lokal fehlender Skill nicht sofort hart mit einer Eskalation abbrechen, sondern im Store gesucht, validiert und on-demand geladen werden.
+3. **Subagent & Extras Katalog:** Bereitstellung von spezialisierten Auxiliary Agents, Templates, Rules und Hooks aus dem ECC-Ökosystem als modulare AOS-Erweiterungen.
+
+---
+
+## 2. Aktueller Systembestand in AOS (Ist-Zustand)
+
+### 2.1 Relevante Code- & Konfigurations-Pfade
+- **Multi-Harness Installer:** [`installer.js`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/installer.js) — Synchronisiert Skills, MCP-Configs und Agents nach `~/.claude/`, `~/.agents/`, `~/.codex/`, `~/.cursor/` etc.
+- **Pipeline Dispatcher:** [`.claude/workflows/startcycle-dispatch.mjs`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/.claude/workflows/startcycle-dispatch.mjs) — Verwaltet den Startcycle-Graph, GO-Gates, mandatory skills (`--skill=<name>`) und Agenten-Orchestrierung.
+- **Skill Router:** [`skills/global_config/ask-tim/SKILL.md`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/skills/global_config/ask-tim/SKILL.md) — Zentraler Einstiegspunkt für Intent-Erkennung und Skill-Auswahl.
+- **Vendor Tracking:** [`~/.agents/vendor-manifest.json`](file:///Users/timrennings/.agents/vendor-manifest.json) — Pinned Git SHAs für Upstream-Repositories (z. B. `anti-slop`, `skylos`, `claude-red`).
+- **Bereits portierte ECC-Komponenten:** [`THIRD_PARTY_NOTICES.md`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/THIRD_PARTY_NOTICES.md) — 6 Auxiliary Agents (`silent-failure-hunter`, `security-reviewer`, `go-build-resolver`, `database-reviewer`, `opensource-forker`, `opensource-sanitizer`) und `plan-canvas`.
+
+### 2.2 Bestehende `--skill` Validierungslogik (`startcycle-dispatch.mjs:701-741`)
+```javascript
+// Aktuelles Verhalten:
+if (mandatorySkillNames.length > 0) {
+  const skillCheckResult = await agent(`Check whether each of these skill names resolves to an installed skill...`);
+  const missing = skillCheckResult?.missing ?? [];
+  if (missing.length > 0) {
+    // HARTES ESKALIEREN:
+    return await escalate(`--skill named skill(s) that could not be found: ${missing.join(', ')}...`);
+  }
+}
+```
+
+---
+
+## 3. Geplante Soll-Architektur
+
+```mermaid
+flowchart TD
+    User([Nutzer-Anfrage / Prompt]) --> Trigger{Einstiegspunkt}
+    
+    Trigger -->|1. /ask-tim Suche| AskTim[ask-tim Router]
+    Trigger -->|2. --skill=name Flag| Dispatcher[startcycle-dispatch]
+    
+    AskTim --> CheckCore1{Im 185-Skill AOS Core?}
+    Dispatcher --> CheckCore2{Lokal auf Disk installiert?}
+    
+    CheckCore1 -->|Ja| UseCore[Empfehle/Nutze nativen AOS-Skill]
+    CheckCore2 -->|Ja| RunCore[Starte Pipeline mit Core-Skill]
+    
+    CheckCore1 -->|Nein| QueryStore[Abfrage lokaler ecc-store-index.json]
+    CheckCore2 -->|Nein| QueryStore
+    
+    QueryStore --> MatchFound{Match im Store?}
+    MatchFound -->|Nein| FinalEscalate[Eskalation / Keine Treffer]
+    MatchFound -->|Ja| StoreAction{Aktion}
+    
+    StoreAction -->|bei /ask-tim| ShowOption[Empfehlung + 'aos store install <name>']
+    StoreAction -->|bei --skill| GateCheck[GO-Gate / Confirmation]
+    
+    GateCheck -->|Genehmigt| FetchEngine[On-Demand Sync in ~/.agents/skills/]
+    FetchEngine --> ValidateHarness[POSIX & Harness-Tool Linter]
+    ValidateHarness --> RunPipeline[Pipeline-Start ohne Unterbrechung]
+```
+
+---
+
+## 4. Kernfragen & Prüffelder für das Audit
+
+Der Auditor-Agent wird gebeten, folgende kritische Fragestellungen strukturiert zu beleuchten:
+
+### 1. GO-Gate & Sicherheit (Supply-Chain-Risiko)
+* **Problem:** Dürfen externe Skills oder Agents während eines autonomen Pipeline-Laufs dynamisch aus einem Remote-Repository nachgeladen werden?
+* **Audit-Frage:** Wie muss die Bestätigung strukturiert sein, damit die strikte AOS-Regel (*"read-only until literal GO"*) nicht kompromittiert wird? Genügt ein lokales, kryptografisch verifiziertes Manifest mit SHA-256 Checksummen?
+
+### 2. Multi-Harness Tool-Inkompatibilitäten
+* **Problem:** `affaan-m/ECC` ist primär für Claude Code konzipiert und verwendet teils hardcodierte Tool-Namen wie `Bash`, `View`, `Edit`, `GlobTool`.
+* **Audit-Frage:** Welche automatisierten Transformations- oder Linter-Regeln müssen beim Ingest/Installationsschritt greifen, damit importierte Skills fehlerfrei in Google Antigravity (`run_command`, `view_file`), OpenAI Codex (`exec`, `read_file`) und Cursor funktionieren?
+
+### 3. Context Window & Token-Budget
+* **Problem:** Ein ungefilterter Import von 400+ Skills würde die Context-Limits und System-Prompts überlasten.
+* **Audit-Frage:** Ist die gewählte Architektur mit einem leichtgewichtigen, lokalen Vektor- oder Metadaten-Index (`ecc-store-index.json` < 100 KB) optimal, und wie sollte das semantische Ranking bei ungenauen Begriffen erfolgen?
+
+### 4. Namenskonflikte & Rangfolge (Precedence)
+* **Problem:** Was passiert, wenn ein ECC-Skill denselben Namen trägt wie ein existierender oder zukünftiger AOS-Kern-Skill (z. B. `tailwind-patterns` oder `tdd-workflow`)?
+* **Audit-Frage:** Sollte ein striktes Namespacing (`ecc/<skill-name>` oder Tagging `origin: ecc`) erzwungen werden, um Overwrites und Seiteneffekte auszuschließen?
+
+### 5. Wartungs- und Sync-Strategie des Forks
+* **Problem:** ECC wird kontinuierlich weiterentwickelt.
+* **Audit-Frage:** Wie sieht eine nachhaltige GitHub-Action-Sync-Pipeline für den Fork `hybridlabor-api/ECC` aus, die neue Upstream-Releases verarbeitet, ohne manuell angepasste Harness-Kompatibilitäts-Fixes zu überschreiben?
+
+---
+
+## 5. Referenzierte Komponenten & Schnittstellen
+
+| Komponente | Datei / Pfad | Relevante Zeilen / Kontext |
+|---|---|---|
+| **Pipeline-Dispatcher** | [`.claude/workflows/startcycle-dispatch.mjs`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/.claude/workflows/startcycle-dispatch.mjs) | Z. 701–741 (Mandatory Skill Check & Eskalation) |
+| **Skill Router** | [`skills/global_config/ask-tim/SKILL.md`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/skills/global_config/ask-tim/SKILL.md) | Z. 1–70 (Main Flow & Intent Index) |
+| **Vendor Registry** | [`~/.agents/vendor-manifest.json`](file:///Users/timrennings/.agents/vendor-manifest.json) | Vorhandene Pinned-Upstream-Repositories |
+| **Lizenz- & Provenance** | [`THIRD_PARTY_NOTICES.md`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/THIRD_PARTY_NOTICES.md) | Z. 12–50 (Bisheriger Port von ECC-Agents) |
+| **AOS Installer & Sync** | [`installer.js`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/installer.js) | Z. 110–135 (Multi-Platform Fan-out) |
+
+---
+
+## 6. Erwartetes Audit-Ergebnis
+
+Der externe Auditor-Agent sollte am Ende einen Bericht mit folgendem Schema abliefern:
+1. **Architektur-Bewertung:** Bestätigung oder Korrektur der vorgeschlagenen Store- und Fallback-Architektur.
+2. **Identifizierte Risiken:** Kategorisiert nach *Blocker*, *Warnung*, *Empfehlung*.
+3. **Konkrete Lösungsvorschläge:** Für Tool-Mapping, Token-Schonung und GO-Gate-Integration.
+4. **Sign-Off / Freigabe-Empfehlung:** Für den Start der Implementierung von Phase 1.