snowprint/geek-calc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init geek calc
Some checks failed
Deploy to GitHub Pages / build-and-deploy (push) Has been cancelled
Details

Browse Source
This commit is contained in:
snowprint
2025-10-04 10:53:41 +08:00
commit 54f427ea21
45 changed files with 4878 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
specs/001-build-a-single/contracts/calculator-contract.md Normal file
View File

@@ -0,0 +1,76 @@
# Calculator Module Interface Contract
## Purpose
Defines the interface for the core calculator functionality module that will handle all mathematical operations.
## Interface Definition
### Core Calculator API
```
interface Calculator {
// Evaluate an arithmetic expression in standard notation
evaluate(expression: string): number | Error
// Add two numbers
add(a: number, b: number): number
// Subtract two numbers
subtract(a: number, b: number): number
// Multiply two numbers
multiply(a: number, b: number): number
// Divide two numbers (handles division by zero)
divide(a: number, b: number): number | Error
// Handle percentage operations
percentage(value: number, percent: number): number
// Toggle sign of a number
toggleSign(value: number): number
// Clear the current calculation
clear(): void
// Get current display value
getCurrentDisplay(): string
}
```
### RPN Calculator API
```
interface RPNCalculator {
// Push a number onto the stack
push(value: number): void
// Pop a number from the stack
pop(): number | undefined
// Perform an operation on stack values
operate(operator: string): number | Error
// Clear the entire stack
clear(): void
// Get current stack state
getStack(): number[]
// Execute RPN expression (e.g., "3 4 +")
evaluate(rpnExpression: string): number | Error
}
```
### Validation Requirements
- All operations must return valid numbers or appropriate error objects
- Division by zero must return an Error object
- Expression syntax errors must return Error objects
- Operations must respect JavaScript numeric limits (will return Infinity if exceeded)
### Performance Requirements
- All operations must complete within 100ms
- Evaluation should be efficient to maintain responsive UI
### Error Handling
- Invalid operations return Error objects with descriptive messages
- Overflow conditions return Infinity values
- Underflow conditions return 0 values

45
specs/001-build-a-single/data-model.md Normal file
View File

@@ -0,0 +1,45 @@
# Data Model: Geek Calculator
## Entities
### Calculation Expression
- **Representation**: String containing numbers, operators (+, -, ×, ÷), parentheses, percentage, +/- signs
- **Validation**: Must follow valid mathematical expression syntax rules
- **State transitions**: In-progress expression → evaluated expression → stored in history
### Calculation Result
- **Representation**: Number (JavaScript number type, may be Infinity or finite value)
- **Validation**: Must be a numeric result from evaluation
- **State transitions**: Calculated from expression → displayed → stored in history
### RPN Stack
- **Representation**: Array of numbers representing operands in Reverse Polish Notation
- **Operations**: Push, pop, peek, clear, size
- **Validation**: Elements must be valid numbers
- **State transitions**: Empty → populated with operands → modified through RPN operations
### Calculation History Entry
- **Fields**:
- expression (string): The original input expression
- result (number): The calculated result
- timestamp (Date): When the calculation was completed
- id (string): Unique identifier for recall
- **Validation**: Expression and result must be valid
- **State transitions**: New entry → stored → accessed → potentially deleted when limit reached
### Application Settings
- **Fields**:
- theme (string): 'dark' or other theme options
- mode (string): 'standard' or 'rpn' for calculation mode
- historyLimit (number): Maximum number of history entries to store
- **Validation**: Values must be from predefined sets
- **State transitions**: Default settings → user modified → saved to localStorage
### User Input State
- **Fields**:
- currentValue (string): The current value being entered
- operator (string): The current operator in use
- previousValue (number): The previous operand
- calculationPending (boolean): Whether a calculation is ready to execute
- **Validation**: Values must be consistent with calculator state
- **State transitions**: Initial state → value entry → operator selection → result calculation

198
specs/001-build-a-single/plan.md Normal file
View File

