aero-agent-roles 1.0.0

package/NOTICE

@@ -0,0 +1,18 @@
+Aero Agent Roles
+Copyright 2026 Ashforde OÜ
+
+This product includes software and methodology developed by Ashforde OÜ
+(Estonia). Licensed under the Apache License, Version 2.0 (the
+"License"); you may not use this product except in compliance with the
+License. You may obtain a copy of the License at
+http://www.apache.org/licenses/LICENSE-2.0.
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied. See the License for the specific language governing
+permissions and limitations under the License.
+
+Aero Agent Roles builds on Aero Agent Skills (Apache-2.0). Standards
+referenced within roles remain the property of their respective
+publishers; no proprietary content is reproduced.

package/README.md

@@ -0,0 +1,49 @@
+# aero-agent-roles
+
+**The role layer for aerospace engineering agents** — professional roles that bind verified [Aero Agent Skills](https://github.com/ashfordeOU/aero-agent-skills) into end-to-end deliverables, with evidence gates and a human sign-off stop, shipped as an npm CLI and an MCP server. Built and maintained by [Ashforde OÜ](https://ashforde.org).
+
+> **Not yet published.** This package is wired and tested (`make package-test`) but `private: true` in `package.json` — npm refuses to publish it until that is deliberately removed. Ready to release, not released.
+
+Full role bank, figures, and provenance: [github.com/ashfordeOU/aero-agent-roles](https://github.com/ashfordeOU/aero-agent-roles) · [ashforde.org/aeroagentroles](https://ashforde.org/aeroagentroles)
+
+Each role is gated by a replayable offline battery (structure lint, offline behavior tests, no-verbatim sweep, security tripwire, manifest-matches-tree). This package bundles the tree at the released commit; live counts come from `aero-roles list`, never from this README.
+
+## CLI
+
+```bash
+npm i -g aero-agent-roles   # or: npx aero-agent-roles <command>
+
+aero-roles list                                    # domains, roles, skills bound
+aero-roles search "DO-178C certification plan"
+aero-roles show do178c-cert-engineer
+aero-roles install do178c-cert-engineer --dest ./roles
+```
+
+`install` copies a role's full folder (`ROLE.md`, `templates/`, `tests/`, `core/`, `cli.py`) to `--dest <dir>` (`--link` symlinks instead of copying). A role is **not** an agent-router skill — `ROLE.md` has no trigger `description` the way `SKILL.md` does — so `install` does not register a role with any host's skill router; it hands you the files to run directly (`python3 <dest>/<slug>/cli.py build --bundle`) or to point an agent at by path.
+
+## MCP server
+
+Works in any Model Context Protocol host: JetBrains AI Assistant and Junie, Claude Desktop, Claude Code, VS Code, Cursor, Windsurf, Gemini CLI.
+
+```json
+{
+  "mcpServers": {
+    "aero-agent-roles": {
+      "command": "npx",
+      "args": ["-y", "aero-agent-roles", "mcp"]
+    }
+  }
+}
+```
+
+Tools: `search_roles` (title/deliverable/domain match), `get_role` (full `ROLE.md`), `list_domains`, `list_roles`, `get_standards` (the machine-readable standards register: publisher, gated flag, which roles bind it).
+
+## What a role is
+
+A folder with a `ROLE.md`: YAML frontmatter (identity, deliverable type, bound standards + skills), a body the agent follows (ordered workflow stages, an evidence gate per stage, forbidden actions, the human sign-off stop), an executable domain engine (`core/*.py` + `cli.py`) that computes the real deliverable offline, and an offline behavior-contract test.
+
+Every role ends at the same line: **the human sign-off**. Roles produce draft deliverables with evidence. They never issue certification approval, declare compliance findings, or claim regulatory sign-off.
+
+## License
+
+Apache-2.0 © Ashforde OÜ (Estonia). Not affiliated with or endorsed by RTCA, EUROCAE, SAE International, IAQG, EASA, FAA, or any government.

package/bin/aero-agent-roles.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// aero-agent-roles CLI: list / search / show / install / where / mcp.
+// Everything answers from the bundled tree + generated manifest — offline,
+// deterministic, no telemetry, no network.
+'use strict';
+
+const { Catalog, version } = require('../lib/catalog');
+const { install } = require('../lib/install');
+
+const HELP = `aero-agent-roles ${version()} — the role layer for aerospace engineering agents (Ashforde OU)
+
+Usage:
+  aero-roles list [domain]                  browse domains, roles
+  aero-roles search <job words...>          match roles by title/deliverable/domain
+  aero-roles show <role-slug>                print one ROLE.md
+  aero-roles install <role-slug...> --dest <dir>
+      --dest <dir>                          required: destination directory
+      --link                                symlink instead of copy
+      selector: all | <role-slug> (default: all)
+  aero-roles mcp                            run the MCP server on stdio
+  aero-roles where                          print the bundled roles root
+  aero-roles version
+
+MCP host config (JetBrains AI Assistant/Junie, Claude Desktop, VS Code, Cursor, Windsurf):
+  {"mcpServers":{"aero-agent-roles":{"command":"npx","args":["-y","aero-agent-roles","mcp"]}}}
+
+Note: a role is not an agent-router skill (ROLE.md has no trigger
+description) — install copies role folders for direct/CLI use, it does
+not register them with any host's skill router.
+`;
+
+function parseFlags(argv) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--dest') flags.dest = argv[++i];
+    else if (argv[i] === '--link') flags.link = true;
+    else rest.push(argv[i]);
+  }
+  return { flags, rest };
+}
+
+function cmdList(catalog, domain) {
+  if (!domain) {
+    const doms = new Map();
+    for (const r of catalog.roles) {
+      const d = doms.get(r.domain) || { roles: 0, skills_bound: 0 };
+      d.roles += 1;
+      d.skills_bound += r.skills_bound;
+      doms.set(r.domain, d);
+    }
+    for (const [name, d] of [...doms.entries()].sort()) {
+      console.log(`${name.padEnd(28)} ${String(d.roles).padStart(3)} roles ${String(d.skills_bound).padStart(4)} skills bound`);
+    }
+    console.log(`\n${catalog.manifest.counts.roles} roles, ${catalog.manifest.counts.domains} domains, ${catalog.manifest.counts.skills_bound} skills bound. \`list <domain>\` to drill in.`);
+    return;
+  }
+  const hits = catalog.roles.filter((r) => r.domain === domain);
+  if (hits.length === 0) {
+    console.error(`nothing under '${domain}'. Run \`aero-roles list\` for domains.`);
+    process.exitCode = 1;
+    return;
+  }
+  for (const r of hits) console.log(`${r.slug}: ${r.title} — ${r.deliverable_type}`);
+}
+
+function main() {
+  const [cmd, ...args] = process.argv.slice(2);
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    console.log(HELP);
+    return;
+  }
+  if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
+    console.log(version());
+    return;
+  }
+  if (cmd === 'mcp') {
+    require('../lib/mcp').serve();
+    return;
+  }
+
+  const catalog = new Catalog();
+  if (cmd === 'list') {
+    cmdList(catalog, args[0]);
+  } else if (cmd === 'search') {
+    const query = args.join(' ').trim();
+    if (!query) {
+      console.error('usage: aero-roles search <job words...>');
+      process.exitCode = 1;
+      return;
+    }
+    const hits = catalog.search(query, 5);
+    if (hits.length === 0) {
+      console.log('no role matches. Run `aero-roles list` to browse.');
+      return;
+    }
+    for (const [i, h] of hits.entries()) {
+      console.log(`${i + 1}. ${h.role.slug}  (score ${h.score})\n   ${h.role.title} — ${h.role.deliverable_type}`);
+    }
+  } else if (cmd === 'show') {
+    const role = catalog.find(args[0] || '');
+    if (!role) {
+      console.error(`no role '${args[0] || ''}'. Try \`aero-roles search\`.`);
+      process.exitCode = 1;
+      return;
+    }
+    process.stdout.write(catalog.readRoleMd(role.slug));
+  } else if (cmd === 'install') {
+    const { flags, rest } = parseFlags(args);
+    try {
+      const result = install(catalog, rest, flags);
+      for (const item of result.installed) console.log(`${result.linked ? 'linked' : 'installed'} ${item.slug} -> ${item.folder}/`);
+      console.log(`\n${result.installed.length} roles ${result.linked ? 'linked' : 'installed'} into ${result.dest}`);
+    } catch (e) {
+      console.error(e.message);
+      process.exitCode = 1;
+    }
+  } else if (cmd === 'where') {
+    console.log(catalog.root);
+  } else {
+    console.error(`unknown command '${cmd}'\n`);
+    console.log(HELP);
+    process.exitCode = 1;
+  }
+}
+
+main();

