Initialize project structure with foundational files including .gitignore, README, and specification templates. Establish project constitution outlining core principles for code quality, testing, user experience, and performance. Add initial feature specification for Reference Board Viewer application.

2025-11-01 21:49:14 -06:00
parent 75492c3b61
commit 43bd1aebf0
15 changed files with 1718 additions and 436 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,122 @@
+# 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]
+