bilalmk__todo_correct/docs/constitution_prompt_final.md

Prompt for Constitution Command (SDD) - Final Version

Architecture Decision

The constitution follows a two-file architecture:

1. .specify/memory/constitution.md - Pure, timeless principles (reusable)
2. CLAUDE.md - Project-specific constraints and tech stack (project-bound)

Both files reference each other to create global awareness for AI agents.

---

Constitution Prompt (Pure Principles)

Create a constitution for Spec-Driven Development projects that establishes foundational principles and standards. This constitution contains ONLY timeless principles that apply across projects.

**IMPORTANT**: Project-specific constraints (tech stack, versions, deadlines) belong in `CLAUDE.md`, not here.

---

## Constitutional Principles

### 1. Development Philosophy (WHY We Build This Way)

**Spec-First Mandate**
- No code may be written without approved specification (spec.md, plan.md, tasks.md)
- Specifications are the single source of truth for requirements
- Code that deviates from spec must be rejected or spec must be updated first
- Iterative refinement: improve spec until AI generates correct implementation

**AI-Native Engineering**
- Engineers are system architects and product designers, not code writers
- AI agents (Claude Code) generate all implementation from specifications
- Human role: clarify requirements, make decisions, validate outputs
- Agent role: explore options, generate code, execute tasks
- Collaboration: treat humans as specialized tools for judgment and clarification

**Iterative Evolution Without Breaking Changes**
- Each phase builds on previous work (no rewrites from scratch)
- Backward compatibility required for all API/schema changes
- Version all breaking changes; maintain migration paths
- Refactoring must preserve existing functionality and tests

**Reusable Intelligence**
- Capture patterns as agent skills and subagents
- Document solutions in PHRs (Prompt History Records)
- Build once, reuse across features and projects
- Share architectural learnings via ADRs (Architecture Decision Records)

**Human-AI Collaboration Protocol**
- Treat users as decision-making tools for ambiguous situations
- Ask 2-3 targeted questions when requirements are unclear
- Present options with tradeoffs; don't decide architecture alone
- Surface unexpected dependencies for human prioritization
- Checkpoint after major milestones to confirm next steps

---

### 2. Technology Selection Principles (How We Choose Tools)

These are CRITERIA for choosing technology, not specific tool mandates.

**Type Safety First**
- Prefer statically-typed languages with compile-time verification
- Use type-safe ORMs and API frameworks
- Type definitions for all data models and interfaces
- No `any` types or dynamic typing unless absolutely necessary
- Validation at compile-time prevents runtime errors

**Modern & Maintainable**
- Choose actively maintained tools with LTS (Long-Term Support)
- Prefer tools with excellent documentation and AI agent compatibility
- Avoid experimental/alpha releases for core dependencies
- Use package managers with lock files for reproducibility
- Consider community size and ecosystem maturity

**Cloud-Native & Scalable**
- All technology must support containerization (Docker)
- Services must be stateless and horizontally scalable
- Prefer managed/serverless services over self-hosted when cost-effective
- Support graceful degradation and health checks
- Infrastructure as code (declarative configuration)

**Developer & AI Experience**
- Tools must have clear, predictable APIs
- Standard patterns over magic/implicit behavior
- Comprehensive error messages with actionable suggestions
- CLI-first tools for automation and scripting
- Well-documented for both humans and AI agents

**Backend Technology Constraints**
- Must support async/non-blocking I/O for scalability
- Type-safe ORM required (no raw SQL string concatenation)
- Built-in API framework with OpenAPI/Swagger support
- Environment-based configuration (12-factor app principles)
- Built-in validation and serialization

**Frontend Technology Constraints**
- Component-based framework (no vanilla JS sprawl)
- Support for server-side rendering (SSR) or static generation (SSG)
- Utility-first CSS framework (no large custom CSS files)
- Centralized API client layer (no scattered fetch calls)
- Strong TypeScript integration

**Data Technology Constraints**
- Managed database with automatic backups and point-in-time recovery
- Support for schema migrations with rollback capability
- Connection pooling and prepared statements
- Multi-tenancy support (row-level security preferred)
- ACID compliance for transactional integrity

**Infrastructure Technology Constraints**
- Kubernetes-compatible orchestration
- Support for declarative configuration (YAML/HCL)
- Built-in observability (logs, metrics, traces)
- Cost-effective for both development and production
- Support for local development (Minikube, Docker Compose)

---

### 3. Architecture Principles (Non-Negotiable Design Patterns)

**Stateless Services**
- No in-memory session state (use database or external state store)
- Any instance can handle any request (no sticky sessions)
- Enable horizontal scaling without coordination
- Conversation/session state persisted to durable storage
- Restart-safe: server restarts don't lose user state

**API-First Design**
- All business logic exposed via well-defined APIs
- RESTful conventions for CRUD operations
- Versioned endpoints (`/api/v1/...`) to support evolution
- Consistent error response format with HTTP status codes
- OpenAPI/Swagger documentation generated from code
- API contracts tested with contract tests

**Multi-Tenancy & User Isolation**
- All data scoped by `user_id` or `tenant_id`
- Row-level security enforced at database level
- Authentication required on all non-public endpoints
- Authorization checks on every data access (never trust user_id from client)
- No cross-user data leakage in queries or responses

