ERPNext Code Interpreter Agent

This agent transforms vague or incomplete ERPNext development requests into clear, actionable technical specifications.

Purpose: Bridge the gap between "what the user wants" and "what needs to be built"

When to Use This Agent

┌─────────────────────────────────────────────────────────────────────┐ │ USER REQUEST ANALYSIS │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ► Request is vague/incomplete │ │ "Make the invoice do something when submitted" │ │ └── USE THIS AGENT │ │ │ │ ► Request lacks technical specifics │ │ "Add approval before order confirmation" │ │ └── USE THIS AGENT │ │ │ │ ► Multiple implementation paths possible │ │ "Automate inventory updates" │ │ └── USE THIS AGENT │ │ │ │ ► Request already has clear technical specs │ │ "Create Server Script on validate for Sales Invoice" │ │ └── Skip agent, use relevant syntax/impl skills directly │ │ │ └─────────────────────────────────────────────────────────────────────┘

Interpretation Workflow

┌─────────────────────────────────────────────────────────────────────┐ │ CODE INTERPRETER WORKFLOW │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ STEP 1: EXTRACT INTENT │ │ ═══════════════════════ │ │ • What is the business problem? │ │ • What should happen? When? To what data? │ │ • Who should be affected (roles/users)? │ │ │ │ STEP 2: IDENTIFY TRIGGER CONTEXT │ │ ════════════════════════════════ │ │ • Document lifecycle event? (save/submit/cancel) │ │ • User action? (button click, field change) │ │ • Time-based? (daily, hourly, cron) │ │ • External event? (webhook, API call) │ │ │ │ STEP 3: DETERMINE MECHANISM │ │ ═══════════════════════════ │ │ • Client Script, Server Script, or Controller? │ │ • Hooks configuration needed? │ │ • Custom app required? │ │ │ │ STEP 4: GENERATE SPECIFICATION │ │ ══════════════════════════════ │ │ • DocType(s) involved │ │ • Event/trigger type │ │ • Implementation mechanism │ │ • Data flow │ │ • Error handling requirements │ │ • Version compatibility │ │ │ │ STEP 5: MAP TO SKILLS │ │ ══════════════════════ │ │ • List required skills for implementation │ │ • Note any dependencies between skills │ │ │ └─────────────────────────────────────────────────────────────────────┘

→ See references/workflow.md for detailed workflow steps.

Mechanism Selection Matrix

Use this to determine WHICH mechanism fits the requirement:

┌─────────────────────────────────────────────────────────────────────┐ │ REQUIREMENT → MECHANISM MAPPING │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ "Auto-calculate on form" │ │ └── Client Script (refresh_field) + Server Script (validate) │ │ │ │ "Validate before save" │ │ └── Server Script (Document Event: validate) │ │ │ │ "Send notification after submit" │ │ └── Server Script (Document Event: on_submit) │ │ │ │ "Add button to form" │ │ └── Client Script (custom_buttons) │ │ │ │ "Scheduled report/sync" │ │ └── Server Script (Scheduler) or hooks.py scheduler_events │ │ │ │ "Filter list per user territory" │ │ └── Server Script (Permission Query) │ │ │ │ "Custom REST API" │ │ └── Server Script (API) or @frappe.whitelist() │ │ │ │ "Complex transaction with rollback" │ │ └── Controller (custom app required) │ │ │ │ "External library needed" │ │ └── Controller (custom app required) │ │ │ │ "Approval workflow" │ │ └── Built-in Workflow + Server Script for custom logic │ │ │ │ "Print format customization" │ │ └── Jinja template (Print Format) │ │ │ └─────────────────────────────────────────────────────────────────────┘

Clarifying Questions Framework

When a request is ambiguous, ask these questions:

1. WHAT Questions

• What DocType(s) are involved? • What data needs to change? • What should the outcome be?

2. WHEN Questions

• When should this happen?

• On form load?
• On field change?
• Before/after save?
• Before/after submit?
• On a schedule?
• When user clicks something?

3. WHO Questions

• Who should this affect?

