Migration Orchestration - AAGMF Workflow Architecture

Section 1: The "Plan, Implement, Validate" Macro-Lifecycle

Phase 1: Plan

Agent: MigrationArchitect agent Output: Master JSON plan Tools: parse-tbl, parse-pof, godot-parser

The MigrationArchitect analyzes assets (.pof, .tbl) and C++ code, producing a master JSON plan that breaks down the migration into discrete, atomic tasks. This phase follows the Reduce & Delegate philosophy by delegating complex parsing to deterministic skills.

Phase 2: Implement

Agents: Engineer agents (GDScriptEngineer, AssetPipelineEngineer) Output: Generated code and assets Tools: generate-resource, convert-pof-to-glb, generate-importer, generate-limboai-tree

Engineer agents execute discrete tasks from the plan using specialized skills for code generation, asset conversion, and resource creation. Each agent works in isolation with clean contexts.

Phase 3: Validate

Agent: QAEngineer agent Output: Validation results and structured failure data Tools: run-gdlint, run-gdunit4-tests

The QAEngineer validates the work using deterministic validation skills, returning structured JSON failure data for the automated remediation loop. All validation output must be structured JSON, not raw text.

Section 2: The Specialized Agentic Team

The Five Core Sub-Agents

Agent Interaction Patterns

• Sequential Flow: Architect → Analyst → Engineers → QA
• Feedback Loops: QA → Engineers (remediation)
• Human-in-the-Loop: Critical decisions and final review
• Parallel Processing: Multiple engineers can work simultaneously on different tasks

Agent Boundaries and Responsibilities

Migration Architect:

• Analyzes legacy C++ codebase and WCS assets
• Creates structured JSON migration plan
• Defines task dependencies and priorities
• Breaks complex migration into atomic tasks

C++ Code Analyst:

• Performs deep analysis of C++ logic patterns
• Creates GDScript translation specifications
• Identifies architectural patterns to migrate
• Documents behavioral requirements

GDScript Engineer:

• Implements custom resource classes
• Creates game logic scripts
• Writes AI behavior trees
• Generates corresponding unit tests

Asset Pipeline Engineer:

• Converts 3D models and textures
• Creates editor import plugins
• Implements composite asset solutions
• Handles material and animation migration

QA Engineer:

• Validates code quality and style
• Runs automated test suites
• Generates structured failure reports
• Enables automated remediation loop

Section 3: Markdown-Based State Management

Task Contract Files

Tasks are managed as individual markdown files in .claude/workflow/tasks/ following this structure:

---
id: TASK-001
title: "Convert Scimitar ship stats to Godot Resource"
status: in_progress
assignee: GDScriptEngineer
priority: 2
dependencies: [TASK-000]
estimated_effort: "2 hours"
tags: ["resource", "ship-stats"]
created: "2025-01-15T10:30:00Z"
---

## Description
The MigrationArchitect has identified ship stats in ships.tbl that need conversion to Godot Custom Resource format. This task involves:

1. Parse ships.tbl to extract Scimitar statistics
2. Generate ShipStats.gd resource class
3. Create corresponding unit tests
4. Validate implementation with gdUnit4

Source: `source/data/tables/ships.tbl`
Target: `target/resources/ship/ShipStats.gd`

## Acceptance Criteria
- [ ] ShipStats class extends Resource with proper @export variables
- [ ] All numeric types correctly mapped (float, int)
- [ ] String fields properly handled and sanitized
- [ ] Test coverage > 90% for generated class
- [ ] Passes gdlint validation with zero violations
- [ ] All gdUnit4 tests pass

## Implementation Details
### Data Mapping
- `$Mass:` → `mass: float`
- `$Armor:` → `armor: float`
- `$Hitpoints:` → `hitpoints: int`
- `$Ship Class:` → `ship_class: String`

### Validation Requirements
- Use run-gdlint for style validation
- Use run-gdunit4-tests for functional testing
- Structured failure data must be appended to Feedback section

## Feedback
[Structured failure data from validation gets appended here]

Critical: The ## Feedback Section

This section serves as the communication bus for the automated remediation loop. When QA skills return structured failure data, it is appended here for the original engineer to act upon.

Task State Lifecycle

1. pending: Not yet started, in backlog
2. in_progress: Currently being worked on by assigned agent
3. completed: Implementation finished, ready for validation
4. validation_requested: Automated validation triggered
5. validation_in_progress: QA Engineer running tests
6. failed: Validation failed, remediation needed
7. validated: All tests pass, task complete
8. blocked: Waiting for dependencies or human input

Task Priority Levels

• 1 (Critical): Blocks other work, must be done first
• 2 (High): Important for core functionality
• 3 (Medium): Features and enhancements
• 4 (Low): Nice-to-have improvements

Section 4: The Event-Driven "Nervous System"

The workflow is automated via hooks that execute scripts in the skills' directories. These hooks implement the event-driven architecture.

Hook 1: UserPromptSubmit (Plan Materialization)

Trigger: MigrationArchitect completes JSON plan Action: Runs scripts/materialize_plan.py --input plan.json --output .claude/workflow/tasks/ Purpose: Parses the Architect's JSON and creates all individual .md task files

