adaptive-director-skill 0.1.1 → 1.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/adaptive-director-skill.svg)](https://www.npmjs.com/package/adaptive-director-skill)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
-[![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20(pure%20built--ins)-blue.svg)](#architecture)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20(pure%20built--ins)-blue.svg)](#core-principles)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 > **One task in. The right agents take it from there.**
@@ -59,31 +59,59 @@ flowchart LR
 
 Adaptive Director runs with **zero external npm dependencies** (pure Node.js built-ins).
 
-### 1. Install & Setup
+### 1. Install Globally
 
-Via npm:
 ```bash
-npm install adaptive-director-skill
+npm install -g adaptive-director-skill
 ```
 
-Or clone directly:
+### 2. Set Up
+
+> `adaptive-director setup` registers the Skill with your coding-agent hosts, discovers available agents, detects optional delegate-skills integration, and creates the local Adaptive Director configuration.
+
 ```bash
-git clone https://github.com/tamourax/Adaptive-Orchestrator.git
-cd Adaptive-Orchestrator
+adaptive-director setup
 ```
 
-Initialize local configuration and run verification:
+Or without a global install:
+
+```bash
+npx adaptive-director-skill setup
+```
+
+### 3. Verify
+
 ```bash
-node scripts/setup.mjs
-node scripts/smoke-test.mjs
+adaptive-director doctor
 ```
 
-### 2. Run with Your AI Agent
+Expected output:
+```
+✓ Package installed
+✓ Skill source exists
+✓ SKILL.md exists
+✓ references/ exists
+✓ templates/ exists
+✓ examples/ exists
+✓ Registry exists
+✓ Registry valid
+✓ Config exists
+✓ Config valid
+✓ Routing script works
+✓ Run state script exists
+✓ Resume script exists
+✓ codex detected
+✓ Skill installed for codex
+
+Ready.
+```
 
-Load `SKILL.md` into your coding agent (Claude Code, Antigravity, Codex, etc.) and prompt:
+### 4. Run with Your AI Agent
+
+The Skill is now installed in your agent's skills directory. Prompt your agent:
 
 ```text
-Use $adaptive-director-skill to implement Stripe checkout in Flutter
+Use $adaptive-director to implement Stripe checkout in Flutter
 ```
 
 ---
@@ -103,33 +131,50 @@ Use $adaptive-director-skill to implement Stripe checkout in Flutter
 
 ---
 
-## Architecture
+## Repository Architecture
+
+The repository separates the **npm management/installer layer** from the **self-contained Agent Skill**:
 
-> *"Reasoning stays with agents. Deterministic operations stay in scripts."*
+- **Repository Root:** npm distribution, CLI tools, setup, host discovery, and health diagnostics (`scripts/`).
+- **`skills/adaptive-director/`:** The canonical, portable Agent Skill (procedural brain, runtime scripts, templates, references, and registry data).
 
 ```text
-adaptive-director/
-├── SKILL.md                 # The brain: instructions read by your AI agent
-├── data/registry.json       # Baseline model capability scores (1–5)
-├── references/              # Handoff schemas, rules, and delegate docs
-└── scripts/                 # Deterministic Node.js helpers (pure built-ins)
-    ├── discover.mjs         # Detects local agent CLIs
-    ├── route.mjs            # Computes agent + effort assignments
-    ├── run-state.mjs        # Manages isolated phase briefs & workspaces
-    └── resume.mjs           # Recovers interrupted runs
+Adaptive-Director-Skill/
+├── scripts/                      # Management & CLI layer
+│   ├── cli.mjs                   # Main CLI router
+│   ├── setup.mjs                 # Interactive host setup
+│   ├── install.mjs               # Idempotent skill copier
+│   ├── refresh.mjs               # Safe config refresher
+│   ├── discover.mjs              # Local agent discovery
+│   ├── doctor.mjs                # Installation diagnostics
+│   └── smoke-test.mjs            # Automated test suite
+│
+└── skills/adaptive-director/     # Portable Agent Skill (the brain)
+    ├── SKILL.md                  # Procedural runbook
+    ├── scripts/                  # Runtime scripts (route, run-state, resume)
+    ├── references/               # Deep documentation & schemas
+    ├── templates/                # Standardized phase brief templates
+    ├── examples/                 # Realistic execution walkthroughs
+    └── data/                     # Capability registry
 ```
 
-### Routing Priority Order
+---
 
-1. **User Overrides:** Explicit settings in `~/.adaptive-director/config.yaml`
-2. **Delegate Lanes:** Optional `delegate-skills` fleet lanes (when `--delegate` is active)
-3. **Capability Registry:** Best available local model meeting phase requirements
-4. **Fallback:** Default host agent
+## CLI Commands
+
+```bash
+adaptive-director setup     # Interactive: discover hosts, install Skill, create config
+adaptive-director install   # Re-install/update Skill in host directories
+adaptive-director refresh   # Re-discover hosts & update config (preserves overrides)
+adaptive-director doctor    # Validate installation and health
+adaptive-director help      # Show usage
+```
 
 ---
 
 ## Core Principles
 
+- **Routing Priority:** User overrides → Delegate fleet lanes → Capability registry → Default fallback.
 - **Independent Review:** The coder never reviews its own work.
 - **Max Reasoning Opt-in:** `max` effort is locked by default; requires `--allow-max`.
 - **Runaway Loop Protection:** Maximum 1 automated fix cycle before alerting the user.
@@ -138,19 +183,43 @@ adaptive-director/
 
 ---
 
-## Configuration (`~/.adaptive-director/config.yaml`)
+## Configuration (`~/.adaptive-director/config.json`)
+
+```json
+{
+  "version": 1,
+  "defaultBudget": "balanced",
+  "overrides": {
+    "plan": "claude",
+    "implement": "codex"
+  }
+}
+```
+
+---
 
-```yaml
-defaultBudget: balanced # conservative | balanced | quality
+## Upgrading
 
-# Optional overrides:
-agentOverrides.plan: claude
-agentOverrides.implement: codex
-agentOverrides.review: claude
+After a package upgrade, re-install the Skill into your host environments:
+
+```bash
+npm install -g adaptive-director-skill@latest
+adaptive-director install
+adaptive-director doctor
 ```
 
 ---
 
+## Uninstalling
+
+```bash
+npm uninstall -g adaptive-director-skill
+```
+
+> **Note:** npm uninstall removes the package, but does **not** remove Skill copies that were installed into your coding-agent host directories. To clean those up, manually delete the `Adaptive-Director/` folder from each host skill directory (e.g. `~/.codex/skills/Adaptive-Director/`).
+
+---
+
 ## License
 
 MIT License © 2026 [Ahmed Tamer](https://github.com/tamourax). See [LICENSE](LICENSE) for details.

package/package.json

@@ -1,26 +1,28 @@
 {
   "name": "adaptive-director-skill",
-  "version": "0.1.1",
+  "version": "1.0.0",
   "description": "Adaptive Director Skill — Skill-first adaptive multi-agent orchestration for AI coding agents",
   "type": "module",
+  "bin": {
+    "adaptive-director": "scripts/cli.mjs"
+  },
   "license": "MIT",
   "author": "Ahmed Tamer",
   "repository": {
     "type": "git",
-    "url": "https://github.com/tamourax/Adaptive-Orchestrator.git"
+    "url": "git+https://github.com/tamourax/Adaptive-Director-Skill.git"
   },
   "files": [
-    "SKILL.md",
     "README.md",
     "LICENSE",
     "scripts/",
-    "references/",
-    "data/"
+    "skills/"
   ],
   "scripts": {
     "test": "node scripts/smoke-test.mjs",
     "setup": "node scripts/setup.mjs",
-    "discover": "node scripts/discover.mjs"
+    "discover": "node scripts/discover.mjs",
+    "doctor": "node scripts/doctor.mjs"
   },
   "keywords": [
     "ai",

package/scripts/cli.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const args = process.argv.slice(2);
+const command = args[0] || 'help';
+
+const commands = {
+  setup: 'setup.mjs',
+  install: 'install.mjs',
+  refresh: 'refresh.mjs',
+  doctor: 'doctor.mjs',
+};
+
+if (command === 'help' || command === '--help' || command === '-h') {
+  console.log(`Adaptive Director Skill CLI v1.0.0
+
+Usage:
+  adaptive-director <command>
+
+Commands:
+  setup    - Initial interactive setup and installation
+  install  - Install/copy the Skill into supported host skill directories
+  refresh  - Re-run discovery and update config without destroying user overrides
+  doctor   - Validate installation and report health
+  help     - Show this help message
+`);
+  process.exit(0);
+}
+
+const targetScript = commands[command];
+
+if (!targetScript) {
+  console.error(`Unknown command: ${command}`);
+  console.log(`Run 'adaptive-director help' for usage.`);
+  process.exit(1);
+}
+
+const scriptPath = path.join(__dirname, targetScript);
+
+if (!fs.existsSync(scriptPath)) {
+  console.error(`Command not yet implemented: ${command}`);
+  process.exit(1);
+}
+
+const result = spawnSync('node', [scriptPath, ...args.slice(1)], {
+  stdio: 'inherit'
+});
+
+process.exit(result.status ?? 1);

package/scripts/discover.mjs

@@ -20,15 +20,15 @@ import { homedir } from 'node:os'
 // ─── Known agents ─────────────────────────────────────────────────────────────
 
 const KNOWN_AGENTS = [
-  { id: 'claude',    bins: ['claude'],       versionArgs: ['--version'] },
-  { id: 'codex',     bins: ['codex'],        versionArgs: ['--version'] },
-  { id: 'agy',       bins: ['agy'],          versionArgs: ['--version'] },
-  { id: 'gemini',    bins: ['gemini'],       versionArgs: ['--version'] },
-  { id: 'opencode',  bins: ['opencode'],     versionArgs: ['--version'] },
-  { id: 'aider',     bins: ['aider'],        versionArgs: ['--version'] },
-  { id: 'cursor',    bins: ['cursor-agent'], versionArgs: ['--version'] },
-  { id: 'cline',     bins: ['cline'],        versionArgs: ['--version'] },
-  { id: 'copilot',   bins: ['copilot'],      versionArgs: ['--version'] },
+  { id: 'claude',    bins: ['claude'],       versionArgs: ['--version'], skillPaths: ['.claude/skills', '.config/claude/skills'] },
+  { id: 'codex',     bins: ['codex'],        versionArgs: ['--version'], skillPaths: ['.codex/skills'] },
+  { id: 'agy',       bins: ['agy'],          versionArgs: ['--version'], skillPaths: ['.gemini/antigravity/builtin/skills', '.gemini/antigravity/skills', '.gemini/antigravity-ide/skills'] },
+  { id: 'gemini',    bins: ['gemini'],       versionArgs: ['--version'], skillPaths: ['.gemini/skills'] },
+  { id: 'opencode',  bins: ['opencode'],     versionArgs: ['--version'], skillPaths: ['.opencode/skills'] },
+  { id: 'aider',     bins: ['aider'],        versionArgs: ['--version'], skillPaths: ['.aider/skills'] },
+  { id: 'cursor',    bins: ['cursor-agent'], versionArgs: ['--version'], skillPaths: ['.cursor/skills'] },
+  { id: 'cline',     bins: ['cline'],        versionArgs: ['--version'], skillPaths: ['.cline/skills'] },
+  { id: 'copilot',   bins: ['copilot'],      versionArgs: ['--version'], skillPaths: ['.copilot/skills'] },
 ]
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -116,10 +116,23 @@ function discover() {
     }
 
     const version = getVersion(bin, desc.versionArgs)
+    let detectedSkillPath = null
+    if (desc.skillPaths) {
+      for (const sp of desc.skillPaths) {
+        const fullPath = join(homedir(), sp)
+        if (existsSync(fullPath)) {
+          detectedSkillPath = fullPath
+          break
+        }
+      }
+    }
+
     agents[desc.id] = {
       installed:  true,
       available:  version !== null,
       version:    version ?? 'unknown',
+      skillPath:  detectedSkillPath,
+      hasSkill:   detectedSkillPath ? existsSync(join(detectedSkillPath, 'adaptive-director')) || existsSync(join(detectedSkillPath, 'Adaptive-Director')) || existsSync(join(detectedSkillPath, 'adaptive-director-skill')) : false
     }
   }
 

package/scripts/doctor.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function run(script, args = []) {
+  try {
+    const out = execFileSync(process.execPath, [script, ...args], {
+      encoding: 'utf8', timeout: 15000,
+      cwd: process.cwd(),
+    });
+    return JSON.parse(out.trim());
+  } catch {
+    return null;
+  }
+}
+
+function check(label, condition, fix = null) {
+  if (condition) {
+    console.log(`✓ ${label}`);
+    return true;
+  } else {
+    console.log(`✗ ${label}`);
+    if (fix) console.log(`  Fix: ${fix}`);
+    return false;
+  }
+}
+
+function warn(label) {
+  console.log(`! ${label}`);
+}
+
+const configDir = join(homedir(), '.adaptive-director');
+const configPath = join(configDir, 'config.json');
+const pkgRoot = join(__dirname, '..');
+const skillRoot = join(pkgRoot, 'skills', 'adaptive-director');
+
+console.log('Adaptive Director Doctor\n');
+
+let allGood = true;
+
+// ── Package & Skill files ──────────────────────────────────────────────────
+allGood &= check('Package installed',     existsSync(join(pkgRoot, 'package.json')));
+allGood &= check('Skill source exists',   existsSync(skillRoot));
+allGood &= check('SKILL.md exists',       existsSync(join(skillRoot, 'SKILL.md')));
+allGood &= check('references/ exists',    existsSync(join(skillRoot, 'references')));
+allGood &= check('templates/ exists',     existsSync(join(skillRoot, 'templates')));
+allGood &= check('examples/ exists',      existsSync(join(skillRoot, 'examples')));
+
+// ── Registry ──────────────────────────────────────────────────────────────
+const registryPath = join(skillRoot, 'data', 'registry.json');
+if (check('Registry exists', existsSync(registryPath))) {
+  try {
+    JSON.parse(readFileSync(registryPath, 'utf8'));
+    check('Registry valid', true);
+  } catch {
+    allGood &= check('Registry valid', false, 'Reinstall package');
+  }
+} else {
+  allGood = false;
+}
+
+// ── Config ────────────────────────────────────────────────────────────────
+if (check('Config exists', existsSync(configPath), 'adaptive-director setup')) {
+  try {
+    JSON.parse(readFileSync(configPath, 'utf8'));
+    check('Config valid', true);
+  } catch {
+    allGood &= check('Config valid', false, 'rm ~/.adaptive-director/config.json && adaptive-director setup');
+  }
+} else {
+  allGood = false;
+}
+
+// ── Runtime Skill Scripts ─────────────────────────────────────────────────
+const routePath = join(skillRoot, 'scripts', 'route.mjs');
+if (existsSync(routePath)) {
+  try {
+    const testPayload = JSON.stringify({ taskSize: 'small', phase: 'implement', budget: 'balanced', allowMax: false, delegateEnabled: false });
+    const out = execFileSync(process.execPath, [routePath, '--input', testPayload], {
+      encoding: 'utf8', timeout: 8000
+    });
+    const result = JSON.parse(out.trim());
+    const valid = result && result.agent && result.effort && result.execution;
+    allGood &= check('Routing script works', valid, 'Check Node version or reinstall');
+  } catch (e) {
+    allGood &= check('Routing script works', false, `Error: ${e.message}`);
+  }
+} else {
+  allGood &= check('Routing script works', false, 'Script missing in skills/adaptive-director/scripts — reinstall package');
+}
+
+allGood &= check('Run state script exists', existsSync(join(skillRoot, 'scripts', 'run-state.mjs')));
+allGood &= check('Resume script exists',    existsSync(join(skillRoot, 'scripts', 'resume.mjs')));
+
+// ── Host discovery ────────────────────────────────────────────────────────
+console.log('');
+const discovery = run(join(__dirname, 'discover.mjs'));
+if (discovery) {
+  let anyHost = false;
+  for (const [id, info] of Object.entries(discovery.agents ?? {})) {
+    if (!info.installed) continue;
+    anyHost = true;
+    check(`${id} detected`, true);
+    const hostHasSkill = info.skillPath && (
+      existsSync(join(info.skillPath, 'adaptive-director', 'SKILL.md')) ||
+      existsSync(join(info.skillPath, 'Adaptive-Director', 'SKILL.md'))
+    );
+    if (hostHasSkill) {
+      check(`Skill installed for ${id}`, true);
+    } else if (info.skillPath) {
+      allGood &= check(`Skill installed for ${id}`, false,
+        `adaptive-director install ${info.skillPath}`);
+    } else {
+      warn(`Skill for ${id}: skill directory unknown (run setup after configuring host)`);
+    }
+  }
+  if (!anyHost) warn('No supported hosts detected');
+
+  console.log('');
+  const ds = discovery.delegateSkills ?? { installed: false };
+  if (ds.installed) {
+    check(`delegate-skills detected (${Object.keys(ds.lanes ?? {}).length} lane(s))`, true);
+  } else {
+    warn('delegate-skills not detected (optional)');
+  }
+} else {
+  allGood &= check('Discovery script works', false, 'Check Node version or reinstall');
+}
+
+console.log('');
+if (allGood) {
+  console.log('Ready.');
+} else {
+  console.log('Some checks failed. Run "adaptive-director setup" to fix.');
+  process.exitCode = 1;
+}

package/scripts/install.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, cpSync, rmSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, '..');
+
+const args = process.argv.slice(2);
+const targets = args.filter(a => !a.startsWith('-'));
+
+const canonicalSkillSource = join(projectRoot, 'skills', 'adaptive-director');
+
+/**
+ * Copy Adaptive Director Skill files into a host skill directory.
+ * Idempotent: removes old copy first, then copies fresh from skills/adaptive-director.
+ */
+function installInto(hostSkillDir) {
+  const dest = join(hostSkillDir, 'adaptive-director');
+  console.log(`  Installing into ${dest}...`);
+  if (!existsSync(canonicalSkillSource)) {
+    console.error(`  Error: Canonical skill source not found at ${canonicalSkillSource}`);
+    process.exit(1);
+  }
+  // Remove legacy title-case folder if different and present
+  const legacyDest = join(hostSkillDir, 'Adaptive-Director');
+  if (legacyDest.toLowerCase() === dest.toLowerCase() && existsSync(legacyDest)) {
+    rmSync(legacyDest, { recursive: true, force: true });
+  } else if (existsSync(dest)) {
+    rmSync(dest, { recursive: true, force: true });
+  }
+  mkdirSync(dest, { recursive: true });
+  cpSync(canonicalSkillSource, dest, { recursive: true });
+  console.log(`  ✓ Installed successfully at ${dest}`);
+}
+
+// ─── If paths were passed as arguments, install into those directly ─────────
+if (targets.length > 0) {
+  for (const target of targets) {
+    installInto(target);
+  }
+  process.exit(0);
+}
+
+// ─── No args: auto-discover hosts and install ───────────────────────────────
+const discoverScript = join(__dirname, 'discover.mjs');
+
+function runDiscover() {
+  try {
+    const out = execFileSync(process.execPath, [discoverScript], {
+      encoding: 'utf8', timeout: 15000, cwd: process.cwd(),
+    });
+    return JSON.parse(out.trim());
+  } catch {
+    return null;
+  }
+}
+
+console.log('\n  Adaptive Director — Install\n');
+console.log('  Discovering hosts...\n');
+
+const discovery = runDiscover();
+if (!discovery) {
+  console.error('  Error: discovery failed.');
+  process.exit(1);
+}
+
+const hostsWithSkillDir = [];
+for (const [id, info] of Object.entries(discovery.agents ?? {})) {
+  if (info.installed && info.skillPath) {
+    hostsWithSkillDir.push({ id, path: info.skillPath });
+  } else if (info.installed) {
+    console.log(`  ! ${id}: installed but skill directory could not be resolved. Skipping.`);
+  }
+}
+
+if (hostsWithSkillDir.length === 0) {
+  console.log('  No known host skill directories found. Nothing to install.');
+  process.exit(0);
+}
+
+console.log('  Installing into detected hosts:');
+for (const h of hostsWithSkillDir) {
+  console.log(`  [→] ${h.id} — ${h.path}`);
+}
+console.log('');
+
+for (const h of hostsWithSkillDir) {
+  try {
+    installInto(h.path);
+  } catch (e) {
+    console.error(`  ✗ Failed to install for ${h.id}: ${e.message}`);
+  }
+}
+
+console.log('\n  Done. Run "adaptive-director doctor" to verify.\n');

package/scripts/refresh.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function run(script, args = []) {
+  try {
+    const out = execFileSync(process.execPath, [script, ...args], {
+      encoding: 'utf8', timeout: 15000,
+      cwd: process.cwd(),
+    });
+    return JSON.parse(out.trim());
+  } catch (e) {
+    return null;
+  }
+}
+
+const configDir = join(homedir(), '.adaptive-director');
+const configPath = join(configDir, 'config.json');
+
+console.log('Refreshing Adaptive Director config...\n');
+
+const discovery = run(join(__dirname, 'discover.mjs'));
+if (!discovery) {
+  console.error('✗ Discovery failed.');
+  process.exit(1);
+}
+
+let existingConfig = {};
+if (existsSync(configPath)) {
+  try {
+    existingConfig = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    console.warn('! Existing config is invalid, creating a new one.');
+  }
+}
+
+const config = {
+  version: 1,
+  defaultBudget: existingConfig.defaultBudget || 'balanced',
+  allowMax: existingConfig.allowMax || false,
+  delegateEnabled: existingConfig.delegateEnabled || false,
+  hosts: {},
+  overrides: existingConfig.overrides || {}
+};
+
+for (const [id, info] of Object.entries(discovery.agents ?? {})) {
+  if (info.installed) {
+    config.hosts[id] = {
+      enabled: existingConfig.hosts?.[id]?.enabled ?? true,
+      skillPath: info.skillPath
+    };
+  }
+}
+
+writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+
+console.log(`✓ Config updated successfully.`);