graft

graft

Purpose

External code intelligence — structured workflow for learning from, adapting, and integrating features from any public repository into your project. Graft is NOT a copy-paste tool. It enforces understanding before adoption through a mandatory challenge gate that evaluates license compatibility, stack fit, scope, quality, and maintenance health before any code touches your codebase.

Core Rule: The Tree is a Menu, Not the Meal

When you clone a repo you see hundreds of files. That tree is a menu — options to order from, not a meal to eat. Grafting the whole tree is how context windows die and foreign patterns leak into your codebase.

• Read the README + the 2-5 files that implement the target feature. Skip the rest.
• If you cannot name the specific files you need before reading, you do not know what you want yet — go back to Step 0 and narrow scope.
• WebFetch on raw GitHub URLs beats git clone whenever you know the exact files. Use clone only when discovery is genuinely needed.

Reading to understand is not grafting. The discipline above caps the graft scope — the files you actually transplant, port, or improve into your codebase (2-5, hard-cap 10). It does NOT cap how many files you may read to learn a pattern. Studying a 24-skill library to extract one convention legitimately reads dozens of files but grafts almost none. Keep the two counts separate: a wide read with a narrow graft is thorough; a wide graft is the failure mode.

This menu discipline applies to the transplant modes (port, copy, improve). Copy mode is not an excuse to import a directory wholesale — you still select files deliberately. Compare mode and survey scope (--deep) are exempt from the read cap by design: their job is breadth of understanding, not transplant. They still must NOT import code wholesale — wide reading, narrow (or zero) graft.

Challenge gate (Step 4) MUST complete before adaptation planning (Step 5). No implementation without confronting trade-offs. This applies to ALL modes except compare. Skip only with --fast flag (user accepts full responsibility).

Modes

Port (default)

Rewrite the target feature using YOUR stack and patterns. Source code is a reference, not a template. Output is idiomatic to your codebase.

When: Different tech stack (Vue→React, Django→FastAPI), or source patterns conflict with your conventions.

Compare

Side-by-side analysis only. No code changes. Outputs a structured comparison report.

When: Evaluating whether to adopt a feature, benchmarking your implementation against another, or learning patterns without importing code.

Copy

Pure transplant with minimal adaptation. Stays as close to the original as possible — only changes imports, paths, and config to fit your project structure.

When: Same tech stack, source code is high quality, you want the exact implementation.

Improve

Copy the feature, then refactor and optimize. Fix anti-patterns, add missing tests, adapt to your codebase conventions, upgrade deprecated APIs.

When: Same stack but source has quality issues, or you want the feature but better.

Speed Options

Flag	Research	Challenge Gate	User Approval
(default)	✅ Full	✅ Yes	✅ Each step
--auto	✅ Full	✅ Yes	❌ Auto-approve
--fast	❌ Skip	❌ Skip	❌ Auto-approve

--fast warning: Skipping challenge gate means no license check, no quality assessment. User accepts full responsibility. Announce: "Fast mode: skipping challenge gate. You are responsible for license and quality review."

Scope Depth

Orthogonal to mode and speed. Controls how widely you may read.

Scope	Read budget	Graft scope	When
(default)	2-5 files, hard-cap 10	the feature's files	Transplant one feature/module
--deep (survey)	unbounded reads, full clone OK	narrow — patterns extracted, not files copied	Study a whole repo/library to learn architecture or compare many components

--deep is for understanding, not importing. Use it when the goal is "what can I learn from this repo" rather than "port this function." Pairs naturally with compare mode. It relaxes the read cap and the scope-guard warning — but the transplant discipline still holds: extract the pattern, then graft narrowly (often into multiple existing skills/files rather than copying source files 1:1).

Smart Intent Detection

