# 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`](.specify/memory/constitution.md)

## Development Environment

This project uses Nix for reproducible development environments:

```bash
# 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

```bash
# 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](.specify/memory/constitution.md)
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]