ChurchCRM Development Guide

Loaded by Claude Code every session. Other agents should follow the same files.

Task ownership

Read the AI operating model for task owners, handoffs and approval boundaries.

Skills

Index: .agents/skills/churchcrm/SKILL.md. How to edit a skill: .agents/skills/churchcrm/skill-architecture.md. Load the card for the task. Do not load every skill.

Always-on:

@.agents/skills/churchcrm/code-standards.md

@.agents/skills/churchcrm/git-workflow.md

Keep these heading names (this file links them): Commit freely, push only on approval, Mandatory Pre-Push Biome Check, Strict vs Loose Comparisons.

Updating a skill

If a durable rule is missing or wrong, edit the existing card. Replace the sentence. Do not append <!-- learned: --> essays. Do not paste catalogs from src/.

Plugin registry URL: CentralServices::PLUGIN_REGISTRY_URL (External branch today).

Issue and PR readiness

Before triaging or implementing an issue, read docs/contributing/issue-readiness.md. Check existing issues/PRs first, size work by review burden and risk, use epics for independently meaningful outcomes or cross-subsystem work, and treat good first issue as a maintainer certification. Keep issue intake friendly and PRs focused. Human maintainers remain accountable for decisions and approvals.

Session hygiene

• Confirm git branch --show-current before committing docs
• Do not land cross-cutting skill edits on an unrelated feature branch
• After a push that fixes review comments, resolve every thread it fixed before you report done: check each against the pushed code, reply with the SHA when unclear, leave unfixed threads open (git-workflow.md)
• Do not merge or close issues unless the maintainer answers yes to a direct question
• User-visible behavior: open a docs tracking issue on ChurchCRM/CRM. It does not block feature merge. Docs PRs wait for the release. See docs/contributing/pr-review.md
• UI that belongs on a marketing or docs page: one PR carries the code, the Cypress specs, and the Playwright capture spec (playwright/workflows/; marketing-visuals-pipeline.md). Images and the manifest are never committed: they are published to cdn.churchcrm.io after the release. To check a capture locally, run the pipeline in a git worktree on its own compose project, never on the dev checkout: it deletes src/Include/Config.php. Open a separate Playwright issue only when the capture spec cannot be written yet
• Follow the human-first writing rules in docs/contributing/issue-readiness.md: BLUF first, concise goals and outcomes, details only when they help a decision.
• Write the current state: positive instructions, no history, no negating comments, migrate a legacy page when you touch it (skill-architecture.md)
• Write little. Names and tests carry intent. Comment only to explain intent or a non-obvious constraint; do not narrate the code.
• If the PR author is the same GitHub user the agent is acting as, do not post a review comment. Fix the branch.

Tests

Run the failing spec in isolation before committing test fixes. Before a push, run the specs the change touches locally and check UI changes in a browser in light and dark, at desktop, tablet, and phone widths; UI PRs carry screenshots (git-workflow.md, cypress-testing.md). Do not assume Cypress / Yasumi fixture shapes — read the source. cy.visit() paths start with /. Raw fetch, cy.task and win.fetch use absoluteUrl() from cypress/support/urls.js so a subdirectory install keeps the install path.