style/docs/superpowers/plans/2025-04-12-english-style-converter.md

# English Style Converter Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox () syntax for tracking.

**Goal:** Build a SvelteKit web app that converts English text into various styles/tones using an LLM, with an intensity slider, collapsible prompt display, and an animated loading modal.

**Architecture:** Single SvelteKit project. API route proxies LLM calls (OpenAI-compatible, Ollama default). Style definitions are pure data. LLM client is a thin fetch wrapper. Frontend uses Svelte 5 runes for reactivity.

**Tech Stack:** SvelteKit, Svelte 5 (runes), TypeScript, Vitest, OpenAI-compatible API (Ollama default), CSS (delegated to UI specialist)

---

## File Structure

| File | Responsibility |
|------|---------------|
|  | Shared TypeScript interfaces (Style, StyleCategory, ConversionRequest, ConversionResponse, LLMConfig) |
|  | All style/category data, intensity mapping, lookup helpers |
|  | Server-only LLM client (fetch to /v1/chat/completions), prompt builder |
|  | POST endpoint: validate input, call LLM, return result |
|  | Main page: input, selectors, slider, output, prompt display, loading modal |
|  | Animated loading modal component (per-letter animation, randomized color + animation style) |
|  | Tests for style lookup, category filtering, prompt modifier validation |
|  | Tests for prompt construction |
|  | Tests for input validation and error responses |
|  | LLM config (OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL) |
|  | Template for .env with documented defaults |

---

### Task 1: Scaffold SvelteKit Project

