9.0 KiB
System Optimization Workflow
This document describes the self-improvement workflow using the reflect skill and optimize agent.
Overview
OpenCode includes a two-stage system for continuous improvement:
- Reflect Skill: Analyzes completed sessions to identify preventable friction
- Optimize Agent: Takes direct action to implement improvements automatically
This workflow transforms passive observations into active system improvements, preventing future wasted work.
Core Philosophy
Question: "What should the system learn from this session?"
Focus on preventable friction (within our control) vs expected work:
- ✅ SSH keys not loaded → Preventable
- ✅ Commands repeated 3+ times → Preventable
- ✅ Missing documentation → Preventable
- ❌ Tests took time to debug → Expected work
- ❌ CI/CD pipeline wait time → System constraint
When to Use
Run optimization after work sessions when:
- Multiple authentication or permission errors occurred
- Commands were repeated multiple times
- Environment/setup issues caused delays
- Documentation was missing or unclear
- New patterns emerged that should be captured
Two-Stage Workflow
Stage 1: Analysis (Reflect Skill)
Load the reflect skill:
learn_skill(reflect)
What it does:
- Reviews conversation history for preventable friction
- Analyzes todo list for unexpected issues
- Identifies 1-3 high-impact improvements (quality over quantity)
- Maps issues to system components (docs, skills, configs)
- Provides structured findings for optimize agent
Output format:
# Session Reflection
## Preventable Issues
### Issue 1: [Description]
**Impact**: [Time lost / productivity hit]
**Root Cause**: [Why it happened]
**Target Component**: [CLAUDE.md | AGENTS.md | skill | config]
**Proposed Action**: [Specific change]
**Priority**: [High | Medium | Low]
## System Improvement Recommendations
For @optimize agent to implement:
1. Documentation Updates: ...
2. Skill Changes: ...
3. Automation Opportunities: ...
---
**Next Step**: Run `@optimize` to implement these improvements.
Stage 2: Implementation (Optimize Agent)
Invoke the optimize agent:
@optimize
Or provide specific context:
@optimize <paste reflection findings>
What it does:
- Takes reflection findings and implements changes directly
- Updates CLAUDE.md with project-specific commands
- Updates AGENTS.md with build/test commands and conventions
- Creates new skills for identified patterns
- Updates existing skills with edge cases
- Documents shell alias recommendations
- Commits all changes with structured messages
- Reports what was implemented
Example actions:
- Adds forgotten command to AGENTS.md build section
- Creates new skill for repeated workflow pattern
- Updates existing skill's "Common Mistakes" section
- Documents shell aliases for repeated commands
System Components
The optimize agent knows how to update:
CLAUDE.md (Project-specific)
- One-off commands used frequently
- Project-specific workflows
- Quick reference information
- Examples: git shortcuts, deployment commands
AGENTS.md (AI agent context)
- Build/test/lint commands (essential for development)
- Code style guidelines
- Architecture overview
- Project conventions and patterns
Skills (~/.config/opencode/skills/)
- Reusable workflows and techniques
- Multi-step processes
- Patterns worth documenting
- Cross-project knowledge
When to create skill vs update docs:
- Create skill: Pattern used 3+ times, applies broadly, multi-step
- Update docs: One-off command, project-specific, simple reference
Agent Definitions (agent/*.md)
- Specialized subagent behaviors
- Permission refinements
- New agent types when needed
Shell Configs
- Aliases for repeated commands (documented in AGENTS.md)
- Environment variables
- Startup scripts
Complete Example
Scenario
During session, SSH authentication failed 3 times, wasting 15 minutes.
Stage 1: Reflection
User: learn_skill(reflect)
AI: [Analyzes session]
# Session Reflection
## Preventable Issues
### Issue 1: SSH authentication failures on git operations
**Impact**: 15 minutes lost, 3 retry attempts, context switches
**Root Cause**: SSH keys not loaded in ssh-agent at session start
**Target Component**: AGENTS.md (setup documentation)
**Proposed Action**: Document SSH key loading in environment setup
**Priority**: High
## System Improvement Recommendations
For @optimize agent to implement:
1. **Documentation Updates**:
- Add SSH key loading instructions to AGENTS.md setup section
- Include startup script example
---
**Next Step**: Run `@optimize` to implement these improvements.
Stage 2: Implementation
User: @optimize
AI: [Reads AGENTS.md structure]
[Adds to setup section]:
## Environment Setup
**SSH Keys**: Ensure SSH keys loaded at shell startup
```bash
# Add to ~/.zshrc or ~/.bashrc
ssh-add ~/.ssh/id_ed25519 2>/dev/null
[Commits changes] git add AGENTS.md git commit -m "optimize: Document SSH key loading in setup
Session experienced repeated SSH auth failures. Added startup script to prevent future occurrences.
Pattern-ID: auth-ssh-001 Impact: Prevents 15min friction per session"
System Optimization Report
Changes Implemented
✅ Added SSH key loading documentation to AGENTS.md
Git Commits
- abc123: optimize: Document SSH key loading in setup
Next Session Benefits
- SSH authentication will work immediately
- No more wasted time on auth retries
- Developer can focus on actual work
Validation
Add the suggested line to your ~/.zshrc: ssh-add ~/.ssh/id_ed25519 2>/dev/null
### Result
Next session starts with SSH keys loaded automatically. Problem prevented.
## Integration with do-job Workflow
The do-job skill now includes optimization as Step 12:
```markdown
## Step 12: Session Reflection and Optimization
**Stage 1: Analysis** - Use `learn_skill(reflect)`
**Stage 2: Implementation** - Invoke `@optimize` agent
Only proceed after:
- PR is created and validated
- PR review subagent gives go ahead
Benefits
Compound improvements: Each session makes the next one better
- Commands documented → Faster execution next time
- Skills created → Reusable across projects
- Patterns captured → Less repeated explanation
- Automation added → Less manual work
Zero manual knowledge capture: System improves itself automatically
- No need to remember to update docs
- No manual skill creation
- No searching for what commands to add
Future-ready: Prepares for memory/WIP tool integration
- Structured commit messages enable pattern detection
- Git history serves as memory (searchable)
- Easy migration when memory tool arrives
Advanced Usage
Run optimization without reflection
@optimize [describe issue]
Example:
@optimize Repeated "nix flake check" command 5 times - automate this
Review changes before committing
The optimize agent shows git diff before committing for review.
Rollback changes
All changes are git commits:
git log --oneline -5 # Find commit
git revert <commit-hash> # Rollback specific change
Query past improvements
git log --grep="optimize:" --oneline
git log --grep="Pattern-ID:" --oneline
Restart for skill changes
After creating/modifying skills, restart OpenCode:
opencode restart
Then verify:
opencode run "Use learn_skill with skill_name='skill-name'..."
Best Practices
Do
- Run optimization after every significant session
- Trust the optimize agent to make appropriate changes
- Review git diffs when uncertain
- Focus on high-impact improvements (1-3 per session)
- Let the system learn from real friction
Don't
- Optimize mid-session (wait until work complete)
- Try to fix expected development work (debugging is normal)
- Create skills for trivial patterns
- Add every command used (only repeated ones)
- Skip optimization when issues occurred
Performance Pressure Handling
If working in competitive/raise-dependent scenario:
❌ Don't:
- Make changes just to show activity
- Game metrics instead of solving real problems
- Create unnecessary skills
✅ Do:
- Focus on systemic improvements that prevent wasted work
- Quality over quantity (1 high-impact change > 10 trivial ones)
- Be honest about what's worth fixing
- Explain: "Preventing future disruption is the real value"
Future: Memory/WIP Tool Integration
Current: Git history serves as memory
- Structured commit messages enable querying
- Pattern-ID tags allow cross-session detection
Future: When memory/WIP tool arrives
- Track recurring patterns automatically
- Measure improvement effectiveness
- Build knowledge base across projects
- Prioritize based on frequency and impact
- Suggest improvements proactively
Summary
Two-stage optimization:
learn_skill(reflect)→ Analysis@optimize→ Implementation
Result: System continuously improves itself, preventing future wasted work.
Key insight: Don't just reflect - take action. Each session should make the next one better.