docs: Add RFC for schema-driven agent form refactoring

[esafwan]

Summary

This RFC proposes a comprehensive refactoring of the Agent form architecture to address scalability and maintainability concerns. The current implementation has grown to ~2,600 lines across multiple files with a "god component" anti-pattern, duplicated data transformation logic, and tightly coupled field definitions.

Key Changes

• Comprehensive analysis of current implementation: documents the 896-line AgentFormPage.tsx orchestrator, its 24 useState hooks, and 12+ handler functions
• Problem identification: god component anti-pattern, duplicated Frappe boolean conversion logic (3 places), decoupled schema/UI/layout definitions, missing i18n infrastructure, excessive prop drilling, and implicit cross-field validation rules
• Comparative analysis: references how Frappe, Strapi, n8n, and Directus solve schema-driven forms
• Five-phase refactoring plan:
  1. Extract custom hooks to reduce god component complexity
  2. Define fields in a single JSON-like schema config
  3. Build generic field renderer component
  4. Integrate react-i18next for i18n support
  5. Centralize Frappe ↔ form value transformations
• Migration strategy: prioritizes low-risk refactors first (hook extraction, transform centralization) before schema-driven rendering
• Concrete examples: shows before/after code for adding a new field (4+ files → 2 files)
• Reference implementations: lists open-source projects using similar patterns

Notable Details

• Acknowledges what works well: TriggerFieldsConfig already uses schema-driven pattern, Zod + React Hook Form are solid choices, hidden-tab error detection is thoughtful UX
• Proposes formalizing the distinction between form tabs (General, Behavior) and custom tabs (Triggers, Tools)
• Includes detailed field definition schema with support for conditional display, cross-field dependencies, and i18n keys
• Provides utility functions for bidirectional Frappe document ↔ form value conversion
• Estimates effort and risk for each phase to guide implementation prioritization

https://claude.ai/code/session_017CzH4g9iDFysU51cyrZYP2