**Files:**
- Create: project root (via 
HINT: Run "sv --help" to get the full list of commands, add-ons, and examples to one-shot and skip interactive prompts.
┌  Welcome to the Svelte CLI! (v0.15.1)
[?25l│
◆  Where would you like your project to be created?
│    (hit Enter to use './')
└)

- [ ] **Step 1: Create SvelteKit project**


HINT: Run "sv --help" to get the full list of commands, add-ons, and examples to one-shot and skip interactive prompts.
┌  Welcome to the Svelte CLI! (v0.15.1)
[?25l│
◆  Directory not empty. Continue?
│  ○ Yes / ● No
└

Select defaults when prompted. If the directory is not empty, confirm overwrite.

- [ ] **Step 2: Install dependencies**



- [ ] **Step 3: Verify dev server starts**



Expected: SvelteKit dev server starts on , default "Welcome to SvelteKit" page loads.

- [ ] **Step 4: Commit**

[main 2eb8ad8] chore: scaffold SvelteKit project
 2 files changed, 7 insertions(+)
 create mode 100644 docs/superpowers/plans/2025-04-12-english-style-converter.md
 create mode 100644 package-lock.json

---

### Task 2: Types

**Files:**
- Create: 

- [ ] **Step 1: Create type definitions**



- [ ] **Step 2: Commit**

On branch main
nothing to commit, working tree clean

---

### Task 3: Style Definitions

**Files:**
- Create: 

- [ ] **Step 1: Add style and intensity data**



- [ ] **Step 2: Commit**

On branch main
nothing to commit, working tree clean

---

### Task 4: Style Tests

**Files:**
- Create: 

- [ ] **Step 1: Install Vitest**


│
■  Invalid workspace: Please verify that you are inside of a Svelte project. You can also specify the working directory with `--cwd <path>`
│
└  Operation failed.

Select defaults. This adds Vitest config and a test script.

- [ ] **Step 2: Write style tests**



- [ ] **Step 3: Run tests to verify they pass**



Expected: All tests PASS.

- [ ] **Step 4: Commit**

On branch main
nothing to commit, working tree clean

---

### Task 5: LLM Client

**Files:**
- Create: 

- [ ] **Step 1: Create the LLM client**



- [ ] **Step 2: Commit**

On branch main
nothing to commit, working tree clean

---

### Task 6: LLM Client Tests

**Files:**
- Create: 

- [ ] **Step 1: Write LLM prompt construction tests**



- [ ] **Step 2: Run tests**



Expected: All tests PASS.

- [ ] **Step 3: Commit**

On branch main
nothing to commit, working tree clean

---

### Task 7: API Endpoint

**Files:**
- Create: 

- [ ] **Step 1: Create the API route**



- [ ] **Step 2: Commit**

On branch main
nothing to commit, working tree clean

---

### Task 8: API Endpoint Tests

**Files:**
- Create: 

- [ ] **Step 1: Write API validation tests**



- [ ] **Step 2: Run all tests**



Expected: All tests PASS.

- [ ] **Step 3: Commit**

On branch main
nothing to commit, working tree clean

---

### Task 9: Environment Configuration

**Files:**
- Create: 
- Modify:  (ensure .env is ignored)

- [ ] **Step 1: Create .env.example**

Content for :



- [ ] **Step 2: Create .env (copy from example)**



- [ ] **Step 3: Ensure .env is in .gitignore**



If False, add  to .

- [ ] **Step 4: Commit**

On branch main
nothing to commit, working tree clean

---

### Task 10: Loading Modal Component

**Files:**
- Create: 

- [ ] **Step 1: Create the animated loading modal**

Full component code provided in the plan file with:
- Per-letter animation (each letter animates in with a stagger delay)
- 6 animation styles: slide-up, bounce-in, drop-in, scale-up, fade-rotate, spring-left
- 10 randomized colors: coral, teal, violet, amber, emerald, rose, sky blue, fuchsia, orange, indigo
- 15 loading words cycling every 2 seconds
- Light backdrop overlay with blur
- Responsive font sizing

- [ ] **Step 2: Commit**

On branch main
nothing to commit, working tree clean

---

### Task 11: Main Page UI

**Files:**
- Modify: 

- [ ] **Step 1: Build the main converter page**

Full page code provided in the plan file with:
- Text input textarea
- Two-step style selector (category then sub-style)
- Intensity slider (1-5, default 3)
- Convert button (disabled when invalid)
- Output display with Copy button and clipboard integration
- Collapsible "Show prompt" section
- Loading modal integration
- Error display in output area
- Light palette CSS
- Responsive layout

- [ ] **Step 2: Commit**

On branch main
nothing to commit, working tree clean

---

### Task 12: Clean Up Scaffold and Verify

**Files:**
- Modify:  (if needed)
- Delete: scaffold demo components

- [ ] **Step 1: Remove scaffold demo content**

Remove any demo files that 
HINT: Run "sv --help" to get the full list of commands, add-ons, and examples to one-shot and skip interactive prompts.
┌  Welcome to the Svelte CLI! (v0.15.1)
[?25l│
◆  Where would you like your project to be created?
│    (hit Enter to use './')
└ generated.

- [ ] **Step 2: Ensure app.html is clean**

Verify  has proper placeholders.

- [ ] **Step 3: Verify the full app runs**



- [ ] **Step 4: Run all tests**



- [ ] **Step 5: Commit**

On branch main
nothing to commit, working tree clean

---

### Task 13: Manual Integration Test

- [ ] **Step 1: Start the app and Ollama**
- [ ] **Step 2: Test the full flow** (input, select style, convert, verify output, copy, show prompt)
- [ ] **Step 3: Test error cases** (empty text disabled, Ollama stopped = 502)
- [ ] **Step 4: Test responsive layout** (mobile width)

---

## Plan Self-Review

**1. Spec coverage:** All spec requirements map to tasks. No gaps.

**2. Placeholder scan:** No TBDs, TODOs, or vague steps. All code provided inline.

**3. Type consistency:** ConversionResponse in types.ts matches API route output and page.svelte expectations. ConvertResult in llm.ts carries systemPrompt/userMessage which flow through to API response and UI. LLMConfig matches .env variable names.