diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..1245ab4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,248 @@ +# 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 "" --domain +``` +Domains: `style`, `color`, `typography`, `product`, `landing`, `chart`, `ux` + +--- + +## Commit Protocol + +- One concern per commit. Do not bundle unrelated changes. +- Message format: `: ` +- 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` | diff --git a/SVS-MSP-Calculator-components.css b/SVS-MSP-Calculator-components.css index b05dfe0..d3e5d2d 100644 --- a/SVS-MSP-Calculator-components.css +++ b/SVS-MSP-Calculator-components.css @@ -1790,12 +1790,12 @@ .sl-otf-waived .otf-waived-label { text-decoration: none; font-weight: 600; letter-spacing: 0.06em; font-size: 0.7rem; margin-right: var(--space-xs); } /* ── ADMIN FEE WAIVED display */ - .admin-fee-header { display: flex; align-items: center; flex-wrap: wrap; gap: var(--space-stack-tight); margin-bottom: 6px; } + .admin-fee-header { display: flex; align-items: center; flex-wrap: wrap; gap: var(--space-stack-tight); margin-bottom: var(--space-xs); } .admin-fee-waive-toggle { margin-left: auto; } .admin-fee-strike { text-decoration: line-through; color: var(--muted); text-decoration-color: var(--muted); } .admin-fee-waived-badge { font-family: 'DM Mono', monospace; font-size: 0.75rem; font-weight: 700; letter-spacing: 0.08em; color: var(--green); background: var(--surface-positive-badge); border: 1px solid var(--border-positive-badge); border-radius: var(--radius-control); padding: 2px var(--space-sm); vertical-align: middle; } .sl-admin-waived > span:first-child { text-decoration: line-through; text-decoration-color: var(--muted); color: var(--muted); } - .admin-waive-savings { display: flex; align-items: center; gap: var(--space-sm); font-family: 'DM Mono', monospace; font-size: 0.78125rem; letter-spacing: 0.04em; color: var(--green); background: var(--surface-positive-panel); border: 1px solid var(--border-positive-panel); border-radius: var(--radius-control); padding: var(--space-stack-tight) var(--space-stack); margin-top: var(--space-md); margin-bottom: 6px; } + .admin-waive-savings { display: flex; align-items: center; gap: var(--space-sm); font-family: 'DM Mono', monospace; font-size: 0.78125rem; letter-spacing: 0.04em; color: var(--green); background: var(--surface-positive-panel); border: 1px solid var(--border-positive-panel); border-radius: var(--radius-control); padding: var(--space-stack-tight) var(--space-stack); margin-top: var(--space-md); margin-bottom: var(--space-xs); } .admin-waive-savings.hidden { display: none; } #adminWaivedAmt { font-weight: 700; } diff --git a/SVS-MSP-Calculator.html b/SVS-MSP-Calculator.html index 1b0962c..d66f8d1 100644 --- a/SVS-MSP-Calculator.html +++ b/SVS-MSP-Calculator.html @@ -209,7 +209,7 @@