| name | lutece-migration-v8-agent-teams |
| description | Migration v7 → v8 via Agent Teams. Parallel teammates, script-heavy, JSON-driven task decomposition. |
| user-invocable | true |
Lutece Migration v7→v8 — Agent Teams Orchestrator
Purpose
Migrates any Lutece plugin/module/library from v7 to v8 using Agent Teams (Swarm Mode). The Team Lead (you) orchestrates, specialized teammates execute in parallel, and bash scripts handle all mechanical work.
Prerequisites: Agent Teams must be enabled (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1).
PHASE A — Scan (Lead executes directly)
A.1 — Verify Lutece project
Confirm the current directory is a Lutece project (pom.xml with lutece-plugin/module/library packaging).
A.2 — Run scanner
mkdir -p .migration
bash ${CLAUDE_PLUGIN_ROOT}/skills/lutece-migration-v8-agent-teams/scripts/scan-project.sh . > .migration/scan.json
A.3 — Display summary
Read .migration/scan.json and show the user:
- Project type, artifact, version
- Migration scope (SMALL/MEDIUM/LARGE)
- Total migration points
- Recommended teammate count
A.4 — Dependency v8 check (BLOCKER)
For every Lutece dependency in scan.json:
- If
v8Status: "available" → OK (already cloned in ~/.lutece-references/)
- If
v8Status: "unknown" → Search GitHub orgs lutece-platform and lutece-secteur-public for v8 branch
- Branch priority:
develop_core8 > develop8 > develop8.x > develop
- If a dependency has NO v8 version → STOP. Do not proceed. Report to user.
- Clone missing dependencies — For each dependency confirmed v8 but not yet in
~/.lutece-references/:
git clone -q --branch <v8_branch> --single-branch https://github.com/<org>/<artifactId>.git ~/.lutece-references/<artifactId>
This ensures teammates can search reference sources for ALL dependencies, not just the 21 pre-cloned repos.
PHASE B — Task Decomposition (Lead executes directly)
bash ${CLAUDE_PLUGIN_ROOT}/skills/lutece-migration-v8-agent-teams/scripts/task-splitter.sh .migration/scan.json .migration
Read the output to know how many teammates to spawn.
PHASE C — Spawn Teammates
Switch to Delegate Mode (Shift+Tab). From this point, you orchestrate only — never implement.
Always spawn:
-
Config Migrator (1 teammate)
- Instructions:
${CLAUDE_PLUGIN_ROOT}/skills/lutece-migration-v8-agent-teams/teammates/config-migrator.md
- Task file:
.migration/tasks-config.json
-
Verifier (1 teammate)
- Instructions:
${CLAUDE_PLUGIN_ROOT}/skills/lutece-migration-v8-agent-teams/teammates/verifier.md
- Starts monitoring immediately, builds only after all others complete
Conditionally spawn:
-
Java Migrator(s) (1-3, based on scan.json recommendation)
- Instructions:
${CLAUDE_PLUGIN_ROOT}/skills/lutece-migration-v8-agent-teams/teammates/java-migrator.md
- Task files:
.migration/tasks-java-0.json, .migration/tasks-java-1.json, .migration/tasks-java-2.json
- Each gets a DISTINCT file partition — no overlap
-
Template Migrator (0-1, if templates/JSP exist)
- Instructions:
${CLAUDE_PLUGIN_ROOT}/skills/lutece-migration-v8-agent-teams/teammates/template-migrator.md
- Task file:
.migration/tasks-template.json
-
Test Migrator (0-1, if test files exist)
- Instructions:
${CLAUDE_PLUGIN_ROOT}/skills/lutece-migration-v8-agent-teams/teammates/test-migrator.md
- Task file:
.migration/tasks-test.json
Spawn instructions template
When spawning each teammate, provide:
Read your instruction file at [path to teammates/*.md].
Read your task assignment at [path to .migration/tasks-*.json].
Execute all steps in your instructions. Use scripts from ${CLAUDE_PLUGIN_ROOT}/skills/lutece-migration-v8-agent-teams/scripts/.
Pattern files are at ${CLAUDE_PLUGIN_ROOT}/skills/lutece-migration-v8-agent-teams/patterns/ — load only when needed.
Reference implementations: always search ~/.lutece-references/ before writing any new pattern.
Migration samples with real before/after diffs: ${CLAUDE_PLUGIN_ROOT}/migrations-samples/ — consult when stuck on a specific migration pattern.
Run verify-file.sh after each file you complete.
PHASE D — Task Dependencies
Wire the dependency graph:
Config Migrator ──────────────────────────────────────── (no blockers, runs first)
│
├──→ Java Migrator 0 ─┐
├──→ Java Migrator 1 ─┤ (blocked by Config Migrator)
└──→ Java Migrator 2 ─┘
│
├──→ Template Migrator ─┐ (blocked by ALL Java Migrators)
└──→ Test Migrator ─────┤ (blocked by Config + at least 1 Java Migrator)
│
└──→ Verifier: Final Build (blocked by ALL above)
- Config Migrator runs first (POM, beans.xml, context XML catalog)
- Java Migrators start after Config completes (they need context-beans.json)
- Template Migrator starts after ALL Java Migrators complete (needs @Named bean names)
- Test Migrator starts after Config + at least 1 Java Migrator complete
- Verifier monitors continuously but only builds after ALL others complete
PHASE E — Monitoring
While teammates work:
- Check task list progress every ~30 seconds
- Run progress report periodically:
bash ${CLAUDE_PLUGIN_ROOT}/skills/lutece-migration-v8-agent-teams/scripts/progress-report.sh .
- If a teammate is stuck (same task > 5 min): send a message via mailbox asking for status
- If a teammate reports a blocker: investigate and either reassign, advise, or fix the blocker
- If the Verifier reports increasing FAILs: pause the responsible teammate and investigate
PHASE F — V8 Reviewer (Lead spawns as teammate)
When the Verifier reports BUILD SUCCESS (compile + tests) and verify-migration.sh: 0 FAIL, spawn a Reviewer teammate:
Read your instruction file at ${CLAUDE_PLUGIN_ROOT}/agents/lutece-v8-reviewer.md.
Review this project for v8 compliance. Do NOT modify any files.
Reference implementations: ~/.lutece-references/
Migration samples: ${CLAUDE_PLUGIN_ROOT}/migrations-samples/
Why a teammate? In Delegate Mode, the Lead can only spawn teammates — the Task tool is not available. The reviewer runs as a read-only teammate that reports findings without modifying files.
Process the reviewer's findings:
- FAIL items: Assign fixes to the appropriate teammate. Re-spawn reviewer after fixes.
- WARN items: Attempt to fix via teammates but do not block on WARNs.
- All FAIL resolved: Proceed to Phase G.
PHASE G — Final Gate
When ALL of the following are true:
- BUILD SUCCESS (both compile and tests)
- verify-migration.sh: 0 FAIL
- Reviewer agent: all FAIL items resolved
Then:
- Ask the Verifier to run final cleanup (.migration/ removal, context XML deletion)
- Present the migration summary to the user:
verify-migration.sh results (PASS/FAIL/WARN counts)- Build result (
mvn clean install — compile + tests)
- Number of test classes, tests run, tests passed/failed/skipped
- Reviewer agent verdict (PASS/FAIL/WARN counts)
- List of files modified
- Clean up the team
- STOP. Do NOT commit. The user decides when and how to commit.
Strict Rules
- Delegate mode: After Phase B, the Lead orchestrates only — never modifies files
- No builds before completion: The project WILL NOT compile during migration. Only the Verifier builds.
- NEVER commit: The skill must NEVER create git commits. Leave that to the user.
- Reference-First Rule: ALL teammates must search
~/.lutece-references/ before writing new patterns
- File ownership: Each file is owned by exactly one teammate. No two teammates touch the same file.
- Script-first: Teammates run mechanical scripts FIRST, then apply intelligence to remaining issues
- Verify per-file: Teammates run
verify-file.sh after each file, not just at the end
Script Locations
All in ${CLAUDE_PLUGIN_ROOT}/skills/lutece-migration-v8-agent-teams/scripts/:
| Script | Purpose | Used by |
|---|
scan-project.sh | Full project scan → JSON | Lead (Phase A) |
task-splitter.sh | JSON scan → per-teammate task files | Lead (Phase B) |
migrate-java-mechanical.sh | javax→jakarta + Spring→CDI + net.sf.json imports | Java Migrators |
migrate-template-mechanical.sh | BO macros + null-safety + namespace | Template Migrator |
extract-context-beans.sh | Spring context XML → JSON catalog | Config Migrator |
verify-migration.sh | 70+ checks, optional --json mode | Verifier |
verify-file.sh | Per-file verification subset | All teammates |
add-liquibase-headers.sh | Liquibase headers on SQL files | Config Migrator |
progress-report.sh | Migration progress display | Lead (Phase E) |
Pattern Locations
All in ${CLAUDE_PLUGIN_ROOT}/skills/lutece-migration-v8-agent-teams/patterns/:
| File | Content | Loaded by |
|---|
cdi-patterns.md | CDI scopes, injection, producers, singleton, Models, Pager, Key Imports | Java Migrators (always) |
events-patterns.md | Event/listener migration | Java Migrators (if events) |
cache-patterns.md | EhCache→JCache | Java Migrators (if cache) |
rest-patterns.md | Jersey→JAX-RS, filters, providers | Java Migrators (if REST) |
mvc-patterns.md | @RequestParam, CSRF auto-filter, @ModelAttribute | Java Migrators (if JspBean/XPage) |
template-macros.md | v8 Freemarker macros, jQuery→vanilla JS | Template Migrator |
fileupload-patterns.md | FileItem→MultipartItem | Java Migrators (if fileupload) |
