adaptive-director-skill 0.1.0

package/references/capability-registry.md

@@ -0,0 +1,92 @@
+# Capability Registry Reference
+
+## Overview
+
+The capability registry assigns numeric scores to known models and defines minimum requirements per phase.
+
+All scores are 1–5:
+
+| Score | Meaning |
+|-------|---------|
+| 1 | Weak — unreliable for this capability |
+| 2 | Limited — acceptable only for simple tasks |
+| 3 | Acceptable — meets baseline requirements |
+| 4 | Strong — reliable for most tasks |
+| 5 | Excellent — best available |
+
+---
+
+## Registry File
+
+Location: `data/registry.json`
+
+```json
+{
+  "models": {
+    "claude-sonnet-4-5": { "planning": 4, "coding": 4, "review": 4 },
+    "codex-default":     { "planning": 2, "coding": 5, "review": 2 },
+    "unknown":           { "planning": 1, "coding": 1, "review": 1 }
+  },
+  "phase_requirements": {
+    "plan":      { "min_planning": 3 },
+    "implement": { "min_coding": 2 },
+    "review":    { "min_review": 3 },
+    "fix":       { "min_coding": 2 },
+    "verify":    { "min_planning": 2 }
+  }
+}
+```
+
+---
+
+## Phase Requirements
+
+| Phase | Minimum Requirement |
+|-------|-------------------|
+| plan | planning ≥ 3 |
+| implement | coding ≥ 2 |
+| review | review ≥ 3 |
+| fix | coding ≥ 2 |
+| verify | planning ≥ 2 |
+
+---
+
+## Priority Chain
+
+The routing script applies this order:
+
+```
+1. User explicit override  (config.yaml agentOverrides.*)
+2. Delegate lane preference (fleet.yaml, only when --delegate)
+3. Built-in registry        (best available agent by score)
+4. Fallback                 (claude)
+```
+
+---
+
+## User Override (config.yaml)
+
+```yaml
+agentOverrides.plan:      claude
+agentOverrides.implement: codex
+agentOverrides.review:    claude
+agentOverrides.verify:    claude
+```
+
+Uncomment lines in `~/.adaptive-orchestrator/config.yaml` to activate.
+
+---
+
+## Adding a New Model
+
+Edit `data/registry.json` and add an entry under `models`:
+
+```json
+"my-custom-model": {
+  "planning": 3,
+  "coding":   4,
+  "review":   3
+}
+```
+
+Then set `ADAPTIVE_CURRENT_MODEL=my-custom-model` in your environment.

package/references/delegate-integration.md

@@ -0,0 +1,115 @@
+# Delegate Integration Reference
+
+## Overview
+
+Delegate execution is **optional** and **disabled by default**.
+
+```
+Default:                   native execution
+--delegate flag:           delegate execution allowed (not forced)
+```
+
+Adaptive Orchestrator always remains the top-level controller.
+`delegate-skills` is the execution channel — never the orchestrator.
+
+---
+
+## How It Works
+
+When `--delegate` is passed:
+
+1. Adaptive Orchestrator reads the `delegate-skills` fleet config
+2. For each phase, it checks if a matching lane exists
+3. If yes → dispatches the phase brief to that lane's implementer
+4. If no  → falls back to native execution
+
+```
+Plan     → native claude (no planning lane)
+Implement → delegate → codex (feature lane matches)
+Review   → native claude (no review lane)
+Verify   → native claude (no verify lane)
+```
+
+---
+
+## delegate-skills Fleet Config
+
+Location: `~/.delegate/fleet.yaml` or `./.delegate/fleet.yaml`
+
+Example:
+```yaml
+lanes:
+  feature:
+    implementer: codex
+    model: o4-mini
+    effort: medium
+  tests:
+    implementer: aider
+  ui:
+    implementer: cursor
+```
+
+Adaptive Orchestrator reads these lanes during routing and maps them to phases by keyword:
+
+| Phase | Matching Lane Keywords |
+|-------|----------------------|
+| implement | feature, impl, code, build |
+| fix | fix, repair, feature |
+| plan | plan, planning |
+| review | review, check |
+| verify | test, verify, qa |
+
+---
+
+## Installing delegate-skills
+
+```bash
+npx skills add amElnagdy/delegate-skills
+```
+
+Or specific skills:
+```bash
+npx skills add amElnagdy/delegate-skills --skill codex-delegate
+npx skills add amElnagdy/delegate-skills --skill claude-delegate
+```
+
+---
+
+## Relay Location
+
+The routing engine looks for relay scripts at:
+
+```
+./.skills/amElnagdy/delegate-skills/skills/<agent>-delegate/scripts/relay.mjs
+~/.skills/amElnagdy/delegate-skills/skills/<agent>-delegate/scripts/relay.mjs
+```
+
+---
+
+## Delegate Rule (MVP)
+
+> One delegated executor per phase maximum.
+
+The delegate should receive a focused brief and return a structured result.
+It must NOT start its own orchestration loop.
+
+```
+Orchestrator → brief → Delegate → result.json → Orchestrator
+```
+
+The delegate NEVER commits. Committing belongs to the reviewer (you).
+
+---
+
+## Runtime Flags
+
+```bash
+# Enable delegate
+adaptive-orchestrator --delegate "Implement Stripe in Flutter"
+
+# Delegate + max reasoning
+adaptive-orchestrator --delegate --allow-max "Refactor payment architecture"
+
+# Dry run (shows routing, no execution)
+adaptive-orchestrator --dry-run --delegate "Implement Stripe in Flutter"
+```

