Church App — AI-Agentic Development Plan
You are the architect, PM, and reviewer. AI agents are the development team. This document defines how they work.
The Team
┌─────────────────────────────────────────────────────────────────┐
│ SIMON (Human — Master Architect / PM / Reviewer) │
│ │
│ Creates: requirements, domain models, ADRs, priorities │
│ Reviews: PRs, architecture consistency, UX quality │
│ Decides: scope, trade-offs, module boundaries, what ships │
│ Approves: every merge to main │
└──────────────────────────────┬──────────────────────────────────┘
│
directs + reviews │
▼
┌─────────────────────────────────────────────────────────────────┐
│ AI AGENT TEAM │
│ │
│ 🏗️ Architect Agent — system design, module boundaries, ADRs │
│ 💻 Backend Agent — Symfony, PHP, API, database, tests │
│ 📱 Frontend Agent — React Native, Expo, components, screens │
│ 🎨 Design Agent — UI/UX, design system, component design │
│ 🔍 Reviewer Agent — code review, quality gates, refactoring │
│ 🧪 Test Agent — unit tests, integration tests, fixtures │
│ 🛠️ DevOps Agent — Docker, CI/CD, OpenTofu, deployment │
│ 📝 Docs Agent — API docs, guides, changelogs │
│ 📣 Marketing Agent — website content, SEO, blog posts │
│ │
│ Tools: Claude Code (primary), Cursor │
└─────────────────────────────────────────────────────────────────┘These aren’t separate software agents — they’re roles that Claude Code (or Cursor) adopts based on the context and task. The CLAUDE.md file and the .ai/agents/ directory define how each role behaves. You invoke a role by referencing it: “Act as the backend agent and implement the Groups module API.”
Repository Context Structure
church-app/
├── CLAUDE.md # Root context — Claude Code reads this first
│
├── .ai/ # All AI agent context lives here
│ │
│ ├── agents/ # Agent role definitions
│ │ ├── architect.md # System design, boundaries, ADRs
│ │ ├── backend.md # Symfony, PHP, API conventions
│ │ ├── frontend.md # React Native, Expo, components
│ │ ├── designer.md # UI/UX principles, design system
│ │ ├── reviewer.md # Code review checklist, quality gates
│ │ ├── tester.md # Test strategy, patterns, coverage
│ │ ├── devops.md # Docker, CI/CD, infrastructure
│ │ ├── docs.md # Documentation standards
│ │ └── marketing.md # Website, content, SEO
│ │
│ ├── guidelines/ # Coding and architecture standards
│ │ ├── CODING_GUIDELINES.md # PHP style, naming, patterns, do/don't
│ │ ├── API_GUIDELINES.md # REST conventions, error formats, pagination
│ │ ├── DATABASE_CONVENTIONS.md # Naming, indexing, JSONB, migrations
│ │ ├── EVENT_GUIDELINES.md # Domain event design, serialization, versioning
│ │ ├── MODULE_GUIDELINES.md # How to create a module end-to-end
│ │ ├── TESTING_GUIDELINES.md # Unit, integration, E2E patterns
│ │ ├── FRONTEND_GUIDELINES.md # RN components, navigation, state, styling
│ │ ├── DESIGN_SYSTEM.md # Colors, typography, spacing, components
│ │ └── GIT_WORKFLOW.md # Branching, commits, PRs, reviews
│ │
│ ├── decisions/ # Architecture Decision Records
│ │ ├── 001-symfony-backend.md
│ │ ├── 002-react-native-expo.md
│ │ ├── 003-zitadel-auth.md
│ │ ├── 004-postgresql-ltree.md
│ │ ├── 005-redis-messenger.md
│ │ ├── 006-ddd-deptrac.md
│ │ ├── 007-mailgun-email.md
│ │ ├── 008-hetzner-hosting.md
│ │ └── ...
│ │
│ ├── skills/ # Step-by-step recipes for common tasks
│ │ ├── create-module.md # Scaffold a new module end-to-end
│ │ ├── create-aggregate.md # Define a DDD aggregate root
│ │ ├── create-domain-event.md # Event class + schema + registration
│ │ ├── create-api-endpoint.md # Controller, DTO, validation, OpenAPI
│ │ ├── create-admin-page.md # Twig + Vue island pattern
│ │ ├── create-screen.md # React Native screen + navigation
│ │ ├── create-component.md # Reusable RN component
│ │ ├── create-migration.md # Doctrine migration conventions
│ │ ├── add-module-entitlement.md # Wire a module into the entitlement system
│ │ ├── write-tests.md # Test patterns per layer
│ │ └── deploy.md # Deployment checklist
│ │
│ ├── templates/ # Code templates for scaffolding
│ │ ├── module/ # Full module skeleton
│ │ │ ├── Domain/
│ │ │ │ ├── Model/AggregateTemplate.php
│ │ │ │ ├── Event/DomainEventTemplate.php
│ │ │ │ └── Repository/RepositoryInterfaceTemplate.php
│ │ │ ├── Application/
│ │ │ │ ├── Command/CommandTemplate.php
│ │ │ │ ├── Command/CommandHandlerTemplate.php
│ │ │ │ └── Query/QueryHandlerTemplate.php
│ │ │ ├── Infrastructure/
│ │ │ │ └── Persistence/DoctrineRepositoryTemplate.php
│ │ │ ├── Presentation/
│ │ │ │ ├── Controller/ApiControllerTemplate.php
│ │ │ │ └── DTO/ResponseTemplate.php
│ │ │ ├── Contract/
│ │ │ │ └── ProviderInterfaceTemplate.php
│ │ │ └── config/
│ │ │ ├── routes.yaml
│ │ │ └── services.yaml
│ │ └── test/
│ │ ├── UnitTestTemplate.php
│ │ └── IntegrationTestTemplate.php
│ │
│ ├── prompts/ # Reusable prompt fragments
│ │ ├── review-module.md # "Review this module for boundary violations..."
│ │ ├── review-pr.md # "Review this PR for quality, style, tests..."
│ │ ├── review-aggregate.md # "Validate aggregate boundaries and invariants..."
│ │ ├── review-api.md # "Check API design, error handling, pagination..."
│ │ ├── implement-feature.md # "Implement this feature following our guidelines..."
│ │ └── write-tests-for.md # "Write tests for this module/class..."
│ │
│ └── context/ # Living project context
│ ├── DOMAIN_MODEL.md # → symlink or copy from docs/domain-model.md
│ ├── ARCHITECTURE.md # → condensed version of architecture-blueprint
│ ├── MVP_SCOPE.md # → what we're building now
│ ├── EVENT_CATALOG.md # All domain events, schemas, who emits/consumes
│ ├── MODULE_STATUS.md # Which modules exist, their maturity, what's next
│ └── CURRENT_SPRINT.md # What's being worked on right nowCLAUDE.md (Root Context File)
This is the first thing Claude Code reads. It must be concise, opinionated, and point to deeper context.
# CLAUDE.md
## Project: Church App Platform
A multi-tenant community platform for churches, organizations, and movements.
Solo founder + AI-agentic development. Built to serve, built to scale.
## Tech Stack
- **Backend:** Symfony 7, PHP 8.3+, PostgreSQL 16 (ltree), Redis 7
- **Frontend:** React Native (Expo) — iOS, Android, Web (PWA)
- **Auth:** Zitadel (self-hosted OIDC)
- **Architecture:** DDD modular monolith, Deptrac-enforced boundaries
- **Events:** JSON-serializable domain events via Symfony Messenger + Redis
- **Infra:** Hetzner, Docker, Cloudflare (R2 + Pages), GitLab CI/CD
## Architecture Rules (non-negotiable)
1. **Domain layer is pure PHP.** No Doctrine, no Symfony, no framework imports.
2. **Modules communicate via domain events or contract interfaces.** Never import another module's domain or infrastructure.
3. **Every domain event is JSON-serializable** with a `version` field.
4. **Deptrac enforces all boundaries.** If Deptrac fails, the code doesn't merge.
5. **No cross-module database queries.** One module, one schema prefix.
6. **Tests accompany every feature.** Unit tests for domain, integration for infrastructure.
## Project Structuresrc/Core/ — Platform, contracts, identity, notifications src/Module/ — Feature modules (People, Groups, Events, News…) src/Pipeline/ — Observe & Protect (Audit, History, Moderation, Translation) frontend/ — React Native (Expo) project admin/ — Admin backend (Twig + Vue 3 islands) infrastructure/ — Docker, OpenTofu, scripts
## Agent Roles
Read `.ai/agents/{role}.md` for role-specific behavior:
- `architect` — system design, ADRs, module boundaries
- `backend` — Symfony, API, database, domain logic
- `frontend` — React Native screens, components, navigation
- `designer` — UI/UX, design system, visual quality
- `reviewer` — code review, quality gates
- `tester` — test strategy, coverage, fixtures
- `devops` — Docker, CI/CD, deployment
- `docs` — documentation, API docs, changelogs
- `marketing` — website, SEO, blog content
## Before Writing Code
1. Read the relevant agent file: `.ai/agents/{role}.md`
2. Read the relevant guideline: `.ai/guidelines/{topic}.md`
3. Read the relevant skill: `.ai/skills/{task}.md`
4. Check `.ai/context/CURRENT_SPRINT.md` for what's being worked on
5. Check `.ai/context/MODULE_STATUS.md` for module maturity
## Git Workflow
- `main` — production-ready, auto-deploys to production on tag
- `develop` — integration branch, auto-deploys to staging
- `feature/{slug}` — one feature per branch, PR to develop
- `fix/{slug}` — bugfix branch, PR to develop
- `hotfix/{slug}` — urgent fix, PR directly to main
Commit messages: conventional commits (`feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`)
## Key Commands
```bash
make up # Start Docker services
make serve # Start Symfony dev server
make expo # Start Expo dev server
make ci # Run full quality check (lint + Deptrac + tests)
make worker # Start Messenger consumers
make db-reset # Reset and re-seed databaseImportant Files
.ai/context/DOMAIN_MODEL.md— aggregates, events, relationships.ai/context/EVENT_CATALOG.md— all domain events with schemas.ai/guidelines/CODING_GUIDELINES.md— PHP style and patterns.ai/guidelines/MODULE_GUIDELINES.md— how to build a moduledeptrac.yaml— architectural boundary rules
---
## Agent Role Definitions
### 🏗️ Architect Agent (`.ai/agents/architect.md`)
```markdown
# Architect Agent
You are the system architect. You think in bounded contexts, aggregates,
and event flows. You protect the integrity of the domain model.
## Responsibilities
- Design new modules and their boundaries
- Define aggregates, value objects, and domain events
- Write Architecture Decision Records (ADRs)
- Review module interactions for coupling violations
- Design API contracts between modules
- Plan database schemas and migration strategies
## You always
- Check `.ai/context/DOMAIN_MODEL.md` before designing anything
- Verify new events against `.ai/context/EVENT_CATALOG.md`
- Write an ADR for any significant decision
- Think about: What happens when this module is extracted to a service?
- Consider: Does the Domain layer stay pure PHP?
## You never
- Write implementation code (that's the backend/frontend agent's job)
- Make decisions about UI/UX (that's the designer's job)
- Skip the Domain layer and go straight to infrastructure
- Create cross-module dependencies without a contract interface
## Output format
- ADRs go in `.ai/decisions/NNN-{slug}.md`
- Event definitions go in `.ai/context/EVENT_CATALOG.md`
- Module designs follow `.ai/guidelines/MODULE_GUIDELINES.md`💻 Backend Agent (.ai/agents/backend.md)
# Backend Agent
You are a senior Symfony developer. You write clean, tested, DDD-structured
PHP code. You follow the project's conventions exactly.
## Before writing any code
1. Read `.ai/guidelines/CODING_GUIDELINES.md`
2. Read `.ai/guidelines/MODULE_GUIDELINES.md`
3. Read `.ai/guidelines/DATABASE_CONVENTIONS.md`
4. Check the relevant module's structure in `src/Module/{Name}/`
5. Check `.ai/context/MODULE_STATUS.md` for module maturity
## Architecture rules you enforce
- Domain layer: pure PHP, no framework deps, no Doctrine annotations
- Application layer: command/query handlers, orchestrates domain + infra
- Infrastructure: implements domain interfaces, uses framework
- Presentation: thin controllers, DTOs, delegates to application layer
- Events: JSON-serializable, versioned, emitted from domain layer
## Conventions
- PSR-12 coding standard
- Strict types in every file: `declare(strict_types=1);`
- Final classes by default (open for extension only when justified)
- Constructor promotion for value objects and DTOs
- Repository interfaces in Domain, implementations in Infrastructure
- Command/Query separation: commands change state, queries don't
- No business logic in controllers — ever
- Table prefix per module: `people_members`, `groups_groups`
## Testing expectations
- Every aggregate: unit test for invariants and state transitions
- Every command handler: unit test with mocked repos
- Every API endpoint: integration test
- Use fixtures, not mocks for integration tests
- Follow `.ai/guidelines/TESTING_GUIDELINES.md`
## When creating a new module
- Follow `.ai/skills/create-module.md` step by step
- Use templates from `.ai/templates/module/`
- Register in Deptrac config: `deptrac.yaml`
- Add to `.ai/context/MODULE_STATUS.md`📱 Frontend Agent (.ai/agents/frontend.md)
# Frontend Agent
You build the React Native (Expo) mobile and web app. You write clean,
typed components with a focus on performance and UX.
## Before writing any code
1. Read `.ai/guidelines/FRONTEND_GUIDELINES.md`
2. Read `.ai/guidelines/DESIGN_SYSTEM.md`
3. Check existing components in `frontend/components/`
4. Check the API contract (OpenAPI docs)
## Stack
- React Native with Expo SDK
- Expo Router (file-based navigation)
- TypeScript (strict mode)
- Custom design system (no Tailwind, no NativeBase)
- i18next for translations (DE, EN minimum)
- Zustand or React Context for state (keep it simple)
- React Query (TanStack) for API state
## Conventions
- One component per file
- Colocate styles with components (StyleSheet.create)
- Use design tokens (colors, spacing, typography) from design system
- Screen files in `frontend/app/` (Expo Router)
- Shared components in `frontend/components/`
- API calls via `frontend/lib/api/` (typed, generated from OpenAPI)
- Every screen handles: loading, error, empty, and success states
- Offline-first: cache API responses, show stale data with refresh
## Platform awareness
- Test on: iOS (simulator), Android (emulator), Web (browser)
- Use Platform.select() only when truly necessary
- Prefer responsive design over platform-specific code
- Web push via service worker, native push via Expo Notifications
## You never
- Use external UI libraries without checking design system first
- Hardcode strings (use i18n keys)
- Skip TypeScript types
- Forget empty states or error handling
- Ignore accessibility (labels, contrast, touch targets)🎨 Design Agent (.ai/agents/designer.md)
# Design Agent
You define the visual language and user experience. You think about
how members feel when they use the app, not just how it looks.
## Design philosophy
- Member-first. The app is for the 25-year-old opening it on Sunday morning.
- Clean, modern, warm. Not corporate SaaS. Not startup bro.
- Church-appropriate but not churchy. Professional but not cold.
- Fast and responsive. No jank. Smooth transitions.
- Accessible. WCAG AA minimum.
## Design system responsibilities
- Color palette (light + dark mode)
- Typography scale (headings, body, captions)
- Spacing system (4px grid)
- Component library (buttons, cards, inputs, lists, modals, badges)
- Icon set (Lucide or similar, consistent)
- Motion/animation guidelines (subtle, purposeful)
- Platform adaptations (iOS/Android/Web differences)
## You always
- Reference `.ai/guidelines/DESIGN_SYSTEM.md`
- Think about the member journey, not isolated screens
- Consider: empty states, loading states, error states
- Design for the smallest screen first (iPhone SE)
- Consider both light and dark mode
## Output format
- Design tokens as TypeScript constants
- Component specs as annotated descriptions
- Screen flows as step-by-step user journeys
- Never assume the developer knows what "looks good" means — be specific🔍 Reviewer Agent (.ai/agents/reviewer.md)
# Reviewer Agent
You review code for quality, consistency, and architectural compliance.
You are the last gate before code merges. Be thorough but constructive.
## Review checklist (every PR)
### Architecture
- [ ] Domain layer has zero framework dependencies
- [ ] No cross-module imports (only via contracts or events)
- [ ] Deptrac passes (`make lint` includes this)
- [ ] Events are JSON-serializable with version field
- [ ] New events added to EVENT_CATALOG.md
### Code quality
- [ ] PSR-12 compliant
- [ ] Strict types declared
- [ ] No business logic in controllers
- [ ] Value objects used where appropriate (not primitive obsession)
- [ ] Error handling: specific exceptions, not generic catch-all
- [ ] No N+1 queries
- [ ] No hardcoded strings in frontend (i18n keys used)
### Testing
- [ ] Domain aggregates: unit tested (invariants, state transitions)
- [ ] Command handlers: unit tested
- [ ] API endpoints: integration tested
- [ ] Frontend: components render without errors
- [ ] Edge cases: empty states, null values, boundary conditions
### Security
- [ ] No PII in logs
- [ ] Tenant scoping on every query (no cross-tenant data leaks)
- [ ] Permission checks on every mutating endpoint
- [ ] Input validation on all DTOs
### Documentation
- [ ] Public API changes: OpenAPI spec updated
- [ ] New module: MODULE_STATUS.md updated
- [ ] New events: EVENT_CATALOG.md updated
- [ ] Breaking changes: documented in PR description
## Review output format
- Start with: what's good about this PR
- Then: what needs to change (categorize as: blocking / suggestion / nit)
- Blocking = must fix before merge
- Suggestion = should fix, can be follow-up
- Nit = style preference, take it or leave it🧪 Test Agent (.ai/agents/tester.md)
# Test Agent
You write and maintain tests. You think about what can go wrong,
not just what should work.
## Test pyramid
- **Unit tests** (fast, many): domain aggregates, value objects, services
- **Integration tests** (medium, some): repositories, API endpoints, event handlers
- **E2E tests** (slow, few): critical user flows (login → create group → RSVP)
## Patterns
- Follow `.ai/guidelines/TESTING_GUIDELINES.md`
- Use templates from `.ai/templates/test/`
- Domain tests: no database, no framework. Pure PHP assertions.
- Integration tests: use test database, fixtures, real Symfony kernel
- API tests: use WebTestCase, assert status codes + response shapes
## What to test
- Every aggregate: creation, state transitions, invariant violations
- Every command handler: happy path + validation failures
- Every API endpoint: auth required, tenant scoping, error responses
- Event emission: verify events are dispatched with correct payload
- Recurring events: RRULE computation edge cases
- Privacy: ensure privacy settings are respected in directory/profile queries
## What NOT to test
- Getter/setter boilerplate
- Framework internals (Doctrine, Symfony routing)
- Third-party library behaviorGit Workflow With AI Agents
Branch Strategy
main (production)
├── protected: requires PR + CI pass + your approval
├── auto-deploys to production on tag (v1.0.0, v1.1.0...)
│
develop (staging)
├── protected: requires PR + CI pass
├── auto-deploys to staging on merge
│
feature/{slug} (feature branches)
├── created from develop
├── one feature per branch
├── AI agent works here
├── PR to develop when ready
│
fix/{slug} (bugfixes)
├── created from develop
├── PR to develop
│
hotfix/{slug} (urgent production fixes)
├── created from main
├── PR to main AND developFeature Development Flow
1. YOU: Define the feature
├── Write a brief in .ai/context/CURRENT_SPRINT.md
├── Or: open a GitLab issue with acceptance criteria
└── Example: "Implement Groups module — CRUD API + admin backend"
2. YOU: Create the branch
git checkout develop
git checkout -b feature/groups-module
3. AI AGENT (architect role): Design
├── Read .ai/context/DOMAIN_MODEL.md (Group aggregate already defined)
├── Design the API contract (endpoints, DTOs, error responses)
├── Define events (group.created, group.member_joined, etc.)
├── Update EVENT_CATALOG.md
└── Commit: "docs: design Groups module API contract"
4. AI AGENT (backend role): Implement
├── Follow .ai/skills/create-module.md
├── Scaffold: Domain → Application → Infrastructure → Presentation
├── Use templates from .ai/templates/module/
├── Write migrations
├── Register in deptrac.yaml
├── Commit incrementally:
│ ├── "feat(groups): add Group aggregate and domain events"
│ ├── "feat(groups): add GroupRepository and Doctrine mapping"
│ ├── "feat(groups): add CRUD API endpoints"
│ └── "feat(groups): add admin backend pages"
5. AI AGENT (tester role): Write tests
├── Unit tests for Group aggregate (invariants, state transitions)
├── Integration tests for API endpoints
├── Commit: "test(groups): add unit and integration tests"
6. AI AGENT (frontend role): Build screens
├── Group list, group detail, join/leave, create group
├── Follow .ai/guidelines/FRONTEND_GUIDELINES.md
├── Commit: "feat(frontend): add Groups screens"
7. AI AGENT (reviewer role): Self-review
├── Run the review checklist from .ai/agents/reviewer.md
├── Fix any issues found
├── Ensure: `make ci` passes
└── Commit: "refactor(groups): address review findings"
8. AI AGENT: Open PR
├── PR title: "feat: Groups module — CRUD API + admin + mobile screens"
├── PR description: what was built, what events were added, what's tested
├── Link to: relevant issue, ADR, domain model section
9. YOU: Review + merge
├── Read the PR description
├── Check: does this match the domain model?
├── Check: does `make ci` pass in CI?
├── Test on staging (auto-deploys on merge to develop)
├── Approve + merge to develop
└── When ready for production: tag a release
10. CI/CD handles the rest
├── Merge to develop → deploy to staging
├── Tag v1.x.x → deploy to production
└── OTA update pushed to native apps (if JS-only change)Commit Convention
feat(module): short description — new feature
fix(module): short description — bug fix
refactor(module): short description — code restructure, no behavior change
test(module): short description — add or update tests
docs(module): short description — documentation
chore: short description — tooling, CI, dependencies
perf(module): short description — performance improvement
Examples:
feat(groups): add Group aggregate with hierarchy support
fix(events): correct RRULE timezone handling for recurring events
refactor(people): extract MemberProfile to value object
test(news): add integration tests for multi-level feed
docs: update EVENT_CATALOG with group events
chore: upgrade Symfony to 7.2Agent Coordination Patterns
Pattern 1: Sequential (most common)
Architect → Backend → Tester → Frontend → Reviewer → You
design implement test screens review approveBest for: new modules, end-to-end features.
Pattern 2: Parallel Backend + Frontend
Architect → ┬─ Backend → Tester ─┬─ Reviewer → You
design └─ Frontend ─────────┘ review approveBest for: features where API contract is defined upfront and frontend can start from mock data.
Pattern 3: Spike / Exploration
You → Architect → You (review) → decide whether to proceed
explore evaluateBest for: evaluating new technologies, designing complex features, prototyping.
Pattern 4: Bug Fix
You → Backend (or Frontend) → Tester → Reviewer → You
report fix test review approveBest for: quick fixes. Skip architect, skip design.
Pattern 5: Marketing / Docs
You → Marketing Agent → You (review) → publish
brief draft refineBest for: blog posts, website content, changelogs. No code agents involved.
Context Management: Keeping Agents In Sync
The biggest risk with AI agents is context drift — an agent generates code that contradicts a decision made earlier. The .ai/context/ directory solves this.
Living Context Files
.ai/context/CURRENT_SPRINT.md
├── Updated weekly by you
├── What's being worked on RIGHT NOW
├── Acceptance criteria for current features
├── Known blockers or decisions pending
└── Every agent reads this before starting work
.ai/context/MODULE_STATUS.md
├── Updated by agents after completing work
├── Which modules exist and their maturity:
│ ├── People: ✅ complete (API, admin, mobile, tests)
│ ├── Groups: 🚧 in progress (API done, frontend WIP)
│ ├── Events: 📋 designed (domain model ready, not implemented)
│ ├── News: 📋 designed
│ ├── Giving: ⏳ planned (Phase 2)
│ └── Chat: ⏳ planned (Phase 2)
└── Prevents agents from reimplementing what exists
.ai/context/EVENT_CATALOG.md
├── Updated by architect agent when designing modules
├── All domain events with their JSON schemas
├── Who emits, who consumes
├── Version numbers
└── The contract between all modules and the pipeline
.ai/context/ARCHITECTURE.md
├── Condensed version of the architecture blueprint
├── Key decisions and their rationale
├── What NOT to do (anti-patterns)
└── Updated when ADRs are added
.ai/context/DOMAIN_MODEL.md
├── Symlinked or copied from the main domain model doc
├── Aggregates, value objects, invariants
├── The single source of truth for what entities look like
└── Every backend agent reads this before writing domain codeContext Loading Order (What an Agent Reads)
When you say: "Implement the Events module API"
The backend agent loads (in order):
1. CLAUDE.md — project overview, rules, commands
2. .ai/agents/backend.md — role-specific behavior
3. .ai/context/CURRENT_SPRINT.md — what's being worked on
4. .ai/context/MODULE_STATUS.md — what already exists
5. .ai/context/DOMAIN_MODEL.md — Event aggregate definition
6. .ai/context/EVENT_CATALOG.md — event schemas
7. .ai/guidelines/MODULE_GUIDELINES.md — how to build a module
8. .ai/guidelines/CODING_GUIDELINES.md — code style
9. .ai/skills/create-module.md — step-by-step recipe
10. .ai/templates/module/ — code skeletons
Then starts writing code. This is why the .ai/ directory is the codebase.AI Tool Strategy
Claude Code (Primary — architecture + backend + review)
USE FOR:
├── Module implementation (backend, full DDD stack)
├── Architecture design and ADRs
├── Code review (review agent role)
├── Test writing
├── Complex refactoring
├── Multi-file changes that need consistency
└── Anything requiring deep project understanding
HOW:
├── Run from repo root: claude
├── It reads CLAUDE.md automatically
├── Direct it with role context: "Read .ai/agents/backend.md and implement..."
├── Use /read to load specific files into context
└── Let it commit directly to feature branchesCursor (Secondary — frontend + rapid iteration)
USE FOR:
├── React Native component development
├── Quick UI iterations
├── Inline code completion while designing screens
├── CSS/styling work
└── Small, focused edits
HOW:
├── Open frontend/ directory
├── .cursorrules file mirrors relevant .ai/ guidelines
├── Use for rapid component building
└── Commit to feature branchesIDE Autocomplete (Passive)
USE FOR:
├── Inline code completion (passive assistance)
├── Boilerplate generation (test fixtures, DTOs)
├── Quick pattern completion
└── Not for architecture or design decisionsQuality Gates (Automated)
EVERY PUSH TO ANY BRANCH:
├── PHPStan level 8 (static analysis)
├── Deptrac (architectural boundaries)
├── PHP CS Fixer (code style)
├── PHPUnit (unit tests)
├── ESLint + TypeScript check (frontend)
└── Total: < 3 minutes
EVERY PR TO DEVELOP:
├── All of the above +
├── Integration tests (with test database)
├── OpenAPI spec validation
├── Migration test (run on clean DB)
└── Total: < 8 minutes
EVERY MERGE TO DEVELOP:
├── Auto-deploy to staging
├── Smoke test (can the app load?)
└── Notify you: "Staging updated: {commit message}"
EVERY TAG (release):
├── Deploy to production
├── OTA update push (if JS-only)
└── Changelog generated from commit messagesGetting Started Checklist
WEEK 1 — SETUP:
├── [ ] Create repo, add CLAUDE.md
├── [ ] Create .ai/ directory structure (copy from this plan)
├── [ ] Write: CODING_GUIDELINES.md (PHP style, patterns)
├── [ ] Write: MODULE_GUIDELINES.md (step-by-step module creation)
├── [ ] Write: FRONTEND_GUIDELINES.md (RN conventions)
├── [ ] Write: GIT_WORKFLOW.md (branching, commits)
├── [ ] Create: code templates in .ai/templates/
├── [ ] Create: first ADRs (001-008 from decisions list)
├── [ ] Setup: Docker Compose (from local-dev-setup.md)
├── [ ] Setup: GitLab CI/CD pipeline
├── [ ] Setup: Symfony project skeleton with DDD structure
├── [ ] Setup: Expo project skeleton
└── [ ] Verify: `make ci` passes on empty project
THEN: Start building modules. The agents have everything they need.Status: AI-Agentic Development Plan — Ready
The .ai/ directory is the codebase. The generated code is the artifact.