john/svsmspcalc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

just being crazy honestly

Browse Source
This commit is contained in:
John OReilly
2026-03-18 17:38:22 -04:00
parent 4c53af96a9
commit de1e0c0847
30 changed files with 511 additions and 1242 deletions
Download Patch File Download Diff File Expand all files Collapse all files

359
CLAUDE.md
View File

@@ -1,248 +1,203 @@
# CLAUDE.md — SVS MSP Calculator
> Master instruction set for Claude Code. This is the SINGLE file to read on session start.
> It references deeper docs — do not duplicate them here.
---
## Project Identity
## What This Is
**App:** SVS MSP Calculator — a live quote/pricing calculator for SVS Managed Services.
**Used by:** Sales team, live on screen with prospects during discovery calls.
**Tech:** Vanilla HTML5 / CSS3 / JS (ES5-compatible). No frameworks, no npm, no build tools. Open `SVS-MSP-Calculator.html` in a browser — it runs.
**Status:** Alpha-ready, pushing to Beta.
**Tests:** 254 passing (`node tests/test-quote-engine.js`)
**Themes:** 3 — Dark (flagship), Light, Glass
**SVS MSP Calculator** — a live pricing and quote tool used by the sales team on screen during prospect calls.
HTML5 / CSS3 / JS. No frameworks, no build tools. Open `SVS-MSP-Calculator.html` in a browser — it runs.
For full architecture, file maps, DOM IDs, and pricing constants see `docs/QUICK-REF.md`.
For business logic and pricing rules see `docs/quote-rules.md`.
For the complete architecture brief see `docs/MASTER-SESSION-PROMPT.md`.
**Status:** Active development — current focus is GUI / UI improvement.
Quote logic and pricing engine are stable. Do not touch without explicit approval.
---
## Session Start Protocol
## How It Works
On every new conversation, execute in order:
### The Update Loop
1. **Read context** (parallel):
- `docs/SESSION-HANDOFF.md` — what happened last, what is next
- `docs/QUICK-REF.md` — file map, DOM IDs, pricing, danger zones
2. **Run baseline tests:** `node tests/test-quote-engine.js` — confirm 254/254 pass
3. **Ask the user** what they want to work on. Do not assume. Do not start changing things.
4. **Read task-specific docs only when needed:**
- `docs/quote-rules.md` — pricing or business logic work
- `docs/regression-checklist.md` — validation work
- `docs/MASTER-SESSION-PROMPT.md` — unfamiliar areas, full architecture
- `docs/DECISION-LOG.md` — check if a relevant decision was already made
- `docs/KNOWN-ISSUES.md` — check if the issue is already tracked
---
## Session End Protocol
Before ending any session:
1. **Run full test suite:** `node tests/test-quote-engine.js` — all 254 must pass
2. **Update `docs/SESSION-HANDOFF.md`** with:
- What was done (brief, specific)
- Files modified (table format)
- Test status (pass count)
- What is next (prioritized)
3. **Update `docs/CHECKPOINT.md`** if structural work was completed
4. **Update `docs/DECISION-LOG.md`** if any decisions were made
5. **Use `superpowers:finishing-a-development-branch`** for commit and cleanup
---
## Orchestration Engine — Superpowers
Use the **superpowers** plugin as the execution backbone for all non-trivial work.
### Workflow Selection
| Situation | Superpowers Skill to Use |
|-----------|--------------------------|
| Planning any feature or multi-step work | `superpowers:writing-plans` |
| Executing a plan with review gates | `superpowers:subagent-driven-development` |
| 2+ independent tasks (e.g., fix CSS in all 3 themes) | `superpowers:dispatching-parallel-agents` |
| Investigating a bug or failure | `superpowers:systematic-debugging` |
| Writing or modifying quote engine logic | `superpowers:test-driven-development` |
| Final checks before marking work done | `superpowers:verification-before-completion` |
| Committing, branch cleanup, merge prep | `superpowers:finishing-a-development-branch` |
| Visual brainstorming for design or UX | `superpowers:brainstorming` |
### Subagent-Driven Development Flow
For any plan with 2+ tasks, use `superpowers:subagent-driven-development`:
Every input change triggers this pipeline:
```
Per task:
1. Dispatch implementer subagent (with role-specific model — see below)
2. Spec compliance review (did it match requirements?)
3. Code quality review (is it well-built?)
4. Mark task complete
After all tasks:
Final code review → superpowers:finishing-a-development-branch
Input event → readFormState() → calculateQuote(state, pricing) → renderQuote(quote) → mobileSync()
```
---
`SVS-MSP-Calculator.js` orchestrates this via `update()`. The engine is a pure function — state in, quote out. Render writes to DOM. Mobile sync clones to the mobile panel. **Any change that touches this chain affects the entire app.**
## Agent Roles & Model Routing
### CSS Cascade
When dispatching subagents (via superpowers or directly), route to the right role and model.
### Frontend Coder — Opus (default)
**When:** JS logic, CSS changes, HTML structure, bug fixes, refactoring.
**How:** Surgical precision. Read the file first, make the minimal change.
**Post-change:** Run the full validation pipeline.
### UI/UX Designer — Opus + ui-ux-pro-max Skill
**When:** Design decisions — palettes, typography, spacing, layout, visual hierarchy, component styling.
**How:** Invoke the ui-ux-pro-max skill BEFORE implementation. Feed design system output to the implementer subagent.
**Sub-skills:** banner-design, brand, design-system, design, slides, ui-styling
**Constraint:** Translate all output to vanilla CSS — this project has no framework.
### Copywriter — Sonnet Model
**When:** ALL user-facing text — button labels, section descriptions, nudge messages, tooltip copy, sidebar labels, sales language, feature descriptions, comparison text, pitch bar copy.
**How:** Dispatch Agent with `model: "sonnet"`. Provide context about:
- The sales use case (live on calls with prospects)
- The specific UI element being written for
- The current text (if revising)
**Tone:** Confident, concise, client-facing. Not marketing fluff. This is a tool used live.
**Rule:** Copy is UX. Every label guides behavior. Every nudge drives a decision.
### Calculation Validator — Opus
**When:** After ANY change to `quote-engine.js`, `quote-pricing.js`, `package-prices-data.js`, or sidebar render values.
**How:**
1. Run `node tests/test-quote-engine.js` — all 254 must pass
2. Manually verify 2+ quote configs against the verification matrix in `docs/MASTER-SESSION-PROMPT.md` (Priority 4)
3. Cross-check sidebar display values against engine output
4. Verify admin fee floor/threshold logic at edge cases (0 users, 1 endpoint)
### QA / Regression Tester — Opus
**When:** After any visual, structural, or behavioral change.
**How:** Run the validation pipeline below. Use Playwright MCP for visual verification.
**Reference:** `docs/regression-checklist.md` for full manual QA procedures.
---
## Validation Pipeline
After every change, validate in order. Stop and fix at the first failure.
9 modular CSS files loaded via `SVS-MSP-Calculator.css` (master import):
```
1. TESTS node tests/test-quote-engine.js (254/254 must pass)
2. SYNTAX No console errors on fresh browser load
3. THEMES Playwright: verify Dark, Light, Glass all render correctly
4. MOBILE Playwright: verify at 375px — floating MRR pill, bottom sheet, sync
5. PRINT If CSS touched: verify print output is unaffected
6. PERSISTENCE If state/form touched: save → reload → verify all values restore
7. EXPORT If export touched: JSON export valid, version field present
tokens.css → base.css → layout.css → components.css → responsive.css
↕
light.css / glass.css (theme overrides)
↕
print.css
```
---
**Tokens are the source of truth.** 60+ semantic variables (`--ink`, `--paper`, `--accent`, `--surface-*`, `--print-*`). Changing a token ripples through all 3 themes, all components, and print output.
## Hard Constraints
Themes are pure CSS variable overrides on `:root` — no HTML changes, no JS logic. `theme-manager.js` toggles a class; the cascade does the rest.
These are inviolable. Every change must preserve them.
### Mobile Sync
| # | Constraint |
|---|-----------|
| 1 | **DOM IDs are a contract.** `mobile-sync.js` maps 100+ ID pairs (desktop ↔ `_m` suffix). Renaming breaks sync silently. |
| 2 | **Quote math is sacred.** Any `quote-engine.js` or `quote-pricing.js` change requires test validation. |
| 3 | **localStorage round-trip must work.** Key: `svs-msp-quote-v1`. Verify after form/state changes. |
| 4 | **All 3 themes must work.** Dark (flagship), Light, Glass. Token/component changes cascade to all. |
| 5 | **Mobile parity maintained.** Sidebar clone in mobile panel must stay in sync. Usable at 375px. |
| 6 | **Print/PDF tested after CSS changes.** Print CSS is sensitive to component class changes. |
| 7 | **No framework or build-tool migration.** Vanilla JS by design. |
| 8 | **No broad rewrites.** Surgical, approved changes only. |
| 9 | **Read before editing.** Always inspect current code before making changes. |
| 10 | **Ask before assuming.** When requirements are ambiguous, ask the user. |
`mobile-sync.js` physically clones the sidebar DOM into a bottom-sheet panel (`#mobileQuotePanel`) and appends `_m` to every cloned ID. It then syncs content, classes, styles, and checkbox states from desktop → mobile after each `update()`.
**If you add a new sidebar element, mobile-sync must know about it or mobile breaks silently.**
### The Sidebar Is the Product
The right column (`.sidebar`) is what the prospect stares at during the call. Hero numbers: MRR, per-user cost, annual total. Every UI change should be evaluated from: **does this make the sidebar clearer?**
### Print / PDF
`SVS-MSP-Calculator-print.css` is a parallel rendering target with its own token set (`--print-*`). At `@media print` it hides all interactive controls, forces sections open, and outputs a clean A4 document. Print is not an afterthought — it's a sales deliverable.
### localStorage
3 keys: quote state (full form data as JSON), quote reference ID, theme preference. Save/load via `quote-persistence.js`. `Ctrl+S` / `Ctrl+L` shortcuts.
---
## Regression Hotspots
## Invariants
| Area | Risk | Why |
|------|------|-----|
| `quote-engine.js` math | Critical | Wrong quotes in real sales calls |
| localStorage round-trip | High | Silent failures lose configured quotes |
| Mobile sync ID map | High | 100+ pairs desync silently if IDs change |
| Print/PDF CSS | Medium | Separate cascade, sensitive to class changes |
| Theme switching | Medium | All 3 themes affected by token changes |
| `update()` call chain | Medium | Side effects cascade: calc → render → sidebar → nudges → summaries → save |
Things that must be true before and after every session. Each has a verification step.
| Invariant | Verify |
|-----------|--------|
| All unit tests pass | `node tests/test-quote-engine.js` — 254/254 |
| All 3 themes render correctly | Playwright-check Dark, Light, Glass after any CSS change |
| DOM IDs unchanged | Never rename — `mobile-sync.js` maps 100+ desktop↔mobile pairs silently |
| localStorage round-trip | Save → reload → confirm all values restore |
| Print output clean | Verify after any CSS change — print has its own cascade |
| Mobile panel matches sidebar | Check mobile bottom-sheet after any sidebar change |
---
## Installed Plugins & Skills
## Working Rules
### Plugins (use when applicable)
How Claude behaves while working. Not testable — behavioral.
| Plugin | When to Use |
|--------|-------------|
| `superpowers` | Orchestration: planning, agents, reviews, TDD, debugging, branch mgmt |
| `frontend-design` | Frontend design patterns and implementation |
| `code-review` | Structured code review |
| `code-simplifier` | Simplification and cleanup passes |
| `playwright` | Browser automation, visual verification, screenshot comparison |
| `claude-md-management` | Maintaining this CLAUDE.md file |
| `skill-creator` | Creating new custom skills for this project |
### Skills (ui-ux-pro-max)
| Skill | When to Use |
|-------|-------------|
| `ui-ux-pro-max` | Main design intelligence — styles, colors, typography, UX rules |
| `design-system` | Token architecture, component specs |
| `brand` | Voice, visual identity, messaging consistency |
| `ui-styling` | Component styling (translate to vanilla CSS) |
| `design` | Logo, icons, visual assets |
| `banner-design` | Marketing banners and heroes |
| `slides` | HTML presentations |
**Search command** (requires Python 3):
```bash
python3 .claude/skills/ui-ux-pro-max/src/ui-ux-pro-max/scripts/search.py "<query>" --domain <domain>
```
Domains: `style`, `color`, `typography`, `product`, `landing`, `chart`, `ux`
1. **Read before editing** — always inspect current code first
2. **Quote engine is locked** — no changes to `quote-engine.js`, `quote-pricing.js`, or `package-prices-data.js` without explicit approval
3. **No frameworks, no build tools** — vanilla JS by design
4. **No broad rewrites** — surgical, approved changes only
5. **Ask before assuming** — when requirements are unclear, ask
---
## Commit Protocol
## Do Not Touch
- One concern per commit. Do not bundle unrelated changes.
- Message format: `<area>: <what> — <why>`
- Examples: `css: fix glass theme sidebar blur — backdrop-filter not applying at 900px`
- Examples: `engine: correct admin fee at zero users — floor logic was bypassed`
- Do not commit temp files or `.bak-focusmode` files.
- Run validation pipeline before committing.
- Use `superpowers:finishing-a-development-branch` for final commit + cleanup.
| Thing | Why |
|-------|-----|
| `fontawesomekit/` | Huge vendor directory. Reference known FA icons by name when needed — never scan this directory |
| `pre-alpha/` | Legacy/experimental files. Ignore unless explicitly asked |
| Quote engine files | `quote-engine.js`, `quote-pricing.js`, `package-prices-data.js` — stable, tested, locked |
---
## Design Principles
1. **Sales clarity over visual novelty.** Prospects must read numbers at a glance.
2. **Trust through polish.** Misaligned inputs erode prospect confidence.
3. **Progressive disclosure.** Lead with MRR total. Detail unfolds on demand.
4. **Feedback immediacy.** Every input change updates sidebar within 1 frame.
5. **Dark theme is the flagship.** Light and Glass must meet the same bar.
6. **The sidebar is the hero.** Design it like a financial summary, not a DOM dump.
7. **Copy is UX.** Labels, nudges, and button text are design decisions.
8. **Mobile is first-class.** A sales rep on a tablet must run a full quote.
1. **Sales clarity over visual novelty** — prospects read numbers at a glance
2. **The sidebar is the hero** — treat it like a financial summary
3. **Dark theme is flagship** — Light and Glass must meet the same bar
4. **Copy is UX** — every label and nudge is a design decision
5. **Mobile is first-class** — a sales rep on a tablet must run a full quote
---
## File Reference
## Architecture
See `docs/QUICK-REF.md` for the complete file map, DOM IDs, and pricing constants.
### HTML Structure
| Category | Key Files |
|----------|-----------|
| Orchestration | `SVS-MSP-Calculator.js`, `SVS-MSP-Calculator.html` |
| Quote Engine | `quote-engine.js`, `quote-pricing.js`, `package-prices-data.js` |
| Rendering | `quote-render.js`, `mobile-sync.js`, `theme-manager.js` |
| Persistence | `quote-persistence.js`, `quote-export.js`, `quote-import.js` |
| CSS Tokens | `SVS-MSP-Calculator-tokens.css` (source of truth for design tokens) |
| CSS Themes | `*-light.css`, `*-glass.css` |
| CSS Layout | `*-layout.css`, `*-components.css`, `*-responsive.css`, `*-print.css` |
| Tests | `tests/test-quote-engine.js` (254 tests, zero deps) |
| Docs | `docs/QUICK-REF.md`, `docs/SESSION-HANDOFF.md`, `docs/MASTER-SESSION-PROMPT.md`, `docs/quote-rules.md`, `docs/DECISION-LOG.md`, `docs/KNOWN-ISSUES.md` |
6 collapsible sections in the main column, sticky sidebar in the right column:
| Section | ID | Content |
|---------|----|---------|
| I — Site Management | `#sec-01` | Admin fee, floor $650 |
| II — User Package | `#sec-02` | Per-user pricing, M365/BYOL |
| III — Endpoint Package | `#sec-03` | Device count |
| IV — Server Management | `#sec-04` | Server count |
| V — Zero Trust HaaS | `#sec-05` | Seats, routers |
| VI — VoIP UCaaS | `#sec-06` | Seats, tiers |
**Layout:** CSS Grid — `3fr | 2fr` (main | sidebar). Collapses to single column at 1100px. Mobile pill + bottom-sheet panel below 1100px.
**Z-index stack:** 400 (modals) → 300 (mobile panel) → 200 (mobile pill) → 100 (top bar) → 10 (sidebar)
### JS Files
| File | Role |
|------|------|
| `SVS-MSP-Calculator.js` | Orchestrator — `update()` loop, form reading, event wiring |
| `quote-engine.js` | Pure calculation — `calculateQuote(state, pricing)` → quote object |
| `quote-pricing.js` | Pricing defaults (32 rates/fees) — `SVSQuotePricing.getSnapshot()` |
| `package-prices-data.js` | External pricing data (optional override) |
| `quote-render.js` | Writes calculated quote to DOM elements |
| `quote-persistence.js` | localStorage save/load + `Ctrl+S`/`Ctrl+L` |
| `quote-export.js` | Printable/exportable quote HTML generation |
| `quote-import.js` | Load saved quotes from JSON |
| `mobile-sync.js` | Clones sidebar → mobile panel, syncs on every `update()` |
| `theme-manager.js` | Dark/Light/Glass toggle, persists preference |
### CSS Files
| File | Role |
|------|------|
| `SVS-MSP-Calculator.css` | Master import — loads all modules |
| `*-tokens.css` | Design tokens — 60+ semantic variables, source of truth |
| `*-base.css` | Body, top bar, theme toggle |
| `*-layout.css` | Grid, page layout, sidebar, modals |
| `*-components.css` | Section cards, buttons, icons, form controls |
| `*-responsive.css` | Media queries — 1100px and 600px breakpoints |
| `*-light.css` | Light theme — `:root` variable overrides only |
| `*-glass.css` | Glass theme — gradients, blur, `color-scheme: dark` |
| `*-print.css` | Print/PDF — own token set, aggressive cleanup, A4-ready |
### Tests
254 tests across 47 groups. Custom minimal harness (no framework). Covers:
pricing, discounts, add-ons, VoIP tiers, HST, contract terms, edge cases, admin fees.
Run: `node tests/test-quote-engine.js`
---
## Tools & When to Use Them
| Tool | Use when |
|------|----------|
| **Playwright** | Visual verification — viewing HTML/CSS across themes |
| **ui-ux-pro-max** | Any design decision — invoke before touching CSS |
| **superpowers** | Planning, parallel agents, debugging, TDD, branch/commit |
| **frontend-design** | Building or modifying UI components |
| **code-review** | Before marking any task complete |
| **code-simplifier** | After implementation — clean up without changing behavior |
| **context-mode** | Large output (>20 lines) — routes through sandbox to protect context window. Use `ctx_batch_execute` for multi-command research, `ctx_search` for follow-up queries, `ctx_execute`/`ctx_execute_file` for data processing, `ctx_fetch_and_index` for URL fetching |
| **accesslint** | Accessibility and colour contrast checking. Use `contrast-checker` for WCAG ratio checks on hex pairs, `use-of-color` to flag colour-only indicators, `reviewer` for full component audits. Minimum standard: WCAG 2.1 AA (4.5:1 normal text, 3:1 large text). Suggest replacement hex values on failure. |
---
## Session Start
1. Read `docs/SESSION-HANDOFF.md` — current state of the project
2. Run `node tests/test-quote-engine.js` — confirm 254/254
3. Ask the user what they want — do not assume, do not start changing things
Read other docs only when the task requires them:
- `docs/QUICK-REF.md` — file map, DOM IDs, pricing constants
- `docs/quote-rules.md` — pricing / business logic
- `docs/DECISION-LOG.md` — has this decision already been made?
- `docs/KNOWN-ISSUES.md` — is this bug already tracked?
---
## Session End
1. Run `node tests/test-quote-engine.js` — all 254 must pass
2. Update `docs/SESSION-HANDOFF.md` as a **current state snapshot**:
- What is the state of the project right now (not a history log)
- What files are in what state
- What is next
3. Commit if approved by user — one concern per commit