adaptive-director-skill 1.1.1 → 1.1.2

package/README.md

@@ -2,237 +2,424 @@
 
 [![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)](#core-principles)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20pure%20built--ins-blue.svg)](#requirements)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-> **One task in. The right agents take it from there.**
+**One coding task. The right AI for every phase.**
 
-**Adaptive Director Skill** is a lightweight, skill-first orchestration layer for AI coding agents. Give it a single development task, and it dynamically directs each phase—**Planning, Implementation, Review, Fixing, and Verification**—to the best available agent, model, and reasoning effort.
+Adaptive Director is a local, skill-first workflow director for AI coding agents. Give it one task and it coordinates the rest: planning, implementation, independent review, targeted fixing, and verification.
 
-Instead of burning expensive reasoning tokens on simple edits or trusting a weak model with complex architecture and reviews, it directs work intelligently based on capability and budget.
+It is built for developers who already use tools like Codex, Claude Code, AGY, and delegate-skills, but do not want to manually decide which agent should plan, code, review, and verify every change.
 
-```text
-               User Task
-                   ↓
-         Adaptive Director
-                   ↓
-Plan  →  Implement  →  Review  →  Verify
- ↓           ↓            ↓
-Best        Best     Independent
-Agent       Coder     Reviewer
+```bash
+npx adaptive-director-skill setup
+adaptive-director run "Add refresh-token authentication"
 ```
 
----
+## Why This Exists
+
+One AI agent doing everything is convenient, but it creates predictable failure modes:
+
+| Problem | What happens |
+| --- | --- |
+| Weak planning | A cheap or fast model makes the wrong architectural call. |
+| Self-review | The same context that wrote the bug often misses it. |
+| Overpowered simple tasks | Expensive reasoning gets spent on small edits. |
+| Manual model juggling | You keep switching tools instead of shipping. |
+| No proof | A final answer says "done" without test/build evidence. |
 
-## Why Use It?
+Adaptive Director turns that into a disciplined local loop.
 
-Running an entire task with a single agent often leads to three common problems:
-- **Weak models on critical planning:** Lightweight models make architectural mistakes.
-- **Wasted reasoning tokens:** Using maximum reasoning for minor code changes burns quota needlessly.
-- **Review blind spots:** Agents struggle to catch their own errors during self-review.
+## Workflow
 
-### How It Solves This
+This chart is plain text so it stays readable on npm, GitHub, terminals, and package mirrors.
 
-```mermaid
-flowchart LR
-    Task([User Task]) --> Plan["1. Plan<br/>(High Reasoning)"]
-    Plan --> Impl["2. Implement<br/>(Fast Coder)"]
-    Impl --> Rev["3. Review<br/>(Independent Agent)"]
-    Rev --> Gate{"Critical<br/>Issues?"}
-    Gate -- Yes --> Fix["Targeted Fix<br/>(Max 1 Cycle)"]
-    Fix --> Rev
-    Gate -- No --> Ver["4. Verify<br/>(Automated Tests)"]
-    Ver --> Done([Verified])
+```text
+User task
+  |
+  v
+Classify size: small / medium / large
+  |
+  v
+Route each phase to the best available host + model + effort
+  |
+  v
++---------+      +------------+      +--------------------+      +----------+
+|  Plan   | ---> | Implement  | ---> | Independent Review | ---> |  Verify  |
++---------+      +------------+      +--------------------+      +----------+
+                                      |
+                                      | critical findings only
+                                      v
+                                +------------+
+                                |    Fix     |
+                                +------------+
+                                      |
+                                      v
+                                Re-review once
 ```
 
-| Phase | Adaptive Decision |
-|---|---|
-| **Plan** | Directed to a strong reasoning model |
-| **Implement** | Routed to an efficient coding specialist |
-| **Review** | Checked by an independent reviewer (never self-reviewed) |
-| **Fix** | Automated 1-cycle fix for critical findings |
-| **Verify** | Validated via project test suites (`flutter test`, `npm test`, `pytest`) |
+Terminal statuses are explicit:
+
+| Status | Meaning |
+| --- | --- |
+| `completed` | Workflow finished and verification passed, or no supported deterministic gates were detected. |
+| `blocked` | Critical review findings remain after the allowed fix cycle, or verification evidence failed. |
+| `needs_recovery` | Delegate execution mutated the workspace and failed, so automatic fallback was blocked. |
+| `failed` | A configuration or execution error prevented safe progress. |
 
----
+## Install And Setup
 
-## Quick Start
+Recommended one-command onboarding:
 
-Adaptive Director runs with **zero external npm dependencies** (pure Node.js built-ins).
+```bash
+npx adaptive-director-skill setup
+```
 
-### 1. Install Globally
+That command:
+
+1. Detects supported coding-agent hosts.
+2. Installs the Adaptive Director skill into host skill directories.
+3. Creates or updates `~/.adaptive-director/config.json`.
+4. Detects optional delegate-skills.
+5. Runs health checks.
+6. Prints the first command to try.
+
+Global install:
 
 ```bash
 npm install -g adaptive-director-skill
+adaptive-director setup
 ```
 
-### 2. Set Up
+Native-only non-interactive setup:
 
-> `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
+npx adaptive-director-skill setup --yes --no-delegate
+```
+
+Setup with delegate-skills integration:
 
 ```bash
-adaptive-director setup
+npx adaptive-director-skill setup --with-delegate
 ```
 
-Or without a global install:
+## Run A Task
 
 ```bash
-npx adaptive-director-skill setup
+adaptive-director run "Add input validation to the login flow"
 ```
 
-### 3. Verify
+What happens:
+
+1. A run workspace is created under `.adaptive-director/runs/<run-id>/`.
+2. The task is classified.
+3. Phase routing decisions are persisted.
+4. Each phase receives a focused handoff brief.
+5. Critical review findings trigger one targeted fix/re-review cycle.
+6. Verification evidence is collected from real project commands where detected.
+7. Final run status is persisted.
+
+Example output shape:
+
+```text
+Adaptive Director
+Run: run-a1b2c3d4
+
+Task size: medium
+Budget: balanced
+
+[1/4] Plan
+  Agent: agy
+  Model: claude-sonnet-4-6
+  Effort: high
+  completed
+
+[2/4] Implement
+  Agent: codex
+  Model: gpt-6-astra
+  Effort: medium
+  completed
+
+[3/4] Review
+  Agent: claude
+  Anti-affinity: Tier 4
+  0 critical
+  2 warnings
+
+[4/4] Verify
+  npm test passed
+
+Status: completed
+```
+
+## Command Reference
+
+### Core commands
+
+| Command | Purpose |
+| --- | --- |
+| `adaptive-director run "<task>"` | Run the complete workflow for one coding task. |
+| `adaptive-director setup` | Discover hosts, install the skill, configure optional delegate integration. |
+| `adaptive-director install` | Reinstall/update the skill into detected host skill directories. |
+| `adaptive-director refresh` | Re-discover hosts and update config while preserving overrides. |
+| `adaptive-director doctor` | Validate package, config, routing, hosts, and delegate integration. |
+| `adaptive-director delegate install` | Install delegate-skills through its official installer. |
+| `adaptive-director delegate status` | Show delegate detection, relays, and lanes. |
+| `adaptive-director help` | Show CLI help. |
+
+### `run` flags
+
+| Flag | Values | Default | Meaning |
+| --- | --- | --- | --- |
+| `--budget <mode>` | `conservative`, `balanced`, `quality` | `balanced` | Chooses effort levels per phase. |
+| `--delegate` | boolean | off | Allows delegate lanes when available. Native remains the fallback. |
+| `--allow-max` | boolean | off | Allows `max` effort if routing selects it. Without this, `max` is downgraded. |
+| `--dry-run` | boolean | off | Prints routing decisions without executing phases. |
+| `--cwd <path>` | path | current directory | Runs the task against a specific project directory. |
+
+Examples:
 
 ```bash
-adaptive-director doctor
+adaptive-director run "Fix password reset validation"
+adaptive-director run "Refactor payment architecture" --budget quality
+adaptive-director run "Add tests for billing retries" --delegate
+adaptive-director run "Plan the auth migration" --dry-run
+adaptive-director run "Fix API pagination" --cwd ../my-api
+adaptive-director run "High-risk security refactor" --budget quality --allow-max
 ```
 
-Expected output:
+### `setup` flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--with-delegate` | Install delegate-skills through the official installer if missing. |
+| `--no-delegate` | Skip optional delegate installation and keep native execution active. |
+| `--yes`, `-y` | Non-interactive setup. |
+| `--delegate-only` | Internal helper used by `adaptive-director delegate install`. |
+
+Examples:
+
+```bash
+adaptive-director setup
+adaptive-director setup --yes --no-delegate
+adaptive-director setup --with-delegate
+adaptive-director delegate status
 ```
-✓ 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.
+
+## Phase Policy
+
+Static phase maps stay simple:
+
+| Task size | Static phases |
+| --- | --- |
+| small | `implement -> review` |
+| medium | `plan -> implement -> review -> verify` |
+| large | `plan -> implement -> review -> verify` |
+
+`fix` is not part of the static map. It is inserted dynamically only when review finds critical issues.
+
+```text
+Review has 0 critical findings
+  -> Verify
+
+Review has critical findings
+  -> Fix
+  -> Re-review
+  -> Verify if clean
+  -> Blocked if critical findings remain
 ```
 
-### 4. Run with Your AI Agent
+Warnings and suggestions are reported but do not trigger a fix cycle.
+
+## Routing
 
-The Skill is now installed in your agent's skills directory. Prompt your agent:
+Routing chooses:
+
+- host/agent
+- model
+- reasoning effort
+- native or delegate execution
+- review anti-affinity
+- verification capability
+
+Routing priority:
 
 ```text
-Use $adaptive-director to implement Stripe checkout in Flutter
+User overrides
+  -> delegate fleet lanes, only when --delegate is passed
+  -> dynamic host/model discovery
+  -> capability registry
+  -> safe fallback
 ```
 
----
+Capability scores in `skills/adaptive-director/data/registry.json` are routing priors, not vendor benchmarks.
 
-## Example Walkthrough
+## Native And Delegate Execution
 
-**Task:** `"Implement Stripe in Flutter"`
+Adaptive Director is native-first. It must work without delegate-skills.
 
-1. **Plan:** Claude (High Effort) inspects the repo and builds the execution plan.
-2. **Implement:** Codex (Medium Effort) writes the code without committing.
-3. **Review:** An independent Claude session inspects the diff.
-   - *Finds 1 Critical issue:* PaymentIntent confirmed twice on retry.
-4. **Fix:** Codex receives a targeted brief to fix only that critical bug.
-5. **Re-Review:** Reviewer confirms the fix.
-6. **Verify:** Runs `flutter analyze && flutter test`.
-7. **Done:** Changes left uncommitted for final developer review.
+When `--delegate` is passed, delegate lanes may be used for matching phases. Delegate execution reuses the hardened `delegate-relay.mjs` boundary:
 
----
+- relay missing -> safe native fallback
+- non-zero relay exit -> inspect workspace mutation
+- missing/malformed result -> fail safely
+- timeout -> terminate and inspect workspace
+- mutated workspace after failure -> `needs_recovery`, no automatic retry
 
-## Repository Architecture
+Native execution is explicit. Adaptive Director does not pretend a host completed work when it cannot be invoked. If no automatic native executor is configured, a phase fails with `native_invocation_required`.
 
-The repository separates the **npm management/installer layer** from the **self-contained Agent Skill**:
+### Native executor contract
 
-- **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).
+Set `AD_NATIVE_EXECUTOR` to a command that reads JSON from stdin and returns JSON on stdout.
 
