<!--
═══════════════════════════════════════════════════════════════════════════════
SYNC IMPACT REPORT
═══════════════════════════════════════════════════════════════════════════════
Version Change: 1.0.0 → 1.1.0 (MINOR)
Change Type: MINOR - New principles added, existing principles expanded
Modified Principles:
- Expanded: I. Code Quality First - Added TypeScript strict mode, type safety requirements
- Expanded: I. Code Quality First - Added Biome as standard linting/formatting tool
- Created: VI. Reuse Over Reinvention - New principle favoring existing solutions
Added Sections:
+ Enhanced code quality standards with TypeScript requirements
+ Biome tooling mandate
+ Type safety enforcement rules
Templates Requiring Updates:
✅ plan-template.md - Reviewed, compatible with updates
✅ spec-template.md - Reviewed, compatible with updates
✅ tasks-template.md - Reviewed, compatible with updates
Follow-up TODOs:
- None
═══════════════════════════════════════════════════════════════════════════════
-->
# HN MCP Server Constitution
## Core Principles
### I. Code Quality First
**Production-quality code with type safety and strict standards:**
- **Type Safety**: TypeScript MUST be used with `strict: true` in tsconfig.json
- **No `any` Types**: Explicit typing required - use proper types, generics, or unknown/never
- **Self-Documenting**: Clear naming conventions (functions, variables, classes)
- **Single Responsibility**: One function = one purpose. Refactor if doing multiple things
- **No Duplication**: Extract shared logic into reusable functions/modules
- **Named Constants**: Replace magic numbers and hardcoded values
- **Comprehensive Error Handling**: No silent failures - all errors MUST be caught and handled
- **Inline Comments**: Explain complex logic (the "why", not the "what")
- **Biome for Everything**: Use Biome exclusively for linting and formatting (no ESLint, Prettier, etc.)
**Rationale**: Type safety prevents runtime errors, strict TypeScript catches bugs at compile time, and Biome provides fast, unified tooling. Clean code is maintainable code.
### II. Test-Driven Development (NON-NEGOTIABLE)
**TDD is mandatory - no exceptions:**
1. **Write tests FIRST** - before any implementation code
2. **Red Phase** - Tests MUST fail initially (proves they work)
3. **Get approval** - Review tests with team before implementing
4. **Green Phase** - Write minimal code to pass tests
5. **Refactor** - Improve code while keeping tests green
6. **Coverage** - Maintain ≥90% test coverage for all new code
**Test Types Required:**
- **Contract Tests**: Verify all API boundaries and data schemas
- **Integration Tests**: Cover cross-module interactions
- **Unit Tests**: Isolate functionality with mocks/stubs
**Test Quality:**
- Independent (no test interdependencies)
- Repeatable (same results every run)
- Fast (quick feedback loop)
**Rationale**: TDD catches bugs early, ensures testable design, provides living documentation, and enables confident refactoring.
### III. User Experience Consistency
**Deliver consistent, predictable experiences:**
- **Documented Patterns**: UX patterns documented and reused across features
- **Clear Error Messages**: User-friendly, actionable (not stack traces)
- **Explicit States**: Loading, error, and empty states handled for all UI
- **Performance Budgets**: Response times defined per feature
- **Accessibility**: WCAG 2.1 AA minimum for all interfaces
- **Predictable Behavior**: Same input = same output
- **Immediate Feedback**: Users know what's happening at all times
**Rationale**: Consistent UX reduces cognitive load, builds trust, and decreases support burden.
### IV. Documentation-First with Context7
**Documentation is mandatory, not optional:**
- **Context7 for Libraries**: ALWAYS use Context7 tools to get latest library docs
- **API Docs**: Written when designing endpoints (before implementation)
- **Architecture Decisions**: Document rationale in ADRs
- **README Files**: Comprehensive with working examples
- **Breaking Changes**: Include migration guides
- **Dependencies**: Document version constraints and selection rationale
**Context7 Workflow:**
1. Call `resolve-library-id` to find the library
2. Call `get-library-docs` with resolved ID
3. Reference docs during implementation
4. Update docs as APIs evolve
**Rationale**: Context7 provides current, accurate docs. Good documentation accelerates onboarding and serves as a contract.
### V. Always Use Latest Stable Versions
**Stay current - technical debt compounds:**
- **At Project Start**: Use latest stable (non-beta) versions
- **Dependency Updates**: Apply within 30 days of stable release
- **Security Updates**: Apply within 7 days of disclosure
- **Test After Updates**: Verify affected features work
- **Quarterly Reviews**: Check for deprecation notices
- **Commit Lock Files**: package-lock.json, pnpm-lock.yaml, etc.
**Version Priority:**
1. Latest stable (preferred)
2. Latest LTS (if stability critical)
3. Previous major (only with documented blocker)
**Rationale**: Latest versions = security patches + performance + new features. Old versions accumulate vulnerabilities and become harder to upgrade.
### VI. Reuse Over Reinvention
**Don't build what already exists:**
- **Search First**: Before writing custom code, search for existing solutions
- **Use Packages**: Prefer well-maintained packages over custom implementations
- **Leverage Examples**: Use official sample code and documentation examples
- **Justify Custom Code**: Document why existing solutions don't work
- **Share Patterns**: Extract reusable patterns from successful implementations
**Examples:**
- Need date handling? Use `date-fns` or `luxon`, not custom functions
- Need validation? Use `zod` or `yup`, not custom validators
- Need HTTP client? Use `fetch` or `axios`, not custom wrappers
- Need routing? Use framework's router, not custom routing logic
**Rationale**: Existing solutions are battle-tested, maintained by communities, and save development time. Focus effort on unique business value, not reinventing wheels.
## Quality Standards
### Code Review
- At least one reviewer required
- Verify constitution compliance
- Check test coverage and quality
- Validate documentation completeness
- Must pass CI/CD pipeline
### TypeScript Standards
- **Strict Mode**: `strict: true` in tsconfig.json (non-negotiable)
- **No Any**: Explicit typing required - use proper types or unknown/never
- **Type Guards**: Use type predicates for runtime type checking
- **Generics**: Prefer generics over any for flexible, type-safe code
- **Return Types**: Explicit return types on all exported functions
### Modularity
- **Separation of Concerns**: Each module has one clear purpose
- **Loose Coupling**: Modules depend on interfaces, not implementations
- **High Cohesion**: Related functionality grouped together
- **Clear Boundaries**: Public APIs clearly defined and documented
### Tooling
- **Biome Only**: All linting and formatting via Biome (no ESLint, Prettier)
- **Configuration**: Maintain biome.json with project standards
- **Pre-commit Hooks**: Auto-format and lint on commit
- **CI Integration**: Biome checks must pass in CI pipeline
### Performance
- Define response time budgets per feature
- Profile memory usage for intensive operations
- Optimize database queries (no N+1)
- Implement caching where appropriate
### Security
- Input validation at all entry points
- Consistent authentication/authorization
- Encrypt sensitive data (rest + transit)
- Highest priority for vulnerabilities
## Development Workflow
### Feature Process
1. **Specify** - Create spec with prioritized user stories (P1, P2, P3)
2. **Plan** - Technical design: architecture, data models, API contracts
3. **Test-First** - Write comprehensive tests (contract, integration, unit)
4. **Implement** - Code to pass tests using TDD cycle
5. **Document** - Update all docs (API, README, ADRs)
6. **Review** - Code review verifying constitution compliance
7. **Deploy** - CI/CD pipeline with automated testing
### Quality Gates (All Required)
- ✅ All tests passing (≥90% coverage)
- ✅ Biome checks passing (zero warnings)
- ✅ TypeScript strict mode (no `any` types)
- ✅ Documentation complete
- ✅ Performance benchmarks met
- ✅ Security scan passed
- ✅ Code review approved
## Governance
### Constitution Authority
- Supersedes all other development practices
- All PRs and reviews must verify compliance
- Exceptions require documentation with rationale and expiration plan
- Non-compliance flagged immediately and remediated before merge
### Amendment Process
- Requires documented proposal with rationale
- Must be reviewed by project maintainers
- Must include migration plan if affecting existing code
- Version bumps follow semantic versioning:
- **MAJOR**: Principle removal/redefinition or breaking governance changes
- **MINOR**: New principle or material expansion of existing principle
- **PATCH**: Clarifications, wording improvements, typo fixes
### Compliance Review
- Verify in every pull request
- Quarterly project adherence assessments
- Refactor or remove non-compliant code
**Version**: 1.1.0 | **Ratified**: 2025-10-30 | **Last Amended**: 2025-10-30
