Doing More with Coding Agents: Lessons from building Opulent

The breakthrough isn’t just bigger models—it’s specialized tools. Morph Fast Apply handles code editing with semantic awareness so your frontier model can focus on reasoning and architecture. Expect ~6× faster edits vs. full-file rewrites and far fewer syntax errors.

• Coding agents vs. assistants: autonomous workflows with verifiable artifacts
• Agent Builder flow: discovery → recommendations → tool setup → configuration
• Real workflows: test coverage, API endpoints, refactors, bug fixes

Serena: Symbol-Level Code Intelligence

While Morph Fast Apply handles precision editing, Serena provides IDE-like code navigation tools that transform how agents understand and manipulate code. Unlike text-based or RAG approaches, Serena uses Language Server Protocol (LSP) to achieve symbol-level understanding—finding functions, classes, and references with semantic accuracy that text search simply cannot match.

Key Capabilities:

• Symbol Discovery: Find functions, classes, variables by name across your entire codebase with find_symbol
• Reference Tracking: Locate all usages of a symbol with find_referencing_symbols—essential for safe refactoring
• Intelligent Editing: Replace function bodies, insert code before/after symbols, all while preserving structure with replace_symbol_body, insert_after_symbol
• Multi-Language Support: Works with Python, TypeScript, JavaScript, Go, Rust, PHP, Java, C++, and 20+ other languages via LSP

Serena + Morph: The Perfect Pairing

Serena and Morph Fast Apply are complementary tools that work together seamlessly:

# Agent Workflow Example:
1. Serena: find_symbol("process_payment") 
   → Locates function across 50+ files in 0.3s

2. Serena: find_referencing_symbols(process_payment)
   → Identifies 12 call sites that need updating

3. Morph: edit_file with Fast Apply
   → Updates function signature at 10,500 tok/sec

4. Serena: replace_symbol_body for unit tests
   → Updates test mocks to match new signature

Result: Safe refactor in seconds, not hours

Integration with Opulent OS Agent Builder

Serena integrates as an MCP (Model Context Protocol) server, making it compatible with Opulent OS Agent Builder, Claude Desktop, VSCode extensions like Cline, and terminal agents like Claude Code. Setup is straightforward:

# Install Serena
uvx --from git+https://github.com/oraios/serena serena start-mcp-server

# Add to Opulent OS Agent Builder
# In agent configuration, add Serena MCP server with context:
--context ide-assistant --project /path/to/your/project

# Agent now has access to 25+ semantic code tools
# while Morph handles the actual editing

Agent Orchestration: Planning and Execution Patterns

Building a coding agent isn't just about tools—it's about orchestration patterns that coordinate thinking, planning, and execution. Frontier agents like Devin and systems like Codex CLI demonstrate proven patterns for breaking complex tasks into manageable steps.

The Planning Phase

Effective coding agents separate planning from execution. Before touching any code, the agent should:

• Gather Context: Use Serena's get_symbols_overview and find_symbol to understand existing code structure
• Identify Dependencies: Map out all files and symbols that will be affected by changes
• Create Explicit Plans: Generate a sequenced todo list with clear success criteria for each step
• Validate Approach: Check for edge cases, breaking changes, and potential rollback strategies

Task Decomposition Principles

Elite coding agents break work into atomic, verifiable steps. Each step should:

• Be Independently Testable: You can run tests/checks after each step to validate progress
• Have Clear Entry/Exit Criteria: "Add type hints to utils.py" is better than "improve code quality"
• Follow Dependency Order: Update interfaces before implementations, base classes before derived
• Shadow, Don't Overwrite: For refactors, create parallel implementations (e.g., AuthService2) and cut over in the final step; this keeps the codebase compiling throughout.
• Enable Rollback: Each step is a logical commit point if something goes wrong

# Good Task Decomposition (Atomic, Verifiable)
1. Add User model with email, password_hash fields
2. Create authentication service with hash/verify methods  
3. Add /login endpoint with JWT generation
4. Add /register endpoint with validation
5. Create auth middleware to verify JWTs
6. Apply middleware to protected routes
7. Add unit tests for auth service (>90% coverage)
8. Add integration tests for login/register flows
9. Update API documentation with auth examples