@@ -0,0 +1,198 @@
# Implementation Plan: Geek Calculator
**Branch**: `001-build-a-single` | **Date**: 2025-10-03 | **Spec**: /Users/snowprint/workspace/spec-lab/geek-calc/specs/001-build-a-single/spec.md
**Input**: Feature specification from `/specs/001-build-a-single/spec.md`
## Execution Flow (/plan command scope)
```
1. Load feature spec from Input path
→ If not found: ERROR "No feature spec at {path}"
2. Fill Technical Context (scan for NEEDS CLARIFICATION)
→ Detect Project Type from file system structure or context (web=frontend+backend, mobile=app+api)
→ Set Structure Decision based on project type
3. Fill the Constitution Check section based on the content of the constitution document.
4. Evaluate Constitution Check section below
→ If violations exist: Document in Complexity Tracking
→ If no justification possible: ERROR "Simplify approach first"
→ Update Progress Tracking: Initial Constitution Check
5. Execute Phase 0 → research.md
→ If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
6. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, `GEMINI.md` for Gemini CLI, `QWEN.md` for Qwen Code, or `AGENTS.md` for all other agents).
7. Re-evaluate Constitution Check section
→ If new violations: Refactor design, return to Phase 1
→ Update Progress Tracking: Post-Design Constitution Check
8. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
9. STOP - Ready for /tasks command
```
**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
- Phase 2: /tasks command creates tasks.md
- Phase 3-4: Implementation execution (manual or via tools)
## Summary
Build a single-file, offline-capable "Geek Calculator" that opens as index.html with no build step and no external CDN. The calculator will support basic arithmetic (+ − × ÷), parentheses, percentages, +/- toggle, and power-user features like RPN mode toggle, keyboard-first operation, command palette ("@"), and history with re-run. The UI features a "geek vibe" with dark terminal theme, monospace font, ASCII banner, blinking cursor, and Easter eggs. Based on research, the implementation will use vanilla JS modules with a simple state store and RPN stack class.
## Technical Context
**Language/Version**: HTML5, CSS3, JavaScript ES6+ (vanilla, no build step)
**Primary Dependencies**: None (pure HTML/CSS/JS, zero dependencies as per constitution)
**Storage**: LocalStorage for calculation history; Service Workers for offline capability
**Testing**: Tiny test runner (uTest-like) in /tests for unit tests of core math + RPN stack
**Target Platform**: Web browser (all modern browsers)
**Project Type**: Single-page application
**Performance Goals**: <50KB total payload, operations within 100ms, Lighthouse scores ≥95
**Constraints**: <50KB total payload; works fully offline; keyboard-first operation; ARIA roles, high-contrast
**Scale/Scope**: Single calculator application with basic and RPN modes
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
Based on the constitution:
- Maintainability: Code will be structured with clear modules (calculator core, RPN engine, UI, state management)
- Zero Dependencies: Using native HTML/CSS/JavaScript only, no external libraries
- Performance: Targeting <50KB total size with efficient algorithms
- Testable Design: TDD approach with unit tests for core math and RPN stack
- Offline Capability: Service worker for full offline functionality
- Keyboard Accessibility: Full keyboard navigation with ARIA roles and high-contrast support
## Project Structure
### Documentation (this feature)
```
specs/001-build-a-single/
├── plan.md # This file (/plan command output)
├── research.md # Phase 0 output (/plan command)
├── data-model.md # Phase 1 output (/plan command)
├── quickstart.md # Phase 1 output (/plan command)
├── contracts/ # Phase 1 output (/plan command)
└── tasks.md # Phase 2 output (/tasks command - NOT created by /plan)
```
### Source Code (repository root)
```
index.html # Main HTML file with embedded CSS/JS or linked files
styles.css # All styles including dark theme, ASCII art, responsive design
app.js # Main application logic with modules for calculator, RPN, UI, state
service-worker.js # Service worker for offline functionality
manifest.webmanifest # Web app manifest for PWA features
README.md # Project documentation
tests/
├── unit/ # Unit tests for core functionality
│ ├── math.test.js # Tests for basic arithmetic operations
│ ├── rpn.test.js # Tests for RPN stack operations
│ └── history.test.js # Tests for calculation history
├── integration/ # Integration tests
│ └── ui.test.js # Tests for UI interactions
└── index.html # HTML to run tests in browser environment
```
**Structure Decision**: Single-page application in root directory with separate test directory. The app will be structured as modules: calculator core module for operations, RPN module for reverse polish notation, UI module for DOM interactions, and state module for data management. All code will follow vanilla JavaScript with ES6 modules to maintain zero dependencies and optimal performance.
## Phase 0: Outline & Research
1. **Extract unknowns from Technical Context** above:
- For each NEEDS CLARIFICATION → research task
- For each dependency → best practices task
- For each integration → patterns task
2. **Generate and dispatch research agents**:
```
For each unknown in Technical Context:
Task: "Research {unknown} for {feature context}"
For each technology choice:
Task: "Find best practices for {tech} in {domain}"
```
3. **Consolidate findings** in `research.md` using format:
- Decision: [what was chosen]
- Rationale: [why chosen]
- Alternatives considered: [what else evaluated]
**Output**: research.md with all NEEDS CLARIFICATION resolved
## Phase 1: Design & Contracts
*Prerequisites: research.md complete*
1. **Extract entities from feature spec** → `data-model.md`:
- Entity name, fields, relationships
- Validation rules from requirements
- State transitions if applicable
2. **Generate API contracts** from functional requirements:
- For each user action → endpoint
- Use standard REST/GraphQL patterns
- Output OpenAPI/GraphQL schema to `/contracts/`
3. **Generate contract tests** from contracts:
- One test file per endpoint
- Assert request/response schemas
- Tests must fail (no implementation yet)
4. **Extract test scenarios** from user stories:
- Each story → integration test scenario
- Quickstart test = story validation steps
5. **Update agent file incrementally** (O(1) operation):
- Run `.specify/scripts/bash/update-agent-context.sh qwen`
**IMPORTANT**: Execute it exactly as specified above. Do not add or remove any arguments.
- If exists: Add only NEW tech from current plan
- Preserve manual additions between markers
- Update recent changes (keep last 3)
- Keep under 150 lines for token efficiency
- Output to repository root
**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file
## Phase 2: Task Planning Approach
*This section describes what the /tasks command will do - DO NOT execute during /plan*
**Task Generation Strategy**:
- Load `.specify/templates/tasks-template.md` as base
- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
- Each contract → contract test task [P]
- Each entity → model creation task [P]
- Each user story → integration test task
- Implementation tasks to make tests pass
**Ordering Strategy**:
- TDD order: Tests before implementation
- Dependency order: Models before services before UI
- Mark [P] for parallel execution (independent files)
**Estimated Output**: 25-30 numbered, ordered tasks in tasks.md
**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
## Phase 3+: Future Implementation
*These phases are beyond the scope of the /plan command*
**Phase 3**: Task execution (/tasks command creates tasks.md)
**Phase 4**: Implementation (execute tasks.md following constitutional principles)
**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
## Complexity Tracking
*Fill ONLY if Constitution Check has violations that must be justified*
| 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] |
## Progress Tracking
*This checklist is updated during execution flow*
**Phase Status**:
- [x] Phase 0: Research complete (/plan command)
- [x] Phase 1: Design complete (/plan command)
- [x] Phase 2: Task planning complete (/plan command - describe approach only)
- [ ] Phase 3: Tasks generated (/tasks command)
- [ ] Phase 4: Implementation complete
- [ ] Phase 5: Validation passed
**Gate Status**:
- [x] Initial Constitution Check: PASS
- [x] Post-Design Constitution Check: PASS
- [x] All NEEDS CLARIFICATION resolved
- [ ] Complexity deviations documented
---
*Based on Constitution v2.0.0 - See `/memory/constitution.md`*