Input Pattern	Detected Mode
Contains "compare", "vs", "diff", "analyze"	compare
Contains "copy", "exact", "as-is", "same"	copy
Contains "improve", "better", "adapt", "upgrade"	improve
Contains "port", "convert", "rewrite", "migrate"	port
URL points to specific file/dir (not repo root)	Auto-scope to that path
Contains "survey", "study", "learn from", "what can I take", "deep dive"	compare + --deep
(default — no keyword match)	port

Triggers

• /rune graft <url> [--port|--compare|--copy|--improve] [--auto|--fast]
• Delegated from cook when task contains "graft", "port from", "copy from repo", "clone feature from"
• Auto-trigger: when user pastes a GitHub URL with context like "use this", "like this repo", "steal this"

Calls (outbound)

• research (L3): fetch repo README, docs, understand purpose and architecture
• scout (L2): scan LOCAL codebase for conventions, patterns, stack detection
• fix (L2): implement adapted code (port and improve modes)
• review (L2): post-graft quality check (improve mode only)

Called By (inbound)

• User: /rune graft <url> direct invocation
• cook (L1): delegation when task is "port feature from external repo"

Data Flow

Feeds Into →

• fix (L2): adaptation plan → fix's implementation targets (port/improve modes)
• review (L2): grafted code → review's analysis targets (improve mode)
• test (L2): new grafted code → test coverage targets
• journal (L3): graft.complete signal → auto-logged for pattern tracking

Fed By ←

• scout (L2): local codebase conventions → graft's adaptation strategy
• research (L3): repo analysis → graft's understanding of source architecture

Executable Steps

Step 0 — Parse Input

Extract from user input:

1. URL — GitHub/GitLab/Bitbucket repo or file URL
2. Mode — explicit flag or auto-detect via intent detection table
3. Speed — --auto or --fast if present
4. Scope — specific dir/file path if URL points to subdirectory, or user specifies "just the auth module"

Validate URL is accessible. If private repo or URL fails → suggest raw file URLs or manual paste.

Step 1 — Fetch & Scope

# Sparse clone for large repos (skip if small or specific files)
git clone --depth 1 --filter=blob:none --sparse <url> /tmp/graft-<hash>
cd /tmp/graft-<hash>
git sparse-checkout set <target-dir>

For specific files or small repos: use WebFetch on raw GitHub URLs instead of cloning.

Read in this order (stop when you have enough context — see Core Rule: the tree is a menu):

1. README.md — purpose, architecture overview
2. Target dir's files — the actual code to graft (aim for 2-5 files, hard-cap at 10)
3. package.json / pyproject.toml / Cargo.toml — dependencies and stack
4. Tests for target feature — understand expected behavior

Scope guard: If target feature spans >15 files or >2000 LOC → WARN user: "Feature is large. Suggest narrowing to [specific module]. Continue anyway?" (Suppressed under --deep/compare — breadth is the point there.)

Menu discipline (transplant modes): Before reading file #6, pause and ask "do I actually need this to graft it, or am I eating the menu?" If the answer isn't a concrete reason tied to the target feature, stop reading and move to Step 2. Under --deep/survey scope this gate is lifted — read as widely as understanding requires, but keep the graft scope narrow (Step 5).

Step 2 — Analyze Source

Understand the target feature's architecture:

• What it does — 2-3 sentence summary
• How it works — key patterns, data flow, core logic
• Dependencies — external packages required, internal imports
• Stack — framework, language version, tooling
• Quality signals — has tests? typed? documented? last commit date?

Output a brief analysis (not full report — save context for later steps).

Step 3 — Scan Local Codebase

Invoke rune:scout (or use cached output if codebase.scanned signal received):

• Local tech stack and version
• Naming conventions (camelCase vs snake_case, file structure)
• Existing patterns that overlap with target feature
• Import style, test framework, state management approach

Stack comparison: Produce a quick compatibility matrix:

| Aspect | Source | Local | Compatible? |
|--------|--------|-------|-------------|
| Framework | Next.js 14 | Next.js 15 | ✅ Minor adaptation |
| Language | TypeScript | TypeScript | ✅ |
| State | Redux | Zustand | ⚠️ Port needed |
| Testing | Jest | Vitest | ⚠️ Port needed |

