Imagine you are a beginner developer.
You have been asked to build a new feature:
“Add authentication to the application.”
You open your AI coding agent, give it the instruction, and a few moments later it changes ten files.
The code works.
But then you start asking yourself:
- Why did it change these files?
- Why did it choose this architecture?
- Why is authentication implemented this way?
- What happens if the database fails?
- Is there a security problem?
- Will this work when the application grows?
This is one of the biggest problems with AI coding tools.
The AI can generate code very quickly, but writing code is only one part of software engineering.
A senior engineer does much more than coding.
Before implementation, they think about requirements, architecture, failure cases, security, performance, testing, and maintainability.
So instead of using AI as a simple code generator, we can design a workflow where different AI agents perform different engineering responsibilities.
This idea is called AI Workflow Orchestration.
What Is AI Workflow Orchestration?
First, we need to understand the difference between an AI agent and an AI workflow.
A simple AI coding agent looks like this:
User Request
↓
AI
↓
Code
You give the AI a task, and it writes the implementation.
But real software engineering looks more like this:
Requirement
↓
Architecture
↓
Planning
↓
Implementation
↓
Testing
↓
Security Review
↓
Performance Review
↓
Code Review
↓
Production Review
The idea behind orchestration is simple:
Instead of asking one AI to do everything, give different responsibilities to different agents and create a process connecting them.
This is similar to how a real engineering team works.
Meet ELOS
A useful way to organize this workflow is the Engineering Learning Operating System, or ELOS.
The idea is not to replace the developer with AI.
Instead, AI acts like a virtual engineering team.
You can think of different agents as different roles:
Product Manager
Software Architect
Tech Lead
Backend Engineer
Code Reviewer
Security Engineer
Performance Engineer
QA Engineer
DevOps Engineer
Engineering Mentor
In a real company, these responsibilities may belong to different people.
In an AI workflow, they can be represented by different agents.
But there is one rule that should never change:
AI can help make engineering decisions, but the developer must understand and approve them.
The goal is not simply to produce code.
The goal is to help the developer learn how the code and architecture work.
1. Start With a Mentor Agent
One of the most useful agents for beginners is a Mentor Agent.
Why?
Because a beginner often thinks:
“What code should I write?”
A senior engineer usually starts with a different question:
“What problem are we actually solving?”
Suppose we are building authentication.
Instead of immediately creating an auth.middleware.ts file, the mentor should first explain the problem.
For example:
A user wants to access:
GET /orders
The backend needs to determine:
Who is making this request?
That leads us to a possible flow:
Client
↓
Authentication Middleware
↓
Controller
↓
Service
↓
Repository
↓
Database
The mentor can then explain why authentication belongs in middleware, why business logic belongs in the service layer, and why database operations belong in the repository layer.
This changes AI from a coding machine into a learning system.
2. Requirements Agent
Now imagine someone says:
“Add user authentication.”
That sounds simple, but it is not a complete requirement.
There are many questions:
How will users log in?
JWT or session?
Will there be access tokens?
Will there be refresh tokens?
Where will tokens be stored?
What happens when a token expires?
What happens with an invalid token?
How will logout work?
Will multiple devices be supported?
Do we need authorization?
A Requirements Agent turns this vague request into something structured.
For example:
Feature:
JWT Authentication
Inputs:
email
password
Outputs:
accessToken
refreshToken
Failure Cases:
invalid credentials
expired token
malformed token
inactive user
Security:
password hashing
token validation
rate limiting
Now the architecture agent has a much clearer problem to solve.
3. Architect Agent
The Architect Agent asks a different question:
“How should this system be designed?”
Instead of immediately writing code, it might propose:
Route
↓
Middleware
↓
Controller
↓
Service
↓
Repository
↓
Database
Then it should explain the responsibility of each layer.
It can also compare different approaches.
For example:
Option A
Put authentication logic directly inside controllers.
Option B
Create reusable authentication middleware.
Then compare them:
Controller Approach
↓
Potential duplication
↓
Harder testing
↓
Harder maintenance
versus:
Middleware
↓
Reusable
↓
Centralized
↓
Easier testing
The important lesson is that architecture is not just about choosing a pattern.
It is about understanding why one approach is better for a specific problem.
4. Architecture Validator
Here is an important improvement.
Even if the Architect Agent proposes a design, we should not automatically assume the design is correct.
So we introduce an Architecture Validator.
Its job is to challenge the proposed architecture.
It asks questions such as:
What happens with concurrent requests?
What happens if the database fails?
What happens if Redis becomes unavailable?
Can duplicate operations happen?
Is the endpoint idempotent?
Are there authorization gaps?
Will this scale?
Is there unnecessary coupling?
Is there a simpler design?
Think of the two agents like this:
Architect:
“This is my design.”
Validator:
“Now let me try to break your design.”
That is much closer to a real engineering review process.
5. Planner Agent
Once the architecture is approved, we need to turn it into implementation steps.
That is the job of the Planner Agent.
For example:
Step 1
Create JWT service
Step 2
Create authentication middleware
Step 3
Protect required routes
Step 4
Update user repository
Step 5
Add tests
Step 6
Run validation
But there is one important detail.
The planner should also explain why each file needs to change.
For example:
auth.service.ts
→ Business logic
auth.middleware.ts
→ Request authentication
jwt.service.ts
→ Token operations
user.repository.ts
→ Database access
auth.test.ts
→ Behavior verification
Now the developer can see the implementation map before any code is written.
6. Implementation Agent
Only now do we start coding.
The Implementation Agent can handle the actual code changes.
But we should give it an important rule:
Do not casually change the approved architecture.
Suppose the agent discovers a problem during implementation.
It should not silently change the design.
Instead, it can report:
BLOCKED
The current architecture does not support X.
Recommended change:
...
Reason:
...
Impact:
...
Then the architecture can be reviewed again.
This prevents a common AI coding problem:
The AI starts with one plan and quietly changes the architecture while implementing.
7. Failure Agent: Try to Break the Code
Now we reach one of the most interesting parts.
The implementation is finished.
A normal coding workflow might say:
“Done.”
But production engineering does not stop there.
We introduce a Failure Agent.
Its job is simple:
Find ways the implementation could fail.
Imagine we are building a payment system.
The Failure Agent might ask:
What if the user clicks Pay twice?
What if the network times out?
What if payment succeeds but the database update fails?
What if a webhook arrives twice?
What if two workers process the same event?
What if Redis goes down?
What if the database transaction fails?
For example:
Scenario:
User clicks Pay twice.
Expected:
Only one charge.
Potential Problem:
Two payment requests are processed independently.
Possible Solution:
Idempotency key.
The agent is not just reviewing the code.
It is trying to break the system mentally.
8. Parallel Review Agents
After implementation, different agents can inspect the same feature from different perspectives.
For example:
Implementation
│
┌───────────┼───────────┐
▼ ▼ ▼
Security Performance QA
│ │ │
└───────────┼───────────┘
▼
Code Review
Security Agent
Looks for things like:
Authentication bugs
Authorization bugs
Injection
Sensitive data exposure
Weak validation
Secrets
Rate limiting problems
Performance Agent
Looks for:
N+1 queries
Missing indexes
Unnecessary API calls
Large payloads
Slow queries
Memory issues
Unnecessary loops
Caching opportunities
QA Agent
Thinks about:
Happy path
Edge cases
Invalid input
Boundary cases
Failure cases
Regression
Concurrency
Code Review Agent
Checks:
Readability
Maintainability
Architecture
Duplication
Complexity
Naming
Tradeoffs
The benefit is simple:
One AI agent may miss something that another perspective catches.
9. Review Aggregator
Now we have another problem.
We may have four reports:
Security Report
Performance Report
QA Report
Code Review
Reading everything manually can become annoying.
So we introduce a Review Aggregator.
It combines all the findings into one prioritized report.
For example:
CRITICAL
1. Authorization vulnerability
HIGH
2. Missing database index
MEDIUM
3. Missing input validation
LOW
4. Naming inconsistency
It can also remove duplicate findings.
Now the developer has one clear review to act on.
10. Automatic Fix and Re-check
Suppose the reviewers identify a missing database index.
The Fix Agent implements the change.
But we should not immediately say:
“Everything is fixed.”
Instead:
Implementation
↓
Review
↓
Problems Found
↓
Fix
↓
Re-check
This creates a feedback loop.
If more issues remain:
Fix
↓
Review
↓
Fix
↓
Review
However, we should avoid infinite loops.
For example:
MAX_REVIEW_ITERATIONS = 3
After three automated attempts, human approval becomes necessary.
This gives us an important safety boundary:
Automation can iterate, but humans remain the final gate.
11. Production Review
A feature can pass tests and still fail in production.
That's why we need a Production Review Agent.
It looks beyond the local development environment.
For example:
Logging
Monitoring
Error handling
Database migrations
Rollback
Environment variables
Scaling
Caching
Observability
Deployment
Failure recovery
Imagine your query takes only 5ms locally.
Everything looks perfect.
But production has millions of rows.
Suddenly the same query may behave very differently because production has different:
Data size
Indexes
Concurrency
Network latency
Query plans
CPU
Memory
So:
“Works on localhost” does not automatically mean “works in production.”
12. Reflection Agent
Now comes the most important part for beginners.
Reflection.
The AI should not simply tell you that the feature is complete.
It should ask you to explain it.
For example:
Why is this logic inside the service?
Why is authentication handled by middleware?
What happens during concurrent requests?
What happens if the database fails?
How would you scale this?
What tradeoff did we make?
What would you change six months from now?
This changes the workflow dramatically.
Because now the goal is not:
“Did AI finish the feature?”
The goal becomes:
“Can I explain the feature without depending on AI?”
If you cannot explain it, the feature is not really complete from a learning perspective.
13. Create an Engineering Journal
After every feature, the workflow can generate a small engineering journal.
For example:
Feature
Problem Solved
Architecture
Design Decisions
Tradeoffs
Production Risks
Mistakes Avoided
New Concepts
Knowledge Gaps
Next Topics
Over time, this becomes your personal engineering knowledge base.
Instead of forgetting what you learned after finishing a project, you gradually build a record of your decisions and lessons.
14. But There Is a Hidden Problem: Token Usage
At this point, you might think:
“This sounds great. Let's create 20 agents!”
But there is a problem.
Context and token usage.
Imagine your repository has 500 files.
If every agent receives the entire repository:
Mentor
→ 500 files
Architect
→ 500 files
Planner
→ 500 files
Implementation
→ 500 files
Security
→ 500 files
Performance
→ 500 files
QA
→ 500 files
We are repeatedly sending information that most agents do not need.
This is inefficient and can reduce the quality of the model's attention because relevant information becomes buried inside unnecessary context.
So orchestration is not only about creating agents.
It is also about managing context intelligently.
15. Give Each Agent Only the Context It Needs
One of the easiest optimizations is:
Do not give every agent the entire repository.
For authentication, the Mentor might need:
README
Architecture docs
Relevant auth files
Database schema
API documentation
The Security Agent might need:
Auth middleware
Auth service
User model
Routes
Configuration
The Performance Agent might need:
Relevant queries
Repository
Schema
Indexes
Performance-sensitive services
Each agent receives the minimum useful context.
That makes the workflow both cheaper and cleaner.
16. Pass Artifacts, Not Entire Conversations
Another common mistake is passing one agent's entire conversation to the next agent.
For example:
Mentor Conversation
↓
Architect
Architect Conversation
↓
Planner
Planner Conversation
↓
Implementation
That can waste a lot of context.
Instead, create structured artifacts.
For example:
architecture.md
Containing:
Decision
Components
Data Flow
API Contract
Database Changes
Tradeoffs
Rejected Alternatives
Risks
Now the Planner only needs to read the artifact.
It does not need the entire conversation that created it.
17. Compress Context
Sometimes a conversation becomes very long.
Suppose the Mentor and developer discussed a feature for 20 minutes.
The Planner probably does not need the complete conversation.
A compact summary may be enough:
Feature:
JWT authentication
Requirements:
...
Architecture:
...
Constraints:
...
Decisions:
...
Open Questions:
...
This is called context compression.
The goal is simple:
Keep the information that matters and discard unnecessary conversation history.
18. Use Different Models for Different Tasks
Another optimization is model routing.
Not every task needs the strongest reasoning model.
Conceptually, you could do something like:
Simple classification
↓
Small model
Formatting
↓
Small model
Test generation
↓
Medium model
Architecture
↓
Strong reasoning model
Security-critical review
↓
Strong model
The important thing is not to blindly choose the cheapest model.
Critical engineering decisions deserve an appropriately capable model.
Cost optimization should never destroy engineering quality.
19. Reuse Stable Project Knowledge
Some project information does not change frequently.
For example:
Coding standards
Architecture principles
Project conventions
Database conventions
API conventions
Instead of explaining these rules in every conversation, store them as reusable project instructions.
For example:
.opencode/
instructions/
architecture.md
security.md
testing.md
coding-standards.md
Then agents can consistently follow the project's existing rules.
20. Add a Context Manager
As workflows become larger, one more role becomes useful:
Context Manager.
Its job is to decide:
What does this agent actually need?
Which files are relevant?
Which previous decisions matter?
What can be summarized?
What can be discarded?
Think of it as the workflow's context-budget gatekeeper.
Instead of blindly giving every agent everything, it decides what information should actually enter the agent's context.
The Complete Workflow
Now we can put everything together.
USER
│
▼
MENTOR
│
▼
REQUIREMENTS
│
▼
ARCHITECT
│
▼
ARCHITECTURE VALIDATOR
│
┌──────┴──────┐
│ │
FAIL PASS
│ │
└─── Revise │
▼
PLANNER
│
▼
CONTEXT MANAGER
│
▼
IMPLEMENTATION
│
▼
FAILURE AGENT
│
┌─────────────┼─────────────┐
▼ ▼ ▼
SECURITY PERFORMANCE QA
│ │ │
└─────────────┼─────────────┘
▼
CODE REVIEW
│
▼
REVIEW AGGREGATOR
│
┌──────┴──────┐
│ │
FAIL PASS
│ │
▼ │
FIX IMPLEMENTATION │
│ │
└──────┐ │
▼ │
RE-CHECK ◄┘
│
▼
PRODUCTION REVIEW
│
▼
HUMAN REVIEW
│
▼
REFLECTION
│
▼
LEARNING SUMMARY
│
▼
ENGINEERING JOURNAL
│
▼
DONE
This is the key idea of ELOS.
The Most Important Rule
After everything we have discussed, one principle matters more than the number of agents.
AI can propose. AI can implement. AI can review. But the engineer must understand and approve.
AI-generated code can look correct.
But:
Looks correct
≠
Is correct
That is why the workflow needs a human quality gate.
Ask yourself:
Can I explain this implementation?
If the answer is no:
Don't accept it yet.
If the answer is yes:
Continue.
What Is the Real Goal?
The future of AI-assisted development is not simply:
“AI writes my code.”
A better vision is:
“AI works with me like an engineering team.”
One agent helps understand requirements.
Another designs architecture.
Another challenges the design.
Another implements the feature.
Another tries to break it.
Security checks security.
Performance checks bottlenecks.
QA checks edge cases.
Code review checks maintainability.
Production review checks real-world risks.
And finally, the AI asks you:
“Do you actually understand what we built?”
That is the difference between using AI to generate code and using AI to become a better engineer.
Final Thought
AI should not make you dependent on generated code.
It should make you better at:
thinking, designing, reviewing, debugging, and making engineering decisions.
The ultimate goal is not to build a system where AI can code without you.
The ultimate goal is to build a system where, over time, you become capable of making senior-level engineering decisions yourself.
That is the real purpose of an Engineering Learning Operating System.
Top comments (1)
We built something similar and nobody flagged handoff contracts as a problem until the third integration broke. The architect agent produces specs with gaps and the implementation agent doesn't ask about them, it just picks something. Two weeks on role design, then another month realizing what each agent actually needs to hand forward. Still finding edge cases.