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 <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 <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 <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:

• Look for hooks.py to identify app root

• Look for sites/common_site_config.json for bench root

• 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: <site>

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+