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

---

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