package/lib/catalog.js

@@ -0,0 +1,97 @@
+// Catalog loader. Answers list/show/search from the bundled manifest.json
+// + roles/ tree — offline, deterministic, no telemetry, no network.
+//
+// Roles are adopted deliberately, not routed by a trigger description the
+// way Aero Agent Skills' SKILL.md files are (ROLE.md has no `description`
+// field) — search() here is a plain token-overlap match over title,
+// deliverable_type, and domain, useful for "what role fits this job"
+// browsing, not a claimed parity port of any evaluated router.
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const STOP = new Set([
+  'a', 'an', 'the', 'for', 'or', 'and', 'of', 'to', 'in', 'on', 'with',
+  'is', 'are', 'was', 'be', 'at', 'by', 'from', 'as', 'into', 'onto',
+]);
+
+const TOKEN_RE = /[a-z0-9][a-z0-9-]*/g;
+
+function tokens(text) {
+  const out = [];
+  for (const m of String(text).toLowerCase().matchAll(TOKEN_RE)) {
+    if (!STOP.has(m[0])) out.push(m[0]);
+  }
+  return out;
+}
+
+const PKG_ROOT = path.join(__dirname, '..');
+
+function rolesRoot() {
+  // Prefer the repo checkout so a stale prepack payload copy can never
+  // shadow the live tree in development; installed packages have no
+  // ../../roles and fall through to the bundled copy.
+  const repo = path.join(PKG_ROOT, '..', '..', 'roles');
+  if (fs.existsSync(repo) && fs.existsSync(path.join(PKG_ROOT, '..', '..', 'manifest.json'))) return repo;
+  const bundled = path.join(PKG_ROOT, 'roles');
+  if (fs.existsSync(bundled)) return bundled;
+  throw new Error('roles tree not found (looked for the repo checkout and a bundled roles/)');
+}
+
+function loadManifest() {
+  return JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'manifest.json'), 'utf8'));
+}
+
+function version() {
+  return JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version;
+}
+
+class Catalog {
+  constructor() {
+    this.root = rolesRoot();
+    this.manifest = loadManifest();
+    this._tok = new Map();
+  }
+
+  get roles() {
+    return this.manifest.roles;
+  }
+
+  find(slug) {
+    return this.manifest.roles.find((r) => r.slug === slug);
+  }
+
+  readRoleMd(slug) {
+    return fs.readFileSync(path.join(this.root, slug, 'ROLE.md'), 'utf8');
+  }
+
+  _tokensFor(role) {
+    let t = this._tok.get(role.slug);
+    if (!t) {
+      t = {
+        haystack: new Set(tokens(`${role.title} ${role.deliverable_type} ${role.domain} ${role.slug}`)),
+      };
+      this._tok.set(role.slug, t);
+    }
+    return t;
+  }
+
+  score(role, query) {
+    const q = new Set(tokens(query));
+    if (q.size === 0) return 0;
+    const t = this._tokensFor(role);
+    let s = 0;
+    for (const w of q) if (t.haystack.has(w)) s += 1;
+    return s;
+  }
+
+  search(query, limit = 5) {
+    const scored = this.manifest.roles.map((r) => ({ role: r, score: this.score(r, query) }));
+    scored.sort((a, b) => b.score - a.score
+      || (a.role.slug < b.role.slug ? -1 : a.role.slug > b.role.slug ? 1 : 0));
+    return scored.filter((s) => s.score > 0).slice(0, limit);
+  }
+}
+
+module.exports = { Catalog, tokens, version, PKG_ROOT };

