# AI Coding Orchestrator (`aico` V2)

A production-quality local CLI application designed to orchestrate specialized coding agents:

* **Codex CLI** → Lead Software Architect, Core Developer, and Complex Problem Solver.
* **Antigravity / AGY CLI** → Quality Assurance, Reviewer, Regression Tester, and Small-Fix Agent.
* **Extended Agents** → **Claude**, **Gemini**, and **Local LLMs** (via Ollama / OpenAI-compatible endpoints).

`aico` manages state machines, workflow transitions, Git worktree isolation, prompt templating, parallel test execution, AST security scanning, human-in-the-loop approvals, MCP server integration, and comprehensive reporting.

---

## 🏗️ Architecture

```
                    ┌────────────────────────┐
                    │      USER / CLI        │
                    │         (aico)         │
                    └───────────┬────────────┘
                                │
                        TASK RECEIVED
                                │
                    ┌───────────▼────────────┐
                    │  GIT & WORKTREE CHECK  │
                    │ Zero-Impact Isolation  │
                    └───────────┬────────────┘
                                │
                    ┌───────────▼────────────┐
                    │       CODEX CLI        │
                    │  • Architecture Design │
                    │  • Core Implementation │
                    │  • Complex Fixes       │
                    └───────────┬────────────┘
                                │
                    ┌───────────▼────────────┐
                    │        AGY CLI         │
                    │  • Review & Test Plan  │
                    │  • Parallel Validation │
                    │  • AST Security Audit  │
                    │  • Issue Classification│
                    └───────────┬────────────┘
                                │
                 ┌──────────────┴──────────────┐
                 │ Issue Classification Branch │
                 └──────────────┬──────────────┘
                                │
       ┌────────────────────────┼────────────────────────┐
       │                        │                        │
     PASS                   SMALL_FIX           COMPLEX / ARCH / BUG / SEC
       │                        │                        │
       ▼                        ▼                        ▼
PARALLEL VALIDATION          AGY FIX                 CODEX FIX
(Test, Lint, Type,           (Local)                 (Deep Fix)
 Build, Security)               │                        │
       │                        ▼                        ▼
       ▼                    AGY RETEST               AGY RETEST
     DONE                       │                        │
                                └─────────►◄─────────────┘
```

---

## 🚀 V2 Features & Enhancements

1. **🌿 Zero-Impact Git Worktree Isolation (`--worktree` / `-w`)**:
   - Executes all agent actions inside an isolated Git worktree without touching your active editor files or unstaged changes.
   - Automatically syncs and merges when the task completes successfully.

2. **⚡ Parallel Quality & Test Engine (`aico test`)**:
   - Concurrently executes Unit Tests, Linters (`ruff`/`eslint`), Typecheckers (`mypy`/`tsc`), Builds, and Security Audits in worker thread pools.

3. **🛡️ Built-in AST & Static Security Scanner (`aico scan`)**:
   - Real-time detection of SQL Injection risks, command injection (`shell=True`), hardcoded JWT secrets, weak cryptography (MD5/SHA1), and unsafe dynamic execution (`eval`/`exec`).

4. **🔶 Human-In-The-Loop (HITL) Mode (`--interactive` / `-i`)**:
   - Interactive checkpoint approval before architectural changes or security fixes with direct prompt guidance injection (`[A]pprove`, `[E]dit guidance`, `[R]eject`, `[Q]uit`).

5. **🎯 Granular Multi-Tier Model Routing**:
   - Configure distinct models per phase (e.g. `o3-mini` / `claude-3-7-sonnet` for architecture, `gemini-2.0-flash` for test review, `gpt-4o-mini` for small fixes).

6. **🔌 Model Context Protocol (MCP) Server (`aico mcp`)**:
   - Run `aico` as a standard MCP server for seamless integration with Cursor, Antigravity IDE, Claude Desktop, and other MCP clients.

7. **🤖 Extended Agent Support**:
   - Built-in adapters for **Claude CLI**, **Gemini CLI**, and **Local LLMs** (Ollama / OpenAI-compatible).

---

## 📦 Installation & Setup

```bash
cd /var/www/html/ai-coding-orchestrator
pip install -e .
```

Verify installation:
```bash
aico doctor
```

---

## 💻 CLI Command Reference

| Command | Description |
| :--- | :--- |
| `aico` | Launch interactive prompt session |
| `aico "task"` | Run a direct task in current working directory |
| `aico run "task"` | Explicit task run |
| `aico run -w "task"` | Run in an isolated **Git worktree** (zero-impact) |
| `aico run -i "task"` | Run with **Interactive Human-In-The-Loop** checkpoints |
| `aico test` | Run parallel test, lint, typecheck, build, and security checks |
| `aico scan` | Run static AST & regex security vulnerability scan |
| `aico mcp` | Start Model Context Protocol (MCP) JSON-RPC stdio server |
| `aico resume` | Resume interrupted task from saved `.ai-orchestrator/state.json` |
| `aico status` | Inspect current task state, iterations, and metrics |
| `aico logs` | View unified logs (`--agent codex`, `--agent agy`) |
| `aico stop` | Abort and cancel active task |
| `aico config show` | View current configuration |
| `aico config set <key> <val>` | Update configuration key |
| `aico doctor` | Run health checks for Codex, AGY, and Git |

---

## ⚙️ Configuration (`~/.aico/config.yaml`)

```yaml
codex:
  command: "codex"
  timeout: 3600
  flags: ["exec", "--dangerously-bypass-approvals-and-sandbox"]
  model: null
  architecture_model: null
  implementation_model: null
  fix_model: null

agy:
  command: "agy"
  timeout: 1800
  flags: ["--print", "--dangerously-skip-permissions"]
  model: null
  review_model: null
  testing_model: null
  fix_model: null

workflow:
  max_iterations: 5
  max_codex_attempts: 5
  max_agy_attempts: 5
  auto_resume: false
  stop_on_environment_issue: true
  interactive: false
  require_approval_on_architecture: false
  require_approval_on_security: false

git:
  enabled: true
  create_branch: true
  branch_prefix: "ai-orchestrator"
  auto_stash_uncommitted: false
  use_worktree: false

testing:
  run_tests: true
  run_lint: true
  run_typecheck: true
  run_build: true
  run_security_scan: true
  parallel: true
  max_workers: 4

safety:
  protect_uncommitted_changes: true
  allow_destructive_git: false
```

---

## 📂 Workspace Layout

```
.ai-orchestrator/
├── state.json           # Machine-readable task state and transition history
├── task.md              # Original user task
├── architecture.md      # Architecture design from Codex
├── final-report.md      # Comprehensive post-task markdown report
│
├── codex/
│   ├── prompt.md        # Prompt sent to Codex
│   ├── result.md        # Codex execution summary
│   └── issues.md        # Issues addressed
│
├── agy/
│   ├── prompt.md        # Prompt sent to AGY
│   ├── test-plan.md     # Test plan created by AGY
│   ├── result.md        # AGY validation results
│   ├── issues.md        # Issues detected
│   └── fixes.md         # Small fixes applied
│
├── logs/
│   ├── orchestrator.log # Workflow state transitions
│   ├── codex.log        # Raw stdout/stderr of Codex
│   └── agy.log          # Raw stdout/stderr of AGY
│
├── worktrees/           # Isolated git worktrees (when enabled)
└── checkpoints/         # Git snapshots before major stages
```

---

## 🧪 Test Suite

Run the full test suite covering all V1 and V2 capabilities:

```bash
pytest -v
```

**65 unit & integration tests pass with 100% success rate.**