AI Agent Workflow

AI Agent Workflow — Using AI to Add Features, Fix Bugs, and Manage PRs

Purpose

• Explain how contributors and maintainers can use AI coding agents to accelerate feature work, address PRs, and fix bugs while keeping ChurchCRM a modern, safe, and auditable project.

Principles (must follow)

• Agents are assistants, not automatic committers — a human reviews and approves all changes.
• Always run existing tests and CI locally before merging anything an agent produces.
• Keep the service layer as the source of business logic: agents should add or update services in src/ChurchCRM/Service/ whenever logic is non-trivial.
• Use Perpl ORM Query classes — never raw SQL. Agents must follow TableMap and addForeignValueCondition() rules. See /.github/skills/database-operations.md.

When to use an AI agent

• Prototyping new endpoints, extracting logic into services, writing tests, creating route skeletons, updating documentation, and writing localized UI text.
• Not for committing secrets, performing irreversible production changes, or replacing code reviews.

How to start (best practice)

1. Identify the task and pick relevant skills (examples):
   • Add API endpoint: api-development.md, slim-4-best-practices.md, service-layer.md, php-best-practices.md.
   • Migrate admin page: admin-mvc-migration.md, refactor.md, frontend-development.md.
   • Add i18n strings: i18n-localization.md and run npm run locale:build.
2. Provide the agent with: short goal, target files/areas, and constraints (PHP version, ORM rules, security). Example: "Create src/groups/sundaySchool/routes/members.php and a GroupService method to add a member; include unit tests and Cypress scenario."
3. Let the agent produce a focused change (one logical change per run). Review and iterate.

Agent workflows (step-by-step)

Add a feature (API + UI)

• Step A — Plan: Ask the agent to draft a small plan (routes → service → view → tests). Confirm.
• Step B — Implement skeletons: Agent creates route file under src/<area>/routes/, service stub in src/ChurchCRM/Service/, and view template under src/<area>/views/ if needed.
• Step C — Tests: Agent generates unit tests for service and API integration tests (Cypress for UI flows). Run tests locally.
• Step D — Local verification: Run npm run build and composer install (in src/) and run tests: npm run test or npx cypress run as appropriate.
• Step E — Human review & commit: Reviewer inspects code, verifies style and security, then commits with a clear message and opens a PR.

Fix a bug / address a PR

• Step A — Reproduce: Ask the agent to create a minimal failing test reproducing the bug. This ensures regression coverage.
• Step B — Diagnose: Provide relevant logs, error messages, and the failing test; agent proposes a minimal fix following project rules (Perpl ORM, RedirectUtils, SlimUtils).
• Step C — Implement & test: Agent implements the fix, updates tests, and documents the change in the PR description.
• Step D — Review & merge: Human reviewer confirms tests pass and merges.

Security & Permissions

• Agents must not modify auth checks without explicit human approval. All permission checks should use the existing User methods (e.g., isAdmin(), canEditPerson()), and use RedirectUtils::securityRedirect() for redirects.

i18n & Frontend

• If the change adds UI strings, run npm run locale:build and commit updates to locale/terms/messages.po before the code PR. Then run npm run build to regenerate frontend assets.
• Frontend libraries & versions (from package.json): Bootstrap 5, Tabler (admin theme), TypeScript, Webpack. React was removed in 7.1.2. Agents should not propose breaking frontend upgrades without an RFC.
• For UI, use Tabler components and Bootstrap 5 class names (not Bootstrap 4). See Tabler-UI-Components for the reference guide.

Testing / CI

• Unit tests: put PHP tests under the appropriate test folder following existing project patterns.
• Cypress: Add UI scenarios under cypress/e2e/ui/<feature>/ and API tests under cypress/e2e/api/. Use npm run test or node_modules/cypress/bin/cypress run --e2e to execute.

Commit / PR conventions

• Small, focused commits; use the project's commit message style, examples:
  • feat(groups): add sundaySchool group membership API
  • fix(api): validate person ID in people-groups endpoint
• Include a short description, testing steps, and any migrations or i18n checklist in the PR body.

Agent prompt templates (examples)

• Add feature: "You are an expert ChurchCRM developer. Create a Slim route POST /groups/sundaySchool/members in src/groups/sundaySchool/routes/members.php that calls GroupService::addMember($groupId, $personId). Add GroupService stub in src/ChurchCRM/Service/GroupService.php, unit tests, and a Cypress UI test. Follow Perpl ORM and use SlimUtils::renderErrorJSON() for errors. Don't commit — show the diff."
• Bug fix: "Reproduce the bug by adding a unit test that fails for src/api/routes/people/people-groups.php when person id is non-numeric. Then implement a minimal fix that validates and returns SlimUtils::renderErrorJSON() with status 400."