Input: Master JSON plan with tasks, dependencies, and assignments Output: Directory of markdown task files with proper frontmatter

Hook 2: SubagentStop (Validation Trigger)

Trigger: Engineer agent marks task complete (status: completed) Action: Runs scripts/trigger_validation.sh --task-id TASK-001 Purpose: Immediately chains the QAEngineer after an Engineer completes a task

Process:

1. Update task status to validation_requested
2. Queue task for QAEngineer
3. Notify QAEngineer of new validation task

Hook 3: PostToolUse (Quality Gate)

Trigger: QAEngineer executes any validation tool Action: Runs scripts/check_qa_status.sh --task-id TASK-001 --exit-code $? Purpose: Checks the QA skill's exit code and initiates the "Automated Remediation Loop" on failure

Exit Code Handling:

• 0: Success → Update task status to validated
• 1: Validation failure → Parse structured output and append to Feedback section
• 2: System error → Log error and flag for human review

Hook 4: TaskAssignment (Work Distribution)

Trigger: New tasks created or dependencies resolved Action: Runs scripts/assign_tasks.py --agent GDScriptEngineer --count 3 Purpose: Distributes available tasks to appropriate agents based on workload and skills

Section 5: Skill Integration Patterns

How Skills Connect Agents

• Plan Phase Skills: parse-tbl, parse-pof, godot-parser (used by MigrationArchitect)
• Implement Phase Skills: generate-resource, convert-pof-to-glb, generate-importer (used by Engineers)
• Validate Phase Skills: run-gdlint, run-gdunit4-tests (used by QAEngineer)

The Unified GodotProject API

All skills are methods on the GodotProject Python wrapper class following the "Gold Standard":

# Engineers don't call Python scripts directly
# SKILL.md files instruct agents to use GodotProject methods

# Instead of: !python scripts/parse_pof.py model.pof
# Use: project.parse_pof("model.pof")

# Instead of: !python scripts/run_gdunit4_tests.py
# Use: project.run_tests()

Progressive Disclosure in Action

1. Discovery: Agents see only skill names and descriptions in metadata
2. Invocation: Full SKILL.md loads when semantic match occurs
3. Execution: Scripts/resources load on-demand for complex tasks
4. Results: Structured JSON output enables automated processing

Section 6: Error Handling and Recovery

The Automated Remediation Loop

1. QA skill detects failure and returns structured JSON
2. PostToolUse hook captures the failure data
3. Script appends failure data to task's ## Feedback section
4. Task is reassigned to original Engineer agent
5. Engineer receives explicit, structured fix instructions
6. Loop continues until validation passes

Structured Feedback Format

## Feedback

### GDLint Violations Detected (2 errors)
```json
{
  "timestamp": "2025-01-15T10:45:00Z",
  "validation_tool": "run-gdlint",
  "status": "failed",
  "violations": [
    {
      "file": "target/resources/ship/ShipStats.gd",
      "line": 15,
      "error": "Variable 'ship_class' not typed",
      "rule": "typing-required",
      "suggestion": "Add type annotation: var ship_class: String",
      "automated_fix_possible": true,
      "confidence": 0.95
    }
  ]
}

GDUnit4 Test Failures (1 error)

{
  "timestamp": "2025-01-15T10:46:00Z",
  "validation_tool": "run-gdunit4-tests",
  "status": "failed",
  "test_summary": {
    "total_tests": 8,
    "tests_passed": 7,
    "tests_failed": 1,
    "success_rate": 87.5
  },
  "failures": [
    {
      "test_name": "test_ship_stats_armor_validation",
      "class_name": "TestShipStats",
      "failure_type": "assertion_failure",
      "message": "Expected armor to be positive, got -1.0",
      "details": "Armor validation failed for negative input",
      "file": "target/resources/ship/ShipStats.gd",
      "line": 42,
      "automated_fix_possible": true,
      "suggestion": "Add validation: @export var armor: float = 0.0 with range(0, INF)"
    }
  ]
}

### Rollback Mechanisms
- All file modifications create .bak backups before changes
- Task contracts maintain complete audit trail of all changes
- Failed implementations can be rolled back safely using backup files
- Git integration tracks all file changes for version control

### Confidence-Based Escalation
- Low confidence tasks (< 70%) automatically trigger human review
- Human feedback is integrated into the same ## Feedback section
- System learns from human corrections over time
- Escalation thresholds adjustable per agent and task type

## Section 7: Performance and Scalability

### Parallel Processing
- Multiple engineers can work on different task types simultaneously
- Dependency resolution prevents conflicts
- Load balancing based on agent capacity and expertise

### Resource Management
- Task priorities ensure critical path work completes first
- Dependency graph prevents bottlenecks
- Resource pools manage agent availability

### Monitoring and Metrics
- Task completion rates per agent type
- Validation success/failure ratios
- Average time per task type
- Remediation loop effectiveness

This orchestration system transforms the complex Wing Commander Saga migration into a manageable, automated workflow with built-in quality assurance and self-correction capabilities, following the Reduce & Delegate philosophy throughout.