View source for Proceedural Agentic Development Methodology 260304


= PAD-Driven ERPNext Implementation Strategy for Comfac IT =

== 1. Problem Statement ==
Current State: Implementation and configuration of Frappe/ERPNext are traditionally slow, requiring deep domain knowledge of both the business processes and the proprietary Frappe framework. Objective: Drastically improve the speed of implementation, configuration, and deployment in Frappe ERPNext for the Comfac IT team using Procedural Agentic Development (PAD) tools (e.g., OpenCode, ClaudeCode).

== 2. Definition of Terms ==

* PAD (Procedural Agentic Development): A workflow utilizing autonomous AI coding agents (e.g., OpenCode, ClaudeCode) to automate software development, configuration, and deployment. The process involves the agent continuously referencing a strict set of inputs—the PRD, System Prompt (SP), Notes, and Knowledge Base (KB)—to generate configurations or code. The user reviews the output and provides feedback (which is logged into the Notes), creating an iterative, self-correcting loop that requires minimum human supervision to achieve the final target state.
* PRD (Product Requirements Document): A clear, human-readable document defining the business logic, required features, and specifications for a given customization.
* SP (System Prompt): The precise, technical instructions fed to the AI agent detailing exactly how to execute the PRD within the target environment.
* Frappe Framework: The underlying low-code, metadata-driven Python/JavaScript web framework that powers ERPNext.
* ERPNext: The open-source enterprise resource planning suite built on the Frappe framework.
* Frappe Cloud: The managed Platform-as-a-Service (PaaS) hosting environment used to deploy and manage Frappe/ERPNext instances.
* Bench: The essential command-line utility (CLI) used to manage Frappe environments, install custom apps, and run database migrations.
* DocType: The core building block in the Frappe ecosystem; it simultaneously represents a database table, a user interface web form, and its associated business logic.
* Fixtures: A Frappe mechanism used to export database-level configurations (like Custom Fields, Property Setters, and Workflows) into JSON files so they can be version-controlled in a Git repository.

== 3. The PAD Workflow Methodology ==
Every configuration or customization task will be strictly governed by the following four-pillar workflow, all documented and stored in the Comfac IT MediaWiki:

# PRD (Product Requirements Document): Defines the business logic, required Doctype changes, workflows, and print formats.
# Knowledge Base (Context): The structured Markdown documentation of Frappe's architecture, specific module logic, and Comfac's historical implementation data. This is the "brain" fed to the AI.
# System Prompt (SP): The exact instructions fed to the PAD (agent) detailing the Frappe-specific technical execution (e.g., "Using the attached Knowledge Base, create a custom app, add these fields via custom script, export fixtures").
# Notes (Feedback & Challenges): The iterative log of what the agent got wrong, Frappe CLI (bench) errors, and workflow refinements to improve the next System Prompt and update the Knowledge Base.

== 4. Core Concept: "Ansible for Frappe" ==
'''Instead of humans clicking through the ERPNext UI to configure settings, create custom fields, or define workflows, the PAD toolset will act as an orchestration engine.'''

* '''Target State Definition: Using the PAD workflow to define a target state (e.g., "Company A needs Manufacturing and HR modules configured with X approval workflows").'''
* '''Agentic Execution: The PAD SSHs into the environment, interacts with the bench CLI, or uses the Frappe REST API to mutate the system to match the target state.'''
* '''Scalability: Existing successful PAD workflows become reusable modules, allowing the Comfac IT team to rapidly deploy pre-configured "industry templates" to new Frappe Cloud sites.'''

== 5. Critical Feedback & Predicted Problems ==
'''''This section highlights the major technical and architectural hurdles you must plan around to make this successful.'''''

=== A. Frappe Architecture Challenges (File vs. Database State) ===

# The Metadata Trap: In Frappe, when you add a Custom Field or change a workflow via the UI, it saves to the database, ''not'' the codebase. If your PAD tries to act like Ansible and just writes Python/JSON files, the system will not recognize the changes.

* ''Mitigation:'' Your PAD must be instructed to use Custom Apps and Fixtures. The agent must make changes, run bench export-fixtures, and commit the resulting JSON files to Git.

