agent-fleet-migrate

Files (1)

• SKILL.md

SKILL.md (first lines)

# Agent Fleet Migrate

> ℹ️ **First, set expectations:** before anything else, print one short line with this skill's version and its most recent change — the top entry of `metadata.changelog` above — e.g. `agent-fleet-migrate vX.Y — recent: <summary>`. Then proceed.

Execute the work order that `/agent-dev:agent-fleet-analysis` produces. The analysis is the *diagnose* half; this skill is the *execute* half — the same relationship as `create-agent:review` → `create-agent:adjust`, one level up.

**Three properties are non-negotiable:**

1. **Non-destructive.** Source agents are never mutated — not even "safe" fixes. All writes land in the target workspace; a run is reversible by deleting a folder. The run proves this at the end (Step 7).
2. **Composition, not duplication.** This skill owns exactly three things: copy semantics, per-paradigm logic extraction, and the fleet-level before/after report. Every other stage is a named skill invocation (see the composition table). This file must contain **no inline restatement of any composed skill's checks or templates** — a restated rubric line is future drift. Gaps found in a composed skill get fixed *in that skill*.
3. **Honest gates.** An agent is reported "migrated" only after the review gate passes and the re-score clears the bar (Step 4d). Failures are reported as failures with named findings — never rounded up. A gate FAIL is a blocker, not an advisory.

## Composition table

| Stage | Invoke |
|-------|--------|
| Work order (missing or stale) | `/agent-dev:agent-fleet-analysis` |
| Scaffold target shape (non-Claude-Code paradigms) | `/create-agent:custom` |
| Extracted capabilities → skills | `/agent-dev:create-playbook` |
| Gap fixes on the copies | `/create-agent:adjust` (composes the review itself) |
| Memory / hub / canon wiring | `/agent-dev:add-memory` · `/agent-dev:add-orchestrator` · `/agent-dev:add-canon` — driven by the work order's `upgrade_paths`, which already names the skill per agent |
| **Verification gate** | `/create-agent:review` per migrated copy |
| Numeric before/after | `/agent-dev:agent-fleet-analysis` re-run on the target workspace |
| Deploy handoff (gated) | A GitHub repo per migrated agent, then `/trinity:onboard` per agent (deploys from the repo), or `mcp__trinity__deploy_system` naming each member `github:Org/repo` |

Execution is **sequential in the main loop** — one agent at a time, in manifest order. Slower than fan-out, but every composed skill resolves exactly as it does when the user runs it directly.

## Usage

```
/agent-fleet-migrate [report.md | report.json | fleet-path ...] [--target dir]
```

- **Report path** (`.md` or `.json` from a previous analysis run): execute it.
- **Fleet path(s)** (directories of agents): run `/agent-dev:agent-fleet-analysis` on them first, then execute the fresh report.
- **Nothing**: find the newest `agent-fleet-analysis-*.json` in the conventional output locations — `./session-files/*_agent_fleet_analysis/`, `./fleet-analysis/`, `/home/developer/public/` — and confirm it at the plan gate.
- `--target dir`: target workspace (default `./fleet-migrated/`). Never inside any source agent directory.

---

## Step 1: Resolve the Work Order

Parse the arguments per Usage. Whenever a markdown report is given or found, prefer its JSON twin (`agent-fleet-analysis-<date>.json`, written alongside) — the structured form carries `agents[]`, `upgrade_paths`, `fleet_topology`, and the roadmap without re-parsing prose. If only the markdown exists, work from it.

**Staleness check:** if any source agent directory listed in the report contains files newer than the report file itself, the diagnosis may no longer match reality. Say which directories changed and offer to refresh via `/agent-dev:agent-fleet-analysis` before executing. Proceeding on a stale report is the operator's call, made at the plan gate — never silent.

**Dead ends get a next action, never silence:**

| Situation | Action |
|-----------|--------|
| No report found anywhere | Print: `No fleet-analysis report found. Run /agent-dev:agent-fleet-analysis <fleet-path> first, or pass the fleet path directly to this skill.` Stop. |
| Report references source dirs that no longer exist | List them; migrate the ones that do exist; record the missing ones as `failed — source directory gone`. |
| Report has zero agents | Print the analysis skill's own no-agents guidance and stop. |
| Report predates schema v2.2 (no `paradigm` field) | Re-run `/agent-dev:agent-fleet-analysis` on the source paths — do not guess paradigms. |

