Co Pilot Loop

Cooperative Co-Pilot Loop (Supervisor Protocol)

The Co-Pilot Loop splits software engineering tasks between a Supervisor (Outer Loop — you) and an Executor (Inner Loop — a lightweight companion sub-agent). The Supervisor acts as the product manager and QA director, while the Executor performs spec writing, planning, and coding inside an isolated worktree.

You do not know which CLI or chat interface the user is using — and that's fine. The skill is model-agnostic. It reads the cheapest model for the active CLI at runtime.

1. Setup & Orientation

Step 1A — Determine the active CLI backend

Ask the user once (or detect from context):

"Which CLI backend is available for the sub-agent? (agy, claude, copilot, codex, llama)"

Step 1B — Look up the cheapest model for that backend

Consult plugins/agent-orchestration/references/cheapest_models.json (or references/cheapest_models.md) to select the cheapest model for the detected CLI backend.

Step 1C — Spawn the sub-agent

Use run_agent.py with the resolved CLI and model:

# For agy (recommended — cheapest Gemini)
python ./scripts/run_agent.py <PERSONA_FILE> <PACKET_FILE> <OUTPUT_FILE> "<INSTRUCTION>" \
  --cli agy --model "Gemini 3.5 Flash (Low)" < /dev/null

# For claude CLI
python ./scripts/run_agent.py <PERSONA_FILE> <PACKET_FILE> <OUTPUT_FILE> "<INSTRUCTION>" \
  --cli claude --model claude-haiku-4.5 < /dev/null

# For copilot CLI
python ./scripts/run_agent.py <PERSONA_FILE> <PACKET_FILE> <OUTPUT_FILE> "<INSTRUCTION>" \
  --cli copilot --model gpt-5.4-nano < /dev/null

CRITICAL: Always append < /dev/null to prevent SIGTTIN process suspension in background execution.

2. Strategy Packet & Handoff

Create an isolated Git worktree or branch for the Executor. Generate a Strategy Packet (via scripts/agent_orchestrator.py packet) containing:

1. Objective — what feature/bug is being implemented.
2. Constraints — TDD rules, symlink policy, coding conventions, no deletions.
3. No-Git Rule — the Executor is strictly forbidden from running any git commands.
4. Spec output path — e.g. docs/superpowers/specs/YYYY-MM-DD-<feature>-spec.md.
5. Plan output path — e.g. implementation_plan.md.

Hand the Strategy Packet to the Executor and start the parallel session.

3. Supervision & Review Gates

You (the Supervisor) enforce the following sequential gates. No gate may be skipped.

Gate 1 — Design Spec Review

When the Executor generates a design spec, audit it:

• No vague placeholders (TODO, TBD, REPLACE).
• Architectural decisions align with existing ADRs and codebase patterns.
• Action: Approve → proceed to Gate 2. Reject → pass specific written feedback back to Executor.

Gate 2 — Implementation Plan Review

Review the Executor's implementation_plan.md / task.md:

• Files grouped logically by dependency layer.
• A clear automated verification plan is included.
• Action: Approve → proceed to Gate 3. Reject → return with specific revision notes.

Gate 3 — QA & Verification

Once Executor signals completion, run the verification suite:

python3 run_tests.py    # or npm run test / npm run build
git diff                # inspect all changed files

Classify issues using the severity schema:

• 🔴 CRITICAL — fails compile or tests. Return error logs to Executor immediately.
• 🟡 MODERATE — works but violates conventions or ADRs. Return with specific ADR.
• 🟢 MINOR — stylistic only. Fix directly yourself.

Generate correction packets via: python ./scripts/agent_orchestrator.py correct --packet handoffs/task_NNN.md --feedback "Reason"

4. Retrospective & Closure

Once all verification tests pass:

1. Merge branch to main (from repo root only, never inside worktree).
2. Update RLM summaries and write session retrospective (scripts/agent_orchestrator.py retro).
3. Commit validated changes.