@c0x12c/spartan-ai-toolkit 1.10.0 → 1.11.0

package/.claude-plugin/marketplace.json

@@ -8,9 +8,9 @@
   "plugins": [
     {
       "name": "spartan-ai-toolkit",
-      "description": "5 workflows, 68 commands, 21 rules, 28 skills, 9 agents — organized in 12 packs with dependencies",
+      "description": "5 workflows, 69 commands, 21 rules, 29 skills, 9 agents — organized in 12 packs with dependencies",
       "source": "./toolkit",
-      "version": "1.10.0"
+      "version": "1.11.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.10.0",
-  "description": "Engineering discipline layer for Claude Code — 5 workflows, 68 commands, 21 rules, 28 skills, 9 agents organized in 12 packs",
+  "version": "1.11.0",
+  "description": "Engineering discipline layer for Claude Code — 5 workflows, 69 commands, 21 rules, 29 skills, 9 agents organized in 12 packs",
   "author": {
     "name": "Khoa Tran",
     "url": "https://github.com/spartan-stratos"

package/README.md

@@ -51,6 +51,20 @@ After install, open any project, run `claude`, then type `/spartan`.
 
 ---
 
+## Demo: Web-to-PRD
+
+Scan a live web app, extract every feature, generate a structured PRD with epics and stories, then export to Notion.
+
+```
+/spartan:web-to-prd "https://screensdesign.com"
+```
+
+![Web-to-PRD scanning screensdesign.com](../docs/images/web-to-prd-demo.png)
+
+Uses Playwright MCP (browser control) + Notion MCP (export). Auto-installs prerequisites, handles login, and asks for confirmation at each step.
+
+---
+
 ## How to Use
 
 ### The core workflow
@@ -229,6 +243,7 @@ Type `/spartan` to get the smart router — it asks what you need and picks the
 | `interview` | Mom Test interview questions |
 | `lean-canvas` | Fill out a 9-block Lean Canvas |
 | `brainstorm` | Generate and rank ideas |
+| `web-to-prd "URL"` | Scan a live web app with Playwright, extract features, generate PRD with epics/stories, export to Notion |
 
 ### Infrastructure (infrastructure pack)
 | Command | What it does |
@@ -293,6 +308,7 @@ Skills give Claude deeper knowledge in specific areas. They're loaded automatica
 | `article-writing` | research | Long-form content creation |
 | `content-engine` | research | Content strategy and production |
 | `startup-pipeline` | research | Full startup research pipeline |
+| `web-to-prd` | product | Scan web apps, extract features, generate PRD, export to Notion |
 
 ---
 

package/VERSION

@@ -1 +1 @@
-1.10.0
+1.11.0

package/claude-md/40-product.md

@@ -36,3 +36,4 @@ You don't have to use all of them. Pick what fits your stage.
 | `/spartan:interview "product"` | Generate Mom Test interview script (talk about their life, not your idea) |
 | `/spartan:lean-canvas "product"` | Fill out 9-block Lean Canvas interactively |
 | `/spartan:brainstorm "theme"` | Generate 8-15 ideas → filter → rank top 3 |
+| `/spartan:web-to-prd "URL"` | Scan a live web app → extract features → generate PRD/epics/stories → export to Notion. Needs Playwright MCP + Notion MCP. |

package/commands/spartan/build.md

@@ -64,21 +64,19 @@ _PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null |
 echo "SESSIONS: $_SESSIONS"
 echo "BRANCH: $_BRANCH"
 echo "PROJECT: $_PROJECT"
+cat .spartan/build.yaml 2>/dev/null || true
+cat .spartan/commands.yaml 2>/dev/null || true
 ```
 
 **Read the output.** If `SESSIONS` >= 3, start EVERY response with: **[PROJECT / BRANCH]** Currently working on: [task]
 
----
-
-## Load Build Config (silent — no questions)
+If `.spartan/commands.yaml` has a `prompts.build` entry, apply those custom instructions alongside the built-in ones.
 
-Check for a project-level build config that overrides default behavior:
+---
 
-```bash
-cat .spartan/build.yaml 2>/dev/null || cat .spartan/build.yml 2>/dev/null
-```
+## Build Config Fields
 
-If `.spartan/build.yaml` exists, read it and apply overrides. All fields are optional — omit to use defaults.
+If the preamble output includes `.spartan/build.yaml` content, apply these overrides. All fields are optional.
 
 | Field | Default | What it does |
 |-------|---------|-------------|

package/commands/spartan/web-to-prd.md

@@ -0,0 +1,544 @@
+---
+name: spartan:web-to-prd
+description: Scan a live web app, extract all features, generate PRD with epics/stories/tasks, export to Notion
+argument-hint: "[URL of the web app to scan]"
+preamble-tier: 3
+---
+
+# Web-to-PRD: {{ args[0] | default: "https://example.com" }}
+
+You are the **Web-to-PRD pipeline** — scan a live web app, extract every feature, create PM artifacts, and push to Notion.
+
+**Target URL:** {{ args[0] | default: "https://example.com" }}
+
+---
+
+## Step 0: Prerequisite Check
+
+**This step is mandatory. Do NOT skip it. Do NOT proceed until all checks pass.**
+
+**You (Claude) handle the setup. Don't ask the user to run install commands — do it yourself.**
+
+### Check 1: Playwright MCP
+
+Two checks: (A) is it installed? (B) is it using the Chrome profile?
+
+**Step A: Check if Playwright MCP is installed**
+
+Try to use any Playwright MCP tool (like `browser_snapshot` or `browser_navigate`).
+
+If tool not found → go to **Auto-Install** below.
+If tool found → go to **Step B**.
+
+**Step B: Check if it's configured properly**
+
+Read the MCP config:
+
+```bash
+cat ~/.claude.json 2>/dev/null | grep -A5 playwright || \
+cat .claude.json 2>/dev/null | grep -A5 playwright || \
+echo "NO_CONFIG_FOUND"
+```
+
+| What you see in config | Status | Action |
+|------------------------|--------|--------|
+| `--user-data-dir` with `.playwright-profile` | Good (default) | Proceed |
+| `--user-data-dir` pointing to real Chrome profile | Risky — extensions cause timeouts | Ask: "Your Playwright uses the real Chrome profile. Extensions can slow it down. Switch to a clean profile?" If yes → **Auto-Install** |
+| No `--user-data-dir` (clean mode) | OK for public sites | If site needs login → ask: "Want me to set up a persistent profile so logins are saved?" |
+| `--cdp-endpoint` | Advanced mode | OK — proceed |
+
+**Auto-Install (handles both fresh install and reconfigure):**
+
+```bash
+# Remove old config
+claude mcp remove playwright 2>/dev/null || true
+
+# Add with persistent separate profile (no extensions, fast, Chrome stays open)
+claude mcp add playwright -- npx @playwright/mcp@latest --user-data-dir="$HOME/.playwright-profile" --browser=chrome
+```
+
+After install, tell the user:
+
+> "Playwright MCP is ready. It uses a separate lightweight profile (no extensions, fast).
+>
+> For public sites: ready to go.
+> For login-protected sites: first run will open a browser — log in there. Your login is saved for next time."
+
+**No need to close Chrome.** Separate profile = no conflict with your running Chrome.
+
+**If the install command fails**, fall back to clean session:
+```bash
+claude mcp remove playwright 2>/dev/null || true
+claude mcp add playwright -- npx @playwright/mcp@latest
+```
+Tell user: "Installed Playwright without persistent profile. Login-protected sites won't save logins between runs."
+
+**Why NOT use the real Chrome profile:**
+- Loads ALL extensions (AdBlock, LastPass, etc.) → timeouts, hangs
+- Requires closing Chrome first (profile lock)
+- Stale `SingletonLock` files cause infinite hangs after Chrome crash
+- A lightweight separate profile is faster and more reliable
+
+### Check 2: Notion MCP
+
+Try to call `notion-search` with query "test".
+
+**If tool not found:**
+
+```
+Notion MCP is not connected.
+
+To connect:
+  1. Go to Claude Code settings (or Claude Desktop > Settings)
+  2. Find "Integrations" or "MCP Servers"
+  3. Enable "Notion" and authorize your workspace
+
+Alternative: Install via CLI:
+  claude mcp add notion -- npx @anthropic-ai/mcp-notion
+
+Then restart Claude Code and re-run:
+
+  /spartan:web-to-prd {{ args[0] | default: "URL" }}
+```
+
+**STOP here. Do not continue.**
+
+**If auth error (needs re-authentication):**
+
+```
+Notion MCP needs re-authentication.
+
+Open Claude Code settings and re-authorize Notion access to your workspace.
+```
+
+**STOP here.**
+
+### Check 3: Confirm both are working
+
+Show status:
+
+```
+Prerequisite Check:
+  Playwright MCP: [connected / not found]
+  Notion MCP:     [connected / not found / needs auth]
+
+[If both connected]: Ready to scan. Proceeding...
+[If any missing]:    Fix the issues above and re-run.
+```
+
+**Only proceed to Step 1 if BOTH are connected.**
+
+---
+
+## Step 1: Navigate and Handle Login
+
+**This step ensures we're fully logged in before exploring anything.**
+
+### 1-pre. Clean up stale browser processes (MANDATORY before first navigate)
+
+Playwright MCP leaves orphan Chrome processes from previous runs. These cause "Opening in existing browser session" errors. **Always run this before the first `browser_navigate` call:**
+
+```bash
+# Remove stale lock files (safe — doesn't kill any processes)
+rm -f "$HOME/.playwright-profile/SingletonLock" \
+      "$HOME/.playwright-profile/SingletonCookie" \
+      "$HOME/.playwright-profile/SingletonSocket" 2>/dev/null
+
+echo "Browser cleanup done"
+```
+
+**WARNING:** Do NOT run `pkill -f "playwright-profile"` — it kills the Playwright MCP server process too, disconnecting the tools mid-session. Only remove lock files.
+
+**If `browser_navigate` still fails with "Opening in existing browser session":**
+1. Run the cleanup again
+2. Wait 2 seconds
+3. Retry once
+4. If still fails → tell user to restart Claude Code (MCP server needs fresh start)
+
+Now navigate to the target URL using Playwright. Take a snapshot.
+
+### 1a. Check if login is needed
+
+Look at the snapshot for login signals:
+- Login/Sign-in form fields (email, password)
+- "Sign in", "Log in", "Create account" text
+- OAuth buttons (Google, GitHub, SSO)
+- URL contains `/login`, `/signin`, `/auth`
+- Redirect to a different domain (auth provider)
+
+### 1b. If login page detected — STOP and handle login
+
+Playwright opens a **visible browser window** (headed mode). The user can see and interact with it.
+
+Tell the user:
+
+> "This app needs login before I can see all the features.
+> A Chrome window should be open on your screen.
+>
+> Please log in directly in that browser window.
+> I won't see or store your credentials.
+>
+> Tell me when you're logged in."
+
+**Wait for user confirmation.** Do NOT proceed until they say "done", "logged in", or similar.
+
+After user confirms:
+1. Take a snapshot of the current page
+2. Check if still on login page → "Still seeing the login page. Try again?"
+3. Check if on dashboard/home/main content → "Logged in. Proceeding."
+4. If unclear → ask user: "I see [page title]. Is this the main page after login?"
+
+**Repeat until login is confirmed.** Do NOT start crawling while on a login page.
+
+**Login security rules:**
+- Never use `browser_type` to enter passwords — user types directly in browser
+- Never ask for credentials in chat
+- Never screenshot login pages (could capture pre-filled credentials)
+- SSO/OAuth popups work normally — wait for user to complete
+
+### 1c. If NOT a login page — proceed directly
+
+The site is public or already logged in (cookies from previous session).
+
+### 1d. Verify access level
+
+After login (or on public site), check what's visible:
+
+> "I can see [dashboard/home page]. I see these navigation sections:
+> 1. [Section name]
+> 2. [Section name]
+> ...
+>
+> Does this look like full access? Or are there sections I'm missing?
+> (Some apps hide admin/settings pages behind roles)"
+
+**Wait for user to confirm** before starting the full crawl. This prevents generating a PRD from a limited view.
+
+### 1e. Show crawl plan
+
+```
+Crawl Plan: [App Name]
+URL:        [target URL]
+Type:       [SPA / Multi-page / Hybrid]
+Auth:       [Logged in / Public]
+Estimated pages: ~[N]
+Estimated time:  [N] minutes
+
+Sections to explore:
+  1. [Section name] — [N sub-items]
+  2. [Section name] — [N sub-items]
+  ...
+
+Proceed? [Y/n]
+```
+
+---
+
+## Step 2: Crawl and Extract
+
+**Only start this step after login is confirmed and crawl plan is approved.**
+
+Navigate through each section systematically:
+
+1. **Visit each page** from the navigation
+2. **Take a snapshot** (accessibility tree) of each page
+3. **Click into sub-pages** — tabs, accordions, detail views
+4. **Note interactive elements** — forms, buttons, modals, filters
+5. **Don't click destructive actions** — skip Delete, Remove, etc.
+6. **Add 1-2 second delay** between navigations
+7. **If session expires mid-crawl** (redirected to login) → STOP, tell user to re-login in the browser, wait, then continue
+
+### Progress updates
+
+After every 10 pages or every major section:
+
+> "Progress: Scanned [N] pages. Found [N] feature areas so far.
+> Latest section: [section name]
+> Continue? [Y/n]"
+
+### What to capture per page
+
+For each page, record:
+- URL and page title
+- Page type (dashboard, list, detail, form, settings, etc.)
+- Features visible on the page
+- Form fields and their types
+- Action buttons and what they do
+- Data displayed (tables, charts, cards)
+- Navigation elements (tabs, breadcrumbs, sidebar items)
+
+### Build the feature map
+
+As you crawl, build a structured feature map:
+
+```yaml
+app:
+  name: "[detected app name]"
+  url: "[target URL]"
+  sections:
+    - name: "[Section from nav]"
+      pages:
+        - url: "/path"
+          title: "Page Title"
+          type: "list"
+          features:
+            - name: "Feature name"
+              type: "data-display | form | action | filter | notification"
+              description: "What it does"
+              ui_elements: ["table", "search bar", "export button"]
+```
+
+---
+
+## Step 3: Organize and Prioritize
+
+After crawling is done, organize the raw features:
+
+### 3a. Group into Epics
+
+Group features by:
+1. Navigation sections (natural grouping)
+2. User goals (what the user is trying to do)
+3. Data domain (features that touch the same data)
+
+### 3b. Write User Stories
+
+For each feature, write a story:
+> As a [user type], I can [action] so that [benefit]
+
+Add acceptance criteria (2-4 per story).
+
+### 3c. Assign Priorities
+
+| Priority | Rule |
+|----------|------|
+| P0 | Core flow — app is broken without it |
+| P1 | Important — app is usable but limited without it |
+| P2 | Nice to have — enhancement, polish |
+| P3 | Future — advanced, not needed now |
+
+### 3d. Map Dependencies
+
+Figure out build order:
+- Auth always comes first
+- CRUD: Create → Read/List → Update → Delete
+- Data display depends on data input
+- Settings depend on the feature they configure
+
+### 3e. Show summary and confirm
+
+> "Here's what I found:
+>
+> **App:** [name]
+> **Pages scanned:** [N]
+> **Epics:** [N]
+> **Stories:** [N]
+> **Tasks:** [N]
+>
+> **Build order:**
+> Phase 1: [Epic A, Epic B] — no dependencies
+> Phase 2: [Epic C] — depends on Phase 1
+> Phase 3: [Epic D, Epic E] — depends on Phase 2
+>
+> Anything look wrong or missing before I generate the PRD?"
+
+---
+
+## Step 4: Generate PRD
+
+Generate a full PRD document with this structure:
+
+```markdown
+# PRD: [App Name]
+
+## 1. TL;DR
+
+[1-2 sentences: what this app does, who it's for, what problem it solves, what makes it different.]
+
+## 2. Goals
+
+### Business Goals
+- [What this app is trying to achieve as a business]
+- [Revenue model, growth metrics observed]
+
+### User Goals
+- [What users can do with this app]
+- [What pain it solves]
+
+### Non-Goals
+- [Things this app intentionally doesn't do]
+- [Adjacent features it could have but chose not to]
+
+## 3. User Stories
+
+[Grouped by persona/role detected in the app:]
+
+- As a [user type], I want to [action], so that [benefit]
+- As a [admin/manager], I want to [action], so that [benefit]
+
+## 4. Functional Requirements
+
+[Grouped by Epic, with priority. This is the main section.]
+
+### Epic 1: [Name] — Priority: P0 — Phase: 1
+**Dependencies:** none
+**Pages:** [URLs in this area]
+
+| # | Requirement | Priority | Story |
+|---|-------------|----------|-------|
+| 1.1 | [Specific feature/capability] | P0 | As a user, I can... |
+| 1.2 | [Specific feature/capability] | P0 | As a user, I can... |
+| 1.3 | [Specific feature/capability] | P1 | As a user, I can... |
+
+**Acceptance Criteria:**
+- [ ] [Testable criterion for 1.1]
+- [ ] [Testable criterion for 1.2]
+
+### Epic 2: [Name] — Priority: P1 — Phase: 2
+**Dependencies:** Epic 1
+...
+
+[Repeat for all epics]
+
+## 5. User Experience
+
+### Entry Points
+- [How users get into the app]
+- [Main navigation structure]
+
+### Key Flows
+1. [Flow name]: [step-by-step from entry to completion]
+2. [Flow name]: [step-by-step]
+
+### Edge Cases
+- [What happens when X fails]
+- [Empty states observed]
+
+### Design Notes
+- [UI patterns used: sidebar, tabs, cards, etc.]
+- [Responsive behavior observed]
+
+## 6. Narrative
+
+[200 words: a story from the user's point of view.
+Walk through a typical session using the app.
+Makes the PRD feel real, not abstract.]
+
+## 7. Build Roadmap
+
+[This is the actionable section. Shows exactly what to build first.]
+
+### Phase 1: Foundation (no dependencies)
+| Epic | Priority | Stories | Est. complexity |
+|------|----------|---------|-----------------|
+| [Epic A] | P0 | [N] | [Simple/Medium/Complex] |
+| [Epic B] | P0 | [N] | [Simple/Medium/Complex] |
+
+### Phase 2: Core Features (depends on Phase 1)
+| Epic | Priority | Stories | Est. complexity |
+|------|----------|---------|-----------------|
+| [Epic C] | P0 | [N] | [Medium/Complex] |
+
+### Phase 3: Enhancement (depends on Phase 2)
+...
+
+### Dependency Graph
+[Text diagram showing which epics depend on which]
+
+## 8. Open Questions
+- [Things that couldn't be determined from the UI]
+- [Decisions that need product input]
+- [Areas where the app behavior was unclear]
+```
+
+**Save locally first:**
+```
+.planning/web-to-prd/
+  prd-[app-name].md
+```
+
+---
+
+## Step 5: Export to Notion
+
+Ask the user:
+
+> "Where should I create the backlog in Notion?
+>
+> A) New page in workspace root
+> B) Under an existing page (I'll search for it)
+> C) Skip Notion — just keep the local PRD file"
+
+### If A or B: Create Notion structure
+
+1. **Create parent page** — "[App Name] — Product Backlog" with PRD content
+2. **Create Epics database** with columns:
+   - Name (title)
+   - Priority (select: P0, P1, P2, P3)
+   - Status (select: Not Started, In Progress, Done)
+   - Phase (number)
+   - Description (rich text)
+3. **Create Stories database** with columns:
+   - Name (title)
+   - Epic (relation to Epics)
+   - Priority (select: P0, P1, P2, P3)
+   - Status (select: Backlog, Ready, In Progress, Review, Done)
+   - User Story (rich text)
+   - Acceptance Criteria (rich text)
+4. **Create Tasks database** with columns:
+   - Name (title)
+   - Story (relation to Stories)
+   - Status (select: To Do, In Progress, Done)
+   - Type (select: Frontend, Backend, Design, DevOps, QA)
+5. **Populate all databases** with the extracted data
+6. **Create views:**
+   - Kanban by Status (for Stories)
+   - Table grouped by Epic (for Stories)
+
+### If C: Local only
+
+Save to `.planning/web-to-prd/` and done.
+
+---
+
+## Step 6: Done
+
+Show final summary:
+
+```
+Web-to-PRD Complete
+
+App:     [name]
+URL:     [url]
+Scanned: [N] pages
+
+Generated:
+  - [N] Epics
+  - [N] Stories
+  - [N] Tasks
+  - [N] Phases (build order)
+
+Saved to:
+  - Local: .planning/web-to-prd/prd-[app-name].md
+  - Notion: [page URL if exported]
+
+Next steps:
+  - Review the PRD and adjust priorities
+  - Use /spartan:spec to detail individual features
+  - Use /spartan:plan to plan implementation for each epic
+```
+
+---
+
+## Rules
+
+1. **Prerequisites are non-negotiable.** Always check Playwright and Notion MCP first. Don't try to work around missing tools.
+2. **Don't guess features you can't see.** Only document what's visible in the UI.
+3. **Don't click destructive buttons.** No Delete, Remove, Reset, or similar actions during crawl.
+4. **Show progress.** Update the user every 10 pages or every section.
+5. **Local save always happens.** Even if Notion export works, save the PRD locally too.
+6. **Ask before login.** Never assume credentials. Let the user handle auth manually.
+7. **One app per run.** Don't follow links to external domains.
+8. **Delay between pages.** 1-2 seconds between navigations. Don't hammer the server.
+9. **Mark assumptions.** If you're guessing what a feature does, say so.
+10. **The PRD is a starting point.** Tell the user to review and adjust — it's not final.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c0x12c/spartan-ai-toolkit",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Engineering discipline layer for AI coding agents — commands, rules, skills, agents, and packs for Claude Code",
   "type": "module",
   "bin": {

package/packs/packs.compiled.json

@@ -281,10 +281,13 @@
         "teardown",
         "interview",
         "lean-canvas",
-        "brainstorm"
+        "brainstorm",
+        "web-to-prd"
       ],
       "rules": [],
-      "skills": [],
+      "skills": [
+        "web-to-prd"
+      ],
       "agents": [],
       "claudeSections": [
         "40-product.md"

package/packs/product.yaml

@@ -11,9 +11,11 @@ commands:
   - interview
   - lean-canvas
   - brainstorm
+  - web-to-prd
 
 rules: []
-skills: []
+skills:
+  - web-to-prd
 agents: []
 
 claude-sections:

package/skills/web-to-prd/SKILL.md

@@ -0,0 +1,436 @@
+---
+name: web-to-prd
+description: "Scan a live web app with Playwright, extract all features, generate PRD/epics/stories with priorities and dependencies, export to Notion. Checks required MCP servers before starting."
+allowed_tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - WebSearch
+---
+
+# Web-to-PRD Skill
+
+Scan a live web app. Extract every feature. Turn it into a structured PRD with epics, stories, and tasks. Push it all to Notion.
+
+## When to Use
+
+- Reverse-engineer a competitor's product
+- Document an existing app you're taking over
+- Create a PRD from a live product (yours or someone else's)
+- Build a feature backlog from scratch by looking at what's already built
+
+## What This Skill Does
+
+1. **Checks prerequisites** — makes sure Playwright MCP and Notion MCP are connected
+2. **Crawls the web app** — navigates page by page, reads UI elements
+3. **Extracts features** — groups what it finds into feature areas
+4. **Generates PM artifacts** — PRD, epics, stories, tasks with priorities and dependencies
+5. **Exports to Notion** — creates linked databases, populates everything
+
+## Prerequisites
+
+This skill needs 2 MCP servers. The command checks both before starting.
+
+### 1. Playwright MCP (browser control)
+
+Claude uses Playwright to open a real browser, navigate pages, and read content.
+
+#### Browser modes
+
+| Mode | Install command | What it does |
+|------|----------------|-------------|
+| **Persistent profile (default)** | See setup below | Lightweight profile at `~/.playwright-profile`. Login once, remembered. Chrome stays open. No extensions bloat. |
+| CDP (advanced) | `--cdp-endpoint='http://localhost:9222'` | Connects to running Chrome. Has your logins but also loads all extensions (can be slow). |
+| Chrome profile (heavy) | `--user-data-dir="[Chrome path]" --browser=chrome` | Uses real Chrome profile. Has logins but loads ALL extensions — often causes timeouts. Not recommended. |
+| Clean session | no extra flags | Fresh browser each time. No saved state. Public sites only. |
+
+#### Default setup: Persistent profile (auto-installed by the command)
+
+The `/spartan:web-to-prd` command handles installation itself. Uses a lightweight separate profile at `~/.playwright-profile` — no extensions, no bloat, fast startup.
+
+**What the command does internally:**
+```bash
+claude mcp remove playwright 2>/dev/null || true
+claude mcp add playwright -- npx @playwright/mcp@latest --user-data-dir="$HOME/.playwright-profile" --browser=chrome
+```
+
+**First run on a login-protected site:** Playwright opens Chrome with a clean profile. User logs in manually. Cookies are saved to `~/.playwright-profile`. Next runs are already logged in.
+
+**Why not the real Chrome profile?** Real Chrome profiles load ALL extensions (AdBlock, LastPass, password managers, etc.). These add latency, block requests, and often cause Playwright to timeout or hang. A separate profile is faster and more reliable.
+
+**Chrome can stay open.** Since we use a separate profile, there's no conflict.
+
+#### Switching modes
+
+To change mode, remove and re-add:
+```bash
+claude mcp remove playwright
+claude mcp add playwright -- npx @playwright/mcp@latest [flags]
+```
+
+#### All Playwright MCP flags
+
+| Flag | What it does |
+|------|-------------|
+| `--cdp-endpoint="http://localhost:9222"` | Connect to running Chrome via CDP |
+| `--user-data-dir="/path"` | Persistent browser profile (keeps cookies) |
+| `--storage-state="/path/to/state.json"` | Load saved cookies from file |
+| `--isolated` | Fresh session, no persistent data |
+| `--browser=chrome` | Use real Chrome instead of Chromium |
+| `--headless` | No visible browser window |
+
+All flags also work as env vars with `PLAYWRIGHT_MCP_` prefix (e.g., `PLAYWRIGHT_MCP_CDP_ENDPOINT`).
+
+**How to verify Playwright MCP is installed:**
+```bash
+claude mcp list | grep -i playwright
+```
+
+**What it gives you:** `browser_navigate`, `browser_click`, `browser_snapshot`, `browser_type`, `browser_tab_list` and more.
+
+### 2. Notion MCP (export destination)
+
+Claude uses Notion MCP to create databases, pages, and views in your workspace.
+
+**How to install:**
+The Notion MCP is available as a Claude.ai integration. Enable it from:
+- Claude Code settings > MCP servers
+- Or Claude Desktop > Settings > Integrations > Notion
+
+**How to verify:**
+```bash
+claude mcp list | grep -i notion
+```
+
+**What it gives you:** `notion-create-database`, `notion-create-pages`, `notion-create-view`, `notion-search`, `notion-update-page`.
+
+### Optional: Firecrawl MCP (faster crawling)
+
+If the user has Firecrawl, use it instead of Playwright for the initial crawl. It's faster but costs money.
+
+```bash
+claude mcp add firecrawl -- npx firecrawl-mcp
+```
+
+Firecrawl is optional. Playwright alone handles everything.
+
+---
+
+## Prerequisite Check Logic
+
+Run this check at the start. **Claude handles installation — don't ask the user to run install commands.**
+
+```
+CHECK 1: Playwright MCP
+  A) Try calling any Playwright tool (e.g., browser_snapshot)
+     If not found → auto-install with Chrome profile (see below)
+
+  B) If found → check the config (grep .claude.json for playwright args)
+     If --user-data-dir points to ~/.playwright-profile → good, proceed
+     If --user-data-dir points to real Chrome profile → risky (extensions cause timeouts), ask to switch
+     If no --user-data-dir (clean mode) → ask: want persistent profile for saved logins?
+     If --cdp-endpoint → good, proceed
+
+  Auto-install: claude mcp remove + add with --user-data-dir="$HOME/.playwright-profile" --browser=chrome
+
+CHECK 2: Notion MCP
+  Try calling notion-search with a simple query
+  If not found → show instructions (needs manual auth, can't auto-install)
+  If auth error → tell user to re-authenticate
+  If found → continue
+
+BOTH OK → proceed to crawl (no need to close Chrome — separate profile has no conflict)
+```
+
+**Notion can't be auto-installed** because it needs the user to authorize their workspace. Show setup instructions and STOP.
+
+---
+
+## Crawl Strategy
+
+### Step 0: Clean up stale browser processes (before every run)
+
+Playwright MCP leaves orphan Chrome processes from previous runs. Always clean up before the first `browser_navigate`:
+
+```bash
+pkill -f "playwright-profile" 2>/dev/null || true
+rm -f "$HOME/.playwright-profile/SingletonLock" "$HOME/.playwright-profile/SingletonCookie" "$HOME/.playwright-profile/SingletonSocket" 2>/dev/null
+```
+
+If navigate still fails with "Opening in existing browser session" → retry once after 2 seconds. If still fails → user needs to restart Claude Code.
+
+### Step 1: Login FIRST (mandatory before crawling)
+
+**Never start crawling without confirming access. Login is Step 1, not an afterthought.**
+
+1. Navigate to the target URL
+2. Take a snapshot — check for login signals (form fields, "Sign in" text, `/login` URL)
+3. **If login page:**
+   - STOP. Tell user: "Login page detected. Please log in in the browser window. Tell me when done."
+   - Wait for user confirmation
+   - Take snapshot to verify — still login page? Ask again. See dashboard? Proceed.
+   - **Repeat until logged in.** Do NOT start crawling from a login page.
+4. **If already logged in** (or public site):
+   - Show the user what sections are visible
+   - Ask: "Does this look like full access? Any sections I'm missing?"
+   - Wait for confirmation before crawling
+
+**Session expiry during crawl:** If redirected to login mid-crawl → STOP, tell user to re-login in the browser, wait for confirmation, then continue where you left off.
+
+**Security rules:**
+- Never use `browser_type` to enter passwords — user types directly in the browser
+- Never ask for credentials in chat
+- Never screenshot login pages
+- SSO/OAuth popups work normally — just wait for user to complete
+
+**Cookies:** With persistent profile (`~/.playwright-profile`), logins are saved. Next run on the same site = already logged in.
+
+### Step 2: Explore all sections
+
+After login is confirmed:
+
+1. Read all navigation links (navbar, sidebar, footer)
+2. Visit each link, take snapshot
+3. For each page, look for:
+   - Sub-navigation (tabs, accordions, dropdowns)
+   - Forms and their fields
+   - Data tables and their columns
+   - Action buttons (create, edit, delete, export)
+   - Modals/dialogs (click non-destructive buttons to discover them)
+   - Settings/config pages
+   - User/account pages
+   - Admin panels (if accessible)
+4. Build a sitemap as you go
+
+### For SPAs (single page apps)
+
+SPAs don't have traditional page URLs. Use this approach:
+1. Start at the root URL
+2. Read the navigation/sidebar for all sections
+3. Click each section, wait for content to load
+4. Take snapshot after each navigation
+5. Track visited states by URL hash or path changes
+
+### Crawl depth limits
+
+| App size | Max pages | Estimated time |
+|----------|-----------|----------------|
+| Small (< 10 pages) | All pages | 2-5 min |
+| Medium (10-50 pages) | All pages | 5-15 min |
+| Large (50+ pages) | Top 50, then ask user | 15+ min |
+
+After every 10 pages, show progress:
+> "Scanned 10/~25 pages. Found 3 feature areas so far. Continue?"
+
+---
+
+## Feature Extraction
+
+### What to extract from each page
+
+For every page visited, capture:
+
+```yaml
+page:
+  url: "/dashboard"
+  title: "Dashboard"
+  type: dashboard | list | detail | form | settings | landing | auth | empty
+  features:
+    - name: "Revenue Chart"
+      type: data-display | form | action | navigation | filter | notification
+      description: "Line chart showing monthly revenue with date range picker"
+      ui_elements:
+        - chart (line, with tooltips)
+        - date range picker
+        - export button
+      interactions:
+        - hover shows tooltip with exact value
+        - date range filters the data
+        - export downloads CSV
+    - name: "Quick Actions Bar"
+      type: action
+      description: "Row of shortcut buttons: New Invoice, New Client, Reports"
+      interactions:
+        - each button navigates to respective page
+```
+
+### Feature grouping rules
+
+After crawling, group features into **feature areas** (these become Epics):
+
+1. **By navigation section** — sidebar/navbar sections are natural groupings
+2. **By user goal** — what is the user trying to do?
+3. **By data domain** — features that touch the same data belong together
+
+Example groupings:
+```
+Epic: User Management
+  - User list with search/filter
+  - User profile page
+  - User invite flow
+  - Role assignment
+  - User deactivation
+
+Epic: Billing & Payments
+  - Invoice list
+  - Create invoice form
+  - Payment tracking
+  - Subscription management
+  - Billing settings
+```
+
+### Priority assignment
+
+Assign priority based on visibility and complexity:
+
+| Priority | Criteria |
+|----------|----------|
+| P0 - Must have | Core user flow, app doesn't work without it |
+| P1 - Should have | Important but app is usable without it |
+| P2 - Nice to have | Enhancement, polish, edge case handling |
+| P3 - Future | Advanced feature, nice but not needed now |
+
+**Heuristics:**
+- Main navigation items → P0 or P1
+- Settings/config pages → P1 or P2
+- Empty states, onboarding → P2
+- Social features, sharing → P2 or P3
+
+### Dependency mapping
+
+Map dependencies between features:
+
+```
+Epic: Authentication (must build first)
+  → Epic: User Management (needs auth)
+    → Epic: Team Management (needs users)
+      → Epic: Permissions (needs teams)
+
+Epic: Product Catalog (independent)
+  → Epic: Shopping Cart (needs products)
+    → Epic: Checkout (needs cart)
+      → Epic: Order Management (needs checkout)
+```
+
+Rules for dependencies:
+- CRUD operations: Create before Read/List before Update before Delete
+- Auth is always first
+- Data display depends on data input
+- Settings depend on the feature they configure
+
+---
+
+## PRD Generation
+
+### Structure
+
+Generate a PRD with 8 sections. The format is designed to be actionable — when someone reads it, they know exactly what to build first, step by step.
+
+```
+1. TL;DR              — 2 sentences, what this app does
+2. Goals              — Business goals, user goals, non-goals
+3. User Stories        — Grouped by persona/role
+4. Functional Reqs    — Grouped by Epic, with priority table + acceptance criteria
+5. User Experience    — Entry points, key flows, edge cases, design notes
+6. Narrative          — 200-word story from user's POV
+7. Build Roadmap      — Phased plan with dependency graph (the "what to do first" section)
+8. Open Questions     — Things that need human input
+```
+
+**Section 4 (Functional Requirements)** is the main section. Each Epic gets:
+- A priority and phase number
+- A requirements table: `# | Requirement | Priority | Story`
+- Acceptance criteria as checkboxes
+
+**Section 7 (Build Roadmap)** is the actionable section. Shows:
+- Phases with parallel epics
+- Dependency graph (text diagram)
+- Complexity estimate per epic
+
+See the command file (`web-to-prd.md`) for the full template.
+
+---
+
+## Notion Export
+
+### Database Structure
+
+Create 4 linked databases in Notion:
+
+```
+Parent page: "[App Name] — Product Backlog"
+├── PRD page (full text PRD)
+├── Epics database
+│   ├── Name (title)
+│   ├── Priority (select: P0, P1, P2, P3)
+│   ├── Status (select: Not Started, In Progress, Done)
+│   ├── Phase (number)
+│   ├── Depends On (relation → Epics)
+│   ├── Description (rich text)
+│   └── Story Count (rollup from Stories)
+├── Stories database
+│   ├── Name (title)
+│   ├── Epic (relation → Epics)
+│   ├── Priority (select: P0, P1, P2, P3)
+│   ├── Status (select: Backlog, Ready, In Progress, Review, Done)
+│   ├── Points (number)
+│   ├── User Story (rich text: As a..., I can..., so that...)
+│   └── Acceptance Criteria (rich text: checklist)
+└── Tasks database
+    ├── Name (title)
+    ├── Story (relation → Stories)
+    ├── Status (select: To Do, In Progress, Done)
+    ├── Type (select: Frontend, Backend, Design, DevOps, QA)
+    └── Description (rich text)
+```
+
+### Export steps
+
+1. **Ask where to put it:**
+   > "Where should I create the backlog in Notion?
+   > A) Create a new page in your workspace root
+   > B) Add it under an existing page (I'll search for it)
+   > C) Just generate the PRD locally, don't push to Notion"
+
+2. **Create parent page** with the PRD content
+3. **Create Epics database** with all epics
+4. **Create Stories database** linked to Epics
+5. **Create Tasks database** linked to Stories
+6. **Create views:**
+   - Kanban view (by Status) for Stories
+   - Timeline view (by Phase) for Epics
+   - Table view (default) for Tasks
+
+### If Notion MCP is not available
+
+Save everything locally:
+```
+.planning/web-to-prd/
+├── prd.md                    # Full PRD document
+├── epics.md                  # All epics with stories
+├── dependency-graph.md       # Visual dependency map
+└── screenshots/              # Page screenshots (if taken)
+```
+
+User can import to Notion manually later.
+
+---
+
+## Rules
+
+1. **Always check prerequisites first.** Don't start crawling without confirming both MCP servers.
+2. **Login before crawling.** Never generate a PRD from a login page or public-only view. If the app has login, handle it first. Verify you see the full app before starting.
+3. **Confirm access level.** After login, show the user what sections are visible and ask if anything is missing. A PRD from a limited view is useless.
+4. **Handle session expiry.** If redirected to login mid-crawl, STOP and ask user to re-login. Don't crawl from a login page.
+5. **Show progress during crawl.** Every 10 pages or every major section, update the user.
+3. **Don't guess features you can't see.** Only document what's visible in the UI. Mark assumptions clearly.
+4. **Ask before clicking destructive actions.** If you see "Delete" or "Remove" buttons, don't click them during crawl.
+5. **Handle errors gracefully.** If a page fails to load, note it and move on. Don't stop the whole crawl.
+6. **Respect rate limits.** Add 1-2 second delays between page navigations to avoid being blocked.
+7. **Screenshots are optional.** Only take them if the user asks or if a page has complex layout.
+8. **Login is the user's job.** Never store or ask for production credentials. Use headed mode for manual login.
+9. **Local save is always available.** Even if Notion export fails, the PRD is saved locally.
+10. **One app per run.** Don't crawl multiple domains in a single session.
+11. **NEVER point `--user-data-dir` to the real Chrome profile directory** (e.g., `~/Library/Application Support/Google/Chrome` on Mac, `~/.config/google-chrome` on Linux). This can corrupt Chrome profiles, delete saved logins, and break the user's browser. Always use a separate directory like `~/.playwright-profile`.