diff --git a/MIGRATION.md b/MIGRATION.md
new file mode 100644
index 0000000..6db1692
--- /dev/null
+++ b/MIGRATION.md
@@ -0,0 +1,233 @@
+# Migration Guide
+
+## Repository Consolidation
+
+This guide helps you migrate from the previous repository structure to the new unified `agents` repository.
+
+## What Changed?
+
+### Repository Structure
+
+**Previous Structure** (before consolidation):
+```
+~/.claude/
+├── agents/                    # wshobson/agents (agents only)
+│   ├── backend-architect.md
+│   ├── frontend-developer.md
+│   └── ... (83 agent files in root)
+└── commands/                  # wshobson/commands (separate repo)
+    ├── feature-development.md
+    ├── api-scaffold.md
+    └── ... (workflow and tool files)
+```
+
+**New Unified Structure** (current):
+```
+~/.claude/
+└── agents/                    # wshobson/agents (everything unified)
+    ├── agents/                # All agent definitions
+    │   ├── backend-architect.md
+    │   ├── frontend-developer.md
+    │   └── ... (83 files)
+    ├── workflows/             # Multi-agent orchestrators
+    │   ├── feature-development.md
+    │   ├── security-hardening.md
+    │   └── ... (15 files)
+    ├── tools/                 # Development utilities
+    │   ├── api-scaffold.md
+    │   ├── security-scan.md
+    │   └── ... (42 files)
+    └── README.md
+```
+
+### Key Changes Summary
+
+| What Changed | Before | After |
+|--------------|--------|-------|
+| **Agents location** | Root of `agents/` repo | `agents/agents/` subdirectory |
+| **Workflows location** | Separate `commands/` repo | `agents/workflows/` subdirectory |
+| **Tools location** | Separate `commands/` repo | `agents/tools/` subdirectory |
+| **Repository count** | 2 repositories | 1 unified repository |
+
+## Migration Steps
+
+### Step 1: Update Your Agents Repository
+
+```bash
+cd ~/.claude/agents
+git pull origin main
+```
+
+This will:
+- Move all agent files into the `agents/` subdirectory
+- Add the `workflows/` directory with 15 workflow orchestrators
+- Add the `tools/` directory with 42 development tools
+
+### Step 2: Remove Old Commands Repository (If Installed)
+
+If you previously had the `commands` repository installed:
+
+```bash
+# Check if it exists
+ls ~/.claude/commands
+
+# If it exists, remove it
+rm -rf ~/.claude/commands
+```
+
+The `commands` repository is now deprecated. All functionality has been moved to the unified `agents` repository.
+
+### Step 3: Verify Installation
+
+Check that your directory structure is correct:
+
+```bash
+ls -la ~/.claude/agents
+```
+
+You should see:
+```
+agents/
+workflows/
+tools/
+README.md
+LICENSE
+```
+
+### Step 4: Update Your Workflow
+
+No changes needed for agent invocations, but workflows and tools now use prefixed commands.
+
+## Command Syntax Changes
+
+### Workflows (formerly in commands repo)
+
+**Old Syntax**:
+```bash
+/feature-development implement user authentication
+/commands:feature-development implement user authentication
+```
+
+**New Syntax**:
+```bash
+/workflows:feature-development implement user authentication
+```
+
+### Tools (formerly in commands repo)
+
+**Old Syntax**:
+```bash
+/api-scaffold create user endpoints
+/commands:api-scaffold create user endpoints
+```
+
+**New Syntax**:
+```bash
+/tools:api-scaffold create user endpoints
+```
+
+### Agents (no change)
+
+Agent invocations work exactly as before:
+
+```bash
+"Use backend-architect to design the API"
+"Have security-auditor review this code"
+"Get performance-engineer to optimize this query"
+```
+
+## What Stays the Same?
+
+✅ All 83 agents work identically
+✅ Agent capabilities unchanged
+✅ Direct agent invocation syntax unchanged
+✅ All workflow and tool functionality preserved
+✅ Multi-agent orchestration patterns unchanged
+
+## What's Different?
+
+⚠️ Agent files moved to `agents/` subdirectory
+⚠️ Workflow command prefix changed to `/workflows:`
+⚠️ Tool command prefix changed to `/tools:`
+⚠️ Commands repository deprecated
+
+## Common Migration Issues
+
+### Issue: "Command not found" errors
+
+**Symptom**: `/feature-development` no longer works
+
+**Solution**: Use the new prefix syntax:
+```bash
+/workflows:feature-development
+```
+
+### Issue: Agents not loading
+
+**Symptom**: Claude Code doesn't recognize agents
+
+**Solution**:
+1. Verify structure: `ls ~/.claude/agents/agents/`
+2. Restart Claude Code
+3. Check for errors in Claude Code logs
+
+### Issue: Both repos installed
+
+**Symptom**: Duplicate commands showing up
+
+**Solution**: Remove the old commands repository:
+```bash
+rm -rf ~/.claude/commands
+```
+
+## Testing Your Migration
+
+After migrating, test these commands to verify everything works:
+
+### Test Workflows
+```bash
+/workflows:feature-development test feature
+/workflows:security-hardening scan project
+```
+
+### Test Tools
+```bash
+/tools:api-scaffold create test endpoint
+/tools:code-explain describe this function
+```
+
+### Test Agents
+```bash
+"Use backend-architect to review the architecture"
+"Have frontend-developer suggest improvements"
+```
+
+## Rollback Instructions
+
+If you need to rollback to the previous structure:
+
+```bash
+cd ~/.claude/agents
+git checkout <previous-commit-hash>
+```
+
+Or reinstall the old commands repository:
+
+```bash
+cd ~/.claude
+git clone https://github.com/wshobson/commands.git
+```
+
+Note: The `commands` repository is deprecated and won't receive updates.
+
+## Need Help?
+
+- **Documentation**: [README.md](README.md)
+- **Issues**: https://github.com/wshobson/agents/issues
+- **Claude Code Docs**: https://docs.anthropic.com/en/docs/claude-code
+
+## Timeline
+
+- **Before**: Two separate repositories (`agents` + `commands`)
+- **Now**: One unified repository (`agents` with subdirectories)
+- **Future**: Plugin marketplace integration (coming soon)
diff --git a/README.md b/README.md
index 6b35d86..0910dc7 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,16 @@
 
 A comprehensive production-ready system combining **83 specialized AI agents**, **15 multi-agent workflow orchestrators**, and **42 development tools** for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
 