64
specs/001-build-a-single/quickstart.md Normal file
View File

@@ -0,0 +1,64 @@
# Quickstart: Geek Calculator
## Running the Calculator
1. Open `index.html` in any modern web browser
2. The calculator will load with a dark terminal-themed UI
3. Begin typing calculations or use mouse/touch to operate
## Basic Operations
- **Addition**: `5 + 3 =` → displays `8`
- **Subtraction**: `10 - 4 =` → displays `6`
- **Multiplication**: `6 * 7 =` → displays `42`
- **Division**: `15 / 3 =` → displays `5`
- **Parentheses**: `(2 + 3) * 4 =` → displays `20`
- **Percentage**: `100 + 10% =` → displays `110`
- **Sign Toggle**: Enter number then press `±` or `+/-` button
## RPN Mode
1. Toggle RPN mode using the RPN button
2. Enter numbers followed by operators
3. Example: To calculate `4 + 6`: `4 ENTER 6 +`
4. Use `ENTER` to push numbers onto the RPN stack
5. Available operations: `+`, `-`, `*`, `/`
## Keyboard Controls
- **Numbers**: 0-9 keys
- **Operators**: `+`, `-`, `*`, `/` keys
- **Equals**: `=` or `Enter` key
- **Clear**: `Escape` or `C` key
- **All Clear**: `Shift + C` or `Double Escape`
- **Decimal Point**: `.` key
- **Backspace**: `Backspace` key
- **RPN Enter**: `Enter` key in RPN mode
- **Toggle RPN**: `R` key
- **Command Palette**: `@` key
- **History**: `↑` and `↓` arrow keys
- **Help/Shortcuts**: `?` key
## Command Palette
- Press `@` to open the command palette
- Type commands like "clear", "history", "theme", etc.
- Provides quick access to calculator functions
## History Feature
- Previous calculations appear in history panel
- Use `↑` and `↓` arrow keys to navigate
- Click on history items to re-run calculations
- Limited to 50 most recent entries
## Accessibility Features
- Full keyboard navigation
- ARIA labels on all controls
- High contrast mode
- Screen reader compatible
- Visible focus indicators
## Troubleshooting
- If you see "Error", check your expression syntax
- For division by zero, the result will show "Infinity"
- If calculator doesn't respond, try clearing with `Escape`
- For offline use, ensure service worker is enabled in your browser
## Testing
- Unit tests for core math operations: Run `tests/index.html` in browser
- Tests cover basic arithmetic, RPN operations, and error conditions

