@dtt_siye/atool 1.1.0

package/skills/ai-project-architecture/templates/migration-plan.md

@@ -0,0 +1,433 @@
+# AI Project Architecture Migration Plan
+
+**Project**: [Project Name]
+**Date**: [YYYY-MM-DD]
+**Created By**: AI Project Architecture Skill
+**Target Standard**: PROJECT_STRUCTURE.md (LangGraph 1.0+)
+
+---
+
+## Executive Summary
+
+**Migration Type**: [Full Refactoring | Partial Refactoring | Minor Adjustments]
+
+**Estimated Complexity**: [Low / Medium / High]
+
+**Affected Components**:
+- Agents: [X]
+- Shared Modules: [X]
+- Configuration Files: [X]
+- Tests: [X]
+
+**Rollback Strategy**: Git-based checkpoint after each batch
+
+---
+
+## Current Structure Documentation
+
+### Directory Tree (Before Migration)
+
+```
+[Insert current directory tree here]
+```
+
+### Current File Locations
+
+| File/Directory | Current Location | Type |
+|----------------|------------------|------|
+| [File/Dir name] | [path] | [Agent/Shared/Config/Test] |
+
+### Agent List
+
+| Agent Name | Current Location | Components | Dependencies |
+|------------|------------------|------------|--------------|
+| [agent_1] | [path] | [nodes, services, models, tools] | [Depends on: ...] |
+| [agent_2] | [path] | [nodes, services, models, tools] | [Depends on: ...] |
+
+### Import Dependencies
+
+**Current Import Graph**:
+```
+[Insert dependency graph or list]
+```
+
+**Key Dependencies**:
+- [agent_1] depends on: [shared modules, other agents]
+- [agent_2] depends on: [shared modules, other agents]
+
+---
+
+## Target Structure Mapping
+
+### Migration Mapping (Old → New)
+
+| Type | Old Path | New Path | Notes |
+|------|----------|----------|-------|
+| Agent | `old_path/agent1/` | `agents/agent1/` | [Notes] |
+| Shared | `old_path/utils/` | `apps/utils/` | [Notes] |
+| Config | `old_path/config.py` | `configs/app_config.py` | [Notes] |
+
+### Directory Structure (After Migration)
+
+```
+[Insert target directory tree here]
+```
+
+---
+
+## Migration Sequence
+
+### Phase 1: Shared Components (Foundation)
+
+**Objective**: Migrate shared components first as they have no dependencies on agents.
+
+#### Batch 1.1: Core Infrastructure
+
+**Components**:
+- `core/` directory setup
+  - `core/constants.py`
+  - `core/exception.py`
+  - `core/response.py`
+  - `core/deps.py`
+  - `core/encrypt.py`
+  - `core/lifespan.py`
+  - `core/scheduler.py`
+  - `core/logging/`
+  - `core/middleware/`
+
+**Actions**:
+1. Create `core/` directory structure
+2. Migrate files from old locations
+3. Update all imports
+4. Verify: `python -m py_compile core/**/*.py`
+
+**Entry Criteria**:
+- [ ] Migration plan approved
+- [ ] Old structure documented
+
+**Exit Criteria**:
+- [ ] All core files migrated
+- [ ] Imports updated and verified
+- [ ] No syntax errors
+- [ ] Git commit: "Migrate core infrastructure"
+
+**Rollback**: `git reset --hard HEAD~1`
+
+---
+
+#### Batch 1.2: Application Layer
+
+**Components**:
+- `apps/` directory setup
+  - `apps/protocol.py`
+  - `apps/llms/`
+  - `apps/utils/`
+  - `apps/logs/`
+
+**Actions**:
+1. Create `apps/` directory structure
+2. Migrate files from old locations
+3. Update all imports
+4. Verify: `python -m py_compile apps/**/*.py`
+
+**Entry Criteria**:
+- [ ] Batch 1.1 completed and verified
+
+**Exit Criteria**:
+- [ ] All apps files migrated
+- [ ] Imports updated and verified
+- [ ] No syntax errors
+- [ ] Git commit: "Migrate application layer"
+
+**Rollback**: `git reset --hard HEAD~1`
+
+---
+
+#### Batch 1.3: Configuration
+
+**Components**:
+- `configs/` directory setup
+  - `configs/app_config.py`
+  - `configs/base/`
+  - `configs/deploy/`
+  - `configs/integrations/`
+  - `configs/feature/`
+  - `configs/extra/`
+
+**Actions**:
+1. Create `configs/` directory structure
+2. Migrate configuration files
+3. Update all import references
+4. Verify: `python -c "import configs.app_config"`
+
+**Entry Criteria**:
+- [ ] Batch 1.2 completed and verified
+
+**Exit Criteria**:
+- [ ] All configs migrated
+- [ ] Import references updated
+- [ ] Configuration loads successfully
+- [ ] Git commit: "Migrate configuration"
+
+**Rollback**: `git reset --hard HEAD~1`
+
+---
+
+#### Batch 1.4: Shared Models
+
+**Components**:
+- `models/` directory setup
+  - `models/base.py`
+  - `models/conn.py`
+  - `models/fields.py`
+  - `models/model.py`
+
+**Actions**:
+1. Create `models/` directory
+2. Migrate shared ORM models
+3. Update all imports
+4. Verify: `python -c "import models"`
+
+**Entry Criteria**:
+- [ ] Batch 1.3 completed and verified
+
+**Exit Criteria**:
+- [ ] All shared models migrated
+- [ ] Imports updated
+- [ ] Models import successfully
+- [ ] Git commit: "Migrate shared models"
+
+**Rollback**: `git reset --hard HEAD~1`
+
+---
+
+### Phase 2: Independent Agents
+
+**Objective**: Migrate agents with no dependencies on other agents.
+
+#### Batch 2.1: Agent [agent_name]
+
+**Current Location**: `[old_path]/[agent_name]/`
+**Target Location**: `agents/[agent_name]/`
+
+**Components**:
+- `agents/[agent_name]/nodes/`
+- `agents/[agent_name]/services/`
+- `agents/[agent_name]/models/`
+- `agents/[agent_name]/tools/`
+- `agents/[agent_name]/graph.py` (optional)
+- `agents/[agent_name]/checkpoint.py` (optional)
+- `agents/[agent_name]/views.py` (optional)
+- `agents/[agent_name]/constants.py` (optional)
+
+**Actions**:
+1. Create `agents/[agent_name]/` with required subdirectories
+2. Migrate nodes → `agents/[agent_name]/nodes/`
+3. Migrate services → `agents/[agent_name]/services/`
+4. Migrate models → `agents/[agent_name]/models/`
+5. Migrate tools → `agents/[agent_name]/tools/`
+6. Migrate optional files
+7. Update all import statements
+8. Verify: `python -c "from agents.[agent_name] import *"`
+
+**Entry Criteria**:
+- [ ] Phase 1 (shared components) completed
+- [ ] Agent has no dependencies on other agents
+
+**Exit Criteria**:
+- [ ] All agent components migrated
+- [ ] All imports updated and verified
+- [ ] No syntax errors
+- [ ] Agent imports successfully
+- [ ] Existing tests pass (if any)
+- [ ] Git commit: "Migrate agent [agent_name]"
+
+**Rollback**: `git reset --hard HEAD~1`
+
+---
+
+### Phase 3: Dependent Agents
+
+**Objective**: Migrate agents that depend on already-migrated agents.
+
+#### Batch 3.1: Agent [dependent_agent_name]
+
+**Current Location**: `[old_path]/[dependent_agent_name]/`
+**Target Location**: `agents/[dependent_agent_name]/`
+
+**Dependencies**: [Depends on: agent1, agent2 (already migrated)]
+
+**Components**: [Same structure as Batch 2.1]
+
+**Actions**: [Same as Batch 2.1]
+
+**Special Considerations**:
+- Ensure dependencies (agent1, agent2) are already migrated
+- Update imports to reference new agent locations
+- Test integration with dependent agents
+
+**Entry Criteria**:
+- [ ] All dependencies migrated
+- [ ] Previous batches verified
+
+**Exit Criteria**:
+- [ ] All agent components migrated
+- [ ] All imports updated (including cross-agent imports)
+- [ ] No syntax errors
+- [ ] Agent and dependencies import successfully
+- [ ] Integration tests pass (if any)
+- [ ] Git commit: "Migrate agent [dependent_agent_name]"
+
+**Rollback**: `git reset --hard HEAD~1`
+
+---
+
+## Import Update Strategy
+
+### Global Import Replacements
+
+| Old Import Pattern | New Import Pattern | Files Affected |
+|--------------------|--------------------|----------------|
+| `from old_apps.xyz` | `from apps.xyz` | [List files] |
+| `from old_core.abc` | `from core.abc` | [List files] |
+| `from old_agents.agent1` | `from agents.agent1` | [List files] |
+
+### Import Update Process
+
+For each batch:
+1. Find all imports referencing old paths
+2. Replace with new paths
+3. Verify each file: `python -m py_compile [file]`
+4. Test import chains: `python -c "import [module]"`
+5. Check for circular dependencies
+
+---
+
+## Risk Assessment
+
+### High-Risk Areas
+
+| Component | Risk | Mitigation |
+|-----------|------|------------|
+| [Component name] | [Risk description] | [Mitigation strategy] |
+
+### Potential Issues
+
+1. **Circular Dependencies**
+   - **Risk**: High
+   - **Detection**: Import analysis tools
+   - **Mitigation**: Refactor to remove cycles before migration
+
+2. **Hard-coded Paths**
+   - **Risk**: Medium
+   - **Detection**: String search for old paths
+   - **Mitigation**: Update all references systematically
+
+3. **Test Failures**
+   - **Risk**: Medium
+   - **Detection**: Run tests after each batch
+   - **Mitigation**: Fix tests immediately, don't proceed until fixed
+
+---
+
+## Validation Checkpoints
+
+### After Each Batch
+
+- [ ] All files migrated
+- [ ] All imports updated
+- [ ] No syntax errors (`python -m py_compile`)
+- [ ] Modules import successfully
+- [ ] Existing tests pass
+- [ ] Git commit created
+- [ ] Batch documented in migration log
+
+### After Each Phase
+
+- [ ] All batches in phase completed
+- [ ] Cross-batch integration verified
+- [ ] Phase tests pass
+- [ ] Phase review completed
+
+---
+
+## Rollback Plan
+
+### Per-Batch Rollback
+
+If a batch fails:
+1. Stop immediately
+2. Identify failure point
+3. `git reset --hard HEAD~1` (revert batch commit)
+4. Analyze issue
+5. Fix issue
+6. Re-run batch
+
+### Full Migration Rollback
+
+If entire migration fails:
+1. Stop migration
+2. `git reset --hard [pre-migration-commit]`
+3. Analyze all issues
+4. Revise migration plan
+5. Restart migration
+
+### Rollback Verification
+
+After rollback:
+- [ ] Old structure restored
+- [ ] All tests pass (pre-migration state)
+- [ ] No partial migration artifacts
+- [ ] Working tree clean
+
+---
+
+## Timeline Estimation
+
+| Batch | Estimated Time | Actual Time | Status |
+|-------|----------------|-------------|--------|
+| 1.1: Core Infrastructure | [X] hours | [X] hours | [Pending/In Progress/Completed] |
+| 1.2: Application Layer | [X] hours | [X] hours | [Pending/In Progress/Completed] |
+| 1.3: Configuration | [X] hours | [X] hours | [Pending/In Progress/Completed] |
+| 1.4: Shared Models | [X] hours | [X] hours | [Pending/In Progress/Completed] |
+| 2.1: Agent [agent_1] | [X] hours | [X] hours | [Pending/In Progress/Completed] |
+| ... | ... | ... | ... |
+
+**Total Estimated Time**: [X] hours
+
+---
+
+## Approval & Sign-Off
+
+**Migration Plan Review**:
+
+- [ ] Current structure documented
+- [ ] Target structure defined
+- [ ] Migration sequence logical
+- [ ] Batches appropriately sized
+- [ ] Rollback plan clear
+- [ ] Risks identified with mitigation
+- [ ] Timeline realistic
+
+**Approved By**: [User/Developer]
+**Approval Date**: [YYYY-MM-DD]
+**Scheduled Start**: [YYYY-MM-DD]
+
+---
+
+## Migration Log
+
+*Update this section during migration*
+
+| Date | Batch | Status | Notes |
+|------|-------|--------|-------|
+| [YYYY-MM-DD] | [Batch ID] | [Started/Completed/Failed] | [Notes] |
+| [YYYY-MM-DD] | [Batch ID] | [Started/Completed/Failed] | [Notes] |
+
+---
+
+**Notes**:
+- This plan should be updated as migration progresses
+- Any deviations from plan should be documented
+- All commits should reference this migration plan
+- After migration, proceed to Phase 4 (Code Verification) and Phase 5 (Archive & Test)