frappe-agent-migrator

Name: frappe-agent-migrator
Author: Impertio-Studio

151stars49forks

How to install frappe-agent-migrator?

impertio-studio/frappe_claude_skill_package/frappe-agent-migrator

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-agent-migrator

Installs into the current project.

Summary

Use when migrating a Frappe app between major versions, detecting breaking API changes, or resolving post-migration errors. Prevents failed migrations from undetected deprecated APIs, removed methods, and changed function signatures. Covers breaking change detection v14-v15-v16,

Files · 1

View on GitHub

SKILL.md

1	# Version Migration Assistant
2
3	Systematically plans and executes Frappe/ERPNext version migrations by analyzing breaking changes, scanning custom code for compatibility issues, and generating migration plans.
4
5	Purpose: Prevent failed migrations by detecting every breaking change BEFORE upgrading.
6
7	## When to Use This Agent
8
9	```
10	MIGRATION TRIGGER
11	\|
12	+-- Planning a version upgrade
13	\| "We need to go from v14 to v15"
14	\| --> USE THIS AGENT
15	\|
16	+-- Post-upgrade errors
17	\| "Everything broke after bench update"
18	\| --> USE THIS AGENT (Step 2-5 for diagnosis)
19	\|
20	+-- Checking custom app compatibility
21	\| "Will our custom app work on v16?"
22	\| --> USE THIS AGENT (Step 3 for code scan)
23	\|
24	+-- Already mid-migration with issues
25	\| "bench migrate fails with errors"
26	\| --> USE THIS AGENT + frappe-agent-debugger
27	```
28
29	## Migration Workflow
30
31	```
32	STEP 1: IDENTIFY MIGRATION PATH
33	Source version → Target version (NEVER skip major versions)
34
35	STEP 2: CHECK BREAKING CHANGES
36	Apply breaking changes database for each version jump
37
38	STEP 3: SCAN CUSTOM CODE
39	Grep for deprecated patterns in all custom apps
40
41	STEP 4: GENERATE MIGRATION PLAN
42	Backup → Staging → Test → Production sequence
43
44	STEP 5: GENERATE PATCH LIST
45	Specific code changes needed per custom app
46	```
47
48	See [references/workflow.md](references/workflow.md) for detailed steps.
49
50	## Step 1: Migration Path Rules
51
52	NEVER skip major versions. ALWAYS migrate sequentially:
53
54	\| Source \| Target \| Path \|
55	\|--------\|--------\|------\|
56	\| v14 \| v15 \| v14 → v15 \|
57	\| v14 \| v16 \| v14 → v15 → v16 \|
58	\| v15 \| v16 \| v15 → v16 \|
59
60	### Version Identification
61	```bash
62	# Check current versions
63	bench version
64	# Output shows: frappe X.Y.Z, erpnext X.Y.Z
65
66	# Check available versions
67	cd apps/frappe && git tag \| grep "^v1[456]" \| tail -5
68	```
69
70	## Step 2: Breaking Changes Summary
71
72	### v14 → v15 Breaking Changes
73
74	\| Category \| Change \| Impact \| Detection Pattern \|
75	\|----------\|--------\|--------\|-------------------\|
76	\| Scheduler \| Tick interval 240s → 60s \| Jobs may run more frequently \| Review `scheduler_events` \|
77	\| Background Jobs \| `job_id` deduplication added \| Duplicate jobs now prevented \| Check `frappe.enqueue()` calls \|
78	\| Web Views \| Workspace replaces Module Def pages \| Custom module pages break \| Grep for `Module Def` references \|
79	\| Print Format \| HTML to PDF engine changes \| Print layout differences \| Test all print formats \|
80	\| Database \| MariaDB 10.6+ required \| Server prerequisite \| Check `mysql --version` \|
81	\| Python \| Python 3.10+ required \| Syntax/library compatibility \| Check `python3 --version` \|
82	\| API \| `frappe.client.get_list` signature change \| Custom API calls may fail \| Grep for `frappe.client.get_list` \|
83	\| Permissions \| Stricter permission checks on API \| Guest access may break \| Check `allow_guest=True` usage \|
84	\| Assets \| New frontend build system \| Custom JS bundles may break \| Test `bench build` \|
85	\| Hooks \| `boot_session` hook changes \| Custom boot data may fail \| Grep for `boot_session` \|
86	\| Naming \| Some naming series changes \| Document names may differ \| Review `autoname` settings \|
87	\| Report \| Report Builder changes \| Custom reports may need updates \| Test all Script Reports \|
88
89	### v15 → v16 Breaking Changes
90
91	\| Category \| Change \| Impact \| Detection Pattern \|
92	\|----------\|--------\|--------\|-------------------\|
93	\| DocType Extension \| `extend_doctype_class` replaces `doc_events` override \| Controller overrides need refactoring \| Grep for `doc_events` with method override \|
94	\| Type Annotations \| Type hints now best practice \| Code style change \| Not breaking, but recommended \|
95	\| Chrome PDF \| New PDF engine (Chrome-based) \| Print format rendering changes \| Test all print formats \|
96	\| Data Masking \| New privacy feature \| PII fields need configuration \| Review sensitive fields \|
97	\| UUID Naming \| New `uuid` naming rule \| Naming logic changes \| Check `autoname` settings \|
98	\| Python \| Python 3.11+ required \| Library compatibility \| Check `python3 --version` \|
99	\| Node.js \| Node 18+ required \| Build system prerequisite \| Check `node --version` \|
100	\| Redis \| Redis 7+ required \| Cache/queue compatibility \| Check `redis-server --version` \|
101	\| Deprecated APIs \| Several APIs removed \| Code using removed APIs fails \| See breaking-changes.md \|
102	\| Workflow \|

