HackerNews MCP Server

<!-- ================================================================================ SYNC IMPACT REPORT ================================================================================ Version Change: 1.1.0 → 1.2.0 Modified Principles: - UPDATED: II. Testing Standards → II. Test-Driven Development - Strengthened TDD requirements and made it the ONLY permitted methodology - UPDATED: IV. Documentation-First Development - Added Mermaid diagram requirements - NEW: VII. Diagram Standards - Added principle requiring Mermaid charts instead of plain text Previous Version (1.1.0): - NEW: I. Code Quality Standards - NEW: II. Testing Standards (NON-NEGOTIABLE) - NEW: III. User Experience Consistency - NEW: IV. Documentation-First Development - NEW: V. Dependency Hygiene - NEW: VI. Prefer Existing Solutions Added Sections: - Core Principles (7 principles defined) Templates Requiring Updates: ✅ plan-template.md - Updated Constitution Check section to reflect new principle numbers and strengthened TDD requirements ✅ data-model.md - Convert ASCII entity relationships diagram to Mermaid format ✅ ARCHITECTURE.md - Convert ASCII flow diagrams to Mermaid format Follow-up TODOs: - Convert any remaining ASCII diagrams in ARCHITECTURE.md to Mermaid format ================================================================================ --> # HN MCP Server Constitution ## Core Principles ### I. Code Quality Standards All code MUST maintain high quality standards that ensure maintainability, readability, and robustness: - **Type Safety**: TypeScript MUST be used with strict mode enabled. No `any` types without explicit justification. - **Code Style**: Consistent formatting and linting enforced via Biome. Code MUST pass Biome checks before commit. Biome configuration MUST be project-wide and version controlled. - **Modularity**: Functions and modules MUST have single, well-defined responsibilities. Maximum function complexity as measured by cyclomatic complexity SHOULD NOT exceed 10. - **Documentation**: All public APIs, complex algorithms, and non-obvious code MUST include inline documentation explaining purpose and behavior. - **Error Handling**: All error conditions MUST be explicitly handled. Silent failures are prohibited. **Rationale**: High-quality code reduces bugs, accelerates onboarding, and enables sustainable long-term development. Type safety catches errors at compile time rather than runtime. Biome provides fast, consistent linting and formatting with zero configuration conflicts. ### II. Test-Driven Development (NON-NEGOTIABLE) Test-Driven Development is the ONLY permitted development methodology: - **TDD Mandatory**: ALL code MUST be developed using Test-Driven Development. No code may be written without corresponding failing tests first. - **Red-Green-Refactor Cycle**: Strictly enforced for ALL development work. Tests MUST fail before implementation, pass after implementation, then code MUST be refactored while maintaining test coverage. - **Test Coverage Requirements**: Minimum 80% code coverage for all new features. Critical paths MUST achieve 100% coverage. Coverage MUST be maintained or improved with every change. - **Test Types Required**: - **Unit Tests**: All functions and modules MUST have unit tests - **Integration Tests**: All API endpoints and external service interactions MUST have integration tests - **Contract Tests**: All public interfaces MUST have contract tests to prevent breaking changes - **Test Quality**: Tests MUST be independent, repeatable, and fast. No flaky tests permitted in main branch. Tests MUST serve as living documentation. - **Continuous Testing**: All tests MUST pass before code can be merged. CI/CD pipeline MUST run all tests on every commit. No exceptions permitted. - **Test-First Planning**: Development tasks MUST include test planning before implementation begins. Test scenarios MUST be defined before coding starts. **Rationale**: TDD is the only proven methodology that guarantees quality, prevents regressions, and enables confident refactoring. Without TDD, code quality cannot be assured and technical debt accumulates rapidly. ### III. User Experience Consistency All user-facing features MUST provide a consistent, predictable experience: - **Interface Consistency**: UI patterns, terminology, and interaction models MUST be consistent across all features. - **Response Times**: User-facing operations MUST complete within 200ms for synchronous operations, 2 seconds for complex operations. Loading states MUST be shown for any operation exceeding 200ms. - **Error Messages**: User-facing error messages MUST be clear, actionable, and consistent in tone. Technical stack traces MUST NOT be exposed to end users. - **Accessibility**: All interfaces MUST meet WCAG 2.1 Level AA standards. Keyboard navigation MUST be fully supported. - **Progressive Enhancement**: Core functionality MUST work without JavaScript. Enhanced features can require JavaScript but MUST degrade gracefully. **Rationale**: Consistent UX reduces cognitive load, increases user confidence, and improves overall satisfaction. Accessibility ensures the product is usable by all people. ### IV. Documentation-First Development Documentation is not optional and MUST be maintained throughout development: - **Context7 MCP Requirement**: Latest library documentation MUST be retrieved using Context7 MCP before implementing any feature using external dependencies. No assumptions about API behavior permitted. - **Architecture Documentation**: All architectural decisions MUST be documented with rationale in ADR (Architecture Decision Record) format. - **API Documentation**: All public APIs MUST have OpenAPI/Swagger documentation that is automatically generated and kept in sync with implementation. - **User Documentation**: All user-facing features MUST have corresponding user documentation completed before feature is considered done. - **Code Comments**: Complex logic MUST include explanatory comments. Comments MUST explain "why" not "what". - **Diagram Standards**: All diagrams and flowcharts should use Mermaid syntax in Markdown where applicable. Plain text ASCII diagrams are discouraged except for folder/file structure. **Rationale**: Documentation enables effective collaboration, reduces onboarding time, and serves as a contract for API consumers. Context7 MCP ensures we always work with accurate, up-to-date documentation. Mermaid provides standardized, accessible, and maintainable diagrams. ### V. Dependency Hygiene Dependencies MUST be actively managed to minimize security risks and technical debt: - **Latest Versions Required**: All dependencies MUST use the latest stable versions unless a specific version is required for compatibility. Version pinning requires explicit justification. - **Dependency Audits**: Security audits MUST be run on every dependency update. Critical vulnerabilities MUST be addressed within 48 hours. - **Minimal Dependencies**: New dependencies MUST be justified by substantial value. Prefer standard library solutions when available. - **License Compatibility**: All dependencies MUST have licenses compatible with project license. GPL/AGPL dependencies require explicit approval. - **Dependency Updates**: Dependencies MUST be reviewed and updated at least monthly. Automated dependency update PRs MUST be reviewed within 1 week. **Rationale**: Up-to-date dependencies minimize security vulnerabilities and ensure access to latest features and performance improvements. Careful dependency management prevents bloat and supply chain attacks. ### VI. Prefer Existing Solutions Code reuse and leveraging existing solutions MUST take precedence over custom implementations: - **Search First**: Before writing custom code, MUST search for existing packages, libraries, or sample code that solve the problem. - **Use Context7 MCP**: MUST use Context7 MCP to find official examples, sample code, and recommended patterns from library documentation. - **Evaluate Before Building**: Custom implementations require written justification explaining why existing solutions are inadequate. - **Contribute Upstream**: If modifying existing code, MUST consider contributing improvements back to the original project. - **Document Sources**: All reused code MUST include attribution and links to original sources. - **Prefer Battle-Tested**: Well-maintained packages with active communities are preferred over writing from scratch. **Rationale**: Existing solutions are typically better tested, maintained, and documented than custom code. This reduces bugs, maintenance burden, and development time while increasing reliability. Context7 MCP ensures we find the most current and recommended approaches. ### VII. Diagram Standards All diagrams and visual representations MUST follow standardized formats: - **Mermaid Required**: All flowcharts, diagrams, and graphs MUST be created using Mermaid syntax in Markdown. Plain text ASCII diagrams are prohibited. - **Accessibility**: Mermaid diagrams MUST include proper labels and descriptions for screen readers and accessibility tools. - **Consistency**: Diagram styling and notation MUST be consistent across all documentation. - **Version Control**: Diagrams MUST be stored as text in Markdown files, not as binary images. - **Maintenance**: Diagrams MUST be updated whenever the represented systems or processes change. **Rationale**: Mermaid provides standardized, accessible, and maintainable diagrams that render consistently across platforms. Text-based diagrams enable proper version control and collaboration compared to binary images. ## Development Standards ### Code Review Requirements All code changes MUST undergo peer review before merging: - At least one approval from a team member required - All automated checks (tests, linting, security scans) MUST pass - Review MUST verify compliance with all constitution principles - No self-merging permitted except for automated dependency updates ### Branch Strategy - Feature branches MUST follow naming convention: `###-feature-name` - Main branch MUST always be in deployable state - No direct commits to main branch - All features MUST go through PR process ### Commit Standards - Commits MUST use conventional commit format: `type(scope): description` - Commit messages MUST be clear and descriptive - Each commit SHOULD represent a logical unit of work ## Quality Gates Before a feature can be considered complete, it MUST pass all quality gates: ### Pre-Merge Gates - [ ] All tests pass (unit, integration, contract) - [ ] Code coverage meets minimum 80% threshold - [ ] Biome checks pass (no linting errors or formatting issues) - [ ] No security vulnerabilities detected - [ ] Documentation updated (API docs, user docs, ADRs if applicable) - [ ] Code review approved by at least one team member - [ ] Constitution compliance verified - [ ] Existing solutions evaluated (if new functionality added) ### Pre-Release Gates - [ ] All pre-merge gates passed - [ ] End-to-end tests pass in staging environment - [ ] Performance benchmarks meet targets - [ ] Accessibility audit passed - [ ] Security penetration testing completed (for security-sensitive features) - [ ] User acceptance testing completed - [ ] Rollback plan documented ## Governance ### Authority This constitution supersedes all other development practices and guidelines. In case of conflict, constitution principles take precedence. ### Amendment Process Amendments to this constitution require: 1. Proposal with clear rationale and impact analysis 2. Discussion period of at least 1 week 3. Consensus among core team members 4. Documentation of version change following semantic versioning 5. Update of all dependent templates and documentation 6. Communication to all team members ### Version Semantics - **MAJOR**: Breaking changes to principles, removal of principles, fundamental governance changes - **MINOR**: New principles added, significant expansions to existing principles - **PATCH**: Clarifications, wording improvements, non-semantic changes ### Compliance - All PRs MUST verify compliance with constitution principles - Constitution violations MUST be justified in writing or the PR rejected - Repeated violations may result in PR privileges being revoked - Team retrospectives MUST include constitution effectiveness review ### Enforcement - Automated tools MUST enforce standards where possible (Biome for linting/formatting, testing frameworks) - Code review MUST include constitution compliance check - Complexity that violates principles MUST be justified or refactored - Justified exceptions MUST be documented in code and tracked in Complexity Tracking section of plan.md - Custom implementations MUST include justification for not using existing solutions ### Evolution - Constitution MUST be reviewed quarterly for effectiveness - Metrics on development velocity, quality, and team satisfaction MUST inform amendments - Team feedback MUST be solicited regularly and incorporated into amendments **Version**: 1.2.0 | **Ratified**: 2025-10-12 | **Last Amended**: 2025-10-12