agentic-loop 3.14.1 → 3.14.2

package/.claude/skills/idea/SKILL.md

@@ -64,6 +64,12 @@ Help the user flesh out the idea through conversation:
 - Caching needed? How fresh must data be?
 - Database indexes: What will be queried/sorted frequently?
 
+**Migration/Refactoring (IMPORTANT - ask if moving or restructuring code):**
+- Source paths: Where does the code currently live?
+- Destination paths: Where should it end up? (be explicit, not vague)
+- Phases: What's the logical order? (move files → update imports → verify)
+- Verification: What commands prove each phase worked?
+
 ### Step 3: Summarize Before Writing
 
 When you have enough information, summarize what you've learned:
@@ -132,6 +138,36 @@ Once the user confirms, write the idea file:
    - **Caching**: What can be cached? For how long?
    - **Database**: What indexes are needed?
 
+   ## Migration Mapping (if moving/restructuring code)
+   For refactoring or migration tasks, explicitly map source to destination:
+
+   | Source | Destination |
+   |--------|-------------|
+   | `~/Sites/old-project/src/` | `apps/new-location/src/` |
+   | `~/Sites/old-project/tests/` | `apps/new-location/tests/` |
+
+   ## Phases & Verification
+   Break complex work into phases with explicit verification commands:
+
+   ### Phase 1: [Name]
+   **What:** Description of what this phase accomplishes
+   **Exit Criteria:**
+   ```bash
+   # These commands must pass before phase is complete
+   test -d apps/new-location/src
+   cd apps/new-location && uv run pytest -x
+   cd apps/new-location && npm run build
+   ```
+
+   ### Phase 2: [Name]
+   **What:** Description
+   **Exit Criteria:**
+   ```bash
+   # Verification commands for phase 2
+   docker-compose config | grep -q 'service-name:'
+   curl -s http://localhost:8000/health | jq -e '.status == "ok"'
+   ```
+
    ## UI Mockup (if applicable)
    ```
    ┌─────────────────────────────────┐
@@ -190,6 +226,26 @@ A good idea file has:
 - **Specific solution** - Not vague ("improve UX") but concrete ("add inline validation")
 - **Scope boundaries** - What's explicitly out of scope?
 - **Architecture hints** - Where do files go? What patterns to follow?
+- **Verification commands** - How do we know it worked? (executable commands, not prose)
+
+### Migration/Refactoring Ideas
+
+For ideas that involve moving or restructuring code, MUST include:
+
+1. **Explicit path mapping** - Source → Destination for every directory
+   ```
+   ❌ "Move GOPA to apps folder"
+   ✅ "~/Sites/gopa/src/gopa/ → apps/gopa/src/gopa/"
+   ```
+
+2. **Phase-based verification** - Each phase has exit criteria with commands
+   ```
+   ❌ "Verify everything still works"
+   ✅ "cd apps/gopa && uv run pytest -x && uv run python -c 'from gopa.server import mcp'"
+   ```
+
+3. **Order of operations** - What must happen before what?
+   - Move files → Update imports → Update configs → Verify
 
 ### ASCII Art for UI
 

package/.claude/skills/prd/SKILL.md

@@ -156,6 +156,7 @@ Does acceptanceCriteria include:
 - Does `contextFiles` include the idea file (has ASCII mockups)?
 - Does `contextFiles` include styleguide (if exists)?
 - Is `testUrl` set?
+- Is `mcp` set to `["playwright", "devtools"]`?
 
 **Fix any issues you find:**
 
@@ -168,6 +169,7 @@ Does acceptanceCriteria include:
 | List endpoint missing pagination | Add pagination criteria to acceptanceCriteria |
 | Frontend missing contextFiles | Add idea file + styleguide paths |
 | Frontend missing testUrl | Add URL from config |
+| Frontend missing mcp | Add `"mcp": ["playwright", "devtools"]` |
 
 ### Step 7: Reorder if Needed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-loop",
-  "version": "3.14.1",
+  "version": "3.14.2",
   "description": "Autonomous AI coding loop - PRD-driven development with Claude Code",
   "author": "Allie Jones <allie@allthrive.ai>",
   "license": "MIT",

package/ralph/prd-check.sh

@@ -282,7 +282,7 @@ _validate_and_fix_stories() {
 
   # Issue counters (bash 3.2 compatible - no associative arrays)
   local cnt_no_tests=0 cnt_backend_curl=0 cnt_backend_contract=0
-  local cnt_frontend_tsc=0 cnt_frontend_url=0 cnt_frontend_context=0
+  local cnt_frontend_tsc=0 cnt_frontend_url=0 cnt_frontend_context=0 cnt_frontend_mcp=0
   local cnt_auth_security=0 cnt_list_pagination=0 cnt_prose_steps=0
   local cnt_migration_prereq=0 cnt_naming_convention=0 cnt_bare_pytest=0
 
@@ -355,7 +355,7 @@ _validate_and_fix_stories() {
       fi
     fi
 
-    # Check 3: Frontend needs testUrl and contextFiles
+    # Check 3: Frontend needs testUrl, contextFiles, and mcp
     if [[ "$story_type" == "frontend" ]]; then
       local has_url
       has_url=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testUrl // empty' "$prd_file")
@@ -370,6 +370,14 @@ _validate_and_fix_stories() {
         story_issues+="missing contextFiles, "
         cnt_frontend_context=$((cnt_frontend_context + 1))
       fi
+
+      # Frontend must have mcp tools for browser verification
+      local mcp_tools
+      mcp_tools=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .mcp // [] | length' "$prd_file")
+      if [[ "$mcp_tools" == "0" ]]; then
+        story_issues+="missing mcp (browser tools), "
+        cnt_frontend_mcp=$((cnt_frontend_mcp + 1))
+      fi
     fi
 
     # Check 4: Auth stories need security criteria
@@ -442,6 +450,7 @@ _validate_and_fix_stories() {
     [[ $cnt_frontend_tsc -gt 0 ]] && echo "    ${cnt_frontend_tsc}x frontend: add tsc/playwright"
     [[ $cnt_frontend_url -gt 0 ]] && echo "    ${cnt_frontend_url}x frontend: add testUrl"
     [[ $cnt_frontend_context -gt 0 ]] && echo "    ${cnt_frontend_context}x frontend: add contextFiles"
+    [[ $cnt_frontend_mcp -gt 0 ]] && echo "    ${cnt_frontend_mcp}x frontend: add mcp browser tools"
     [[ $cnt_auth_security -gt 0 ]] && echo "    ${cnt_auth_security}x auth: add security criteria"
     [[ $cnt_list_pagination -gt 0 ]] && echo "    ${cnt_list_pagination}x list: add pagination"
     [[ $cnt_migration_prereq -gt 0 ]] && echo "    ${cnt_migration_prereq}x migration: add prerequisites (DB reset)"
@@ -467,27 +476,41 @@ _fix_stories_with_claude() {
   local prd_file="$1"
   local issues="$2"
 
+  # Read config values for context
+  local config_file="$RALPH_DIR/config.json"
+  local backend_url="" frontend_url=""
+  if [[ -f "$config_file" ]]; then
+    backend_url=$(jq -r '.urls.backend // .api.baseUrl // "http://localhost:8000"' "$config_file" 2>/dev/null)
+    frontend_url=$(jq -r '.urls.frontend // .playwright.baseUrl // "http://localhost:3000"' "$config_file" 2>/dev/null)
+  fi
+
   local fix_prompt="Enhance test coverage for these stories. Output the COMPLETE updated prd.json.
 
 STORIES TO OPTIMIZE:
 $issues
 
+CONFIG VALUES (use these):
+- Backend URL: $backend_url (use as {config.urls.backend} in testSteps)
+- Frontend URL: $frontend_url (use as {config.urls.frontend} in testUrl)
+
 RULES:
 1. Backend stories MUST have testSteps with curl commands that hit real endpoints
    Example: curl -s -X POST {config.urls.backend}/api/users -d '...' | jq -e '.id'
 2. Backend stories MUST have apiContract with endpoint, request, response
-3. Frontend stories MUST have testUrl set to {config.urls.frontend}/page
+3. Frontend stories MUST have testUrl set to {config.urls.frontend}/[page-path]
+   - Derive page path from story title (e.g., 'login form' → '/login', 'dashboard' → '/dashboard')
 4. Frontend stories MUST have contextFiles array (include idea file path from originalContext)
-5. Auth stories MUST have security acceptanceCriteria:
+5. Frontend stories MUST have mcp array with browser tools: [\"playwright\", \"devtools\"]
+6. Auth stories MUST have security acceptanceCriteria:
    - Passwords hashed with bcrypt (cost 10+)
    - Passwords NEVER in API responses
    - Rate limiting on login attempts
-6. List endpoints MUST have pagination acceptanceCriteria:
+7. List endpoints MUST have pagination acceptanceCriteria:
    - Returns paginated results (max 100 per page)
    - Accepts ?page=N&limit=N query params
-7. Migration stories (creating alembic/versions, migrations/, or modifying models) MUST have prerequisites:
+8. Migration stories (creating alembic/versions, migrations/, or modifying models) MUST have prerequisites:
    Example: \"prerequisites\": [{\"name\": \"Reset test DB\", \"command\": \"npm run db:reset:test\", \"when\": \"schema changes\"}]
-8. Frontend/general stories that consume APIs MUST have notes about naming conventions:
+9. Frontend/general stories that consume APIs MUST have notes about naming conventions:
    Example: \"notes\": \"Transform API responses from snake_case to camelCase. Create typed interfaces with camelCase properties and map: const user = { userName: data.user_name }\"
 
 CURRENT PRD:
@@ -591,7 +614,7 @@ validate_stories_quick() {
       fi
     fi
 
-    # Check 3: Frontend needs testUrl and contextFiles
+    # Check 3: Frontend needs testUrl, contextFiles, and mcp
     if [[ "$story_type" == "frontend" ]]; then
       local has_url
       has_url=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .testUrl // empty' "$prd_file")
@@ -600,6 +623,10 @@ validate_stories_quick() {
       local context_files
       context_files=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .contextFiles // [] | length' "$prd_file")
       [[ "$context_files" == "0" ]] && issues+="$story_id: missing contextFiles, "
+
+      local mcp_tools
+      mcp_tools=$(jq -r --arg id "$story_id" '.stories[] | select(.id==$id) | .mcp // [] | length' "$prd_file")
+      [[ "$mcp_tools" == "0" ]] && issues+="$story_id: missing mcp, "
     fi
 
     # Check 4: Auth stories need security criteria

package/ralph/setup/quick-setup.sh

@@ -202,20 +202,33 @@ configure_mcp() {
   # Create claude.json if it doesn't exist
   [[ ! -f "$claude_json" ]] && echo '{}' > "$claude_json"
 
-  # Check if chrome-devtools is already configured
-  if jq -e '.mcpServers["chrome-devtools"]' "$claude_json" > /dev/null 2>&1; then
-    echo -e "    ${DIM}Skipped: Chrome DevTools MCP already configured${NC}"
-    return
-  fi
+  local added_any=false
 
-  # Add Chrome DevTools MCP
-  local tmp=$(mktemp)
-  jq '.mcpServers["chrome-devtools"] = {
-    "command": "npx",
-    "args": ["-y", "@anthropic-ai/mcp-server-chrome-devtools@0.0.5"]
-  }' "$claude_json" > "$tmp" && mv "$tmp" "$claude_json"
+  # Add Playwright MCP if not configured (uses chromium + headless to avoid Chrome conflicts)
+  if ! jq -e '.mcpServers["playwright"]' "$claude_json" > /dev/null 2>&1; then
+    local tmp=$(mktemp)
+    jq '.mcpServers["playwright"] = {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium", "--headless"]
+    }' "$claude_json" > "$tmp" && mv "$tmp" "$claude_json"
+    echo -e "    ${GREEN}${EMOJI_CHECK}${NC} Playwright MCP configured"
+    added_any=true
+  else
+    echo -e "    ${DIM}Skipped: Playwright MCP already configured${NC}"
+  fi
 
-  echo -e "    ${GREEN}${EMOJI_CHECK}${NC} Chrome DevTools MCP configured"
+  # Add Chrome DevTools MCP if not configured
+  if ! jq -e '.mcpServers["chrome-devtools"]' "$claude_json" > /dev/null 2>&1; then
+    local tmp=$(mktemp)
+    jq '.mcpServers["chrome-devtools"] = {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-server-chrome-devtools@0.0.5"]
+    }' "$claude_json" > "$tmp" && mv "$tmp" "$claude_json"
+    echo -e "    ${GREEN}${EMOJI_CHECK}${NC} Chrome DevTools MCP configured"
+    added_any=true
+  else
+    echo -e "    ${DIM}Skipped: Chrome DevTools MCP already configured${NC}"
+  fi
 }
 
 show_completion() {

package/ralph/setup.sh

@@ -586,13 +586,14 @@ setup_mcp() {
   local added_any=false
 
   # Add Playwright MCP if not configured
+  # Uses chromium + headless to avoid conflicts with user's Chrome session
   if ! jq -e '.mcpServers["playwright"]' "$claude_json" > /dev/null 2>&1; then
     echo "Configuring MCP servers..."
     local tmp
     tmp=$(mktemp)
     jq '.mcpServers["playwright"] = {
       "command": "npx",
-      "args": ["-y", "@playwright/mcp@latest"]
+      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium", "--headless"]
     }' "$claude_json" > "$tmp" && mv "$tmp" "$claude_json"
     echo "  Added playwright MCP server (browser automation & testing)"
     added_any=true

package/templates/config/fastmcp.json

@@ -61,7 +61,12 @@
     "serverModule": "",
     "tools": [],
     "resources": [],
-    "prompts": []
+    "prompts": [],
+    "playwright": {
+      "browser": "chromium",
+      "headless": true,
+      "viewport": "1280x720"
+    }
   },
 
   "playwright": {

package/templates/config/fullstack.json

@@ -64,6 +64,14 @@
     "baseUrl": "http://localhost:3000"
   },
 
+  "mcp": {
+    "playwright": {
+      "browser": "chromium",
+      "headless": true,
+      "viewport": "1280x720"
+    }
+  },
+
   "verification": {
     "codeReviewEnabled": true,
     "browserEnabled": true,

package/templates/config/node.json

@@ -62,6 +62,14 @@
     "baseUrl": "http://localhost:3000"
   },
 
+  "mcp": {
+    "playwright": {
+      "browser": "chromium",
+      "headless": true,
+      "viewport": "1280x720"
+    }
+  },
+
   "verification": {
     "codeReviewEnabled": true,
     "browserEnabled": true,

package/templates/config/python.json

@@ -62,6 +62,14 @@
     "baseUrl": "http://localhost:8000"
   },
 
+  "mcp": {
+    "playwright": {
+      "browser": "chromium",
+      "headless": true,
+      "viewport": "1280x720"
+    }
+  },
+
   "verification": {
     "codeReviewEnabled": true,
     "browserEnabled": true,