multi-cli

Files (4)

• SKILL.md
• notify-tts.ps1 · templates/
• runner-template.ps1 · templates/
• wait-signal.ps1 · templates/

SKILL.md (first lines)

# Multi-CLI — Orchestrating external agents in visible terminals

The main agent dispatches; the CLIs execute with their own models; the user supervises live. The main agent
reads only compact signals — never dumps. **Project-agnostic** — the cycle applies to any codebase.

## `/multi-cli` flow on a new project

1. **Bootstrap** (idempotent, at the project root):
   - Create `workspace/{tasks,logs,results,modules}`.
   - Copy `notify-tts.ps1` from `~/.claude/skills/multi-cli/templates/` to `workspace/`.
   - Create `workspace/LEARNINGS.md` (project log) if missing.
2. **Worker health check** (skip if already validated today): a write smoke test in `workspace/sandbox/` for
   each CLI (30-60 s). Check each CLI's configured model; pick the tier with [[token-router]].
3. **Phased plan** (bucle-agentico blueprint pattern): small phases that leave the project working; subtasks
   only when entering a phase, after mapping the real context (grep, not assumptions).
4. **One-shot dispatch**: one task = one `tasks/T-XXX.md` file with numbered points + a runner from
   `templates/runner-template.ps1` + a visible `wt` pane. Parallelism only with partitioning (one owner per file).
   - **Before dispatching:** classify difficulty with [[token-router]] and assign the MINIMUM sufficient
     worker+model. Compile the prompt with the `agent-uplift` spec compiler.
5. **Review every delivery** with [[verify-repair]]: run the verify gate on the worker's output. NOT accepted
   without exit 0 (`edited=True` isn't enough). Failure → repair with a separate critic (fresh conversation) →
   one-shot re-derivation.
6. **Close**: functional verification of the whole, update LEARNINGS.md, and propagate with [[scratchpad]] to
   the right memory layers.

## Harness integration (quality + economy)

| Skill | What it adds to each dispatch |
|---|---|
| [[token-router]] | Minimum worker+model per difficulty |
| `agent-uplift` spec compiler | Perfect one-shot prompt + the target model's anti-patterns injected |
| [[verify-repair]] | Objective verdict on the worker's output, not just `edited` |
| [[scratchpad]] | Dispatch notes + correction detection + memory propagation at close |

### Adaptive verification (VG-Search: −52% FLOPs)

The verification level scales with the task's criticality:

| Criticality | Verification |
|---|---|
| Trivial (formatting, data, isolated module) | basic gate: parse + deliverable check |
| Standard (function, fix, bounded feature) | + lint + project tests + grep per spec point |
| Critical (main file, integration, refactor) | + Playwright/behaviour + point-by-point review |

Spend verification where an error is expensive; the verdict stays objective at every level.

## CLI inventory (examples — check your versions)

| CLI | Headless | Model | Writes files | Monitoring |
|---|---|---|---|---|
| AGY = Antigravity CLI | `agy -p "task" --print-timeout 30m` | `~/.gemini/antigravity-cli/settings.json` → `"model"` | ✅ (trusted workspaces) | ⚠️ no capturable stdout → transcript JSONL under `~/.gemini/antigravity-cli/brain/<conv>/.system_generated/logs/transcript.jsonl` |
| OpenCode | `opencode run "task"` | `-m provider/model`; `--format json`, `-s session` | ✅ by default | normal stdout → `Tee-Object` works |
| Codex | `codex exec "task"` | `-m model` | ✅ with the right sandbox flag | normal stdout |

Multi-turn without the TUI: `opencode run -s <id> "..."`. The TUI is for the human.

## One-shot doctrine

Every dispatch is a **self-contained one-shot prompt** — the worker gets ALL the context it needs (numbered
spec + file references) and must finish in one pass. Don't chain corrections over long conversations: if a
delivery misses something non-trivial, **re-derive with a new one-shot** (corrected spec, fresh conversation)
instead of patching a contaminated context. Tiny details are fixed directly by the main agent.

| Level | Worker + model | When |
|---|---|---|
| Excellence | strongest available model (e.g. Opus via a CLI or subagent) | architecture, big edits to the main file |
| Medium | a strong free/cheap model | modules, bounded features |
| Mechanical | the cheapest model | QA, data, short tasks |

If a CLI degrades (fast exit 0 without activity), try switching its model line: quotas are often per line.

## Dispatch protocol

```
workspace/
├── tasks/T-XXX.md      ← prompt: goal + rules + "summary max 10 lines at the end"
├── runner-T-XXX.ps1    ← wrapper (template below)
├── logs/T-XXX.log      ← full output (for the human; AGY doesn't fill it — use its transcript)
├── logs/T-XXX.done     ← compact signal: exit + time + checks (the ONLY thing the main agent polls)
└── results/            ← final JSON/reports
```

Runner template (the `edited` check is MANDATORY for tasks that edit files — exit 0 doesn't guarantee an edit):
```powershell
$ws = $PSScriptRoot
Set-Location (Split-Path $ws)   # project root
$task = Get-Content "$ws\tasks\T-XXX.md" -Raw
$pre = (Get-Item .\<target-file>).Length             # snapshot before
Copy-Item .\<target-file> "$ws\backup-T-XXX" -Force  # backup before editing
Write-Host "=== T-XXX · <CLI> · <GOAL> · $(Get-Date -Format HH:mm:ss) ===" -ForegroundColor Cyan
<cli> <flags> $task 2>&1 | Tee-Object "$ws\logs\T-XXX.log"
$post = (Get-Item .\<target-file>).Length
"exit=$LASTEXITCODE end=$(Get-Date -Format HH:mm:ss) size_pre=$pre size_post=$post edited=$($post -ne $pre) <deliverable checks: x=$(Test-Path ...)>" | Set-Content "$ws\logs\T-XXX.done"
pwsh -File "$ws\notify-tts.ps1" -msg "Task T XXX finished. File edited: $($post -ne $pre)."
```
For tasks that CREATE files, the `.done` carries a `Test-Path` per expected deliverable.

Voice notification: `workspace/notify-tts.ps1` — edge_tts (voice from `JARVIS_TTS_VOICE`, default
`en-US-GuyNeural`) → ffplay → SAPI → beep. Each runner calls it when writing its `.done`, so the human knows
without watching the terminals.

Visible terminals (the human previews):
```powershell
wt -w 0 nt --title "T-A · AGY" pwsh -NoExit -File runner-A.ps1 `; sp --title "T-B · OpenCode" pwsh -NoExit -File runner-B.ps1
```
(`` `; `` escapes the pane separator for wt; `-NoExit` keeps the pane inspectable.)

Waiting: a background monitor polls `.done` every 5-10 s with a deadline (`templates/wait-signal.ps1`); on
close, read `.done` + the log tail (`-Tail 25`) or the AGY transcript. NEVER read whole logs.

## PARALLEL work without collisions

Partition rule: **only one agent edits each target file**. Others produce self-contained modules in
`workspace/modules/` against an explicit interface contract (which globals exist, what not to redefine, no
import/export). Integration is done by the next task of the file's owner.

## Retry, degradation and fallback policy

When a delivery fails review (`edited=False`, missing deliverable, or checklist gaps):

From Ignvvcio254/Jarvis-254-Agent, MIT.

More from Ignvvcio254/Jarvis-254-Agent