54
specs/001-build-a-single/research.md Normal file
View File

@@ -0,0 +1,54 @@
# Research: Geek Calculator Implementation
## Key Unknowns Identified
- Error handling for invalid expressions
- Behavior for calculations that exceed numerical limits
- Limits to calculation history storage
- Specific percentage operation behaviors
- Response to inputs exceeding v1 scope
## Research Findings
### Decision: Error Handling for Invalid Expressions
**Rationale**: For invalid expressions like "5 // 0" or "5 + * 3", the calculator will display "Error" in the display area and require clearing before continuing.
**Alternatives considered**: Alternative was to show specific error messages (e.g., "Division by zero", "Invalid syntax") but the simpler "Error" approach maintains the minimal UI aesthetic.
### Decision: Overflow and Large Number Handling
**Rationale**: For calculations that exceed JavaScript's numerical limits, the calculator will show "Infinity" or "-Infinity" for overflow, and "0" for underflow.
**Alternatives considered**: Could have implemented custom large number handling but this would increase code size beyond 50KB target.
### Decision: Calculation History Storage
**Rationale**: History will be stored in localStorage with a limit of 50 entries. When limit is reached, oldest entries are removed.
**Alternatives considered**: Unlimited history was considered but would risk localStorage quota exhaustion and performance degradation.
### Decision: Percentage Operation Behavior
**Rationale**: Percentage operations will follow standard calculator behavior: "100 + 10%" = 110, "50%" = 0.5, "100 * 5%" = 5.
**Alternatives considered**: Scientific calculator percentage behavior (like "100 + 10%" = 100.1) was considered but standard behavior is more familiar to users.
### Decision: Handling Out-of-Scope Functions
**Rationale**: For inputs that exceed v1 scope (like scientific functions), the calculator will display "Error" to maintain focus on core features.
**Alternatives considered**: Ignoring invalid inputs silently was considered but providing feedback is better for user experience.
## Technology Decisions
### Decision: Vanilla JS Modules Architecture
**Rationale**: Using ES6 modules will provide clean separation of concerns while maintaining zero dependencies as required by the constitution.
**Alternatives considered**: Single file vs. modular approach; modular was chosen for maintainability despite the single-file requirement for the final deliverable.
### Decision: RPN Implementation
**Rationale**: Implementing RPN with a stack data structure will provide the required functionality while keeping the code efficient.
**Alternatives considered**: String-based RPN processing vs. stack-based; stack-based was chosen for better performance and clearer code.
### Decision: Testing Framework
**Rationale**: A minimal custom test harness will be implemented to avoid external dependencies while providing necessary test coverage.
**Alternatives considered**: External testing libraries like Jest were considered but rejected to maintain zero dependencies requirement.
### Decision: Service Worker Strategy
**Rationale**: A cache-first service worker will ensure full offline functionality as required by the constitution.
**Alternatives considered**: Network-first or stale-while-revalidate strategies were considered but cache-first better ensures offline capability.
## Accessibility Implementation
### Decision: ARIA Roles and Keyboard Navigation
**Rationale**: Using semantic HTML with appropriate ARIA roles and comprehensive keyboard event handling will meet WCAG requirements.
**Alternatives considered**: Custom accessibility solutions vs. standard HTML patterns; standard patterns were chosen for better compatibility and maintainability.

