Migrating to Latest Template Version
Template remote: git@github.com:decocms/mcp-app.git. Fetch latest, analyze changes with parallel subagents, present migration plan, apply after user approval.
Workflow
- Fetch template remote
- Find base commit (when user forked/cloned)
- Get changelog (base → latest)
- Dispatch 5 analysis subagents in parallel
- Present migration plan — wait for user approval
- Apply changes (subagents per category)
- Verify:
bun install && bun run check && bun run ci:check && bun run build && bun test
Step 1–3: Setup & Changelog
git remote add template git@github.com:decocms/mcp-app.git 2>/dev/null || true
git fetch template main
# Find base commit (try in order):
git merge-base HEAD template/main # A: shared history
git log --oneline --reverse | head -5 # B: check initial commit
# C: ask user which version they started from
# Changelog:
git log --oneline <base>..template/main
git diff <base>..template/main --stat
If no common ancestor (GitHub "Use this template"), diff full template against user's code file-by-file.
Step 4: Dispatch 5 Analysis Subagents (ALL IN PARALLEL)
Each subagent compares <base>..template/main for its file category, checks if user also modified those files, and recommends APPLY (no conflict), MERGE (both sides changed), or SKIP (user deleted/replaced). Output as markdown table.
| # |
Category |
Files to Analyze |
| 1 |
Infrastructure |
vite.config.ts, tsconfig.json, biome.json, package.json scripts, .github/workflows/*, scripts/*, index.html |
| 2 |
Dependencies |
package.json deps/devDeps — new, removed, version bumps (flag breaking major bumps) |
| 3 |
Framework Core |
web/context.tsx, web/router.tsx, web/types.ts, web/app.tsx, api/main.ts, api/types/env.ts |
| 4 |
UI Components |
web/components/ui/*, web/lib/*, web/hooks/*, CSS files (shadcn = usually safe to replace) |
| 5 |
Docs & Skills |
CLAUDE.md, AGENTS.md, README.md, .claude/skills/**/* |
Step 5: Migration Plan
Compile subagent results into:
## Migration Plan: <base_short> → <latest_short>
- X commits, Y files changed
1. **Auto-apply** (no conflicts): [files]
2. **Merge required** (user also modified): [files]
3. **Skip** (user deleted/replaced): [files]
4. **Manual review** (breaking changes): [files]
### Breaking Changes: [list]
Present to user. Do NOT apply until approved.
Step 6: Apply Changes
Apply order: deps → infra → framework → UI → docs
- Auto-apply:
git checkout template/main -- <file>
- Merge-required: Dispatch subagent per file — read user's version, template's version, and base version. Merge preserving user's custom additions (tools, routes, resources) while adopting template structural updates.
- package.json: Merge deps (keep user's custom, update template's). Run
bun install.
Step 7: Verify & Fix
bun install && bun run check && bun run ci:check && bun run build && bun test
If checks fail, dispatch a subagent to diagnose: template incompatibility, bad merge, or missing dep.
File Categories Reference
| Category |
Files |
Strategy |
| Infrastructure |
vite.config.ts, tsconfig.json, biome.json, index.html |
Replace |
| Build Scripts |
package.json scripts |
Merge (user adds TOOL= entries) |
| Dependencies |
package.json deps/devDeps |
Merge (keep user's, update template's) |
| Framework Core |
web/context.tsx, web/router.tsx, web/types.ts, web/app.tsx |
Merge carefully |
| Server Core |
api/main.ts, api/types/env.ts |
Merge carefully |
| UI Components |
web/components/ui/*, web/lib/* |
Replace (shadcn standard) |
| Example Tool |
api/tools/hello.ts, web/tools/hello/ |
Skip if user deleted |
| User Tools |
api/tools/*, web/tools/* (non-hello) |
Never overwrite |
| CI/CD |
.github/workflows/* |
Replace unless customized |
| Docs |
CLAUDE.md, README.md |
Merge |
| Skills |
.claude/skills/* |
Add new, don't overwrite |
Common Mistakes
| Mistake |
Fix |
| Overwriting TOOL_PAGES in router.tsx |
Merge: keep user's entries, adopt structural changes |
| Replacing package.json entirely |
Merge deps/scripts separately |
| Losing user's resources in api/main.ts |
Merge: preserve user's resource registrations |
Not running bun install after dep changes |
Always install before type-checking |
| Restoring files user intentionally deleted |
Check git log for deletion before restoring |
1---2name: migrate-template-23description: Use when the user asks to update their MCP App to the latest template version, sync with upstream template, pull in template changes, upgrade the template, or migrate to a newer version of the MCP App template.4---56# Migrating to Latest Template Version78Template remote: `git@github.com:decocms/mcp-app.git`. Fetch latest, analyze changes with parallel subagents, present migration plan, apply after user approval.910## Workflow11121. Fetch template remote132. Find base commit (when user forked/cloned)143. Get changelog (base → latest)154. **Dispatch 5 analysis subagents in parallel**165. Present migration plan — **wait for user approval**176. Apply changes (subagents per category)187. Verify: `bun install && bun run check && bun run ci:check && bun run build && bun test`1920## Step 1–3: Setup & Changelog2122```bash23git remote add template git@github.com:decocms/mcp-app.git 2>/dev/null || true24git fetch template main2526# Find base commit (try in order):27git merge-base HEAD template/main # A: shared history28git log --oneline --reverse | head -5 # B: check initial commit29# C: ask user which version they started from3031# Changelog:32git log --oneline <base>..template/main33git diff <base>..template/main --stat34```3536If no common ancestor (GitHub "Use this template"), diff full template against user's code file-by-file.3738## Step 4: Dispatch 5 Analysis Subagents (ALL IN PARALLEL)3940Each subagent compares `<base>..template/main` for its file category, checks if user also modified those files, and recommends **APPLY** (no conflict), **MERGE** (both sides changed), or **SKIP** (user deleted/replaced). Output as markdown table.4142| # | Category | Files to Analyze |43|---|----------|-----------------|44| 1 | **Infrastructure** | `vite.config.ts`, `tsconfig.json`, `biome.json`, `package.json` scripts, `.github/workflows/*`, `scripts/*`, `index.html` |45| 2 | **Dependencies** | `package.json` deps/devDeps — new, removed, version bumps (flag breaking major bumps) |46| 3 | **Framework Core** | `web/context.tsx`, `web/router.tsx`, `web/types.ts`, `web/app.tsx`, `api/main.ts`, `api/types/env.ts` |47| 4 | **UI Components** | `web/components/ui/*`, `web/lib/*`, `web/hooks/*`, CSS files (shadcn = usually safe to replace) |48| 5 | **Docs & Skills** | `CLAUDE.md`, `AGENTS.md`, `README.md`, `.claude/skills/**/*` |4950## Step 5: Migration Plan5152Compile subagent results into:5354```markdown55## Migration Plan: <base_short> → <latest_short>56- X commits, Y files changed571. **Auto-apply** (no conflicts): [files]582. **Merge required** (user also modified): [files]593. **Skip** (user deleted/replaced): [files]604. **Manual review** (breaking changes): [files]61### Breaking Changes: [list]62```6364**Present to user. Do NOT apply until approved.**6566## Step 6: Apply Changes6768### Apply order: deps → infra → framework → UI → docs6970- **Auto-apply**: `git checkout template/main -- <file>`71- **Merge-required**: Dispatch subagent per file — read user's version, template's version, and base version. Merge preserving user's custom additions (tools, routes, resources) while adopting template structural updates.72- **package.json**: Merge deps (keep user's custom, update template's). Run `bun install`.7374## Step 7: Verify & Fix7576```bash77bun install && bun run check && bun run ci:check && bun run build && bun test78```7980If checks fail, dispatch a subagent to diagnose: template incompatibility, bad merge, or missing dep.8182## File Categories Reference8384| Category | Files | Strategy |85|----------|-------|----------|86| Infrastructure | `vite.config.ts`, `tsconfig.json`, `biome.json`, `index.html` | Replace |87| Build Scripts | `package.json` scripts | Merge (user adds TOOL= entries) |88| Dependencies | `package.json` deps/devDeps | Merge (keep user's, update template's) |89| Framework Core | `web/context.tsx`, `web/router.tsx`, `web/types.ts`, `web/app.tsx` | Merge carefully |90| Server Core | `api/main.ts`, `api/types/env.ts` | Merge carefully |91| UI Components | `web/components/ui/*`, `web/lib/*` | Replace (shadcn standard) |92| Example Tool | `api/tools/hello.ts`, `web/tools/hello/` | Skip if user deleted |93| User Tools | `api/tools/*`, `web/tools/*` (non-hello) | Never overwrite |94| CI/CD | `.github/workflows/*` | Replace unless customized |95| Docs | `CLAUDE.md`, `README.md` | Merge |96| Skills | `.claude/skills/*` | Add new, don't overwrite |9798## Common Mistakes99100| Mistake | Fix |101|---------|-----|102| Overwriting TOOL_PAGES in router.tsx | Merge: keep user's entries, adopt structural changes |103| Replacing package.json entirely | Merge deps/scripts separately |104| Losing user's resources in api/main.ts | Merge: preserve user's resource registrations |105| Not running `bun install` after dep changes | Always install before type-checking |106| Restoring files user intentionally deleted | Check git log for deletion before restoring |
decocms