-```text
-Adaptive-Director-Skill/
-├── scripts/                      # Management & CLI layer
-│   ├── cli.mjs                   # Main CLI router
-│   ├── setup.mjs                 # Interactive host setup & delegate integration
-│   ├── delegate-cli.mjs          # Delegate skills integration CLI
-│   ├── install.mjs               # Idempotent skill copier
-│   ├── refresh.mjs               # Safe config refresher
-│   ├── discover.mjs              # Local agent & delegate 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
+Input shape:
+
+```json
+{
+  "phase": "implement",
+  "runId": "run-a1b2c3d4",
+  "task": "Add input validation",
+  "brief": "...",
+  "briefPath": ".adaptive-director/runs/run-a1b2c3d4/brief-implement.md",
+  "cwd": "/path/to/project",
+  "agent": "codex",
+  "model": "gpt-6-astra",
+  "effort": "medium",
+  "execution": "native",
+  "route": {}
+}
 ```
 
----
+Output shape:
 
-## CLI Commands
+```json
+{
+  "ok": true,
+  "status": "completed",
+  "summary": "Changed lib/auth.ts and added validation tests.",
+  "findings": [],
+  "artifacts": [],
+  "resultPath": ".adaptive-director/runs/run-a1b2c3d4/implement.json"
+}
+```
 
-```bash
-adaptive-director setup               # Interactive: discover hosts, install Skill, configure delegate
-adaptive-director setup --with-delegate # Setup and automatically install delegate-skills
-adaptive-director setup --no-delegate   # Setup skipping delegate-skills (native execution)
-adaptive-director delegate install    # Install delegate-skills via official installer
-adaptive-director delegate status     # Check delegate-skills discovery and relay status
-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
+## Verification Evidence
+
+Verification is not only an AI instruction. Adaptive Director detects common project types and runs conservative gates when available:
+
+| Project | Detection | Commands |
+| --- | --- | --- |
+| Node.js | `package.json` | `npm test`, `npm run build` when scripts exist |
+| Flutter | `pubspec.yaml` | `flutter analyze`, `flutter test` |
+| Laravel/PHP | `artisan` + `composer.json` | `php artisan test` |
+| Python | `pyproject.toml`, `pytest.ini`, `tox.ini`, or `setup.cfg` | `pytest` |
+
+Evidence is stored in run metadata and `verification-evidence.json`:
+
+```json
+{
+  "commands": [
+    {
+      "command": "npm test",
+      "exitCode": 0,
+      "durationMs": 1200
+    }
+  ],
+  "passed": true
+}
 ```
 
