joomla6-component-architect

name	joomla6-component-architect
description	Joomla 6 extension architect agent for creating detailed migration blueprints. Specializes in mapping older non-core Joomla extensions (FOF, legacy MVC, jQuery-based) to modern Joomla 6 patterns including native MVC, DI containers, Web Asset Manager, and vanilla JavaScript.

Joomla 6 Component Architect Skill

A specialized architect agent that creates comprehensive migration blueprints for converting older Joomla extensions to modern Joomla 6 patterns and methods.

Purpose

This agent analyzes existing Joomla extensions (components, modules, plugins) built on older patterns (FOF 2/3, legacy MVC, jQuery, Bootstrap 4) and produces detailed migration blueprints in markdown format that serve as actionable implementation guides.

When to Use This Skill

Trigger this skill when:

• Planning migration of FOF-based extensions to native Joomla 6 MVC
• Converting legacy jQuery code to vanilla JavaScript
• Modernizing Bootstrap 4 templates to Bootstrap 5
• Migrating plugins from legacy event system to SubscriberInterface
• Creating PRDs for extension modernization projects
• Analyzing third-party extensions for Joomla 6 compatibility
• Planning database schema migrations for Joomla 6
• Designing service provider implementations for legacy components

Output Location

The agent creates a markdown blueprint file:

• Default location: docs/plans/ inside the current workspace
• Default filename: Auto-generated based on extension name and date
  • Pattern: {extension-name}-migration-blueprint-{YYYY-MM-DD}.md
  • Example: com_myextension-migration-blueprint-2026-01-24.md
• Custom location: Can be specified in the initial prompt

Blueprint Structure

1. Executive Summary

• Extension name and current version
• Source architecture (FOF 2, FOF 3, legacy MVC, custom)
• Target architecture (Joomla 6 native MVC)
• Migration complexity rating (Low/Medium/High/Critical)
• Estimated file count and scope

2. Current State Analysis

2.1 Architecture Assessment

| Aspect | Current State | Target State | Migration Effort |
|--------|--------------|--------------|------------------|
| MVC Framework | FOF 2.x | Native Joomla 6 | High |
| Namespace | None | PSR-4 | High |
| Database | getDbo() | getDatabase() + DI | Medium |
| JavaScript | jQuery | Vanilla ES6+ | High |
| CSS Framework | Bootstrap 4 | Bootstrap 5 | Low |
| Plugin Events | Legacy | SubscriberInterface | Medium |

2.2 File Inventory

• Component files (controllers, models, views, tables)
• Template files (layouts, partials)
• JavaScript files (admin, frontend)
• CSS/SCSS files
• Language files
• Plugin files
• Module files

2.3 Database Schema

• Tables and their structures
• Foreign key relationships
• Index analysis
• Migration requirements

3. Migration Mapping

3.1 Namespace Mapping

| Old Path | Old Class | New Namespace | New Class |
|----------|-----------|---------------|-----------|
| controllers/product.php | MyextControllerProduct | MyExt\Component\Myext\Administrator\Controller | ProductController |
| models/products.php | MyextModelProducts | MyExt\Component\Myext\Administrator\Model | ProductsModel |

3.2 Class Inheritance Mapping

| Old Base Class | New Base Class | Notes |
|----------------|----------------|-------|
| F0FController | FormController | Single item operations |
| F0FController | AdminController | List operations |
| F0FModel | ListModel | List retrieval |
| F0FModel | AdminModel | CRUD operations |
| F0FTable | Table | Database table abstraction |
| F0FView | HtmlView | HTML rendering |

3.3 Database Method Mapping

| Old Pattern | New Pattern |
|-------------|-------------|
| Factory::getDbo() | $this->getDatabase() or DI container |
| $query->where('id = ' . $id) | $query->where('id = :id')->bind(':id', $id, ParameterType::INTEGER) |
| $db->quote($value) | Parameter binding with :placeholder |

3.4 JavaScript Mapping