# Bad Task Decomposition (Vague, Not Verifiable)
1. Set up authentication
2. Make it secure
3. Test everything
4. Deploy

Tool Design Principles: Lessons from Serena

Serena's architecture reveals critical patterns for building agent tools. Great tools share these characteristics:

1. Semantic Over Syntactic Operations

Text-based tools force agents to think in terms of strings and line numbers. Semantic tools let agents think in terms of concepts:

# Text-Based Tool (Brittle) vs Semantic Tool (Robust)
# Serena prefers semantic operations (via LSP) over raw text/regex,
# which makes tools resilient to decorators, annotations, and nesting.

2. Structured Output with Rich Metadata

Serena's tools return JSON with precise location data, not raw text. This enables chaining:

# Serena's find_symbol returns symbol kind, file path, and body location.
# This powers precise follow-ups like: find_referencing_symbols, replace_symbol_body,
# and get_symbols_overview for surrounding context.

3. Built-in Safety and Validation

Production tools anticipate failure modes and provide clear error messages:

• Path Validation: All file operations validate paths are within project boundaries
• Content Limits: Tools have max_answer_chars to prevent context overflow
• Idempotency: Tools like create_file clearly indicate if overwriting existing files
• Rollback Support: Edit operations preserve history for undo functionality

4. Tool Markers for Capabilities

Serena uses marker classes to categorize tools by capability. This enables dynamic tool filtering based on context:

class ToolMarkerSymbolicRead:  # Read-only symbol operations
    pass

class ToolMarkerCanEdit:  # File modification operations
    pass

class ToolMarkerOptional:  # Advanced/optional tools
    pass

# Enable read-only mode by filtering out ToolMarkerCanEdit tools
# Enable safe mode by removing ToolMarkerOptional tools
# Context-specific subsets based on user environment

5. Batch Operations and Speculative Execution

Elite agent tools support batch operations to minimize round-trip latency. Instead of sequential calls, agents can speculatively request multiple resources:

# Sequential (Slow - 3 round trips)
file1 = read_file("src/auth.py")      # Round trip 1
file2 = read_file("src/middleware.py") # Round trip 2  
file3 = read_file("tests/test_auth.py") # Round trip 3

# Batch (Fast - 1 round trip)
files = read_files([
    "src/auth.py",
    "src/middleware.py", 
    "tests/test_auth.py"
])

# Advanced: Include LSP diagnostics inline
files = read_files([
    {"path": "src/auth.py", "includeDiagnostics": true},
    {"path": "src/middleware.py", "includeDiagnostics": true}
])
# Returns: content + errors, warnings, lint suggestions in one call

Speculative reading strategy: When investigating a bug, read all potentially relevant files in one batch rather than discovering them sequentially. Agents that batch read 5-10 files upfront complete tasks 3-5x faster than those making sequential reads.

Validation Loops: Ensuring Correctness at Every Step

The difference between a prototype agent and a production agent is validation discipline. Elite agents verify their work continuously, not just at the end.

The Validation Hierarchy

Effective agents validate in layers, from fastest to most comprehensive:

# Layer 1: Static Analysis (Fastest, ~1-5 seconds)
npm run lint          # or: eslint, flake8, clippy, golangci-lint
npm run typecheck     # or: tsc, mypy, go vet

# Layer 2: Unit Tests (Fast, ~5-30 seconds)  
npm test              # Run tests for changed modules
npm test -- --coverage  # Verify coverage doesn't drop

# Layer 3: Integration Tests (Moderate, ~30-120 seconds)
npm run test:integration  # Test API endpoints, database operations

# Layer 4: Build Verification (Slow, ~60-300 seconds)
npm run build         # Ensure production build succeeds
npm run build:analyze # Check bundle size hasn't regressed

# Layer 5: E2E Tests (Slowest, ~120-600 seconds)
npm run test:e2e      # Full user journey tests

Iterative Fix Loops

When validation fails, agents should follow a systematic debugging process:

