uv-suite 0.3.2 → 0.5.0

package/agents/claude-code/prototype-builder.md

@@ -44,6 +44,18 @@ For presentation-style output:
 - 16:9 aspect ratio for slides
 - PDF export via Puppeteer with `printBackground: true`
 
+## Visual Verification (Playwright)
+
+If the Playwright MCP server is available, use it to verify the prototype after building:
+
+1. Start the dev server: `npm run dev`
+2. Use Playwright to navigate to the prototype URL
+3. Verify key screens render correctly at mobile (375px), tablet (768px), and desktop (1920px)
+4. Check that navigation works between pages
+5. Report any visual issues found
+
+This catches broken layouts, missing content, and navigation bugs before the human sees the prototype.
+
 ## Rules
 
 - Always use React + Vite + Tailwind as the base stack

package/agents/claude-code/test-writer.md

@@ -42,6 +42,15 @@ Never generate these patterns:
 - Tests with no meaningful assertions
 - Tests that test framework behavior
 
+## E2E Tests (Playwright)
+
+If the Playwright MCP server is available and the project has a UI:
+
+1. Use Playwright to write e2e tests that verify user flows in a real browser
+2. Test at mobile (375px) and desktop (1920px) viewports
+3. Use accessibility-tree selectors (getByRole, getByLabel) over CSS selectors
+4. Write Playwright tests in the project's test directory alongside unit tests
+
 ## Rules
 
 - Match existing test patterns in the project

package/hooks/context-warning.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+# REMOVED — status line config is the better approach for context warnings.
+# This file is a no-op placeholder.
+exit 0

package/install.sh

@@ -75,11 +75,32 @@ mkdir -p "$TARGET_DIR/hooks"
 mkdir -p "$TARGET_DIR/rules"
 
 # --- Install agents (Claude Code subagent definitions) ---
-echo "Installing 10 agent definitions..."
+echo "Installing 10 Claude Code agent definitions..."
 cp "$UV_SUITE_DIR/agents/claude-code/"*.md "$TARGET_DIR/agents/"
 echo "  ✓ cartographer, spec-writer, architect, reviewer, test-writer"
 echo "  ✓ eval-writer, anti-slop-guard, prototype-builder, devops, security"
 
+# --- Install Codex agents (.codex/agents/*.toml + AGENTS.md) ---
+PROJECT_ROOT="$(dirname "$TARGET_DIR")"
+echo "Installing 10 Codex agent definitions..."
+mkdir -p "$PROJECT_ROOT/.codex/agents"
+cp "$UV_SUITE_DIR/agents/codex/"*.toml "$PROJECT_ROOT/.codex/agents/"
+
+# Create AGENTS.md for Codex (it reads this instead of CLAUDE.md)
+if [ ! -f "$PROJECT_ROOT/AGENTS.md" ]; then
+  cp "$PROJECT_ROOT/CLAUDE.md" "$PROJECT_ROOT/AGENTS.md" 2>/dev/null || touch "$PROJECT_ROOT/AGENTS.md"
+  echo "  ✓ AGENTS.md created (Codex reads this)"
+else
+  echo "  ✓ AGENTS.md already exists"
+fi
+echo "  ✓ .codex/agents/*.toml installed"
+
+# --- Install Cursor rules (.cursor/rules/*.mdc) ---
+echo "Installing 10 Cursor rule definitions..."
+mkdir -p "$PROJECT_ROOT/.cursor/rules"
+cp "$UV_SUITE_DIR/agents/cursor/"*.mdc "$PROJECT_ROOT/.cursor/rules/"
+echo "  ✓ .cursor/rules/*.mdc installed"
+
 # --- Install skills (slash commands) ---
 echo "Installing 9 skills..."
 for skill_dir in "$UV_SUITE_DIR/skills/"*/; do
@@ -284,6 +305,26 @@ else
   fi
 fi
 
+# --- Register Playwright MCP server ---
+echo "Registering MCP servers..."
+if command -v claude &>/dev/null; then
+  # Check if playwright MCP is already registered
+  if claude mcp list 2>/dev/null | grep -q "playwright"; then
+    echo "  ✓ Playwright MCP (already registered)"
+  else
+    echo "  Registering Playwright MCP (browser automation for Prototype Builder + Test Writer)..."
+    claude mcp add playwright -- npx @playwright/mcp@latest 2>/dev/null
+    if [ $? -eq 0 ]; then
+      echo "  ✓ Playwright MCP registered"
+    else
+      echo "  ✗ Playwright MCP failed — register manually: claude mcp add playwright -- npx @playwright/mcp@latest"
+    fi
+  fi
+else
+  echo "  · Claude Code CLI not found — skipping MCP registration"
+  echo "    Register manually after installing Claude Code: claude mcp add playwright -- npx @playwright/mcp@latest"
+fi
+
 # --- Write UV Suite context to CLAUDE.md ---
 if [ "$INSTALL_MODE" = "project" ]; then
   PROJECT_ROOT="$(dirname "$TARGET_DIR")"
