Frappe Project Triage

Frappe Project Triage

Quickly analyze a Frappe project to determine its type, installed apps, version, and available tooling.

When to use

• First step when opening a new Frappe project
• Before making any code changes to understand the codebase
• When debugging to determine which apps/versions are involved
• To identify the development environment (Bench vs Frappe Manager)

Inputs required

• Project root path (where apps/, sites/, or app code lives)
• Access to run shell commands (for version checks)

Procedure

0) Identify project structure

Check for these patterns:

| Pattern | Project Type | |---------|--------------| | apps/ + sites/ directories | Bench installation | | docker-compose.yml with frappe | Frappe Manager site | | pyproject.toml or setup.py with frappe | Standalone app | | doctype/ directory | Inside an app module |

1) Detect installed apps

# Inside Bench/FM shell
bench --site  list-apps

# Or check apps directory
ls apps/

2) Check Frappe version

# Inside Bench/FM shell
bench version

# Or check from Python
bench --site  console
>>> frappe.__version__

3) Identify tooling

| File/Directory | Tooling | |----------------|---------| | Procfile | Standard bench | | docker-compose.yml | Docker/FM | | cypress/ | UI testing available | | .github/workflows/ | CI configured | | package.json with @frappe/* | JS build tooling |

4) Check development mode

# Check site config
bench --site  console
>>> frappe.conf.developer_mode

Verification

• [ ] Project type identified (bench/FM/standalone app)
• [ ] Installed apps listed
• [ ] Frappe version known
• [ ] Development mode status confirmed
• [ ] Available tooling documented

Failure modes / debugging

• No site found: May be inside an app directory, navigate to bench root
• bench command not found: Not in bench environment, use fm shell or activate venv
• Permission errors: Check if running as correct user

Escalation

If project structure is unclear:

1. Look for hooks.py to identify app root
2. Look for sites/common_site_config.json for bench root
3. Check git remote for app repository identification

Output format

After triage, document:

Project Type: [bench|frappe-manager|standalone-app]
Frappe Version: X.Y.Z
Installed Apps: [list]
Developer Mode: [yes|no]
Tooling: [list]
Site Name: 

Use this output to route to the appropriate skill:

• DocType work → frappe-doctype-development
• API work → frappe-api-development
• Testing → frappe-testing
• Enterprise patterns → frappe-enterprise-patterns

Guardrails

• Never modify code before completing triage - understand the project first
• Check for custom apps that may override standard behavior
• Verify site exists before running site-specific commands
• Check developer_mode before making schema changes (required for DocType modifications)
• Note Node.js version - frontend builds require compatible Node (typically 18+ for v15)

Common Mistakes

| Mistake | Why It Fails | Fix | |---------|--------------|-----| | Running bench migrate without site | Affects wrong/default site | Always use --site sitename | | Assuming ERPNext is installed | Import errors, missing DocTypes | Check list-apps output first | | Missing FM shell context | bench commands not found | Use fm shell sitename first | | Wrong directory level | Commands fail silently | Navigate to bench root (where apps/ exists) | | Ignoring custom app overrides | Unexpected behavior | Check hooks.py for overrides | | Not checking Python version | Syntax/compatibility errors | Verify Python >= 3.10 for v15+ |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lubusIN
• Source: lubusIN/frappe-skills
• License: MIT

Install and usage instructions live in the source repository linked above.