Merges a completed sub-project back into its parent. Renumbers research, reconciles docs, merges DB. Invoke with /sub-project-merge.
Merges a completed sub-project back into its parent project — research artifacts, documents, artifact DB records, source files, and all. Generates a merge-specific plan at runtime, presents it for approval, then executes in safety-tiered batches so nothing is lost or overwritten without confirmation.
This skill exists because sub-projects accumulate their own research numbering, features, plan entries, and artifact DB records that must be reconciled with the parent's state. Manual merging is error-prone — renumbering alone requires scanning both trees, remapping folder names, summary files, internal references, and DB labels. This skill automates all of it.
Context-window strategy: Only Phases 0, 2, 3, and 6 stay inline (detection, merge plan generation, approval gate, destructive confirmation). All heavy work delegates to subagents.
| Input | Source | Required |
|---|---|---|
| Sub-project path | User prompt or auto-detect | Yes |
| Parent project root | cwd or inferred from symlinks | Yes |
Sub-project architecture.md |
| Sub-project root |
| Yes (Section 11: Parent Modifications) |
Sub-project features.md | Sub-project root | Yes |
Sub-project build-plan.md | Sub-project root | Yes |
Sub-project project-context.md | Sub-project root | No |
Sub-project todo.md | Sub-project root | No |
Sub-project cnotes.md | Sub-project root | No |
Parent features.md | Parent root | Yes |
Parent project-plan.md | Parent root | Yes |
Parent project-context.md | Parent root | No |
merge-plan.md in the sub-project directory — runtime-generated merge plan
with inventory, renumbering map, document diffs, conflict list, risk assessmentfeatures.md, project-plan.md, project-context.md,
todo.md, cnotes.md — reconciled with sub-project stateproject.db
with sub:<name>/ namespace prefixartifacts/archived-sub-projects/<name>/db_upsert 'sub-project-merge' 'merge' '<sub-project-name>' "$SUMMARY"Identify the sub-project to merge.
./<name>/architecture.md (subdirectory mode)git worktree list output matching sub/<name> (worktree mode)architecture.md and a symlinked coterie.md). Present candidates:
"Found sub-projects: auth-service/, payment-api/. Which one to merge?"
Detect merge mode:
git worktree list shows the sub-project path → will use
git merge + git worktree removeDetermine parent root:
Exit condition: Sub-project path confirmed, parent root identified, merge mode (worktree vs subdirectory) determined.
Dispatch a Sonnet subagent to inventory the sub-project. Read agents/scanner.md
for the prompt template — fill in placeholders before spawning.
The scanner:
artifacts/research/ folders and summariesartifacts/project.dbarchitecture.md Section 11 ("Parent Modifications") — the explicit
list of parent files this sub-project intended to modifyfeatures.md — extracts feature names and statusesbuild-plan.md — extracts work unit completion statusRead the scanner output when complete.
Exit condition: Inventory file exists with all files categorized, parent modification list extracted, completion status assessed.
Build merge-plan.md in the sub-project directory. This is the plan for THIS
specific merge — not a generic template.
Read references/merge-checklist.md for the exhaustive checklist to follow.
Read references/renumbering-protocol.md for the research renumbering rules.
artifacts/research/ for existing numbered folders.D suffix): e.g., folders 001D-009 → max = 9.artifacts/research/ for its numbered folders.sub:001D → parent:010D (preserves D suffix)sub:002 → parent:011 (no D stays no D)For each document that will be merged, generate a diff preview:
From scanner's Section 11 extraction, list:
Count records in sub-project DB. List skill/phase namespaces found. Note any that would collide with parent DB namespaces (after prefixing).
List all symlinks to remove, the sub-project directory archive path
(artifacts/archived-sub-projects/<name>/), and worktree teardown steps if
applicable.
Rate the merge:
Write all of the above to <sub-project>/merge-plan.md.
Exit condition: merge-plan.md exists with all 6 sections populated.
Present the merge plan to the user. Show:
Merge Plan:
<name>→ parentRisk: LOW / MEDIUM / HIGH Research to renumber: N folders (001D→010D, 002→011, ...) Features to merge: N (X done, Y in-progress) Code files to transfer: N files Artifact DB records: N records Conflicts detected: N (list if any)
Review the full plan at
<sub-project>/merge-plan.md. Proceed? (yes / modify / abort)
If "modify" — ask what to change, regenerate affected sections. If "abort" — exit cleanly. If "yes" — proceed to Phase 4.
Exit condition: User explicitly approves the merge.
This phase makes only additive changes to the parent. Nothing is deleted.
Dispatch a Sonnet subagent for document merging. Read agents/doc-merger.md
for the prompt template.
The doc-merger receives merge-plan.md and both project roots. It:
[sub:<name>] in Notes.project-context.md. Updates Tech Stack if sub-project
introduced new dependencies. Appends changelog entry.work_scope with
[sub:<name>].All merges are edit-in-place using the Edit tool — never overwrite entire files.
Read the subagent output. Verify each document was updated.
Execute the renumbering map from merge-plan.md:
sub/artifacts/research/001D/ → parent/artifacts/research/010D/sub/artifacts/research/summary/001D-topic.md → parent/artifacts/research/summary/010D-topic.md001D)
and replace with the new number (010D). Be precise — match 001D as a
whole token, not as a substring.Exit condition: All parent docs updated. Research artifacts renumbered and present in parent. No stale references to old numbers.
Dispatch a Sonnet subagent for DB merging. Read agents/db-merger.md for the
prompt template.
The db-merger:
artifacts/project.db, sub-project artifacts/project.db)skill field with sub:<name>/ (e.g., research-execute → sub:auth-service/research-execute)label field where it contains a research numberartifacts_fts triggersRead the subagent output. Verify record counts.
If the merge plan lists source files to transfer:
For worktree mode, skip this step — code transfer happens via git merge in
Phase 6.
Exit condition: Artifact DB merged. Source files transferred (or conflicts resolved). Subagent output verified.
Present the cleanup plan and get explicit confirmation:
Ready to clean up. These actions are destructive:
Batch A (safe — no data loss):
- Remove symlinks: coterie.md, [lint configs], artifacts/db.sh
Batch B (archive — data preserved):
- Archive sub-project to
artifacts/archived-sub-projects/<name>/Batch C (destructive — worktree only):
git worktree remove <path>git branch -d sub/<name>(only if fully merged)Proceed with cleanup? (yes / keep-sub-project / abort)
If "keep-sub-project" — skip Batch B and C, only run Batch A (symlink removal). If "abort" — leave everything as-is. If "yes":
Batch A: Remove all symlinks in the sub-project directory. These point to parent files that still exist — removing the link is safe.
Batch B:
artifacts/archived-sub-projects/ in the parent if it doesn't existartifacts/archived-sub-projects/<name>/merge-plan.md from the archive (it was a working document)Batch C (worktree mode only):
git merge sub/<name> — if conflicts, present to user for resolutiongit worktree remove <path>git branch -d sub/<name> — only if the branch is fully mergedExit condition: Symlinks removed. Sub-project archived (or kept). Worktree cleaned up (if applicable).
Run post-merge validation:
artifacts/research/summary/ should have
continuous numbering (no gaps from renumbering).features.md has a valid
status. No duplicate feature rows.project-plan.md has no work units referencing
the sub-project as a dependency that's still pending.sqlite3 parent/artifacts/project.db "SELECT count(*) FROM artifacts WHERE skill LIKE 'sub:<name>/%';" returns the expected record count.Store merge summary in artifact DB:
source artifacts/db.sh
db_upsert 'sub-project-merge' 'merge' '<sub-project-name>' "$SUMMARY"
Present the summary:
Merge complete:
<name>→ parent
- Research renumbered: 001D→010D, 002→011 (N folders)
- Features merged: N features (X done, Y in-progress)
- Plan updated: N work units marked complete
- DB records transferred: N records under
sub:<name>/namespace- Code files transferred: N files (M conflicts resolved)
- Archived to:
artifacts/archived-sub-projects/<name>/Suggested follow-ups:
/compliance-review— verify parent conventions after merge/drift-review— check docs match current code state/evolve— update project-context.md if scope changed
Log to cnotes.md per cross-cutting rules.
Read these files only when needed for the relevant phase:
references/merge-checklist.md — exhaustive merge checklist with action, risk level, and rollback step for every operation. Used in Phase 2 when generating merge-plan.md.references/renumbering-protocol.md — step-by-step research artifact renumbering rules including edge cases (no research, gaps, D vs non-D, internal cross-refs). Used in Phase 2.1 and Phase 4.2.User: "/sub-project-merge auth-service"
→ Detect auth-service/ subdirectory. Scan. Generate merge plan showing 2 research
folders to renumber (001D→010D, 002→011), 4 features to merge (3 done, 1 in-progress),
6 source files to transfer. User approves. Merge docs, renumber research, transfer
code, archive sub-project.
User: "Merge the payment sub-project back"
→ Detect payment/ with worktree mode (git worktree list shows sub/payment). Scan.
Generate merge plan. Execute: doc merge, research renumber, DB merge. Cleanup:
git merge sub/payment, git worktree remove, git branch -d. Archive.
User: "/sub-project-merge frontend-redesign --keep"
→ Full merge but skip Batch B/C cleanup. Sub-project directory stays in place.
Symlinks removed. Useful for long-running sub-projects that aren't done yet
but have deliverables ready to merge.
User: "I finished the API rewrite sub-project, merge it in"
→ Auto-detect sub-project. Scanner finds 0 research folders, 8 features all done,
12 source files, HIGH risk (modifies shared types). Merge plan flags 2 conflicts
in parent types/. User resolves inline. Clean merge.
Before completing, read and follow ../references/cross-cutting-rules.md.