## Step 2: Migration Manifest — the Plan Gate

Build the manifest from the work order and present it for **one approval before any write**. Every row is editable at the gate (skip an agent, rename a target, change the hub):

```
## Migration manifest — approve before any write

Work order: <report path> (generated <date>, <fresh | STALE — details above>)
Target:     <target dir>   Sources: never mutated

| # | Agent | Paradigm | Score | Action | Target |
|---|-------|----------|-------|--------|--------|
| 1 | <name> | claude-code | 45% maturity | uplift (copy + fix gaps) | <target>/<name>/ |
| 2 | <name> | n8n | 70% readiness | convert (scaffold + extract) | <target>/<name>/ |
| 3 | <name> | freeform-coded | 20% readiness | skip — operator call | — |

Hub designation: <name>  (from fleet_topology.hub)
Fleet wiring after per-agent work: <upgrade_paths entries, mechanical vs. handoff — see Step 5>
Skipped: <list with reasons — low readiness, non-agent, operator exclusion>
```

Actions are: **uplift** (`claude-code` — the copy is the migration; fixes close the gap list), **convert** (`n8n` / `framework` / `freeform-coded` — scaffold + extraction), **skip** (recorded with reason). Default: migrate everything the report inventoried as an agent; suggest skipping only agents the report scored under 40 readiness with no discoverable purpose.

If every agent ends up skipped, print what was skipped and why, plus the one action that would unblock the most agents (usually "state the purpose of X — its readiness score is limited by purpose discoverability"). Stop — an empty manifest is not a run.

The **deploy offer is a second, separate gate** (Step 8). Approving the manifest never implies deployment.

## Step 3: Prepare the Target Workspace

```bash
TARGET="${TARGET_DIR:-./fleet-migrated}"
mkdir -p "$TARGET"
STAMP="$TARGET/.pre-migration-stamp"
touch "$STAMP"   # mtime marker — Step 7 proves no source file is newer than this
```

**Re-run semantics (additive, never destructive):** if `<target>/<name>/` already exists from a previous run, do **not** re-copy, delete, or overwrite it — treat it as a resume: skip Step 4a for that agent and run Steps 4b–4d against the existing copy. Hand-edits the user made to a migrated copy are preserved; the git history inside each copy (initialized in 4a) shows exactly what each run changed. To start over instead, the user deletes the folder or passes a fresh `--target`.

## Step 4: Per-Agent Migration Loop

Process manifest agents sequentially. **One agent's failure never aborts the fleet run** — record the failure with its named reason and continue with the next agent.

### 4a: Copy or scaffold — the non-destructive workspace

**`claude-code` (uplift):** copy the source into the target, excluding volatile and secret-bearing paths, then initialize git so every later change is diffable:

```bash
SRC="<source agent dir>"; DEST="$TARGET/<name>"
mkdir -p "$DEST"
rsync -a \
  --exclude ".git" --exclude "node_modules" --exclude ".venv" --exclude "venv" \
  --exclude "__pycache__" --exclude ".env" --exclude ".env.*" --exclude ".mcp.json" \
  --include ".env.example" \
  "$SRC/" "$DEST/"
git -C "$DEST" init -q
git -C "$DEST" add -A && git -C "$DEST" commit -qm "pre-migration copy of $SRC"
```

Real `.env` / `.mcp.json` files are deliberately left behind — the migrated copy documents credentials via `.env.example` only; the user re-supplies real values when running the copy.

**`n8n` / `framework` / `freeform-coded` (convert):** copy the source material to `<target>/_sources/<name>/` (same exclusions; reference only, never git-inited) — the extraction in 4b reads from this copy, not from the original. Then scaffold the target agent: **Invoke `/create-agent:custom`** for `<target>/<name>/` with the purpose extracted by the analysis (the report's `purpose` field) as the agent's stated purpose. Port the 4b extraction results into the scaffold.

### 4b: Per-paradigm logic extraction (convert actions only)

From Abilityai/trinity-skills, Apache-2.0.

More from Abilityai/trinity-skills