adaptive-director-skill 0.1.1 → 1.1.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
-node scripts/setup.mjs
-node scripts/smoke-test.mjs
+npx adaptive-director-skill setup
+```
+
+### 3. Verify
+
+```bash
+adaptive-director doctor
+```
+
+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.
 ```
 
-### 2. Run with Your AI Agent
+### 4. Run with Your AI Agent
 
-Load `SKILL.md` into your coding agent (Claude Code, Antigravity, Codex, etc.) and prompt:
+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,34 +131,53 @@ 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
 
+- **Dynamic Discovery:** Discovers installed host CLIs and inspects locally available models at runtime rather than assuming static pairings.
+- **Routing Priority:** User overrides → Delegate fleet lanes → Dynamic Host Discovery → Capability registry → Default fallback.
 - **Independent Review:** The coder never reviews its own work.
+- **Verification Dimension:** Independent verification requires dedicated verification capabilities (`min_verification: 3`).
 - **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.
 - **Context Isolation:** Each agent receives only a self-contained brief on disk (`.adaptive-director/runs/`), preventing context window bloat.
@@ -138,19 +185,68 @@ adaptive-director/
 
 ---
 
-## Configuration (`~/.adaptive-director/config.yaml`)
+## Dynamic Model Discovery & Heuristics
+
+Adaptive Director does **not** rely on rigid, hardcoded host-to-model pairings. Real-world model availability depends on local CLI versions, host configurations, and account subscriptions.
+
+### Routing Pipeline
+
+```text
+Detect Host CLI
+       ↓
+Discover Locally Available Models (cache / config / env)
+       ↓
+Resolve Aliases (e.g. 'astra' → 'gpt-6-astra')
+       ↓
+Intersect with Registry Capabilities & Phase Requirements
+       ↓
+Score Compatible Candidates for Current Phase
+       ↓
+Route to Optimal Candidate (with Graceful Fallback)
+```
+
+> [!NOTE]
+> **Heuristic Calibration Disclaimer:** Capability scores (1–5) in `data/registry.json` represent internal routing heuristics and priors calibrated for phase allocation. They are **not** vendor laboratory benchmarks or absolute leaderboards.
+
+---
+
+## Configuration (`~/.adaptive-director/config.json`)
+
+```json
+{
+  "version": 1,
+  "defaultBudget": "balanced",
+  "overrides": {
+    "plan": "claude",
+    "implement": "codex"
+  }
+}
+```
+
+---
+
+## Upgrading
 
-```yaml
-defaultBudget: balanced # conservative | balanced | quality
+After a package upgrade, re-install the Skill into your host environments:
 
-# Optional overrides:
-agentOverrides.plan: claude
-agentOverrides.implement: codex
-agentOverrides.review: claude
+```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.1.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.1.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

@@ -16,19 +16,20 @@ import { execFileSync, execSync } from 'node:child_process'
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
+import { discoverHostModels } from '../skills/adaptive-director/scripts/discover-models.mjs'
 
 // ─── 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 ──────────────────────────────────────────────────────────────────
@@ -88,19 +89,83 @@ function readFleet(path) {
   }
 }
 
+function readJsonConfig(path) {
+  if (!existsSync(path)) return null
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'))
+    if (raw.lanes && typeof raw.lanes === 'object') {
+      const result = {}
+      for (const [lane, def] of Object.entries(raw.lanes)) {
+        result[lane] = {
+          agent: def.implementer ?? def.agent,
+          model: def.model ?? null,
+          effort: def.effort ?? def.variant ?? null,
+          implementer: def.implementer ?? def.agent,
+        }
+      }
+      return Object.keys(result).length > 0 ? result : null
+    }
+  } catch {}
+  return null
+}
+
 function discoverDelegate() {
-  const globalPath  = join(homedir(), '.delegate', 'fleet.yaml')
-  const projectPath = join(process.cwd(), '.delegate', 'fleet.yaml')
+  const paths = [
+    join(process.cwd(), '.delegate', 'fleet.yaml'),
+    join(homedir(), '.delegate', 'fleet.yaml'),
+    join(process.cwd(), '.delegate', 'config.json'),
+    join(homedir(), '.config', 'delegate-skills', 'config.json'),
+  ]
+
+  let lanes = {}
+  for (const p of paths) {
+    if (p.endsWith('.json')) {
+      const jsonLanes = readJsonConfig(p)
+      if (jsonLanes) lanes = { ...lanes, ...jsonLanes }
+    } else {
+      const fleetLanes = readFleet(p)
+      if (fleetLanes) lanes = { ...lanes, ...fleetLanes }
+    }
+  }
 
-  const globalLanes  = readFleet(globalPath)
-  const projectLanes = readFleet(projectPath)
+  // Check if delegate-skills is installed on disk
+  const agentsSkillsDir = join(homedir(), '.agents', 'skills')
+  const codexSkillsDir  = join(homedir(), '.codex', 'skills')
+  const hasAgentsSkills = existsSync(join(agentsSkillsDir, 'delegate-setup')) ||
+                          existsSync(join(agentsSkillsDir, 'codex-delegate')) ||
+                          existsSync(join(agentsSkillsDir, 'agy-delegate')) ||
+                          existsSync(join(codexSkillsDir, 'delegate-review-loop'))
+
+  let hasSkillLock = false
+  const skillLockPath = join(homedir(), '.agents', '.skill-lock.json')
+  if (existsSync(skillLockPath)) {
+    try {
+      const lockContent = readFileSync(skillLockPath, 'utf8')
+      if (lockContent.includes('delegate-skills')) hasSkillLock = true
+    } catch {}
+  }
+
+  const installed = Object.keys(lanes).length > 0 || hasAgentsSkills || hasSkillLock
 
-  if (!globalLanes && !projectLanes) {
-    return { installed: false, lanes: {} }
+  // If installed but no explicit fleet lanes file configured, synthesize lanes from installed delegate skills
+  if (installed && Object.keys(lanes).length === 0 && hasAgentsSkills) {
+    if (existsSync(join(agentsSkillsDir, 'codex-delegate'))) {
+      lanes.feature = { agent: 'codex', implementer: 'codex' }
+      lanes.implement = { agent: 'codex', implementer: 'codex' }
+      lanes.fix = { agent: 'codex', implementer: 'codex' }
+    }
+    if (existsSync(join(agentsSkillsDir, 'agy-delegate'))) {
+      lanes.plan = { agent: 'agy', implementer: 'agy' }
+      lanes.review = { agent: 'agy', implementer: 'agy' }
+      lanes.verify = { agent: 'agy', implementer: 'agy' }
+    }
   }
 
-  const merged = { ...(globalLanes ?? {}), ...(projectLanes ?? {}) }
-  return { installed: true, lanes: merged }
+  return {
+    installed,
+    lanes,
+    source: hasSkillLock ? 'amElnagdy/delegate-skills' : (hasAgentsSkills ? 'local-skills' : (Object.keys(lanes).length > 0 ? 'fleet-config' : null))
+  }
 }
 
 // ─── Main ─────────────────────────────────────────────────────────────────────
@@ -116,10 +181,24 @@ 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',
+      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,
+      availableModels: discoverHostModels(desc.id),
     }
   }
 

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;
+}