135
specs/001-build-a-single/spec.md Normal file
View File

@@ -0,0 +1,135 @@
# Feature Specification: Geek Calculator
**Feature Branch**: `001-build-a-single`
**Created**: 2025-10-03
**Status**: Draft
**Input**: User description: "Build a single-file, offline-capable "Geek Calculator" that opens as index.html with no build step and no external CDN. User goals: - Perform basic arithmetic (+ − × ÷), parentheses, percentages, +/- toggle. - Power-user features: RPN mode toggle, keyboard-first operation, command palette (\"@\"), and history with re-run. - "Geek vibe" UI: dark terminal theme, monospace font, ASCII banner, blinking cursor in input, small Easter eggs. Constraints: - Pure HTML/CSS/JS, no frameworks, total payload < 50KB. - Works fully offline; no network requests. - A11y: full keyboard navigation, ARIA roles, high-contrast. Non-goals: - Scientific/trig functions, i18n for v1. Success metrics: - Lighthouse Perf/Best Practices/SEO/Accessibility ≥ 95 locally. - 100% keyboard coverage for primary flows. - Unit tests for core math + RPN stack."
## Execution Flow (main)
```
1. Parse user description from Input
→ If empty: ERROR "No feature description provided"
2. Extract key concepts from description
→ Identify: actors, actions, data, constraints
3. For each unclear aspect:
→ Mark with [NEEDS CLARIFICATION: specific question]
4. Fill User Scenarios & Testing section
→ If no clear user flow: ERROR "Cannot determine user scenarios"
5. Generate Functional Requirements
→ Each requirement must be testable
→ Mark ambiguous requirements
6. Identify Key Entities (if data involved)
7. Run Review Checklist
→ If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
→ If implementation details found: ERROR "Remove tech details"
8. Return: SUCCESS (spec ready for planning)
```
---
## ⚡ Quick Guidelines
- ✅ Focus on WHAT users need and WHY
- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
- 👥 Written for business stakeholders, not developers
### Section Requirements
- **Mandatory sections**: Must be completed for every feature
- **Optional sections**: Include only when relevant to the feature
- When a section doesn't apply, remove it entirely (don't leave as "N/A")
### For AI Generation
When creating this spec from a user prompt:
1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
2. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
3. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
4. **Common underspecified areas**:
- User types and permissions
- Data retention/deletion policies
- Performance targets and scale
- Error handling behaviors
- Integration requirements
- Security/compliance needs
---
## User Scenarios & Testing *(mandatory)*
### Primary User Story
As a user, I want to open the Geek Calculator and perform basic arithmetic operations (addition, subtraction, multiplication, division) with immediate results, so that I can quickly calculate mathematical expressions without needing an internet connection or installing additional software.
### Acceptance Scenarios
1. **Given** I am on the Geek Calculator page with a dark terminal-themed UI and monospace font, **When** I input a basic arithmetic expression like "5 + 3 * 2" using the keyboard, **Then** I see the correct result (11) displayed and formatted with the "geek vibe" aesthetic.
2. **Given** I want to perform calculations without a mouse, **When** I use keyboard shortcuts to enter numbers and operations, **Then** the calculator responds to my input and shows results instantly with keyboard-first navigation.
3. **Given** I have performed several calculations, **When** I access the history feature, **Then** I can see my previous calculations and re-run them to reproduce the same results.
4. **Given** I am a power user familiar with RPN calculators, **When** I toggle the RPN mode and use postfix notation for calculations, **Then** the calculator correctly processes expressions in RPN format rather than standard infix notation.
### Edge Cases
- What happens when I input an invalid expression like "5 // 0" or "5 + * 3"? [NEEDS CLARIFICATION: What error handling behavior is expected for invalid expressions?]
- How does the system handle very large numbers or calculations that result in overflow? [NEEDS CLARIFICATION: What is the expected behavior for calculations that exceed numerical limits?]
- What happens when the calculation history becomes very long - is there a limit or does it scroll? [NEEDS CLARIFICATION: Are there limits to calculation history storage?]
- How does the calculator handle the percentage operation in different contexts (e.g., "50% of 100" vs "100 + 50%")? [NEEDS CLARIFICATION: What are the specific percentage operation behaviors expected?]
- What happens if someone tries to use scientific functions (non-goal) - does it show an error or ignore? [NEEDS CLARIFICATION: How should the system respond to inputs that exceed the v1 scope?]
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: System MUST perform basic arithmetic operations (+, -, ×, ÷) with correct order of operations precedence
- **FR-002**: System MUST support parentheses for expression grouping and control of evaluation order
- **FR-003**: Users MUST be able to use percentage operations in calculations
- **FR-004**: Users MUST be able to toggle the sign of numbers using a +/- feature
- **FR-005**: System MUST provide an RPN mode toggle that switches between standard and Reverse Polish Notation calculation methods
- **FR-006**: System MUST support keyboard-first operation with all functions accessible via keyboard shortcuts
- **FR-007**: System MUST provide a command palette feature accessible via the "@" key
- **FR-008**: System MUST maintain a calculation history that users can review and re-run
- **FR-009**: System MUST provide a "geek vibe" UI with dark terminal theme, monospace font, and ASCII banner
- **FR-010**: System MUST display a blinking cursor in the input field for terminal-like experience
- **FR-011**: System MUST include small Easter eggs for enhanced user experience
- **FR-012**: System MUST work fully offline with no network requests required
- **FR-013**: System MUST store calculation history locally for offline access
- **FR-014**: System MUST provide full keyboard navigation for accessibility compliance
- **FR-015**: System MUST implement ARIA roles for accessibility compliance
- **FR-016**: System MUST support high-contrast mode for accessibility
- **FR-017**: System MUST maintain total payload under 50KB
- **FR-018**: System MUST provide unit tests for core math operations
- **FR-019**: System MUST provide unit tests for RPN stack operations
### Key Entities
- **Calculation Expression**: Represents the mathematical expression being entered or evaluated, including operands, operators, and parentheses grouping
- **Calculation Result**: The numerical result of a completed calculation, with formatting that matches the "geek vibe" aesthetic
- **RPN Stack**: A data structure used in Reverse Polish Notation mode to manage operands during calculations
- **Calculation History Entry**: A record of previous calculations, including the expression, result, and timestamp, that can be recalled and re-executed
- **Application Settings**: Configuration options for the calculator including theme preferences, RPN vs standard mode, keyboard shortcuts, and accessibility settings
- **User Input**: The current expression being entered by the user, which may be in progress or ready for evaluation
---
## Review & Acceptance Checklist
*GATE: Automated checks run during main() execution*
### Content Quality
- [ ] 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
### Requirement Completeness
- [ ] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous
- [x] Success criteria are measurable
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified
---
## Execution Status
*Updated by main() during processing*
- [x] User description parsed
- [x] Key concepts extracted
- [x] Ambiguities marked
- [x] User scenarios defined
- [x] Requirements generated
- [x] Entities identified
- [ ] Review checklist passed
---

