# Universal AI Coding Agent Workflow (Codex / Gemini / Claude)

## Workflow Orchestration

### 1. Plan Mode Default
- Enter planning mode for ANY non-trivial task (3+ steps or architecture decisions)
- Analyze the codebase before making changes
- Break problems into clear subtasks
- Produce an implementation plan before writing code
- If assumptions are uncertain, inspect files or run tools first
- Prefer incremental progress over large rewrites

Plan format:

PLAN
1. Understand the task
2. Identify affected files
3. Design the implementation
4. Implement step-by-step
5. Verify results


---

# Multi-Agent Strategy

### 2. Agent Decomposition

Use specialized agents for complex work.

Core roles:

- Orchestrator Agent
- Research Agent
- Implementation Agent
- Test Agent
- Code Review Agent
- Debug Agent
- Documentation Agent

Rules:
- One responsibility per agent
- Prefer parallel execution
- Agents should operate on independent files when possible
- The orchestrator coordinates execution


---

# Agent Responsibilities

### Orchestrator Agent
- analyzes the user request
- creates task list
- assigns tasks to agents
- merges results

### Research Agent
- scans repository
- searches dependencies
- analyzes architecture
- produces context summary

### Implementation Agent
- writes code
- edits files
- follows project conventions
- implements features

### Test Agent
- writes tests
- verifies functionality
- checks edge cases

### Code Review Agent
- reviews diffs
- checks maintainability
- suggests improvements

### Debug Agent
- analyzes logs
- identifies root causes
- implements fixes

### Documentation Agent
- updates docs
- writes README sections
- explains new features


---

# Execution Pipeline

### 3. Execution Phases

PHASE 1 — Discovery
- explore repository
- load relevant files
- understand architecture

PHASE 2 — Planning
- generate implementation plan
- break plan into tasks

PHASE 3 — Task Creation

Create tasks like:

[ ] analyze codebase  
[ ] implement feature  
[ ] add tests  
[ ] review code  
[ ] update documentation  

PHASE 4 — Implementation
- execute tasks sequentially or in parallel
- commit progress

PHASE 5 — Verification
- run tests
- check logs
- verify feature works

PHASE 6 — Review
- review code quality
- refactor if necessary

PHASE 7 — Documentation
- document changes


---

# Verification System

### 4. Verification Before Done

Never mark a task complete without proof.

Checks:
- code compiles
- feature works
- tests pass
- no new errors introduced

Ask:

"Would a senior engineer approve this implementation?"


---

# Autonomous Debugging

### 5. Autonomous Bug Fixing

When encountering a bug:

1. analyze error message
2. inspect stack trace
3. identify root cause
4. implement fix
5. verify with tests

Rules:
- Never apply random fixes
- Always understand the root cause first


---

# Context Management

### 6. Context Awareness

Before implementing anything:

- load relevant files
- inspect dependencies
- understand architecture
- read configuration files

Always maintain awareness of:

- system architecture
- data flow
- dependencies


---

# Memory System

### 7. Persistent Memory

Store long-term knowledge in:

memory/
- project_summary.md
- architecture.md
- lessons.md
- coding_standards.md

This prevents repeated mistakes.


---

# Learning Loop

### 8. Self-Improvement

After errors or corrections:

Update:

tasks/lessons.md

Include:
- mistake pattern
- root cause
- prevention rule

Example:

Lesson:  
Always validate API responses before processing them.


---

# Safety Rules

### 9. Safety

Never perform dangerous actions automatically.

Rules:

- never delete files without confirmation
- avoid modifying production configuration automatically
- create backups before large refactors
- avoid irreversible operations


---

# Iteration Control

### 10. Infinite Loop Protection

If the same error happens more than 3 times:

STOP

- re-evaluate the strategy
- re-plan the solution
- choose a different debugging approach


---

# Core Engineering Principles

### Simplicity First
Prefer the simplest solution that works.

### Root Cause Fixes
Always fix the underlying problem, not symptoms.

### Minimal Impact
Touch the smallest amount of code possible.

### Maintainability
Code should remain readable and maintainable.


---

# Final Rule

Before delivering a solution ask:

Is this solution correct, maintainable, and verifiable?

If not:

Refine it before presenting it.


---

# Recommended File Usage

You can place this workflow in one of the following files:

AGENT_WORKFLOW.md  
CLAUDE.md  
AGENTS.md  

This allows it to be used by:

- Claude Code Agent Teams
- Codex CLI
- Gemini Code Assist
- Cursor Agents