package/lib/install.js

@@ -0,0 +1,48 @@
+// Installer: copies one role's full folder (ROLE.md, templates/, tests/,
+// core/, cli.py, SOURCES.md) to a destination directory.
+//
+// Unlike Aero Agent Skills' installer, this does NOT claim any agent-host
+// skill-router integration: ROLE.md has no `description` trigger field, so
+// dropping it into a host's skills/ directory would not make it
+// discoverable by that host's router — it would just be an inert folder.
+// A role is adopted deliberately (a human or agent runs its cli.py
+// directly), so `install` is a plain "get me this role's files" copy, not
+// a harness-aware install. `--dest` is required for exactly that reason.
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function install(catalog, slugs, opts) {
+  if (!opts.dest) {
+    throw new Error("install requires --dest <dir> (roles are not agent-router "
+      + "skills, so there is no default harness skills root to guess)");
+  }
+  const dest = path.resolve(opts.dest);
+  const selection = slugs.length === 0 || slugs.includes('all')
+    ? catalog.roles.slice()
+    : slugs.map((slug) => {
+      const r = catalog.find(slug);
+      if (!r) {
+        const near = catalog.search(slug.replace(/-/g, ' '), 3).map((s) => s.role.slug).join(', ');
+        throw new Error(`no role '${slug}'. Closest: ${near || 'none'}. Run \`aero-roles list\`.`);
+      }
+      return r;
+    });
+  fs.mkdirSync(dest, { recursive: true });
+  const installed = [];
+  for (const r of selection) {
+    const src = path.join(catalog.root, r.slug);
+    const dst = path.join(dest, r.slug);
+    if (opts.link) {
+      fs.rmSync(dst, { recursive: true, force: true });
+      fs.symlinkSync(src, dst, 'dir');
+    } else {
+      fs.cpSync(src, dst, { recursive: true, force: true });
+    }
+    installed.push({ slug: r.slug, folder: r.slug });
+  }
+  return { dest, installed, linked: !!opts.link };
+}
+
+module.exports = { install };

