@pennyfarthing/core 9.2.0 → 9.3.0

package/pennyfarthing-dist/workflows/interactive-debug/steps/step-01-connect.md

@@ -1,257 +0,0 @@
-# Step 1: Connect to Frontend
-
-<step-meta>
-number: 1
-name: connect
-gate: false
-</step-meta>
-
-<purpose>
-Detect what type of frontend is running (web server or Electron app), establish a Playwright MCP connection, and verify the connection works.
-</purpose>
-
-<instructions>
-1. READ the complete step file before taking any action
-2. Determine app type (Web vs Electron) using process detection
-3. If Web: verify server is running or start it
-4. If Electron: check CDP is enabled and get internal server URL
-5. Establish Playwright MCP connection
-6. Verify connection with snapshot
-7. Confirm app type, URL, and CDP port to user
-</instructions>
-
-<output>
-Report back:
-- App Type: {Web|Electron}
-- Connected to: {actual_url}
-- CDP Port: {port if Electron, "N/A" if Web}
-- Playwright MCP: Verified
-- Snapshot: [display snapshot or screenshot]
-- Ready to explore the UI
-</output>
-
-## Purpose
-
-Detect what type of frontend is running (web server or Electron app), establish a Playwright MCP connection, and verify the connection works.
-
-## Mandatory Execution Rules
-
-- READ the complete step file before taking any action
-- NEVER skip app type detection
-- VERIFY Playwright MCP connection before proceeding
-
-## App Type Detection
-
-**First, determine what we're connecting to:**
-
-### Check for Running Processes
-
-```bash
-# Check for web server on expected port
-lsof -ti:{dev_port} 2>/dev/null
-
-# Check for Electron processes (app name varies by project)
-ps aux | grep -i electron | grep -v grep
-```
-
-### Detection Logic
-
-| Signal | App Type |
-|--------|----------|
-| Web server on port, no Electron process | **Web** |
-| Electron process running | **Electron** |
-| Both detected | Ask user which to connect to |
-| Neither detected | Offer to start one |
-
----
-
-## Web Mode Connection
-
-For standard web servers (React, Vue, Next.js, Express, etc.):
-
-### If Server IS Running
-
-Present to user:
-
-> I detected a web server running on port {dev_port}.
->
-> - **[C] Connect** - Use the existing server at {dev_url}
-> - **[N] New** - Kill it and start fresh with `{dev_command}`
-> - **[U] URL** - Specify a different URL to connect to
-
-### If Server is NOT Running
-
-Present to user:
-
-> No web server detected on port {dev_port}.
->
-> - **[S] Start** - Launch with `{dev_command}`
-> - **[U] URL** - Specify a different URL (server running elsewhere)
-> - **[M] Manual** - I'll start the server myself, then continue
-
-**If user chooses Start:**
-- Run `{dev_command}` in background
-- Wait for server to be ready (poll {dev_url} with curl)
-- Confirm server is up before proceeding
-
-### Web Mode Playwright Connection
-
-Simply navigate to the URL:
-
-```
-Use mcp__playwright__browser_navigate to {dev_url}
-```
-
----
-
-## Electron Mode Connection
-
-Electron apps require **Chrome DevTools Protocol (CDP)** for Playwright to connect.
-
-### Check if CDP is Enabled
-
-```bash
-# Look for Electron process with remote-debugging-port
-ps aux | grep -i electron | grep "remote-debugging-port"
-
-# Check if CDP port (typically 9222) is listening
-lsof -i :9222 | grep LISTEN
-```
-
-### If CDP IS Enabled
-
-The Electron app was started with `--remote-debugging-port=9222`.
-
-**Connect via CDP:**
-
-```bash
-# Get the CDP endpoint
-curl -s http://localhost:9222/json/version
-```
-
-Then use Playwright to connect to `http://localhost:9222`.
-
-### If CDP is NOT Enabled
-
-Present to user:
-
-> I detected an Electron app running, but CDP (Chrome DevTools Protocol) is not enabled.
-> Playwright needs CDP to connect to Electron apps.
->
-> **To enable CDP, restart the Electron app with the `--remote-debugging-port` flag:**
->
-> Option 1: If using a justfile with `cdp` flag:
-> ```bash
-> # Kill current instance
-> pkill -f "electron"
->
-> # Restart with CDP enabled
-> just {app_name} cdp
-> ```
->
-> Option 2: Direct electron command:
-> ```bash
-> electron --remote-debugging-port=9222 dist/main.js
-> ```
->
-> Option 3: Add to package.json scripts:
-> ```json
-> "dev:cdp": "electron --remote-debugging-port=9222 dist/main.js"
-> ```
->
-> - **[R] Retry** - Check again after restarting
-> - **[W] Web Mode** - Switch to web mode instead (if available)
-> - **[M] Manual** - I'll configure CDP myself, then continue
-
-**STOP and wait for user to enable CDP before proceeding.**
-
-### Electron Mode Playwright Connection
-
-**Important:** Playwright MCP starts its own Chromium browser - it does NOT connect directly to
-existing CDP endpoints. The workaround is to connect to the Electron app's internal web server.
-
-Once CDP is confirmed:
-
-1. **Get the internal server URL from CDP:**
-   ```bash
-   curl -s http://localhost:9222/json/list
-   ```
-
-   Look for the `url` field in the response:
-   ```json
-   [{
-     "title": "Your App",
-     "url": "http://localhost:60178/",
-     "webSocketDebuggerUrl": "ws://localhost:9222/devtools/page/..."
-   }]
-   ```
-
-2. **Connect Playwright to the internal URL** (NOT the CDP port):
-   ```
-   Use mcp__playwright__browser_navigate to http://localhost:60178/
-   ```
-
-   The port varies each launch - always check `/json/list` first.
-
-3. **Verify connection** with `mcp__playwright__browser_snapshot`
-
-**Why this works:** Electron apps run an internal Express server for the renderer. CDP exposes
-the page list which includes this internal URL. Playwright connects to this URL and sees the
-same content as the Electron renderer.
-
-**Common mistake:** Navigating to `http://localhost:9222` shows the CDP index page, not your app.
-
----
-
-## Playwright MCP Verification
-
-**After establishing connection (either mode), verify Playwright MCP:**
-
-1. Use the Playwright MCP tool to navigate to the target URL
-2. Take a snapshot to confirm connection works
-
-**If Playwright MCP is not available:**
-
-> Playwright MCP is not configured. This workflow requires browser automation.
->
-> Please add the Playwright MCP server to your Claude settings and restart.
->
-> Example configuration (claude_desktop_config.json):
-> ```json
-> {
->   "mcpServers": {
->     "playwright": {
->       "command": "npx",
->       "args": ["@anthropic-ai/mcp-playwright"]
->     }
->   }
-> }
-> ```
-
-**STOP workflow if Playwright MCP unavailable.**
-
----
-
-## Output
-
-Confirm to user:
-
-```
-App Type: {Web|Electron}
-Connected to: {actual_url}
-CDP Port: {port if Electron, "N/A" if Web}
-Playwright MCP: Verified
-Snapshot: [display snapshot or screenshot]
-
-Ready to explore the UI.
-```
-
-## Collaboration Menu
-
-- **[C] Continue** - Proceed to UI exploration
-- **[R] Reconnect** - Try a different URL or restart app
-- **[T] Toggle Mode** - Switch between Electron/Web if both available
-
-## Next Step
-
-After user confirms connection, proceed to UI exploration.