**Event-Driven Decoupling**
- Services communicate via events, not direct synchronous calls
- Publish events for all state changes (create, update, delete)
- Idempotent event handlers (process duplicate events safely)
- Event schema versioning for backward compatibility
- Dead letter queues for failed event processing

**Database Design Standards**
- User-scoped data: foreign key to users table with ON DELETE CASCADE
- Soft deletes preferred (`deleted_at` timestamp, not hard delete)
- Audit fields: `created_at`, `updated_at`, `created_by`, `updated_by`
- Indexes on all foreign keys and frequently queried fields
- Never expose sequential database IDs in URLs (use UUIDs or slugs)
- Timestamps in UTC, timezone conversion at presentation layer

**Error Handling & Resilience**
- Graceful degradation when dependencies fail
- Circuit breakers for external service calls
- Exponential backoff with jitter for retries
- Comprehensive error taxonomy with recovery actions
- Errors logged with context (request ID, user ID, stack trace)

---

### 4. Code Quality Standards (Non-Negotiable Practices)

**Type Safety & Validation**
- Type hints/annotations required for all function signatures
- Input validation at API boundaries (Pydantic, Zod)
- Output validation before returning to client
- No silent type coercion or implicit conversions
- Runtime validation complements compile-time checks

**Asynchronous Operations**
- Async/await for all I/O operations (DB, API calls, file I/O)
- No blocking calls in request handlers
- Connection pooling for database and HTTP clients
- Timeout configuration on all external calls
- Concurrent operations where possible (parallel API calls)

**Testing Requirements**
- Unit tests for business logic (pure functions)
- Integration tests for API endpoints (database interactions)
- E2E tests for critical user journeys
- Test coverage target: 80%+ for core features
- All tests must be deterministic (no flaky tests)
- Tests run in CI/CD pipeline before deployment

**Code Organization**
- Clear separation of concerns (models, services, controllers)
- Dependency injection for testability
- Configuration via environment variables (never hardcoded)
- No magic numbers or strings (use constants/enums)
- Single Responsibility Principle: one function, one purpose

**Documentation Standards**
- API endpoints documented with OpenAPI/Swagger
- Complex business logic explained with inline comments
- README with setup and development instructions
- Architecture diagrams in plan.md (sequence, component, deployment)
- All public functions have docstrings/JSDoc

---

### 5. Security Requirements (Mandatory Controls)

**Authentication & Authorization**
- Industry-standard protocols only (JWT, OAuth 2.0)
- Token expiration enforced (max 7 days for refresh tokens)
- Shared secrets via environment variables, never committed
- Token validation on every protected request
- User ID from token must match resource ownership
- Password hashing with bcrypt/argon2 (never plain text)

**Data Protection**
- No secrets in version control (.env in .gitignore)
- Database credentials via environment variables
- API keys stored in secret management system (Kubernetes Secrets, Dapr)
- No PII (personally identifiable information) in logs
- Encrypt sensitive data at rest and in transit (TLS 1.2+)

**Input Validation & Sanitization**
- Validate all user input against schema (whitelist, not blacklist)
- Sanitize HTML/SQL injection vectors
- Use ORM parameterized queries (no string concatenation)
- Rate limiting on authentication endpoints (prevent brute force)
- CORS configuration for production domains only
- Content Security Policy headers

**API Security**
- HTTPS/TLS required for all external traffic
- Authentication required on all non-public endpoints
- Rate limiting on expensive operations
- Request size limits to prevent DoS
- Security headers (CSP, X-Frame-Options, HSTS, X-Content-Type-Options)

---

### 6. Performance Targets (Service Level Objectives)

**Response Time SLOs**
- API endpoints: p95 < 500ms (synchronous CRUD operations)
- AI/LLM responses: < 5s (including model latency)
- Database queries: < 100ms (with proper indexes)
- Frontend: First Contentful Paint < 2s, Time to Interactive < 4s

**Throughput & Scalability**
- Support 100 concurrent users per instance (minimum)
- Horizontal scaling to 10x load without code changes
- Database connection pooling (reuse connections)
- Stateless design enables unlimited horizontal scaling
- Cache frequently accessed, rarely changing data

**Resource Efficiency**
- Memory usage < 512MB per service instance (development)
- CPU usage < 50% under normal load (leaves headroom for spikes)
- Database connection pool sized appropriately (not too large)
- Event queue processing keeps lag < 1 minute

---

### 7. Operational Standards (How We Run Systems)

**Observability Requirements**
- Structured JSON logs with request IDs for tracing
- Log levels: DEBUG (dev), INFO (prod), ERROR (always)
- Metrics: request count, latency (p50/p95/p99), error rate
- Distributed tracing for multi-service requests (OpenTelemetry)
- Health check endpoints (`/health`, `/ready`) for orchestration

**Deployment Practices**
- Immutable infrastructure (no in-place updates)
- Docker images tagged with git commit SHA (traceability)
- Helm charts for reproducible Kubernetes deployments
- Rolling updates with zero downtime
- Automated rollback on health check failures
- Blue-green or canary deployments for critical services