package/lib/mcp.js

@@ -0,0 +1,199 @@
+// MCP server over stdio: newline-delimited JSON-RPC 2.0, zero dependencies.
+// Same wire protocol and host-config shape as Aero Agent Skills' MCP
+// server (JetBrains AI Assistant/Junie, Claude Desktop, VS Code, Cursor,
+// Windsurf all speak this identically) — implements initialize, ping,
+// tools/list, tools/call; anything else gets -32601, and requests without
+// an id are notifications and never answered. Offline: every answer comes
+// from the bundled manifest — no network, ever.
+'use strict';
+
+const { Catalog, version } = require('./catalog');
+
+const TOOLS = [
+  {
+    name: 'search_roles',
+    description: 'Search Aero Agent Roles by plain-text match over title, deliverable type, and '
+      + 'domain. Use when a task needs a role that owns an end-to-end aerospace-engineering '
+      + 'deliverable (a certification plan, a compliance matrix, an analysis report), not just a '
+      + 'single skill. Returns ranked role slugs; load the winner with get_role.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'The deliverable or job, in plain words.' },
+        limit: { type: 'integer', minimum: 1, maximum: 25, description: 'Max results (default 5).' },
+      },
+      required: ['query'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_role',
+    description: 'Fetch one complete ROLE.md by slug (e.g. do178c-cert-engineer). Use after '
+      + 'search_roles or list_roles to load the full contract: the ordered workflow stages, the '
+      + 'evidence gate per stage, the bound skills and standards, forbidden actions, and the human '
+      + 'sign-off stop.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        slug: { type: 'string', description: 'Role slug as returned by search_roles or list_roles.' },
+      },
+      required: ['slug'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'list_domains',
+    description: 'List the engineering domains with their role and skills-bound counts. Use to get '
+      + 'an overview of what the role bank covers before searching or browsing.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'list_roles',
+    description: 'List roles, optionally filtered to one domain. Use to browse a discipline; each '
+      + 'entry gives the slug to pass to get_role.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        domain: { type: 'string', description: 'Domain, e.g. avionics.' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'get_standards',
+    description: 'Look up the machine-readable aerospace standards register: publisher, whether '
+      + 'verbatim text is gated, and which roles bind it. Use when a task cites a standard '
+      + '(DO-178C, ARP4754A, AS9100, CS-25, ECSS, ...) and you need its scope or handling rules. '
+      + 'Omit id to list all.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Standard id, e.g. do-178c (case-insensitive).' },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+function text(t) {
+  return { content: [{ type: 'text', text: t }], isError: false };
+}
+
+function toolError(t) {
+  return { content: [{ type: 'text', text: t }], isError: true };
+}
+
+function domainsSummary(catalog) {
+  const doms = new Map();
+  for (const r of catalog.roles) {
+    const d = doms.get(r.domain) || { roles: 0, skills_bound: 0 };
+    d.roles += 1;
+    d.skills_bound += r.skills_bound;
+    doms.set(r.domain, d);
+  }
+  return [...doms.entries()].sort()
+    .map(([name, d]) => `${name}: ${d.roles} roles, ${d.skills_bound} skills bound`)
+    .join('\n');
+}
+
+function callTool(catalog, name, args) {
+  args = args || {};
+  switch (name) {
+    case 'search_roles': {
+      if (!args.query || !String(args.query).trim()) return toolError('query is required');
+      const limit = Math.min(Math.max(args.limit || 5, 1), 25);
+      const hits = catalog.search(String(args.query), limit);
+      if (hits.length === 0) return toolError('no role matches that query. Call list_domains or list_roles to browse.');
+      return text(hits.map((h, i) => `${i + 1}. ${h.role.slug} (score ${h.score})\n   ${h.role.title} — ${h.role.deliverable_type}`).join('\n\n'));
+    }
+    case 'get_role': {
+      const role = catalog.find(String(args.slug || ''));
+      if (!role) {
+        const near = catalog.search(String(args.slug || '').replace(/-/g, ' '), 3)
+          .map((h) => h.role.slug).join(', ');
+        return toolError(`no role '${args.slug}'. Closest: ${near || 'none'}.`);
+      }
+      return text(catalog.readRoleMd(role.slug));
+    }
+    case 'list_domains':
+      return text(domainsSummary(catalog));
+    case 'list_roles': {
+      let roles = catalog.roles;
+      if (args.domain) roles = roles.filter((r) => r.domain === args.domain);
+      if (roles.length === 0) return toolError('no roles match that domain filter. Call list_domains first.');
+      return text(roles.map((r) => `${r.slug}: ${r.title} — ${r.deliverable_type}`).join('\n'));
+    }
+    case 'get_standards': {
+      let standards = catalog.manifest.standards;
+      if (args.id) {
+        const id = String(args.id).toLowerCase();
+        standards = standards.filter((s) => s.id.toLowerCase() === id);
+        if (standards.length === 0) return toolError(`no standard with id '${args.id}'. Omit id to list all.`);
+      }
+      return text(standards.map((s) =>
+        `${s.id}: ${s.name}\n  publisher: ${s.publisher}${s.gated ? ' (gated: no verbatim text)' : ''}\n  roles: ${s.roles.join(', ')}`)
+        .join('\n\n'));
+    }
+    default:
+      return toolError(`unknown tool '${name}'`);
+  }
+}
+
+function serve() {
+  const catalog = new Catalog();
+  let buffer = '';
+
+  const reply = (id, result, error) => {
+    const msg = { jsonrpc: '2.0', id };
+    if (error) msg.error = error;
+    else msg.result = result;
+    process.stdout.write(JSON.stringify(msg) + '\n');
+  };
+
+  const handle = (req) => {
+    const isNotification = req.id === undefined || req.id === null;
+    switch (req.method) {
+      case 'initialize':
+        return reply(req.id, {
+          protocolVersion: (req.params && req.params.protocolVersion) || '2025-06-18',
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: 'aero-agent-roles', version: version() },
+        });
+      case 'ping':
+        return reply(req.id, {});
+      case 'tools/list':
+        return reply(req.id, { tools: TOOLS });
+      case 'tools/call':
+        try {
+          return reply(req.id, callTool(catalog, req.params && req.params.name, req.params && req.params.arguments));
+        } catch (e) {
+          return reply(req.id, toolError(`tool failed: ${e.message}`));
+        }
+      default:
+        if (isNotification) return undefined;
+        return reply(req.id, undefined, { code: -32601, message: `method not found: ${req.method}` });
+    }
+  };
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+    let nl;
+    while ((nl = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      let req;
+      try {
+        req = JSON.parse(line);
+      } catch {
+        reply(null, undefined, { code: -32700, message: 'parse error' });
+        continue;
+      }
+      handle(req);
+    }
+  });
+  process.stdin.on('end', () => process.exit(0));
+}
+
+module.exports = { serve, callTool, TOOLS };