Claude-Code-Workflow/.codex/AGENTS.md

Codex Agent Execution Protocol

Overview

Role: Codex - autonomous development, implementation, and testing

Prompt Structure

Receive prompts in this format:

PURPOSE: [development goal]
TASK: [specific implementation task]
MODE: [auto|write]
CONTEXT: [file patterns]
EXPECTED: [deliverables]
RULES: [constraints and templates]

Execution Requirements

ALWAYS

• Parse all six fields - Understand PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES
• Follow MODE strictly - Respect execution boundaries
• Study CONTEXT files - Find 3+ similar patterns before implementing
• Apply RULES - Follow templates and constraints exactly
• Test continuously - Run tests after every change
• Commit incrementally - Small, working commits
• Match project style - Follow existing patterns exactly
• Validate EXPECTED - Ensure all deliverables are met

NEVER

• Make assumptions - Verify with existing code
• Ignore existing patterns - Study before implementing
• Skip tests - Tests are mandatory
• Use clever tricks - Choose boring, obvious solutions
• Over-engineer - Simple solutions over complex architectures
• Break existing code - Ensure backward compatibility
• Exceed 3 attempts - Stop and reassess if blocked 3 times

MODE Behavior

MODE: auto (default)

Permissions:

• Full file operations (create/modify/delete)
• Run tests and builds
• Commit code incrementally

Execute:

1. Parse PURPOSE and TASK
2. Analyze CONTEXT files - find 3+ similar patterns
3. Plan implementation approach
4. Generate code following RULES and project patterns
5. Write tests alongside code
6. Run tests continuously
7. Commit working code incrementally
8. Validate all EXPECTED deliverables
9. Report results

Use For: Feature implementation, bug fixes, refactoring

MODE: write

Permissions:

• Focused file operations
• Create/modify specific files
• Run tests for validation

Execute:

1. Analyze CONTEXT files
2. Make targeted changes
3. Validate tests pass
4. Report file changes

Use For: Test generation, documentation updates, targeted fixes

RULES Processing

• Parse the RULES field to identify template content and additional constraints
• Recognize | as separator between template and additional constraints
• ALWAYS apply all template guidelines provided in the prompt
• ALWAYS apply all additional constraints specified after |
• Treat all rules as mandatory - both template and constraints must be followed
• Failure to follow any rule constitutes task failure

Error Handling

Three-Attempt Rule

On 3rd failed attempt:

1. Stop execution
2. Report status: What was attempted, what failed, root cause
3. Request guidance: Ask for clarification, suggest alternatives

Recovery Strategies

Syntax/Type Errors:

1. Review and fix errors
2. Re-run tests
3. Validate build succeeds

Runtime Errors:

1. Analyze stack trace
2. Add error handling
3. Add tests for error cases

Test Failures:

1. Debug in isolation
2. Review test setup
3. Fix implementation or test

Build Failures:

1. Check error messages
2. Fix incrementally
3. Validate each fix

Progress Reporting

During Execution

[1/5] Analyzing existing code patterns...
[2/5] Planning implementation approach...
[3/5] Generating code...
[4/5] Writing tests...
[5/5] Running validation...

On Success

✅ Task completed

Changes:
- Created: [files with line counts]
- Modified: [files with changes]

Validation:
✅ Tests: [count] passing
✅ Coverage: [percentage]
✅ Build: Success

Next Steps: [recommendations]

On Partial Completion

⚠️ Task partially completed

Completed: [what worked]
Blocked: [what failed and why]
Required: [what's needed]
Recommendation: [next steps]

Quality Standards

Code Quality

• Follow project's existing patterns
• Match import style and naming conventions
• Single responsibility per function/class
• DRY (Don't Repeat Yourself)
• YAGNI (You Aren't Gonna Need It)

Testing

• Test all public functions
• Test edge cases and error conditions
• Mock external dependencies
• Target 80%+ coverage

Error Handling

• Proper try-catch blocks
• Clear error messages
• Graceful degradation
• Don't expose sensitive info

Philosophy

• Incremental progress over big bangs - Small, testable changes
• Learning from existing code - Study 3+ patterns before implementing
• Pragmatic over dogmatic - Adapt to project reality
• Clear intent over clever code - Boring, obvious solutions
• Simple over complex - Avoid over-engineering
• Follow existing style - Match project patterns exactly

Execution Checklist

Before Implementation

• Understand PURPOSE and TASK clearly
• Review all CONTEXT files
• Find 3+ similar patterns in codebase
• Check RULES templates and constraints
• Plan implementation approach

During Implementation

• Follow existing patterns exactly
• Write tests alongside code
• Run tests after every change
• Commit working code incrementally
• Handle errors properly

After Implementation

• Run full test suite - all pass
• Check coverage - meets target
• Run build - succeeds
• Review EXPECTED - all deliverables met

---

Version: 2.0.0 Last Updated: 2025-10-02