Maestro:transplant

Transplant — Bespoke Issue Workflow Generator

Transplants the full Maestro issue-workflow into a target project as a self-contained, project-specific workflow. WP-specific steps are stripped for non-WP projects; everything is rewritten for the target's actual stack. The output lives entirely in the target project's .claude/ directory and bin/ — no Maestro dependency at runtime.

Usage

/maestro:transplant <target-project-path>

<target-project-path> may be absolute or relative to the current working directory.

Step 0 — Setup

Resolve paths:

MAESTRO_ROOT="$(pwd)"
TARGET_ROOT="$(cd "<target-project-path>" 2>/dev/null && pwd)"

If the target path does not exist, stop:

Error: target path does not exist — <path>

Detect mode — check for an existing transplant manifest:

MANIFEST="$TARGET_ROOT/.claude/transplant-manifest.json"
if [ -f "$MANIFEST" ]; then
  MODE="upgrade"
  MAESTRO_COMMIT_AT_TRANSPLANT="$(jq -r '.maestro_commit' "$MANIFEST")"
  TRANSPLANTED_AT="$(jq -r '.transplanted_at' "$MANIFEST")"
else
  MODE="fresh"
fi

# Check for legacy .aiassistant directory
AIASSISTANT_EXISTS=false
[ -d "$TARGET_ROOT/.aiassistant" ] && AIASSISTANT_EXISTS=true

Fresh mode — if .claude/ already contains files (but no manifest), warn:

.claude/ already exists in the target project and will be overwritten. Reply "proceed" to continue or "cancel" to abort. Wait for confirmation before continuing.

Upgrade mode — if manifest found, print:

Transplant manifest found (last run: {TRANSPLANTED_AT}, Maestro commit: {MAESTRO_COMMIT_AT_TRANSPLANT}). Running in upgrade mode — team customizations will be preserved, only new Maestro changes will be merged in. Stack recorded at last transplant: {manifest.interview.project_type} · {manifest.interview.languages} · tests: {manifest.interview.test_runners} Has your tech stack changed since then? (y/n — if yes, describe what changed)

Wait for the answer. If no: proceed automatically. If yes: re-run Step 0b with a note that this is a stack update, then pass the updated interview context block to the analyst prompt.

Step 0b — Project Interview (fresh mode only)

Skip this step entirely in upgrade mode — the context already exists in transplant-context.md.

In fresh mode, collect ground truth from the user before spawning the analyst. Ask all questions at once in a single message — do not ask one by one.

Present this intake form:

Before analysing the project, I need a few answers to make the transplant as accurate as possible.

Skip anything you don't know — the analyst will read the codebase and fill it in.
There are no wrong answers. Partial answers are fine.

1. Project type (pick one):
   a) WordPress plugin or theme
   b) Website / web app (React, Vue, Next.js, static, etc.)
   c) Backend API (REST, GraphQL — no browser UI)
   d) CLI tool or automation script
   e) Monorepo (multiple apps)
   f) Other — describe briefly

2. Primary language(s):
   e.g. PHP, TypeScript, Python, Go, Ruby — list all that apply
   (skip if unsure)

3. Test runner(s):
   e.g. PHPUnit, Jest, Vitest, Pytest, RSpec, Mocha, none yet
   (skip if unsure)

4. Local dev environment:
   a) Yes — Docker / docker compose
   b) Yes — custom shell script (what command?)
   c) Yes — other (describe)
   d) No local dev environment
   (skip if unsure)
   If yes: what URL does it run on? e.g. http://localhost:3000

5. Does the project have a browser-testable UI?
   Admin panel, web app pages, settings page, etc. — yes / no / unsure

6. CI setup:
   a) GitHub Actions
   b) Other CI (name it)
   c) No CI yet
   (skip if unsure)

7. Agents' working temp directory:
   Agents write issue-tracking files, logs, and locks here.
   Default: `.ai` — or type a custom name (e.g. `.TemporaryItems`, `.work`)
   Leave blank to accept the default.

Anything else I should know? (framework conventions, monorepo structure, unusual tooling, etc.)

Wait for the user's answers.

Handling skipped or uncertain answers:

When the analyst cannot determine a field from either the user answer or the codebase (e.g. "infer" and no evidence in the codebase), it writes "FIXME: <what is needed>" for that field and surfaces it as a manual step in the final summary.

Once answers are received, build the interview context block:

