vc-phase-loop

name: vc-phase-loop description: Ultimate autonomous execution engine. Plan → Execute → Test → Never Stop Until Done. Use when the user wants hands-off completion with no questions, automatic recovery from any failure, and proven results. metadata: short-description: Plan → execute → test → prove (with retries).

VC Phase Loop - ULTIMATE EDITION

Core Philosophy

┌─────────────────────────────────────────────────────────────┐
│                    THE IRON LAWS                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. NEVER STOP UNTIL PROVEN DONE                            │
│  2. NEVER ASK - DECIDE AND RECORD                           │
│  3. NEVER FAIL - ADAPT AND RETRY                            │
│  4. NEVER FORGET - TRACK EVERYTHING                         │
│  5. NEVER ASSUME DONE - VERIFY WITH EVIDENCE                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Step Zero: Work Document (MANDATORY)

BEFORE ANY WORK, create .vc/work-{timestamp}.md:

# Task: {description}
Started: {datetime}
Status: in_progress

## Phases
- [ ] Phase 1: {name}
- [ ] Phase 2: {name}
...

## Assumptions Log
| # | Decision | Rationale | Reversible |
|---|----------|-----------|------------|

## Error Log
| # | Phase | Error | Attempted Fix | Result |
|---|-------|-------|---------------|--------|

## Completion Evidence
{filled when verified complete}

UPDATE THIS DOCUMENT AFTER EVERY ACTION.

VC Triggers

Activate with any of these:

• vcf: <task> - SHORT AND POWERFUL (recommended)
• use vcf: <task> - equivalent explicit invocation (Codex may output this form)
• "vc finish", "finish it", "take it to the end"
• "plan and execute", "hands off"

The Execution Engine

Phase Structure

┌─────────────────────────────────────────────────────────────┐
│              EXECUTION PIPELINE                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  STAGE 1: RECONNAISSANCE (Parallel if possible)             │
│  ├─ Analyze requirements                                    │
│  ├─ Find related code                                       │
│  ├─ Identify risks                                          │
│  └─ Duration: Until complete understanding                  │
│                                                             │
│  STAGE 2: PLANNING                                          │
│  ├─ Create 10-phase plan (20 for large scope)               │
│  ├─ Define success criteria per phase                       │
│  ├─ Identify parallel opportunities                         │
│  └─ Output: Phase list with checkboxes                      │
│                                                             │
│  STAGE 3: EXECUTION (Parallel where independent)            │
│  ├─ Execute phases sequentially or in parallel              │
│  ├─ On failure: SELF-HEAL (see below)                       │
│  ├─ Record assumptions with rationale                       │
│  └─ Update work document after each phase                   │
│                                                             │
│  STAGE 4: VERIFICATION                                      │
│  ├─ Run ALL tests                                           │
│  ├─ Verify each requirement with evidence                   │
│  ├─ If fails: LOOP BACK (do not stop)                       │
│  └─ Output: Completion proof                                │
│                                                             │
│  EXIT: ONLY when proven complete                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Infinite Retry Engine

ON ANY FAILURE:

┌─────────────────────────────────────────────────────────────┐
│              SELF-HEALING PROTOCOL                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Attempt 1: Standard approach                               │
│      ↓ FAIL?                                                │
│  Attempt 2: Alternative method                              │
│      ↓ FAIL?                                                │
│  Attempt 3: Decompose into smaller tasks                    │
│      ↓ FAIL?                                                │
│  Attempt 4: Deep root cause analysis                        │
│      ↓ FAIL?                                                │
│  Attempt 5: Try 3 different approaches in parallel          │
│      ↓ FAIL?                                                │
│  Attempt 6: Research external solutions                     │
│      ↓ FAIL?                                                │
│  Attempt 7: Create workaround                               │
│      ↓ FAIL?                                                │
│  Attempt 8+: Hybrid approach combining all learnings        │
│      ↓ CONTINUE INDEFINITELY                                │
│                                                             │
│  ═══════════════════════════════════════════════════════    │
│  THE LOOP NEVER ENDS UNTIL SUCCESS                          │
│  ═══════════════════════════════════════════════════════    │
│                                                             │
│  On EVERY failure:                                          │
│  1. Log error with full context                             │
│  2. Diagnose root cause                                     │
│  3. Select new strategy                                     │
│  4. Execute immediately                                     │
│  5. Record lesson learned                                   │
│                                                             │
│  NEVER: Stop and wait for user                              │
│  NEVER: Give up                                             │
│  NEVER: Report failure without attempting fix               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Decision Policy

Automatic Decisions (No User Input)

Make these decisions automatically and record in Assumptions Log:

Hard Stops (PAUSE AND ASK)

Only pause for these HIGH-RISK scenarios:

• Deleting more than 10 files
• Modifying production database
• Actions costing more than $10
• Security credentials handling
• Irreversible destructive operations

Everything else: DECIDE AND CONTINUE.

Test Discovery & Execution

Auto-Detection

Priority order:
1. package.json scripts → npm/yarn/pnpm test
2. Makefile → make test
3. pytest.ini/pyproject.toml → pytest
4. go.mod → go test ./...
5. Cargo.toml → cargo test
6. pom.xml → mvn test
7. build.gradle → ./gradlew test
8. *.csproj → dotnet test

If No Tests Found

1. Check for any quality command (lint, typecheck, build)
2. Run that instead
3. Note gap: "No tests found, ran lint/build instead"
4. Continue execution (do NOT stop)

Test Failure Response

Test Failed
    ↓
Analyze failure output
    ↓
Identify root cause
    ↓
Fix immediately
    ↓
Rerun tests
    ↓
If still failing: RETRY ENGINE (see above)
    ↓