If stack is identical → suggest copy or improve mode (not port). If stack differs significantly → force port mode.

Step 4 — Challenge Gate

Score all 5 dimensions. If 2+ dimensions score ❌ → BLOCK graft. If 1 dimension scores ❌ → WARN + require explicit user override. Only --fast skips this gate entirely.

Present challenge results to user:

## Challenge Gate Results

| Dimension | Score | Detail |
|-----------|-------|--------|
| License | ✅ | MIT — compatible |
| Stack Fit | ⚠️ | Redux → Zustand migration needed |
| Scope | ✅ | 6 files, ~400 LOC — manageable |
| Quality | ✅ | Typed, tested, documented |
| Maintenance | ⚠️ | Last commit 4 months ago |

**Verdict: PROCEED with caveats** (0 ❌, 2 ⚠️)

Wait for user approval (unless --auto).

Step 5 — Plan Adaptation

Graft scope stays narrow regardless of how widely you read. If this run used --deep/survey to study a library, the read cap was lifted — but the adaptation plan below still selects a small set of files/patterns to actually transplant. A wide survey legitimately feeds a copy/improve plan that grafts only the 2-5 best files; it does not license importing the surveyed tree.

Based on mode, produce adaptation plan:

Compare mode → skip to output. Write comparison report and STOP.

Copy mode → list files to transplant, import path changes, config adjustments. Minimal changes only.

Port mode → for each source component, describe the rewrite:

• Source pattern → local pattern mapping
• Dependencies to replace (Redux→Zustand, Jest→Vitest)
• Files to create/modify in local project
• What to keep vs what to rewrite from scratch

Improve mode → copy plan + improvement list:

• Anti-patterns to fix (mutations, any types, missing error handling)
• Missing tests to add
• Deprecated APIs to upgrade
• Convention mismatches to align

Present plan to user. Wait for approval (unless --auto).

Step 6 — Execute

Compare mode: Output report → emit graft.complete → done.

Copy/Port/Improve modes:

1. Create/modify files per adaptation plan
2. For port/improve: invoke rune:fix for complex rewrites
3. For improve: invoke rune:review on grafted code
4. Run project verification (lint, type-check, test if applicable)
5. Clean up temp clone dir

Post-execution: Emit graft.complete signal with payload:

graft.complete:
  mode: "port|copy|improve|compare"
  source_url: "<url>"
  files_changed: ["src/auth/middleware.ts", "src/auth/types.ts"]
  challenge_score: { license: "pass", stack: "warn", scope: "pass", quality: "pass", maintenance: "warn" }

Output Format

Compare Mode Output

## Graft Comparison: [feature] — [source repo] vs [local]

### Summary
[2-3 sentences: what was compared, key differences]

### Comparison
| Aspect | Source | Local | Winner | Notes |
|--------|--------|-------|--------|-------|
| [aspect] | [approach] | [approach] | [which] | [why] |

### Recommendations
- [what to adopt from source]
- [what to keep from local]
- [what to graft: specific files/patterns]

Port/Copy/Improve Output

## Graft Complete: [feature] from [source]

### Mode: [port|copy|improve]
### Files Changed
- `path/file.ts` — [new|modified] — [what changed]

### Adaptations Made
- [adaptation 1]
- [adaptation 2]

### Verify
- [ ] `npm run lint` passes
- [ ] `npm run test` passes
- [ ] Feature works as expected

Returns

Field	Type	Description
mode	enum	port, compare, copy, improve
source_url	string	Source repository URL
files_changed	string[]	List of created/modified local files
challenge_score	object	5-dimension scores (pass/warn/fail)
status	enum	DONE, DONE_WITH_CONCERNS, BLOCKED
comparison_report	string?	Markdown report (compare mode only)