1. Isolate the Failure: Run the failing test in isolation to get clean output
2. Read the Error: Parse stack traces, assertion failures, type errors precisely
3. Inspect Context: Use Serena to examine the failing code and its dependencies
4. Form Hypothesis: Based on error + context, predict root cause
5. Make Surgical Fix: Use Morph Fast Apply to patch the exact issue
6. Re-validate: Re-run the failing test + related tests
7. Escalate if Stuck: After 3 attempts, ask user for guidance

Context Management: Working Within Token Limits

Even with 200K+ token contexts, agents must be frugal. Poor context management leads to incomplete analyses and hallucinated fixes.

Strategies for Efficient Context Use

• Start Specific, Expand as Needed: Use get_symbols_overview before reading entire files
• Structured Partial Reads: For large files, read specific line ranges (e.g., 300, 500, 700 line chunks) rather than full content
• Track What You've Read: Serena maintains LinesRead to avoid re-reading unchanged code
• Use Memories for Continuity: Write summaries to .serena/memories/ before starting new conversations
• Chunk Large Operations: Break massive refactors into multiple PRs with clear dependencies

# Efficient Context Pattern for Large Codebases

# Step 1: High-level survey (minimal tokens)
symbols = get_symbols_overview("src/services/")  # ~500 tokens

# Step 2: Targeted symbol lookup (moderate tokens)  
auth_class = find_symbol("AuthService")  # ~200 tokens

# Step 3: Read only required methods (controlled tokens)
auth_method = read_file(
    "src/services/auth.py",
    start_line=auth_class.body_start,
    end_line=auth_class.body_end,
    max_answer_chars=2000  # Hard limit to prevent overflow
)

# Step 4: Find dependencies (targeted search)
references = find_referencing_symbols("AuthService.verify_token")

# Total: ~3,000 tokens vs 50,000+ for reading entire codebase

Memory Systems for Long-Running Tasks

For tasks spanning multiple conversations, Serena's memory system enables continuity:

# Conversation 1: Initial analysis (context at 150K tokens)
write_memory("auth_refactor_plan", '''
## Auth Refactoring Plan

### Completed:
- ✅ Surveyed 23 route handlers in src/api/
- ✅ Identified 8 unprotected endpoints
- ✅ Analyzed existing middleware pattern in src/middleware/auth.py

### In Progress:
- 🔄 Adding @require_auth to user routes (4/8 complete)

### Next Steps:
1. Complete remaining user routes (settings, profile, delete, export)
2. Add integration tests for protected routes  
3. Update API documentation
4. Run full test suite and fix any auth-related failures

### Key Decisions:
- Using decorator pattern (not middleware) for consistency
- JWT expiry set to 24h (matches existing sessions)
- Error responses return 401 with {"error": "Authentication required"}
''')

# Conversation 2: Resume work (minimal startup context)
plan = read_memory("auth_refactor_plan")  # ~500 tokens
# Agent immediately knows: state, decisions made, next steps

Agentic Context Engineering: Evolving Contexts as Playbooks

Recent research from Stanford and SambaNova on ACE (Agentic Context Engineering) (Zhang et al., 2025) reveals a critical insight: contexts should function as comprehensive, evolving playbooks rather than concise summaries. Unlike humans who benefit from brevity, LLMs perform better when provided with long, detailed contexts and can autonomously distill relevance at inference time.

The key innovation is preventing context collapse—a phenomenon where monolithic rewriting by an LLM degrades contexts into shorter, less informative summaries over time. ACE addresses this through:

• Incremental Delta Updates: Represent context as itemized bullets with metadata (IDs, counters). Only update relevant items rather than rewriting everything, avoiding the computational cost and information loss of full rewrites.
• Grow-and-Refine: New insights are appended, existing ones updated in place, with periodic de-duplication via semantic embeddings. Context expands adaptively while remaining interpretable.
• Modular Workflow: Separate Generation (produce reasoning), Reflection (extract lessons from success/failure), and Curation (integrate insights) into distinct roles, preventing the bottleneck of overloading a single model.

ACE demonstrated +10.6% improvement on agent benchmarks and +8.6% on domain-specific tasks, with 86.9% lower adaptation latency than baseline methods. Critically, it works without labeled supervision, leveraging natural execution feedback (test pass/fail, code execution success) to self-improve, a key ingredient for autonomous agents in production.

Cline Memory Bank: Structured Project Context Across Sessions

While ACE demonstrates how to evolve agent memory over time, Cline's Memory Bank provides a practical framework for agents—like Cline itself in VSCode or integrated with Opulent OS—to maintain hierarchical project documentation that transforms them "from a stateless assistant into a persistent development partner." As documented in the Cline Memory Bank guide, this system uses six primary markdown files organized hierarchically: projectbrief.md (core requirements), productContext.md (purpose and UX), activeContext.md (current work focus), systemPatterns.md (architecture decisions), techContext.md (technologies and setup), and progress.md (completed work and remaining tasks).

The power lies in the update triggers: Memory Bank updates occur automatically after significant changes or when patterns are discovered, and can be manually triggered with "update memory bank" to review all files. When triggered manually, the guide emphasizes that "I MUST review every memory bank file, even if some don't require updates"—this disciplined review ensures consistency and prevents information drift. activeContext.md and progress.md receive priority attention during updates since they track the most volatile, work-in-progress information. This hierarchical approach mirrors real project documentation: some files (like projectbrief.md) are nearly immutable foundational documents, while others (like activeContext.md) evolve with each agent session.

DeepWiki: Architectural Context Layer

While Serena handles code-level navigation and Morph handles precision editing, DeepWiki from Cognition provides architectural understanding. It automatically indexes repositories and generates comprehensive wikis with architecture diagrams, source links, and semantic search—giving your agent the "big picture" before diving into implementation details.

Think of DeepWiki as your agent's onboarding documentation. Instead of reading files linearly or making blind searches, your agent can:

• Explore architecture visually: Auto-generated diagrams show component relationships and data flow
• Find relevant context fast: Semantic search across your entire codebase with ranked results
• Understand conventions: Automatically documented patterns, naming conventions, and project structure
• Navigate hierarchically: Organized wiki pages for frontend, backend, utilities, tests, etc.

Steering DeepWiki for Your Agent

For large repositories, you can steer wiki generation with a .devin/wiki.json configuration file:

{
  "repo_notes": [
    {
      "content": "The cui/ folder contains critical UI components. The backend/ folder has API logic. Prioritize documenting authentication flow and data models."
    }
  ],
  "pages": [
    {
      "title": "Authentication System",
      "purpose": "Document auth flow, token management, and session handling"
    },
    {
      "title": "API Endpoints",
      "purpose": "REST API docs with request/response formats",
      "parent": "Architecture Overview"
    }
  ]
}

To steer DeepWiki, provide repo notes highlighting critical areas and define target pages (for example, “Authentication System” or “API Endpoints”) so the generated wiki emphasizes the most important parts of your codebase.

Why This Matters: When your coding agent combines DeepWiki's codebase understanding with Morph Fast Apply's precise edits, you get intelligent modifications that respect your architecture, follow your conventions, and integrate seamlessly with existing code.

Visual Codebase Navigation: Windsurf Codemaps

Windsurf IDE (formerly Codeium) extends the visual context paradigm with Codemaps—interactive graphs showing function/class relationships across your codebase. While DeepWiki provides architectural documentation, Codemaps offer a live, navigable topology map that updates as code changes.

For coding agents integrated with Windsurf, Codemaps serve as a spatial index: instead of searching files linearly, the agent can traverse the dependency graph, identify critical paths between entry points and implementation details, and understand ripple effects of proposed changes. This is particularly powerful for refactoring tasks where understanding "what depends on what" determines safety and correctness.

Step-by-Step Setup

1. Set Up Morph Fast Apply

# Get your Morph API key from https://morph.so
export MORPH_API_KEY="your_key_here"

# Morph integrates with Agent Builder's edit_file tool
# No additional installation required

2. Install Serena for Semantic Code Navigation

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone Serena
git clone https://github.com/oraios/serena
cd serena

# Index your project for faster tool execution
uv run serena project index /path/to/your/project

