/frappe-agent-interpreter

name: frappe-agent-interpreter
description: >
  Use when receiving vague or unclear ERPNext/Frappe development requests
  that need interpretation. Transforms requirements like 'make invoice
  auto-calculate' or 'add approval workflow' into concrete technical
  specifications. Determines which Frappe mechanisms to use and maps to
  the full 61-skill catalog. Keywords: vague requirement, clarify scope,
  translate business need, technical spec, implementation plan,
  what does this mean, unclear requirement, translate to code, how to build this.
license: MIT
compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16."
metadata:
  author: OpenAEC-Foundation
  version: "2.0"

Frappe Code Interpreter Agent

Transforms vague or incomplete Frappe/ERPNext development requests into clear, actionable technical specifications mapped to the full 61-skill catalog.

**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 has clear technical specs already
|   "Create Server Script on validate for Sales Invoice"
|   --> Skip agent, use relevant frappe-* skills directly

Interpretation 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?
  - v16 extend_doctype_class applicable?

STEP 4: GENERATE SPECIFICATION
  - DocType(s), event/trigger, mechanism, data flow
  - Error handling requirements
  - Version compatibility (v14/v15/v16)

STEP 5: MAP TO SKILLS
  - List required frappe-* skills from full catalog
  - Note dependencies between skills

See [references/workflow.md](references/workflow.md) for detailed steps.

Mechanism Selection Matrix

| Requirement Pattern | Mechanism | Custom App? | |---------------------|-----------|:-----------:| | "Auto-calculate on form" | Client Script + Server Script | No | | "Validate before save" | Server Script (validate) | No | | "Send notification after submit" | Server Script (on_submit) | No | | "Add button to form" | Client Script | No | | "Scheduled report/sync" | hooks.py scheduler_events | Yes | | "Filter list per user" | Server Script (Permission Query) | No | | "Custom REST API" | Server Script (API) or @frappe.whitelist() | Depends | | "Complex transaction with rollback" | Controller | Yes | | "External library needed (requests)" | Controller | Yes | | "Approval workflow" | Built-in Workflow + optional Server Script | No | | "Print format customization" | Jinja template (Print Format) | No | | "Custom report" | Script Report or Query Report | Depends | | "Background processing" | frappe.enqueue() | Yes | | "File upload handling" | Controller + File hooks | Yes | | "Cache invalidation" | Cache API + hooks | Yes | | "Website/portal page" | Web template + routing | Yes | | "UI component (dashboard, etc.)" | Page or Custom Page | Yes |

Clarifying Questions Framework

1. WHAT Questions

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

2. WHEN Questions

• On form load? On field change? Before/after save?
• Before/after submit? On a schedule? Button click?

3. WHO Questions

• All users? Specific roles? Document owner only?

4. WHERE Questions

• In the form (UI)? Database only? Report? External system?

5. ERROR Questions

• Block the operation? Show warning? Log silently?

6. VERSION Questions (v16 considerations)

• Target single version or multi-version compatibility?
• Can we use `extend_doctype_class` (v16) or need `doc_events` (v14+)?
• Type annotations desired? (v16 best practice)

Output Specification Template

ALWAYS generate specifications in this format:

## Technical Specification

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

### Business Requirement
[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]

### Error Handling
[Strategy]

### Required Skills
- [ ] frappe-skill-name - for [purpose]

### Validation Criteria
[How to verify it works]

Complete Skill Catalog (61 skills)

Syntax Layer (11 skills)

| Skill | Use For | |-------|---------| | `frappe-syntax-clientscripts` | Client Script JS syntax | | `frappe-syntax-serverscripts` | Server Script Python sandbox syntax | | `frappe-syntax-controllers` | Controller class syntax | | `frappe-syntax-hooks` | hooks.py configuration syntax | | `frappe-syntax-hooks-events` | Document event hook syntax | | `frappe-syntax-whitelisted` | @frappe.whitelist() syntax | | `frappe-syntax-jinja` | Jinja template syntax | | `frappe-syntax-scheduler` | Scheduler/enqueue syntax | | `frappe-syntax-customapp` | App structure syntax | | `frappe-syntax-doctypes` | DocType JSON definition syntax | | `frappe-syntax-reports` | Report definition syntax |

Core Layer (7 skills)

| Skill | Use For | |-------|---------| | `frappe-core-database` | Database operations, ORM, raw SQL | | `frappe-core-permissions` | Permission system, roles, rules | | `frappe-core-api` | REST API, resource API |