// Set up and run different development service arrangements for testing specific features. Use when starting dev servers, testing Storybook addon (SB8 or SB10), testing Tailwind v3 vs v4, testing Astro, or when asked which services to run. Covers compound tasks, port assignments, and which services need each other.
| name | dev-environments |
| description | Set up and run different development service arrangements for testing specific features. Use when starting dev servers, testing Storybook addon (SB8 or SB10), testing Tailwind v3 vs v4, testing Astro, or when asked which services to run. Covers compound tasks, port assignments, and which services need each other. |
This project has multiple test apps, Storybook versions, and server configurations. Different features require different combinations of services.
Run via Terminal → Run Task:
| Task | What it starts | Use when |
|---|---|---|
| Dev: Test App | Overlay watch, Panel watch, Server (3333), Test App (5173) | General development, overlay/panel work |
| Dev: SB8 | Overlay watch, Panel watch, Server (3333→SB 6007), SB8 (6007), Test App (5173) | Testing Storybook 8 addon integration |
| Dev: SB10 | Overlay watch, Panel watch, Server (3333→SB 6008), SB10 (6008), Test App (5173) | Testing Storybook 10 addon integration |
| Dev: All v3 | Overlay watch, Panel watch, Server v3 (3334), Test App v3 (5175) | Testing Tailwind v3 support |
| Dev: Angular | Overlay watch, Panel watch, Server Angular (3335), Test App Angular (5177) | Testing Angular 21 support |
| Dev: SB Angular | Overlay watch, Panel watch, Server Angular (3335→SB 6009), SB Angular (6009), Test App Angular (5177) | Testing Angular Storybook addon |
| Port | Service | Notes |
|---|---|---|
| 3333 | MCP Server | Always runs from test-app/ cwd (resolves TW v4) |
| 3334 | MCP Server v3 | Runs from test-app-v3/ cwd (resolves TW v3) |
| 5173 | Test App | Tailwind v4 React app |
| 5174 | Panel dev | Only for panel-only dev (cd panel && npm run dev) |
| 5175 | Test App v3 | Tailwind v3 React app |
| 5176 | Test App Astro | Astro framework test app |
| 6006 | Panel Storybook | Panel component stories (internal dev) |
| 6007 | SB8: Test App | Storybook 8 with test-app stories + Convey addon |
| 6008 | SB10: Test App | Storybook 10 with test-app stories + Convey addon |
| 3335 | MCP Server Angular | Runs from test-app-angular/ cwd (resolves TW v4) |
| 5177 | Test App Angular | Angular 21 + Tailwind v4 app |
| 6009 | SB10: Angular | Storybook 10 with Angular test-app stories + Convey addon |
overlay/dist/overlay.js on savepanel/dist/ on saveThese are the brain of the system. Without them, changes to overlay or panel code won't take effect.
The server resolves tailwindcss from its cwd's node_modules/. This determines which Tailwind version the compiler uses:
test-app/ → Tailwind v4test-app-v3/ → Tailwind v3test-app-angular/ → Tailwind v4 (via PostCSS)The server's STORYBOOK_URL env var tells it which Storybook to connect to for the Draw tab feature:
STORYBOOK_URL=http://localhost:6007 for SB8STORYBOOK_URL=http://localhost:6008 for SB10The Mock MCP Client spawns its own server via stdio. Never run both simultaneously — they'd conflict on port 3333.
The server runs from test-app/ to resolve tailwindcss. The test app itself (port 5173) is useful for verifying the overlay works outside Storybook, but the server task is what truly needs test-app's node_modules.
Task: Dev: Test App
The default setup for working on overlay, panel, or server features.
Services:
test-app/Open: http://localhost:5173 (app) and http://localhost:3333/panel/ (inspector)
Task: Dev: SB8
Test the Convey addon in Storybook 8.
Services:
STORYBOOK_URL=http://localhost:6007storybook-test/v8/Open: http://localhost:6007 — Convey addon panel appears in the right sidebar
Task: Dev: SB10
Test the Convey addon in Storybook 10.
Services:
STORYBOOK_URL=http://localhost:6008storybook-test/v10/Open: http://localhost:6008 — Convey addon panel appears in the right sidebar
Task: Dev: All v3
Test the inspector with Tailwind v3 apps.
Services:
test-app-v3/Open: http://localhost:5175 (app) and http://localhost:3334/panel/ (inspector)
Task: Dev: Angular
Test the inspector with Angular 21 apps.
Services:
test-app-angular/Open: http://localhost:5177 (app) and http://localhost:3335/panel/ (inspector)
Task: Dev: SB Angular
Test the Convey addon in Storybook 10 with Angular components.
Services:
STORYBOOK_URL=http://localhost:6009storybook-test/angular-v10/Open: http://localhost:6009 — Convey addon panel appears in the right sidebar
No compound task yet — run individually:
test-app/ (needs TW v4 resolution)Open: http://localhost:5176
For testing the full agent workflow (stage → commit → implement → mark done → repeat):
Do NOT also start the Server task — the Mock MCP Client owns it.
For working on panel components in isolation:
panel/No other services needed. Panel Storybook only shows panel components, no addon integration.
Arrangements that use port 3333 are mutually exclusive — only run one at a time:
Dev: All v3 uses port 3334, so it can run alongside any of the above.
Before launching services, always run this procedure to avoid port conflicts and stale processes:
lsof -iTCP -sTCP:LISTEN -P -n 2>/dev/null | grep -E ':(3333|3334|5173|5174|5175|5176|6006|6007|6008) ' || echo "No conflicting ports in use"
Compare the output against the arrangement you want to start. Conflict rules:
Dev: Test App to Dev: SB8, since STORYBOOK_URL differs)Kill only the processes that conflict. Use the PID from lsof:
# Kill a specific port's process
kill $(lsof -ti :3333) 2>/dev/null
# Or for stubborn processes
kill -9 $(lsof -ti :3333) 2>/dev/null
Never kill ports that the new arrangement also needs and that are already running correctly. For example, if Test App (5173) is already running and the new arrangement also needs it, leave it alone.
Use the compound task (Dev: SB8, Dev: SB10, etc.) or start individual tasks.
| Switching to | Kill port 3333? | Kill port 6007? | Kill port 6008? | Kill port 5173? |
|---|---|---|---|---|
| Dev: Test App | Yes, if server config differs | No (not used) | No (not used) | No (reuse) |
| Dev: SB8 | Yes, if STORYBOOK_URL ≠ 6007 | No (reuse if SB8) | Yes (if SB10 running) | No (reuse) |
| Dev: SB10 | Yes, if STORYBOOK_URL ≠ 6008 | Yes (if SB8 running) | No (reuse if SB10) | No (reuse) |
| Dev: All v3 | No (uses 3334) | No (not used) | No (not used) | No (uses 5175) |
| Mock MCP Client | Yes, always | No | No | No (reuse) |
Each environment needs its own npm install:
cd test-app && npm install
cd test-app-v3 && npm install
cd storybook-test/v8 && npm install
cd storybook-test/v10 && npm install
cd panel && npm install
npm install # root
Always start a fresh browser session after any file change, walk through the full user flow, and monitor for errors before proceeding with further work.
Defines the interaction behavior of global mode buttons (Select, Insert) and component row buttons (Place, Replace). Use when modifying button states, colors, labels, tab visibility, or page interaction behavior. Must review and update these tables before making changes.
Canonical naming for all Convey UI parts, features, and concepts. Reference when discussing, documenting, or writing code for any part of the app. Ensures consistent terminology across humans and AI agents.
Build panel UI components that live-preview Tailwind className changes in the user's app via WebSocket. Use when creating any control (dropdown, scrubber, color picker, toggle, etc.) that lets users hover/scrub values before committing. Covers the preview/revert/stage lifecycle, the onHover/onLeave prop contract, and the focus-trap pattern that prevents preview leaks.
Debug and fix failing Playwright E2E tests. Use when tests fail, when asked to fix failing tests, or when investigating test failures. Analyzes test output, screenshots, error context, and uses Playwright MCP to identify root causes.
Canonical terminology for Tailwind CSS concepts used throughout the codebase. Reference this skill to ensure consistent naming in code, docs, and conversation.