@@ -363,15 +404,17 @@ cat << 'HOOKS'
 HOOKS
 fi)
 
-### Personas
+### Context management
+
+If the conversation is getting long, proactively suggest running /compact or starting a new session. Use /cost to check token usage. The user's status line shows context window usage.
 
-Switch persona by starting a new session:
+### Launching sessions
 
 \`\`\`
-./uv.sh spike    # Research & docs (Opus, max)
-./uv.sh sport    # New projects (Sonnet, high)
-./uv.sh pro      # Production code (all hooks, all guardrails)
-./uv.sh auto     # Fully autonomous (max, everything approved)
+uv claude pro     # Claude Code, Professional persona
+uv claude auto    # Claude Code, Auto persona
+uv codex pro      # OpenAI Codex, Professional persona
+uv codex sport    # OpenAI Codex, Sport persona
 \`\`\`
 CLAUDEMD
 
@@ -392,14 +435,11 @@ echo "╚═══════════════════════
 echo ""
 echo "What was installed:"
 echo ""
-echo "  AGENTS (10)     $TARGET_DIR/agents/*.md"
-echo "  SKILLS (9)      $TARGET_DIR/skills/*/SKILL.md"
-echo "  HOOKS (4)       $TARGET_DIR/hooks/*.sh"
-if [ "$PERSONA" = "professional" ] || [ "$PERSONA" = "auto" ]; then
-echo "  GUARDRAILS (6)  $TARGET_DIR/rules/*.md"
-fi
-echo "  PERSONAS (4)    $TARGET_DIR/personas/*.json"
-echo "  SETTINGS        $TARGET_DIR/settings.json"
+echo "  Claude Code     .claude/agents/*.md + skills/ + hooks/ + rules/"
+echo "  Codex           .codex/agents/*.toml + AGENTS.md"
+echo "  Cursor          .cursor/rules/*.mdc"
+echo "  Personas (4)    .claude/personas/*.json"
+echo "  Launcher        ./uv.sh"
 echo ""
 
 echo "Available slash commands:"
@@ -450,17 +490,11 @@ echo "Can write docs and analysis files. Cannot edit existing code, commit, or p
 fi
 
 echo ""
-echo "Start a session with a persona:"
-echo ""
-echo "  ./uv.sh spike        Research & docs (Opus, max, doc-slop checked)"
-echo "  ./uv.sh sport        New projects (Sonnet, high, lint only)"
-echo "  ./uv.sh pro          Production code (all hooks, all guardrails)"
-echo "  ./uv.sh auto         Fully autonomous (max effort, everything approved)"
-echo "  ./uv.sh              Defaults to Professional"
-echo ""
-echo "Or launch Claude directly with a persona:"
+echo "Start a session:"
 echo ""
-echo "  claude --settings .claude/personas/sport.json"
-echo "  claude --settings .claude/personas/professional.json"
-echo "  claude --settings .claude/personas/auto.json"
-echo "  claude --settings .claude/personas/spike.json"
+echo "  ./uv.sh claude pro      Claude Code, Professional"
+echo "  ./uv.sh claude auto     Claude Code, Auto"
+echo "  ./uv.sh codex pro       Codex, Professional"
+echo "  ./uv.sh codex auto      Codex, Auto"
+echo "  ./uv.sh pro             Shorthand (defaults to Claude Code)"
+echo "  ./uv.sh                 Claude Code, Professional"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uv-suite",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Portable framework for AI-assisted software development. 10 agents, 9 skills, 5 hooks, 4 personas. Works with Claude Code, Cursor, and Codex.",
   "author": "Utsav Anand",
   "license": "MIT",

package/uv.sh

@@ -1,56 +1,122 @@
 #!/bin/bash
-# UV Suite — Session launcher
-# Starts a Claude Code session with the specified persona.
+# UV Suite — Unified session launcher
+# Starts Claude Code or Codex with the specified persona.
 #
 # Usage:
-#   uv spike              Start a Spike session (research & docs)
-#   uv sport              Start a Sport session (fast, new projects)
-#   uv pro                Start a Professional session (production code)
-#   uv auto               Start an Auto session (fully autonomous)
-#   uv                    Start with default (Professional)
+#   uv claude pro         Claude Code, Professional persona
+#   uv claude auto        Claude Code, Auto persona
+#   uv codex sport        OpenAI Codex, Sport persona
+#   uv codex pro          OpenAI Codex, Professional persona
+#   uv pro                Shorthand — defaults to Claude Code
+#   uv                    Claude Code, Professional persona
 
-PERSONA="${1:-pro}"
-shift 2>/dev/null  # consume the persona arg, pass the rest to claude
+TOOL=""
+PERSONA=""
 
-# Resolve persona to settings file
-case "$PERSONA" in
-  spike)
-    SETTINGS=".claude/personas/spike.json"
-    LABEL="UV Spike — research & docs (Opus, max effort, doc-slop checked)"
+# Parse arguments
+case "$1" in
+  claude|codex)
+    TOOL="$1"
+    PERSONA="${2:-pro}"
+    shift 2 2>/dev/null
     ;;
-  sport)
-    SETTINGS=".claude/personas/sport.json"
-    LABEL="UV Sport — lightweight (Sonnet, high effort, lint only)"
+  spike|sport|pro|professional|auto)
+    TOOL="claude"
+    PERSONA="$1"
+    shift
     ;;
-  pro|professional)
-    SETTINGS=".claude/personas/professional.json"
-    LABEL="UV Professional — full rigor (all hooks, all guardrails)"
+  --help|-h)
+    echo ""
+    echo "  uv — UV Suite session launcher"
+    echo ""
+    echo "  Usage:"
+    echo "    uv claude <persona>    Start Claude Code with persona"
+    echo "    uv codex <persona>     Start OpenAI Codex with persona"
+    echo "    uv <persona>           Shorthand for uv claude <persona>"
+    echo "    uv                     Defaults to uv claude pro"
+    echo ""
+    echo "  Personas:"
+    echo "    spike    Research & docs (Opus, max effort)"
+    echo "    sport    New projects (Sonnet, high effort)"
+    echo "    pro      Production code (all hooks, all guardrails)"
+    echo "    auto     Fully autonomous (max effort, everything approved)"
+    echo ""
+    exit 0
+    ;;
+  "")
+    TOOL="claude"
+    PERSONA="pro"
     ;;
-  auto)
-    SETTINGS=".claude/personas/auto.json"
-    LABEL="UV Auto — autonomous (max effort, everything approved)"
+  *)
+    echo "Unknown argument: $1"
+    echo "Usage: uv [claude|codex] [spike|sport|pro|auto]"
+    exit 1
     ;;
+esac
+
+# Normalize persona name
+case "$PERSONA" in
+  pro|professional) PERSONA="professional" ;;
+  spike|sport|auto) ;; # already correct
   *)
     echo "Unknown persona: $PERSONA"
-    echo ""
-    echo "Usage: uv [spike|sport|pro|auto]"
-    echo ""
-    echo "  spike   Research & documentation (Opus, max, doc-slop hook)"
-    echo "  sport   New projects, prototyping (Sonnet, high, lint only)"
-    echo "  pro     Production code (all hooks, all guardrails, human-gated)"
-    echo "  auto    Fully autonomous (max effort, everything auto-approved)"
-    echo ""
-    echo "  uv      Defaults to 'pro'"
+    echo "Available: spike, sport, pro, auto"
     exit 1
     ;;
 esac
 
-if [ ! -f "$SETTINGS" ]; then
-  echo "Settings file not found: $SETTINGS"
-  echo "Run install.sh first to set up UV Suite in this project."
-  exit 1
-fi
+# Persona labels
+case "$PERSONA" in
+  spike)        LABEL="Spike — research & docs (Opus, max)" ;;
+  sport)        LABEL="Sport — lightweight (Sonnet, high)" ;;
+  professional) LABEL="Professional — full rigor (all hooks, all guardrails)" ;;
+  auto)         LABEL="Auto — autonomous (max, everything approved)" ;;
+esac
+
+SETTINGS=".claude/personas/$PERSONA.json"
 
-echo "$LABEL"
-echo ""
-exec claude --settings "$SETTINGS" "$@"
+if [ "$TOOL" = "claude" ]; then
+  # --- Claude Code ---
+  if ! command -v claude &>/dev/null; then
+    echo "Error: claude not found. Install Claude Code first."
+    exit 1
+  fi
+
+  if [ ! -f "$SETTINGS" ]; then
+    echo "Error: $SETTINGS not found. Run 'npx uv-suite install' first."
+    exit 1
+  fi
+
+  echo "UV Suite | Claude Code | $LABEL"
+  echo ""
+  exec claude --settings "$SETTINGS" "$@"
+
+elif [ "$TOOL" = "codex" ]; then
+  # --- OpenAI Codex ---
+  if ! command -v codex &>/dev/null; then
+    echo "Error: codex not found. Install OpenAI Codex first."
+    echo "  npm install -g @openai/codex"
+    exit 1
+  fi
+
+  # Codex doesn't have --settings, but reads AGENTS.md and .codex/agents/
+  # We can pass model and approval mode based on persona
+  case "$PERSONA" in
+    spike)
+      CODEX_ARGS="--model o3 --approval-mode suggest"
+      ;;
+    sport)
+      CODEX_ARGS="--approval-mode auto-edit"
+      ;;
+    professional)
+      CODEX_ARGS="--approval-mode suggest"
+      ;;
+    auto)
+      CODEX_ARGS="--approval-mode full-auto"
+      ;;
+  esac
+
+  echo "UV Suite | Codex | $LABEL"
+  echo ""
+  exec codex $CODEX_ARGS "$@"
+fi