adaptive-director-skill 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Tamer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# 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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> **One task in. The right agents take it from there.**
+
+**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.
+
+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.
+
+```text
+               User Task
+                   ↓
+         Adaptive Director
+                   ↓
+Plan  →  Implement  →  Review  →  Verify
+ ↓           ↓            ↓
+Best        Best     Independent
+Agent       Coder     Reviewer
+```
+
+---
+
+## Why Use It?
+
+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.
+
+### How It Solves This
+
+```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])
+```
+
+| 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`) |
+
+---
+
+## Quick Start
+
+Adaptive Director runs with **zero external npm dependencies** (pure Node.js built-ins).
+
+### 1. Clone & Setup
+
+```bash
+git clone https://github.com/tamourax/Adaptive-Orchestrator.git
+cd Adaptive-Orchestrator
+
+# Probe local agents (Claude, Codex, Antigravity, Cursor, etc.)
+node scripts/setup.mjs
+
+# Verify installation with smoke test
+node scripts/smoke-test.mjs
+```
+
+### 2. Run with Your AI Agent
+
+Load `SKILL.md` into your coding agent (Claude Code, Antigravity, Codex, etc.) and prompt:
+
+```text
+Use $adaptive-director-skill to implement Stripe checkout in Flutter
+```
+
+---
+
+## Example Walkthrough
+
+**Task:** `"Implement Stripe in Flutter"`
+
+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.
+
+---
+
+## Architecture
+
+> *"Reasoning stays with agents. Deterministic operations stay in scripts."*
+
+```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
+```
+
+### 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
+
+---
+
+## Core Principles
+
+- **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.
+- **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+.
+
+---
+
+## Configuration (`~/.adaptive-director/config.yaml`)
+
+```yaml
+defaultBudget: balanced # conservative | balanced | quality
+
+# Optional overrides:
+agentOverrides.plan: claude
+agentOverrides.implement: codex
+agentOverrides.review: claude
+```
+
+---
+
+## License
+
+MIT License © 2026 [Ahmed Tamer](https://github.com/tamourax). See [LICENSE](LICENSE) for details.

package/SKILL.md

@@ -0,0 +1,395 @@
+---
+name: adaptive-director-skill
+description: >
+  Adaptive multi-agent director for coding tasks.
+  Routes every phase (plan, implement, review, fix, verify) to the right
+  agent, model, and reasoning effort automatically.
+version: 0.1.0
+---
+
+# Adaptive Director Skill
+
+> **One task in. The right agents take it from there.**
+
+---
+
+## What This Skill Does
+
+When you invoke this skill with a coding task, you:
+
+1. Classify the task
+2. Determine which phases to run
+3. Route each phase to the right agent, model, and effort level
+4. Execute phases using handoff files (not shared chat history)
+5. Handle review findings (fix critical issues once, then re-review)
+6. Verify the result
+7. Produce a final status report
+
+You do NOT implement, review, or verify yourself unless you are the best available agent for those phases and the routing engine assigns you.
+
+---
+
+## Core Rules
+
+These rules are absolute:
+
+```
+1. Max reasoning is DISABLED by default.
+   → Only use if --allow-max was passed.
+
+2. Delegate execution is DISABLED by default.
+   → Only use if --delegate was passed.
+
+3. Native agents/sub-agents are preferred.
+
+4. Review MUST be independent.
+   → The reviewer must not be the same execution context that implemented.
+
+5. Critical findings MUST be fixed before verification.
+
+6. Warning findings are reported but do not block.
+
+7. Suggestion findings are informational only.
+
+8. Maximum 1 automatic fix/re-review cycle.
+   → If critical issues remain after re-review → Status: Blocked.
+
+9. Never commit. Committing belongs to the user.
+
+10. Never guess unavailable agent capabilities.
+    → If unknown, mark as unknown.
+```
+
+---
+
+## How to Start a Run
+
+### Step 1: Read user input
+
+Extract:
+- Task description
+- Flags: `--budget`, `--delegate`, `--allow-max`, `--dry-run`
+- Default budget: `balanced`
+
+### Step 2: Classify the task
+
+Run initial heuristic classification:
+
+```bash
+# Small: rename, fix typo, update text, minor fix, change color/label
+# Medium: integration, API feature, module refactor, password reset
+# Large: architecture refactor, auth redesign, migration, payment system
+```
+
+Use the heuristic. Do NOT call an agent for classification yet.
+The Planner will reclassify after repo inspection if needed.
+
+### Step 3: Get routing for each phase
+
+For EACH phase in the task's phase list, call `route.mjs`:
+
+```bash
+echo '{
+  "taskSize": "medium",
+  "phase": "plan",
+  "budget": "balanced",
+  "allowMax": false,
+  "delegateEnabled": false
+}' | node scripts/route.mjs
+```
+
+`route.mjs` returns:
+```json
+{
+  "agent": "claude",
+  "model": "claude-sonnet-4-5",
+  "effort": "high",
+  "execution": "native"
+}
+```
+
+Repeat for all phases. Build a routing table.
+
+### Step 4: Dry run check
+
+If `--dry-run` was passed:
+- Print the routing table
+- Exit. No execution.
+
+### Step 5: Init run workspace
+
+```bash
+node scripts/run-state.mjs init \
+  --task "Implement Stripe in Flutter" \
+  --size medium \
+  --budget balanced
+```
+
+Returns `{ "runId": "run-abc123", "workspacePath": "..." }`.
+Save the `runId`. You will use it for all subsequent operations.
+
+### Step 6: Execute phases
+
+See the **Phase Execution** section below.
+
+---
+
+## Phase Map
+
+| Task Size | Phases |
+|-----------|--------|
+| small | implement → review |
+| medium | plan → implement → review → verify |
+| large | plan → implement → review → [fix if critical] → verify |
+
+---
+
+## Phase Execution
+
+Execute phases in order. For each phase:
+
+### 1. Update metadata
+```bash
+node scripts/run-state.mjs update \
+  --run-id run-abc123 \
+  --status running \
+  --phase plan
+```
+
+### 2. Build the brief
+```bash
+node scripts/run-state.mjs build-brief \
+  --run-id run-abc123 \
+  --phase plan
+```
+
+The brief is a self-contained prompt. Pass it to the assigned agent.
+**Do not share full chat history with the agent — use the brief only.**
+
+### 3. Execute the phase
+
+Use the routing decision from Step 3 above:
+
+- `execution: native` → use a native sub-agent or spawn the agent CLI
+- `execution: delegate` → use `delegate-skills` relay for the assigned agent
+
+Pass the brief as the task for the agent.
+
+### 4. Write the phase result
+
+After the agent completes, write its output:
+
+```bash
+node scripts/run-state.mjs write-phase \
+  --run-id run-abc123 \
+  --phase plan \
+  --status completed \
+  --summary "<agent output>"
+```
+
+If the phase is `review` or `fix`, also parse findings and include:
+```bash
+  --findings-json '[{"severity":"critical","title":"...","description":"...","file":"..."}]'
+```
+
+---
+
+## Special Phase: Plan + Reclassification
+
+After the **plan** phase completes:
+
+1. Look for a JSON block at the end of the planner's output:
+   ```json
+   {"recommended_size": "large", "reason": "..."}
+   ```
+
+2. If `recommended_size` differs from the initial classification:
+   - Log: `Reclassified: medium → large (reason)`
+   - Rebuild the routing table for the new size
+   - Update metadata
+
+3. Continue with the updated phase list and routing.
+
+---
+
+## Special Phase: Review
+
+After the **review** phase:
+
+1. Parse findings from the review output.
+   Look for lines like:
+   ```
+   [CRITICAL] <title>
+   [WARNING]  <title>
+   [SUGGESTION] <title>
+   ```
+
+2. Write phase result with findings JSON.
+
+3. Check for CRITICAL findings:
+
+```
+Critical found?
+├── No  → continue to Verify
+└── Yes → enter Fix Loop
+```
+
+---
+
+## Fix Loop
+
+Maximum: **1 automatic cycle**.
+
+### Fix phase
+
+```bash
+node scripts/run-state.mjs build-brief --run-id run-abc123 --phase fix
+```
+
+Execute with the assigned fix agent. The brief includes the previous review.
+
+### Re-review
+
+Build and execute a new review brief. Parse findings again.
+
+```
+Re-review: Critical still found?
+├── No  → continue to Verify
+└── Yes → Status: Blocked
+          Report remaining issues to user.
+          STOP.
+```
+
+---
+
+## Special Phase: Verify
+
+Run project-appropriate verification commands:
+
+| Project Type | Detected by | Commands |
+|-------------|------------|---------|
+| Flutter | `pubspec.yaml` | `flutter analyze`, `flutter test` |
+| Node.js | `package.json` | `npm test`, `npm run build` |
+| Laravel | `composer.json` | `php artisan test` |
+| Python | `pyproject.toml` or `requirements.txt` | `pytest` |
+| Unknown | (none) | skip |
+
+If commands pass → `Status: Verified`
+If commands fail → `Status: Blocked`
+
+Write final result:
+```bash
+node scripts/run-state.mjs write-phase \
+  --run-id run-abc123 \
+  --phase verify \
+  --status completed \
+  --summary "flutter analyze: passed. flutter test: 42 tests passed."
+```
+
+---
+
+## Final Report
+
+Print a clean summary:
+
+```
+  Adaptive Orchestrator
+
+  Task:    Implement Stripe in Flutter
+  Run ID:  run-abc123
+  Size:    medium
+  Budget:  balanced
+
+  Execution:
+  ✓ Plan completed
+  ✓ Implementation completed
+  ⚠ Review found 1 CRITICAL issue
+  ✓ Fix completed
+  ✓ Re-review passed
+  ✓ Verification passed
+
+  Status: Verified
+```
+
+Or if blocked:
+```
+  Status: Blocked
+
+  Remaining critical issue:
+  [CRITICAL] PaymentIntent confirmed twice
+  File: lib/payment_service.dart
+  PaymentIntent.confirm() is called twice on retry...
+```
+
+---
+
+## Resume a Run
+
+If a run was interrupted:
+
+```bash
+node scripts/resume.mjs
+```
+
+Returns the most recent interrupted run's metadata (or null).
+
+Use `currentPhase` from metadata to determine where to continue.
+Rebuild briefs using `run-state.mjs build-brief` for remaining phases.
+
+---
+
+## Coordinator-Only Mode
+
+If the current agent's model is below the minimum capability for critical phases:
+
+```
+Current model planning score < 3  (required for plan)
+Current model review score   < 3  (required for review)
+→ Role: Coordinator Only
+```
+
+In Coordinator-Only mode:
+- Do NOT plan or review yourself
+- Dispatch ALL critical phases to stronger agents via routing
+- Only: pass briefs, receive results, update run state, report outcome
+
+The routing engine already handles this — it will NOT select a weak model for planning or review.
+
+---
+
+## What This Skill Does NOT Do
+
+```
+✗ Self-learning
+✗ Automatic quota detection
+✗ Cost prediction
+✗ Multiple delegates per phase
+✗ Unlimited review loops
+✗ Automatic rollback
+✗ Cloud features
+```
+
+---
+
+## Quick Reference
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/discover.mjs` | Detect installed agents and delegate fleet |
+| `scripts/setup.mjs` | Interactive setup + config write |
+| `scripts/route.mjs` | Deterministic routing (stdin JSON → stdout JSON) |
+| `scripts/run-state.mjs` | Run workspace: init, update, read, write, brief |
+| `scripts/resume.mjs` | Find and return interrupted run |
+
+| Reference | Content |
+|-----------|---------|
+| `references/capability-registry.md` | Score definitions, phase requirements |
+| `references/routing-rules.md` | Classification, effort table, agent priority |
+| `references/handoff-schema.md` | File schemas, run-state.mjs usage |
+| `references/delegate-integration.md` | Delegate setup and rules |
+
+---
+
+## One-Line Description
+
+> **Give Adaptive Director one coding task. It routes every phase to the right agent, model, and reasoning effort automatically.**