# Start Serena MCP server (Agent Builder will connect to it)
uv run serena start-mcp-server --context ide-assistant --project /path/to/your/project

3. Configure Agent Builder

In Opulent OS Agent Builder, configure your agent with:

• MCP Servers: Add Serena MCP connection
• Tools: Enable file operations, shell execution, Morph edit_file
• GitHub Integration: Optional MCP for create_pr, add comments

4. System Prompt Template

You are an expert software engineer agent with access to:

1. **Serena Tools** (symbol-level code navigation):
   - find_symbol: Locate functions/classes across the codebase
   - find_referencing_symbols: Find all usages before refactoring
   - get_symbols_overview: Understand file structure
   - replace_symbol_body: Update function implementations

2. **Morph Fast Apply** (via edit_file):
   - Use // ... existing code ... pattern for context
   - Never rewrite entire files - only changed sections
   - Morph handles semantic merging at 10,500 tok/sec

3. **Verification Workflow**:
   - After edits: run linter, type checker, unit tests
   - Fix issues iteratively using Serena + Morph
   - Create PR only when all checks pass

Always use Serena to navigate, Morph to edit, tests to verify.

5. Example Agent Workflow

Task: "Add error handling to all database queries"

1. Serena: find_symbol("execute_query")
   → Found in src/db/query.py:45

2. Serena: find_referencing_symbols(execute_query)
   → 23 call sites across 8 files

3. Morph: edit_file src/db/query.py
   // ... existing code ...
   def execute_query(sql: str) -> Result:
       try:
           return conn.execute(sql)
       except DatabaseError as e:
           logger.error(f"Query failed: {e}")
           raise QueryExecutionError(sql, e) from e
   // ... existing code ...

4. Shell: pytest tests/test_db.py -v
   → 2 failures: tests expect old error types

5. Morph: edit_file tests/test_db.py
   → Update test assertions to expect QueryExecutionError

6. Shell: pytest tests/ --cov=src
   → All passing, coverage 92%

7. GitHub: create_pr with test results and coverage report

1. Locate the target function and all call sites with Serena.
2. Apply a precise edit with Morph to add robust error handling.
3. Run focused tests, update assertions as needed, and re-run with coverage.
4. Create a PR with results once validations pass.

6. Git Workflows and PR Automation

Production coding agents must follow disciplined Git practices. Lessons from Devin's system reveal best practices:

# Complete Git Workflow for Agent Implementation

# 1. Environment sync (CRITICAL - do first)
git fetch --all --prune
git pull --ff-only  # Fail fast if conflicts exist
git status          # Verify clean state

# 2. Create feature branch with timestamp
TIMESTAMP=$(date +%s)
git checkout -b "feature/$TIMESTAMP-add-auth-middleware"

# 3. Implement changes (Serena + Morph workflow)
# ... development work ...

# 4. Run validation suite
npm run lint && npm run typecheck && npm test

# 5. Stage changes carefully (never use git add .)
git add src/middleware/auth.ts
git add src/types/auth.ts  
git add tests/middleware/auth.test.ts

# 6. Review changes before commit
git diff --cached  # MANDATORY: check for secrets, debug code
git status         # Verify only intended files staged

# 7. Commit with descriptive message
git commit -m "feat(auth): add JWT middleware for API protection

- Add verifyToken middleware with RS256 validation
- Include role-based access control (RBAC) support  
- Add comprehensive test coverage (95%)"

# 8. Push to remote
git push -u origin "feature/$TIMESTAMP-add-auth-middleware"

# 9. Create PR with context
gh pr create \
  --title "Add JWT authentication middleware" \
  --body "$(cat << EOF
## Changes
- Implemented JWT middleware with RS256 validation
- Added RBAC support for role-based permissions
- Comprehensive test coverage (95%)

## Testing
```bash
npm run lint   # ✓ Passed
npm run typecheck  # ✓ Passed  
npm test       # ✓ 142/142 passed
npm test -- --coverage  # ✓ 95% coverage
```

## Related Issues
Closes #123

## Checklist
- [x] Tests passing
- [x] Linter passing
- [x] Type checks passing
- [x] Documentation updated
- [x] No secrets in diff