## Project interview (user-provided ground truth — trust over codebase inference)

project_type: <answer or "infer">
languages: <answer or "infer">
test_runners: <answer or "infer">
local_dev_cmd: <boot command or "none" or "infer">
local_url: <URL or "none" or "infer">
has_browser_ui: <yes / no / infer>
ci: <answer or "infer">
temp_root: <custom name, or ".ai" if left blank>
notes: <free-text answer to "anything else" or empty>

This block is injected into the analyst prompt as the first section. It overrides any conflicting inference the analyst makes from reading the codebase.

Phase 1 — Deep Analysis (Claude Opus)

Spawn the transplant-analyst agent with model opus:

Prompt to pass (fresh mode):

Analyse the project at {TARGET_ROOT} for transplanting the Maestro issue-workflow.

mode: fresh
maestro_root: {MAESTRO_ROOT}
target_root: {TARGET_ROOT}
aiassistant_exists: {AIASSISTANT_EXISTS}

{INTERVIEW_CONTEXT_BLOCK}

Interview field rules:
- Field value is a real answer → authoritative. Do not override from codebase even if they conflict. Note any discrepancy in the context doc.
- Field value is `"infer"` → unknown. Read the codebase and derive the value. Record the inferred value (not `"infer"`) in the context doc.
- Field value is `"none"` → user confirmed the thing does not exist. Do not look for it.
- Field value is `"FIXME: ..."` → neither the user nor the codebase supplied it. Leave it as FIXME and surface it as a manual step in your return JSON.

Use interview answers to drive disposition decisions: non-PHP projects should have PHP-specific checks rewritten or dropped; projects with no browser UI should have e2e-qa-tester dropped; test runner answers directly determine what replaces PHPUnit in DOD Check 2 and implementation agents.

Produce transplant-context.md at {TARGET_ROOT}/.claude/transplant-context.md and return the JSON summary.

Prompt to pass (upgrade mode):

Analyse the project at {TARGET_ROOT} for a Maestro workflow upgrade.

mode: upgrade
maestro_root: {MAESTRO_ROOT}
target_root: {TARGET_ROOT}
aiassistant_exists: {AIASSISTANT_EXISTS}
manifest_path: {TARGET_ROOT}/.claude/transplant-manifest.json

The manifest (version 2) contains a `components` array with `{ maestro_source, output_path, sha256 }` per written file — use this for team-change detection instead of a refs directory. Use `git -C {MAESTRO_ROOT} show {maestro_commit}:{maestro_source}` to reconstruct Maestro baselines.

Produce an updated transplant-context.md and an upgrade plan. Return the JSON summary.

When the analyst returns, print:

─────────────────────────────────────────
Transplant Analysis Complete
─────────────────────────────────────────
Project:  {analyst.project_name} ({analyst.project_type})
Language: {derived from context}
Repo:     {analyst.repo}

Component disposition:
  KEEP_AS_IS  {analyst.keep_count}
  ADAPT       {analyst.adapt_count}
  REWRITE     {analyst.rewrite_count}
  DROP        {analyst.drop_count}

Dropped:  {analyst.drops | join(", ") or "none"}

Context doc: {analyst.context_path}
─────────────────────────────────────────

Spawn the transplant-analyst-reviewer agent with model opus (fresh mode only — skip in upgrade mode):

Review the transplant context doc at {TARGET_ROOT}/.claude/transplant-context.md.

context_path: {TARGET_ROOT}/.claude/transplant-context.md
maestro_root: {MAESTRO_ROOT}

The reviewer applies unambiguous auto-fixes directly to the context doc (wrong DROP/KEEP dispositions, missing TEMP_ROOT default, etc.) and returns a verdict JSON.

If reviewer returns auto_fixed entries: note each correction.

If reviewer returns findings with severity: FAIL: these need user attention.

Then ask the user (combining the analyst summary + reviewer outcome):

Fresh mode:

If reviewer returned NEEDS_REVISION or any findings:

"Reviewer flagged {N} item(s): {for each finding: • [FAIL|WARN] {component}: {description}}

{if auto_fixed non-empty: Auto-corrected {M} disposition(s) in the context doc: {list}.}

Review the context doc at {analyst.context_path} and confirm to proceed — or describe what needs correcting."

If reviewer returned APPROVED:

"Review the context doc at {analyst.context_path} and confirm to generate the workflow — or describe what needs correcting."

Upgrade mode:

Build the confirmation message:

"Here is the upgrade plan (Section 10 of the context doc). MERGE components will be semantically merged preserving team edits. APPLY components will be re-transplanted as-is (no team changes detected). PRESERVE and SKIP components will not be touched.

{if analyst.remove_candidates non-empty:} ⚠️ {analyst.remove_count} orphaned component(s) found — present at last transplant but no longer in Maestro: {for each remove_candidate: • {output_path} (was {maestro_source})} Delete these from the target project after the upgrade? (y/n — default: n)

Confirm to proceed — or describe what needs adjusting."

Record the user's orphan deletion answer as DELETE_ORPHANS (true/false, default false).

Wait for explicit confirmation before continuing.

If the user requests corrections: update {TARGET_ROOT}/.claude/transplant-context.md directly (or re-run the analyst with the correction as additional context), then ask again.

Phase 2 — Directory Setup

Create all output directories dynamically from the analyst's dispatch_plans — no hardcoded list needed:

echo "$ANALYST_JSON" | jq -r '
  .dispatch_plans | to_entries[].value[] |
  .output_path | select(. != null)
' | xargs -I{} dirname {} | sort -u | xargs mkdir -p

This automatically handles any new component the analyst discovered, including newly added skills that weren't in any previous hardcoded list.

Legacy bin/ cleanup (v2 migration): Before spawning writers, remove any workflow scripts left at the old location:

for f in dev-start.sh dev-seed.sh dev-down.sh; do
  [ -f "$TARGET_ROOT/bin/$f" ] && rm -f "$TARGET_ROOT/bin/$f"
done
rmdir "$TARGET_ROOT/bin" 2>/dev/null || true

The rmdir silently no-ops if bin/ still has other project scripts — only removes it if empty.

Phase 2 — Build Dispatch Plans

The analyst's return JSON now includes a dispatch_plans map — consume it directly:

DISPATCH_PLANS="$(echo "$ANALYST_JSON" | jq '.dispatch_plans')"

Each cluster key maps to an array of { name, disposition, source_path, output_path } objects. No manual table lookup is needed.

Each dispatch plan follows this structure (replace placeholders with resolved absolute paths):

{
  "mode": "fresh | upgrade",
  "maestro_root": "{MAESTRO_ROOT}",
  "target_root": "{TARGET_ROOT}",
  "context_path": "{TARGET_ROOT}/.claude/transplant-context.md",
  "cluster": "cluster-name",
  "components": [
    {
      "name": "component-name",
      "disposition": "DISPOSITION-FROM-CONTEXT-DOC",
      "source_path": "/absolute/source/path (current Maestro)",
      "output_path": "/absolute/output/path"
    }
  ]
}

For MERGE components in upgrade mode, add three extra fields so the writer can reconstruct the Maestro baseline from git without a refs directory:

{
  "name": "backend-agent",
  "disposition": "MERGE",
  "source_path": "/absolute/maestro/agents/backend-agent.md",
  "output_path": "/absolute/target/.claude/agents/backend-agent.md",
  "maestro_root": "{MAESTRO_ROOT}",
  "maestro_commit": "{MAESTRO_COMMIT_AT_TRANSPLANT}",
  "maestro_source": "agents/backend-agent.md"
}

maestro_commit is the maestro_commit value read from the existing manifest (Step 0). maestro_source is the Maestro-relative path for this component.

In upgrade mode, disposition values come from the context doc's Section 10 — Upgrade Plan (SKIP / PRESERVE / APPLY / MERGE) rather than Section 8. Writers handle each disposition differently — see transplant-writer.md.

Phase 2 — Inline KEEP_AS_IS

Before spawning writer agents, handle all KEEP_AS_IS and DROP components directly in the orchestrator. This avoids spawning writer agents for trivial file copies.

For each cluster in DISPATCH_PLANS, iterate components:

• DROP: Skip. Record name in files_skipped.
• KEEP_AS_IS: Copy source to output, apply the universal pre-write pass via sed, compute sha256, record in files_written and file_hashes:

cp "$source_path" "$output_path"
sed -i.bak \
  -e '/maestro\.json/d' \
  -e 's/\bMaestro\b/this workflow/g' \
  -e 's/bin\/dev-up\.sh/.claude\/bin\/dev-start.sh/g' \
  -e 's/bash bin\/dev-up\.sh/bash .claude\/bin\/dev-start.sh/g' \
  -e 's/bash bin\/dev-start\.sh/bash .claude\/bin\/dev-start.sh/g' \
  -e 's/^name: maestro:/name: /' \
  -e 's/`\/maestro:\([^`]*\)`/`\/\1`/g' \
  "$output_path"
rm -f "${output_path}.bak"
SHA256=$( (sha256sum "$output_path" 2>/dev/null || shasum -a 256 "$output_path") | awk '{print $1}' )

After processing, remove KEEP_AS_IS and DROP entries from each cluster's component array before passing to writers. If a cluster's component array is empty after filtering, do not spawn a writer for that cluster.

Phase 2 — Spawn Writers

Spawn one transplant-writer agent per cluster that has at least one ADAPT, REWRITE, MERGE, or GENERATE component (after inline processing removed KEEP_AS_IS and DROP). Clusters with no remaining components are skipped. Each receiving its dispatch plan as prompt input.

Each prompt must be self-contained — writers are isolated agents with no access to this conversation:

You are a transplant-writer agent. Here is your dispatch plan:

{dispatch plan JSON for this cluster}

Read the context doc at {TARGET_ROOT}/.claude/transplant-context.md, then process each component per its disposition. Return the JSON result when done.

Phase 2 — Collect Results + Finalize

After all writers complete, collect their return JSON. Aggregate files_written, file_hashes, files_merged, files_skipped, and fixme_values.

Run consistency pass — spawn the transplant-consistency agent:

Run a cross-cluster consistency check on the transplanted workflow.

context_path: {TARGET_ROOT}/.claude/transplant-context.md
target_root: {TARGET_ROOT}
files_written: {JSON array of all files_written from aggregated writer results}

The consistency agent applies fixes directly to the written files. Collect its fixes_applied and warnings for the final summary. Do not block on warnings — proceed regardless of consistency findings.

Write transplant manifest (after consistency pass):

The manifest uses per-file SHA256 hashes (from the file_hashes arrays collected from writer results) instead of a refs directory. This lets the upgrade analyst detect Maestro drift via git show and team modifications via hash comparison — with no file copies needed.

Build the components array by iterating the aggregated file_hashes:

MAESTRO_COMMIT="$(git -C "$MAESTRO_ROOT" rev-parse HEAD 2>/dev/null || echo 'unknown')"

Write {TARGET_ROOT}/.claude/transplant-manifest.json with this structure:

{
  "version": "3",
  "transplanted_at": "{ISO 8601 UTC timestamp}",
  "maestro_commit": "{MAESTRO_COMMIT}",
  "project_type": "{analyst.project_type}",
  "context_path": ".claude/transplant-context.md",
  "interview": {
    "project_type": "{interview.project_type}",
    "languages": "{interview.languages}",
    "test_runners": "{interview.test_runners}",
    "local_dev_cmd": "{interview.local_dev_cmd}",
    "local_url": "{interview.local_url}",
    "has_browser_ui": "{interview.has_browser_ui}",
    "ci": "{interview.ci}",
    "temp_root": "{interview.temp_root}",
    "notes": "{interview.notes}"
  },
  "components": [
    {
      "maestro_source": "agents/backend-agent.md",
      "output_path": ".claude/agents/backend-agent.md",
      "disposition": "ADAPT",
      "sha256": "{sha256 from file_hashes}"
    }
  ]
}

One entry per file in the aggregated file_hashes. DROPped/SKIPped/PREServed components are absent (they have no output file or no new sha256).