NEVER stop on test failure

Parallelization Rules

Identify Parallel Opportunities

RULE: If two tasks have NO dependencies, run them in parallel.

Example:
  Phase 1: Create component A    ─┐
  Phase 2: Create component B    ─┼─ PARALLEL
  Phase 3: Create component C    ─┘
  Phase 4: Integrate A+B+C         → SEQUENTIAL (depends on 1-3)
  Phase 5: Add tests for A      ─┐
  Phase 6: Add tests for B      ─┼─ PARALLEL
  Phase 7: Add tests for C      ─┘

Background Execution

These run in background while continuing:

• npm install, pip install
• npm run build, cargo build
• Long-running compilations
• Docker operations

Check results before depending on them.

Team Delegation Protocol

When coordination overhead grows, use vc-agent-teams conventions with file mailboxes:

1. Create team and members:
   • vc teams create --name <team>
   • vc teams add-member --team <team> --name <agent>
2. Delegate scoped work via direct messages:
   • vc teams send --team <team> --type message --from team-lead --recipient <agent> --content \"<task>\"
3. Use broadcast only for milestone updates:
   • vc teams send --team <team> --type broadcast --from team-lead --content \"<status>\"
4. Process mailbox responses and mark them read to avoid duplicate execution.
5. Prune old read traffic periodically:
   • vc teams prune --team <team> --days 7

Protocol message types:

• message
• broadcast
• shutdown_request
• shutdown_response
• plan_approval_response

Sub-Agents (Collaboration Tools)

Modern Codex can spawn sub-agents. Use them to speed up independent work (recon, analysis, testing), then merge results into a single execution thread.

When to Spawn Sub-Agents

Use sub-agents when you have 2+ independent threads such as:

• Repo reconnaissance (find files, map architecture, identify owners)
• Documentation lookup / API surface verification
• Running tests + collecting failure analysis
• Exploring alternative implementations in parallel

Sub-Agent Rules (Hard)

• Max 4 sub-agents (Codex may cap at 6; stay below it).
• Each sub-agent gets one narrow goal and a strict deliverable format.
• Prefer read-only tasks for sub-agents; the main agent owns all writes/patches to avoid conflicts.
• Keep collaboration depth at 1: sub-agents should not spawn more agents.
• If a sub-agent can’t run tools (or spawn_agent isn’t available), fallback to sequential.
• Always close_agent after harvesting results to avoid resource leaks.

Agent Role Presets (Recommended)

If supported, use role presets to make sub-agent behavior more predictable:

• explorer: repo reconnaissance (file map, configs, constraints). Read-only.
• worker: testing, repro, alternative approach sketches. Prefer read-only unless explicitly told to modify.
• default: general-purpose.

Dispatch Protocol (Tooling)

1. spawn_agent for each independent thread (use explorer for recon and worker for testing when supported).
2. Provide:
   • Goal (1 sentence)
   • Scope boundaries (what to touch / not touch)
   • Required output format (bullets/table)
   • Stop condition (when to reply)
3. wait for results (with timeouts), then send_input follow-ups if needed (use interrupt to stop/retask a long-running agent).
4. Integrate outputs into:
   • Work doc (Phases / Assumptions / Error Log)
   • A single consolidated plan (main agent)
5. close_agent for each sub-agent.

Output Format (Required)

Every sub-agent response must start with:

• SUMMARY: (≤5 bullets)
• FINDINGS: (facts + file paths/commands)
• RISKS: (what could go wrong)
• RECOMMENDATION: (next action)

Completion Proof (REQUIRED)

Before declaring done, you MUST provide:

## COMPLETION PROOF

✓ Executed:
  Command: {actual command}
  Output: {actual output pasted}

✓ Tests:
  Command: {test command}
  Result: {X passed, Y failed}

✓ Requirements Verified:
  - [Req 1]: {file}:{line} - {evidence}
  - [Req 2]: {file}:{line} - {evidence}

✓ Quality Checks:
  - Build: PASS
  - Lint: PASS (or N errors fixed)
  - Types: PASS

✓ Work Document: All boxes checked

Forbidden Completion Phrases

If you say these, YOU HAVE NOT COMPLETED:

• "I think it's done" → NOT DONE
• "Should work" → NOT DONE
• "Looks correct" → NOT DONE
• "I believe" → NOT DONE
• "Probably" → NOT DONE

Certainty required. Evidence required.

Context Management

For Long Tasks

When approaching context limits:

1. Checkpoint: Update work document with current state
2. Compress: Summarize completed phases briefly
3. Focus: Keep only current phase details in context
4. Reference: Point to work document for history

Resumption Protocol

If interrupted:

1. Read .vc/work-*.md to restore state
2. Find first unchecked item
3. Continue from there
4. No re-explanation needed

Output Format

Use these sections in order:

# Execution Report

## Plan
{10-20 phases with checkboxes}

## Progress
{Phase-by-phase execution with timestamps}

## Assumptions
{Table of decisions made}

## Tests
{Test execution results}

## Completion Proof
{Evidence as specified above}

The VC Promise

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   YOU SET THE GOAL.                                         │
│                                                             │
│   WE PLAN IT.                                               │
│   WE EXECUTE IT.                                            │
│   WE FIX WHATEVER BREAKS.                                   │
│   WE RETRY UNTIL SUCCESS.                                   │
│   WE PROVE IT WORKS.                                        │
│                                                             │
│   NO QUESTIONS. NO EXCUSES. NO STOPPING.                    │
│                                                             │
│   UNTIL IT'S DONE.                                          │
│   ACTUALLY DONE.                                            │
│   PROVEN DONE.                                              │
│                                                             │
└─────────────────────────────────────────────────────────────┘