webref

A Python project for web reference management, built with quality and maintainability as core values.

Project Constitution

This project follows a formal constitution that establishes binding principles for all development work. The constitution ensures consistent quality, testing discipline, user experience, and performance across the codebase.

Constitutional Principles:

1. Code Quality & Maintainability - Clear, consistent, maintainable code with proper typing and documentation
2. Testing Discipline - ≥80% coverage, automated testing for all functionality
3. User Experience Consistency - Intuitive, accessible, consistent interfaces
4. Performance & Efficiency - Performance-first design with bounded resources

📖 Full constitution: .specify/memory/constitution.md

Development Environment

This project uses Nix for reproducible development environments:

# Enter development shell
nix-shell

# Or use direnv for automatic activation
echo "use nix" > .envrc
direnv allow

Included tools:

• Python 3 with setuptools
• uv (fast Python package manager)

Project Structure

webref/
├── .specify/                   # Project governance and templates
│   ├── memory/
│   │   └── constitution.md     # Project constitution
│   └── templates/
│       ├── plan-template.md    # Planning document template
│       ├── spec-template.md    # Specification template
│       ├── tasks-template.md   # Task tracking template
│       └── commands/
│           └── constitution.md # Constitution amendment workflow
├── shell.nix                   # Nix development environment
└── README.md                   # This file

Using the Specification System

Planning a Feature

1. Copy .specify/templates/plan-template.md to .specify/plans/[feature-name].md
2. Fill in objectives, scope, and technical approach
3. Complete the Constitution Alignment Check to verify adherence to principles
4. Review with team before proceeding to specification

Writing a Specification

1. Copy .specify/templates/spec-template.md to .specify/specs/[feature-name].md
2. Define functional and non-functional requirements
3. Each requirement must address constitutional alignment (testing, UX, performance)
4. Include clear acceptance criteria for validation

Managing Tasks

1. Copy .specify/templates/tasks-template.md to .specify/tasks/[sprint-name].md
2. Organize tasks by constitutional principle category:
   • 🏗️ Implementation (Code Quality)
   • 🧪 Testing (Testing Discipline)
   • 👤 User Experience (UX Consistency)
   • ⚡ Performance (Performance & Efficiency)
3. Complete the checklist before closing any task

Amending the Constitution

1. Create a pull request to .specify/memory/constitution.md
2. Include rationale and impact analysis
3. Update version number (MAJOR.MINOR.PATCH)
4. Update all dependent templates
5. Prepend Sync Impact Report

Code Quality Standards

All code must meet these requirements before merge:

• ✅ Linter passing (no errors/warnings)
• ✅ Type hints on all public APIs
• ✅ Tests passing with ≥80% coverage
• ✅ Code review approved
• ✅ Constitution principles verified

Testing

# Run tests
pytest

# With coverage report
pytest --cov=webref --cov-report=html

# Coverage must be ≥80% per Constitutional Principle 2

Contributing

1. Read the constitution
2. Follow the planning → specification → implementation flow
3. Ensure all code meets constitutional principles
4. Write tests first (TDD encouraged)
5. Request code review

License

[License information to be added]

Contact

[Contact information to be added]