DEC. 10, 2025
10 Min Read
In “From Developer to Orchestrator,” I explained how AI agent orchestration lets me work on multiple features simultaneously. The concept resonates with people, but I get the same questions:
“What does this actually look like?”“How do you context-switch between four agents without losing your mind?”“What happens when things go wrong?”
Let me walk you through that day. Four different features. Four different complexity levels. All developed in parallel.
The setup: Four parallel workstreams
Here’s what I was working on:
Worktree 1: New feature - lead document management APIs
- Upload API already exists, need to add download/list/update/delete for lead documents
- Implement secure document downloads with presigned URLs
- List documents for a specific lead with category filtering
- Update document file name or category
- Soft delete documents with proper authorization
- Add category column to the database
Worktree 2: QA feedback - contact deletion confirmation
- When deleting a contact from the lead module, UI wasn’t showing confirmation
- Risk of accidental data loss
- Simple fix but needed to match our UX patterns
Worktree 3: UI polish - phone number formatter
- Phone numbers weren’t displaying correctly
- Needed to match Figma designs exactly
- Format: (XXX) XXX-XXXX for US numbers
Worktree 4: Bug fix - users API missing joined ddata
- GET /users/ endpoint returning users but missing related facility data
- Dynamic joins not working as expected
- Blocking the frontend team
How it played out
9:00 AM - Review tickets and launch agents
I’m working on four different things today. For the complex document API feature, I don’t jump straight to implementation. I use the Architect → Plan → Implement pattern:
- An architect agent analyzes the requirements and creates a technical plan
- I review and adjust the plan based on my knowledge
- Save plan to memory directory (.agents/memory/BLAC-789-document-api-plan.md)
- Backend Dev agent implements following the approved plan
This separation is crucial. The architect thinks about system design, security, edge cases, and tradeoffs. The backend dev agent focuses on implementation. I act as the reviewer and decision-maker between the two phases.
For the simpler tickets (phone formatter, confirmation dialog), I skip straight to implementation since the approach is straightforward.
# Terminal 1: Document API - ARCHITECT FIRST, then implementation
cd ~/worktrees/feature-document-api
export COMPOSE_PROJECT_NAME="agent-document-api"
# STEP 1: Architect agent analyzes and creates plan
ROLE: @.agents/profiles/architect.md
CONTEXT:
- @.agents/context/codebase-overview.md
- @.agents/context/conventions.md
- @.agents/context/dependencies.md
TASK: Complete the lead document management API. Upload endpoint already exists,
need to add download, listing, updating, and deletion capabilities for
documents attached to leads.
Requirements:
- GET /v1/leads/{lead_id}/documents - List documents for a lead (with category filter)
- GET /v1/leads/{lead_id}/documents/{id} - Get document metadata
- GET /v1/leads/{lead_id}/documents/{id}/download - Generate presigned S3 URLs for secure downloads
- PATCH /v1/leads/{lead_id}/documents/{id} - Update document file_name or category
- DELETE /v1/leads/{lead_id}/documents/{id} - Soft delete documents
- Add category column to documents table
- Support sort_by and sort_direction query params
- Multi-tenant isolation required (users can only access their org's documents)
- Permission checks (users must have access to parent lead)
- Full audit logging for HIPAA compliance (track all downloads/deletes)
Please analyze this feature and create a technical implementation plan.
# Terminal 2: Frontend agent on confirmation dialog
cd ~/worktrees/fix-contact-delete-confirm
ROLE: @.agents/profiles/frontend-dev.md
CONTEXT:
- @.agents/context/codebase-overview.md
- @.agents/context/conventions.md
- @.agents/context/dependencies.md
WORKFLOW: @.agents/workflows/bug-fix.md
TASK: Fix the contact deletion flow to include a confirmation dialog.
From Jira ticket: Users should see a confirmation dialog before deleting a contact,
similar to the facility deletion flow. Should show the contact name in the message.
Please implement this.
# Terminal 3: Frontend agent on phone formatter
cd ~/worktrees/fix-phone-formatter
ROLE: @.agents/profiles/frontend-dev.md
CONTEXT:
- @.agents/context/codebase-overview.md
- @.agents/context/conventions.md
- @.agents/context/dependencies.md
TASK: Update phone number formatting to match Figma designs.
Components affected: ContactCard, ContactList, LeadDetailView
Expected format: (XXX) XXX-XXXX for US numbers
Please implement this.
# Terminal 4: Backend agent on users API bug
cd ~/worktrees/debug-users-api-joins
ROLE: @.agents/profiles/backend-dev.md
CONTEXT:
- @.agents/context/codebase-overview.md
- @.agents/context/conventions.md
- @.agents/context/dependencies.md
WORKFLOW: @.agents/workflows/bug-fix.md
TASK: BUG - GET /v1/users/ endpoint returns users but the facilities relationship
is not being included in the response.
Expected: User objects should include their associated facilities
Actual: facilities field is null/undefined
Impact: Blocking frontend team from displaying user-facility associations
Investigate SQLModel relationship loading and fix the query.
9:10 AM - Architect completes document API plan
Architect: "I've analyzed the document management API requirements.
Upload is already done, focusing on list/download/update/delete
for lead documents.
API Design:
- GET /v1/leads/{lead_id}/documents - List documents for a lead
- GET /v1/leads/{lead_id}/documents/{id} - Get document metadata
- GET /v1/leads/{lead_id}/documents/{id}/download - Presigned S3 URL (1hr expiration)
- PATCH /v1/leads/{lead_id}/documents/{id} - Update file_name or category
- DELETE /v1/leads/{lead_id}/documents/{id} - Soft delete (set deleted_at)
Query Parameters for List:
- category - Filter by document category (invoice, contract, etc.)
- sort_by - Sort field (uploaded_at, file_name, category)
- sort_direction - asc or desc
- Standard pagination params
Database Changes:
- Add category column to documents table (string, nullable)
- Add deleted_at column (timestamp, nullable) for soft delete
- Add index on (lead_id, category, deleted_at) for efficient queries
Security Concerns:
- CRITICAL: All endpoints must verify user has access to the parent lead
- Multi-tenant isolation via schema-based separation (already handled at DB layer)
- Document IDs use UUIDs (not guessable)
- Must check: user has read/write access to the parent lead based on facility relationships
- Audit log all downloads and deletes for HIPAA
Soft Delete Pattern:
- Don't actually delete from S3 or database
- Set deleted_at timestamp
- Exclude deleted documents from list queries (WHERE deleted_at IS NULL)
- Keep for audit trail and potential recovery
Questions:
1. What are the valid category values? Should we use an enum?
2. Pagination - what page size defaults?
3. Should download generate a new presigned URL each time or cache?"
Me: Reviews plan
"Great analysis. Answers:
1. Start with string - categories will evolve. Add enum later if needed.
2. Default page size 50, max 200
3. Generate new URL each time - simpler, no cache invalidation
One addition: On DELETE, also log who deleted it and from which IP
for audit purposes."
Architect: Updates plan
Me: Approves and saves to .agents/memory/BLAC-789-document-api-plan.md
"Perfect. Backend dev agent, implement this plan."
9:20 AM - Backend dev agent starts implementation based on plan
Backend dev agent working on document API:
# Backend agent begins implementation
ROLE: @.agents/profiles/backend-dev.md
CONTEXT:
- @.agents/context/codebase-overview.md
- @.agents/context/conventions.md
- @.agents/context/dependencies.md
PLAN: @.agents/memory/BLAC-789-document-api-plan.md
WORKFLOW: @.agents/workflows/feature-development.md
The architect has created a technical plan. Please implement the document
management endpoints (list/download/update/delete) following this plan and
the feature development workflow.
9:30 AM - First review cycle begins
Backend dev agent working on document API asks:
Agent: "Following the plan - adding the category column to documents table.
Database migration created. Starting on the list endpoint.
Should I add validation for category values?"
Me: "Not yet - let's keep category as a free-text string for now.
We'll add enum validation later once we see what categories
are actually being used."
9:45 AM - Quick win on phone formatter
Agent: "Phone formatter updated. Applied to ContactCard, ContactList,
and LeadDetailView components."
Me: Reviews code
"Perfect. One thing - add null check for international numbers."
Agent: Updates
Me: "Approved. Done."
First completion: 9:50 AM. One down, three to go.
10:00 AM - Users API bug identified
Agent: "Found the issue. The query is using select(User) but the
relationship isn't configured with selectinload. The facilities
are lazy-loaded, causing N+1 queries."
Me: "Good catch. Use selectinload(User.facilities) in the query."
Agent: Implements fix
"Updated. Also added selectinload for facility_groups since
that was missing too."
Me: Reviews
"Excellent proactive fix. Add a test that verifies facilities
are included in response."
Agent: Adds test
Me: "Perfect. Done."
Second completion: 10:20 AM. Bug fixed and tested.
10:30 AM - Contact deletion needs refinement
Agent: "Confirmation dialog implemented using AlertDialog component."
Me: Reviews code
"Good start. Two changes:
1. Show the contact name in the confirmation message
2. Add error handling if deletion fails"
Agent: Updates implementation
Me: Reviews again
"The error handling is showing a technical error message.
Use our toast notification pattern with a user-friendly message."
Agent: Fixes
"Updated to use useToast with 'Unable to delete contact' message."
Me: "Perfect. Done."
Third completion: 10:50 AM. QA feedback addressed.
11:00 AM - 11:30 AM - Tech lead duties (agents still working)
Here’s where it gets interesting. I need to handle some tech lead responsibilities:
- Review two PRs from other team members
- Answer architecture questions in Slack
- Respond to PM about the timeline for the next sprint’s features
- Quick sync with another team lead about shared infrastructure
In the traditional single-threaded workflow, this context switch would be brutal. I’d lose my place in whatever feature I was implementing, spend 30 minutes handling these responsibilities, then another 15 minutes rebuilding my mental model when I returned to coding.
With agent orchestration, there’s no context to lose. The document API agent is still working through the implementation plan. When I’m ready to review, I just check in on its progress. No mental model to rebuild, no “where was I?” moment.
11:30 AM - Document API review
Agent: "Lead documents API implemented:
- GET /v1/leads/{lead_id}/documents - List with filters (category,
sort_by, sort_direction)
- GET /v1/leads/{lead_id}/documents/{id} - Get metadata
- GET /v1/leads/{lead_id}/documents/{id}/download - Presigned S3 URLs (1hr expiration)
- PATCH /v1/leads/{lead_id}/documents/{id} - Update file_name or category
- DELETE /v1/leads/{lead_id}/documents/{id} - Soft delete with deleted_at
- Added category column to database
- Pagination (default 50, max 200)
- Multi-tenant isolation
- Audit logging
- Tests written"
Me: Deep review - this is the complex one
Checks list endpoint filters - looks good
Checks category filtering - good
Checks soft delete logic - good, using deleted_at with WHERE clause
Checks presigned URL expiration - 1 hour, reasonable
Checks permission logic - wait...
"Security issue: The download endpoint isn't checking if the user
has permission to access the document's parent lead. Need to verify
the user has access to the lead before allowing document download."
Agent: "You're right. Should I check the lead relationship?"
Me: "Yes, use our standard permission pattern:
1. Verify the document belongs to a lead the user has access to
2. Check user's facility relationships allow access to this lead
3. Log the download access for audit trail with user_id and IP"
Agent: Implements comprehensive permission checks
Me: Reviews security logic carefully
"Much better. Now add tests for:
- User without access to parent lead can't download
- Soft-deleted documents aren't returned in list
- Category filtering works correctly
- Audit log is created on successful download and delete"
Agent: Adds security tests
Me: Final review
"Excellent. This is production-ready. Done."
Fourth completion: 12:30 PM. Complex feature shipped with security baked in.
The results
By 12:30 PM on a single day:
- Lead documents API (list/download/update/delete): Architected, implemented with security hardening, tested, complete
- Users API bug: Diagnosed, fixed, tested, complete
- Phone formatter: Updated across all components, complete
- Contact deletion UX: Confirmation dialog added, complete
Four different problems, four different complexity levels, all resolved in parallel.
Multiple terminals and just as many agents, all working simultaneously. This is what orchestration looks like in practice.
What made this possible
The traditional approach would have been:
Day 1 AM: Work on document API
Day 1 PM: Someone reports users API bug - context switch, lose 30 min
Day 2 AM: Finish users API fix
Day 2 PM: QA reports contact deletion issue - context switch again
Day 3 AM: Fix contact deletion
Day 3 PM: Remember phone formatter was on the list...
Day 4: Back to document API, have to rebuild mental model
The orchestrated approach:
All four agents are working simultaneously. My cognitive load wasn’t “keep track of four implementations” - it was “make four architectural/quality decisions.”
When the document API agent needed security guidance, I provided it. When the users API agent found the N+1 query issue, I confirmed the fix. When the contact deletion needed UX polish, I reviewed it.
I was a real-time code reviewer for four parallel streams of development.
The context switching was effortless because I wasn’t context switching between implementations - I was context switching between reviews and decisions.
What this feels like in practice
The experience is fundamentally different from traditional development. Here’s what changed:
Your focus shifts:
- FROM: “How do I implement this?”
- TO: “Is this implementation correct and complete?”
Your mental model changes:
- FROM: Holding implementation details in working memory
- TO: Holding architectural decisions and quality criteria
Your bottleneck moves:
- FROM: How fast can you type and implement
- TO: How quickly can you review and make decisions
Your value increases:
- FROM: Individual contributor shipping features
- TO: Quality multiplier ensuring correctness across multiple streams
The cognitive load is different but not necessarily lighter. You’re making more decisions, catching more edge cases, and ensuring more quality. However, you’re undertaking it across multiple parallel efforts instead of a single sequential stream.
It’s exhausting in a different way. But it’s also exhilarating.
