AI for Sugar Devs is a Sugar developer skills library for generating installable, upgrade-safe SugarCRM Module Loadable Packages (MLPs) — from a single logic hook up to a full multi-module package with relationships, sidecar layouts, icons, and language registration.
Designed for Sugar developers with any AI agent (Claude Code, Copilot, ChatGPT, Codex). Skills are exposed as SKILL.md files with YAML frontmatter so Claude Code can route them automatically, while remaining plain-markdown-friendly for everything else.
This repo supports two scales of work. Pick the one that matches your task:
You want to add ONE specific thing to an existing Sugar instance — a logic hook, a custom field, one relationship, a REST endpoint, a scheduler, or a UI tweak.
- Format your request using prompts/feature_request_format.md
- Pick the matching skill from
skills/:- sugar-logic-hook — react to bean events
- sugar-custom-field — vardef custom field (
_csuffix) - sugar-custom-field-type — highlight, color picker, etc.
- sugar-rest-endpoint — custom REST routes
- sugar-scheduler — cron jobs
- sugar-ui-customization — Sidecar views/dashlets/subpanels
- sugar-external-resource-client — outbound HTTP
- Build the zip:
cd build/<PackageName> && php pack.php 1.0.0 - Install via Admin → Module Loader
Examples: examples/01_logic_hook_webhook.md, examples/02_custom_field_varchar.md, examples/03_relationship_many_to_many.md, examples/04_rest_endpoint_api.md, examples/06_notes_1m_attachment.md.
You want to scaffold a brand-new module, or multiple modules linked together — the kind of package Module Builder would produce, but generated by AI and aware of every gotcha.
- Read skills/sugar-feature-generator/SKILL.md — the orchestrator
- Read skills/sugar-new-module/SKILL.md — Escalation singular/plural pattern, ~22 files per module
- Read skills/sugar-relationship/SKILL.md — MB-style M:M-with-join-table even for 1:M
- Read skills/sugar-notes-attachment/SKILL.md — the Notes exception (parent_id/parent_type)
- Read skills/sugar-module-icons/SKILL.md —
installdefs['image_dir'](NOT$manifest) - Read skills/sugar-application-language/SKILL.md — sidebar + dropdowns
- Read skills/sugar-package-build/SKILL.md — pack.php with all 7 installdefs sections
- Use templates/full_module/ as your starting scaffold
- Use templates/relationship/ for each relationship
Or — if you already have a Module Builder export zip — start at skills/sugar-mb-export-flow/SKILL.md to strip the doubled prefix and apply the singular-bean-class override.
Example: examples/05_full_module_package.md.
sequenceDiagram
participant Human as Developer
participant Docs as Skills / Reference
participant AI as AI Agent
participant Build as Build Output
participant Sugar as SugarCRM
Human->>Docs: 1. Read README.md
Docs-->>Human: Pick Path A or Path B
Human->>Docs: 2. Read relevant skills/sugar-*/SKILL.md
Docs-->>Human: Per-skill examples, rules, gotchas
Human->>AI: 3. Submit feature request
Note over AI: Reads CLAUDE.md + AGENTS.md<br/>(execution contract)
AI->>Docs: Route to skill(s)
Docs-->>AI: SKILL.md content + cross-links
AI->>Docs: Consult reference/installdefs_cheatsheet.md
Docs-->>AI: Routing rules
AI->>Build: 4. Generate package in build/<PackageName>/
Note over Build: src/, pack.php, version, releases/
AI-->>Human: Raw file entries
Human->>Build: 5. php pack.php 1.0.0
Build-->>Human: sugarcrm-<PackageName>-1.0.0.zip
Human->>Sugar: 6. Install via Module Loader
Sugar-->>Human: Package installed
Note over Human,Sugar: Studio post-install:<br/>drag-place new fields on OOB record views
├── README.md ← human entry point (you are here)
├── CLAUDE.md ← entry point for Claude Code (skill routing)
├── AGENTS.md ← binding execution contract (v2 mandates)
├── .claude/skills/ ← copy of skills/ for Claude Code's auto-discovery (keep in sync)
├── skills/ ← 19 SKILL.md files (canonical source)
│ ├── sugar-logic-hook/
│ ├── sugar-custom-field/
│ ├── sugar-custom-field-type/
│ ├── sugar-relationship/
│ ├── sugar-rest-endpoint/
│ ├── sugar-scheduler/
│ ├── sugar-ui-customization/
│ ├── sugar-external-resource-client/
│ ├── sugar-feature-generator/ (orchestrator)
│ ├── sugar-package-build/ (pack.php)
│ ├── sugar-mlp-anatomy/ (7 installdefs sections)
│ ├── sugar-new-module/ (MB-style full module)
│ ├── sugar-notes-attachment/ (Notes 1:M exception)
│ ├── sugar-mb-export-flow/ (turn MB export into MLP)
│ ├── sugar-module-icons/ (image_dir gotcha)
│ ├── sugar-application-language/ (sidebar + dropdowns)
│ ├── sugar-address-grouping/ (Quotes fieldset pattern)
│ ├── sugar-studio-debugging/ (symptom → fix table)
│ └── sugar-viewdef-editing/ (safe Sidecar viewdef edits)
├── prompts/
│ ├── feature_request_format.md ← canonical input schema
│ └── *.md ← compat shims (redirect to skills/)
├── reference/
│ ├── master_reference.md
│ ├── installdefs_cheatsheet.md ← 7 sections + file routing
│ ├── module_anatomy.md ← file-by-file new-module walkthrough
│ ├── common_gotchas.md ← symptom → root cause table
│ └── sugar_developer_guide_25.2_md/
├── templates/
│ ├── minimal_mlp/
│ │ ├── pack.stub.php ← 7-section scanner (full)
│ │ └── pack.simple.stub.php ← single-section copy (simple)
│ ├── full_module/ ← parameterized ~22-file module scaffold
│ └── relationship/ ← 5-file relationship template
└── examples/
├── 01_logic_hook_webhook.md
├── 02_custom_field_varchar.md
├── 03_relationship_many_to_many.md
├── 04_rest_endpoint_api.md
├── 05_full_module_package.md ← multi-module walkthrough
└── 06_notes_1m_attachment.md ← minimal Notes 1:M example
The full list lives in AGENTS.md under "Recent Mandates (v2)". The most-frequently-violated ones:
- Custom field names MUST end in
_c - Vardefs use
vname, neverlabel - NO
'help'text on vardefs — labels carry it image_dirbelongs in$installdefs, NEVER$manifest- Escalation pattern: module folder/table PLURAL; bean class/object_name/$dictionary key SINGULAR
- Relationships: lhs = parent, rhs = child
- M:M-with-join-table even for declared 1:M (MB convention) — except Notes
- Notes 1:M: parent_id/parent_type with
relationship_role_column $app_list_stringsfor moduleList + dropdowns MUST be application-scope- HTTP from PHP uses
Sugarcrm\Sugarcrm\Security\HttpClient\ExternalResourceClientonly — never curl/file_get_contents/fopen/stream_get_contents - After install: new fields on OOB modules need Studio drag-place
- CLAUDE.md — Claude Code skill routing entry point
- AGENTS.md — binding execution contract (mandatory rules, prohibited actions, code quality)
- skills/sugar-feature-generator/SKILL.md — orchestrator skill
For any AI agent (Claude, Copilot, ChatGPT, Codex), the routing table in CLAUDE.md plus the YAML frontmatter on each SKILL.md should be enough to find the right skill from a developer intent phrase.
Read and follow AGENTS.md strictly.
Read and follow skills/sugar-feature-generator/SKILL.md strictly.
No explanations. No markdown. Output raw file entries only.
Feature Type: Logic Hook
Module: Accounts
Trigger: after_save
Condition:
field: account_type = 'Customer' or
field: account_type = 'Prospect'
Action:
type: webhook
method: POST
url: https://webhooks.com/mywebhook
payload: full bean
extract the response if http 200 log the result and return 'myresponse'
Package Name: Custom_AccountsCustomerWebhook
Then:
cd build/Custom_AccountsCustomerWebhook
php pack.php 1.0.0
# → releases/sugarcrm-Custom_AccountsCustomerWebhook-1.0.0.zipInstall via Admin → Module Loader.
For full multi-module work (Path B), see examples/05_full_module_package.md.
AI can generate Sugar code, but without structure it produces inconsistent and unsafe packages. This system enforces:
- Extension Framework purity — no core overrides
- Upgrade safety by contract — install/uninstall via Module Loader
- Deterministic builds — reproducible, testable packages
- Sidecar-aware — knows about viewdefs, sidecar layouts, application-scope language
- MB-style fluency — produces packages that look like Module Builder output (and works around MB's quirks: doubled prefix, label-vs-vname, image_dir misplacement)
It transforms AI from a code assistant into a controlled, production-ready Sugar MLP compiler.