portable-transplant

What this skill does

# Portable Transplant

Translate portable component specs into targeted epics for a specific project.

**Estimated Time:** 5-20 minutes (depending on mode)
**Prerequisites:** Portable extract completed (`_portable-extract/`), target project has BMAD docs (PRD + Architecture minimum)
**Output:** Targeted epics + transplant report in `_portable-transplant/`

---

## Trigger Phrases

- "Transplant these portable specs into my target project"
- "Translate these extracted specs for my project"
- "Import portable business logic into this BMAD project"
- "Write epics for my target project using the extracted specs"

---

## Input Requirements

### Portable Extract (Source)

The `_portable-extract/` directory from a previous portable-extract run:

| File | Required | Contains |
|------|----------|----------|
| `epics.md` | Yes | Abstract epics with [User]/[Admin]/[System] personas, YAML frontmatter with `source_project` |
| `component-spec.md` | Yes | Business rules (BR-*), data contracts (DC-*), edge cases (EC-*), flows (FLOW-*) |

**Location resolution order:**
1. Current directory: `./_portable-extract/`
2. User-specified explicit path
3. Batch results: `~/git/batch-results/service-name/_portable-extract/`

### Target BMAD Docs

| File | Required | Provides |
|------|----------|----------|
| PRD (prd.md) | Yes | Target personas, business goals, domain language, requirements context |
| Architecture (architecture.md) | Yes | Target tech stack, data models, API patterns, integration architecture |
| UX Design (ux-design-specification.md) | No | Target design system, user flows, interaction patterns |

**Location resolution order:**
1. `_bmad-output/planning-artifacts/`
2. `docs/` or project root
3. User-specified explicit path

**If UX Design is not available:** Skip interaction pattern enrichment in Phase 3 and note in the transplant report that UX patterns were not mapped.

---

## Mode Selection

Determine which mode to use based on user request. If the user does not specify, default to Guided.

### Mode 1: YOLO (Fully Automatic)

No user interaction. Map all personas by role similarity. Translate all domain language using context clues from target PRD. Map all data contracts to closest target models. Mark uncertain mappings with `[AUTO-MAPPED - review recommended]`.

### Mode 2: Guided (Default)

3-8 targeted questions. Auto-map high-confidence items. Present mapping questions for ambiguous items (persona matches, domain terms, data contract fields). Incorporate user answers before generating epics.

### Mode 3: Interactive

Full conversation. Walk through each persona mapping, each domain term translation, and each data contract mapping individually. Present each epic for review before finalizing.

---

## Process

Phases 0, 1, 6, and 7 are identical across all modes. Phases 2-5 have mode-specific behavior documented in each phase and its referenced operations file.

### Phase 0: Locate and Verify Inputs

1. Locate the portable extract directory using the resolution order above.
2. Locate the target BMAD docs using the resolution order above.
3. Verify `epics.md` and `component-spec.md` exist in the portable extract.
4. Verify `prd.md` and `architecture.md` exist in the target docs.

**If portable extract is missing:** Tell the user to run portable-extract on the source project first. Stop.
**If target BMAD docs are missing:** Tell the user to create them via BMAD workflows or bmad-synthesize. Stop.

### Phase 1: Load, Parse, and Validate Inputs

Read all input files using the Read tool. Use parallel reads where possible.

**From portable extract, load:**
- All abstract personas with their role mappings
- All business rules (BR-CALC, BR-VAL, BR-DEC, BR-STATE)
- All data contracts (DC-IN, DC-OUT, DC-STATE)
- All edge cases (EC-*) and error states (ERR-*)
- All interaction patterns (FLOW-*)
- All epic groupings and story definitions

**From target BMAD docs, load:**
- PRD: personas (names, roles, goals), business vision, success criteria, domain terminology, FRs/NFRs
- Architecture: tech stack, data models, API contracts, integration patterns, domain model
- UX Design (if available): design system, user flows, interaction patterns

**Validation gate -- verify all of the following before proceeding:**
1. Portable extract contains at least 1 persona, at least 1 BR-* rule, and at least 1 DC-* contract.
2. Target PRD contains at least 1 named persona and identifiable domain terminology.
3. Target Architecture contains at least 1 data model or API contract.

**If validation fails:** Report which requirements are missing. If the file exists but lacks required content (empty sections, missing frontmatter, no BR-*/DC-* IDs), tell the user which file is malformed and what is missing. Stop.

> Phase 1 complete. Report: "Loaded N personas, M business rules, K data contracts from source. Target has X personas, Y data models."

### Phase 2: Map Personas

Follow `operations/map-to-target.md` Part 1 (Steps 1-5) for persona mapping. The operation handles all three modes.

> Phase 2 complete. Report: "Persona mapping: [User] -> TargetName, [Admin] -> TargetName, [System] -> TargetName(s)."

### Phase 3: Map Domain Language

Follow `operations/map-to-target.md` Part 2 (Steps 1-5) for domain language translation. The operation handles all three modes.

> Phase 3 complete. Report: "N domain terms translated, M excluded, K flagged for review."

### Phase 4: Map Data Contracts

Follow `operations/map-to-target.md` Part 3 (Steps 1-5) for data contract mapping. The operation handles all three modes.

> Phase 4 complete. Report: "N contracts mapped, M gaps identified, K adapter notes generated."

**Mapping validation checkpoint -- verify before proceeding to generation:**
1. Every abstract persona has at least one target mapping.
2. Every domain term has a translation, an exclusion, or a review flag.
3. Every DC-* contract has a target model mapping or a documented gap.

**If validation fails:** Report which mappings are incomplete. In Guided/Interactive mode, ask the user to resolve. In YOLO mode, mark incomplete mappings with `[INCOMPLETE - review required]` and proceed.

### Phase 5: Generate Targeted Epics

Follow `operations/generate-targeted-epics.md` (Steps 1-6) for epic generation and quality checks.

> Phase 5 complete. Report: "Generated N epics with M stories. K stories excluded, J items flagged for review."

### Phase 6: Write Output

Write output files following `operations/write-output.md`.

1. Create `_portable-transplant/` directory if it does not exist.
2. Write to `_portable-transplant/targeted-epics.md` (overwrite if exists).
3. Write to `_portable-transplant/transplant-report.md` (overwrite if exists).

### Phase 7: Report Summary

Output a summary to the user:

```
Portable Transplant Complete
==============================
Source: [source_project name]
Target: [target_project name]
Mode: [mode used]

Persona Mapping: N personas mapped
Domain Language: M terms translated, K excluded
Data Contracts: J contracts mapped, L gaps identified
Epics Generated: X epics, Y stories
Items Needing Review: Z (see transplant-report.md)

Next Steps:
  1. Review targeted-epics.md
  2. Resolve items marked [REVIEW]
  3. Feed into BMAD: use as input for create-epics-stories or create-story
```

---

## Multi-Source Transplant

To transplant from multiple portable extracts into a single target:

1. Run the transplant process for each source separately.
2. Write each source's output to `_portable-transplant/{source-name}/` where `source-name` is the `source_project` value from the portable extract's epics.md frontmatter, lowercased and hyphenated.
3. After all sources are processed, check for conflicts across sources:
   - **Duplicate BR-* IDs:** If two sources define the same BR-* ID, prefix with the source name (e.g., `payment-BR-CALC-001`, `inventory-BR-CALC-001`).
   - **Overlapping epic domains:** If two sources produce epics covering the same functional area, flag for u