----
+## Supported Hosts
+
+Adaptive Director can discover these host CLIs when installed:
 
-## Core Principles
+| Host | Binary | Notes |
+| --- | --- | --- |
+| Claude Code | `claude` | Claude's coding CLI. |
+| Codex | `codex` | OpenAI Codex CLI. |
+| Antigravity / AGY | `agy` | Google Antigravity CLI. It may expose Gemini and other models through AGY. |
+| Gemini CLI | `gemini` | Separate Gemini CLI, detected only if installed independently. |
+| OpenCode | `opencode` | OpenCode CLI. |
+| Aider | `aider` | Aider CLI. |
+| Cursor Agent | `cursor-agent` | Cursor's headless agent CLI. |
+| Cline | `cline` | Cline CLI. |
+| GitHub Copilot CLI | `copilot` | GitHub Copilot CLI. |
 
-- **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.
-- **Zero Dependencies:** Runs on vanilla Node.js 18+.
+Delegate relays can add more implementers through `delegate-skills`.
 
----
+## Skill Prompt Usage
 
-## Dynamic Model Discovery & Heuristics
+The package also installs a normal agent skill. You can ask an agent directly:
 
-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.
+```text
+Use $adaptive-director to implement Stripe checkout in Flutter.
+```
 
-### Routing Pipeline
+Useful prompt flags:
 
 ```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)
+Use $adaptive-director --budget quality to refactor the auth system.
+Use $adaptive-director --delegate to implement the billing retry flow.
+Use $adaptive-director --dry-run to show routing for this task.
+Use $adaptive-director --allow-max for this high-risk migration.
 ```
 