Constraints

1. MUST run challenge gate before any code changes — no blind copying
2. MUST clean up temp clone directories after completion
3. MUST detect and warn about license incompatibility before proceeding
4. MUST use sparse checkout for repos >100MB — never full clone large repos
5. MUST respect local conventions — grafted code should look native, not foreign
6. MUST NOT modify the source repository — read-only access only
7. MUST NOT graft without scoping — always narrow to specific feature/module
8. MUST treat the source file tree as a menu, not a meal for transplant — graft the 2-5 files the feature actually needs, not every file you can see. Reading widely to understand (esp. under --deep/compare) is allowed; grafting widely is not

Mesh Gates

Gate	Requires	If Missing
Challenge Gate	5-dimension score with 0-1 ❌	BLOCK if 2+ ❌, WARN if 1 ❌
Scout Gate	Local codebase scanned	Invoke rune:scout first
Scope Gate	Target feature ≤15 files	WARN user, suggest narrowing

Sharp Edges

Failure Mode	Severity	Mitigation
Grafting GPL code into MIT project	CRITICAL	Challenge gate checks license — blocks incompatible
Blindly copying code without understanding	CRITICAL	HARD-GATE: challenge before implement
Context overflow from large source files	HIGH	Scope guard: >15 files or >2000 LOC triggers warning
Reading the whole repo instead of the feature	HIGH	"Tree is a menu" rule — pause before file #6, justify each read (transplant modes only)
Forcing a pattern-study graft into the 10-file feature cap	MEDIUM	Use --deep/survey scope — wide read, narrow graft; cap counts grafted files, not reads
Grafted code doesn't match local conventions	HIGH	Step 3 scans local patterns, Step 5 plans adaptation
Stale source (abandoned repo)	MEDIUM	Maintenance dimension in challenge gate
Private repo URL fails	MEDIUM	Fallback to WebFetch raw URLs or manual paste
Port mode when copy would suffice (wasted effort)	MEDIUM	Mode decision tree suggests optimal mode

Self-Validation

SELF-VALIDATION (run before emitting graft.complete):
- [ ] Challenge gate was executed (or --fast acknowledged)
- [ ] All grafted files follow local naming conventions
- [ ] No source-specific imports remain (wrong paths, missing packages)
- [ ] License compatibility confirmed (or user override documented)
- [ ] Temp clone directory cleaned up
- [ ] Grafted code compiles/lints without new errors
- [ ] **Graft scope** ≤10 files (files actually transplanted/ported/improved) — if >10, document why. This is NOT the read count: under `--deep`/compare you may read far more to understand, but the files you graft stay narrow.
IF ANY check fails → fix before reporting done. Do NOT defer to completion-gate.

Cross-cutting Updates

If this skill is added to the repo (first time):

• README.md — skill count (61→62), L2 count (28→29)
• docs/ARCHITECTURE.md — add graft to L2 list
• CLAUDE.md — add graft to L2 list, routing table, skill count
• docs/index.html — update meta stats if applicable

Done When

• Input parsed: URL, mode, speed flags extracted
• Source fetched and scoped (sparse clone or WebFetch)
• Source analyzed: patterns, dependencies, stack understood
• Challenge gate passed (5 dimensions scored, 0-1 ❌)
• Local codebase scanned for conventions
• Adaptation plan produced and approved
• Code grafted per mode (port/copy/improve/compare)
• Verification passed (lint, type-check, tests)
• Temp files cleaned up
• graft.complete signal emitted
• Self-Validation: all checks passed

Cost Profile

~2000-4000 tokens input (SKILL.md + 1-2 references), ~3000-8000 tokens output (analysis + adaptation + code). Sonnet for execution. Heaviest when port mode rewrites significant code — but that's where the value is highest.

Scope guardrail: Do not become a general-purpose code review tool. Graft analyzes external code for adoption purposes only — use rune:review for reviewing your own code, rune:research for general technology research.