package/references/handoff-schema.md

@@ -0,0 +1,137 @@
+# Handoff Schema Reference
+
+## Overview
+
+Every run gets an isolated workspace. Agents communicate through files — not shared chat history.
+
+```
+.adaptive-orchestrator/runs/<run-id>/
+├── metadata.json       ← machine-readable run state
+├── task.md             ← original task (human + machine)
+├── plan.md             ← planner output (human readable)
+├── plan.json           ← planner output (machine contract)
+├── implementation.md   ← implementer report (human readable)
+├── implementation.json ← implementer report (machine contract)
+├── review.md           ← reviewer findings (human readable)
+├── review.json         ← reviewer findings (machine contract)
+└── final.md / final.json ← verification result
+```
+
+---
+
+## metadata.json
+
+```json
+{
+  "runId":        "run-abc123",
+  "task":         "Implement Stripe in Flutter",
+  "status":       "running",
+  "currentPhase": "review",
+  "size":         "medium",
+  "budget":       "balanced",
+  "allowMax":     false,
+  "useDelegate":  false,
+  "routing":      [],
+  "startedAt":    "2026-09-17T01:00:00Z",
+  "updatedAt":    "2026-09-17T01:15:00Z"
+}
+```
+
+### RunStatus values
+
+| Status | Meaning |
+|--------|---------|
+| pending | initialized, not started |
+| running | currently executing |
+| verified | completed successfully |
+| blocked | review or verify failed after max cycles |
+| failed | agent returned an error |
+| interrupted | stopped mid-run (can resume) |
+
+---
+
+## Phase JSON Contract
+
+All phase results follow this schema:
+
+```json
+{
+  "phase":   "review",
+  "status":  "completed",
+  "summary": "Found 1 critical issue...",
+  "findings": [
+    {
+      "severity":    "critical",
+      "title":       "Duplicate PaymentIntent confirmation",
+      "file":        "lib/payment_service.dart",
+      "description": "PaymentIntent.confirm() is called twice on retry."
+    }
+  ],
+  "touchedFiles": ["lib/payment_service.dart"],
+  "sessionId":    "sess-xyz"
+}
+```
+
+### severity values
+
+| Value | Behavior |
+|-------|---------|
+| critical | Must fix — triggers fix loop |
+| warning | Report and continue |
+| suggestion | Informational only |
+
+---
+
+## Managing State with run-state.mjs
+
+### Init a run
+```bash
+node scripts/run-state.mjs init \
+  --task "Implement Stripe in Flutter" \
+  --size medium \
+  --budget balanced
+```
+
+### Update status
+```bash
+node scripts/run-state.mjs update --run-id run-abc123 --status running --phase plan
+```
+
+### Write a phase result
+```bash
+node scripts/run-state.mjs write-phase \
+  --run-id run-abc123 \
+  --phase review \
+  --status completed \
+  --summary "Found 1 critical issue" \
+  --findings-json '[{"severity":"critical","title":"...","description":"..."}]'
+```
+
+### Read a phase result
+```bash
+node scripts/run-state.mjs read-phase --run-id run-abc123 --phase review
+```
+
+### Build a brief for a phase
+```bash
+node scripts/run-state.mjs build-brief --run-id run-abc123 --phase implement
+```
+
+### List all runs
+```bash
+node scripts/run-state.mjs list
+```
+
+---
+
+## Brief Format (what each agent receives)
+
+Each agent receives ONLY what it needs — not the full chat history.
+
+| Phase | Receives |
+|-------|---------|
+| plan | task.md + instructions |
+| implement | task.md + plan.md + instructions |
+| review | task.md + plan.md + implementation.md + instructions |
+| fix | task.md + review.md + instructions |
+| verify | task.md + plan.md + instructions |