-> [!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
 
----
+User config lives at:
 
-## Configuration (`~/.adaptive-director/config.json`)
+```text
+~/.adaptive-director/config.json
+```
+
+Example:
 
 ```json
 {
   "version": 1,
+  "execution": "native",
   "defaultBudget": "balanced",
+  "allowMax": false,
+  "delegateEnabled": false,
+  "hosts": {
+    "codex": {
+      "enabled": true,
+      "skillPath": "C:/Users/you/.codex/skills"
+    }
+  },
   "overrides": {
     "plan": "claude",
-    "implement": "codex"
+    "implement": "codex",
+    "review": "claude"
   }
 }
 ```
 
----
+## Requirements
+
+- Node.js 18+
+- Git for workspace mutation detection and touched-file reporting
+- At least one supported coding-agent CLI for real execution
+- Authenticated host CLIs for real model calls
+- No runtime npm dependencies in Adaptive Director itself
+
+## Validation Status
 
-## Upgrading
+Verified locally:
 
-After a package upgrade, re-install the Skill into your host environments:
+- `npm test`
+- setup and doctor flows
+- routing decisions and persistence
+- `implement.md` review handoff regression
+- mock end-to-end happy path
+- mock critical fix path
+- blocked path after one fix cycle
+- delegate mutation failure -> `needs_recovery`
+- `npm pack --dry-run`
+
+Real host validation depends on your local CLI authentication and quotas. Adaptive Director reports those failures plainly instead of claiming success.
+
+## Upgrade
 
 ```bash
 npm install -g adaptive-director-skill@latest
@@ -240,17 +427,13 @@ adaptive-director install
 adaptive-director doctor
 ```
 
----
-
-## Uninstalling
+## Uninstall
 
 ```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/`).