+> **⚠️ Major Update**: This repository has been restructured. If you're upgrading from a previous version, see the [Migration Guide](#migration-guide) below.
+
+## Quick Links
+
+- [Installation](#installation) - New users start here
+- [Migration Guide](#migration-guide) - **Upgrading from previous version? Read this first**
+- [Workflow Commands](#workflow-commands) - Multi-agent orchestration
+- [Development Tools](#development-tools) - Single-purpose utilities
+- [Agent Categories](#agent-categories) - All 83 agents organized by domain
+
 ## Overview
 
 This unified repository provides everything needed for intelligent automation and multi-agent orchestration across modern software development:
@@ -17,6 +27,8 @@ This unified repository provides everything needed for intelligent automation an
 
 ## Installation
 
+### New Installation
+
 ```bash
 cd ~/.claude
 git clone https://github.com/wshobson/agents.git
@@ -24,6 +36,17 @@ git clone https://github.com/wshobson/agents.git
 
 All agents, workflows, and tools will be automatically available to Claude Code.
 
+### Updating from Previous Version
+
+If you previously had the `agents` repository installed:
+
+```bash
+cd ~/.claude/agents
+git pull origin main
+```
+
+**Important**: The repository structure has changed. All agent files have been moved to the `agents/` subdirectory. Claude Code will automatically detect the new structure.
+
 ## Repository Structure
 
 ```
@@ -249,9 +272,98 @@ debugger → [backend-architect | frontend-developer | devops-troubleshooter]
 feature-development → security-auditor → performance-engineer → Validated release
 ```
 
-## Migration from Commands Repository
+## Migration Guide
 
-This repository now includes all functionality from the separate `commands` repository. The commands repo is being deprecated in favor of this unified structure. All workflows and tools are now available in a single installation.
+### What Changed?
+
+**Major Update**: This repository has been restructured to consolidate all Claude Code extensions in one place:
+
+1. **Repository Structure**: All agents moved from root to `agents/` subdirectory
+2. **Workflows Added**: 15 multi-agent workflow orchestrators (previously in separate `commands` repo)
+3. **Tools Added**: 42 development utilities (previously in separate `commands` repo)
+4. **Unified Experience**: Everything now accessible from a single repository
+
+### Migrating from Commands Repository
+
+If you previously used the separate `commands` repository (`wshobson/commands`):
+
+**Before** (old structure):
+```
+~/.claude/
+├── agents/              # Agents repository
+│   └── *.md files
+└── commands/            # Commands repository (DEPRECATED)
+    └── *.md files
+```
+
+**After** (new unified structure):
+```
+~/.claude/
+└── agents/              # Unified repository
+    ├── agents/
+    ├── workflows/
+    └── tools/
+```
+
+#### Migration Steps
+
+1. **Update the agents repository**:
+   ```bash
+   cd ~/.claude/agents
+   git pull origin main
+   ```
+
+2. **Remove the old commands repository** (if installed):
+   ```bash
+   rm -rf ~/.claude/commands
+   ```
+
+3. **Verify installation**:
+   ```bash
+   ls ~/.claude/agents
+   # Should show: agents/ workflows/ tools/ README.md
+   ```
+
+4. **Update your workflow**:
+   - Old: `/feature-development` or `/commands:feature-development`
+   - New: `/workflows:feature-development`
+
+   - Old: `/api-scaffold` or `/commands:api-scaffold`
+   - New: `/tools:api-scaffold`
+
+### What Stays the Same?
+
+- All 83 agents work exactly as before (no command syntax changes)
+- Agent definitions and capabilities unchanged
+- Direct agent invocation still works: "Use backend-architect to..."
+
+### Breaking Changes
+
+⚠️ **Command Invocation Syntax**:
+- Workflows now use `/workflows:` prefix instead of just `/`
+- Tools now use `/tools:` prefix instead of just `/`
+
+**Old syntax** (deprecated):
+```bash
+/feature-development implement auth
+/api-scaffold create endpoints
+```
+
+**New syntax** (current):
+```bash
+/workflows:feature-development implement auth
+/tools:api-scaffold create endpoints
+```
+
+### Need Help?
+
+For detailed migration instructions and troubleshooting, see [MIGRATION.md](MIGRATION.md).
+
+If you encounter issues after migrating:
+1. Verify directory structure: `ls -la ~/.claude/agents`
+2. Check git status: `cd ~/.claude/agents && git status`
+3. Review common issues in [MIGRATION.md](MIGRATION.md)
+4. Report issues at: https://github.com/wshobson/agents/issues
 
 ## Contributing