geek-calc/specs/001-build-a-single/plan.md

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:

• Phase 0: Research complete (/plan command)
• Phase 1: Design complete (/plan command)
• 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:

• Initial Constitution Check: PASS
• Post-Design Constitution Check: PASS
• All NEEDS CLARIFICATION resolved
• Complexity deviations documented

---

Based on Constitution v2.0.0 - See /memory/constitution.md