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 (CLAUDECODEEXPERIMENTALAGENTTEAMS=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:

1. If v8Status: "available" → OK (already cloned in ~/.lutece-references/)
2. If v8Status: "unknown" → Search GitHub orgs lutece-platform and lutece-secteur-public for v8 branch
3. Branch priority: develop_core8 > develop8 > develop8.x > develop
4. If a dependency has NO v8 version → STOP. Do not proceed. Report to user.
5. Clone missing dependencies — For each dependency confirmed v8 but not yet in ~/.lutece-references/:

``bash 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:

1. Config Migrator (1 teammate)

- Instructions: ${CLAUDEPLUGINROOT}/skills/lutece-migration-v8-agent-teams/teammates/config-migrator.md - Task file: .migration/tasks-config.json

1. Verifier (1 teammate)

- Instructions: ${CLAUDEPLUGINROOT}/skills/lutece-migration-v8-agent-teams/teammates/verifier.md - Starts monitoring immediately, builds only after all others complete

Conditionally spawn:

1. Java Migrator(s) (1-3, based on scan.json recommendation)

- Instructions: ${CLAUDEPLUGINROOT}/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

1. Template Migrator (0-1, if templates/JSP exist)

- Instructions: ${CLAUDEPLUGINROOT}/skills/lutece-migration-v8-agent-teams/teammates/template-migrator.md - Task file: .migration/tasks-template.json

1. Test Migrator (0-1, if test files exist)

- Instructions: ${CLAUDEPLUGINROOT}/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:

1. Check task list progress every ~30 seconds
2. Run progress report periodically:

``bash bash ${CLAUDEPLUGINROOT}/skills/lutece-migration-v8-agent-teams/scripts/progress-report.sh . ``

1. If a teammate is stuck (same task > 5 min): send a message via mailbox asking for status
2. If a teammate reports a blocker: investigate and either reassign, advise, or fix the blocker
3. 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:

1. Ask the Verifier to run final cleanup (.migration/ removal, context XML deletion)
2. 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

1. Clean up the team
2. STOP. Do NOT commit. The user decides when and how to commit.

Strict Rules

1. Delegate mode: After Phase B, the Lead orchestrates only — never modifies files
2. No builds before completion: The project WILL NOT compile during migration. Only the Verifier builds.
3. NEVER commit: The skill must NEVER create git commits. Leave that to the user.
4. Reference-First Rule: ALL teammates must search ~/.lutece-references/ before writing new patterns
5. File ownership: Each file is owned by exactly one teammate. No two teammates touch the same file.
6. Script-first: Teammates run mechanical scripts FIRST, then apply intelligence to remaining issues
7. Verify per-file: Teammates run verify-file.sh after each file, not just at the end

Manual review hotspots

The scan reports counts only — these patterns require human judgment, no mechanical sed:

• shutdownServiceImpls — Classes implementing fr.paris.lutece.portal.service.init.ShutdownService. With CDI-managed @ApplicationScoped beans, replace with Jakarta-native @PreDestroy on a shutdown method. Drop the interface entirely if process() does nothing meaningful (no real cleanup work). When real cleanup exists:

``java // Before public class XService implements ShutdownService { @Override public String getName() { return "XService"; } @Override public void process() { client.close(); } } // After public class XService { @PreDestroy void shutdown() { client.close(); } } ` Java Migrators handle this case-by-case. Don't auto-replace via sed — getName()` may have legitimate uses elsewhere.

Script Locations

All in ${CLAUDEPLUGINROOT}/skills/lutece-migration-v8-agent-teams/scripts/:

Pattern Locations

All in ${CLAUDEPLUGINROOT}/skills/lutece-migration-v8-agent-teams/patterns/: