maestro-transplant

name	maestro:transplant
description	Generate a bespoke issue-workflow for any target project. Phase 1 — a Claude Opus analyst reads the project deeply and produces a disposition report. Phase 2 — on approval, parallel writer agents transplant every Maestro workflow component, adapted to the target project's actual stack, test runner, dev environment, and conventions. Use when a project needs its own self-contained issue-workflow without taking a direct dependency on Maestro.
disable-model-invocation	true

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:

User response	What to put in the context block	What the analyst does
A clear answer	The answer verbatim	Treat as authoritative — do not override from codebase
Skipped / blank	"infer"	Read the codebase and derive the value; record the inferred value in the context doc
"I don't know" / "unsure"	"infer"	Same as skipped
"none" / "not set up yet"	"none"	Accept as-is — do not look for it in the codebase
Contradicts the codebase	Keep user answer	Trust the user; note the discrepancy in the context doc

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}"
     
  
   
    
       
       
       
       
    
  

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:

---

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

Situation	Action
Analyst returns no JSON	Re-spawn with a note to return JSON. If it fails twice, ask user to run the analyst manually and provide the context doc.
Writer returns no JSON	Log the cluster as failed, continue collecting other results. List it in the error summary.
Writer returns no file_hashes	Compute hashes inline: (sha256sum "$f" 2>/dev/null || shasum -a 256 "$f") | awk '{print $1}' for each path in files_written. Use maestro_source from the dispatch plan for each file.
Reviewer agent fails or returns no JSON	Log and skip reviewer step — proceed to user review prompt without reviewer findings.
Consistency agent fails or returns no JSON	Log the failure in the summary as a warning. Do not block Phase 3.
MERGE writer cannot find maestro_commit in git history	Writer preserves the team's file unchanged and records a merge conflict. Surfaces in upgrade summary.
Target .claude/ already exists and user confirmed	Proceed — writers use Write which overwrites.
Context doc missing a section	Proceed — writers will use FIXME markers for missing values. Flag in summary.
analyst.repo == "FIXME"	Note in summary: "Fill in REPO= in .claude/skills/orchestrator/SKILL.md constants block."