@hybridlabor-api/aos 4.8.0 → 4.10.0

package/packages/aos-cli/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@hybridlabor-api/aos-cli",
+  "version": "0.1.0",
+  "private": true,
+  "description": "AOS CLI -- the AOS dispatcher contract and skills on the pi coding agent",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "aos-cli": "bin/aos-cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "themes/",
+    "scripts/",
+    "extensions/",
+    "core-skills.json",
+    "!packages/aos-cli/node_modules",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node scripts/check-theme.mjs"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "^0.87.1"
+  }
+}

package/packages/aos-cli/scripts/check-theme.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Validate themes/aos.json against pi's theme schema contract.
+//
+// Two things go wrong when you re-skin a pi theme, and neither is obvious:
+// a missing required role makes pi reject the whole theme, and a role pointing
+// at a var that does not exist looks fine in the file but resolves to nothing
+// at render time. This is a theme-tuning loop guard, not a schema validator --
+// it checks the contract pi actually enforces, so it stays small.
+//
+//   node scripts/check-theme.mjs
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const themePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'themes', 'aos.json');
+
+// pi's published theme-schema.json, trimmed to the enforced part: the required
+// colour roles and the five value forms pi accepts (hex, rgb()/oklsl(),
+// 256-colour index, var reference, terminal default).
+const REQUIRED = [
+    'accent', 'border', 'borderAccent', 'borderMuted', 'success', 'error', 'warning',
+    'muted', 'dim', 'text', 'thinkingText', 'selectedBg', 'userMessageBg',
+    'userMessageText', 'customMessageBg', 'customMessageText', 'customMessageLabel',
+    'toolPendingBg', 'toolSuccessBg', 'toolErrorBg', 'toolTitle', 'toolOutput',
+    'mdHeading', 'mdLink', 'mdLinkUrl', 'mdCode', 'mdCodeBlock', 'mdCodeBlockBorder',
+    'mdQuote', 'mdQuoteBorder', 'mdHr', 'mdListBullet', 'toolDiffAdded',
+    'toolDiffRemoved', 'toolDiffContext', 'syntaxComment', 'syntaxKeyword',
+    'syntaxFunction', 'syntaxVariable', 'syntaxString', 'syntaxNumber', 'syntaxType',
+    'syntaxOperator', 'syntaxPunctuation', 'thinkingOff', 'thinkingMinimal',
+    'thinkingLow', 'thinkingMedium', 'thinkingHigh', 'thinkingXhigh', 'bashMode',
+];
+const isLiteral = (v) =>
+    v === '' || typeof v === 'number' ||
+    /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(v) ||
+    /^(rgb|oklsl)\(/.test(v);
+
+const theme = JSON.parse(readFileSync(themePath, 'utf8'));
+const colors = theme.colors ?? {};
+const vars = theme.vars ?? {};
+
+const problems = [];
+if (theme.name !== 'aos') problems.push(`name is "${theme.name}", expected "aos"`);
+for (const role of REQUIRED) {
+    if (!(role in colors)) problems.push(`missing required color role: ${role}`);
+}
+for (const [role, value] of Object.entries(colors)) {
+    if (typeof value !== 'string') problems.push(`${role}: expected a string, got ${typeof value}`);
+    else if (!isLiteral(value) && !(value in vars)) problems.push(`${role}: references undefined var "${value}"`);
+}
+for (const [name, value] of Object.entries(vars)) {
+    if (typeof value === 'string' && value.startsWith('#') && !isLiteral(value)) problems.push(`var ${name}: malformed hex "${value}"`);
+    if (typeof value === 'string' && !value.startsWith('#') && !isLiteral(value) && !(value in vars)) {
+        problems.push(`var ${name}: references undefined var "${value}"`);
+    }
+}
+
+if (problems.length) {
+    for (const p of problems) console.error(`  ${p}`);
+    console.error(`\ntheme invalid (${problems.length} problem${problems.length > 1 ? 's' : ''})`);
+    process.exit(1);
+}
+console.log(`theme "${theme.name}" valid -- ${Object.keys(colors).length} roles, ${Object.keys(vars).length} vars, ${REQUIRED.length} required present`);

package/packages/aos-cli/themes/aos.json

@@ -0,0 +1,97 @@
+{
+	"$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+	"name": "aos",
+	"appearance": "dark",
+	"vars": {
+		"purple": "#9D4EDD",
+		"amethyst": "#9B59B6",
+		"beige": "#DECAA8",
+		"gold": "#D4AF37",
+		"forge": "#FF6321",
+		"emerald": "#2ECC71",
+
+		"cyan": "#00d7ff",
+		"blue": "#5f87ff",
+		"red": "#cc6666",
+		"text": "#d4d4d4",
+		"gray": "#808080",
+		"dimGray": "#666666",
+		"darkGray": "#505050",
+		"accent": "purple",
+		"selectedBg": "#3a3a4a",
+		"userMsgBg": "#343541",
+		"toolPendingBg": "#282832",
+		"toolSuccessBg": "#283228",
+		"toolErrorBg": "#3c2828",
+		"customMsgBg": "#2d2838"
+	},
+	"colors": {
+		"accent": "accent",
+		"border": "amethyst",
+		"borderAccent": "gold",
+		"borderMuted": "darkGray",
+		"success": "emerald",
+		"error": "red",
+		"warning": "forge",
+		"muted": "gray",
+		"dim": "dimGray",
+		"text": "text",
+		"thinkingText": "gray",
+
+		"selectedBg": "selectedBg",
+		"scrollbarTrack": "darkGray",
+		"scrollbarThumb": "text",
+		"searchMatchBg": "selectedBg",
+		"searchMatchText": "text",
+		"userMessageBg": "userMsgBg",
+		"userMessageText": "text",
+		"customMessageBg": "customMsgBg",
+		"customMessageText": "text",
+		"customMessageLabel": "amethyst",
+		"toolPendingBg": "toolPendingBg",
+		"toolSuccessBg": "toolSuccessBg",
+		"toolErrorBg": "toolErrorBg",
+		"toolTitle": "text",
+		"toolOutput": "gray",
+
+		"mdHeading": "beige",
+		"mdLink": "cyan",
+		"mdLinkUrl": "dimGray",
+		"mdCode": "accent",
+		"mdCodeBlock": "emerald",
+		"mdCodeBlockBorder": "gray",
+		"mdQuote": "gray",
+		"mdQuoteBorder": "amethyst",
+		"mdHr": "gray",
+		"mdListBullet": "accent",
+
+		"toolDiffAdded": "emerald",
+		"toolDiffRemoved": "red",
+		"toolDiffContext": "gray",
+
+		"syntaxComment": "#6A9955",
+		"syntaxKeyword": "#569CD6",
+		"syntaxFunction": "#DCDCAA",
+		"syntaxVariable": "#9CDCFE",
+		"syntaxString": "#CE9178",
+		"syntaxNumber": "#B5CEA8",
+		"syntaxType": "#4EC9B0",
+		"syntaxOperator": "#D4D4D4",
+		"syntaxPunctuation": "#D4D4D4",
+
+		"thinkingOff": "darkGray",
+		"thinkingMinimal": "#6e6e6e",
+		"thinkingLow": "#5f87af",
+		"thinkingMedium": "#81a2be",
+		"thinkingHigh": "amethyst",
+		"thinkingXhigh": "purple",
+		"thinkingMax": "#ff5fff",
+
+		"bashMode": "emerald"
+	},
+	"export": {
+		"pageBg": "#18181e",
+		"cardBg": "#1e1e24",
+		"infoBg": "#3c3728"
+	}
+}

package/scripts/build-plugin-manifest.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+// Generates .claude-plugin/plugin.json and the plugin-root agents/ directory.
+//
+// Claude Code resolves plugin components two different ways, and only one of
+// them is obvious:
+//
+//   skills  -> the manifest's "skills" array, one entry per skill DIRECTORY.
+//              No globs ("skills/*/*/" is rejected as "Path not found") and no
+//              recursion (a category dir like ./skills/global_config resolves to
+//              nothing, because it holds no SKILL.md of its own). Every skill
+//              must therefore be named explicitly, or it silently ships nothing.
+//   agents  -> convention only, <plugin-root>/agents/*.md. The manifest's
+//              "agents" key is accepted by the schema and then ignored, so a
+//              correct-looking path list there yields 0 agents and no warning.
+//
+// The AOS skills live at skills/<category>/<name>/SKILL.md, two levels deep, and
+// the agent personas live at .claude/agents/ (referenced by .agents/nodes.json
+// personaFile paths and regenerated by installer.js, so they cannot move). Both
+// facts mean the plugin needs a generated layout, which is what this script is.
+//
+// Usage: node scripts/build-plugin-manifest.mjs [--check]
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const CHECK = process.argv.includes('--check');
+
+const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'));
+const repoUrl = pkg.repository?.url?.replace(/^git\+/, '').replace(/\.git$/, '') ??
+  'https://github.com/hybridlabor-api/aos';
+
+function walkSkills(dir, output = []) {
+  if (!existsSync(dir)) return output;
+  for (const item of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, item.name);
+    if (item.isDirectory()) walkSkills(full, output);
+    else if (item.name === 'SKILL.md') output.push(dirname(full));
+  }
+  return output;
+}
+
+const skillDirs = walkSkills(join(ROOT, 'skills')).sort();
+if (skillDirs.length === 0) throw new Error('No skills found under skills/ — refusing to write an empty manifest');
+
+const skills = skillDirs.map((dir) => `./${relative(ROOT, dir).split(/[\\/]/).join('/')}`);
+
+const agentSrc = join(ROOT, '.claude', 'agents');
+const agentDst = join(ROOT, 'agents');
+const agentNames = existsSync(agentSrc)
+  ? readdirSync(agentSrc).filter((name) => name.endsWith('.md')).sort()
+  : [];
+
+// The personas are the same 13 files the repo loads via .claude/agents/. They are
+// copied rather than symlinked because validate --strict (the release gate)
+// refuses a symlinked component directory, and a symlink is fragile once the
+// plugin is cloned or downloaded on a platform that does not create them.
+const drift = [];
+if (!CHECK) mkdirSync(agentDst, { recursive: true });
+for (const name of agentNames) {
+  const want = readFileSync(join(agentSrc, name));
+  const path = join(agentDst, name);
+  if (!existsSync(path) || !readFileSync(path).equals(want)) {
+    if (CHECK) drift.push(name);
+    else {
+      writeFileSync(path, want);
+      console.log(`synced agents/${name}`);
+    }
+  }
+}
+if (!CHECK) {
+  for (const name of readdirSync(agentDst)) {
+    if (!agentNames.includes(name)) {
+      rmSync(join(agentDst, name));
+      console.log(`removed stale agents/${name}`);
+    }
+  }
+}
+
+const manifest = {
+  $schema: 'https://anthropic.com/claude-code/plugin.schema.json',
+  name: 'bdb-aos',
+  version: pkg.version,
+  description:
+    'Full BDB Agent OS suite: 200+ curated skills, subagents, the startcycle pipeline, ' +
+    'CI/CD workflows and security hooks for Claude Code.',
+  author: { name: 'Tim Rennings / Hybridlabor Global LLC', email: 'hybridlabor@gmail.com' },
+  homepage: repoUrl,
+  repository: repoUrl,
+  license: 'proprietary',
+  keywords: ['skills', 'agent-os', 'cicd', 'multiagent', 'startcycle', 'bdb'],
+  skills,
+};
+
+const target = join(ROOT, '.claude-plugin', 'plugin.json');
+const serialized = `${JSON.stringify(manifest, null, 2)}\n`;
+const current = existsSync(target) ? readFileSync(target, 'utf8') : '';
+
+// `claude plugin tag` refuses to cut a release unless plugin.json and the
+// enclosing marketplace entry agree on the version, so the marketplace copy of
+// the number is generated here too rather than hand-maintained.
+const marketPath = join(ROOT, '.claude-plugin', 'marketplace.json');
+const market = JSON.parse(readFileSync(marketPath, 'utf8'));
+const entry = market.plugins?.find((plugin) => plugin.name === manifest.name);
+if (!entry) throw new Error(`marketplace.json has no entry named ${manifest.name}`);
+entry.version = pkg.version;
+const marketSerialized = `${JSON.stringify(market, null, 2)}\n`;
+const marketCurrent = readFileSync(marketPath, 'utf8');
+
+if (CHECK) {
+  if (current !== serialized) {
+    console.error('plugin.json is out of date — run: node scripts/build-plugin-manifest.mjs');
+    process.exit(1);
+  }
+  if (marketCurrent !== marketSerialized) {
+    console.error('marketplace.json version is out of date — run: node scripts/build-plugin-manifest.mjs');
+    process.exit(1);
+  }
+  if (drift.length > 0) {
+    console.error(`agents/ is out of date (${drift.join(', ')}) — run: node scripts/build-plugin-manifest.mjs`);
+    process.exit(1);
+  }
+  console.log(`plugin manifest up to date: ${skills.length} skills, ${agentNames.length} agents`);
+} else {
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, serialized);
+  writeFileSync(marketPath, marketSerialized);
+  console.log(`Wrote .claude-plugin/plugin.json with ${skills.length} skills and ${agentNames.length} agents`);
+}