133
specs/001-build-a-single/tasks.md Normal file
View File

@@ -0,0 +1,133 @@
# Tasks: Geek Calculator
**Input**: Design documents from `/specs/001-build-a-single/`
**Prerequisites**: plan.md (required), research.md, data-model.md, contracts/
## Execution Flow (main)
```
1. Load plan.md from feature directory
→ If not found: ERROR "No implementation plan found"
→ Extract: tech stack, libraries, structure
2. Load optional design documents:
→ data-model.md: Extract entities → model tasks
→ contracts/: Each file → contract test task
→ research.md: Extract decisions → setup tasks
3. Generate tasks by category:
→ Setup: project init, dependencies, linting
→ Tests: contract tests, integration tests
→ Core: models, services, CLI commands
→ Integration: DB, middleware, logging
→ Polish: unit tests, performance, docs
4. Apply task rules:
→ Different files = mark [P] for parallel
→ Same file = sequential (no [P])
→ Tests before implementation (TDD)
5. Number tasks sequentially (T001, T002...)
6. Generate dependency graph
7. Create parallel execution examples
8. Validate task completeness:
→ All contracts have tests?
→ All entities have models?
→ All endpoints implemented?
9. Return: SUCCESS (tasks ready for execution)
```
## Format: `[ID] [P?] Description`
- **[P]**: Can run in parallel (different files, no dependencies)
- Include exact file paths in descriptions
## Path Conventions
- **Single project**: index.html, styles.css, app.js at repository root
- **Test files**: tests/unit/, tests/integration/ directories
## Phase 3.1: Setup
- [X] T001 Create project structure: index.html, styles.css, app.js, service-worker.js, manifest.webmanifest
- [X] T002 [P] Create test directory structure: tests/unit/, tests/integration/, tests/index.html
- [X] T003 [P] Create README.md with usage instructions
## Phase 3.2: Tests First (TDD) ⚠️ MUST COMPLETE BEFORE 3.3
**CRITICAL: These tests MUST be written and MUST FAIL before ANY implementation**
- [X] T004 [P] Contract test for Core Calculator API in tests/unit/calculator.test.js
- [X] T005 [P] Contract test for RPN Calculator API in tests/unit/rpn-calculator.test.js
- [X] T021 Unit tests for core math operations in tests/unit/math.test.js
- [X] T022 Unit tests for RPN stack operations in tests/unit/rpn.test.js
- [X] T016 Integration tests for user scenarios in tests/integration/ui.test.js
## Phase 3.3: Core Implementation (ONLY after tests are failing)
- [X] T006 [P] Calculator class implementation in calculator.js
- [X] T007 [P] RPN Calculator class implementation in rpn-calculator.js
- [X] T008 [P] State management class implementation in state.js
- [X] T009 [P] UI controller implementation in ui.js
- [X] T010 [P] Utility functions in utils.js
- [X] T015 [P] Custom test harness implementation in tests/test-harness.js
## Phase 3.4: Integration
- [X] T011 [P] Service worker implementation for offline functionality in service-worker.js
- [X] T012 Web app manifest for PWA features in manifest.webmanifest
- [X] T013 [P] Accessibility features (ARIA roles, keyboard navigation) in ui.js and index.html
- [X] T014 [P] History with localStorage implementation in state.js
- [X] T019 [P] Keyboard controls implementation in ui.js
- [X] T020 [P] Command palette feature implementation in ui.js
## Phase 3.5: Polish
- [X] T017 [P] Performance validation and size budget check script
- [X] T018 [P] CSS styling for dark theme, ASCII banner, and terminal aesthetic in styles.css
- [X] T023 [P] GitHub Pages deployment setup
- [X] T024 Size optimization to ensure <50KB payload
## Dependencies
- Setup (T001-T003) before everything
- Tests (T004-T005, T021-T022, T016) before implementation (T006-T010, T015)
- Core implementation (T006-T010, T015) before integration (T011-T014, T019-T020)
- Integration (T011-T014, T019-T020) before polish (T017-T018, T023-T024)
## Parallel Example
```
# Launch T004-T005, T021-T022 together:
Task: "Contract test for Core Calculator API in tests/unit/calculator.test.js"
Task: "Contract test for RPN Calculator API in tests/unit/rpn-calculator.test.js"
Task: "Unit tests for core math operations in tests/unit/math.test.js"
Task: "Unit tests for RPN stack operations in tests/unit/rpn.test.js"
# Launch T006-T010 together:
Task: "Calculator class implementation in calculator.js"
Task: "RPN Calculator class implementation in rpn-calculator.js"
Task: "State management class implementation in state.js"
Task: "UI controller implementation in ui.js"
Task: "Utility functions in utils.js"
```
## Notes
- [P] tasks = different files, no dependencies
- Verify tests fail before implementing
- Commit after each task
- Avoid: vague tasks, same file conflicts
## Task Generation Rules
*Applied during main() execution*
1. **From Contracts**:
- Each contract file → contract test task [P]
- Each endpoint → implementation task
2. **From Data Model**:
- Each entity → model creation task [P]
- Relationships → service layer tasks
3. **From User Stories**:
- Each story → integration test [P]
- Quickstart scenarios → validation tasks
4. **Ordering**:
- Setup → Tests → Models → Services → Endpoints → Polish
- Dependencies block parallel execution
## Validation Checklist
*GATE: Checked by main() before returning*
- [ ] All contracts have corresponding tests
- [ ] All entities have model tasks
- [ ] All tests come before implementation
- [ ] Parallel tasks truly independent
- [ ] Each task specifies exact file path
- [ ] No task modifies same file as another [P] task