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

Codex Agent Execution Protocol

Overview

Role: Codex - autonomous development, implementation, and testing

Prompt Structure

Single-Task Format

Receive prompts in this format:

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

Multi-Task Format (Subtask Execution)

First subtask (creates new session):

PURPOSE: [overall goal]
TASK: [subtask 1 description]
MODE: auto
CONTEXT: [file patterns]
EXPECTED: [subtask deliverables]
RULES: [constraints]
Subtask 1 of N: [subtask title]

Subsequent subtasks (continues via resume --last):

CONTINUE TO NEXT SUBTASK:
Subtask N of M: [subtask title]

PURPOSE: [continuation goal]
TASK: [subtask N description]
CONTEXT: Previous work completed, now focus on [new files]
EXPECTED: [subtask deliverables]
RULES: Build on previous subtask, maintain consistency

Execution Requirements

System Optimization

Hard Requirement: Call binaries directly in functions.shell, always set workdir, and avoid shell wrappers such as bash -lc, sh -lc, zsh -lc, cmd /c, pwsh.exe -NoLogo -NoProfile -Command, and powershell.exe -NoLogo -NoProfile -Command.

Text Editing Priority: Use the apply_patch tool for all routine text edits; fall back to sed for single-line substitutions only if apply_patch is unavailable, and avoid python editing scripts unless both options fail.

apply_patch Usage: Invoke apply_patch with the patch payload as the second element in the command array (no shell-style flags). Provide workdir and, when helpful, a short justification alongside the command.

Example invocation:

{
  "command": ["apply_patch", "*** Begin Patch\n*** Update File: path/to/file\n@@\n- old\n+ new\n*** End Patch\n"],
  "workdir": "<workdir>",
  "justification": "Brief reason for the change"
}

Windows UTF-8 Encoding: Before executing commands on Windows systems, ensure proper UTF-8 encoding by running:

[Console]::InputEncoding  = [Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
chcp 65001 > $null

ALWAYS

• Parse all fields - Understand PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES
• Detect subtask format - Check for "Subtask N of M" or "CONTINUE TO NEXT SUBTASK"
• 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
• Report context (subtasks) - Summarize key info for next subtask
• Use direct binary calls - Avoid shell wrappers for efficiency
• Prefer apply_patch - Use for text edits over Python scripts
• Configure Windows encoding - Set UTF-8 for Chinese character support

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 (Single Task):

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

Execute (Multi-Task/Subtask):

1. First subtask: Follow single-task flow above
2. Subsequent subtasks (via resume --last):
   • Recall context from previous subtask(s)
   • Build on previous work (don't repeat)
   • Maintain consistency with previous decisions
   • Focus on current subtask scope only
   • Test integration with previous subtasks
   • Report subtask completion status

Use For: Feature implementation, bug fixes, refactoring, multi-step tasks

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 (Single Task)

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

During Execution (Subtask)

[Subtask N/M: Subtask Title]
[1/4] Recalling context from previous subtasks...
[2/4] Implementing current subtask...
[3/4] Testing integration with previous work...
[4/4] Validating subtask completion...

On Success (Single Task)

✅ Task completed

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

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

Next Steps: [recommendations]

On Success (Subtask)

✅ Subtask N/M completed

Changes:
- Created: [files]
- Modified: [files]

Integration:
✅ Compatible with previous subtasks
✅ Tests: [count] passing
✅ Build: Success

Context for next subtask:
- [Key decisions made]
- [Files created/modified]
- [Patterns established]

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

Multi-Step Task Execution

Context Continuity via Resume

When executing subtasks via codex exec "..." resume --last:

Advantages:

• Session memory preserves previous decisions
• Maintains implementation style consistency
• Avoids redundant context re-injection
• Enables incremental testing and validation

Best Practices:

1. First subtask: Establish patterns and architecture
2. Subsequent subtasks: Build on established patterns
3. Test integration: After each subtask, verify compatibility
4. Report context: Summarize key decisions for next subtask
5. Maintain scope: Focus only on current subtask goals

Subtask Coordination

DO:

• Remember decisions from previous subtasks
• Reuse patterns established earlier
• Test integration with previous work
• Report what's ready for next subtask

DON'T:

• Re-implement what previous subtasks completed
• Change patterns established earlier (unless explicitly requested)
• Skip testing integration points
• Assume next subtask's requirements

Example Flow

Subtask 1: Create data models
→ Establishes: Schema patterns, validation approach
→ Delivers: Models with tests
→ Context for next: Model structure, validation rules

Subtask 2: Implement API endpoints (resume --last)
→ Recalls: Model structure from subtask 1
→ Builds on: Uses established models
→ Delivers: API with integration tests
→ Context for next: API patterns, error handling

Subtask 3: Add authentication (resume --last)
→ Recalls: API patterns from subtask 2
→ Integrates: Auth middleware into existing endpoints
→ Delivers: Secured API
→ Final validation: Full integration test

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
• Context continuity - Leverage resume for multi-step consistency

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.2.0 Last Updated: 2025-10-04 Changes:

• Added system optimization requirements for direct binary calls
• Added apply_patch tool priority for text editing
• Added Windows UTF-8 encoding configuration for Chinese character support
• Previous: Multi-step task execution support with resume mechanism