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

code

┌─────────────────────────────────────────────────────────────────────┐
│ 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

┌─────────────────────────────────────────────────────────────────────┐
│                    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:

code

┌─────────────────────────────────────────────────────────────────────┐
│ 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

code

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

2. WHEN Questions

code

• 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

code

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

4. WHERE Questions

code

• Where should changes appear?
  - In the form (UI)?
  - In the database only?
  - In a report?
  - In an external system?

5. ERROR Questions

code

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

markdown

## Technical Specification

### Summary
[One sentence describing what will be built]

### Business Requirement
[The original user request, clarified]

### Implementation

| Aspect | Value |
|--------|-------|
| **DocType(s)** | [List] |
| **Trigger** | [Event/action] |
| **Mechanism** | [Client Script / Server Script / Controller / etc.] |
| **Version** | [v14 / v15 / v16 / all] |

### 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]"

code

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]"

code

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]"

code

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"

code

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.