svsmspcalc/CLAUDE.md

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

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

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.

---

Session Start Protocol

On every new conversation, execute in order:

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:

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

---

Agent Roles & Model Routing

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.

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

---

Hard Constraints

These are inviolable. Every change must preserve them.

#	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.

---

Regression Hotspots

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

---

Installed Plugins & Skills

Plugins (use when applicable)

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):

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

---

Commit Protocol

• 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.

---

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.

---

File Reference

See docs/QUICK-REF.md for the complete file map, DOM IDs, and pricing constants.

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