package/data/registry.json

@@ -0,0 +1,42 @@
+{
+  "models": {
+    "claude-opus-4":    { "planning": 5, "coding": 4, "review": 5 },
+    "claude-opus-3":    { "planning": 5, "coding": 4, "review": 5 },
+    "claude-sonnet-4-5":{ "planning": 4, "coding": 4, "review": 4 },
+    "claude-sonnet-3-5":{ "planning": 4, "coding": 4, "review": 4 },
+    "claude-haiku-3-5": { "planning": 2, "coding": 3, "review": 2 },
+    "o3":               { "planning": 5, "coding": 3, "review": 5 },
+    "o4-mini":          { "planning": 3, "coding": 4, "review": 3 },
+    "gpt-4o":           { "planning": 3, "coding": 4, "review": 3 },
+    "gemini-2-5-pro":   { "planning": 4, "coding": 4, "review": 4 },
+    "gemini-2-0-flash": { "planning": 2, "coding": 3, "review": 2 },
+    "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 }
+  },
+  "effort_table": {
+    "conservative": {
+      "plan": "medium", "implement": "medium",
+      "review": "high", "fix": "medium", "verify": "medium"
+    },
+    "balanced": {
+      "plan": "high",   "implement": "medium",
+      "review": "high", "fix": "medium", "verify": "medium"
+    },
+    "quality": {
+      "plan": "high",   "implement": "medium",
+      "review": "high", "fix": "medium", "verify": "high"
+    }
+  },
+  "phase_map": {
+    "small":  ["implement", "review"],
+    "medium": ["plan", "implement", "review", "verify"],
+    "large":  ["plan", "implement", "review", "fix", "verify"]
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "adaptive-director-skill",
+  "version": "0.1.0",
+  "description": "Adaptive Director Skill — Skill-first adaptive multi-agent orchestration for AI coding agents",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ahmed Tamer",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tamourax/Adaptive-Orchestrator.git"
+  },
+  "files": [
+    "SKILL.md",
+    "README.md",
+    "LICENSE",
+    "scripts/",
+    "references/",
+    "data/"
+  ],
+  "scripts": {
+    "test": "node scripts/smoke-test.mjs",
+    "setup": "node scripts/setup.mjs",
+    "discover": "node scripts/discover.mjs"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "coding-agents",
+    "multi-agent",
+    "orchestration",
+    "director",
+    "codex",
+    "claude",
+    "agentic-coding",
+    "skill"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}