package/references/routing-rules.md

@@ -0,0 +1,99 @@
+# Routing Rules Reference
+
+## Task Classification
+
+Initial classification uses keyword heuristics:
+
+| Size | Examples |
+|------|---------|
+| small | rename, fix typo, update text, minor fix, change color |
+| medium | Stripe integration, password reset, new API, module refactor |
+| large | architecture refactor, auth system, payment architecture, migration |
+
+Default when no keyword matches: **medium**
+
+### Reclassification
+
+After the Planner inspects the repository, it appends a JSON block to its plan:
+
+```json
+{"recommended_size": "large", "reason": "discovered webhooks + saved cards + refunds"}
+```
+
+If `recommended_size` differs from initial, Adaptive Orchestrator reclassifies and rebuilds the routing table.
+
+---
+
+## Phase Map
+
+| Task Size | Phases |
+|-----------|--------|
+| small | implement → review |
+| medium | plan → implement → review → verify |
+| large | plan → implement → review → [fix] → verify |
+
+`fix` only runs if review finds CRITICAL issues.
+
+---
+
+## Effort Table
+
+| Phase | conservative | balanced | quality |
+|-------|-------------|---------|---------|
+| plan | medium | high | high |
+| implement | medium | medium | medium |
+| review | high | high | high |
+| fix | medium | medium | medium |
+| verify | medium | medium | high |
+
+`max` is never used unless `--allow-max` is passed AND the routing engine selects it.
+
+---
+
+## Agent Priority
+
+### For planning/review/verify phases:
+```
+claude → agy → gemini → opencode → cursor → cline → copilot → aider → codex
+```
+
+### For implementation/fix phases:
+```
+codex → aider → opencode → cursor → cline → claude → agy → copilot → gemini
+```
+
+The first agent in the list whose representative model meets the phase requirement is selected.
+
+---
+
+## Execution Mode
+
+| Condition | Execution |
+|-----------|-----------|
+| Default | native |
+| `--delegate` + matching fleet lane | delegate |
+| `--delegate` + no matching lane | native (fallback) |
+
+---
+
+## Using route.mjs
+
+```bash
+echo '{
+  "taskSize": "medium",
+  "phase": "review",
+  "budget": "balanced",
+  "allowMax": false,
+  "delegateEnabled": false
+}' | node scripts/route.mjs
+```
+
+Returns:
+```json
+{
+  "agent": "claude",
+  "model": "claude-sonnet-4-5",
+  "effort": "high",
+  "execution": "native"
+}
+```

