ContractSpec Codebase
Defines a spec-first compiler approach for AI-generated code, with rules, commands, and governance for multi-surface consistency.
What this file does
Defines a spec-first compiler approach for AI-generated code, with rules, commands, and governance for multi-surface consistency.
When to use it
- Adopting a contract-first workflow for AI-assisted development
- Setting up governance and traceability for AI code generation
- Standardizing code style and file size limits across a TypeScript project
- Establishing a regeneration-safe codebase with spec-driven consistency
Assumes this stack
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
- Spec-First: Contracts define behavior before implementation
- Multi-Surface Consistency: One spec → API, DB, UI, events
- Safe Regeneration: Code can be regenerated without breaking invariants
- Standard Tech: TypeScript, Zod, no magic abstractions
- 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
- Read relevant rules for your change type
- Check existing patterns in the codebase
- Plan with DocBlocks if adding new features
- Run
/ai-auditto 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-auditto 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-auditto verify your approach
What's inside
One mission statement, 5 core principles, 4 code style rules, 3 pre-coding steps, 8 commands, and a table of 11 rule files.
Change this for your project
- Replace
lssm-tech/contractspecwith your own repository name - Replace
/ai-auditwith your own governance command if different - Replace
ContractSpecwith your project's compiler or tool name
Where it goes
Keep it in your repository where the agent or team that needs it will read it.
Worth borrowing
- Spec-first contracts that define behavior before implementation
- Conflict resolution hierarchy: Security > Compliance > Safety > Quality > UX > Performance
- Max line limits per file type (250 general, 150 components, 100 utilities)
Related Documents
GOOBY - Closing Store Marketplace
Defines a full-stack marketplace app for discovering closing retail stores in NY/NJ/CT/PA, with automated closure scanning and admin review.
Lua Code Obfuscator/Deobfuscator
Provides a full-stack web app for obfuscating and deobfuscating Roblox Lua scripts with a Monaco editor and PostgreSQL storage.
GREEN NODE - Project Overview
Describes a full-stack recycling platform with three runtime modes, provider architecture, and development scripts for Cochabamba, Bolivia.
ADN Systems DMR Peer Server
Documents a forked FreeDMR server for amateur radio DMR voice/data routing with bridges, proxies, scheduled voice announcements, and centralized security.