ContractSpec Codebase

# ContractSpec Codebase

**Mission**: ContractSpec is the deterministic, spec-first compiler that keeps AI-written software coherent, safe, and regenerable.

## Quick Reference

| Concern | Rule File | Key Points |
|---------|-----------|------------|
| **Contracts** | `contracts-first.md` | Spec before implementation |
| Mission & Context | `contractspec-mission.md` | Why we exist, who we serve |
| Architecture | `package-architecture.md` | libs → bundles → apps |
| Code Quality | `code-quality-practices.md` | Testing, naming, standards |
| File Organization | `code-splitting.md` | Max 250 lines, domain grouping |
| Type Safety | `type-safety-dependencies.md` | No `any`, latest deps |
| Frontend | `frontend.md` | Atomic design, state handling |
| Backend | `backend.md` | Hexagonal, DDD |
| Design System | `design-system-usage.md` | No raw HTML |
| AI Governance | `ai-agent.md` | Traceability, composability |
| Documentation | `docs.md` | DocBlocks first |

## Core Principles

1. **Spec-First**: Contracts define behavior before implementation
2. **Multi-Surface Consistency**: One spec → API, DB, UI, events
3. **Safe Regeneration**: Code can be regenerated without breaking invariants
4. **Standard Tech**: TypeScript, Zod, no magic abstractions
5. **Incremental Adoption**: Stabilize one module at a time

## Code Style (Enforced)

- **Language**: TypeScript (strict mode)
- **Formatting**: 2 spaces, semicolons, double quotes, trailing commas
- **Types**: Explicit, no `any`, proper type guards
- **Files**: Max 250 lines (components: 150, utilities: 100)

## Before You Code

1. Read relevant rules for your change type
2. Check existing patterns in the codebase
3. Plan with DocBlocks if adding new features
4. Run `/ai-audit` to verify decisions

## AI Agent Guidelines

When working with AI assistants:
- Rules are applied contextually based on file type
- Conflicts resolved by: Security > Compliance > Safety > Quality > UX > Performance
- All decisions should be traceable and reversible
- Use `/ai-audit` to verify governance compliance

## Commands Available

- `/commit` - Create conventional commit
- `/test` - Run tests with analysis
- `/lint` - Check and fix lint issues
- `/fix` - Auto-fix common issues
- `/explain` - Understand code
- `/refactor` - Guided refactoring
- `/review-pr` - Code review
- `/ai-audit` - Governance check

## Getting Help

- Check the specific rule file for detailed guidance
- Use `/explain <concept>` for architecture questions
- Run `/ai-audit` to verify your approach