How It Works
Architect Mode splits complex editing tasks into two phases:Architect Phase: Planning
A strong model (Claude Opus, GPT-4) analyzes your request and produces a structured JSON plan with file-by-file edit instructions.
Why Two Models?
This pattern offers several advantages:- Better planning - Strong models see the full context and make better architectural decisions
- Lower cost - Expensive models only plan; cheap models do the repetitive editing work
- Clearer reasoning - The structured plan is saved in conversation history
- Easier review - You can review the plan before execution begins
Enabling Architect Mode
Via Configuration
Set architect and editor models in.loom.toml:
.loom.toml
Via Session API
Enable architect mode for a session:Via CLI
Architect mode is not yet exposed in the CLI (coming in Phase 4).Via Web UI
A mode toggle will be added to the LiveView UI in Phase 4.The Planning Phase
The architect model receives full context:- System prompt with project path and instructions
- Decision graph context (recent goals and decisions)
- Repository map (file structure and symbols)
- Conversation history
- All tool definitions
Plan Structure
Each plan item has four required fields:- file - Relative path from project root
- action - One of:
create,edit,delete - description - Human-readable summary of what this step does
- details - Precise instructions for the editor model
The Execution Phase
The editor model receives each plan item sequentially:Apply Changes
The editor uses
file_edit, file_write, or shell commands to make the specified changes.Tool Restrictions
The editor model only has access to file-related tools:file_readfile_editfile_writedirectory_list
Example Session
User Request
Architect Response
The architect model produces a plan:Editor Execution
The editor model executes each step:When to Use Architect Mode
Good Use Cases
Large Refactorings
Large Refactorings
When changes span multiple files and require architectural thinking.Example: Extracting a subsystem into a separate OTP application
Framework Migrations
Framework Migrations
Migrating from one library to another (e.g., Phoenix PubSub → Broadway).Example: Replacing hand-rolled auth with Guardian or Pow
New Feature Scaffolding
New Feature Scaffolding
Creating the initial structure for a complex feature.Example: Adding a new bounded context with multiple schemas
Coordinated Updates
Coordinated Updates
Changes that must happen together across multiple modules.Example: Updating a core data type and all its consumers
When NOT to Use Architect Mode
Configuration Details
Model Selection
The architect and editor models can be configured independently:.loom.toml
Recommended Combinations
- Balanced
- Budget
- OpenAI
Implementation Details
The architect mode logic lives inlib/loom/session/architect.ex:
lib/loom/session/architect.ex:1 for the full implementation.
PubSub Events
Architect mode broadcasts events for LiveView UI updates:Limitations
Editor Can’t Ask Questions
The editor model follows the plan mechanically. If the plan is unclear or wrong, the editor can’t ask for clarification—it will just fail or produce incorrect results. Mitigation: Write detailed instructions in the plan’sdetails field.
No Mid-Flight Adjustments
If step 3 reveals a problem with step 5, the editor still executes step 5 as written. Mitigation: Review the plan before execution begins (future feature).Tool Restrictions
The editor only has file tools. It can’t run tests, search the codebase, or inspect runtime behavior. Mitigation: Switch back to normal mode for verification:Best Practices
Be Specific in Requests
Vague requests produce vague plans:Review the Plan
The plan is saved in conversation history. Read it before asking follow-up questions.Use for Multi-File Changes
Architect mode shines when changes span 3+ files:- ✅ Adding a new feature with controller, context, schema, tests
- ✅ Refactoring a subsystem across multiple modules
- ❌ Fixing a typo in one file
- ❌ Adding a single function
Start Small
Test architect mode on smaller tasks first to understand its strengths and limitations.Troubleshooting
Plan Parsing Errors
Error:Failed to parse architect plan: Invalid JSON
Cause: The architect model didn’t return valid JSON.
Solution:
- Try a different architect model (Opus > Sonnet > GPT-4)
- Simplify your request
- Check for model API issues
Editor Goes Off-Script
Issue: The editor makes changes not in the plan. Cause: The plan’sdetails field was too vague.
Solution: Restart in normal mode and be more explicit:
Partial Failures
Issue: Steps 1-3 succeed, step 4 fails, steps 5-6 are skipped. Cause: Editor encountered an error (file not found, invalid syntax, etc.). Solution:- Review the execution results
- Fix the issue manually or ask Loom to fix it
- Re-run the remaining steps
Future Enhancements
Plan Review Step
Pause between planning and execution to review/edit the plan.Adaptive Execution
Editor reports issues back to architect for plan adjustments.Tool Expansion
Allow editor to run tests, check compilation, or search for references.Plan Templates
Save and reuse successful plans for similar tasks.Next Steps
Sub-Agents
Spawn lightweight agents for parallel exploration
Model Selection
Choose the right models for your workflow