<!--
Sync Impact Report:
Version Change: 1.0.0 → 1.1.0 (MINOR: New guidance added)
Modified Principles:
- Principle I (Code Quality First): Added "Prefer Existing Solutions" bullet, updated formatting tool to Biome
- Development Standards: Updated tooling to Biome (TS/JS), added Code Reuse Philosophy
Rationale for MINOR bump: Material expansion of Code Quality principle with reuse philosophy
Added Sections: None
Removed Sections: None
Templates Requiring Updates:
✅ constitution.md - Updated
✅ plan-template.md - Updated: Added "existing solutions evaluated" check
✅ tasks-template.md - Updated: Changed ESLint+Prettier to Biome, added "Evaluate Packages" task
✅ checklist-template.md - Updated: Added CHK007 for existing solutions evaluation, updated linting checks to Biome
✅ agent-file-template.md - No changes needed (already generic)
Follow-up TODOs: None - All templates synchronized
-->
# HN MCP Server Constitution
## Core Principles
### I. Code Quality First (NON-NEGOTIABLE)
Every code change MUST meet these standards before merge:
- **Zero Technical Debt**: No TODOs, FIXMEs, or temporary hacks without explicit acceptance and tracking
- **Type Safety**: Full type annotations/declarations required (TypeScript strict mode, Python type hints, etc.)
- **Linting Clean**: Zero linter warnings or errors; all auto-fixable issues must be fixed
- **Formatting Consistent**: Code formatted via automated tools (Biome for JS/TS, Black for Python, etc.)
- **Self-Documenting**: Clear variable names, functions under 50 lines, single responsibility principle
- **Documentation Complete**: All public APIs documented with examples; complex logic has inline comments
- **Prefer Existing Solutions**: Use established packages and sample code over custom implementations; only write custom code when existing solutions inadequate
**Rationale**: Code is read 10x more than written. Quality standards prevent compounding technical debt and ensure maintainability. Existing solutions are battle-tested and reduce maintenance burden.
### II. Test-First Development (NON-NEGOTIABLE)
Test-Driven Development (TDD) is mandatory for all features:
- **Red-Green-Refactor Cycle**: Tests written → Tests fail → Implement → Tests pass → Refactor
- **User Story Approval**: Tests must be reviewed and approved BEFORE implementation begins
- **Test Coverage Minimum**: 80% code coverage for all new code; 100% for critical paths
- **Test Types Required**:
- **Unit Tests**: All functions, methods, and modules
- **Integration Tests**: API endpoints, data flows, external service interactions
- **Contract Tests**: MCP tool interfaces, API contracts, public interfaces
- **Test Quality**: Tests must be deterministic, fast (<5s suite), isolated, and maintainable
**Rationale**: TDD catches bugs early (10-100x cheaper), ensures testability, serves as living documentation, and prevents regressions.
### III. User Experience Consistency
All user-facing interfaces MUST maintain consistency:
- **MCP Tool Naming**: Clear, verb-based names following MCP conventions (e.g., `get_story`, `search_stories`)
- **Parameter Design**: Consistent naming, required vs optional clarity, sensible defaults
- **Error Messages**: Human-readable, actionable, include context and suggestions
- **Response Format**: Consistent structure across similar operations; JSON for structured data
- **Documentation Standards**: Every tool has description, parameter docs, usage examples, error scenarios
- **Versioning Strategy**: Breaking changes require major version bump; deprecation warnings required 2 releases before removal
**Rationale**: Consistent UX reduces cognitive load, improves discoverability, and creates predictable behavior that users can rely on.
### IV. Latest Dependencies Always
Dependency management follows strict currency requirements:
- **Context7 MCP MUST**: Always use Context7 MCP tools to retrieve latest library documentation before implementing features
- **Latest Stable Versions**: All packages MUST use latest stable versions unless explicit security/compatibility concern documented
- **Monthly Dependency Audits**: Dependencies reviewed first Monday of each month; updates applied within 1 week
- **Security Updates Immediate**: CVE patches applied within 24 hours of disclosure
- **Deprecation Tracking**: Deprecated dependencies replaced within 2 release cycles
- **Version Pinning**: Exact versions in lock files; ranges only for peer dependencies
- **Documentation Currency**: Before using any library, consult Context7 to ensure using current API patterns
**Rationale**: Latest versions include security patches, performance improvements, bug fixes, and modern API patterns. Staying current prevents painful migration cycles.
### V. Documentation-Driven Development
Documentation is not optional; it drives development:
- **Context7 First**: Before implementing any external library integration, retrieve latest docs via Context7 MCP
- **Specification Before Code**: Feature specs (spec.md) written and approved before any code
- **API Documentation**: All MCP tools documented with schemas, examples, error cases
- **Architecture Decisions**: Major design choices documented in ADR (Architecture Decision Records) format
- **Quickstart Guides**: Every feature has working example users can run in <5 minutes
- **Changelog Discipline**: CHANGELOG.md updated with every PR; follows Keep a Changelog format
**Rationale**: Documentation ensures shared understanding, enables onboarding, prevents miscommunication, and serves as contract between stakeholders.
### VI. Integration Testing Discipline
Integration tests validate real-world scenarios:
- **MCP Tool Integration**: Every MCP tool has integration test calling actual Hacker News API (with rate limiting)
- **Contract Validation**: API contracts tested against actual responses; schema validation enforced
- **Error Scenario Coverage**: Network failures, rate limits, malformed responses all tested
- **End-to-End Flows**: User stories validated through full integration test suites
- **External Service Mocking**: Test fixtures for offline testing; integration tests for online validation
- **Performance Baselines**: Integration tests track response times; alerts on 20% regression
**Rationale**: Unit tests verify components in isolation, but integration tests catch real-world failures, API changes, and system-level issues.
### VII. Observability & Debuggability
Systems must be observable and debuggable:
- **Structured Logging**: JSON logs with correlation IDs, severity levels, timestamps, context
- **Error Context**: Errors include stack traces, input parameters, system state at failure
- **Performance Metrics**: Response times, rate limit consumption, cache hit rates tracked
- **Health Endpoints**: MCP server exposes health/status information
- **Tracing**: Request flows traceable across async operations
- **Debug Mode**: Verbose logging available via environment variable without code changes
**Rationale**: Production issues require rapid diagnosis. Comprehensive observability reduces mean time to resolution from hours to minutes.
## Development Standards
### Code Review Requirements
- All PRs require at least one approval
- Constitution compliance checklist completed
- Test coverage verified (no coverage decrease)
- Documentation updated
- No linter warnings
- Integration tests passing
### Technology Stack Standards
- **Language**: TypeScript/JavaScript (Node.js LTS) or Python 3.11+
- **MCP Framework**: Model Context Protocol latest stable
- **Testing**: Jest/Vitest (TS/JS) or pytest (Python)
- **Linting & Formatting**: Biome (TS/JS) or ruff + black (Python)
- **Type Checking**: TypeScript strict mode or mypy strict
- **Documentation**: JSDoc/TSDoc or Python docstrings
- **Code Reuse Philosophy**: Prefer npm packages, reference implementations, and sample code over custom solutions
### Performance Standards
- MCP tool response time <2 seconds for 95th percentile
- Rate limit compliance with Hacker News API (no more than 1 req/sec)
- Memory usage <200MB for server process
- Cold start time <5 seconds
## Quality Gates
Every PR MUST pass these gates before merge:
**Gate 1: Constitution Compliance**
- [ ] Code Quality First: Zero linter errors, types complete, documented
- [ ] Test-First Development: Tests written first, TDD cycle followed, 80%+ coverage
- [ ] UX Consistency: Naming conventions followed, error messages clear
- [ ] Latest Dependencies: Context7 consulted, latest stable versions used
- [ ] Documentation-Driven: Specs written first, API docs complete
- [ ] Integration Testing: Integration tests passing, contracts validated
- [ ] Observability: Structured logging added, error context included
**Gate 2: Automated Checks**
- [ ] All tests passing (unit + integration + contract)
- [ ] Code coverage ≥80% (no decrease from baseline)
- [ ] Linter clean (zero warnings or errors)
- [ ] Type checker passing (strict mode)
- [ ] Build successful
- [ ] No security vulnerabilities (npm audit / pip-audit)
**Gate 3: Manual Review**
- [ ] Code review approved
- [ ] Documentation review approved
- [ ] Test quality verified (not just coverage, but meaningful tests)
- [ ] Complexity justified if constitution violations exist
## Governance
**Authority**: This constitution supersedes all other development practices and preferences. When in doubt, constitution principles win.
**Amendment Process**:
1. Proposed amendments documented with rationale and impact analysis
2. Team discussion and consensus building
3. Version increment following semantic versioning:
- **MAJOR**: Backward incompatible governance/principle removals or redefinitions
- **MINOR**: New principle/section added or materially expanded guidance
- **PATCH**: Clarifications, wording, typo fixes, non-semantic refinements
4. Update all dependent templates (plan, spec, tasks, checklist)
5. Migration plan for existing code if needed
**Compliance Review**: Every PR includes constitution compliance checklist. Violations require explicit justification in "Complexity Tracking" section of plan.md.
**Enforcement**: Violations blocking merge unless:
- Documented in Complexity Tracking table
- Alternative approach explicitly considered and rejected with reasoning
- Temporary exemption approved with remediation timeline
**Living Document**: Constitution reviewed quarterly; outdated principles updated or removed; new principles added as patterns emerge.
**Version**: 1.1.0 | **Ratified**: 2025-10-12 | **Last Amended**: 2025-10-12