---
Created by Coding Agent
Droid-assisted: Yes
EOF
)" \
  --assignee "@me"

7. PR Description Generation Patterns

Elite agents generate rich PR descriptions that do the heavy lifting for human reviewers. Rather than forcing reviewers to dig through commits or run tests themselves, the agent's PR description explains the objective, catalogs exactly what changed and why, provides evidence that everything was tested, and crucially, includes a rollback plan if production issues surface.

The structure mirrors how experienced developers actually think: What are we solving? (Objective), How did we solve it? (Implementation and security), Did it work? (Testing evidence with actual command outputs), What breaks? (Performance impact and migration requirements), and Can we recover? (Rollback procedure). This isn't just documentation—it's a trust signal that the agent thoughtfully considered the change from end to end.

The key insight from Codecapy's approach: PR descriptions aren't summaries—they're evidence. When your agent attaches command outputs showing all 142 tests passing, coverage at 95.2%, linting passing, and type checks valid, reviewers see concrete proof the change was verified. Pair this with the implementation rationale ("We chose middleware over decorator for consistency with existing patterns") and the PR becomes self-validating. Reviewers focus on architectural soundness and edge cases rather than confirming basic hygiene.

8. Automated Code Review Integration

After your agent opens a PR, automated code review systems like Codex Code Review, GitHub Copilot, or specialized linters provide a second verification layer. This mimics the workflow at companies like Google and Meta: one system builds, another reviews before human involvement.

The workflow is straightforward in practice: Agent 1 creates a PR with full test evidence and clear description. A review system (or Agent 2) analyzes the diff, checks for logic errors, scans for security issues, and identifies missing test cases. If issues exist, the original agent reads the review comments via GitHub APIs, understands the feedback, and applies fixes. This iteration continues until the review passes, then the PR moves to human review already pre-qualified.

Integration options range from simple (enable GitHub Copilot for code review) to sophisticated (chain multiple specialized agents). CodeCapy demonstrates the pattern: after agents generate tests, a separate system validates them in isolated browsers before committing. This separation of concerns—generate, verify, fix—mirrors production systems at scale and ensures reliability. The net effect is that your coding agent operates more like a well-managed development team than a single person: focused specialists doing what they do best, handing off to the next stage when ready, with automated gates preventing half-baked work from advancing.

Next: Integration Patterns

1. Enable Codex Cloud for your repository
2. Navigate to Codex Settings → Code Review
3. Enable "Code review" for your target repositories

Usage Pattern:

# Agent Workflow with Automated Review

# 1. Agent implements feature
agent.execute_task(task_description)
agent.run_validation()  # lint, typecheck, tests
pr = agent.create_pr()
    
# 2. Trigger Codex review
gh_api.add_comment(pr.number, "@codex review")
    
# 3. Wait for Codex review completion
review = wait_for_codex_review(pr.number, timeout=300)
    
# 4. Parse review comments
issues = parse_review_comments(review)
    
if issues.blocking_issues:
    # 5. Agent addresses critical issues
    for issue in issues.blocking_issues:
        agent.fix_issue(
            file=issue.file,
            line=issue.line,
            description=issue.comment,
            suggestion=issue.suggested_change
        )
    
    # 6. Re-validate and push fixes
    agent.run_validation()
    git.push()
    
    # 7. Request re-review
    gh_api.add_comment(pr.number, 
        "Addressed Codex feedback. @codex review")
    
return pr

# Example output:
# PR #342: feat(auth): add JWT middleware
# - Agent implementation: 15 files changed
# - Codex review: 3 blocking issues, 5 suggestions
# - Agent fixes: 3 blocking issues resolved
# - Codex re-review: ✓ All blocking issues resolved

Speculative fix loop: For fully autonomous flows, the agent can read Codex comments via GitHub APIs, apply fixes, re-run validations, and iterate until no blocking issues remain before requesting human review.

1. Agent implements the feature and runs validations.
2. Trigger Codex review by commenting on the PR.
3. Parse review feedback and address blocking issues.
4. Re-run validations, push fixes, and request re-review.