tomevault-io ChurchCRM Development Skills
Project-specific skills for AI agents and developers working on ChurchCRM. Each skill covers a focused workflow area with ChurchCRM-specific patterns, conventions, and examples.
Architecture & API
Reading order for API development:
- Routing & Architecture — Understand file organization and entry points
- Slim 4 Best Practices — Framework patterns (middleware, error handling)
- API Development — Create or modify REST endpoints
- Service Layer — Extract business logic into services
- API Compatibility & Deprecation — Maintain backward compatibility
Additional skills:
| Skill | When to Use |
|---|---|
| Slim MVC Skill | MVC route groups, security patterns, migration guidance (optional) |
| Configuration Management | Settings, SystemConfig, admin panels |
Database
| Skill | When to Use |
|---|---|
| Database Operations | ORM queries, Perpl ORM patterns, data persistence |
| DB Schema Migration | Schema changes, migration scripts |
Frontend & UI
Any time you add or edit a table with row actions — read
table-action-menu.mdfirst. Any time you add settings/config to a page — readfrontend-development.md(System Settings Panel section) for the gold-standard pattern from Finance Dashboard.
| Skill | When to Use |
|---|---|
| Table Action Menu | Required for every table with row-level actions — dropdown pattern, overflow fix, cart buttons, checklist |
| Frontend Development | Settings Panel (gold-standard pattern), UI changes, Bootstrap 5, i18n, notifications, confirmations, modals, asset management |
| Timezone Handling | Required for any datetime-aware change — wall-clock-in-sTimeZone storage, FullCalendar marker quirks, Propel space format Chrome misparse, kiosk timing, cross-tz banner. Read before touching event-form.js, event-calendars.js, calendar-event-editor.js, kiosk-jsom.ts, KioskDevice::heartbeat(), or events.php API |
| Responsive Design Guidelines | Canonical mobile / tablet / laptop form factors, breakpoints, grid patterns, touch targets — read before any page layout or responsive bug fix |
| Tabler Components | Page layout, cards, tables, forms, nav, badges, modals, toasts, icons |
| Bootstrap 5 Migration | Complete BS4→BS5 migration reference: data attributes, class renames, JS API, components |
| Webpack & TypeScript | Frontend bundling, vanilla JS/TS modules, asset management |
| i18n & Localization | Adding UI text, translations |
| AI Locale Translation | Translating missing terms via Claude AI before a release |
| Locale Stack Ranking | NEW — Prioritize translation effort by impact (TIER-1: 53% world pop, TIER-2: 80%, etc.) |
| Currency Localization | NEW — Displaying money with configurable symbol / position / separators (PHP, JS, DataTables, Chart.js, CSS, PDFs). Required for any finance-adjacent change. Epic: #8459 |
Tabler Migration (Vision 2026)
| Skill | When to Use |
|---|---|
| Tabler Components | Page layout, cards, tables, forms, nav, badges, modals, toasts, icons — the new UI reference |
| Library Replacement Guide | Which 3rd-party libs to swap (Select2→Tom Select, etc.), npm/webpack/Grunt changes |
| Migration Playbook | Per-page migration steps, full codebase audit inventory, phased execution plan |
| Bootstrap 5 Migration | Data attribute renames, CSS class mapping, JS API changes (shared with Frontend section) |
| Error Reporting & Issue Filing | Shared Tabler-styled error pages (4xx/5xx), consistent UX, wiring to Issue Reporter modal, and E2E testing patterns |
Agent-only skill file: .claudecode/migration-rules.md — strict rules for the Tabler shell, personas, iconography, and legacy bridge.
Epic Issue: #8301 — UI Migration: AdminLTE to Tabler 2026
Security
| Skill | When to Use |
|---|---|
| Authorization & Security | Permission checks, authentication |
| Security Best Practices | Security features, sensitive operations, output escaping (incl. data-* attributes) |
| Security Advisory Review | Analyzing/fixing GitHub security advisories — access draft advisories via gh CLI, understand vulnerability scope, write tests, create PRs |
| GitHub Interaction | Security Advisory lifecycle: draft → publish → CVE request, notifying reporters |
Plugins
| Skill | Audience | When to Use |
|---|---|---|
| Plugin System | All | Runtime architecture — PluginManager, hooks, install flow, plugin-local localization loader |
| Plugin Development | Plugin authors | Building a plugin end-to-end. Start here, and read the security-scan preamble at the top before writing code. Covers allowed/forbidden capabilities, hooks, sandboxed config, and plugin-local translations. |
| Plugin Create (Community) | Community plugin authors | Quickstart + submission flow: scaffold a community plugin, run the security scan against your own tree, build a reproducible zip, and open the approved-plugins.json PR |
| Plugin Migration (Core only) | Core plugin maintainers | Checklist when a core API change affects src/plugins/core/*. Not for community plugins — they follow plugin-create.md instead |
| Plugin Security Scan | ChurchCRM maintainers | Required review checklist before approving a community plugin for src/plugins/approved-plugins.json. Covers intake, static analysis, risk classification, and the 2026 plugin standards reference. |
| Plugin Compliance (Admin Audit) | Site admins | Monthly/quarterly scans of already-installed community plugins. Read the approved list, verify on-disk state, re-run the orphan scan, respond to revoked plugins. |
Testing
| Skill | When to Use |
|---|---|
| Testing | Writing tests, debugging, test suites |
| Cypress Testing | E2E tests, CI/CD testing, API test patterns |
| Testing Migration & E2E | Testing strategy for migrations |
Running Cypress Locally
Follow these steps to run Cypress tests locally and generate machine-readable reports useful for CI parity:
Install dependencies:
npm ciRun a single spec (headless, Electron):
npx cypress run --spec "cypress/e2e/path/to/specfile.spec.js" --browser electronRun the full test suite with JUnit output (for CI-like reports):
npx cypress run --reporter junit --reporter-options "mochaFile=cypress/reports/junit-[name].xml"Run with a specific base URL (useful for docker/local server):
CYPRESS_BASE_URL=http://127.0.0.1:8080/churchcrm/ npx cypress run --config-file cypress/configs/docker.config.tsRun a spec in headed mode for interactive debugging:
npx cypress open --config-file cypress/configs/docker.config.tsGenerate an HTML report (mochawesome) locally (optional):
Install reporters:
npm install --save-dev mochawesome mochawesome-merge mochawesome-report-generatorRun and write JSON output:
npx cypress run --reporter mochawesome --reporter-options "reportDir=cypress/reports,overwrite=false,html=false,json=true"Merge and generate HTML:
npx mochawesome-merge cypress/reports/*.json > cypress/reports/merged.json npx mochawesome-report-generator cypress/reports/merged.json -o cypress/reports/html
Tips & diagnostics:
- Use
--headed --browser chrometo visually reproduce failures. - Use
--config video=true,screenshotOnRunFailure=trueto capture artifacts. - When testing admin routes, ensure the local app is running and reachable (see
docker/compose profiles used in CI). - Use
--reporter jsonto produce structured output you can parse for automated triage. - For flaky selectors after UI changes, prefer stable selectors:
id,data-cy,input[name=], link href/text, and avoid visual utility classes.
- Use
Before committing ANY test changes: See CLAUDE.md → Test Review & Commit Workflow for mandatory checklist
MVC Migration
| Skill | When to Use |
|---|---|
| Admin MVC Migration | Migrating legacy pages to modern MVC |
| Groups MVC Guidelines | Groups module MVC patterns |
| Refactor | Refactoring legacy code to services/MVC |
PHP & Performance
| Skill | When to Use |
|---|---|
| PHP Best Practices | ChurchCRM PHP patterns, Perpl ORM |
| Modern PHP Frameworks | Security hardening, framework features |
| Performance Optimization | Query optimization, scaling, response times |
| Observability, Logging & Metrics | Logging, metrics, monitoring |
Development Process
| Skill | When to Use |
|---|---|
| Git Workflow | Commits, PRs, pre-commit validation |
| GitHub Interaction | Reviews, commits, PR management |
| PR Review | Full PR review: fetch changes, validate standards, check docs/wiki, manual testing, address comments, capture learnings |
| PR Description Guidelines | Ensure PR bodies are written in Markdown with required sections (Summary, Changes, Files Changed, Validation, Testing) |
| Development Workflows | Setup, build, Docker management |
| Code Standards | General coding, quality checks, PR reviews |
| Wiki Documentation | Complex documentation, admin guides |
| Release Notes | Authoring GitHub release notes for any version type |
| Social Media Release | Generating platform posts for X, Facebook, Instagram, LinkedIn |
Example Workflows
- New API endpoint:
api-development.md→service-layer.md→slim-4-best-practices.md→security-best-practices.md→cypress-testing.md→git-workflow.md - Migrate legacy page:
routing-architecture.md→admin-mvc-migration.md→frontend-development.md→database-operations.md→git-workflow.md - Fix security issue:
security-best-practices.md→authorization-security.md→php-best-practices.md→git-workflow.md - Add a community plugin:
plugin-system.md→plugin-development.md→plugin-create.md→plugin-security-scan.md→git-workflow.md - Update a core plugin (
src/plugins/core/*):plugin-system.md→plugin-development.md→plugin-migration.md→git-workflow.md - Audit installed plugins (admin):
plugin-compliance.md - Optimize queries:
performance-optimization.md→database-operations.md→service-layer.md - Add UI text:
i18n-localization.md→frontend-development.md→git-workflow.md - Render money / currency anywhere:
currency-localization.md→configuration-management.md→frontend-development.md→git-workflow.md - Manage security advisory (publish GHSA, request CVE, notify reporters):
github-interaction.md(Security Advisory Management section) →security-best-practices.md - Write release notes:
release-notes.md→github-interaction.md - Publish a release:
release-notes.md→social-media-release.md→github-interaction.md - Review a PR:
pr-review.md→code-standards.md→security-best-practices.md→wiki-documentation.md - Address PR comments:
pr-review.md→github-interaction.md→git-workflow.md - Add print support to a page:
frontend-development.md(Print Support section) →security-best-practices.md(CSP) →git-workflow.md - Migrate a page to Tabler:
tabler-migration-playbook.md→tabler-components.md→table-action-menu.md→bootstrap-5-migration.md→git-workflow.md - Add or edit a table with row actions:
table-action-menu.md→tabler-components.md→git-workflow.md - Swap a 3rd-party library:
tabler-library-replacement.md→webpack-typescript.md→git-workflow.md
Source: ChurchCRM/CRM — distributed by TomeVault.