Agent System Migration Guide
Migration Summary (2025-09-21)​
Successfully consolidated 50+ agent files into 10 core agents.
What Changed​
Before: Scattered Agents​
- 17 files in
./agents/(UPPERCASE_NAMES.md) - 8 files in
./.codi/agents/(YAML format) - 13 files in
./.claude/agents/(specialized) - 40+ scripts in
./.codi/scripts/ - Multiple formats, naming conventions, duplicates
After: Unified Structure​
agents/
├── coditect/ # 10 core CODITECT agents
├── claude-subagents/ # Claude specialists for delegation
├── tools/ # 3 consolidated tools
├── templates/ # Standardized template
├── guides/ # Usage guides
├── README.md # Complete documentation
└── migration-guide.md # This file
Agent Name Mapping​
| Old Name | New Name | Location |
|---|---|---|
| ORCHESTRATOR_WORKFLOW | orchestrator | agents/coditect/ |
| orchestrator-code-review | orchestrator | (merged) |
| agent-orchestrator.yaml | orchestrator | (merged) |
| RUST_DEVELOPER_SPECIALIST | rust-developer | agents/coditect/ |
| rust-expert-developer | rust-developer | (merged) |
| agent-coder-senior-architect | rust-developer | (merged) |
| FRONTEND_SPECIALIST | frontend-developer | agents/coditect/ |
| frontend-react-typescript-expert | frontend-developer | (merged) |
| DATABASE_SPECIALIST | database-specialist | agents/coditect/ |
| database-schema-specialist | database-specialist | (merged) |
| QA_REVIEWER_PRIMARY | qa-reviewer | agents/coditect/ |
| qa-documentation-reviewer | qa-reviewer | (merged) |
| SECURITY_SPECIALIST | security-specialist | agents/coditect/ |
| TESTING_SPECIALIST | testing-specialist | agents/coditect/ |
| CLOUD_SPECIALIST + DEPLOYMENT_SPECIALIST | cloud-architect | agents/coditect/ |
| MONITORING_SPECIALIST | monitoring-specialist | agents/coditect/ |
| AI_SPECIALIST | ai-specialist | agents/coditect/ |
Workflow Updates​
Starting Sessions​
Old Way:
# Multiple scripts to remember
source .codi/scripts/agent-session-start.sh
.codi/scripts/set-orchestrator-session.sh
New Way:
# Single interactive starter
agents/tools/start-session.sh
Viewing Agent Details​
Old Way:
# Hunt through multiple directories
cat ./agents/ORCHESTRATOR_WORKFLOW.md
cat .claude/agents/orchestrator-code-review.md
New Way:
# Single location, consistent names
cat agents/coditect/orchestrator.md
Quick Logging​
Old Way:
# Long paths
.codi/scripts/codi-log-ai.sh "message" "ACTION"
New Way:
# Short helper
agents/tools/agent-log.sh "message" "ACTION"
Archived Locations​
All old agent files have been archived to:
.archived/agent-consolidation-20250921/
You can still access them if needed, but they should not be used going forward.
Benefits Realized​
- 83% File Reduction: From 50+ files to ~13 total
- Consistent Naming: All lowercase-hyphenated
- Single Format: Standardized markdown template
- Clear Hierarchy: CODITECT primary, Claude as sub-agents
- Better Discovery: Everything in one place
- Simplified Tools: 3 scripts instead of 40+
Migration Checklist​
- Update any personal scripts to use new paths
- Review new agent definitions in
agents/coditect/ - Test session start with
agents/tools/start-session.sh - Update any documentation referencing old agents
- Remove references to archived directories
Questions?​
- See
agents/README.mdfor complete guide - Check
agents/templates/agent-template.mdfor structure - Review
CODITECT-CLAUDE-AGENT-INTEGRATION.mdfor delegation patterns