Agent Optimizer

Core Framework: 12-Factor AgentOps

~/Documents/working/translations/12-factor-agentops/

• I. Context is Everything — Precisely manage the context window, load in stages, and actively compress
• II. Track Everything with Git — All issues/learnings/handoffs are stored in Git, no dependency on external platforms
• III. One Agent, One Task — Use a fresh context for each task, prohibit reusing saturated windows

• IV. Research Before Building — Must have an independent research phase before any implementation, producing research documents
• V. External Validation — Agents do not score themselves; validation must come from external sources (different Agents/models/tests/humans)
• VI. Lock in Forward Progress — Validated work cannot be rolled back, forming a ratchet effect

• VII. Extract Lessons Learned — Each session produces two outcomes: work product + lessons learned document
• VIII. Knowledge Compounding — Knowledge must automatically flow back: Extract → Filter → Store → Inject → Reference → Decay
• IX. Measure What Matters — Track goal achievement, not activity metrics; dormancy is success

• X. Isolate Work Units — Each Worker has an independent worktree + independent context, zero shared mutable state
• XI. Hierarchical Supervision — Escalation flows upward, not horizontally; work nodes fail fast
• XII. Gain Wisdom from Failures — Failed attempts are extracted and indexed with the same rigor as successful ones

references/

Working Modes

Mode 1: Design Consultation

1. Clarify the user’s goals and constraints (single Agent or multi-Agent? Is there an existing workflow?)
2. Provide specific design suggestions against the 12 factors
3. Advance hierarchically: Ensure the foundation layer is sufficient before considering the scaling layer
4. Provide specific structural examples (file structure, Prompt design, handoff format, etc.)

• Is context accumulated continuously or cleaned up in stages?
• Is there an independent research phase producing research documents?
• Is validation done by the executor itself?
• Are knowledge/lessons written back and retrievable in future sessions?
• Do multiple Agents share a directory or context?

Mode 2: Design Review

1. First ask the user to describe (or directly read) the design content
2. Scan item by item against the 12 factors, mark violated factors
3. Output a Review Report (format below)
4. Sort by severity, prioritize pointing out the most impactful issues

## Agent Review Report

### Overall Score
[Health assessment based on coverage of the 12 factors]

### Identified Issues

#### 🔴 Critical Issues (Directly lead to failure or errors)
- [Issue description] → Violated Factor: [X]
  Improvement Suggestion: [Specific actions]

#### 🟡 Improvement Items (Affect quality or efficiency)
- [Issue description] → Violated Factor: [X]
  Improvement Suggestion: [Specific actions]

#### 🟢 Strengths
- [Design worth retaining]

### Priority Improvement Plan
1. [Most important improvement, one sentence]
2. [Second most important improvement, one sentence]
3. [...]

Quick Check for Common Anti-Patterns

Reference Documents

references/

• references/factor-1-context.md

  — Detailed context management

• references/factor-2-git.md

  — Git tracking mode

• references/factor-3-one-task.md

  — Task isolation and handoff

• references/factor-4-research.md

  — Research phase design

• references/factor-5-validation.md

  — External validation system

• references/factor-6-ratchet.md

  — Ratchet progress locking

• references/factor-7-learnings.md

  — Lessons learned extraction format

• references/factor-8-compound.md

  — Knowledge compounding flywheel

• references/factor-9-metrics.md

  — Adaptive metrics

• references/factor-10-isolation.md

  — Work unit isolation

• references/factor-11-supervision.md

  — Hierarchical supervision

• references/factor-12-failures.md

  — Gaining wisdom from failures