package/scripts/validate-skills.mjs

@@ -17,6 +17,19 @@ const CATEGORIES = new Set([
 ]);
 const REQUIRED = ['name', 'description', 'category'];
 
+// The Agent Skills specification constrains `name` to lowercase letters,
+// numbers, and single hyphens, max 64 chars. A harness that enforces the spec
+// drops such a skill silently, so a self-consistent name==directory pair is
+// not enough: `MCP_Manage` matched its own directory perfectly and was still
+// unloadable by pi. Tolerant harnesses hide this; strict ones lose the skill.
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const NAME_MAX = 64;
+
+// Charset and length are one rule. Keeping them as two expressions meant the
+// selftest could assert the charset and pass while the length limit lived only
+// in validate() -- the two can drift, and then the test proves nothing.
+const isValidSkillName = (v) => v.length <= NAME_MAX && NAME_RE.test(v);
+
 // Names that are stand-ins or service accounts rather than a person. The rule
 // is about leaking a human's username; `/home/agent` on the SaaS fleet is a
 // role account and is meant to be written down.
@@ -36,7 +49,7 @@ function findClosingQuote(s, from, q) {
   for (let i = from; i < s.length; i++) {
     if (s[i] !== q) continue;
     if (q === "'" && s[i + 1] === "'") { i++; continue; }   // '' escapes a quote
-    if (q === '"' && s[i - 1] === '\\') continue;
+    if (q === '"') { let b = 0, j = i - 1; while (j >= from && s[j] === '\\') { b++; j--; } if (b % 2 !== 0) continue; }
     return i;
   }
   return -1;
@@ -108,6 +121,18 @@ export function scanFrontmatter(text) {
       }
     } else {
       eatIndented(false);                                  // plain scalar
+      // A plain (unquoted) scalar containing ": " is a nested mapping as far as
+      // YAML is concerned. The scanner above takes the rest of the line as the
+      // value and sees nothing wrong, and so does every lenient harness — but
+      // a spec-conformant reader parses it as a map, drops the frontmatter, and
+      // the skill never loads. `description: live map: of a build` is the shape.
+      if (/:(\s|$)/.test(restT)) {
+        issues.push({
+          code: 'E-YAML04', key,
+          msg: `plain value of \`${key}\` contains ":" — YAML reads the rest as a nested mapping, not text. ` +
+               'Quote the value or fold it (>-); as written the frontmatter does not parse.',
+        });
+      }
     }
 
     if (swallowed.length) {
@@ -247,11 +272,21 @@ function validate() {
     }
 
     const name = byKey.get('name');
-    if (name && unquote(name.value) !== dirName) {
-      findings.push({
-        level: 'error', code: 'E-FM04', file: rel, line: name.line,
-        msg: `\`name: ${unquote(name.value)}\` does not match its directory \`${dirName}\``,
-      });
+    if (name) {
+      const value = unquote(name.value);
+      if (!isValidSkillName(value)) {
+        findings.push({
+          level: 'error', code: 'E-NAME01', file: rel, line: name.line,
+          msg: `\`name: ${value}\` is not spec-valid — lowercase a-z, 0-9 and single hyphens only, max ${NAME_MAX} chars. ` +
+               'A harness that enforces the Agent Skills spec will not load this skill at all.',
+        });
+      }
+      if (value !== dirName) {
+        findings.push({
+          level: 'error', code: 'E-FM04', file: rel, line: name.line,
+          msg: `\`name: ${value}\` does not match its directory \`${dirName}\``,
+        });
+      }
     }
 
     const desc = byKey.get('description');
@@ -383,9 +418,49 @@ function selftest() {
   assert.equal(quoted.issues.length, 0);
   assert.equal(quoted.keys.find((k) => k.key === 'category').value, 'library');
 
+  // A plain scalar holding ": " is a nested mapping to a real YAML reader, so
+  // the frontmatter does not parse and the skill never loads. Every lenient
+  // harness accepts it, which is how agenttrail shipped: the shape passed this
+  // validator, Claude Code and Antigravity, and only pi rejected it.
+  const colon = scanFrontmatter([
+    '---', 'name: agenttrail', 'description: Live map of a build: which component',
+    'category: bdb-core', '---',
+  ].join('\n'));
+  assert.ok(
+    colon.issues.some((i) => i.code === 'E-YAML04'),
+    'a plain scalar containing ": " must be reported',
+  );
+  assert.equal(colon.keys.find((k) => k.key === 'description').value, 'Live map of a build: which component');
+
+  // A colon that is not followed by whitespace is not a mapping boundary --
+  // URLs and times are the common false positive.
+  const url = scanFrontmatter([
+    '---', 'name: firecrawl', 'description: See https://example.com/a:b for the API',
+    'category: library', '---',
+  ].join('\n'));
+  assert.ok(!url.issues.some((i) => i.code === 'E-YAML04'), 'a colon inside a URL is not a mapping');
+
+  // The quoted form of the same text is fine -- that is the fix.
+  const quotedColon = scanFrontmatter([
+    '---', 'name: agenttrail', 'description: "Live map of a build: which component"',
+    'category: bdb-core', '---',
+  ].join('\n'));
+  assert.equal(quotedColon.issues.length, 0, 'quoting the value resolves E-YAML04');
+
   assert.equal(scanFrontmatter('# no frontmatter').ok, false);
   assert.equal(scanFrontmatter('---\nname: x\n').reason, 'unterminated');
 
+  // The spec's name charset, and the case that shipped: MCP_Manage matched its
+  // own directory perfectly and was still unloadable by a strict reader.
+  for (const bad of ['MCP_Manage', 'MCP-manage', 'mcp_manage', '-mcp', 'mcp-', 'mcp--manage', 'mcp manage']) {
+    assert.ok(!isValidSkillName(bad), `\`${bad}\` must not be a valid skill name`);
+  }
+  for (const good of ['mcp-manage', 'ask-tim', 'a', 'skill2', 'a-b-c-1']) {
+    assert.ok(isValidSkillName(good), `\`${good}\` must be a valid skill name`);
+  }
+  assert.ok(isValidSkillName('a'.repeat(NAME_MAX)), 'a 64-char name is at the limit and valid');
+  assert.ok(!isValidSkillName('a'.repeat(NAME_MAX + 1)), 'a 65-char name is over the limit');
+
   console.log('✓ selftest passed');
 }
 

package/skills/basic/ao-orchestrator/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: ao-orchestrator
+description: Use when acting as the multi-project orchestrator and lead coordinator across repositories using the Agent Orchestrator (AO) daemon. Spawns, inspects, coordinates, and reviews parallel coding agents in isolated Git worktrees.
+category: bdb-core
+risk: safe
+tools:
+- claude-code
+- antigravity
+- opencode
+- cursor
+- codex-cli
+---
+
+# 👑 AO Multi-Project Orchestrator (`/ao-orchestrator`)
+
+## Overview
+
+This skill equips any AI coding agent across all supported harnesses (**Claude Code**, **Google Antigravity**, **OpenCode**, **Cursor**, **Codex**) to act as a **Multi-Project Orchestrator** supervising tasks across independent code repositories via the **Agent Orchestrator (AO)** background daemon (`~/.local/bin/ao`).
+
+Instead of making changes directly across multiple repositories within a single context window, the Orchestrator breaks down high-level business goals into scoped work items, delegates them to specialized worker agents running in isolated Git worktrees, monitors their progress, and reviews/integrates their Pull Requests.
+
+---
+
+## 🧭 Orchestrator Responsibilities
+
+1. **Project Discovery & Mapping**: Identify which repositories and workspaces are involved in the user's goal.
+2. **Task Decomposition**: Split cross-repo features into clear, atomic specifications for individual worker sessions.
+3. **Session Lifecycle Management**: Spawn worker agents with explicit roles (`architect`, `techlead`, `ui_ux`, `engineering`, `reviewer`, `shipping`), appropriate harnesses (`claude-code`, `opencode`, `agy`), and specific prompts.
+4. **Coordination & Supervision**: Track running sessions via `ao session ls`, inspect agent logs, and inject steering instructions or clarifications via `ao send`.
+5. **Quality Gate & PR Review**: Run `ao review` once a worker completes its task, verify tests, and coordinate cross-project integration.
+
+---
+
+## 🛠️ AO CLI Core Command Suite
+
+The Orchestrator interacts with the local daemon (listening on loopback port `3101`) strictly through the `ao` CLI:
+
+### 1. Discovery & Status
+```bash
+# Check AO daemon health and version
+ao status
+
+# List all registered repositories and workspaces
+ao project ls
+
+# List active and recent agent sessions across all projects
+ao session ls
+```
+
+### 2. Spawning Multi-Project Workers
+Run worker agents in fresh, isolated Git worktrees (`ao/<session-id>/root`) so they never conflict with uncommitted working trees:
+
+```bash
+# Spawn a Backend Engineer in Project A
+ao spawn \
+  --project <project-id-or-path> \
+  --name "Backend-API" \
+  --role engineering \
+  --harness claude-code \
+  --prompt "Implement the OAuth2 callback handler per specification in issue #42. Ensure all tests pass."
+
+# Spawn a Frontend Designer/Engineer in Project B
+ao spawn \
+  --project <project-id-or-path> \
+  --name "Frontend-UI" \
+  --role ui_ux \
+  --harness claude-code \
+  --prompt "Build the settings page OAuth connection cards with Tailwind and React."
+
+# Spawn an Adversarial Reviewer for an existing worker branch
+ao spawn \
+  --project <project-id-or-path> \
+  --name "Audit-Worker" \
+  --role reviewer \
+  --prompt "Review branch ao/<session-id>/root for security gaps, unhandled errors, and contract compliance."
+```
+
+### 3. Monitoring & Steering Sessions
+```bash
+# Inspect detailed state of a specific session
+ao session get <session-id>
+
+# Send instructions, feedback, or corrections to a running worker
+ao send <session-id> "The database migration must support SQLite and Postgres. Please update the schema."
+
+# Switch agent harness if needed (e.g. switch to opencode or agy)
+ao session switch-agent <session-id> --to opencode
+```
+
+### 4. Review & Completion
+```bash
+# Trigger an AO code review of the worker's changes
+ao review <session-id>
+
+# Clean up or terminate completed sessions
+ao session kill <session-id>
+ao session cleanup
+```
+
+---
+
+## 📋 Multi-Project Orchestration Protocol
+
+When the user asks you to coordinate work across multiple projects:
+
+1. **Step 1: Check Registered Projects**
+   Run `ao project ls` to verify the repositories exist in AO. If a project is not registered, instruct the user to register it or navigate to the directory and run `ao project add .`.
+2. **Step 2: Propose the Architecture & Work Breakdown**
+   Present a clear plan to the user:
+   - Which repo needs what changes.
+   - What workers will be spawned and with which AOS roles.
+   - The dependency order (e.g. Backend API first, then Frontend integration).
+3. **Step 3: Spawn Workers Orderly**
+   Spawn the prerequisite workers. Avoid spawning dependent workers before the contract/API they depend on is established.
+4. **Step 4: Report Progress to User**
+   Provide regular, concise summaries in your response showing the status of each spawned session and next actions.