People who liked this also viewed

6 picks

Type

frappe-agent-migrator

151stars49forks

View on GitHub

How to install frappe-agent-migrator?

impertio-studio/frappe_claude_skill_package/frappe-agent-migrator

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-agent-migrator

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Version Migration Assistant
2
3	Systematically plans and executes Frappe/ERPNext version migrations by analyzing breaking changes, scanning custom code for compatibility issues, and generating migration plans.
4
5	Purpose: Prevent failed migrations by detecting every breaking change BEFORE upgrading.
6
7	## When to Use This Agent
8
9	```
10	MIGRATION TRIGGER
11	\|
12	+-- Planning a version upgrade
13	\| "We need to go from v14 to v15"
14	\| --> USE THIS AGENT
15	\|
16	+-- Post-upgrade errors
17	\| "Everything broke after bench update"
18	\| --> USE THIS AGENT (Step 2-5 for diagnosis)
19	\|
20	+-- Checking custom app compatibility
21	\| "Will our custom app work on v16?"
22	\| --> USE THIS AGENT (Step 3 for code scan)
23	\|
24	+-- Already mid-migration with issues
25	\| "bench migrate fails with errors"
26	\| --> USE THIS AGENT + frappe-agent-debugger
27	```
28
29	## Migration Workflow
30
31	```
32	STEP 1: IDENTIFY MIGRATION PATH
33	Source version → Target version (NEVER skip major versions)
34
35	STEP 2: CHECK BREAKING CHANGES
36	Apply breaking changes database for each version jump
37
38	STEP 3: SCAN CUSTOM CODE
39	Grep for deprecated patterns in all custom apps
40
41	STEP 4: GENERATE MIGRATION PLAN
42	Backup → Staging → Test → Production sequence
43
44	STEP 5: GENERATE PATCH LIST
45	Specific code changes needed per custom app
46	```
47
48	See [references/workflow.md](references/workflow.md) for detailed steps.
49
50	## Step 1: Migration Path Rules
51
52	NEVER skip major versions. ALWAYS migrate sequentially:
53
54	\| Source \| Target \| Path \|
55	\|--------\|--------\|------\|
56	\| v14 \| v15 \| v14 → v15 \|
57	\| v14 \| v16 \| v14 → v15 → v16 \|
58	\| v15 \| v16 \| v15 → v16 \|
59
60	### Version Identification
61	```bash
62	# Check current versions
63	bench version
64	# Output shows: frappe X.Y.Z, erpnext X.Y.Z
65
66	# Check available versions
67	cd apps/frappe && git tag \| grep "^v1[456]" \| tail -5
68	```
69
70	## Step 2: Breaking Changes Summary
71
72	### v14 → v15 Breaking Changes
73
74	\| Category \| Change \| Impact \| Detection Pattern \|
75	\|----------\|--------\|--------\|-------------------\|
76	\| Scheduler \| Tick interval 240s → 60s \| Jobs may run more frequently \| Review `scheduler_events` \|
77	\| Background Jobs \| `job_id` deduplication added \| Duplicate jobs now prevented \| Check `frappe.enqueue()` calls \|
78	\| Web Views \| Workspace replaces Module Def pages \| Custom module pages break \| Grep for `Module Def` references \|
79	\| Print Format \| HTML to PDF engine changes \| Print layout differences \| Test all print formats \|
80	\| Database \| MariaDB 10.6+ required \| Server prerequisite \| Check `mysql --version` \|
81	\| Python \| Python 3.10+ required \| Syntax/library compatibility \| Check `python3 --version` \|
82	\| API \| `frappe.client.get_list` signature change \| Custom API calls may fail \| Grep for `frappe.client.get_list` \|
83	\| Permissions \| Stricter permission checks on API \| Guest access may break \| Check `allow_guest=True` usage \|
84	\| Assets \| New frontend build system \| Custom JS bundles may break \| Test `bench build` \|
85	\| Hooks \| `boot_session` hook changes \| Custom boot data may fail \| Grep for `boot_session` \|
86	\| Naming \| Some naming series changes \| Document names may differ \| Review `autoname` settings \|
87	\| Report \| Report Builder changes \| Custom reports may need updates \| Test all Script Reports \|
88
89	### v15 → v16 Breaking Changes
90
91	\| Category \| Change \| Impact \| Detection Pattern \|
92	\|----------\|--------\|--------\|-------------------\|
93	\| DocType Extension \| `extend_doctype_class` replaces `doc_events` override \| Controller overrides need refactoring \| Grep for `doc_events` with method override \|
94	\| Type Annotations \| Type hints now best practice \| Code style change \| Not breaking, but recommended \|
95	\| Chrome PDF \| New PDF engine (Chrome-based) \| Print format rendering changes \| Test all print formats \|
96	\| Data Masking \| New privacy feature \| PII fields need configuration \| Review sensitive fields \|
97	\| UUID Naming \| New `uuid` naming rule \| Naming logic changes \| Check `autoname` settings \|
98	\| Python \| Python 3.11+ required \| Library compatibility \| Check `python3 --version` \|
99	\| Node.js \| Node 18+ required \| Build system prerequisite \| Check `node --version` \|
100	\| Redis \| Redis 7+ required \| Cache/queue compatibility \| Check `redis-server --version` \|
101	\| Deprecated APIs \| Several APIs removed \| Code using removed APIs fails \| See breaking-changes.md \|
102	\| Workflow \|

People who liked this also viewed

6 picks

Type