# Idempotency Issues: Ansible's superpower is idempotency (running it 10 times results in the same state as running it once). Agents executing Python scripts or API calls often lack this. If a PAD agent runs a script to "create a Custom Field," running it twice might throw an IntegrityError (duplicate column).

* ''Mitigation:'' The PAD must wrap all configuration code in "Check before Execute" logic (e.g., if not frappe.db.exists('Custom Field', ...): create_field()).

=== B. Frappe Cloud Specific Constraints ===

# Direct SSH Limitations: Frappe Cloud is a managed PaaS. Direct, persistent root/SSH access to live-edit files is heavily restricted to prevent drift between their container orchestration and your site.

* ''Mitigation:'' Do not have the PAD "live-edit" production via SSH. Instead, have the PAD clone your custom app repository locally, write the code/fixtures, commit to GitHub/GitLab, and trigger a webhook to Frappe Cloud to rebuild and deploy the image.

# bench migrate Downtime: Every time your PAD pushes a configuration change that alters the database schema, Frappe Cloud will run bench migrate. If the PAD pushes micro-changes continuously, the site will experience frequent micro-downtimes.

* ''Mitigation:'' Batch PAD operations. The workflow should compile a complete "Configuration Release" before pushing to Frappe Cloud.

=== C. PAD (Agentic) Limitations ===

# Context Window Overwhelm: ERPNext is a massive monolith. If you tell an agent to "understand how customizing configuration impacts the system," it will drown in millions of lines of code.

* ''Mitigation:'' Restrict the PAD's operational scope using the specific Knowledge Base files from your MediaWiki (e.g., only provide the documentation for the erpnext/manufacturing module).

# Hallucinating Frappe APIs: Frappe has very specific ORM methods (frappe.get_doc, doc.insert(), frappe.db.get_value). LLMs often hallucinate standard Django or SQLAlchemy syntax instead.

* ''Mitigation:'' Your System Prompts must explicitly reference your MediaWiki "Frappe Cheat Sheet" enforcing the correct ORM syntax and bench commands.

== 6. Strategic Roadmap for Implementation ==
Phase 0: Research and Context Mapping (The Foundation)

* Action: Clone the Frappe and ERPNext GitHub repositories locally.
* Mapping: Have an initial LLM parse and organize the repository logic (DocTypes, Controllers, Hooks) into AI- and human-readable Markdown files.
* Education (Local Llama): Load this mapped context into a local LLM (e.g., Llama 3). Use this instance to translate complex Frappe architecture into simple explanations for non-IT students and Comfac staff.
* MediaWiki Deployment: Upload all generated PRD templates, System Prompts, Notes, and the Knowledge Base Markdown files to the Comfac IT team's MediaWiki. This becomes the central "source of truth" for all future PAD operations.

Phase 1: Frappe Cloud Experiments & Change Detection (The Sandbox)

* Action: Setup a sandbox/test instance on Frappe Cloud.
* Detection: Perform manual configurations via the UI. Use the PAD to ''detect'' the underlying database or JSON changes (diffing the system state).
* Instruction Validation: Test the reverse workflow. Write System Prompts giving the PAD instructions to replicate those detected changes programmatically. Update the Notes and Knowledge Base in MediaWiki based on its success or failure.

Phase 2: The API Configurator (The "Ansible" MVP)

* Instead of SSH and CLI, use the Frappe REST API.
* Write PAD workflows that authenticate via API and send JSON payloads to configure basic things (e.g., System Settings, Company setup, Item Groups). The API naturally handles a lot of the database/state validation that SSH/CLI bypassing might miss.

Phase 3: The Custom App Generator

* Task the PAD with scaffolding actual Frappe Custom Apps based on MediaWiki PRDs.
* Workflow: PRD specifies a new feature -> PAD reads Knowledge Base & SP -> Generates the doctype.json, doctype.py, and doctype.js files -> Commits to Git -> Deploys to Frappe Cloud.

Phase 4: Full CI/CD Agentic Deployment

* Integrate test data. The PAD deploys a configuration, injects test data (e.g., creates 10 dummy Sales Invoices), and runs an automated script to verify the workflow behaves as expected. If it fails, the error goes back to the "Notes" section of the MediaWiki to trigger a self-correction loop.