-
----
+`npm uninstall` removes the package, but it does not remove copied skill folders from host skill directories. Delete those manually if needed.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adaptive-director-skill",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Adaptive Director Skill — Skill-first adaptive multi-agent orchestration for AI coding agents",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
     "skills/"
   ],
   "scripts": {
-    "test": "node scripts/smoke-test.mjs && node scripts/test-setup-delegate.mjs",
+    "test": "node scripts/smoke-test.mjs && node scripts/test-setup-delegate.mjs && node scripts/test-run-flow.mjs",
     "setup": "node scripts/setup.mjs",
     "discover": "node scripts/discover.mjs",
     "doctor": "node scripts/doctor.mjs"

package/scripts/cli.mjs

@@ -11,6 +11,7 @@ const args = process.argv.slice(2);
 const command = args[0] || 'help';
 
 const commands = {
+  run: 'run.mjs',
   setup: 'setup.mjs',
   install: 'install.mjs',
   refresh: 'refresh.mjs',
@@ -19,12 +20,13 @@ const commands = {
 };
 
 if (command === 'help' || command === '--help' || command === '-h') {
-  console.log(`Adaptive Director Skill CLI v1.1.1
+  console.log(`Adaptive Director Skill CLI v1.1.2
 
 Usage:
   adaptive-director <command> [options]
 
 Commands:
+  run       - Run a complete Adaptive Director workflow for one coding task
   setup     - Initial interactive setup and host/delegate configuration
               Flags: --with-delegate, --no-delegate, --yes
   install   - Install/copy the Skill into supported host skill directories