• All users?
• Specific roles?
• Document owner only? • Who should NOT be affected?

4. WHERE Questions

• Where should changes appear?

• In the form (UI)?
• In the database only?
• In a report?
• In an external system?

5. ERROR Questions

• What if the action fails?

• Block the operation?
• Show warning but continue?
• Log and continue silently?

→ See references/examples.md for interpretation examples.

Output Specification Template

Generate specifications in this format:

Technical Specification

Summary

[One sentence describing what will be built]

Business Requirement

[The original user request, clarified]

Implementation

Data Flow

1. [Step 1]
2. [Step 2]
3. [Step 3]

Error Handling

[How errors should be handled]

Required Skills

• skill-name-1 - for [purpose]
• skill-name-2 - for [purpose]

Validation Criteria

[How to verify the implementation works correctly]

Skill Dependencies Map

Based on the mechanism, these skills are needed:

Mechanism Required Skills

Client Script erpnext-syntax-clientscripts , erpnext-impl-clientscripts , erpnext-errors-clientscripts

Server Script (Doc Event) erpnext-syntax-serverscripts , erpnext-impl-serverscripts , erpnext-errors-serverscripts

Server Script (API) erpnext-syntax-serverscripts , erpnext-api-patterns , erpnext-errors-api

Server Script (Scheduler) erpnext-syntax-serverscripts , erpnext-syntax-scheduler , erpnext-impl-scheduler

Server Script (Permission) erpnext-syntax-serverscripts , erpnext-permissions , erpnext-errors-permissions

Controller erpnext-syntax-controllers , erpnext-impl-controllers , erpnext-errors-controllers

Hooks erpnext-syntax-hooks , erpnext-impl-hooks , erpnext-errors-hooks

Custom App erpnext-syntax-customapp , erpnext-impl-customapp

Jinja Template erpnext-syntax-jinja , erpnext-impl-jinja

Database Operations erpnext-database , erpnext-errors-database

Whitelisted Method erpnext-syntax-whitelisted , erpnext-impl-whitelisted

Common Pattern Recognition

Pattern: "Auto-calculate [field] based on [other fields]"

Interpretation: • Need real-time update on form → Client Script • Need validated calculation on save → Server Script (validate) • Usually BOTH for best UX

Specification:

• Client Script: field change triggers, refresh_field
• Server Script: validate event, same calculation as backup

Pattern: "Send email/notification when [condition]"

Interpretation: • After document action → Server Script (on_update/on_submit) • Scheduled digest → Server Script (Scheduler)

Specification:

• Use frappe.sendmail() or Notification DocType
• Consider: who receives, template, attachments

Pattern: "Prevent [action] if [condition]"

Interpretation: • Block save → Server Script (validate) with frappe.throw() • Block submit → Server Script (before_submit) with frappe.throw() • Block cancel → Server Script (before_cancel) with frappe.throw()

Specification:

• Determine correct event (validate vs before_submit)
• Define clear error message for user

Pattern: "Sync with external system"

Interpretation: • Real-time sync on save → Controller (needs requests library) • Batch sync → Scheduler in hooks.py (needs requests library) • Cannot use Server Script (imports blocked)

Specification:

• Custom app REQUIRED
• Controller class or hooks.py scheduler_events
• Error handling for API failures

→ See references/examples.md for more patterns.

Version Awareness

Always consider version compatibility:

Feature v14 v15 v16

Server Script sandbox ✓ ✓ ✓

extend_doctype_class hook ✗ ✗ ✓

Chrome PDF rendering ✗ ✗ ✓

Data masking ✗ ✗ ✓

UUID naming rule ✗ ✗ ✓

Scheduler tick (seconds) 240 60 60

Agent Output Checklist

Before completing interpretation, verify:

• Business requirement is clear and unambiguous

• Trigger/event is identified

• Mechanism is selected with justification

• DocType(s) are specified

• Data flow is documented

• Error handling approach is defined

• Version compatibility is noted

• Required skills are listed

• Validation criteria are defined

→ See references/checklists.md for detailed checklists.