package/pennyfarthing-dist/workflows/interactive-debug/steps/step-02-explore.md

@@ -1,107 +0,0 @@
-# Step 2: Explore UI
-
-<step-meta>
-number: 2
-name: explore
-gate: false
-</step-meta>
-
-<purpose>
-Systematically explore the UI to understand current state and identify areas of concern.
-</purpose>
-
-<instructions>
-1. USE Playwright MCP for all browser interactions
-2. Take initial screenshot of landing page
-3. Identify main navigation routes and sections
-4. Note any immediate issues (broken layouts, console errors, visual glitches)
-5. Ask user which area to focus on
-6. For each area: navigate, screenshot, interact, observe issues
-7. Document all findings with screenshots
-8. Present issues found and get user guidance on what to fix
-</instructions>
-
-<output>
-Report findings:
-- Current State: [screenshots showing landing page and main sections]
-- Main Sections: [list navigation items found]
-- Initial Observations: [notable findings]
-- Issues Found: [list with descriptions and severity]
-- Ready for user to select area or decide on fixes
-</output>
-
-## Purpose
-
-Systematically explore the UI to understand current state and identify areas of concern.
-
-## Mandatory Execution Rules
-
-- USE Playwright MCP for all browser interactions
-- TAKE screenshots at each major view
-- DOCUMENT what you observe
-- ASK user where to focus
-
-## Initial Exploration
-
-1. **Screenshot the landing page** - What do we see first?
-2. **Identify navigation** - What are the main routes/sections?
-3. **Note any immediate issues** - Broken layouts, console errors, visual glitches
-
-**Present findings:**
-
-```
-## Current State
-
-**Landing Page:** [screenshot]
-**Main Sections:** [list navigation items found]
-**Initial Observations:**
-- [anything notable - good or bad]
-```
-
-## User-Guided Focus
-
-Ask the user:
-
-> What area would you like to focus on?
->
-> I can see these sections: [list main navigation/features]
->
-> Or describe what you'd like me to look at.
-
-## Exploration Loop
-
-For each area the user wants to explore:
-
-1. **Navigate** - Use Playwright to go there
-2. **Screenshot** - Capture the current state
-3. **Interact** - Click buttons, fill forms, test interactions
-4. **Observe** - Note any issues:
-   - Visual bugs (misalignment, overflow, wrong colors)
-   - Interaction bugs (buttons don't work, forms fail)
-   - Console errors (check browser console if possible)
-   - UX issues (confusing flow, missing feedback)
-
-**Report findings as you go:**
-
-```
-## Exploring: [Section Name]
-
-**Screenshot:** [image]
-**Interactions Tested:** [what I clicked/typed]
-**Issues Found:**
-- [ ] Issue 1: [description]
-- [ ] Issue 2: [description]
-
-**No Issues:** [if clean]
-```
-
-## Collaboration Menu
-
-- **[E] Explore more** - Look at another section
-- **[I] Investigate issue** - Dig deeper into a specific problem
-- **[F] Fix issues** - Ready to start fixing what we found
-- **[D] Done** - No issues found, exit workflow
-
-## Next Step
-
-When user is ready to fix issues, proceed to the fix phase.

package/pennyfarthing-dist/workflows/interactive-debug/steps/step-03-fix.md

@@ -1,127 +0,0 @@
-# Step 3: Fix Issues
-
-<step-meta>
-number: 3
-name: fix
-gate: false
-</step-meta>
-
-<purpose>
-Work through identified issues one by one, making fixes and verifying them in the browser.
-</purpose>
-
-<instructions>
-1. FIX one issue at a time
-2. For each issue: Analyze (reproduce, locate source, understand why)
-3. Consult UX Designer perspective on visual/UX fixes
-4. Implement focused code changes
-5. VERIFY each fix in browser with Playwright MCP
-6. Take before/after screenshots
-7. Confirm with user that fix is correct
-8. TRACK all changes for final commit
-9. Repeat until all issues are fixed and verified
-</instructions>
-
-<output>
-Provide for each fix:
-- Issue description
-- Before screenshot
-- After screenshot
-- Files changed with descriptions
-- Confirmation from user
-- Running list of all changes made
-- Final summary of all fixes ready for commit
-</output>
-
-## Purpose
-
-Work through identified issues one by one, making fixes and verifying them in the browser.
-
-## Mandatory Execution Rules
-
-- FIX one issue at a time
-- VERIFY each fix in the browser before moving on
-- TRACK all changes made for the final commit
-- CONSULT UX Designer perspective on visual fixes
-
-## Issue Triage
-
-Present the issues found:
-
-```
-## Issues to Fix
-
-| # | Issue | Severity | Type |
-|---|-------|----------|------|
-| 1 | [description] | High/Med/Low | Visual/Interaction/UX |
-| 2 | [description] | High/Med/Low | Visual/Interaction/UX |
-...
-
-Which issue should we tackle first?
-```
-
-## Fix Loop
-
-For each issue:
-
-### 1. Analyze
-
-- **Reproduce** - Use Playwright to show the bug
-- **Locate** - Find the source file(s) responsible
-- **Understand** - Why is this happening?
-
-### 2. Consult UX Designer
-
-For visual/UX issues, apply UX Designer thinking:
-
-- Is this a one-off fix or a pattern problem?
-- Does the fix align with design system?
-- Are there accessibility implications?
-- Will this fix break other states (hover, focus, mobile)?
-
-### 3. Implement Fix
-
-- Make the code change
-- Keep changes minimal and focused
-
-### 4. Verify
-
-- Use Playwright to navigate back to the affected area
-- Take a screenshot showing the fix
-- Confirm with user:
-
-```
-## Fixed: [Issue Description]
-
-**Before:** [screenshot or description]
-**After:** [screenshot]
-**Files Changed:** [list]
-
-Does this look right?
-- **[Y] Yes** - Mark fixed, next issue
-- **[N] No** - Needs adjustment
-- **[R] Revert** - Undo this change
-```
-
-### 5. Track
-
-Maintain a running list:
-
-```
-## Changes Made
-
-- [ ] `src/components/Panel.css` - Fixed overflow on main panel
-- [ ] `src/components/Button.tsx` - Added missing click handler
-...
-```
-
-## Collaboration Menu
-
-- **[N] Next issue** - Move to the next issue
-- **[A] Add issue** - Found another issue while fixing
-- **[V] Verify all** - Re-check all fixes together
-- **[C] Commit** - All issues fixed, ready to commit
-
-## Next Step
-
-When all issues are fixed and verified, proceed to commit.

package/pennyfarthing-dist/workflows/interactive-debug/steps/step-04-commit.md

@@ -1,122 +0,0 @@
-# Step 4: Commit Changes
-
-<step-meta>
-number: 4
-name: commit
-gate: false
-</step-meta>
-
-<purpose>
-Roll up all fixes into a single chore commit using the `/chore` skill.
-</purpose>
-
-<instructions>
-1. REVIEW all changes before committing
-2. Present summary of all changes (issues fixed, files changed)
-3. Show git status output to verify no unintended changes
-4. Ask user to confirm ready to commit
-5. USE `/chore` skill to execute the commit
-6. VERIFY no unintended changes are staged
-7. Confirm commit succeeded with hash and message
-8. Offer options to push, debug more, or exit
-</instructions>
-
-<output>
-Provide:
-- Summary: Issues fixed count, files changed count
-- Changes table: File path and what was changed
-- Git status before commit
-- Commit hash
-- Commit message used
-- Post-commit status
-- Next steps offered to user
-</output>
-
-## Purpose
-
-Roll up all fixes into a single chore commit using the `/chore` skill.
-
-## Mandatory Execution Rules
-
-- REVIEW all changes before committing
-- USE `/chore` skill for the commit
-- VERIFY no unintended changes are staged
-
-## Pre-Commit Review
-
-Present summary of all changes:
-
-```
-## Debug Session Summary
-
-**Issues Fixed:** [count]
-**Files Changed:** [count]
-
-### Changes
-
-| File | Change |
-|------|--------|
-| `path/to/file.css` | Fixed overflow on main panel |
-| `path/to/file.tsx` | Added missing click handler |
-...
-
-### Git Status
-[show git status output]
-```
-
-Ask user to confirm:
-
-> Ready to commit these changes as a chore fix?
->
-> - **[C] Commit** - Bundle into chore commit
-> - **[R] Review** - Show me the diffs first
-> - **[S] Split** - These should be separate commits
-> - **[X] Cancel** - Don't commit yet
-
-## Commit Execution
-
-**Use the `/chore` skill to create the commit.**
-
-The chore skill will:
-1. Stage the relevant files
-2. Create a commit with appropriate message format
-3. Handle the Co-Authored-By trailer
-
-Suggested commit message format:
-
-```
-fix(ui): resolve visual bugs from debug session
-
-- Fixed [issue 1 brief description]
-- Fixed [issue 2 brief description]
-...
-
-Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
-```
-
-## Post-Commit
-
-After successful commit:
-
-```
-## Debug Session Complete
-
-**Commit:** [hash]
-**Message:** [commit message]
-**Files:** [count] files changed
-
-The fixes have been committed. You can:
-- Push to remote when ready
-- Continue with another debug session
-- Exit the workflow
-```
-
-## Collaboration Menu
-
-- **[P] Push** - Push to remote branch
-- **[D] Debug more** - Start another debug session (back to step 1)
-- **[X] Exit** - End workflow
-
-## Workflow Complete
-
-This concludes the interactive-debug workflow.

package/pennyfarthing-dist/workflows/interactive-debug/workflow.yaml

@@ -1,51 +0,0 @@
-# Interactive Debug Workflow - BikeLane Stepped Workflow
-#
-# Connect to a running frontend (web server or Electron app), use Playwright MCP
-# for browser automation, hunt bugs collaboratively with UX Designer, fix them,
-# and roll up into a chore commit.
-#
-# Supports two connection modes:
-#   - Web Mode: Standard web servers (React, Vue, Next.js, Express, etc.)
-#   - Electron Mode: Desktop apps via Chrome DevTools Protocol (CDP)
-#
-# Prerequisites:
-#   - Playwright MCP configured in Claude settings
-#   - For web: A running dev server or command to start one
-#   - For Electron: App started with --remote-debugging-port=9222
-#
-# Purpose: Interactive visual debugging session that produces committed fixes
-# Role: UX Designer leads visual inspection, Dev fixes issues
-# Output: Chore commit with all bug fixes rolled up
-
-workflow:
-  name: interactive-debug
-  description: |
-    Interactive debugging workflow that connects to your frontend via Playwright MCP.
-    Supports both web servers and Electron apps (via CDP). Collaboratively identifies
-    bugs with UX Designer, fixes them, and commits as a chore.
-  version: "1.0.0"
-  type: stepped
-
-  # Step configuration
-  steps:
-    path: ./steps/
-    pattern: step-*.md
-
-  # Variables available in step files
-  variables:
-    project_root: .
-    dev_command: npm run dev
-    dev_port: 3000
-    dev_url: http://localhost:3000
-    # Electron/CDP configuration (for Electron apps)
-    cdp_port: 9222
-    cdp_url: http://localhost:9222
-    app_name: app  # Used in `just {app_name} cdp` suggestion
-
-  # Agent assignment - UX Designer leads visual debugging
-  agent: ux-designer
-
-  # Triggers - when to suggest this workflow
-  triggers:
-    types: [interactive-debug, debug-ui, visual-debug, bug-hunt]
-    tags: [debug, visual, playwright, ux, bug-fix]