chmod +x "$TARGET_ROOT"/.claude/bin/*.sh 2>/dev/null || true

Phase 3 — QA Pass (Claude Opus)

After the consistency pass and manifest are written, spawn the transplant-qa agent with model opus:

Prompt:

Audit the transplanted workflow for the project at {TARGET_ROOT}.

context_path: {TARGET_ROOT}/.claude/transplant-context.md
target_root: {TARGET_ROOT}
project_type: {analyst.project_type}
mode: {fresh | upgrade}
files_written: {JSON array of all files_written from aggregated writer results}
files_merged: {JSON array of all files_merged from aggregated writer results, empty array if fresh mode}

On green verdict: proceed to Phase 4.

On red verdict: run a targeted re-work pass:

1. Group findings by cluster (use the cluster keys from DISPATCH_PLANS).
2. For each cluster with FAIL findings, build a targeted dispatch plan containing only the flagged components. Append a qa_feedback array to the plan:

   {
     "mode": "fresh",
     "maestro_root": "{MAESTRO_ROOT}",
     "target_root": "{TARGET_ROOT}",
     "context_path": "{TARGET_ROOT}/.claude/transplant-context.md",
     "cluster": "{cluster-name}",
     "qa_feedback": [
       {
         "file": "/absolute/path",
         "check": "A",
         "description": "...",
         "rework_instruction": "..."
       }
     ],
     "components": [...]
   }
   

3. Spawn targeted transplant-writer agents in parallel for each flagged cluster. Each writer's prompt includes: "This is a QA re-work pass. Apply every item in qa_feedback to its file before re-writing."
4. Re-run the QA agent. Maximum 2 re-spin rounds total.
5. If still red after 2 rounds: print remaining findings as manual steps in the summary and proceed to Phase 4.

Phase 4 — Cleanup Prompt

Ask:

"transplant-manifest.json and transplant-context.md are only needed if you plan to run /transplant again to upgrade this workflow later. (No refs directory is created — the manifest is a single JSON file.)

Keep upgrade artifacts? (y/n — default: y)"

If no:

rm -f "$TARGET_ROOT/.claude/transplant-manifest.json"
rm -f "$TARGET_ROOT/.claude/transplant-context.md"

If yes (default): keep both files.

If .aiassistant/ was found at $TARGET_ROOT:

"The .aiassistant/ directory was read during analysis and all relevant customizations have been incorporated into the transplanted workflow. Delete it now? (y/n — default: y)"

If yes (default):

rm -rf "$TARGET_ROOT/.aiassistant"

Note in the final summary:

  .aiassistant/ removed — workflow is now self-contained in .claude/.

If no: leave it and note in the final summary:

  ⚠️  .aiassistant/ not removed — clean up manually when ready.

Print the final summary:

Fresh mode:

─────────────────────────────────────────
Transplant Complete
─────────────────────────────────────────
Target: {TARGET_ROOT}

Files written ({total count}):
  Agents:   {list of .claude/agents/*.md written}
  Commands: {list of .claude/skills/*/SKILL.md written}
  Scripts:  {list of bin/ and scripts/ written}

Dropped: {list or "none"}

{if fixme_values non-empty:}
⚠️  Manual steps required:
  {each fixme_value}

{if consistency fixes non-empty:}
  Consistency fixes: {N fixes across M files}

{if consistency warnings non-empty:}
⚠️  Consistency warnings (review manually):
  {each warning}

{if writer errors:}
⚠️  Writer errors:
  {cluster}: {error}

{if upgrade artifacts removed:}
  Upgrade artifacts removed — workflow is self-contained.
{if upgrade artifacts kept:}
  Upgrade artifacts retained: .claude/transplant-manifest.json
─────────────────────────────────────────
Next steps:
  1. Review generated agents — especially orchestrator.md, backend-agent.md, and qa-engineer.md
  2. Commit .claude/ to the target repo
  3. Test: cd {TARGET_ROOT} && bash .claude/bin/dev-start.sh
─────────────────────────────────────────

Upgrade mode:

─────────────────────────────────────────
Transplant Upgrade Complete
─────────────────────────────────────────
Target: {TARGET_ROOT}

  MERGED   ({count}): {list — team edits preserved, Maestro delta applied}
  APPLIED  ({count}): {list — re-transplanted, no team edits detected}
  PRESERVED({count}): {list — team-only changes, Maestro unchanged, not touched}
  SKIPPED  ({count}): {list — no changes on either side}

{if remove_candidates non-empty and DELETE_ORPHANS true:}
  REMOVED  ({count}): {list — no longer in Maestro, deleted from target}
{if remove_candidates non-empty and DELETE_ORPHANS false:}
⚠️  Orphans kept ({count} — not in Maestro, kept by user choice):
  {each output_path}

{if fixme_values non-empty:}
⚠️  Manual review needed:
  {each fixme_value}

{if merge_conflicts non-empty:}
⚠️  Merge conflicts (manual resolution required):
  {component}: {description of conflict}
─────────────────────────────────────────

Orphan deletion — if DELETE_ORPHANS is true, delete confirmed orphans after the summary is printed:

for output_path in analyst.remove_candidates[*].output_path; do
  rm -f "$output_path"
done

Error handling