agent-phase-loop

You are executing the agent-phase-loop workflow.

Agent Roles

Agent	Role in this skill
Claude Code	Plans phases from specs, authors task specs, monitors, QA, updates state
Codex	Implements — receives compact task specs, returns diffs
Gemini	Reviews every phase exhaustively — mandatory before closing any phase
Copilot	Additional review or targeted implementation when needed

LLM Handoff Optimization

Codex

Codex implements best from compact, unambiguous specs. One prompt per phase — batch everything.

Spec format (the only acceptable format):

<file_path> — <function_signature>
  - <behavior bullet>
  - <behavior bullet>

Spec quality checklist — verify before sending:

• Every item has an exact file path and function signature
• Behavior bullets are deterministic (no "as appropriate", "if needed", "consider")
• No architecture opinions or prose — Codex will fill gaps with hallucinations
• No more than one concept per bullet
• Tests specified explicitly if they need to run

Codex failure modes:

• Vague spec → Codex invents behavior that seems plausible but is wrong
• Split across multiple prompts → Codex loses context, duplicates or contradicts
• Asking Codex to "figure out" structure → always over-engineers
• No verification step specified → Codex skips tests silently

Gemini

Gemini is the phase gate. Every phase must pass Gemini review before active-context.md is updated.

Frame the review prompt to exploit Gemini's large context:

• List every file changed in the phase explicitly
• Ask Gemini to read all changed files in full before commenting
• Request structured output: severity-tagged findings, one per line
• Ask for LGTM or NEEDS WORK verdict on first line

mcp__agent-bridge__call_gemini(prompt="""
Phase review: <phase name>

Changed files:
- <file1>
- <file2>

Read each file in full. Review for:
- Correctness: does implementation match the spec?
- Regressions: does anything break existing behavior?
- Completeness: any spec items missed?
- Quality: obvious bugs, missing error handling at boundaries

First line verdict: "LGTM" or "NEEDS WORK"
Then: one finding per line, severity-tagged [CRITICAL|HIGH|MEDIUM|LOW]
""", cwd="<project_root>")

Do NOT specify a Gemini model — MCP bridge picks best available. If MCP fails: fallback to gemini -m gemini-2.5-pro --approval-mode yolo.

Copilot

Use Copilot for targeted second opinions on security-sensitive or API surface changes. Scope it explicitly — don't ask Copilot to review the whole phase, ask about one concern.

Claude Code (self)

Claude Code owns the spec, the review interpretation, and all state writes. Never use the Agent tool to delegate implementation (re-sends full context = 2x cost). Only Codex (Bash) and Gemini/Copilot (MCP bridge) are approved implementation/review paths.

---

Trigger

On "read active-context.md", "continue", "pick up", or "start next phase": execute all lifecycle steps immediately and autonomously without pausing for confirmation.

---

Phase Lifecycle

1. Read active-context.md → determine next phase and scope
2. Read phase spec from .planning/phases/ if one exists for this phase
3. Author phase plan: task list only — file path + function signature + behavior bullets, no prose
4. Hand off to Codex via Bash heredoc (full task spec, one prompt)
5. Monitor Codex until complete
6. Hand off to Gemini via MCP bridge for exhaustive review
7. Monitor Gemini until complete
8. Remediate every Gemini finding (re-send to Codex if code changes needed)
9. Update active-context.md (max 150 lines, strip completed phase details)
10. Inform user phase is complete

---

Agent Handoff Patterns

Codex — Bash heredoc (MCP bridge incompatible with codex ≥0.128.0):

codex exec --dangerously-bypass-approvals-and-sandbox - <<'EOF'
<task spec>
EOF

Gemini — MCP bridge:

mcp__agent-bridge__call_gemini(prompt="<prompt>", cwd="<project_root>")

Copilot — MCP bridge:

mcp__agent-bridge__call_copilot(prompt="<prompt>", cwd="<project_root>")

Claude — MCP bridge (for sub-tasks only, not implementation):

mcp__agent-bridge__call_claude(prompt="<prompt>", cwd="<project_root>")

---

Task Spec Format (Codex)

backend/app/auth.py — verify_token(token: str) -> User
  - Decode JWT using SECRET_KEY from config
  - Raise HTTP 401 if expired or invalid signature
  - Look up user by sub claim, raise HTTP 404 if not found
  - Return User ORM object

backend/tests/test_auth.py — test_verify_token_expired()
  - Assert verify_token raises 401 on expired token
  - Use a token signed with a past exp claim

---

Token Rules

• No Agent tool for writing code — full context re-send = 2x cost
• Read only files being edited or containing symbols to import
• No speculative reads; no re-reads unless content changed
• Batch all phase tasks into one Codex prompt
• One verification run at end of phase
• No mid-phase re-reads of active-context.md or planning docs
• Terminal output: errors/failures only
  • pytest: pass/fail counts + failed test names only
  • Build logs: | grep -E 'error|Error|ERROR'

---

Planning Docs

All docs in .planning/ — gitignored, excluded from agent contexts. Read only when a specific file is named by the user or required for the current phase spec.

---

Gemini Review (mandatory)

Gemini reviews every phase. Not optional. Even when no issues are suspected, hand off and wait for verdict before closing. Remediate every finding before updating active-context.md.

Gemini fallback if MCP fails:

gemini -m gemini-2.5-pro --approval-mode yolo - <<'PROMPT'
<review prompt>
PROMPT

---

active-context.md Rules

• Max 150 lines
• Strip completed phase details after close — keep only current state and next phase
• Update after every completed phase, not mid-phase

---

Phase Completion Checklist

• All Codex tasks complete
• Gemini review verdict: LGTM
• All Gemini findings remediated
• Tests pass (pass/fail count only)
• active-context.md updated
• User informed

---

Related Skills

• agent-review-loop — run before starting a build cycle to discover issues first
• agent-remediate-loop — run to fix findings from agent-review-loop before or after phases