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.
This commit is contained in:
Danilo Reyes
58
.gitignore
vendored
Normal file
58
.gitignore
vendored
Normal file
@@ -0,0 +1,58 @@
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
*.so
|
||||
.Python
|
||||
build/
|
||||
develop-eggs/
|
||||
dist/
|
||||
downloads/
|
||||
eggs/
|
||||
.eggs/
|
||||
lib/
|
||||
lib64/
|
||||
parts/
|
||||
sdist/
|
||||
var/
|
||||
wheels/
|
||||
*.egg-info/
|
||||
.installed.cfg
|
||||
*.egg
|
||||
MANIFEST
|
||||
.pytest_cache/
|
||||
.coverage
|
||||
htmlcov/
|
||||
.tox/
|
||||
.hypothesis/
|
||||
|
||||
# Virtual environments
|
||||
venv/
|
||||
ENV/
|
||||
env/
|
||||
.venv
|
||||
|
||||
# IDEs
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
.DS_Store
|
||||
|
||||
# Nix
|
||||
result
|
||||
result-*
|
||||
|
||||
# Project specific
|
||||
.specify/plans/*
|
||||
.specify/specs/*
|
||||
.specify/tasks/*
|
||||
!.specify/plans/.gitkeep
|
||||
!.specify/specs/.gitkeep
|
||||
!.specify/tasks/.gitkeep
|
||||
|
||||
# Keep template and memory directories
|
||||
!.specify/templates/
|
||||
!.specify/memory/
|
||||
|
||||
105
.specify/README.md
Normal file
105
.specify/README.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# .specify Directory
|
||||
|
||||
This directory contains the project's governance framework and specification templates.
|
||||
|
||||
## Purpose
|
||||
|
||||
The `.specify` system provides:
|
||||
- **Constitutional Principles:** Binding rules for all development work
|
||||
- **Template Library:** Standardized formats for plans, specs, and tasks
|
||||
- **Consistency Enforcement:** Automated checks that code adheres to principles
|
||||
- **Living Documentation:** Evolving guidance that grows with the project
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
.specify/
|
||||
├── memory/
|
||||
│ └── constitution.md # Project constitution (versioned)
|
||||
├── templates/
|
||||
│ ├── plan-template.md # Feature planning template
|
||||
│ ├── spec-template.md # Technical specification template
|
||||
│ ├── tasks-template.md # Task tracking template
|
||||
│ └── commands/
|
||||
│ └── constitution.md # Constitution amendment workflow
|
||||
├── plans/ # (Create as needed) Feature plans
|
||||
├── specs/ # (Create as needed) Specifications
|
||||
└── tasks/ # (Create as needed) Task lists
|
||||
```
|
||||
|
||||
## Key Files
|
||||
|
||||
### constitution.md
|
||||
The project's binding principles covering:
|
||||
- Code quality and maintainability
|
||||
- Testing discipline (≥80% coverage)
|
||||
- User experience consistency
|
||||
- Performance and efficiency
|
||||
|
||||
**Version:** 1.0.0 (ratified 2025-11-02)
|
||||
|
||||
Every code change must align with constitutional principles. The constitution can be amended via pull request with proper versioning and impact analysis.
|
||||
|
||||
### Templates
|
||||
|
||||
#### plan-template.md
|
||||
Use for high-level feature planning. Includes:
|
||||
- Objectives and scope definition
|
||||
- Constitution alignment checklist
|
||||
- Technical approach and architecture
|
||||
- Implementation phases
|
||||
- Risk assessment
|
||||
|
||||
#### spec-template.md
|
||||
Use for detailed technical specifications. Includes:
|
||||
- Functional and non-functional requirements
|
||||
- Design and data models
|
||||
- API specifications with types
|
||||
- Testing strategy
|
||||
- Performance analysis
|
||||
|
||||
#### tasks-template.md
|
||||
Use for sprint/milestone task tracking. Includes:
|
||||
- Tasks categorized by constitutional principle
|
||||
- Estimation guidelines (S/M/L/XL)
|
||||
- Completion checklist
|
||||
- Blocked task tracking
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Plan** → Create plan from template, verify constitutional alignment
|
||||
2. **Specify** → Write detailed spec with testable requirements
|
||||
3. **Implement** → Break down into tasks, execute with continuous testing
|
||||
4. **Review** → Code review validates principle adherence
|
||||
5. **Deploy** → Merge and monitor success metrics
|
||||
|
||||
## Constitutional Compliance
|
||||
|
||||
Every plan, spec, and task must explicitly address:
|
||||
|
||||
✅ **Code Quality:** How will this maintain/improve maintainability?
|
||||
✅ **Testing:** What tests ensure correctness? (≥80% coverage)
|
||||
✅ **User Experience:** How does this impact users positively?
|
||||
✅ **Performance:** What are the performance implications?
|
||||
|
||||
## Amending the System
|
||||
|
||||
### To amend the constitution:
|
||||
1. PR to `constitution.md` with rationale
|
||||
2. Increment version (MAJOR.MINOR.PATCH)
|
||||
3. Update dependent templates
|
||||
4. Add Sync Impact Report
|
||||
|
||||
### To improve templates:
|
||||
1. PR to template file with changes
|
||||
2. Explain benefit and backward compatibility
|
||||
3. Update examples if structure changes
|
||||
|
||||
## Version History
|
||||
|
||||
- **1.0.0 (2025-11-02):** Initial specification system established with four core principles
|
||||
|
||||
## Questions?
|
||||
|
||||
Refer to the [main README](../README.md) or the constitution itself for detailed guidance.
|
||||
|
||||
@@ -1,50 +1,147 @@
|
||||
# [PROJECT_NAME] Constitution
|
||||
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
|
||||
<!--
|
||||
Sync Impact Report - Version 1.0.0 (2025-11-02)
|
||||
═══════════════════════════════════════════════════════════════
|
||||
|
||||
VERSION CHANGE: Initial constitution establishment (v1.0.0)
|
||||
|
||||
MODIFIED PRINCIPLES: N/A (Initial creation)
|
||||
|
||||
ADDED SECTIONS:
|
||||
✓ Principle 1: Code Quality & Maintainability
|
||||
✓ Principle 2: Testing Discipline
|
||||
✓ Principle 3: User Experience Consistency
|
||||
✓ Principle 4: Performance & Efficiency
|
||||
✓ Governance & Amendment Process
|
||||
|
||||
REMOVED SECTIONS: N/A
|
||||
|
||||
TEMPLATE SYNC STATUS:
|
||||
✅ .specify/templates/plan-template.md - Created with constitution alignment
|
||||
✅ .specify/templates/spec-template.md - Created with principle checks
|
||||
✅ .specify/templates/tasks-template.md - Created with principle-driven categories
|
||||
✅ .specify/templates/commands/constitution.md - Created with amendment workflow
|
||||
|
||||
DEFERRED ITEMS: None
|
||||
|
||||
RATIONALE: Initial constitution establishing foundational principles for code quality,
|
||||
testing standards, user experience, and performance requirements for the webref project.
|
||||
═══════════════════════════════════════════════════════════════
|
||||
-->
|
||||
|
||||
# Project Constitution
|
||||
|
||||
**Project Name:** webref
|
||||
**Constitution Version:** 1.0.0
|
||||
**Ratification Date:** 2025-11-02
|
||||
**Last Amended:** 2025-11-02
|
||||
|
||||
## Preamble
|
||||
|
||||
This constitution establishes the foundational principles and governance framework for the webref project. These principles are binding on all development work, architectural decisions, and contributions. They exist to ensure consistent quality, maintainability, user satisfaction, and technical excellence across the project lifecycle.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### [PRINCIPLE_1_NAME]
|
||||
<!-- Example: I. Library-First -->
|
||||
[PRINCIPLE_1_DESCRIPTION]
|
||||
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
|
||||
### Principle 1: Code Quality & Maintainability
|
||||
|
||||
### [PRINCIPLE_2_NAME]
|
||||
<!-- Example: II. CLI Interface -->
|
||||
[PRINCIPLE_2_DESCRIPTION]
|
||||
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
|
||||
**Declaration:** All code MUST be written with clarity, consistency, and long-term maintainability as primary concerns.
|
||||
|
||||
### [PRINCIPLE_3_NAME]
|
||||
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
|
||||
[PRINCIPLE_3_DESCRIPTION]
|
||||
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
|
||||
**Requirements:**
|
||||
- Code MUST follow established style guides and formatting conventions (enforced via linters)
|
||||
- Functions and modules MUST have clear, single responsibilities (SRP)
|
||||
- Complex logic MUST be accompanied by inline comments explaining the "why"
|
||||
- Magic numbers and hard-coded values MUST be replaced with named constants
|
||||
- Code duplication beyond trivial patterns (>5 lines) MUST be refactored into reusable components
|
||||
- Type hints MUST be used for all public APIs and function signatures in Python
|
||||
- Dependencies MUST be explicitly versioned and regularly audited for security and compatibility
|
||||
|
||||
### [PRINCIPLE_4_NAME]
|
||||
<!-- Example: IV. Integration Testing -->
|
||||
[PRINCIPLE_4_DESCRIPTION]
|
||||
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
|
||||
**Rationale:** Code is read far more often than written. Maintainable code reduces cognitive load, accelerates feature development, simplifies debugging, and enables confident refactoring. Poor code quality compounds into technical debt that eventually paralyzes development velocity.
|
||||
|
||||
### [PRINCIPLE_5_NAME]
|
||||
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
|
||||
[PRINCIPLE_5_DESCRIPTION]
|
||||
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
|
||||
**Enforcement:** Pre-commit hooks, CI linting checks, code review requirements.
|
||||
|
||||
## [SECTION_2_NAME]
|
||||
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
|
||||
### Principle 2: Testing Discipline
|
||||
|
||||
[SECTION_2_CONTENT]
|
||||
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
|
||||
**Declaration:** All functionality MUST be validated through automated tests before merging to main branches.
|
||||
|
||||
## [SECTION_3_NAME]
|
||||
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
|
||||
**Requirements:**
|
||||
- Unit tests MUST cover all public functions and methods (minimum 80% coverage)
|
||||
- Integration tests MUST verify interactions between components and external dependencies
|
||||
- Edge cases and error paths MUST have explicit test coverage
|
||||
- Tests MUST be deterministic, isolated, and fast (unit tests <1s, integration <10s)
|
||||
- Test failures MUST block merges via CI/CD pipelines
|
||||
- Critical user flows MUST have end-to-end tests when applicable
|
||||
- Regression tests MUST be added for every bug fix
|
||||
- Test code MUST maintain the same quality standards as production code
|
||||
|
||||
[SECTION_3_CONTENT]
|
||||
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
|
||||
**Rationale:** Automated testing is the only scalable way to ensure correctness, prevent regressions, and enable confident refactoring. Manual testing alone is insufficient for maintaining quality as complexity grows. Tests serve as living documentation of expected behavior.
|
||||
|
||||
## Governance
|
||||
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
|
||||
**Enforcement:** CI/CD pipeline gates, coverage reporting, code review checklists.
|
||||
|
||||
[GOVERNANCE_RULES]
|
||||
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
|
||||
### Principle 3: User Experience Consistency
|
||||
|
||||
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
|
||||
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
|
||||
**Declaration:** User-facing interfaces MUST provide consistent, intuitive, and accessible experiences across all touchpoints.
|
||||
|
||||
**Requirements:**
|
||||
- UI components MUST follow established design systems and patterns
|
||||
- Error messages MUST be clear, actionable, and user-friendly (no raw exceptions)
|
||||
- User workflows MUST be tested for common use cases before release
|
||||
- Response times for user-initiated actions MUST be <200ms or provide feedback
|
||||
- Accessibility standards (WCAG 2.1 AA minimum) MUST be met for all interfaces
|
||||
- API responses MUST follow consistent schemas and error formats
|
||||
- Documentation MUST be written for users, not developers (unless internal APIs)
|
||||
- Breaking changes to user-facing features MUST include migration paths
|
||||
|
||||
**Rationale:** Inconsistent experiences create friction, confusion, and frustration. Users develop mental models based on patterns; violations of these patterns increase cognitive load and reduce trust. Quality user experience is a competitive differentiator and retention driver.
|
||||
|
||||
**Enforcement:** Design review, usability testing, accessibility audits, API contract testing.
|
||||
|
||||
### Principle 4: Performance & Efficiency
|
||||
|
||||
**Declaration:** All systems MUST be designed and implemented with performance as a first-class concern, not an afterthought.
|
||||
|
||||
**Requirements:**
|
||||
- Performance budgets MUST be established for critical operations (API response time, page load, query execution)
|
||||
- Algorithmic complexity MUST be considered and optimized for expected data scales (prefer O(n log n) over O(n²) for large datasets)
|
||||
- Database queries MUST be indexed appropriately and avoid N+1 problems
|
||||
- Memory usage MUST be bounded and monitored (no unbounded caches or collection growth)
|
||||
- Network requests MUST be batched, cached, or minimized where possible
|
||||
- Performance regressions >10% MUST be investigated and justified before merge
|
||||
- Profiling MUST be performed for suspected bottlenecks before optimization
|
||||
- Resource-intensive operations MUST be logged and monitored in production
|
||||
|
||||
**Rationale:** Performance directly impacts user satisfaction, operational costs, and system scalability. Poor performance compounds exponentially with scale. Retrofitting performance is far more expensive than designing for it upfront. Users abandon slow systems.
|
||||
|
||||
**Enforcement:** Performance benchmarks in CI, profiling tools, load testing, production monitoring.
|
||||
|
||||
## Governance & Amendment Process
|
||||
|
||||
### Amendment Procedure
|
||||
|
||||
1. Amendments MUST be proposed via pull request to `.specify/memory/constitution.md`
|
||||
2. Proposals MUST include rationale and impact analysis on existing code/templates
|
||||
3. Amendments require explicit approval from project maintainers
|
||||
4. Version number MUST be incremented following semantic versioning:
|
||||
- **MAJOR:** Backward-incompatible principle changes (removal, fundamental redefinition)
|
||||
- **MINOR:** New principles, sections, or material expansions to existing guidance
|
||||
- **PATCH:** Clarifications, wording improvements, non-semantic refinements
|
||||
5. All dependent templates MUST be updated before amendment merge
|
||||
6. A Sync Impact Report MUST be prepended to the constitution file
|
||||
|
||||
### Compliance Review
|
||||
|
||||
- Code reviews MUST verify compliance with constitutional principles
|
||||
- CI/CD pipelines MUST enforce automated compliance checks where possible
|
||||
- Quarterly audits SHOULD assess adherence and identify systematic violations
|
||||
- Principle violations MUST be documented and justified if accepted as technical debt
|
||||
|
||||
### Living Document Commitment
|
||||
|
||||
This constitution is a living document. As the project evolves, principles may need refinement to reflect new challenges, technologies, or organizational priorities. However, the core commitment to quality, testing, user experience, and performance remains immutable.
|
||||
|
||||
## Ratified By
|
||||
|
||||
Project maintainers of webref on 2025-11-02.
|
||||
|
||||
---
|
||||
|
||||
*Version History:*
|
||||
- **v1.0.0 (2025-11-02):** Initial constitution ratified with four foundational principles
|
||||
|
||||
0
.specify/plans/.gitkeep
Normal file
0
.specify/plans/.gitkeep
Normal file
0
.specify/specs/.gitkeep
Normal file
0
.specify/specs/.gitkeep
Normal file
0
.specify/tasks/.gitkeep
Normal file
0
.specify/tasks/.gitkeep
Normal file
@@ -2,6 +2,17 @@
|
||||
|
||||
Auto-generated from all feature plans. Last updated: [DATE]
|
||||
|
||||
## Constitutional Principles
|
||||
|
||||
This project follows a formal constitution (`.specify/memory/constitution.md`). All development work MUST align with these principles:
|
||||
|
||||
1. **Code Quality & Maintainability** - Clear, maintainable code with proper typing
|
||||
2. **Testing Discipline** - ≥80% coverage, automated testing required
|
||||
3. **User Experience Consistency** - Intuitive, accessible interfaces
|
||||
4. **Performance & Efficiency** - Performance-first design with bounded resources
|
||||
|
||||
Reference the full constitution for detailed requirements and enforcement mechanisms.
|
||||
|
||||
## Active Technologies
|
||||
|
||||
[EXTRACTED FROM ALL PLAN.MD FILES]
|
||||
@@ -20,6 +31,24 @@ Auto-generated from all feature plans. Last updated: [DATE]
|
||||
|
||||
[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
|
||||
|
||||
### Constitutional Requirements
|
||||
|
||||
All code MUST meet these standards (per Principle 1):
|
||||
- Linter passing (zero errors/warnings)
|
||||
- Type hints on all public APIs
|
||||
- Clear single responsibilities (SRP)
|
||||
- Explicit constants (no magic numbers)
|
||||
- Comments explaining "why" not "what"
|
||||
|
||||
## Testing Standards
|
||||
|
||||
Per Constitutional Principle 2:
|
||||
- Minimum 80% test coverage required
|
||||
- Unit tests for all public functions
|
||||
- Integration tests for component interactions
|
||||
- Edge cases and error paths explicitly tested
|
||||
- Tests are deterministic, isolated, and fast (<1s unit, <10s integration)
|
||||
|
||||
## Recent Changes
|
||||
|
||||
[LAST 3 FEATURES AND WHAT THEY ADDED]
|
||||
|
||||
@@ -20,6 +20,15 @@
|
||||
============================================================================
|
||||
-->
|
||||
|
||||
## Constitutional Compliance Check
|
||||
|
||||
Before proceeding, verify alignment with constitutional principles:
|
||||
|
||||
- [ ] **Code Quality (Principle 1):** Design maintains/improves maintainability
|
||||
- [ ] **Testing (Principle 2):** ≥80% coverage plan established
|
||||
- [ ] **UX Consistency (Principle 3):** User impact documented and positive
|
||||
- [ ] **Performance (Principle 4):** Performance budget and complexity analyzed
|
||||
|
||||
## [Category 1]
|
||||
|
||||
- [ ] CHK001 First checklist item with clear action
|
||||
@@ -32,6 +41,16 @@
|
||||
- [ ] CHK005 Item with specific criteria
|
||||
- [ ] CHK006 Final item in this category
|
||||
|
||||
## Pre-Merge Validation
|
||||
|
||||
Per constitutional requirements:
|
||||
|
||||
- [ ] All tests passing (≥80% coverage maintained)
|
||||
- [ ] Linter/type checker passing (zero errors)
|
||||
- [ ] Code review approved with principle verification
|
||||
- [ ] Documentation updated
|
||||
- [ ] Performance benchmarks met (if applicable)
|
||||
|
||||
## Notes
|
||||
|
||||
- Check items off as completed: `[x]`
|
||||
|
||||
81
.specify/templates/commands/constitution.md
Normal file
81
.specify/templates/commands/constitution.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync
|
||||
---
|
||||
|
||||
## User Input
|
||||
|
||||
```text
|
||||
[User's request for constitutional changes]
|
||||
```
|
||||
|
||||
You **MUST** consider the user input before proceeding (if not empty).
|
||||
|
||||
## Outline
|
||||
|
||||
You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
|
||||
|
||||
Follow this execution flow:
|
||||
|
||||
1. Load the existing constitution template at `.specify/memory/constitution.md`.
|
||||
- Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
|
||||
**IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
|
||||
|
||||
2. Collect/derive values for placeholders:
|
||||
- If user input (conversation) supplies a value, use it.
|
||||
- Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
|
||||
- For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
|
||||
- `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
|
||||
- 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.
|
||||
- If version bump type ambiguous, propose reasoning before finalizing.
|
||||
|
||||
3. Draft the updated constitution content:
|
||||
- Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
|
||||
- Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
|
||||
- Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
|
||||
- Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
|
||||
|
||||
4. Consistency propagation checklist (convert prior checklist into active validations):
|
||||
- Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
|
||||
- Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
|
||||
- Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
|
||||
- Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
|
||||
- Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
|
||||
|
||||
5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
|
||||
- Version change: old → new
|
||||
- List of modified principles (old title → new title if renamed)
|
||||
- Added sections
|
||||
- Removed sections
|
||||
- Templates requiring updates (✅ updated / ⚠ pending) with file paths
|
||||
- Follow-up TODOs if any placeholders intentionally deferred.
|
||||
|
||||
6. Validation before final output:
|
||||
- No remaining unexplained bracket tokens.
|
||||
- Version line matches report.
|
||||
- Dates ISO format YYYY-MM-DD.
|
||||
- Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
|
||||
|
||||
7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
|
||||
|
||||
8. Output a final summary to the user with:
|
||||
- New version and bump rationale.
|
||||
- Any files flagged for manual follow-up.
|
||||
- Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
|
||||
|
||||
Formatting & Style Requirements:
|
||||
|
||||
- Use Markdown headings exactly as in the template (do not demote/promote levels).
|
||||
- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
|
||||
- Keep a single blank line between sections.
|
||||
- Avoid trailing whitespace.
|
||||
|
||||
If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
|
||||
|
||||
If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
|
||||
|
||||
Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.
|
||||
|
||||
--- End Command ---
|
||||
|
||||
@@ -1,104 +1,97 @@
|
||||
# Implementation Plan: [FEATURE]
|
||||
# Plan: [FEATURE_NAME]
|
||||
|
||||
**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
|
||||
**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
|
||||
**Created:** [YYYY-MM-DD]
|
||||
**Status:** [Draft | Active | Completed | Obsolete]
|
||||
**Owner:** [OWNER_NAME]
|
||||
|
||||
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
|
||||
## Overview
|
||||
|
||||
## Summary
|
||||
Brief description of what this plan aims to achieve and why it's important.
|
||||
|
||||
[Extract from feature spec: primary requirement + technical approach from research]
|
||||
## Objectives
|
||||
|
||||
## Technical Context
|
||||
- [ ] Primary objective 1
|
||||
- [ ] Primary objective 2
|
||||
- [ ] Primary objective 3
|
||||
|
||||
<!--
|
||||
ACTION REQUIRED: Replace the content in this section with the technical details
|
||||
for the project. The structure here is presented in advisory capacity to guide
|
||||
the iteration process.
|
||||
-->
|
||||
## Constitution Alignment Check
|
||||
|
||||
**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
|
||||
**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]
|
||||
**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
|
||||
**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]
|
||||
**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
|
||||
**Project Type**: [single/web/mobile - determines source structure]
|
||||
**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]
|
||||
**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
|
||||
**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
|
||||
Before proceeding, verify alignment with constitutional principles:
|
||||
|
||||
## Constitution Check
|
||||
- **Code Quality & Maintainability:** How will this maintain/improve code quality?
|
||||
- [ ] Design follows single responsibility principle
|
||||
- [ ] Clear module boundaries defined
|
||||
- [ ] Dependencies justified and documented
|
||||
|
||||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||||
- **Testing Discipline:** What testing strategy will ensure correctness?
|
||||
- [ ] Unit test coverage plan (≥80%)
|
||||
- [ ] Integration test scenarios identified
|
||||
- [ ] Edge cases documented
|
||||
|
||||
[Gates determined based on constitution file]
|
||||
- **User Experience Consistency:** How does this impact users?
|
||||
- [ ] UI/API changes follow existing patterns
|
||||
- [ ] Error handling is user-friendly
|
||||
- [ ] Documentation plan complete
|
||||
|
||||
## Project Structure
|
||||
- **Performance & Efficiency:** What are the performance implications?
|
||||
- [ ] Performance budget established
|
||||
- [ ] Algorithmic complexity analyzed
|
||||
- [ ] Resource usage estimated
|
||||
|
||||
### Documentation (this feature)
|
||||
## Scope
|
||||
|
||||
```text
|
||||
specs/[###-feature]/
|
||||
├── plan.md # This file (/speckit.plan command output)
|
||||
├── research.md # Phase 0 output (/speckit.plan command)
|
||||
├── data-model.md # Phase 1 output (/speckit.plan command)
|
||||
├── quickstart.md # Phase 1 output (/speckit.plan command)
|
||||
├── contracts/ # Phase 1 output (/speckit.plan command)
|
||||
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
|
||||
```
|
||||
### In Scope
|
||||
- What will be built/changed
|
||||
- Explicit boundaries
|
||||
|
||||
### Source Code (repository root)
|
||||
<!--
|
||||
ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
|
||||
for this feature. Delete unused options and expand the chosen structure with
|
||||
real paths (e.g., apps/admin, packages/something). The delivered plan must
|
||||
not include Option labels.
|
||||
-->
|
||||
### Out of Scope
|
||||
- What will NOT be addressed
|
||||
- Deferred items for future work
|
||||
|
||||
```text
|
||||
# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
|
||||
src/
|
||||
├── models/
|
||||
├── services/
|
||||
├── cli/
|
||||
└── lib/
|
||||
## Technical Approach
|
||||
|
||||
tests/
|
||||
├── contract/
|
||||
├── integration/
|
||||
└── unit/
|
||||
High-level technical strategy and architectural decisions.
|
||||
|
||||
# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
|
||||
backend/
|
||||
├── src/
|
||||
│ ├── models/
|
||||
│ ├── services/
|
||||
│ └── api/
|
||||
└── tests/
|
||||
### Key Components
|
||||
1. Component A: Purpose and responsibilities
|
||||
2. Component B: Purpose and responsibilities
|
||||
3. Component C: Purpose and responsibilities
|
||||
|
||||
frontend/
|
||||
├── src/
|
||||
│ ├── components/
|
||||
│ ├── pages/
|
||||
│ └── services/
|
||||
└── tests/
|
||||
### Dependencies
|
||||
- Internal dependencies (other modules/services)
|
||||
- External dependencies (libraries, APIs, services)
|
||||
|
||||
# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
|
||||
api/
|
||||
└── [same as backend above]
|
||||
### Risks & Mitigations
|
||||
| Risk | Impact | Probability | Mitigation Strategy |
|
||||
|------|--------|-------------|---------------------|
|
||||
| Risk 1 | High/Med/Low | High/Med/Low | How we'll address it |
|
||||
|
||||
ios/ or android/
|
||||
└── [platform-specific structure: feature modules, UI flows, platform tests]
|
||||
```
|
||||
## Implementation Phases
|
||||
|
||||
**Structure Decision**: [Document the selected structure and reference the real
|
||||
directories captured above]
|
||||
### Phase 1: [Name] (Est: X days)
|
||||
- Milestone 1
|
||||
- Milestone 2
|
||||
|
||||
## Complexity Tracking
|
||||
### Phase 2: [Name] (Est: X days)
|
||||
- Milestone 3
|
||||
- Milestone 4
|
||||
|
||||
> **Fill ONLY if Constitution Check has violations that must be justified**
|
||||
## Success Criteria
|
||||
|
||||
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
||||
|-----------|------------|-------------------------------------|
|
||||
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
|
||||
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
|
||||
Clear, measurable criteria for completion:
|
||||
- [ ] All tests passing with ≥80% coverage
|
||||
- [ ] Performance benchmarks met
|
||||
- [ ] Documentation complete
|
||||
- [ ] Code review approved
|
||||
- [ ] Production deployment successful
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Question 1 that needs resolution
|
||||
- [ ] Question 2 that needs research
|
||||
|
||||
## References
|
||||
|
||||
- Link to specs
|
||||
- Related plans
|
||||
- External documentation
|
||||
|
||||
@@ -1,115 +1,181 @@
|
||||
# Feature Specification: [FEATURE NAME]
|
||||
# Specification: [FEATURE_NAME]
|
||||
|
||||
**Feature Branch**: `[###-feature-name]`
|
||||
**Created**: [DATE]
|
||||
**Status**: Draft
|
||||
**Input**: User description: "$ARGUMENTS"
|
||||
**Version:** [X.Y.Z]
|
||||
**Created:** [YYYY-MM-DD]
|
||||
**Last Updated:** [YYYY-MM-DD]
|
||||
**Status:** [Draft | Review | Approved | Implemented]
|
||||
**Owner:** [OWNER_NAME]
|
||||
|
||||
## User Scenarios & Testing *(mandatory)*
|
||||
## Purpose
|
||||
|
||||
<!--
|
||||
IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
|
||||
Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
|
||||
you should still have a viable MVP (Minimum Viable Product) that delivers value.
|
||||
Clear statement of what this specification defines and its business/technical value.
|
||||
|
||||
Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
|
||||
Think of each story as a standalone slice of functionality that can be:
|
||||
- Developed independently
|
||||
- Tested independently
|
||||
- Deployed independently
|
||||
- Demonstrated to users independently
|
||||
-->
|
||||
|
||||
### User Story 1 - [Brief Title] (Priority: P1)
|
||||
|
||||
[Describe this user journey in plain language]
|
||||
|
||||
**Why this priority**: [Explain the value and why it has this priority level]
|
||||
|
||||
**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
||||
2. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
||||
|
||||
---
|
||||
|
||||
### User Story 2 - [Brief Title] (Priority: P2)
|
||||
|
||||
[Describe this user journey in plain language]
|
||||
|
||||
**Why this priority**: [Explain the value and why it has this priority level]
|
||||
|
||||
**Independent Test**: [Describe how this can be tested independently]
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
||||
|
||||
---
|
||||
|
||||
### User Story 3 - [Brief Title] (Priority: P3)
|
||||
|
||||
[Describe this user journey in plain language]
|
||||
|
||||
**Why this priority**: [Explain the value and why it has this priority level]
|
||||
|
||||
**Independent Test**: [Describe how this can be tested independently]
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
||||
|
||||
---
|
||||
|
||||
[Add more user stories as needed, each with an assigned priority]
|
||||
|
||||
### Edge Cases
|
||||
|
||||
<!--
|
||||
ACTION REQUIRED: The content in this section represents placeholders.
|
||||
Fill them out with the right edge cases.
|
||||
-->
|
||||
|
||||
- What happens when [boundary condition]?
|
||||
- How does system handle [error scenario]?
|
||||
|
||||
## Requirements *(mandatory)*
|
||||
|
||||
<!--
|
||||
ACTION REQUIRED: The content in this section represents placeholders.
|
||||
Fill them out with the right functional requirements.
|
||||
-->
|
||||
## Requirements
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
|
||||
- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
|
||||
- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
|
||||
- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
|
||||
- **FR-005**: System MUST [behavior, e.g., "log all security events"]
|
||||
#### FR1: [Requirement Name]
|
||||
**Priority:** [Critical | High | Medium | Low]
|
||||
**Description:** Detailed description of the requirement.
|
||||
|
||||
*Example of marking unclear requirements:*
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Criterion 1 (testable condition)
|
||||
- [ ] Criterion 2 (testable condition)
|
||||
- [ ] Criterion 3 (testable condition)
|
||||
|
||||
- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
|
||||
- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
|
||||
**Constitutional Alignment:**
|
||||
- Testing: [How this will be tested per Principle 2]
|
||||
- UX Impact: [User-facing implications per Principle 3]
|
||||
- Performance: [Performance considerations per Principle 4]
|
||||
|
||||
### Key Entities *(include if feature involves data)*
|
||||
#### FR2: [Requirement Name]
|
||||
[Repeat structure above]
|
||||
|
||||
- **[Entity 1]**: [What it represents, key attributes without implementation]
|
||||
- **[Entity 2]**: [What it represents, relationships to other entities]
|
||||
### Non-Functional Requirements
|
||||
|
||||
## Success Criteria *(mandatory)*
|
||||
#### NFR1: Performance
|
||||
Per Constitutional Principle 4:
|
||||
- Response time: [target, e.g., <200ms for p95]
|
||||
- Throughput: [target, e.g., >1000 req/s]
|
||||
- Resource limits: [memory/CPU bounds]
|
||||
- Scalability: [expected load ranges]
|
||||
|
||||
<!--
|
||||
ACTION REQUIRED: Define measurable success criteria.
|
||||
These must be technology-agnostic and measurable.
|
||||
-->
|
||||
#### NFR2: Quality
|
||||
Per Constitutional Principle 1:
|
||||
- Code coverage: ≥80% (Principle 2 requirement)
|
||||
- Linting: Zero errors/warnings
|
||||
- Type safety: Full type hints on public APIs
|
||||
- Documentation: All public APIs documented
|
||||
|
||||
### Measurable Outcomes
|
||||
#### NFR3: User Experience
|
||||
Per Constitutional Principle 3:
|
||||
- Accessibility: WCAG 2.1 AA compliance
|
||||
- Error handling: User-friendly messages
|
||||
- Consistency: Follows existing design patterns
|
||||
- Response feedback: <200ms or progress indicators
|
||||
|
||||
- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
|
||||
- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
|
||||
- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
|
||||
- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
|
||||
#### NFR4: Maintainability
|
||||
Per Constitutional Principle 1:
|
||||
- Complexity: Cyclomatic complexity <10 per function
|
||||
- Dependencies: Explicit versioning, security audit
|
||||
- Modularity: Clear separation of concerns
|
||||
|
||||
## Design
|
||||
|
||||
### Architecture Overview
|
||||
[Diagram or description of system components and their interactions]
|
||||
|
||||
### Data Models
|
||||
```python
|
||||
# Example data structures with type hints
|
||||
class ExampleModel:
|
||||
"""Clear docstring explaining purpose."""
|
||||
field1: str
|
||||
field2: int
|
||||
field3: Optional[List[str]]
|
||||
```
|
||||
|
||||
### API/Interface Specifications
|
||||
|
||||
#### Endpoint/Method: [Name]
|
||||
```python
|
||||
def example_function(param1: str, param2: int) -> ResultType:
|
||||
"""
|
||||
Clear description of what this does.
|
||||
|
||||
Args:
|
||||
param1: Description of parameter
|
||||
param2: Description of parameter
|
||||
|
||||
Returns:
|
||||
Description of return value
|
||||
|
||||
Raises:
|
||||
ValueError: When validation fails
|
||||
"""
|
||||
pass
|
||||
```
|
||||
|
||||
**Error Handling:**
|
||||
- Error case 1: Response/behavior
|
||||
- Error case 2: Response/behavior
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
#### Unit Tests
|
||||
- Component A: [Test scenarios]
|
||||
- Component B: [Test scenarios]
|
||||
- Edge cases: [List critical edge cases]
|
||||
|
||||
#### Integration Tests
|
||||
- Integration point 1: [Test scenario]
|
||||
- Integration point 2: [Test scenario]
|
||||
|
||||
#### Performance Tests
|
||||
- Benchmark 1: [Target metric]
|
||||
- Load test: [Expected traffic pattern]
|
||||
|
||||
## Implementation Considerations
|
||||
|
||||
### Performance Analysis
|
||||
- Algorithmic complexity: [Big-O analysis]
|
||||
- Database queries: [Query plans, indexes needed]
|
||||
- Caching strategy: [What, when, invalidation]
|
||||
- Bottleneck prevention: [Known risks and mitigations]
|
||||
|
||||
### Security Considerations
|
||||
- Authentication/Authorization requirements
|
||||
- Input validation requirements
|
||||
- Data protection measures
|
||||
|
||||
### Migration Path
|
||||
If this changes existing functionality:
|
||||
- Backward compatibility strategy
|
||||
- User migration steps
|
||||
- Rollback plan
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Internal Dependencies
|
||||
- Module/Service A: [Why needed]
|
||||
- Module/Service B: [Why needed]
|
||||
|
||||
### External Dependencies
|
||||
```python
|
||||
# New dependencies to add (with justification)
|
||||
package-name==X.Y.Z # Why: specific reason for this dependency
|
||||
```
|
||||
|
||||
## Rollout Plan
|
||||
|
||||
1. **Development:** [Timeline and milestones]
|
||||
2. **Testing:** [QA approach and environments]
|
||||
3. **Staging:** [Validation steps]
|
||||
4. **Production:** [Deployment strategy - canary/blue-green/etc]
|
||||
5. **Monitoring:** [Key metrics to watch]
|
||||
|
||||
## Success Metrics
|
||||
|
||||
Post-deployment validation:
|
||||
- [ ] All acceptance criteria met
|
||||
- [ ] Performance benchmarks achieved
|
||||
- [ ] Zero critical bugs in first week
|
||||
- [ ] User feedback collected and positive
|
||||
- [ ] Test coverage ≥80% maintained
|
||||
|
||||
## Open Issues
|
||||
|
||||
- [ ] Issue 1 requiring resolution
|
||||
- [ ] Issue 2 needing decision
|
||||
|
||||
## Appendix
|
||||
|
||||
### References
|
||||
- Related specifications
|
||||
- External documentation
|
||||
- Research materials
|
||||
|
||||
### Change Log
|
||||
| Version | Date | Author | Changes |
|
||||
|---------|------|--------|---------|
|
||||
| 1.0.0 | YYYY-MM-DD | Name | Initial specification |
|
||||
|
||||
@@ -1,251 +1,148 @@
|
||||
---
|
||||
# Tasks: [FEATURE/AREA_NAME]
|
||||
|
||||
description: "Task list template for feature implementation"
|
||||
---
|
||||
**Created:** [YYYY-MM-DD]
|
||||
**Last Updated:** [YYYY-MM-DD]
|
||||
**Sprint/Milestone:** [IDENTIFIER]
|
||||
|
||||
# Tasks: [FEATURE NAME]
|
||||
## Overview
|
||||
|
||||
Brief context for this task list and its relationship to plans/specs.
|
||||
|
||||
**Input**: Design documents from `/specs/[###-feature-name]/`
|
||||
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
|
||||
## Task Categories
|
||||
|
||||
**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
|
||||
Tasks are organized by constitutional principle to ensure balanced development:
|
||||
|
||||
**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
|
||||
### 🏗️ Implementation Tasks (Principle 1: Code Quality)
|
||||
|
||||
- [ ] **[TASK-001]** Task title
|
||||
- **Description:** What needs to be done
|
||||
- **Acceptance:** How to verify completion
|
||||
- **Estimate:** [S/M/L/XL or hours]
|
||||
- **Dependencies:** [Other task IDs]
|
||||
- **Quality checklist:**
|
||||
- [ ] Follows style guide (linter passes)
|
||||
- [ ] Type hints added
|
||||
- [ ] No code duplication
|
||||
- [ ] Comments explain "why" not "what"
|
||||
|
||||
- [ ] **[TASK-002]** Next task...
|
||||
|
||||
### 🧪 Testing Tasks (Principle 2: Testing Discipline)
|
||||
|
||||
## Format: `[ID] [P?] [Story] Description`
|
||||
- [ ] **[TEST-001]** Write unit tests for [Component]
|
||||
- **Coverage target:** ≥80% for new code
|
||||
- **Test scenarios:**
|
||||
- [ ] Happy path
|
||||
- [ ] Edge case 1
|
||||
- [ ] Edge case 2
|
||||
- [ ] Error handling
|
||||
- **Estimate:** [S/M/L/XL]
|
||||
|
||||
- **[P]**: Can run in parallel (different files, no dependencies)
|
||||
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
|
||||
- Include exact file paths in descriptions
|
||||
- [ ] **[TEST-002]** Integration tests for [Feature]
|
||||
- **Scope:** [Component interactions to validate]
|
||||
- **Performance target:** <10s execution time
|
||||
|
||||
## Path Conventions
|
||||
- [ ] **[TEST-003]** Regression test for [Bug #X]
|
||||
- **Bug reference:** [Link to issue]
|
||||
- **Reproduction steps:** [Documented]
|
||||
|
||||
- **Single project**: `src/`, `tests/` at repository root
|
||||
- **Web app**: `backend/src/`, `frontend/src/`
|
||||
- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
|
||||
- Paths shown below assume single project - adjust based on plan.md structure
|
||||
### 👤 User Experience Tasks (Principle 3: UX Consistency)
|
||||
|
||||
<!--
|
||||
============================================================================
|
||||
IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
|
||||
- [ ] **[UX-001]** Design/implement [UI Component]
|
||||
- **Design system alignment:** [Pattern/component to follow]
|
||||
- **Accessibility checklist:**
|
||||
- [ ] Keyboard navigable
|
||||
- [ ] Screen reader compatible
|
||||
- [ ] Color contrast WCAG AA
|
||||
- [ ] Focus indicators visible
|
||||
- **Estimate:** [S/M/L/XL]
|
||||
|
||||
The /speckit.tasks command MUST replace these with actual tasks based on:
|
||||
- User stories from spec.md (with their priorities P1, P2, P3...)
|
||||
- Feature requirements from plan.md
|
||||
- Entities from data-model.md
|
||||
- Endpoints from contracts/
|
||||
- [ ] **[UX-002]** Error message improvement for [Feature]
|
||||
- **Current message:** [What users see now]
|
||||
- **Improved message:** [Clear, actionable alternative]
|
||||
- **Context provided:** [Where, why, what to do]
|
||||
|
||||
Tasks MUST be organized by user story so each story can be:
|
||||
- Implemented independently
|
||||
- Tested independently
|
||||
- Delivered as an MVP increment
|
||||
- [ ] **[UX-003]** User documentation for [Feature]
|
||||
- **Target audience:** [End users/API consumers/admins]
|
||||
- **Format:** [README/Wiki/API docs/Tutorial]
|
||||
|
||||
DO NOT keep these sample tasks in the generated tasks.md file.
|
||||
============================================================================
|
||||
-->
|
||||
### ⚡ Performance Tasks (Principle 4: Performance & Efficiency)
|
||||
|
||||
## Phase 1: Setup (Shared Infrastructure)
|
||||
- [ ] **[PERF-001]** Optimize [Operation/Query]
|
||||
- **Current performance:** [Baseline metric]
|
||||
- **Target performance:** [Goal metric]
|
||||
- **Approach:** [Algorithm change/caching/indexing/etc]
|
||||
- **Estimate:** [S/M/L/XL]
|
||||
|
||||
**Purpose**: Project initialization and basic structure
|
||||
- [ ] **[PERF-002]** Add performance benchmark for [Feature]
|
||||
- **Metric:** [Response time/throughput/memory]
|
||||
- **Budget:** [Threshold that triggers alert]
|
||||
- **CI integration:** [How it blocks bad merges]
|
||||
|
||||
- [ ] T001 Create project structure per implementation plan
|
||||
- [ ] T002 Initialize [language] project with [framework] dependencies
|
||||
- [ ] T003 [P] Configure linting and formatting tools
|
||||
- [ ] **[PERF-003]** Profile and fix [Bottleneck]
|
||||
- **Profiling tool:** [Tool to use]
|
||||
- **Suspected issue:** [Hypothesis]
|
||||
- **Verification:** [How to confirm fix]
|
||||
|
||||
---
|
||||
### 🔧 Infrastructure/DevOps Tasks
|
||||
|
||||
## Phase 2: Foundational (Blocking Prerequisites)
|
||||
- [ ] **[INFRA-001]** Setup [Tool/Service]
|
||||
- **Purpose:** [Why this is needed]
|
||||
- **Configuration:** [Key settings]
|
||||
- **Documentation:** [Where to document setup]
|
||||
|
||||
**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
|
||||
- [ ] **[INFRA-002]** CI/CD pipeline enhancement
|
||||
- **Addition:** [What check/stage to add]
|
||||
- **Constitutional alignment:** [Which principle this enforces]
|
||||
|
||||
**⚠️ CRITICAL**: No user story work can begin until this phase is complete
|
||||
### 📋 Technical Debt Tasks
|
||||
|
||||
Examples of foundational tasks (adjust based on your project):
|
||||
- [ ] **[DEBT-001]** Refactor [Component]
|
||||
- **Current problem:** [What makes this debt]
|
||||
- **Proposed solution:** [Refactoring approach]
|
||||
- **Impact:** [What improves after fix]
|
||||
- **Estimate:** [S/M/L/XL]
|
||||
|
||||
- [ ] T004 Setup database schema and migrations framework
|
||||
- [ ] T005 [P] Implement authentication/authorization framework
|
||||
- [ ] T006 [P] Setup API routing and middleware structure
|
||||
- [ ] T007 Create base models/entities that all stories depend on
|
||||
- [ ] T008 Configure error handling and logging infrastructure
|
||||
- [ ] T009 Setup environment configuration management
|
||||
- [ ] **[DEBT-002]** Update dependencies
|
||||
- **Packages:** [List outdated packages]
|
||||
- **Risk assessment:** [Breaking changes?]
|
||||
- **Testing plan:** [How to verify upgrade]
|
||||
|
||||
**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
|
||||
## Task Estimation Guide
|
||||
|
||||
---
|
||||
- **S (Small):** <2 hours, single file, no dependencies
|
||||
- **M (Medium):** 2-4 hours, multiple files, minor dependencies
|
||||
- **L (Large):** 4-8 hours, multiple components, significant testing
|
||||
- **XL (X-Large):** >8 hours, consider breaking down further
|
||||
|
||||
## Completion Checklist
|
||||
|
||||
## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
|
||||
Before closing any task, verify:
|
||||
- [ ] Code changes committed with clear message
|
||||
- [ ] Tests written and passing (≥80% coverage for new code)
|
||||
- [ ] Linter/type checker passing
|
||||
- [ ] Documentation updated
|
||||
- [ ] Code review completed
|
||||
- [ ] Constitutional principles satisfied
|
||||
- [ ] Deployed to staging/production
|
||||
|
||||
**Goal**: [Brief description of what this story delivers]
|
||||
## Blocked Tasks
|
||||
|
||||
**Independent Test**: [How to verify this story works on its own]
|
||||
Track tasks waiting on external dependencies:
|
||||
|
||||
### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
|
||||
- **[TASK-XXX]** Task title
|
||||
- **Blocked by:** [Reason/dependency]
|
||||
- **Resolution needed:** [Action to unblock]
|
||||
- **Owner of blocker:** [Person/team]
|
||||
|
||||
> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
|
||||
## Completed Tasks
|
||||
|
||||
- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
|
||||
- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
|
||||
Move completed tasks here with completion date:
|
||||
|
||||
### Implementation for User Story 1
|
||||
- ✅ **[TASK-000]** Example completed task (2025-11-01)
|
||||
|
||||
- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
|
||||
- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
|
||||
- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
|
||||
- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
|
||||
- [ ] T016 [US1] Add validation and error handling
|
||||
- [ ] T017 [US1] Add logging for user story 1 operations
|
||||
## Notes & Decisions
|
||||
|
||||
**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
|
||||
Document important decisions or context that affects multiple tasks:
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: User Story 2 - [Title] (Priority: P2)
|
||||
|
||||
**Goal**: [Brief description of what this story delivers]
|
||||
|
||||
**Independent Test**: [How to verify this story works on its own]
|
||||
|
||||
### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
|
||||
|
||||
- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
|
||||
- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
|
||||
|
||||
### Implementation for User Story 2
|
||||
|
||||
- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
|
||||
- [ ] T021 [US2] Implement [Service] in src/services/[service].py
|
||||
- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
|
||||
- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
|
||||
|
||||
**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: User Story 3 - [Title] (Priority: P3)
|
||||
|
||||
**Goal**: [Brief description of what this story delivers]
|
||||
|
||||
**Independent Test**: [How to verify this story works on its own]
|
||||
|
||||
### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
|
||||
|
||||
- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
|
||||
- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
|
||||
|
||||
### Implementation for User Story 3
|
||||
|
||||
- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
|
||||
- [ ] T027 [US3] Implement [Service] in src/services/[service].py
|
||||
- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
|
||||
|
||||
**Checkpoint**: All user stories should now be independently functional
|
||||
|
||||
---
|
||||
|
||||
[Add more user story phases as needed, following the same pattern]
|
||||
|
||||
---
|
||||
|
||||
## Phase N: Polish & Cross-Cutting Concerns
|
||||
|
||||
**Purpose**: Improvements that affect multiple user stories
|
||||
|
||||
- [ ] TXXX [P] Documentation updates in docs/
|
||||
- [ ] TXXX Code cleanup and refactoring
|
||||
- [ ] TXXX Performance optimization across all stories
|
||||
- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
|
||||
- [ ] TXXX Security hardening
|
||||
- [ ] TXXX Run quickstart.md validation
|
||||
|
||||
---
|
||||
|
||||
## Dependencies & Execution Order
|
||||
|
||||
### Phase Dependencies
|
||||
|
||||
- **Setup (Phase 1)**: No dependencies - can start immediately
|
||||
- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
|
||||
- **User Stories (Phase 3+)**: All depend on Foundational phase completion
|
||||
- User stories can then proceed in parallel (if staffed)
|
||||
- Or sequentially in priority order (P1 → P2 → P3)
|
||||
- **Polish (Final Phase)**: Depends on all desired user stories being complete
|
||||
|
||||
### User Story Dependencies
|
||||
|
||||
- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
|
||||
- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
|
||||
- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
|
||||
|
||||
### Within Each User Story
|
||||
|
||||
- Tests (if included) MUST be written and FAIL before implementation
|
||||
- Models before services
|
||||
- Services before endpoints
|
||||
- Core implementation before integration
|
||||
- Story complete before moving to next priority
|
||||
|
||||
### Parallel Opportunities
|
||||
|
||||
- All Setup tasks marked [P] can run in parallel
|
||||
- All Foundational tasks marked [P] can run in parallel (within Phase 2)
|
||||
- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
|
||||
- All tests for a user story marked [P] can run in parallel
|
||||
- Models within a story marked [P] can run in parallel
|
||||
- Different user stories can be worked on in parallel by different team members
|
||||
|
||||
---
|
||||
|
||||
## Parallel Example: User Story 1
|
||||
|
||||
```bash
|
||||
# Launch all tests for User Story 1 together (if tests requested):
|
||||
Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
|
||||
Task: "Integration test for [user journey] in tests/integration/test_[name].py"
|
||||
|
||||
# Launch all models for User Story 1 together:
|
||||
Task: "Create [Entity1] model in src/models/[entity1].py"
|
||||
Task: "Create [Entity2] model in src/models/[entity2].py"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
### MVP First (User Story 1 Only)
|
||||
|
||||
1. Complete Phase 1: Setup
|
||||
2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
|
||||
3. Complete Phase 3: User Story 1
|
||||
4. **STOP and VALIDATE**: Test User Story 1 independently
|
||||
5. Deploy/demo if ready
|
||||
|
||||
### Incremental Delivery
|
||||
|
||||
1. Complete Setup + Foundational → Foundation ready
|
||||
2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
|
||||
3. Add User Story 2 → Test independently → Deploy/Demo
|
||||
4. Add User Story 3 → Test independently → Deploy/Demo
|
||||
5. Each story adds value without breaking previous stories
|
||||
|
||||
### Parallel Team Strategy
|
||||
|
||||
With multiple developers:
|
||||
|
||||
1. Team completes Setup + Foundational together
|
||||
2. Once Foundational is done:
|
||||
- Developer A: User Story 1
|
||||
- Developer B: User Story 2
|
||||
- Developer C: User Story 3
|
||||
3. Stories complete and integrate independently
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- [P] tasks = different files, no dependencies
|
||||
- [Story] label maps task to specific user story for traceability
|
||||
- Each user story should be independently completable and testable
|
||||
- Verify tests fail before implementing
|
||||
- Commit after each task or logical group
|
||||
- Stop at any checkpoint to validate story independently
|
||||
- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence
|
||||
- **[2025-11-02]** Decision about [topic]: [What was decided and why]
|
||||
|
||||
122
README.md
Normal file
122
README.md
Normal file
@@ -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]
|
||||
|
||||
108
specs/001-reference-board-viewer/checklists/requirements.md
Normal file
108
specs/001-reference-board-viewer/checklists/requirements.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# Specification Quality Checklist: Reference Board Viewer
|
||||
|
||||
**Purpose**: Validate specification completeness and quality before proceeding to planning
|
||||
**Created**: 2025-11-02
|
||||
**Feature**: [spec.md](../spec.md)
|
||||
|
||||
## Content Quality
|
||||
|
||||
- [x] No implementation details (languages, frameworks, APIs)
|
||||
- [x] Focused on user value and business needs
|
||||
- [x] Written for non-technical stakeholders
|
||||
- [x] All mandatory sections completed
|
||||
|
||||
**Notes:** Spec successfully avoids implementation details, focuses on WHAT users need and WHY. All requirements written in business terms.
|
||||
|
||||
## Requirement Completeness
|
||||
|
||||
- [x] No [NEEDS CLARIFICATION] markers remain
|
||||
- [x] Requirements are testable and unambiguous
|
||||
- [x] Success criteria are measurable
|
||||
- [x] Success criteria are technology-agnostic (no implementation details)
|
||||
- [x] All acceptance scenarios are defined
|
||||
- [x] Edge cases are identified
|
||||
- [x] Scope is clearly bounded
|
||||
- [x] Dependencies and assumptions identified
|
||||
|
||||
**Notes:**
|
||||
- **All clarifications resolved:**
|
||||
1. FR3: Configurable share permissions (View-only or View+Comment) - owner decides per link
|
||||
2. FR16: Hybrid connection detection (automatic with manual override)
|
||||
3. FR13: User-configurable navigation order (Chronological, Spatial, Alphabetical, Random)
|
||||
- All requirements have clear acceptance criteria
|
||||
- Success criteria are measurable and technology-agnostic
|
||||
- User scenarios cover primary flows comprehensively
|
||||
- Scope clearly defined with 18 functional requirements
|
||||
|
||||
## Feature Readiness
|
||||
|
||||
- [x] All functional requirements have clear acceptance criteria
|
||||
- [x] User scenarios cover primary flows
|
||||
- [x] Feature meets measurable outcomes defined in Success Criteria
|
||||
- [x] No implementation details leak into specification
|
||||
|
||||
**Notes:** 18 functional requirements with detailed acceptance criteria. 5 user scenarios covering critical paths.
|
||||
|
||||
## Clarification Resolutions
|
||||
|
||||
All clarification questions have been answered:
|
||||
|
||||
### Question 1: Viewer Annotation Capability ✅ RESOLVED
|
||||
|
||||
**User's Answer:** C - Configurable per share link (owner decides)
|
||||
|
||||
**Implementation Details Added to Spec:**
|
||||
- Share links have two permission levels: View-only or View+Comment
|
||||
- Owner chooses permission level when creating share link
|
||||
- Owner can change permission level of existing links
|
||||
- View+Comment allows annotations but not image/layout modifications
|
||||
- Comments from viewers are visually distinct from owner content
|
||||
|
||||
### Question 2: Connection Speed Detection Method ✅ RESOLVED
|
||||
|
||||
**User's Answer:** C - Hybrid: Auto-detect with manual override option
|
||||
|
||||
**Implementation Details Added to Spec:**
|
||||
- Automatic detection using browser Network Information API and speed test
|
||||
- Three quality tiers: Low (<1 Mbps), Medium (1-5 Mbps), High (>5 Mbps)
|
||||
- Manual override available: Auto/Low/Medium/High setting
|
||||
- Quality setting selector easily accessible in UI
|
||||
- Periodic re-evaluation (every 5 minutes) in Auto mode
|
||||
- Setting persists across sessions
|
||||
|
||||
### Question 3: Image Navigation Order ✅ RESOLVED
|
||||
|
||||
**User's Answer:** C - User-configurable, with additional options (Random and Alphabetical)
|
||||
|
||||
**Implementation Details Added to Spec:**
|
||||
- Four navigation order options: Chronological (default), Spatial, Alphabetical, Random
|
||||
- Navigation order applies to both focus mode and slideshow
|
||||
- User preference saved and persists across sessions
|
||||
- Also added "Random" option to FR18 (Arrange Images by Criteria)
|
||||
|
||||
## Validation Status: ✅ COMPLETE
|
||||
|
||||
Specification is **READY FOR PLANNING** (`/speckit.plan`)
|
||||
|
||||
### Quality Summary
|
||||
|
||||
- **18 Functional Requirements** with detailed, testable acceptance criteria
|
||||
- **7 Non-Functional Requirements** aligned with constitutional principles
|
||||
- **5 User Scenarios** covering critical workflows
|
||||
- **14 Success Criteria** (measurable, technology-agnostic)
|
||||
- **All clarifications resolved** (no open questions)
|
||||
- **696 lines** of comprehensive specification
|
||||
|
||||
### Constitutional Alignment Verified
|
||||
|
||||
- **Code Quality (Principle 1):** Modularity and separation of concerns emphasized in NFR4
|
||||
- **Testing (Principle 2):** 80% coverage requirement in NFR2, all requirements have testable acceptance criteria
|
||||
- **UX Consistency (Principle 3):** WCAG 2.1 AA compliance, keyboard navigation, clear error messages in NFR3
|
||||
- **Performance (Principle 4):** Specific performance budgets defined in NFR1 (60fps, <200ms response, 1000 concurrent users)
|
||||
|
||||
### Next Steps
|
||||
|
||||
1. Run `/speckit.plan` to create the implementation plan
|
||||
2. Plan will break down the 18 functional requirements into phased development approach
|
||||
3. Technical architecture and Nix deployment strategy will be defined in planning phase
|
||||
|
||||
707
specs/001-reference-board-viewer/spec.md
Normal file
707
specs/001-reference-board-viewer/spec.md
Normal file
@@ -0,0 +1,707 @@
|
||||
# Specification: Reference Board Viewer
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Created:** 2025-11-02
|
||||
**Last Updated:** 2025-11-02
|
||||
**Status:** Approved
|
||||
**Owner:** Project Team
|
||||
|
||||
## Purpose
|
||||
|
||||
This specification defines a web-based reference board application for artists and creative professionals to collect, organize, and manipulate visual reference images. The application addresses the need for a collaborative, accessible alternative to desktop-only tools (like PureRef), enabling users to create mood boards, reference collections, and visual collages from any device with internet access.
|
||||
|
||||
**Business Value:**
|
||||
- Enables remote collaboration on visual reference collections
|
||||
- Provides accessible visual organization tools without desktop software installation
|
||||
- Supports artists' creative workflows with non-destructive image manipulation
|
||||
- Scales from individual artists to collaborative creative teams
|
||||
|
||||
## User Scenarios & Testing
|
||||
|
||||
### Scenario 1: Creating a New Reference Board
|
||||
|
||||
**Actor:** Artist (authenticated user)
|
||||
**Goal:** Create a new reference board for a character design project
|
||||
|
||||
**Flow:**
|
||||
1. User logs into the application
|
||||
2. User creates a new board titled "Character Design - Fantasy Knight"
|
||||
3. User uploads 15 reference images (armor, poses, weapons) via drag-and-drop
|
||||
4. User arranges images by dragging them into desired positions
|
||||
5. User groups armor references together with a label "Plate Armor - Blue"
|
||||
6. User saves the board
|
||||
|
||||
**Success Criteria:** Board is saved with all images properly positioned and grouped
|
||||
|
||||
### Scenario 2: Collaborating on a Shared Board
|
||||
|
||||
**Actor:** Art Director (authenticated user)
|
||||
**Goal:** Review and annotate a junior artist's reference board
|
||||
|
||||
**Flow:**
|
||||
1. Junior artist shares board "Environment Concepts" with art director (View+Comment permission)
|
||||
2. Art director opens the shared board link
|
||||
3. Art director views all images and can add comments
|
||||
4. Art director adds comment "Love the color palette in group 3"
|
||||
5. Junior artist sees the comment when reopening the board
|
||||
|
||||
**Success Criteria:** Art director can view board, add comments, but cannot modify images or layout
|
||||
|
||||
### Scenario 3: Working with Limited Bandwidth
|
||||
|
||||
**Actor:** Freelance artist with slow internet connection
|
||||
**Goal:** Access reference board while traveling
|
||||
|
||||
**Flow:**
|
||||
1. User opens their board "Portrait References"
|
||||
2. Application automatically detects slow connection using browser Network API and speed test
|
||||
3. Application serves low-resolution previews of images
|
||||
4. User can still zoom/pan/arrange images smoothly
|
||||
5. User can optionally load full-resolution version of specific images
|
||||
6. User can manually override quality setting if auto-detection is incorrect
|
||||
|
||||
**Success Criteria:** Board loads and remains usable within 10 seconds on 3G connection
|
||||
|
||||
### Scenario 4: Complex Image Arrangement
|
||||
|
||||
**Actor:** Concept artist (authenticated user)
|
||||
**Goal:** Create organized layout of 50+ references with precise alignment
|
||||
|
||||
**Flow:**
|
||||
1. User opens existing board with 50 images
|
||||
2. User selects 10 images showing character expressions
|
||||
3. User uses "Align Top" command to align all selected images
|
||||
4. User uses "Distribute Horizontal" to space them evenly
|
||||
5. User enables snap-to-grid for precise placement
|
||||
6. User groups the aligned images with annotation "Expression Study"
|
||||
7. User exports the final arrangement as a single high-resolution image
|
||||
|
||||
**Success Criteria:** Images align precisely, export contains all images at full quality
|
||||
|
||||
### Scenario 5: Non-Destructive Editing
|
||||
|
||||
**Actor:** Illustrator (authenticated user)
|
||||
**Goal:** Crop and adjust images for board without losing original files
|
||||
|
||||
**Flow:**
|
||||
1. User uploads high-resolution reference photo (4K resolution)
|
||||
2. User crops image to focus on a specific detail
|
||||
3. User converts image to greyscale for value study
|
||||
4. User reduces opacity to 50% for overlay reference
|
||||
5. User later needs original - clicks "Reset to Original"
|
||||
6. All edits are reverted, original 4K image restored
|
||||
|
||||
**Success Criteria:** Original image is never modified, all edits are reversible
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
#### FR1: User Authentication & Account Management
|
||||
**Priority:** Critical
|
||||
**Description:** Users must be able to create accounts, log in, and manage their profile to access private boards and collaborate with others.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can register for an account with email and password
|
||||
- [ ] Users can log in and log out securely
|
||||
- [ ] User sessions persist across browser sessions
|
||||
- [ ] Users can reset forgotten passwords
|
||||
- [ ] Each user has a unique, isolated workspace for their boards
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Unit tests for authentication logic, integration tests for login/logout flows
|
||||
- UX Impact: Login process completes in <3 seconds, clear error messages for failed authentication
|
||||
- Performance: Authentication check completes in <100ms, sessions cached efficiently
|
||||
|
||||
#### FR2: Board Management
|
||||
**Priority:** Critical
|
||||
**Description:** Users must be able to create, save, edit, delete, and organize multiple reference boards.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can create a new board with a title
|
||||
- [ ] Users can save boards (auto-save and manual save)
|
||||
- [ ] Users can edit board title and metadata
|
||||
- [ ] Users can delete boards (with confirmation prompt)
|
||||
- [ ] Users can view a list of all their boards
|
||||
- [ ] Board list shows preview thumbnail, title, last modified date, and image count
|
||||
- [ ] Users can duplicate existing boards
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Unit tests for board CRUD operations, integration tests for board list rendering
|
||||
- UX Impact: Board creation is instant (<200ms), deletion requires confirmation to prevent accidents
|
||||
- Performance: Board list loads in <1 second for users with up to 100 boards
|
||||
|
||||
#### FR3: Board Sharing & Collaboration
|
||||
**Priority:** High
|
||||
**Description:** Users must be able to share boards with other users while maintaining privacy controls.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Boards are private by default (only owner can access)
|
||||
- [ ] Users can generate a share link for any board
|
||||
- [ ] When creating share link, owner chooses permission level: View-only or View+Comment
|
||||
- [ ] View-only links allow recipients to see board but not modify or comment
|
||||
- [ ] View+Comment links allow recipients to add comments/annotations but not modify images or layout
|
||||
- [ ] Users can revoke share links at any time
|
||||
- [ ] Users can change permission level of existing share links
|
||||
- [ ] Board owner can see list of active share links with their permission levels
|
||||
- [ ] Comments from viewers are visually distinct from owner content
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Integration tests for sharing permissions, security tests to verify access controls
|
||||
- UX Impact: Share link generation is instant, clear indication of board privacy status
|
||||
- Performance: Share link validation completes in <100ms
|
||||
|
||||
#### FR4: Image Upload & Import
|
||||
**Priority:** Critical
|
||||
**Description:** Users must be able to add images to boards through multiple convenient methods.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can upload images via file picker dialog
|
||||
- [ ] Users can upload multiple images simultaneously (batch upload)
|
||||
- [ ] Users can drag and drop image files directly onto the board
|
||||
- [ ] Users can paste images from clipboard (e.g., screenshots)
|
||||
- [ ] Users can upload ZIP files containing multiple images (extracted automatically)
|
||||
- [ ] Supported formats: JPEG, PNG, GIF, WebP, SVG
|
||||
- [ ] Maximum individual file size: 50MB
|
||||
- [ ] Maximum batch upload size: 500MB
|
||||
- [ ] Upload progress indicator shows for uploads >5 seconds
|
||||
- [ ] Failed uploads show clear error messages with reasons
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Unit tests for file validation, integration tests for each upload method
|
||||
- UX Impact: Upload progress visible for large files, drag-drop works intuitively
|
||||
- Performance: Upload processes in background, UI remains responsive
|
||||
|
||||
#### FR5: Image Positioning & Layout
|
||||
**Priority:** Critical
|
||||
**Description:** Users must be able to freely position, arrange, and organize images on the infinite canvas.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can drag images to any position on the canvas
|
||||
- [ ] Images can overlap (Z-order controlled by user)
|
||||
- [ ] Users can bring images to front or send to back
|
||||
- [ ] Users can bring images forward/backward one layer at a time
|
||||
- [ ] Canvas is infinite (no boundaries, scrollable in all directions)
|
||||
- [ ] Users can select multiple images with click+drag selection box
|
||||
- [ ] Users can select/deselect individual images with Ctrl+Click (Cmd+Click on Mac)
|
||||
- [ ] Selected images show visual highlight (border or outline)
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Integration tests for drag-drop, unit tests for Z-order calculations
|
||||
- UX Impact: Dragging feels smooth (<16ms frame time), visual feedback is immediate
|
||||
- Performance: Handles 500+ images on canvas without lag
|
||||
|
||||
#### FR6: Image Alignment & Distribution
|
||||
**Priority:** High
|
||||
**Description:** Users must be able to precisely align and distribute images for professional layouts.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can align selected images: Top, Bottom, Left, Right, Center Vertical, Center Horizontal
|
||||
- [ ] Users can distribute selected images: Horizontal spacing, Vertical spacing
|
||||
- [ ] Alignment operations preserve relative positions except for aligned axis
|
||||
- [ ] Distribution creates equal spacing between images
|
||||
- [ ] Snap-to-grid mode helps images align to grid lines
|
||||
- [ ] Grid size is configurable (default: 50px)
|
||||
- [ ] Snap-to-grid can be toggled on/off with keyboard shortcut
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Unit tests for alignment calculations, integration tests for UI commands
|
||||
- UX Impact: Alignment is instant (<50ms), grid provides visual guides
|
||||
- Performance: Alignment calculations complete in <100ms for 100 selected images
|
||||
|
||||
#### FR7: Image Grouping & Annotations
|
||||
**Priority:** High
|
||||
**Description:** Users must be able to organize images into groups with labels for better organization.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can select multiple images and create a group
|
||||
- [ ] Groups can have text annotations (title/description)
|
||||
- [ ] Groups can have colored labels (user selects from color palette)
|
||||
- [ ] Groups can be moved as a single unit (all images move together)
|
||||
- [ ] Groups can be ungrouped (images remain, group dissolves)
|
||||
- [ ] Images can belong to only one group at a time
|
||||
- [ ] Groups can contain 1-1000 images
|
||||
- [ ] Group annotations are visible as overlay or adjacent to group
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Unit tests for grouping logic, integration tests for group operations
|
||||
- UX Impact: Group creation is instant, visual indicators clearly show grouped images
|
||||
- Performance: Moving groups with 100+ images maintains 60fps
|
||||
|
||||
#### FR8: Image Transformation & Editing
|
||||
**Priority:** Critical
|
||||
**Description:** Users must be able to transform and adjust images non-destructively.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can scale images (resize) by dragging corners or entering dimensions
|
||||
- [ ] Users can rotate images to any angle (free rotation and 90° increments)
|
||||
- [ ] Users can flip images horizontally and vertically
|
||||
- [ ] Users can crop images to rectangular regions
|
||||
- [ ] Users can adjust image opacity (0-100%)
|
||||
- [ ] Users can convert images to greyscale
|
||||
- [ ] All transformations are non-destructive (original preserved)
|
||||
- [ ] Users can reset any image to original state
|
||||
- [ ] Transformation UI shows current values (angle, scale %, opacity %)
|
||||
- [ ] Proportional scaling is default (maintains aspect ratio)
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Unit tests for transformation calculations, integration tests for UI controls
|
||||
- UX Impact: Transformations render in real-time (<16ms), controls are intuitive
|
||||
- Performance: Transformations use GPU acceleration when available
|
||||
|
||||
#### FR9: Multi-Selection & Bulk Operations
|
||||
**Priority:** High
|
||||
**Description:** Users must be able to select and operate on multiple images simultaneously.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can select multiple images by dragging selection rectangle
|
||||
- [ ] Users can add to selection with Ctrl+Click (Cmd+Click on Mac)
|
||||
- [ ] Users can select all images with Ctrl+A (Cmd+A on Mac)
|
||||
- [ ] Users can deselect all with Escape key or clicking empty canvas
|
||||
- [ ] Bulk operations available: Move, Scale, Rotate, Delete, Group, Align, Distribute
|
||||
- [ ] Bulk transformations apply relative to each image's center
|
||||
- [ ] Selection count indicator shows number of selected images
|
||||
- [ ] Users can invert selection (select all except currently selected)
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Integration tests for selection operations, unit tests for bulk transforms
|
||||
- UX Impact: Selection box appears instantly, visual feedback for selected state
|
||||
- Performance: Selection operations remain responsive with 500+ images
|
||||
|
||||
#### FR10: Copy, Cut, Paste, Delete Operations
|
||||
**Priority:** High
|
||||
**Description:** Users must have standard clipboard operations for efficient editing.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can copy selected images (Ctrl+C / Cmd+C)
|
||||
- [ ] Users can cut selected images (Ctrl+X / Cmd+X)
|
||||
- [ ] Users can paste copied/cut images (Ctrl+V / Cmd+V)
|
||||
- [ ] Pasted images appear at center of current viewport
|
||||
- [ ] Pasted images are automatically selected
|
||||
- [ ] Users can delete selected images (Delete/Backspace key)
|
||||
- [ ] Delete operation requires confirmation if >10 images selected
|
||||
- [ ] Cut images are removed from canvas after paste
|
||||
- [ ] Copied images remain on canvas after paste
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Integration tests for clipboard operations, unit tests for delete logic
|
||||
- UX Impact: Standard keyboard shortcuts work as expected
|
||||
- Performance: Copy/paste operations complete in <200ms
|
||||
|
||||
#### FR11: Command Palette
|
||||
**Priority:** Medium
|
||||
**Description:** Users must have quick access to all commands through a searchable palette.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Command palette opens with keyboard shortcut (Ctrl+K / Cmd+K)
|
||||
- [ ] Palette shows list of all available commands
|
||||
- [ ] Users can search/filter commands by typing
|
||||
- [ ] Search matches command names and synonyms
|
||||
- [ ] Palette shows keyboard shortcuts next to commands
|
||||
- [ ] Recently used commands appear at top
|
||||
- [ ] Palette closes after command execution or on Escape key
|
||||
- [ ] Commands are categorized (File, Edit, View, Arrange, etc.)
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Integration tests for command execution, unit tests for search/filter
|
||||
- UX Impact: Palette opens instantly (<100ms), search results update in real-time
|
||||
- Performance: Search filters 100+ commands in <50ms
|
||||
|
||||
#### FR12: Canvas Navigation & Viewport Control
|
||||
**Priority:** Critical
|
||||
**Description:** Users must be able to navigate the infinite canvas efficiently.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can pan canvas by dragging with middle mouse button or spacebar+drag
|
||||
- [ ] Users can zoom in/out with mouse wheel or pinch gesture
|
||||
- [ ] Zoom levels: 10% to 500% (increments of 10%)
|
||||
- [ ] Users can rotate entire canvas view (for different perspective)
|
||||
- [ ] Users can reset camera to default position/zoom/rotation
|
||||
- [ ] Users can fit all images to viewport (zoom to fit)
|
||||
- [ ] Users can center on selected image(s)
|
||||
- [ ] Viewport position/zoom persists when reopening board
|
||||
- [ ] Touch gestures supported on tablets: two-finger pan, pinch zoom, rotate
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Integration tests for navigation controls, unit tests for zoom calculations
|
||||
- UX Impact: Pan/zoom feels smooth (60fps), gestures respond naturally
|
||||
- Performance: Viewport updates maintain 60fps with 500+ images
|
||||
|
||||
#### FR13: Image Focus & Navigation
|
||||
**Priority:** Medium
|
||||
**Description:** Users must be able to focus on individual images and navigate between them.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can double-click image to enter focus mode (image fills viewport)
|
||||
- [ ] Focus mode hides all other images temporarily
|
||||
- [ ] Users can exit focus mode with Escape key or clicking outside
|
||||
- [ ] Users can navigate to next image with arrow key or on-screen button
|
||||
- [ ] Users can navigate to previous image with arrow key or on-screen button
|
||||
- [ ] Users can choose navigation order from dropdown: Chronological (upload time), Spatial (left-to-right, top-to-bottom), Alphabetical (by filename), Random
|
||||
- [ ] Navigation order preference is saved per user and persists across sessions
|
||||
- [ ] Default navigation order is Chronological
|
||||
- [ ] Focus mode shows image counter (e.g., "5 of 23")
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Integration tests for focus mode, unit tests for navigation logic
|
||||
- UX Impact: Focus transition is smooth, navigation is intuitive
|
||||
- Performance: Focus mode transitions complete in <200ms
|
||||
|
||||
#### FR14: Slideshow Mode
|
||||
**Priority:** Low
|
||||
**Description:** Users must be able to play an automatic slideshow of board images.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can start slideshow from menu or keyboard shortcut
|
||||
- [ ] Slideshow displays images in full-screen or maximized view
|
||||
- [ ] Configurable interval between images (1-30 seconds, default 5)
|
||||
- [ ] Users can pause/resume slideshow
|
||||
- [ ] Users can manually advance to next/previous image during slideshow
|
||||
- [ ] Users can exit slideshow with Escape key
|
||||
- [ ] Slideshow respects navigation order setting (same as focus mode: Chronological, Spatial, Alphabetical, or Random)
|
||||
- [ ] Slideshow controls overlay bottom of screen
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Integration tests for slideshow controls, unit tests for timing logic
|
||||
- UX Impact: Transitions between images are smooth, controls are accessible
|
||||
- Performance: Slideshow maintains smooth transitions at 60fps
|
||||
|
||||
#### FR15: Image Export & Download
|
||||
**Priority:** High
|
||||
**Description:** Users must be able to export images and board layouts for external use.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can download individual images (click image → "Download")
|
||||
- [ ] Users can export all images as ZIP file (preserves original quality)
|
||||
- [ ] Users can export entire board as single composite image (PNG/JPEG)
|
||||
- [ ] Composite export captures current viewport or all images [user selects]
|
||||
- [ ] Composite export resolution: Screen resolution, 2x, 4x (up to 16K pixels)
|
||||
- [ ] Export operations show progress indicator
|
||||
- [ ] Exported ZIP includes folder structure for grouped images
|
||||
- [ ] Exported images maintain original filenames where possible
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Integration tests for export operations, unit tests for image generation
|
||||
- UX Impact: Export options are clear, progress visible for large exports
|
||||
- Performance: Single image export <1s, ZIP export <10s for 100 images
|
||||
|
||||
#### FR16: Adaptive Image Quality Serving
|
||||
**Priority:** High
|
||||
**Description:** Application must serve appropriate image quality based on connection speed to ensure usability on all networks.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Application automatically detects user's connection speed using browser Network Information API and initial speed test
|
||||
- [ ] On slow connections (<1 Mbps), serve low-resolution previews (max 800px)
|
||||
- [ ] On medium connections (1-5 Mbps), serve medium-resolution (max 1600px)
|
||||
- [ ] On fast connections (>5 Mbps), serve full-resolution images
|
||||
- [ ] Users can manually override automatic detection with quality setting (Auto/Low/Medium/High)
|
||||
- [ ] Quality setting selector is easily accessible in UI
|
||||
- [ ] Original full-resolution images always preserved on server
|
||||
- [ ] Users can selectively load full-resolution for specific images regardless of quality setting
|
||||
- [ ] Quality setting preference persists across sessions
|
||||
- [ ] Loading indicator shows when full-resolution is being fetched
|
||||
- [ ] Application re-evaluates connection speed periodically (every 5 minutes) when in Auto mode
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Integration tests for quality detection, unit tests for resolution logic
|
||||
- UX Impact: Boards load within 10 seconds on slow connections
|
||||
- Performance: Quality detection completes within first 2 seconds of session
|
||||
|
||||
#### FR17: Image Reuse Across Boards
|
||||
**Priority:** Medium
|
||||
**Description:** Users must be able to reuse uploaded images across multiple boards without re-uploading.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] When image is uploaded, it's stored in user's image library
|
||||
- [ ] Users can access their image library from any board
|
||||
- [ ] Users can add existing library images to new boards
|
||||
- [ ] Same image on multiple boards references single stored file (no duplication)
|
||||
- [ ] Deleting image from a board doesn't delete from library
|
||||
- [ ] Users can permanently delete images from library (removes from all boards)
|
||||
- [ ] Library view shows all uploaded images with thumbnails
|
||||
- [ ] Library supports search/filter by filename or upload date
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Integration tests for library operations, unit tests for reference counting
|
||||
- UX Impact: Adding library images is instant (no re-upload), library is easily browsable
|
||||
- Performance: Image library with 1000+ images loads in <2 seconds
|
||||
|
||||
#### FR18: Arrange Images by Criteria
|
||||
**Priority:** Low
|
||||
**Description:** Users can automatically arrange images based on different sorting criteria.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Users can auto-arrange images by: Name (alphabetical), Upload date, Optimal layout, Random
|
||||
- [ ] Optimal layout minimizes whitespace while maintaining readability
|
||||
- [ ] Random arrangement distributes images unpredictably across canvas
|
||||
- [ ] Auto-arrange preserves groups (grouped images stay together)
|
||||
- [ ] Users can undo auto-arrange operation
|
||||
- [ ] Auto-arrange operation shows preview before applying
|
||||
- [ ] Users can configure arrange direction (left-to-right, top-to-bottom)
|
||||
- [ ] Arrange operation respects existing groups and their internal layout
|
||||
|
||||
**Constitutional Alignment:**
|
||||
- Testing: Unit tests for sorting algorithms, integration tests for arrange UI
|
||||
- UX Impact: Arrange operation is reversible, preview shows expected result
|
||||
- Performance: Auto-arrange completes in <2 seconds for 100 images
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
#### NFR1: Performance
|
||||
Per Constitutional Principle 4:
|
||||
- **Page Load Time:** Initial application load <3 seconds on 5 Mbps connection
|
||||
- **Board Load Time:** Board with 100 images loads in <2 seconds (low-res previews)
|
||||
- **UI Responsiveness:** All user interactions respond within 200ms
|
||||
- **Animation Frame Rate:** Canvas operations maintain 60fps (pan, zoom, drag)
|
||||
- **Concurrent Users:** System supports 1,000 concurrent users
|
||||
- **Large Boards:** Boards with 500+ images remain usable (no lag during pan/zoom)
|
||||
- **Upload Performance:** 10 images (20MB total) upload in <10 seconds on 10 Mbps connection
|
||||
- **Export Performance:** Board export to single image completes in <30 seconds for 100 images
|
||||
|
||||
#### NFR2: Quality
|
||||
Per Constitutional Principle 1:
|
||||
- **Code Coverage:** ≥80% test coverage (Principle 2 requirement)
|
||||
- **Linting:** Zero errors/warnings in code quality checks
|
||||
- **Type Safety:** All data structures and interfaces fully typed
|
||||
- **Documentation:** All user-facing features documented in help system
|
||||
- **Error Handling:** All error states have user-friendly messages
|
||||
- **Logging:** All critical operations logged for debugging
|
||||
|
||||
#### NFR3: User Experience
|
||||
Per Constitutional Principle 3:
|
||||
- **Accessibility:** WCAG 2.1 AA compliance for all UI elements
|
||||
- **Keyboard Navigation:** All features accessible via keyboard shortcuts
|
||||
- **Error Messages:** Clear, actionable messages for all error conditions
|
||||
- **Responsive Design:** Works on desktop (1920x1080), tablet (1024x768), and mobile (375x667)
|
||||
- **Browser Support:** Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
|
||||
- **Loading States:** Progress indicators for all operations >1 second
|
||||
- **Offline Support:** Users see appropriate message when offline (no cryptic errors)
|
||||
- **Help System:** Contextual help available for all major features
|
||||
|
||||
#### NFR4: Maintainability
|
||||
Per Constitutional Principle 1:
|
||||
- **Code Complexity:** Functions maintain low cyclomatic complexity (<10)
|
||||
- **Modularity:** Clear separation between UI, business logic, and data layers
|
||||
- **Dependency Management:** All dependencies explicitly versioned
|
||||
- **Deployment:** Reproducible deployments via Nix configuration
|
||||
- **Configuration:** Environment-specific settings externalized (not hardcoded)
|
||||
- **Monitoring:** Application health metrics exposed for monitoring
|
||||
|
||||
#### NFR5: Security
|
||||
- **Authentication:** Secure password hashing and session management
|
||||
- **Authorization:** Strict access controls for private boards
|
||||
- **Data Privacy:** User data isolated, no cross-user data leakage
|
||||
- **File Upload Validation:** All uploads validated for file type, size, and malicious content
|
||||
- **XSS Prevention:** All user input sanitized before display
|
||||
- **CSRF Protection:** All state-changing operations protected against CSRF
|
||||
- **HTTPS:** All connections encrypted in transit
|
||||
- **Secrets Management:** No hardcoded secrets, use environment variables
|
||||
|
||||
#### NFR6: Scalability
|
||||
- **Storage:** Support for 100GB+ total image storage per user
|
||||
- **Boards per User:** Support for 500+ boards per user
|
||||
- **Images per Board:** Support for 1,000+ images per board
|
||||
- **Concurrent Sessions:** Single user can have 5+ concurrent sessions
|
||||
- **Horizontal Scaling:** Application can scale horizontally (add more servers)
|
||||
|
||||
#### NFR7: Reliability
|
||||
- **Uptime:** 99.9% uptime target (SLA)
|
||||
- **Data Durability:** Image uploads have 99.999% durability (no data loss)
|
||||
- **Auto-Save:** Boards auto-save every 30 seconds (prevents work loss)
|
||||
- **Backup:** User data backed up daily
|
||||
- **Recovery:** Point-in-time recovery available for last 30 days
|
||||
- **Graceful Degradation:** If image service fails, application shows cached/cached thumbnails
|
||||
|
||||
## Success Criteria
|
||||
|
||||
Post-deployment validation (technology-agnostic, measurable outcomes):
|
||||
|
||||
- [ ] **User Onboarding:** New users can create their first board with 10 images within 5 minutes
|
||||
- [ ] **Board Load Performance:** 95% of board loads complete within 3 seconds
|
||||
- [ ] **Operation Responsiveness:** 99% of user interactions respond within 200ms
|
||||
- [ ] **Upload Success Rate:** 99% of valid image uploads succeed on first attempt
|
||||
- [ ] **Cross-Browser Compatibility:** Application works identically on all supported browsers
|
||||
- [ ] **Accessibility Compliance:** Application passes WCAG 2.1 AA automated testing suite
|
||||
- [ ] **Mobile Usability:** Users can successfully create and edit boards on tablet devices
|
||||
- [ ] **Collaboration Success:** Users can successfully share boards and recipients can access within 1 minute
|
||||
- [ ] **Export Reliability:** 100% of export operations complete successfully or show clear error
|
||||
- [ ] **Non-Destructive Editing:** Users can reset any edited image to original 100% of the time
|
||||
- [ ] **Connection Adaptability:** Application loads successfully on 3G connections (1 Mbps) within 10 seconds
|
||||
- [ ] **User Satisfaction:** 90%+ of users rate the application "easy to use" in post-launch survey
|
||||
- [ ] **Feature Completeness:** All 18 functional requirements fully implemented and testable
|
||||
- [ ] **Test Coverage:** ≥80% code coverage maintained across entire codebase
|
||||
|
||||
## Key Entities
|
||||
|
||||
High-level description of main concepts in the system:
|
||||
|
||||
### User
|
||||
- Unique identifier
|
||||
- Authentication credentials (email, password hash)
|
||||
- Profile information (name, preferences)
|
||||
- Owns multiple Boards
|
||||
- Has access to own Image Library
|
||||
- Can receive shared board links
|
||||
|
||||
### Board
|
||||
- Unique identifier
|
||||
- Title and description
|
||||
- Owner (User reference)
|
||||
- Creation and last modified timestamps
|
||||
- Privacy setting (private or shareable)
|
||||
- Contains multiple Images positioned on canvas
|
||||
- Contains multiple Groups
|
||||
- Viewport state (zoom, pan, rotation)
|
||||
- Auto-save enabled/disabled
|
||||
|
||||
### Image
|
||||
- Unique identifier
|
||||
- Original file (full resolution)
|
||||
- Thumbnail versions (multiple resolutions)
|
||||
- File metadata (filename, size, dimensions, format, upload date)
|
||||
- Position on board (X, Y coordinates)
|
||||
- Transformations (scale, rotation, crop, opacity, effects)
|
||||
- Z-order (layer position)
|
||||
- Belongs to zero or one Group
|
||||
- Reference count (how many boards use this image)
|
||||
|
||||
### Group
|
||||
- Unique identifier
|
||||
- Contains multiple Images
|
||||
- Annotation text
|
||||
- Color label
|
||||
- Position and bounding box
|
||||
- Transformation state (can be moved/scaled as unit)
|
||||
|
||||
### Share Link
|
||||
- Unique identifier
|
||||
- Associated Board reference
|
||||
- Access token (secure, unguessable)
|
||||
- Creation timestamp
|
||||
- Access count and last accessed timestamp
|
||||
- Active/revoked status
|
||||
|
||||
### Image Library
|
||||
- User's collection of all uploaded images
|
||||
- Organized by upload date, filename
|
||||
- Shared across all user's boards
|
||||
- Images can be added to multiple boards
|
||||
|
||||
## Assumptions
|
||||
|
||||
Based on the feature description, we're making these informed assumptions:
|
||||
|
||||
1. **Authentication Method:** Email/password authentication with secure session management (industry standard for web apps)
|
||||
|
||||
2. **Single User Type:** All authenticated users have the same capabilities (no admin/editor/viewer roles beyond board sharing)
|
||||
|
||||
3. **Board Editing:** Only board owner can edit; shared links provide read-only access
|
||||
|
||||
4. **Image Storage:** Images stored in cloud-compatible storage (filesystem or object storage) with CDN support for optimal delivery
|
||||
|
||||
5. **Connection Detection:** Slow connection detected using browser Network Information API or download speed test on first load
|
||||
|
||||
6. **Navigation Order:** Image navigation in focus/slideshow modes follows upload order (chronological) by default
|
||||
|
||||
7. **Deployment Environment:** Self-hosted deployment on Linux-based servers using Nix for reproducible builds
|
||||
|
||||
8. **Offline Capability:** Application is online-only (requires internet connection), gracefully handles disconnections
|
||||
|
||||
9. **Image Formats:** Standard web image formats supported (JPEG, PNG, GIF, WebP, SVG), no RAW or specialized formats
|
||||
|
||||
10. **Concurrent Editing:** No real-time collaborative editing (multiple users editing same board simultaneously), only sharing for viewing
|
||||
|
||||
11. **Billing/Payment:** No monetization features in v1.0 (free for all users)
|
||||
|
||||
12. **Mobile Support:** Optimized for tablet/desktop, mobile phone support is basic (view-only recommended)
|
||||
|
||||
13. **Browser Requirements:** Modern evergreen browsers (no IE11 support)
|
||||
|
||||
14. **Language:** English-only interface in v1.0
|
||||
|
||||
15. **Maximum Limits:** Reasonable limits to prevent abuse: 50MB per image, 500MB per batch upload, 1000 images per board
|
||||
|
||||
16. **Share Link Permissions:** Configurable per link - owner decides between View-only and View+Comment when generating share link
|
||||
|
||||
17. **Connection Detection:** Hybrid approach using automatic detection (browser Network Information API + speed test) with manual user override capability
|
||||
|
||||
18. **Navigation Order Options:** User-configurable with four options: Chronological (default), Spatial, Alphabetical, and Random
|
||||
|
||||
## Dependencies
|
||||
|
||||
### External Dependencies (High-Level)
|
||||
|
||||
- **Web Hosting Infrastructure:** Server environment capable of running modern web applications
|
||||
- **Storage System:** File storage with sufficient capacity and performance for image files
|
||||
- **HTTPS/SSL Certificates:** Required for secure authentication and data transmission
|
||||
- **Email Service:** For password reset and notifications (if implemented)
|
||||
- **Browser APIs:** Modern browser support for drag-drop, clipboard, canvas rendering
|
||||
|
||||
### Internal Dependencies
|
||||
|
||||
- **User Authentication System:** Required before any board/image operations
|
||||
- **File Upload System:** Required before image manipulation features
|
||||
- **Image Processing:** Required for generating thumbnails and low-resolution versions
|
||||
- **State Management:** Required for canvas operations (undo/redo, auto-save)
|
||||
|
||||
## Open Issues
|
||||
|
||||
None - all clarifications resolved.
|
||||
|
||||
## Rollout Plan
|
||||
|
||||
1. **Development:** 12-16 week development cycle
|
||||
- Weeks 1-4: User authentication, board management, basic image upload
|
||||
- Weeks 5-8: Canvas operations, image positioning, transformations
|
||||
- Weeks 9-12: Advanced features (groups, command palette, export)
|
||||
- Weeks 13-16: Polish, adaptive quality, performance optimization
|
||||
|
||||
2. **Testing:** 2-week QA cycle
|
||||
- Functional testing of all 18 requirements
|
||||
- Cross-browser compatibility testing
|
||||
- Performance benchmarking under load
|
||||
- Accessibility audit
|
||||
|
||||
3. **Staging:** 1-week validation period
|
||||
- Deploy to staging environment with Nix
|
||||
- Internal team dogfooding (create real reference boards)
|
||||
- Security audit and penetration testing
|
||||
- Performance monitoring and optimization
|
||||
|
||||
4. **Production:** Phased rollout
|
||||
- Week 1: Closed beta (50 invited users)
|
||||
- Week 2-3: Open beta (public access, feedback collection)
|
||||
- Week 4: General availability release
|
||||
- Post-launch: Monitor error rates, performance metrics, user feedback
|
||||
|
||||
5. **Monitoring:** Key metrics to watch
|
||||
- Application error rate (<0.1% target)
|
||||
- Average page load time (<3s target)
|
||||
- API response times (<200ms p95 target)
|
||||
- Upload success rate (>99% target)
|
||||
- User engagement (boards created, images uploaded)
|
||||
- Browser/device distribution
|
||||
|
||||
## Appendix
|
||||
|
||||
### References
|
||||
|
||||
- **PureRef:** Desktop application providing inspiration for feature set (https://www.pureref.com/)
|
||||
- **WCAG 2.1 Guidelines:** Web Content Accessibility Guidelines for accessibility compliance
|
||||
- **Nix Package Manager:** For reproducible deployment (https://nixos.org/)
|
||||
|
||||
### Terminology
|
||||
|
||||
- **Board:** A canvas containing positioned reference images (also called "reference board" or "mood board")
|
||||
- **Canvas:** Infinite 2D workspace where images are positioned
|
||||
- **Focus Mode:** Full-screen view of a single image, hiding all others
|
||||
- **Group:** Collection of images that move together, with shared annotation
|
||||
- **Non-Destructive Editing:** Image modifications that don't alter the original file
|
||||
- **Z-Order:** Stacking order of overlapping images (which appears in front)
|
||||
- **Adaptive Quality:** Serving different image resolutions based on connection speed
|
||||
|
||||
### Change Log
|
||||
|
||||
| Version | Date | Author | Changes |
|
||||
|---------|------------|--------------|----------------------------|
|
||||
| 1.0.0 | 2025-11-02 | Project Team | Initial specification |
|
||||
Reference in New Issue
Block a user