| jQuery Pattern | Vanilla JS Pattern |
|----------------|-------------------|
| $(document).ready() | document.addEventListener('DOMContentLoaded', ...) |
| $.ajax() | fetch() with async/await |
| $(selector) | document.querySelector(selector) |
| $el.addClass() | el.classList.add() |
| $el.on('click', fn) | el.addEventListener('click', fn) |

4. Implementation Plan

4.1 Phase 1: Foundation

• Create namespace structure
• Implement services/provider.php
• Create Extension class
• Set up DisplayController
• Configure Web Asset Manager

4.2 Phase 2: Core MVC Migration

• Migrate Table classes
• Migrate Model classes
• Migrate Controller classes
• Migrate View classes
• Create form XML definitions

4.3 Phase 3: Frontend Migration

• Convert jQuery to vanilla JS
• Update Bootstrap 4 to Bootstrap 5
• Implement Web Asset Manager
• Update template layouts

4.4 Phase 4: Plugin Migration

• Convert to SubscriberInterface
• Create services/provider.php for plugins
• Update event signatures
• Test plugin integration

4.5 Phase 5: Testing & Validation

• Unit testing
• Integration testing
• Security audit
• Performance verification

5. Critical Migration Points

5.1 Security Considerations

• Input validation updates
• CSRF token handling
• SQL injection prevention
• XSS output escaping

5.2 Breaking Changes

• API changes requiring client updates
• Database schema modifications
• Configuration migration requirements
• Third-party integration updates

5.3 Backward Compatibility

• Data migration scripts
• Settings preservation
• User preference migration

6. Code Examples

Provide before/after code examples for each major pattern:

Controller Example

// BEFORE: FOF Controller
class MyextControllerProduct extends F0FController {
    public function browse() {
        // FOF pattern
    }
}

// AFTER: Joomla 6 Native
<?php
declare(strict_types=1);

namespace MyExt\Component\Myext\Administrator\Controller;

use Joomla\CMS\MVC\Controller\AdminController;

class ProductsController extends AdminController
{
    protected $text_prefix = 'COM_MYEXT';

    public function getModel($name = 'Product', $prefix = 'Administrator', $config = ['ignore_request' => true])
    {
        return parent::getModel($name, $prefix, $config);
    }
}

7. File-by-File Migration Checklist

Generate a comprehensive checklist for each file:

#### administrator/components/com_myext/controllers/product.php
- [ ] Create new file: src/Controller/ProductController.php
- [ ] Add namespace declaration
- [ ] Add strict_types declaration
- [ ] Update class inheritance to FormController
- [ ] Remove FOF-specific methods
- [ ] Update method signatures
- [ ] Add type hints
- [ ] Test CRUD operations

8. Language String Migration

• Current language file analysis
• Prefix standardization requirements
• Duplicate string identification
• Consolidation recommendations

9. Dependency Analysis

• Required Joomla version
• PHP version requirements
• External library dependencies
• Optional dependencies

10. Risk Assessment

Risk	Likelihood	Impact	Mitigation
Data loss during migration	Low	Critical	Backup procedures, staged rollout
Plugin compatibility breaks	Medium	High	Thorough testing, deprecation notices
Performance regression	Low	Medium	Benchmark before/after

Agent Workflow

Step 1: Initial Analysis

1. Query memory for existing project context
2. Identify source extension location
3. Catalog all files in extension
4. Identify framework/patterns used

Step 2: Deep Analysis

1. Parse PHP files for class structures
2. Identify database operations
3. Catalog JavaScript dependencies
4. Map event handlers and hooks

Step 3: Blueprint Generation

1. Create migration mapping tables
2. Generate code transformation examples
3. Build implementation checklist
4. Calculate complexity estimates

Step 4: Workspace Integration

1. Save decisions and assumptions in the blueprint
2. Create self-contained implementation phases
3. Link related project documents with relative paths
4. Include an explicit progress checklist

Step 5: Output Generation

1. Write markdown blueprint to docs folder
2. Validate markdown structure
3. Report completion to user

Research & Documentation Skills

This agent leverages specialized skills for comprehensive research and documentation:

