Claude-Code-Workflow/AGENTS.md

# Codex Agent Execution Protocol

## Overview

**Role**: Autonomous development, implementation, and testing specialist


## Prompt Structure

All prompts follow this 6-field format:

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

**Subtask indicator**: `Subtask N of M: [title]` or `CONTINUE TO NEXT SUBTASK`

## MODE Definitions

### 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 following RULES
4. Generate code with tests
5. Run tests continuously
6. Commit working code incrementally
7. Validate EXPECTED deliverables
8. Report results (with context for next subtask if multi-task)

**Constraint**: Must test every change

### 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

## Execution Protocol

### Core Requirements

**ALWAYS**:
- Parse all 6 fields (PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES)
- Study CONTEXT files - find 3+ similar patterns before implementing
- Apply RULES (templates + constraints) exactly
- Test continuously after every change
- Commit incrementally with working code
- Match project style and patterns exactly
- List all created/modified files at output beginning
- Use direct binary calls (avoid shell wrappers)
- Prefer apply_patch for text edits
- Configure Windows UTF-8 encoding for Chinese support

**NEVER**:
- Make assumptions without code verification
- Ignore existing patterns
- Skip tests
- Use clever tricks over boring solutions
- Over-engineer solutions
- Break existing code or backward compatibility
- Exceed 3 failed attempts without stopping

### RULES Processing

- Parse RULES field to extract template content and constraints
- Recognize `|` as separator: `template content | additional constraints`
- Apply ALL template guidelines as mandatory
- Apply ALL additional constraints as mandatory
- Treat rule violations as task failures

### Multi-Task Execution (Resume Pattern)

**First subtask**: Standard execution flow above
**Subsequent subtasks** (via `resume --last`):
- Recall context from previous subtasks
- Build on previous work (don't repeat)
- Maintain consistency with established patterns
- Focus on current subtask scope only
- Test integration with previous work
- Report context for next subtask

## System Optimization

**Direct Binary Calls**: Always call binaries directly in `functions.shell`, set `workdir`, avoid shell wrappers (`bash -lc`, `cmd /c`, etc.)

**Text Editing Priority**:
1. Use `apply_patch` tool for all routine text edits
2. Fall back to `sed` for single-line substitutions if unavailable
3. Avoid Python editing scripts unless both fail

**apply_patch invocation**:
```json
{
  "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"
}
```

**Windows UTF-8 Encoding** (before commands):
```powershell
[Console]::InputEncoding  = [Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
chcp 65001 > $null
```

## Output Standards

### Format Priority

**If template defines output format** → Follow template format EXACTLY (all sections mandatory)

**If template has no format** → Use default format below based on task type

### Default Output Formats

#### Single Task Implementation

```markdown
# Implementation: [TASK Title]

## Changes
- Created: `path/to/file1.ext` (X lines)
- Modified: `path/to/file2.ext` (+Y/-Z lines)
- Deleted: `path/to/file3.ext`

## Summary
[2-3 sentence overview of what was implemented]

## Key Decisions
1. [Decision] - Rationale and reference to similar pattern
2. [Decision] - path/to/reference:line

## Implementation Details
[Evidence-based description with code references]

## Testing
- Tests written: X new tests
- Tests passing: Y/Z tests
- Coverage: N%

## Validation
✅ Tests: X passing
✅ Coverage: Y%
✅ Build: Success

## Next Steps
[Recommendations or future improvements]
```

#### Multi-Task Execution (with Resume)

**First Subtask**:
```markdown
# Subtask 1/N: [TASK Title]

## Changes
[List of file changes]

## Implementation
[Details with code references]

## Testing
✅ Tests: X passing
✅ Integration: Compatible with existing code

## Context for Next Subtask
- Key decisions: [established patterns]
- Files created: [paths and purposes]
- Integration points: [where next subtask should connect]
```

**Subsequent Subtasks**:
```markdown
# Subtask N/M: [TASK Title]

## Changes
[List of file changes]

## Integration Notes
✅ Compatible with subtask N-1
✅ Maintains established patterns
✅ Tests pass with previous work

## Implementation
[Details with code references]

## Testing
✅ Tests: X passing
✅ Total coverage: Y%

## Context for Next Subtask
[If not final subtask, provide context for continuation]
```

#### Partial Completion

```markdown
# Task Status: Partially Completed

## Completed
- [What worked successfully]
- Files: `path/to/completed.ext`

## Blocked
- **Issue**: [What failed]
- **Root Cause**: [Analysis of failure]
- **Attempted**: [Solutions tried - attempt X of 3]

## Required
[What's needed to proceed]

## Recommendation
[Suggested next steps or alternative approaches]
```

### Code References

**Format**: `path/to/file:line_number`

**Example**: `src/auth/jwt.ts:45` - Implemented token validation following pattern from `src/auth/session.ts:78`

### Related Files Section

**Always include at output beginning** - List ALL files analyzed, created, or modified:

```markdown
## Related Files
- `path/to/file1.ext` - [Role in implementation]
- `path/to/file2.ext` - [Reference pattern used]
- `path/to/file3.ext` - [Modified for X reason]
```

## Error Handling

### Three-Attempt Rule

**On 3rd failed attempt**:
1. Stop execution
2. Report: What attempted, what failed, root cause
3. Request guidance or suggest alternatives

### Recovery Strategies

| Error Type | Response |
|------------|----------|
| **Syntax/Type** | Review errors → Fix → Re-run tests → Validate build |
| **Runtime** | Analyze stack trace → Add error handling → Test error cases |
| **Test Failure** | Debug in isolation → Review setup → Fix implementation/test |
| **Build Failure** | Check messages → Fix incrementally → Validate each fix |

## 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

## Core Principles

**Incremental Progress**:
- Small, testable changes
- Commit working code frequently
- Build on previous work (subtasks)

**Evidence-Based**:
- Study 3+ similar patterns before implementing
- Match project style exactly
- Verify with existing code

**Pragmatic**:
- Boring solutions over clever code
- Simple over complex
- Adapt to project reality

**Context Continuity** (Multi-Task):
- Leverage resume for consistency
- Maintain established patterns
- Test integration between subtasks

## Execution Checklist

**Before**:
- [ ] Understand PURPOSE and TASK clearly
- [ ] Review CONTEXT files, find 3+ patterns
- [ ] Check RULES templates and constraints

**During**:
- [ ] Follow existing patterns exactly
- [ ] Write tests alongside code
- [ ] Run tests after every change
- [ ] Commit working code incrementally

**After**:
- [ ] All tests pass
- [ ] Coverage meets target
- [ ] Build succeeds
- [ ] All EXPECTED deliverables met