Best practices & warnings

• Always run composer validate and composer install --no-dev under src/ if you change PHP dependencies.
• Do not let agents change composer.json or package.json versions without human review.
• Keep database schema changes separate: open a migration PR with DB scripts and follow db-schema-migration.md.
• Keep a clear audit trail: reference JIRA/Issue numbers in commits and PRs for traceability.

Where to read more

• Skills directory (use the relevant skills for agent prompts): .github/skills/ — e.g., slim-4-best-practices.md, api-development.md, service-layer.md, i18n-localization.md, testing.md.

Want me to create a pull request template or an agent-ready checklist file for PR authors? Reply and I'll add it.

---

Building Custom Features: Plugins Are the Right Approach

Upgrade warning: Any file you modify directly inside the ChurchCRM source tree (src/, public/, locale/, etc.) will be overwritten the next time you upgrade. There are no merge steps — the upgrade process replaces application files wholesale. If you want your customization to survive upgrades, it must live in a community plugin.

ChurchCRM's plugin system is specifically designed for this. A plugin:

• Lives in its own directory (src/plugins/community/<your-plugin>/)
• Is never touched by the upgrade process
• Can add pages, API routes, menu items, notification channels, and hooks into core events
• Can be enabled, disabled, or removed independently

If you are tempted to edit a core PHP file to add a custom field, a new page, or an integration — build a plugin instead.

See Creating-Community-Plugins for the full plugin development guide.

---

Using AI to Kickstart Plugin Development

The AI agent workflow is especially powerful for building community plugins from scratch. Here is how to use it effectively.

1. Load the relevant skills

The .github/skills/ directory (in the CRM repo) contains task-specific instruction sets for AI agents. For plugin development, load:

.github/skills/churchcrm/creating-community-plugins.md
.github/skills/churchcrm/api-development.md
.github/skills/churchcrm/slim-4-best-practices.md
.github/skills/churchcrm/service-layer.md
.github/skills/churchcrm/i18n-localization.md

In Claude Code, you can load these as context at the start of your session. Paste the content directly or reference them explicitly in your prompt.

2. Write a clear plugin brief

Give the agent a short, specific goal. Example:

Goal: Create a community plugin called mailchimp-sync that adds a settings page under Admin, stores a Mailchimp API key in the plugin config table, and syncs the member email list to a Mailchimp audience on demand via a button on the settings page.

Constraints: Use Slim 4 route handlers, Propel ORM for any DB access, Tabler/Bootstrap 5 UI, wrap all UI strings in gettext(). Do not modify any core files. Follow the plugin manifest format in Creating-Community-Plugins.md.

3. Use the agent for scaffolding

Ask the agent to generate:

1. plugin.json — manifest with name, version, author, hooks
2. Main plugin class — registers routes and menu items
3. Route file — Slim 4 handlers for settings page and sync endpoint
4. View template — Tabler-styled settings form
5. Any service class needed (e.g., MailchimpService.php)

Review the scaffold, then iterate. The agent is excellent at filling in boilerplate; your job is to verify business logic and security.

4. Testing

Agents can generate Cypress tests for your plugin's UI and API routes. Ask for:

- A Cypress API test that POSTs to /plugins/mailchimp-sync/sync and asserts a 200 response
- A Cypress UI test that opens the plugin settings page and saves an API key

Run tests with npm run test before considering the plugin ready.

5. Skip straight to the skills checklist

Quick reference — for each plugin task, ask the agent to:

Task	Key skill(s) to reference
Plugin scaffold	creating-community-plugins.md
Settings/config page	slim-4-best-practices.md, Tabler-UI-Components wiki page
External API integration	service-layer.md, api-development.md
Adding translations	i18n-localization.md
Writing tests	testing.md
Database changes (plugin tables)	db-schema-migration.md

---

Available Agent Skills (Quick Reference)

All skills are in .github/skills/ in the CRM repo. The most useful for new contributors:

Skill file	Use it for
churchcrm/creating-community-plugins.md	Building any community plugin
churchcrm/api-development.md	Adding API endpoints
churchcrm/slim-4-best-practices.md	Slim 4 routing and middleware
churchcrm/service-layer.md	Business logic in service classes
churchcrm/i18n-localization.md	Making UI text translatable
churchcrm/testing.md	Cypress tests for UI and API
churchcrm/db-schema-migration.md	Schema changes and migrations
churchcrm/frontend-development.md	JavaScript and Tabler UI
churchcrm/admin-mvc-migration.md	Migrating legacy admin pages
php-best-practices.md	PHP type safety, PSR-12, SOLID
interface-design.md	Tabler UI design patterns