package/scripts/discover.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * discover.mjs
+ * ─────────────
+ * Detects installed coding-agent CLIs and delegate-skills fleet.
+ * Never guesses. If a capability cannot be verified, it is marked unknown/false.
+ *
+ * Output: JSON on stdout.
+ *
+ * Usage:
+ *   node scripts/discover.mjs
+ *   node scripts/discover.mjs --json   (same, explicit)
+ */
+
+import { execFileSync, execSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+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'] },
+]
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function isOnPath(bin) {
+  try {
+    execSync(
+      process.platform === 'win32' ? `where ${bin}` : `which ${bin}`,
+      { stdio: 'ignore', timeout: 3000 }
+    )
+    return true
+  } catch {
+    return false
+  }
+}
+
+function findBinary(bins) {
+  for (const bin of bins) {
+    if (isOnPath(bin)) return bin
+  }
+  return null
+}
+
+function getVersion(bin, args) {
+  try {
+    const out = execFileSync(bin, args, {
+      encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore']
+    })
+    return out.trim().split('\n')[0].trim()
+  } catch {
+    return null
+  }
+}
+
+// ─── Delegate-skills fleet ────────────────────────────────────────────────────
+
+function readFleet(path) {
+  if (!existsSync(path)) return null
+  try {
+    const raw = readFileSync(path, 'utf8')
+    // Simple YAML lane parser (avoids dependency on js-yaml in scripts)
+    const lanes = {}
+    let currentLane = null
+    for (const line of raw.split('\n')) {
+      const laneMatch = line.match(/^  (\w[\w-]*):\s*$/)
+      const implementerMatch = line.match(/^\s+implementer:\s*(.+)$/)
+      const modelMatch = line.match(/^\s+model:\s*(.+)$/)
+      const effortMatch = line.match(/^\s+effort:\s*(.+)$/)
+      if (laneMatch) { currentLane = laneMatch[1]; lanes[currentLane] = {} }
+      else if (currentLane && implementerMatch) lanes[currentLane].implementer = implementerMatch[1].trim()
+      else if (currentLane && modelMatch)       lanes[currentLane].model       = modelMatch[1].trim()
+      else if (currentLane && effortMatch)      lanes[currentLane].effort      = effortMatch[1].trim()
+    }
+    return Object.keys(lanes).length > 0 ? lanes : null
+  } catch {
+    return null
+  }
+}
+
+function discoverDelegate() {
+  const globalPath  = join(homedir(), '.delegate', 'fleet.yaml')
+  const projectPath = join(process.cwd(), '.delegate', 'fleet.yaml')
+
+  const globalLanes  = readFleet(globalPath)
+  const projectLanes = readFleet(projectPath)
+
+  if (!globalLanes && !projectLanes) {
+    return { installed: false, lanes: {} }
+  }
+
+  const merged = { ...(globalLanes ?? {}), ...(projectLanes ?? {}) }
+  return { installed: true, lanes: merged }
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+function discover() {
+  const agents = {}
+
+  for (const desc of KNOWN_AGENTS) {
+    const bin = findBinary(desc.bins)
+    if (!bin) {
+      agents[desc.id] = { installed: false, available: false }
+      continue
+    }
+
+    const version = getVersion(bin, desc.versionArgs)
+    agents[desc.id] = {
+      installed:  true,
+      available:  version !== null,
+      version:    version ?? 'unknown',
+    }
+  }
+
+  const delegateSkills = discoverDelegate()
+
+  const result = { agents, delegateSkills }
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n')
+}
+
+discover()

package/scripts/resume.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * resume.mjs
+ * ───────────
+ * Finds interrupted or running runs and returns state for resumption.
+ *
+ * Usage:
+ *   node scripts/resume.mjs                    → most recent interrupted run
+ *   node scripts/resume.mjs --run-id run-abc   → specific run
+ *   node scripts/resume.mjs --list             → all runs with status
+ *
+ * Output: JSON metadata of the run, or null if nothing to resume.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+const RUNS_ROOT = existsSync(join(process.cwd(), '.adaptive-orchestrator', 'runs'))
+  ? join(process.cwd(), '.adaptive-orchestrator', 'runs')
+  : join(process.cwd(), '.adaptive-director', 'runs')
+const RESUMABLE = new Set(['interrupted', 'running', 'pending'])
+
+function metaPath(runId) {
+  return join(RUNS_ROOT, runId, 'metadata.json')
+}
+
+function allRuns() {
+  if (!existsSync(RUNS_ROOT)) return []
+  return readdirSync(RUNS_ROOT, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => {
+      try { return JSON.parse(readFileSync(metaPath(d.name), 'utf8')) }
+      catch { return null }
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+}
+
+// ─── Arg parser ───────────────────────────────────────────────────────────────
+
+const args = {}
+const argv = process.argv.slice(2)
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i].startsWith('--')) {
+    args[argv[i]] = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true
+  }
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+function out(data) { process.stdout.write(JSON.stringify(data, null, 2) + '\n') }
+
+if (args['--list']) {
+  out(allRuns())
+  process.exit(0)
+}
+
+if (args['--run-id']) {
+  const path = metaPath(args['--run-id'])
+  if (!existsSync(path)) {
+    process.stderr.write(`Run not found: ${args['--run-id']}\n`)
+    process.exit(1)
+  }
+  out(JSON.parse(readFileSync(path, 'utf8')))
+  process.exit(0)
+}
+
+// Find most recent resumable run
+const resumable = allRuns().find(r => RESUMABLE.has(r.status))
+out(resumable ?? null)