CLAUDE.md

1# CLAUDE.md
2 
3## AI Assistant Context for SAFe Multi-Agent Development
4 
5**Repository**: {{PROJECT_NAME}}
6**Methodology**: SAFe (Scaled Agile Framework) Agentic Workflow
7**Philosophy**: "Round Table" - Equal voice, mutual respect, shared responsibility
8 
9---
10 
11## Quick Start
12 
13This is a **SAFe multi-agent development project** with 11 specialized AI agents working collaboratively. You are part of a team where your input has equal weight with human contributors.
14 
15**Core Principles**:
16- Search for existing patterns before creating new ones ("Search First, Reuse Always")
17- Attach evidence to Linear tickets for all work
18- You have "stop-the-line" authority for architectural/security concerns
19- Follow SAFe methodology: Epic → Feature → Story → Enabler
20 
21**Key Resources**:
22- [AGENTS.md](AGENTS.md) - All 11 agent roles, invocation patterns, capabilities
23- [CONTRIBUTING.md](CONTRIBUTING.md) - Git workflow, commit standards, PR process
24- [docs/onboarding/](docs/onboarding/) - Setup guides and daily workflows
25- [docs/guides/ROUND-TABLE-PHILOSOPHY.md](docs/guides/ROUND-TABLE-PHILOSOPHY.md) - Collaboration principles
26- [patterns_library/](patterns_library/) - Reusable code patterns (18+ patterns, 7 categories)
27- [knowledge-vault/](knowledge-vault/README.md) - Evidence-verified knowledge base. To build this repo's own vault, run [SAW-VAULT-BUILD.md](knowledge-vault/docs/SAW-VAULT-BUILD.md)
28 
29---
30 
31## Development Commands
32 
33```bash
34# Development server
35{{DEV_COMMAND}}              # Start development server
36 
37# Build and production
38{{BUILD_COMMAND}}            # Build for production
39{{START_COMMAND}}            # Start production server
40 
41# Code quality
42{{LINT_COMMAND}}             # Run linting
43{{LINT_FIX_COMMAND}}         # Auto-fix linting issues
44{{TYPE_CHECK_COMMAND}}       # TypeScript validation
45{{FORMAT_CHECK_COMMAND}}     # Prettier formatting check
46 
47# Testing
48{{TEST_UNIT_COMMAND}}        # Run unit tests
49{{TEST_INTEGRATION_COMMAND}} # Run integration tests
50{{TEST_E2E_COMMAND}}         # Run end-to-end tests
51 
52# Database (if applicable)
53{{DB_MIGRATE_COMMAND}}       # Run migrations
54 
55# CI/CD validation (REQUIRED before PR)
56{{CI_VALIDATE_COMMAND}}      # Run all quality checks
57```
58 
59**Important**: Always run `{{CI_VALIDATE_COMMAND}}` before creating a pull request.
60 
61---
62 
63## Architecture Overview
64 
65### Technology Stack
66 
67- **Frontend**: {{FRONTEND_FRAMEWORK}}
68- **Backend**: {{BACKEND_FRAMEWORK}}
69- **Database**: {{DATABASE_SYSTEM}}
70- **ORM**: {{ORM_TOOL}}
71- **Authentication**: {{AUTH_PROVIDER}}
72- **Payments**: {{PAYMENT_PROVIDER}}
73- **Analytics**: {{ANALYTICS_PROVIDER}}
74- **UI Components**: {{UI_LIBRARY}}
75 
76### Repository Structure
77 
78```
79{{PROJECT_NAME}}/
80├── CLAUDE.md                    # This file - AI assistant context
81├── AGENTS.md                    # Agent team quick reference
82├── CONTRIBUTING.md              # Git workflow and commit standards
83├── docs/                        # Documentation (onboarding, database, security, sop, workflow)
84├── specs/                       # SAFe specifications (Epic/Feature/Story)
85├── patterns_library/            # Reusable code patterns (7 categories)
86├── .claude/                     # Claude Code harness (hooks, commands, skills, agents)
87├── agent_providers/             # Agent configurations
88└── scripts/                     # Utility scripts
89```
90 
91---
92 
93## SAFe Workflow
94 
95All work follows the SAFe hierarchy and specs-driven development:
96 
971. BSA creates spec in `specs/{{TICKET_PREFIX}}-XXX-feature-spec.md`
982. System Architect validates architectural approach
993. Implementation agents execute with pattern discovery
1004. QAS validates against acceptance criteria
1015. Evidence attached to Linear ticket before POPM review
102 
103### Metacognitive Tags
104 
105Use in specs to highlight critical decisions:
106- `#PATH_DECISION` - Architectural path chosen (document alternatives)
107- `#PLAN_UNCERTAINTY` - Areas requiring validation
108- `#EXPORT_CRITICAL` - Security/compliance requirements
109 
110### Pattern Discovery Protocol (MANDATORY)
111 
112**Before implementing ANY feature:**
113 
1141. Search `patterns_library/` for existing patterns
1152. Search `specs/` for similar specifications
1163. Search codebase for similar implementations
1174. Consult documentation: [CONTRIBUTING.md](CONTRIBUTING.md), [docs/database/](docs/database/), [docs/security/](docs/security/)
1185. Propose to System Architect before implementation
119 
120---
121 
122## Project-Specific Implementation Notes
123 
124*Customize this section for your technology stack.*
125 
126### Authentication
127 
128**Provider**: {{AUTH_PROVIDER}}
129 
130- Environment variables: See `.env.template`
131- Routes: {{AUTH_ROUTES}} / {{PROTECTED_ROUTES}}
132- Patterns: `patterns_library/` + [docs/security/SECURITY_FIRST_ARCHITECTURE.md](docs/security/SECURITY_FIRST_ARCHITECTURE.md)
133 
134### Payments
135 
136**Provider**: {{PAYMENT_PROVIDER}}
137 
138- Webhook endpoints: {{WEBHOOK_ROUTES}}
139- Patterns: `patterns_library/api/webhook-handler.md`
140- Idempotency required for all payment operations
141 
142### Analytics
143 
144**Provider**: {{ANALYTICS_PROVIDER}}
145 
146- Privacy-first: No tracking without explicit consent (GDPR/CCPA)
147- Error boundaries: Analytics failures must not crash the app
148 
149### Database
150 
151**System**: {{DATABASE_SYSTEM}} | **ORM**: {{ORM_TOOL}}
152 
153**Guidelines**:
154- Always use ORM (type safety) with RLS context helpers (`withUserContext`, `withAdminContext`, `withSystemContext`)
155- Always create proper migrations (never `db push` in production)
156- Never use direct SQL or bypass RLS policies
157 
158**Schema Docs**: [docs/database/DATA_DICTIONARY.md](docs/database/DATA_DICTIONARY.md) (single source of truth)
159 
160**Migration Workflow**:
161```bash
162{{MIGRATION_CREATE_COMMAND}}     # Create migration
163{{MIGRATION_TEST_COMMAND}}       # Test locally
164git add {{MIGRATIONS_DIR}}/ && git commit -m "feat(db): add feature migration"
165{{MIGRATION_DEPLOY_COMMAND}}     # Deploy to production
166```
167 
168---
169 
170## Code Quality
171 
172**Linter**: {{LINTER_TOOL}} | **Config**: {{LINTER_CONFIG_FORMAT}}
173 
174```bash
175{{LINT_COMMAND}}          # Run linter
176{{LINT_FIX_COMMAND}}      # Auto-fix issues
177```
178 
179Always run `{{LINT_COMMAND}}` before committing. Consult your linting configuration file for project-specific rules.
180 
181---
182 
183## CI/CD Pipeline
184 
185**MANDATORY**: Read [CONTRIBUTING.md](CONTRIBUTING.md) before any development.
186 
187### PR Workflow
188 
1891. Create feature branch: `{{TICKET_PREFIX}}-{number}-{description}`
1902. Implement with proper commits: `type(scope): description [{{TICKET_PREFIX}}-XXX]`
1913. Rebase: `git rebase origin/{{MAIN_BRANCH}}`
1924. Validate: `{{CI_VALIDATE_COMMAND}}` (must pass)
1935. Push: `git push --force-with-lease`
1946. Create PR using `.github/pull_request_template.md`
1957. Merge using "Rebase and merge" only
196 
197### Branch Protection
198 
199- All PRs must be up-to-date with `{{MAIN_BRANCH}}`
200- All CI checks must pass
201- CODEOWNERS reviewers required
202- No direct pushes to `{{MAIN_BRANCH}}`
203 
204**Detailed Guides**: [docs/ci-cd/CI-CD-Pipeline-Guide.md](docs/ci-cd/CI-CD-Pipeline-Guide.md) | [docs/workflow/](docs/workflow/)
205