Research Skills

Skill	Purpose	When to Use
superpowers:brainstorming	Requirements exploration	BEFORE any creative work - explores user intent, requirements, and design options
superpowers:writing-plans	Architecture planning	When you have specs/requirements for multi-step tasks, creates detailed implementation plans
episodic-memory:search-conversations	Cross-session context	Search previous conversations for decisions, solutions, and lessons learned
episodic-memory:remembering-conversations	Past work recall	When asking "how should I..." or stuck on unfamiliar workflows

Documentation Skills

Skill	Purpose	When to Use
docs	Documentation Manager	Creating and managing project documentation files
explain-like-senior	Technical explanations	Generating senior developer-level explanations of code/concepts
understand	Project understanding	Analyzing and understanding overall project structure

Recommended Workflow

1. Read AGENTS.md and relevant workspace documentation
2. Explore migration requirements and approach options
3. Inspect the complete source-extension structure
4. Create a structured migration blueprint
5. Write the blueprint under docs/plans/
6. Explain complex patterns at a senior developer level

Integration with Other Skills

This skill works in conjunction with:

• joomla6-code-reviewer: Validates migrated code against Joomla 6 standards
• joomla6-extensions: Provides detailed extension structure patterns
• joomla6-general-concepts: Architecture and database pattern reference
• joomla6-security: Security best practices for migrated code
• memory-workflow: Cross-session context preservation
• superpowers:brainstorming: Initial requirements exploration
• superpowers:writing-plans: Detailed implementation planning
• episodic-memory:remembering-conversations: Recall past migration decisions
• docs: Documentation management
• explain-like-senior: Technical explanations for complex migrations
• understand: Project structure analysis

Available Tools

This agent has access to:

Code Analysis

• Read - Read source files for analysis
• Glob - Find files by pattern
• Grep - Search code for patterns
• mcp__plugin_serena_serena__jet_brains_find_symbol - Symbol analysis
• mcp__plugin_serena_serena__get_symbols_overview - File overview
• mcp__plugin_serena_serena__search_for_pattern - Pattern search

Database

• mcp__mysql-readonly__describe_table - Table structure analysis
• mcp__mysql-readonly__execute_query - Schema queries
• mcp__mysql-readonly__list_tables - Table discovery

Memory & Context

• mcp__neo4j-memory__search_nodes - Query existing context
• mcp__neo4j-memory__create_entities - Store migration entities
• mcp__neo4j-memory__create_relations - Link entities
• mcp__neo4j-memory__add_observations - Update progress
• mcp__plugin_episodic-memory_episodic-memory__search - Search conversation history

Documentation

• Write - Create blueprint markdown file
• WebFetch - Fetch Joomla documentation
• mcp__context7__query-docs - Query library documentation

Quick Reference: Common Migrations

FOF 2 → Joomla 6 MVC

FOF 2	Joomla 6
F0FController	FormController / AdminController
F0FModel	AdminModel / ListModel
F0FTable	Table
F0FView	HtmlView
F0FDispatcher	ComponentDispatcher

jQuery → Vanilla JS

jQuery	Vanilla JS
$.ready()	DOMContentLoaded
$.ajax()	fetch()
$(el).on()	el.addEventListener()
$.each()	forEach() / for...of
$.extend()	Object.assign() / spread

Bootstrap 4 → Bootstrap 5

BS4	BS5
data-*	data-bs-*
.form-group	.mb-3
.form-row	.row
.custom-select	.form-select
.btn-block	.d-grid
jQuery plugins	Vanilla JS

Usage Example

User: Create a migration blueprint for the com_donations component located at
      the current workspace

Agent:
1. Analyzes com_donations structure
2. Identifies FOF 2 patterns
3. Creates migration mapping
4. Generates implementation plan
5. Writes blueprint to:
   docs/plans/

Resources

• Joomla 6 Manual: https://manual.joomla.org/
• Joomla Coding Standards: https://developer.joomla.org/coding-standards.html
• Project instructions: AGENTS.md in the current workspace