erpnext-code-interpreter

name

erpnext-code-interpreter

description

Intelligent agent for interpreting vague ERPNext development requests and producing concrete technical specifications. Use when receiving unclear requirements like 'make invoice auto-calculate', 'add approval workflow', 'sync with external system'. Triggers: user gives vague requirement, need to clarify scope, translate business need to technical spec, determine which ERPNext mechanisms to use, create implementation plan.

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

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

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.