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 4.6.2, AdminLTE 3.2.0, React 19.2.4, TypeScript 5.9.3, webpack 5.105.2. Agents should not propose breaking frontend upgrades without an RFC.

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.