**Monitoring & Alerting**
- Kubernetes liveness and readiness probes configured
- Alerts on error rate >5% or latency p95 >1s
- Dead letter queues for failed events
- On-call runbooks for common incidents
- Post-mortem documents for outages (blameless)

**Secrets Management**
- Secrets injected via environment variables (12-factor)
- Kubernetes Secrets or Dapr secret store
- Rotate secrets regularly (every 90 days)
- Never log secrets, tokens, or credentials
- Audit secret access (who accessed what when)

---

### 8. Spec-Driven Development Workflow (The Process)

**Required Workflow Steps**
1. **Constitution**: Define principles (this document) - ONCE per project
2. **Specify**: Write WHAT to build (user stories, acceptance criteria) - per feature
3. **Plan**: Design HOW to build it (architecture, APIs, schemas) - per feature
4. **Tasks**: Break into atomic work units with test cases - per feature
5. **Implement**: AI generates code; human validates - per task

**Workflow Constraints**
- Never skip steps (no coding before planning)
- Never write code before specification is approved
- All code must reference Task IDs (traceability)
- Refine specs iteratively until AI generates correct output
- No "creative" implementations that deviate from plan
- Each task is independently testable

**Documentation Requirements**
- Every feature has `spec.md`, `plan.md`, `tasks.md`
- PHRs (Prompt History Records) for significant work sessions
- ADRs (Architecture Decision Records) for major decisions
- README updated with new setup steps
- CHANGELOG for user-facing changes

**Quality Gates**
- Specification reviewed and approved before planning
- Plan reviewed for architecture compliance before tasking
- Tasks include test cases before implementation
- Code passes tests before marking task complete
- All acceptance criteria met before feature is done

---

### 9. Prohibited Practices (Never Do This)

**Code & Architecture**
- ❌ Manual coding (must use AI agent generation from specs)
- ❌ Hardcoded secrets, API keys, or tokens
- ❌ Tight coupling between services (shared databases, direct calls)
- ❌ Synchronous blocking calls to external services
- ❌ Direct database access from frontend (use API layer)
- ❌ Breaking changes without versioning
- ❌ Features not specified in spec.md
- ❌ Global mutable state or singletons

**Security**
- ❌ Committing `.env` files or secrets to git
- ❌ Disabling CORS or authentication "temporarily"
- ❌ Storing passwords in plain text
- ❌ Trusting user input without validation
- ❌ SQL queries via string concatenation
- ❌ Exposing stack traces to end users

**Development Process**
- ❌ Skipping specification or planning steps
- ❌ Implementing features not in the current spec
- ❌ Cutting corners to meet deadlines (technical debt)
- ❌ Deploying without tests passing
- ❌ Ignoring code quality standards
- ❌ Merging code without review

**Operations**
- ❌ Manual deployments (must be automated)
- ❌ In-place updates (must be immutable)
- ❌ Running without health checks
- ❌ Ignoring error logs or alerts
- ❌ Deploying without rollback plan

---

### 10. Success Criteria (How We Measure Excellence)

**Functional Completeness**
- All specified features implemented and working
- All acceptance criteria in spec.md satisfied
- No critical bugs or security vulnerabilities
- User journeys flow end-to-end without errors

**Technical Excellence**
- Stateless architecture (validated via server restart test)
- Multi-user support with proper data isolation
- Event-driven architecture with decoupled services
- All services containerized and orchestrated
- Automated deployment pipeline functioning

**Spec-Driven Compliance**
- Every feature has corresponding spec, plan, and tasks files
- All tasks reference sections in spec and plan
- Constitution principles followed throughout
- PHRs created for major work sessions
- ADRs document significant architectural decisions

**Operational Readiness**
- Health checks passing (liveness and readiness)
- Logs, metrics, and traces available
- Automated deployments successful
- Rollback tested and working
- Documentation complete and accurate

---

## Project-Specific Constraints

**IMPORTANT**: This constitution contains only timeless principles. For project-specific constraints, see:

- **Technology Stack Mandates**: See `@CLAUDE.md` Section "Technology Stack Requirements"
- **Tool Versions & Compatibility**: See `@CLAUDE.md` Section "Project Constraints"
- **Phase-Specific Requirements**: See `@CLAUDE.md` Section "Hackathon Phases"
- **Deadlines & Deliverables**: See `@CLAUDE.md` Section "Submission Requirements"

The constitution defines HOW to think; CLAUDE.md defines WHAT to use for THIS project.

## Project-Specific Constraints

See `@CLAUDE.md` for:
- Technology stack mandates for THIS project
- Tool versions and compatibility requirements
- Phase-specific constraints
- Deadlines and deliverables
- Hackathon-specific rules


**Enforcement**: This constitution is binding for all AI agents and human developers. Deviations must be documented as ADRs with explicit justification.

**Precedence**: When conflicts arise:
1. Constitution (timeless principles) - highest authority
2. CLAUDE.md (project constraints) - project-specific
3. spec.md (feature requirements) - what to build
4. plan.md (architecture) - how to build
5. tasks.md (implementation) - execution steps