diff --git a/.agents/skills/agent-browser/SKILL.md b/.agents/skills/agent-browser/SKILL.md deleted file mode 100644 index f07d3f70b..000000000 --- a/.agents/skills/agent-browser/SKILL.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -name: agent-browser -description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. -allowed-tools: Bash(agent-browser:*) ---- - -# Browser Automation with agent-browser - -## Core Workflow - -Every browser automation follows this pattern: - -1. **Navigate**: `agent-browser open ` -2. **Snapshot**: `agent-browser snapshot -i` (get element refs like `@e1`, `@e2`) -3. **Interact**: Use refs to click, fill, select -4. **Re-snapshot**: After navigation or DOM changes, get fresh refs - -```bash -agent-browser open https://example.com/form -agent-browser snapshot -i -# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit" - -agent-browser fill @e1 "user@example.com" -agent-browser fill @e2 "password123" -agent-browser click @e3 -agent-browser wait --load networkidle -agent-browser snapshot -i # Check result -``` - -## Essential Commands - -```bash -# Navigation -agent-browser open # Navigate (aliases: goto, navigate) -agent-browser close # Close browser - -# Snapshot -agent-browser snapshot -i # Interactive elements with refs (recommended) -agent-browser snapshot -s "#selector" # Scope to CSS selector - -# Interaction (use @refs from snapshot) -agent-browser click @e1 # Click element -agent-browser fill @e2 "text" # Clear and type text -agent-browser type @e2 "text" # Type without clearing -agent-browser select @e1 "option" # Select dropdown option -agent-browser check @e1 # Check checkbox -agent-browser press Enter # Press key -agent-browser scroll down 500 # Scroll page - -# Get information -agent-browser get text @e1 # Get element text -agent-browser get url # Get current URL -agent-browser get title # Get page title - -# Wait -agent-browser wait @e1 # Wait for element -agent-browser wait --load networkidle # Wait for network idle -agent-browser wait --url "**/page" # Wait for URL pattern -agent-browser wait 2000 # Wait milliseconds - -# Capture -agent-browser screenshot # Screenshot to temp dir -agent-browser screenshot --full # Full page screenshot -agent-browser pdf output.pdf # Save as PDF -``` - -## Common Patterns - -### Form Submission - -```bash -agent-browser open https://example.com/signup -agent-browser snapshot -i -agent-browser fill @e1 "Jane Doe" -agent-browser fill @e2 "jane@example.com" -agent-browser select @e3 "California" -agent-browser check @e4 -agent-browser click @e5 -agent-browser wait --load networkidle -``` - -### Authentication with State Persistence - -```bash -# Login once and save state -agent-browser open https://app.example.com/login -agent-browser snapshot -i -agent-browser fill @e1 "$USERNAME" -agent-browser fill @e2 "$PASSWORD" -agent-browser click @e3 -agent-browser wait --url "**/dashboard" -agent-browser state save auth.json - -# Reuse in future sessions -agent-browser state load auth.json -agent-browser open https://app.example.com/dashboard -``` - -### Data Extraction - -```bash -agent-browser open https://example.com/products -agent-browser snapshot -i -agent-browser get text @e5 # Get specific element text -agent-browser get text body > page.txt # Get all page text - -# JSON output for parsing -agent-browser snapshot -i --json -agent-browser get text @e1 --json -``` - -### Parallel Sessions - -```bash -agent-browser --session site1 open https://site-a.com -agent-browser --session site2 open https://site-b.com - -agent-browser --session site1 snapshot -i -agent-browser --session site2 snapshot -i - -agent-browser session list -``` - -### Visual Browser (Debugging) - -```bash -agent-browser --headed open https://example.com -agent-browser highlight @e1 # Highlight element -agent-browser record start demo.webm # Record session -``` - -### iOS Simulator (Mobile Safari) - -```bash -# List available iOS simulators -agent-browser device list - -# Launch Safari on a specific device -agent-browser -p ios --device "iPhone 16 Pro" open https://example.com - -# Same workflow as desktop - snapshot, interact, re-snapshot -agent-browser -p ios snapshot -i -agent-browser -p ios tap @e1 # Tap (alias for click) -agent-browser -p ios fill @e2 "text" -agent-browser -p ios swipe up # Mobile-specific gesture - -# Take screenshot -agent-browser -p ios screenshot mobile.png - -# Close session (shuts down simulator) -agent-browser -p ios close -``` - -**Requirements:** macOS with Xcode, Appium (`npm install -g appium && appium driver install xcuitest`) - -**Real devices:** Works with physical iOS devices if pre-configured. Use `--device ""` where UDID is from `xcrun xctrace list devices`. - -## Ref Lifecycle (Important) - -Refs (`@e1`, `@e2`, etc.) are invalidated when the page changes. Always re-snapshot after: - -- Clicking links or buttons that navigate -- Form submissions -- Dynamic content loading (dropdowns, modals) - -```bash -agent-browser click @e5 # Navigates to new page -agent-browser snapshot -i # MUST re-snapshot -agent-browser click @e1 # Use new refs -``` - -## Semantic Locators (Alternative to Refs) - -When refs are unavailable or unreliable, use semantic locators: - -```bash -agent-browser find text "Sign In" click -agent-browser find label "Email" fill "user@test.com" -agent-browser find role button click --name "Submit" -agent-browser find placeholder "Search" type "query" -agent-browser find testid "submit-btn" click -``` - -## Deep-Dive Documentation - -| Reference | When to Use | -|-----------|-------------| -| [references/commands.md](references/commands.md) | Full command reference with all options | -| [references/snapshot-refs.md](references/snapshot-refs.md) | Ref lifecycle, invalidation rules, troubleshooting | -| [references/session-management.md](references/session-management.md) | Parallel sessions, state persistence, concurrent scraping | -| [references/authentication.md](references/authentication.md) | Login flows, OAuth, 2FA handling, state reuse | -| [references/video-recording.md](references/video-recording.md) | Recording workflows for debugging and documentation | -| [references/proxy-support.md](references/proxy-support.md) | Proxy configuration, geo-testing, rotating proxies | - -## Ready-to-Use Templates - -| Template | Description | -|----------|-------------| -| [templates/form-automation.sh](templates/form-automation.sh) | Form filling with validation | -| [templates/authenticated-session.sh](templates/authenticated-session.sh) | Login once, reuse state | -| [templates/capture-workflow.sh](templates/capture-workflow.sh) | Content extraction with screenshots | - -```bash -./templates/form-automation.sh https://example.com/form -./templates/authenticated-session.sh https://app.example.com/login -./templates/capture-workflow.sh https://example.com ./output -``` diff --git a/.agents/skills/agent-browser/references/authentication.md b/.agents/skills/agent-browser/references/authentication.md deleted file mode 100644 index 12ef5e41b..000000000 --- a/.agents/skills/agent-browser/references/authentication.md +++ /dev/null @@ -1,202 +0,0 @@ -# Authentication Patterns - -Login flows, session persistence, OAuth, 2FA, and authenticated browsing. - -**Related**: [session-management.md](session-management.md) for state persistence details, [SKILL.md](../SKILL.md) for quick start. - -## Contents - -- [Basic Login Flow](#basic-login-flow) -- [Saving Authentication State](#saving-authentication-state) -- [Restoring Authentication](#restoring-authentication) -- [OAuth / SSO Flows](#oauth--sso-flows) -- [Two-Factor Authentication](#two-factor-authentication) -- [HTTP Basic Auth](#http-basic-auth) -- [Cookie-Based Auth](#cookie-based-auth) -- [Token Refresh Handling](#token-refresh-handling) -- [Security Best Practices](#security-best-practices) - -## Basic Login Flow - -```bash -# Navigate to login page -agent-browser open https://app.example.com/login -agent-browser wait --load networkidle - -# Get form elements -agent-browser snapshot -i -# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Sign In" - -# Fill credentials -agent-browser fill @e1 "user@example.com" -agent-browser fill @e2 "password123" - -# Submit -agent-browser click @e3 -agent-browser wait --load networkidle - -# Verify login succeeded -agent-browser get url # Should be dashboard, not login -``` - -## Saving Authentication State - -After logging in, save state for reuse: - -```bash -# Login first (see above) -agent-browser open https://app.example.com/login -agent-browser snapshot -i -agent-browser fill @e1 "user@example.com" -agent-browser fill @e2 "password123" -agent-browser click @e3 -agent-browser wait --url "**/dashboard" - -# Save authenticated state -agent-browser state save ./auth-state.json -``` - -## Restoring Authentication - -Skip login by loading saved state: - -```bash -# Load saved auth state -agent-browser state load ./auth-state.json - -# Navigate directly to protected page -agent-browser open https://app.example.com/dashboard - -# Verify authenticated -agent-browser snapshot -i -``` - -## OAuth / SSO Flows - -For OAuth redirects: - -```bash -# Start OAuth flow -agent-browser open https://app.example.com/auth/google - -# Handle redirects automatically -agent-browser wait --url "**/accounts.google.com**" -agent-browser snapshot -i - -# Fill Google credentials -agent-browser fill @e1 "user@gmail.com" -agent-browser click @e2 # Next button -agent-browser wait 2000 -agent-browser snapshot -i -agent-browser fill @e3 "password" -agent-browser click @e4 # Sign in - -# Wait for redirect back -agent-browser wait --url "**/app.example.com**" -agent-browser state save ./oauth-state.json -``` - -## Two-Factor Authentication - -Handle 2FA with manual intervention: - -```bash -# Login with credentials -agent-browser open https://app.example.com/login --headed # Show browser -agent-browser snapshot -i -agent-browser fill @e1 "user@example.com" -agent-browser fill @e2 "password123" -agent-browser click @e3 - -# Wait for user to complete 2FA manually -echo "Complete 2FA in the browser window..." -agent-browser wait --url "**/dashboard" --timeout 120000 - -# Save state after 2FA -agent-browser state save ./2fa-state.json -``` - -## HTTP Basic Auth - -For sites using HTTP Basic Authentication: - -```bash -# Set credentials before navigation -agent-browser set credentials username password - -# Navigate to protected resource -agent-browser open https://protected.example.com/api -``` - -## Cookie-Based Auth - -Manually set authentication cookies: - -```bash -# Set auth cookie -agent-browser cookies set session_token "abc123xyz" - -# Navigate to protected page -agent-browser open https://app.example.com/dashboard -``` - -## Token Refresh Handling - -For sessions with expiring tokens: - -```bash -#!/bin/bash -# Wrapper that handles token refresh - -STATE_FILE="./auth-state.json" - -# Try loading existing state -if [[ -f "$STATE_FILE" ]]; then - agent-browser state load "$STATE_FILE" - agent-browser open https://app.example.com/dashboard - - # Check if session is still valid - URL=$(agent-browser get url) - if [[ "$URL" == *"/login"* ]]; then - echo "Session expired, re-authenticating..." - # Perform fresh login - agent-browser snapshot -i - agent-browser fill @e1 "$USERNAME" - agent-browser fill @e2 "$PASSWORD" - agent-browser click @e3 - agent-browser wait --url "**/dashboard" - agent-browser state save "$STATE_FILE" - fi -else - # First-time login - agent-browser open https://app.example.com/login - # ... login flow ... -fi -``` - -## Security Best Practices - -1. **Never commit state files** - They contain session tokens - ```bash - echo "*.auth-state.json" >> .gitignore - ``` - -2. **Use environment variables for credentials** - ```bash - agent-browser fill @e1 "$APP_USERNAME" - agent-browser fill @e2 "$APP_PASSWORD" - ``` - -3. **Clean up after automation** - ```bash - agent-browser cookies clear - rm -f ./auth-state.json - ``` - -4. **Use short-lived sessions for CI/CD** - ```bash - # Don't persist state in CI - agent-browser open https://app.example.com/login - # ... login and perform actions ... - agent-browser close # Session ends, nothing persisted - ``` diff --git a/.agents/skills/agent-browser/references/commands.md b/.agents/skills/agent-browser/references/commands.md deleted file mode 100644 index 8744accf7..000000000 --- a/.agents/skills/agent-browser/references/commands.md +++ /dev/null @@ -1,259 +0,0 @@ -# Command Reference - -Complete reference for all agent-browser commands. For quick start and common patterns, see SKILL.md. - -## Navigation - -```bash -agent-browser open # Navigate to URL (aliases: goto, navigate) - # Supports: https://, http://, file://, about:, data:// - # Auto-prepends https:// if no protocol given -agent-browser back # Go back -agent-browser forward # Go forward -agent-browser reload # Reload page -agent-browser close # Close browser (aliases: quit, exit) -agent-browser connect 9222 # Connect to browser via CDP port -``` - -## Snapshot (page analysis) - -```bash -agent-browser snapshot # Full accessibility tree -agent-browser snapshot -i # Interactive elements only (recommended) -agent-browser snapshot -c # Compact output -agent-browser snapshot -d 3 # Limit depth to 3 -agent-browser snapshot -s "#main" # Scope to CSS selector -``` - -## Interactions (use @refs from snapshot) - -```bash -agent-browser click @e1 # Click -agent-browser dblclick @e1 # Double-click -agent-browser focus @e1 # Focus element -agent-browser fill @e2 "text" # Clear and type -agent-browser type @e2 "text" # Type without clearing -agent-browser press Enter # Press key (alias: key) -agent-browser press Control+a # Key combination -agent-browser keydown Shift # Hold key down -agent-browser keyup Shift # Release key -agent-browser hover @e1 # Hover -agent-browser check @e1 # Check checkbox -agent-browser uncheck @e1 # Uncheck checkbox -agent-browser select @e1 "value" # Select dropdown option -agent-browser select @e1 "a" "b" # Select multiple options -agent-browser scroll down 500 # Scroll page (default: down 300px) -agent-browser scrollintoview @e1 # Scroll element into view (alias: scrollinto) -agent-browser drag @e1 @e2 # Drag and drop -agent-browser upload @e1 file.pdf # Upload files -``` - -## Get Information - -```bash -agent-browser get text @e1 # Get element text -agent-browser get html @e1 # Get innerHTML -agent-browser get value @e1 # Get input value -agent-browser get attr @e1 href # Get attribute -agent-browser get title # Get page title -agent-browser get url # Get current URL -agent-browser get count ".item" # Count matching elements -agent-browser get box @e1 # Get bounding box -agent-browser get styles @e1 # Get computed styles (font, color, bg, etc.) -``` - -## Check State - -```bash -agent-browser is visible @e1 # Check if visible -agent-browser is enabled @e1 # Check if enabled -agent-browser is checked @e1 # Check if checked -``` - -## Screenshots and PDF - -```bash -agent-browser screenshot # Save to temporary directory -agent-browser screenshot path.png # Save to specific path -agent-browser screenshot --full # Full page -agent-browser pdf output.pdf # Save as PDF -``` - -## Video Recording - -```bash -agent-browser record start ./demo.webm # Start recording -agent-browser click @e1 # Perform actions -agent-browser record stop # Stop and save video -agent-browser record restart ./take2.webm # Stop current + start new -``` - -## Wait - -```bash -agent-browser wait @e1 # Wait for element -agent-browser wait 2000 # Wait milliseconds -agent-browser wait --text "Success" # Wait for text (or -t) -agent-browser wait --url "**/dashboard" # Wait for URL pattern (or -u) -agent-browser wait --load networkidle # Wait for network idle (or -l) -agent-browser wait --fn "window.ready" # Wait for JS condition (or -f) -``` - -## Mouse Control - -```bash -agent-browser mouse move 100 200 # Move mouse -agent-browser mouse down left # Press button -agent-browser mouse up left # Release button -agent-browser mouse wheel 100 # Scroll wheel -``` - -## Semantic Locators (alternative to refs) - -```bash -agent-browser find role button click --name "Submit" -agent-browser find text "Sign In" click -agent-browser find text "Sign In" click --exact # Exact match only -agent-browser find label "Email" fill "user@test.com" -agent-browser find placeholder "Search" type "query" -agent-browser find alt "Logo" click -agent-browser find title "Close" click -agent-browser find testid "submit-btn" click -agent-browser find first ".item" click -agent-browser find last ".item" click -agent-browser find nth 2 "a" hover -``` - -## Browser Settings - -```bash -agent-browser set viewport 1920 1080 # Set viewport size -agent-browser set device "iPhone 14" # Emulate device -agent-browser set geo 37.7749 -122.4194 # Set geolocation (alias: geolocation) -agent-browser set offline on # Toggle offline mode -agent-browser set headers '{"X-Key":"v"}' # Extra HTTP headers -agent-browser set credentials user pass # HTTP basic auth (alias: auth) -agent-browser set media dark # Emulate color scheme -agent-browser set media light reduced-motion # Light mode + reduced motion -``` - -## Cookies and Storage - -```bash -agent-browser cookies # Get all cookies -agent-browser cookies set name value # Set cookie -agent-browser cookies clear # Clear cookies -agent-browser storage local # Get all localStorage -agent-browser storage local key # Get specific key -agent-browser storage local set k v # Set value -agent-browser storage local clear # Clear all -``` - -## Network - -```bash -agent-browser network route # Intercept requests -agent-browser network route --abort # Block requests -agent-browser network route --body '{}' # Mock response -agent-browser network unroute [url] # Remove routes -agent-browser network requests # View tracked requests -agent-browser network requests --filter api # Filter requests -``` - -## Tabs and Windows - -```bash -agent-browser tab # List tabs -agent-browser tab new [url] # New tab -agent-browser tab 2 # Switch to tab by index -agent-browser tab close # Close current tab -agent-browser tab close 2 # Close tab by index -agent-browser window new # New window -``` - -## Frames - -```bash -agent-browser frame "#iframe" # Switch to iframe -agent-browser frame main # Back to main frame -``` - -## Dialogs - -```bash -agent-browser dialog accept [text] # Accept dialog -agent-browser dialog dismiss # Dismiss dialog -``` - -## JavaScript - -```bash -agent-browser eval "document.title" # Simple expressions only -agent-browser eval -b "" # Any JavaScript (base64 encoded) -agent-browser eval --stdin # Read script from stdin -``` - -Use `-b`/`--base64` or `--stdin` for reliable execution. Shell escaping with nested quotes and special characters is error-prone. - -```bash -# Base64 encode your script, then: -agent-browser eval -b "ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ==" - -# Or use stdin with heredoc for multiline scripts: -cat <<'EOF' | agent-browser eval --stdin -const links = document.querySelectorAll('a'); -Array.from(links).map(a => a.href); -EOF -``` - -## State Management - -```bash -agent-browser state save auth.json # Save cookies, storage, auth state -agent-browser state load auth.json # Restore saved state -``` - -## Global Options - -```bash -agent-browser --session ... # Isolated browser session -agent-browser --json ... # JSON output for parsing -agent-browser --headed ... # Show browser window (not headless) -agent-browser --full ... # Full page screenshot (-f) -agent-browser --cdp ... # Connect via Chrome DevTools Protocol -agent-browser -p ... # Cloud browser provider (--provider) -agent-browser --proxy ... # Use proxy server -agent-browser --headers ... # HTTP headers scoped to URL's origin -agent-browser --executable-path

# Custom browser executable -agent-browser --extension ... # Load browser extension (repeatable) -agent-browser --ignore-https-errors # Ignore SSL certificate errors -agent-browser --help # Show help (-h) -agent-browser --version # Show version (-V) -agent-browser --help # Show detailed help for a command -``` - -## Debugging - -```bash -agent-browser --headed open example.com # Show browser window -agent-browser --cdp 9222 snapshot # Connect via CDP port -agent-browser connect 9222 # Alternative: connect command -agent-browser console # View console messages -agent-browser console --clear # Clear console -agent-browser errors # View page errors -agent-browser errors --clear # Clear errors -agent-browser highlight @e1 # Highlight element -agent-browser trace start # Start recording trace -agent-browser trace stop trace.zip # Stop and save trace -``` - -## Environment Variables - -```bash -AGENT_BROWSER_SESSION="mysession" # Default session name -AGENT_BROWSER_EXECUTABLE_PATH="/path/chrome" # Custom browser path -AGENT_BROWSER_EXTENSIONS="/ext1,/ext2" # Comma-separated extension paths -AGENT_BROWSER_PROVIDER="browserbase" # Cloud browser provider -AGENT_BROWSER_STREAM_PORT="9223" # WebSocket streaming port -AGENT_BROWSER_HOME="/path/to/agent-browser" # Custom install location -``` diff --git a/.agents/skills/agent-browser/references/proxy-support.md b/.agents/skills/agent-browser/references/proxy-support.md deleted file mode 100644 index 05cc9d538..000000000 --- a/.agents/skills/agent-browser/references/proxy-support.md +++ /dev/null @@ -1,188 +0,0 @@ -# Proxy Support - -Proxy configuration for geo-testing, rate limiting avoidance, and corporate environments. - -**Related**: [commands.md](commands.md) for global options, [SKILL.md](../SKILL.md) for quick start. - -## Contents - -- [Basic Proxy Configuration](#basic-proxy-configuration) -- [Authenticated Proxy](#authenticated-proxy) -- [SOCKS Proxy](#socks-proxy) -- [Proxy Bypass](#proxy-bypass) -- [Common Use Cases](#common-use-cases) -- [Verifying Proxy Connection](#verifying-proxy-connection) -- [Troubleshooting](#troubleshooting) -- [Best Practices](#best-practices) - -## Basic Proxy Configuration - -Set proxy via environment variable before starting: - -```bash -# HTTP proxy -export HTTP_PROXY="http://proxy.example.com:8080" -agent-browser open https://example.com - -# HTTPS proxy -export HTTPS_PROXY="https://proxy.example.com:8080" -agent-browser open https://example.com - -# Both -export HTTP_PROXY="http://proxy.example.com:8080" -export HTTPS_PROXY="http://proxy.example.com:8080" -agent-browser open https://example.com -``` - -## Authenticated Proxy - -For proxies requiring authentication: - -```bash -# Include credentials in URL -export HTTP_PROXY="http://username:password@proxy.example.com:8080" -agent-browser open https://example.com -``` - -## SOCKS Proxy - -```bash -# SOCKS5 proxy -export ALL_PROXY="socks5://proxy.example.com:1080" -agent-browser open https://example.com - -# SOCKS5 with auth -export ALL_PROXY="socks5://user:pass@proxy.example.com:1080" -agent-browser open https://example.com -``` - -## Proxy Bypass - -Skip proxy for specific domains: - -```bash -# Bypass proxy for local addresses -export NO_PROXY="localhost,127.0.0.1,.internal.company.com" -agent-browser open https://internal.company.com # Direct connection -agent-browser open https://external.com # Via proxy -``` - -## Common Use Cases - -### Geo-Location Testing - -```bash -#!/bin/bash -# Test site from different regions using geo-located proxies - -PROXIES=( - "http://us-proxy.example.com:8080" - "http://eu-proxy.example.com:8080" - "http://asia-proxy.example.com:8080" -) - -for proxy in "${PROXIES[@]}"; do - export HTTP_PROXY="$proxy" - export HTTPS_PROXY="$proxy" - - region=$(echo "$proxy" | grep -oP '^\w+-\w+') - echo "Testing from: $region" - - agent-browser --session "$region" open https://example.com - agent-browser --session "$region" screenshot "./screenshots/$region.png" - agent-browser --session "$region" close -done -``` - -### Rotating Proxies for Scraping - -```bash -#!/bin/bash -# Rotate through proxy list to avoid rate limiting - -PROXY_LIST=( - "http://proxy1.example.com:8080" - "http://proxy2.example.com:8080" - "http://proxy3.example.com:8080" -) - -URLS=( - "https://site.com/page1" - "https://site.com/page2" - "https://site.com/page3" -) - -for i in "${!URLS[@]}"; do - proxy_index=$((i % ${#PROXY_LIST[@]})) - export HTTP_PROXY="${PROXY_LIST[$proxy_index]}" - export HTTPS_PROXY="${PROXY_LIST[$proxy_index]}" - - agent-browser open "${URLS[$i]}" - agent-browser get text body > "output-$i.txt" - agent-browser close - - sleep 1 # Polite delay -done -``` - -### Corporate Network Access - -```bash -#!/bin/bash -# Access internal sites via corporate proxy - -export HTTP_PROXY="http://corpproxy.company.com:8080" -export HTTPS_PROXY="http://corpproxy.company.com:8080" -export NO_PROXY="localhost,127.0.0.1,.company.com" - -# External sites go through proxy -agent-browser open https://external-vendor.com - -# Internal sites bypass proxy -agent-browser open https://intranet.company.com -``` - -## Verifying Proxy Connection - -```bash -# Check your apparent IP -agent-browser open https://httpbin.org/ip -agent-browser get text body -# Should show proxy's IP, not your real IP -``` - -## Troubleshooting - -### Proxy Connection Failed - -```bash -# Test proxy connectivity first -curl -x http://proxy.example.com:8080 https://httpbin.org/ip - -# Check if proxy requires auth -export HTTP_PROXY="http://user:pass@proxy.example.com:8080" -``` - -### SSL/TLS Errors Through Proxy - -Some proxies perform SSL inspection. If you encounter certificate errors: - -```bash -# For testing only - not recommended for production -agent-browser open https://example.com --ignore-https-errors -``` - -### Slow Performance - -```bash -# Use proxy only when necessary -export NO_PROXY="*.cdn.com,*.static.com" # Direct CDN access -``` - -## Best Practices - -1. **Use environment variables** - Don't hardcode proxy credentials -2. **Set NO_PROXY appropriately** - Avoid routing local traffic through proxy -3. **Test proxy before automation** - Verify connectivity with simple requests -4. **Handle proxy failures gracefully** - Implement retry logic for unstable proxies -5. **Rotate proxies for large scraping jobs** - Distribute load and avoid bans diff --git a/.agents/skills/agent-browser/references/session-management.md b/.agents/skills/agent-browser/references/session-management.md deleted file mode 100644 index bb5312dbd..000000000 --- a/.agents/skills/agent-browser/references/session-management.md +++ /dev/null @@ -1,193 +0,0 @@ -# Session Management - -Multiple isolated browser sessions with state persistence and concurrent browsing. - -**Related**: [authentication.md](authentication.md) for login patterns, [SKILL.md](../SKILL.md) for quick start. - -## Contents - -- [Named Sessions](#named-sessions) -- [Session Isolation Properties](#session-isolation-properties) -- [Session State Persistence](#session-state-persistence) -- [Common Patterns](#common-patterns) -- [Default Session](#default-session) -- [Session Cleanup](#session-cleanup) -- [Best Practices](#best-practices) - -## Named Sessions - -Use `--session` flag to isolate browser contexts: - -```bash -# Session 1: Authentication flow -agent-browser --session auth open https://app.example.com/login - -# Session 2: Public browsing (separate cookies, storage) -agent-browser --session public open https://example.com - -# Commands are isolated by session -agent-browser --session auth fill @e1 "user@example.com" -agent-browser --session public get text body -``` - -## Session Isolation Properties - -Each session has independent: -- Cookies -- LocalStorage / SessionStorage -- IndexedDB -- Cache -- Browsing history -- Open tabs - -## Session State Persistence - -### Save Session State - -```bash -# Save cookies, storage, and auth state -agent-browser state save /path/to/auth-state.json -``` - -### Load Session State - -```bash -# Restore saved state -agent-browser state load /path/to/auth-state.json - -# Continue with authenticated session -agent-browser open https://app.example.com/dashboard -``` - -### State File Contents - -```json -{ - "cookies": [...], - "localStorage": {...}, - "sessionStorage": {...}, - "origins": [...] -} -``` - -## Common Patterns - -### Authenticated Session Reuse - -```bash -#!/bin/bash -# Save login state once, reuse many times - -STATE_FILE="/tmp/auth-state.json" - -# Check if we have saved state -if [[ -f "$STATE_FILE" ]]; then - agent-browser state load "$STATE_FILE" - agent-browser open https://app.example.com/dashboard -else - # Perform login - agent-browser open https://app.example.com/login - agent-browser snapshot -i - agent-browser fill @e1 "$USERNAME" - agent-browser fill @e2 "$PASSWORD" - agent-browser click @e3 - agent-browser wait --load networkidle - - # Save for future use - agent-browser state save "$STATE_FILE" -fi -``` - -### Concurrent Scraping - -```bash -#!/bin/bash -# Scrape multiple sites concurrently - -# Start all sessions -agent-browser --session site1 open https://site1.com & -agent-browser --session site2 open https://site2.com & -agent-browser --session site3 open https://site3.com & -wait - -# Extract from each -agent-browser --session site1 get text body > site1.txt -agent-browser --session site2 get text body > site2.txt -agent-browser --session site3 get text body > site3.txt - -# Cleanup -agent-browser --session site1 close -agent-browser --session site2 close -agent-browser --session site3 close -``` - -### A/B Testing Sessions - -```bash -# Test different user experiences -agent-browser --session variant-a open "https://app.com?variant=a" -agent-browser --session variant-b open "https://app.com?variant=b" - -# Compare -agent-browser --session variant-a screenshot /tmp/variant-a.png -agent-browser --session variant-b screenshot /tmp/variant-b.png -``` - -## Default Session - -When `--session` is omitted, commands use the default session: - -```bash -# These use the same default session -agent-browser open https://example.com -agent-browser snapshot -i -agent-browser close # Closes default session -``` - -## Session Cleanup - -```bash -# Close specific session -agent-browser --session auth close - -# List active sessions -agent-browser session list -``` - -## Best Practices - -### 1. Name Sessions Semantically - -```bash -# GOOD: Clear purpose -agent-browser --session github-auth open https://github.com -agent-browser --session docs-scrape open https://docs.example.com - -# AVOID: Generic names -agent-browser --session s1 open https://github.com -``` - -### 2. Always Clean Up - -```bash -# Close sessions when done -agent-browser --session auth close -agent-browser --session scrape close -``` - -### 3. Handle State Files Securely - -```bash -# Don't commit state files (contain auth tokens!) -echo "*.auth-state.json" >> .gitignore - -# Delete after use -rm /tmp/auth-state.json -``` - -### 4. Timeout Long Sessions - -```bash -# Set timeout for automated scripts -timeout 60 agent-browser --session long-task get text body -``` diff --git a/.agents/skills/agent-browser/references/snapshot-refs.md b/.agents/skills/agent-browser/references/snapshot-refs.md deleted file mode 100644 index c13d53a89..000000000 --- a/.agents/skills/agent-browser/references/snapshot-refs.md +++ /dev/null @@ -1,194 +0,0 @@ -# Snapshot and Refs - -Compact element references that reduce context usage dramatically for AI agents. - -**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start. - -## Contents - -- [How Refs Work](#how-refs-work) -- [Snapshot Command](#the-snapshot-command) -- [Using Refs](#using-refs) -- [Ref Lifecycle](#ref-lifecycle) -- [Best Practices](#best-practices) -- [Ref Notation Details](#ref-notation-details) -- [Troubleshooting](#troubleshooting) - -## How Refs Work - -Traditional approach: -``` -Full DOM/HTML → AI parses → CSS selector → Action (~3000-5000 tokens) -``` - -agent-browser approach: -``` -Compact snapshot → @refs assigned → Direct interaction (~200-400 tokens) -``` - -## The Snapshot Command - -```bash -# Basic snapshot (shows page structure) -agent-browser snapshot - -# Interactive snapshot (-i flag) - RECOMMENDED -agent-browser snapshot -i -``` - -### Snapshot Output Format - -``` -Page: Example Site - Home -URL: https://example.com - -@e1 [header] - @e2 [nav] - @e3 [a] "Home" - @e4 [a] "Products" - @e5 [a] "About" - @e6 [button] "Sign In" - -@e7 [main] - @e8 [h1] "Welcome" - @e9 [form] - @e10 [input type="email"] placeholder="Email" - @e11 [input type="password"] placeholder="Password" - @e12 [button type="submit"] "Log In" - -@e13 [footer] - @e14 [a] "Privacy Policy" -``` - -## Using Refs - -Once you have refs, interact directly: - -```bash -# Click the "Sign In" button -agent-browser click @e6 - -# Fill email input -agent-browser fill @e10 "user@example.com" - -# Fill password -agent-browser fill @e11 "password123" - -# Submit the form -agent-browser click @e12 -``` - -## Ref Lifecycle - -**IMPORTANT**: Refs are invalidated when the page changes! - -```bash -# Get initial snapshot -agent-browser snapshot -i -# @e1 [button] "Next" - -# Click triggers page change -agent-browser click @e1 - -# MUST re-snapshot to get new refs! -agent-browser snapshot -i -# @e1 [h1] "Page 2" ← Different element now! -``` - -## Best Practices - -### 1. Always Snapshot Before Interacting - -```bash -# CORRECT -agent-browser open https://example.com -agent-browser snapshot -i # Get refs first -agent-browser click @e1 # Use ref - -# WRONG -agent-browser open https://example.com -agent-browser click @e1 # Ref doesn't exist yet! -``` - -### 2. Re-Snapshot After Navigation - -```bash -agent-browser click @e5 # Navigates to new page -agent-browser snapshot -i # Get new refs -agent-browser click @e1 # Use new refs -``` - -### 3. Re-Snapshot After Dynamic Changes - -```bash -agent-browser click @e1 # Opens dropdown -agent-browser snapshot -i # See dropdown items -agent-browser click @e7 # Select item -``` - -### 4. Snapshot Specific Regions - -For complex pages, snapshot specific areas: - -```bash -# Snapshot just the form -agent-browser snapshot @e9 -``` - -## Ref Notation Details - -``` -@e1 [tag type="value"] "text content" placeholder="hint" -│ │ │ │ │ -│ │ │ │ └─ Additional attributes -│ │ │ └─ Visible text -│ │ └─ Key attributes shown -│ └─ HTML tag name -└─ Unique ref ID -``` - -### Common Patterns - -``` -@e1 [button] "Submit" # Button with text -@e2 [input type="email"] # Email input -@e3 [input type="password"] # Password input -@e4 [a href="/page"] "Link Text" # Anchor link -@e5 [select] # Dropdown -@e6 [textarea] placeholder="Message" # Text area -@e7 [div class="modal"] # Container (when relevant) -@e8 [img alt="Logo"] # Image -@e9 [checkbox] checked # Checked checkbox -@e10 [radio] selected # Selected radio -``` - -## Troubleshooting - -### "Ref not found" Error - -```bash -# Ref may have changed - re-snapshot -agent-browser snapshot -i -``` - -### Element Not Visible in Snapshot - -```bash -# Scroll to reveal element -agent-browser scroll --bottom -agent-browser snapshot -i - -# Or wait for dynamic content -agent-browser wait 1000 -agent-browser snapshot -i -``` - -### Too Many Elements - -```bash -# Snapshot specific container -agent-browser snapshot @e5 - -# Or use get text for content-only extraction -agent-browser get text @e5 -``` diff --git a/.agents/skills/agent-browser/references/video-recording.md b/.agents/skills/agent-browser/references/video-recording.md deleted file mode 100644 index e6a9fb4e2..000000000 --- a/.agents/skills/agent-browser/references/video-recording.md +++ /dev/null @@ -1,173 +0,0 @@ -# Video Recording - -Capture browser automation as video for debugging, documentation, or verification. - -**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start. - -## Contents - -- [Basic Recording](#basic-recording) -- [Recording Commands](#recording-commands) -- [Use Cases](#use-cases) -- [Best Practices](#best-practices) -- [Output Format](#output-format) -- [Limitations](#limitations) - -## Basic Recording - -```bash -# Start recording -agent-browser record start ./demo.webm - -# Perform actions -agent-browser open https://example.com -agent-browser snapshot -i -agent-browser click @e1 -agent-browser fill @e2 "test input" - -# Stop and save -agent-browser record stop -``` - -## Recording Commands - -```bash -# Start recording to file -agent-browser record start ./output.webm - -# Stop current recording -agent-browser record stop - -# Restart with new file (stops current + starts new) -agent-browser record restart ./take2.webm -``` - -## Use Cases - -### Debugging Failed Automation - -```bash -#!/bin/bash -# Record automation for debugging - -agent-browser record start ./debug-$(date +%Y%m%d-%H%M%S).webm - -# Run your automation -agent-browser open https://app.example.com -agent-browser snapshot -i -agent-browser click @e1 || { - echo "Click failed - check recording" - agent-browser record stop - exit 1 -} - -agent-browser record stop -``` - -### Documentation Generation - -```bash -#!/bin/bash -# Record workflow for documentation - -agent-browser record start ./docs/how-to-login.webm - -agent-browser open https://app.example.com/login -agent-browser wait 1000 # Pause for visibility - -agent-browser snapshot -i -agent-browser fill @e1 "demo@example.com" -agent-browser wait 500 - -agent-browser fill @e2 "password" -agent-browser wait 500 - -agent-browser click @e3 -agent-browser wait --load networkidle -agent-browser wait 1000 # Show result - -agent-browser record stop -``` - -### CI/CD Test Evidence - -```bash -#!/bin/bash -# Record E2E test runs for CI artifacts - -TEST_NAME="${1:-e2e-test}" -RECORDING_DIR="./test-recordings" -mkdir -p "$RECORDING_DIR" - -agent-browser record start "$RECORDING_DIR/$TEST_NAME-$(date +%s).webm" - -# Run test -if run_e2e_test; then - echo "Test passed" -else - echo "Test failed - recording saved" -fi - -agent-browser record stop -``` - -## Best Practices - -### 1. Add Pauses for Clarity - -```bash -# Slow down for human viewing -agent-browser click @e1 -agent-browser wait 500 # Let viewer see result -``` - -### 2. Use Descriptive Filenames - -```bash -# Include context in filename -agent-browser record start ./recordings/login-flow-2024-01-15.webm -agent-browser record start ./recordings/checkout-test-run-42.webm -``` - -### 3. Handle Recording in Error Cases - -```bash -#!/bin/bash -set -e - -cleanup() { - agent-browser record stop 2>/dev/null || true - agent-browser close 2>/dev/null || true -} -trap cleanup EXIT - -agent-browser record start ./automation.webm -# ... automation steps ... -``` - -### 4. Combine with Screenshots - -```bash -# Record video AND capture key frames -agent-browser record start ./flow.webm - -agent-browser open https://example.com -agent-browser screenshot ./screenshots/step1-homepage.png - -agent-browser click @e1 -agent-browser screenshot ./screenshots/step2-after-click.png - -agent-browser record stop -``` - -## Output Format - -- Default format: WebM (VP8/VP9 codec) -- Compatible with all modern browsers and video players -- Compressed but high quality - -## Limitations - -- Recording adds slight overhead to automation -- Large recordings can consume significant disk space -- Some headless environments may have codec limitations diff --git a/.agents/skills/agent-browser/templates/authenticated-session.sh b/.agents/skills/agent-browser/templates/authenticated-session.sh deleted file mode 100755 index ebbfc1fae..000000000 --- a/.agents/skills/agent-browser/templates/authenticated-session.sh +++ /dev/null @@ -1,97 +0,0 @@ -#!/bin/bash -# Template: Authenticated Session Workflow -# Purpose: Login once, save state, reuse for subsequent runs -# Usage: ./authenticated-session.sh [state-file] -# -# Environment variables: -# APP_USERNAME - Login username/email -# APP_PASSWORD - Login password -# -# Two modes: -# 1. Discovery mode (default): Shows form structure so you can identify refs -# 2. Login mode: Performs actual login after you update the refs -# -# Setup steps: -# 1. Run once to see form structure (discovery mode) -# 2. Update refs in LOGIN FLOW section below -# 3. Set APP_USERNAME and APP_PASSWORD -# 4. Delete the DISCOVERY section - -set -euo pipefail - -LOGIN_URL="${1:?Usage: $0 [state-file]}" -STATE_FILE="${2:-./auth-state.json}" - -echo "Authentication workflow: $LOGIN_URL" - -# ================================================================ -# SAVED STATE: Skip login if valid saved state exists -# ================================================================ -if [[ -f "$STATE_FILE" ]]; then - echo "Loading saved state from $STATE_FILE..." - agent-browser state load "$STATE_FILE" - agent-browser open "$LOGIN_URL" - agent-browser wait --load networkidle - - CURRENT_URL=$(agent-browser get url) - if [[ "$CURRENT_URL" != *"login"* ]] && [[ "$CURRENT_URL" != *"signin"* ]]; then - echo "Session restored successfully" - agent-browser snapshot -i - exit 0 - fi - echo "Session expired, performing fresh login..." - rm -f "$STATE_FILE" -fi - -# ================================================================ -# DISCOVERY MODE: Shows form structure (delete after setup) -# ================================================================ -echo "Opening login page..." -agent-browser open "$LOGIN_URL" -agent-browser wait --load networkidle - -echo "" -echo "Login form structure:" -echo "---" -agent-browser snapshot -i -echo "---" -echo "" -echo "Next steps:" -echo " 1. Note the refs: username=@e?, password=@e?, submit=@e?" -echo " 2. Update the LOGIN FLOW section below with your refs" -echo " 3. Set: export APP_USERNAME='...' APP_PASSWORD='...'" -echo " 4. Delete this DISCOVERY MODE section" -echo "" -agent-browser close -exit 0 - -# ================================================================ -# LOGIN FLOW: Uncomment and customize after discovery -# ================================================================ -# : "${APP_USERNAME:?Set APP_USERNAME environment variable}" -# : "${APP_PASSWORD:?Set APP_PASSWORD environment variable}" -# -# agent-browser open "$LOGIN_URL" -# agent-browser wait --load networkidle -# agent-browser snapshot -i -# -# # Fill credentials (update refs to match your form) -# agent-browser fill @e1 "$APP_USERNAME" -# agent-browser fill @e2 "$APP_PASSWORD" -# agent-browser click @e3 -# agent-browser wait --load networkidle -# -# # Verify login succeeded -# FINAL_URL=$(agent-browser get url) -# if [[ "$FINAL_URL" == *"login"* ]] || [[ "$FINAL_URL" == *"signin"* ]]; then -# echo "Login failed - still on login page" -# agent-browser screenshot /tmp/login-failed.png -# agent-browser close -# exit 1 -# fi -# -# # Save state for future runs -# echo "Saving state to $STATE_FILE" -# agent-browser state save "$STATE_FILE" -# echo "Login successful" -# agent-browser snapshot -i diff --git a/.agents/skills/agent-browser/templates/capture-workflow.sh b/.agents/skills/agent-browser/templates/capture-workflow.sh deleted file mode 100755 index 3bc93ad0c..000000000 --- a/.agents/skills/agent-browser/templates/capture-workflow.sh +++ /dev/null @@ -1,69 +0,0 @@ -#!/bin/bash -# Template: Content Capture Workflow -# Purpose: Extract content from web pages (text, screenshots, PDF) -# Usage: ./capture-workflow.sh [output-dir] -# -# Outputs: -# - page-full.png: Full page screenshot -# - page-structure.txt: Page element structure with refs -# - page-text.txt: All text content -# - page.pdf: PDF version -# -# Optional: Load auth state for protected pages - -set -euo pipefail - -TARGET_URL="${1:?Usage: $0 [output-dir]}" -OUTPUT_DIR="${2:-.}" - -echo "Capturing: $TARGET_URL" -mkdir -p "$OUTPUT_DIR" - -# Optional: Load authentication state -# if [[ -f "./auth-state.json" ]]; then -# echo "Loading authentication state..." -# agent-browser state load "./auth-state.json" -# fi - -# Navigate to target -agent-browser open "$TARGET_URL" -agent-browser wait --load networkidle - -# Get metadata -TITLE=$(agent-browser get title) -URL=$(agent-browser get url) -echo "Title: $TITLE" -echo "URL: $URL" - -# Capture full page screenshot -agent-browser screenshot --full "$OUTPUT_DIR/page-full.png" -echo "Saved: $OUTPUT_DIR/page-full.png" - -# Get page structure with refs -agent-browser snapshot -i > "$OUTPUT_DIR/page-structure.txt" -echo "Saved: $OUTPUT_DIR/page-structure.txt" - -# Extract all text content -agent-browser get text body > "$OUTPUT_DIR/page-text.txt" -echo "Saved: $OUTPUT_DIR/page-text.txt" - -# Save as PDF -agent-browser pdf "$OUTPUT_DIR/page.pdf" -echo "Saved: $OUTPUT_DIR/page.pdf" - -# Optional: Extract specific elements using refs from structure -# agent-browser get text @e5 > "$OUTPUT_DIR/main-content.txt" - -# Optional: Handle infinite scroll pages -# for i in {1..5}; do -# agent-browser scroll down 1000 -# agent-browser wait 1000 -# done -# agent-browser screenshot --full "$OUTPUT_DIR/page-scrolled.png" - -# Cleanup -agent-browser close - -echo "" -echo "Capture complete:" -ls -la "$OUTPUT_DIR" diff --git a/.agents/skills/agent-browser/templates/form-automation.sh b/.agents/skills/agent-browser/templates/form-automation.sh deleted file mode 100755 index 6784fcd3a..000000000 --- a/.agents/skills/agent-browser/templates/form-automation.sh +++ /dev/null @@ -1,62 +0,0 @@ -#!/bin/bash -# Template: Form Automation Workflow -# Purpose: Fill and submit web forms with validation -# Usage: ./form-automation.sh -# -# This template demonstrates the snapshot-interact-verify pattern: -# 1. Navigate to form -# 2. Snapshot to get element refs -# 3. Fill fields using refs -# 4. Submit and verify result -# -# Customize: Update the refs (@e1, @e2, etc.) based on your form's snapshot output - -set -euo pipefail - -FORM_URL="${1:?Usage: $0 }" - -echo "Form automation: $FORM_URL" - -# Step 1: Navigate to form -agent-browser open "$FORM_URL" -agent-browser wait --load networkidle - -# Step 2: Snapshot to discover form elements -echo "" -echo "Form structure:" -agent-browser snapshot -i - -# Step 3: Fill form fields (customize these refs based on snapshot output) -# -# Common field types: -# agent-browser fill @e1 "John Doe" # Text input -# agent-browser fill @e2 "user@example.com" # Email input -# agent-browser fill @e3 "SecureP@ss123" # Password input -# agent-browser select @e4 "Option Value" # Dropdown -# agent-browser check @e5 # Checkbox -# agent-browser click @e6 # Radio button -# agent-browser fill @e7 "Multi-line text" # Textarea -# agent-browser upload @e8 /path/to/file.pdf # File upload -# -# Uncomment and modify: -# agent-browser fill @e1 "Test User" -# agent-browser fill @e2 "test@example.com" -# agent-browser click @e3 # Submit button - -# Step 4: Wait for submission -# agent-browser wait --load networkidle -# agent-browser wait --url "**/success" # Or wait for redirect - -# Step 5: Verify result -echo "" -echo "Result:" -agent-browser get url -agent-browser snapshot -i - -# Optional: Capture evidence -agent-browser screenshot /tmp/form-result.png -echo "Screenshot saved: /tmp/form-result.png" - -# Cleanup -agent-browser close -echo "Done" diff --git a/.agents/skills/github-integration/SKILL.md b/.agents/skills/github-integration/SKILL.md deleted file mode 100644 index a585f1504..000000000 --- a/.agents/skills/github-integration/SKILL.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -name: github-integration -description: > - Enable the GitHub CLI (`gh`) in Claude Code cloud sessions and GitHub - Copilot coding agent environments. Use this skill when: (1) setting up a - project so cloud AI agents can use `gh` for PRs, issues, and releases, - (2) configuring setup scripts or SessionStart hooks for `gh` installation, - (3) adding `copilot-setup-steps.yml` for GitHub Copilot agents, - (4) troubleshooting `gh` auth failures in cloud sessions, or - (5) configuring `GH_TOKEN` for headless environments. Triggers on: - "enable gh", "github integration", "Claude Code cloud setup", - "copilot setup steps", "gh auth in cloud", "gh not working in cloud", - "setup script", or any request involving GitHub CLI access from - cloud-based AI coding agents. -metadata: - author: Codervisor - version: 0.2.0 - homepage: https://github.com/codervisor/forge ---- - -# GitHub Integration - -Enable `gh` CLI access in Claude Code cloud and GitHub Copilot coding agent -environments so agents can create PRs, manage issues, and interact with -GitHub APIs. - -## When to Use This Skill - -Activate when: -- User wants cloud AI agents to use `gh` (PRs, issues, releases, API calls) -- User needs to install `gh` in Claude Code cloud sessions -- User wants to add `copilot-setup-steps.yml` for GitHub Copilot agents -- `gh` commands fail with auth or "not found" errors in a cloud session -- User wants to enable GitHub integration for any cloud-based AI coding agent - -## Decision Tree - -``` -Which cloud environment? - -Claude Code cloud (claude.ai/code)? - → gh is NOT pre-installed in the default image - → Install via setup script: apt update && apt install -y gh - → Set GH_TOKEN as environment variable in environment settings - → For repo-portable setup, use SessionStart hook instead - → Use -R owner/repo flag with gh due to sandbox proxy - -GitHub Copilot coding agent? - → Add .github/copilot-setup-steps.yml to the repo - → gh IS pre-installed; just configure GH_TOKEN - → Commit and push — agent sessions pick it up automatically - -gh commands failing? - → "command not found" → gh not installed; add to setup script - → HTTP 401 → GH_TOKEN not set; add to environment variables - → HTTP 403 → Token lacks required scope; check permissions - → "could not determine repo" → Use -R owner/repo flag - → See references/cloud-auth.md for more - -Need gh in local dev too? - → Run: gh auth login (interactive, browser-based) - → Or set GH_TOKEN env var for headless/CI use -``` - -## Two Environments, Two Approaches - -### Claude Code Cloud (claude.ai/code) - -Claude Code cloud runs sessions in Anthropic-managed VMs. The `gh` CLI -is **not pre-installed**. You need two things: - -1. **Setup script** — installs `gh` when the session starts -2. **`GH_TOKEN` env var** — authenticates `gh` with your GitHub PAT - -#### Quick Start: Setup Script - -In the Claude Code web UI: Environment Settings → Setup script: - -```bash -#!/bin/bash -apt update && apt install -y gh -``` - -Then add `GH_TOKEN` as an environment variable with your GitHub Personal -Access Token (needs `repo` scope). - -#### Alternative: SessionStart Hook (repo-portable) - -Add to `.claude/settings.json` in your repo: - -```json -{ - "hooks": { - "SessionStart": [ - { - "hooks": [ - { - "type": "command", - "command": "if [ \"$CLAUDE_CODE_REMOTE\" = \"true\" ]; then apt update && apt install -y gh; fi", - "timeout": 120 - } - ] - } - ] - } -} -``` - -The `CLAUDE_CODE_REMOTE` check ensures it only runs in cloud sessions. - -#### Important: The `-R` Flag - -Due to the sandbox proxy, `gh` may not auto-detect the repo. Use the -`-R owner/repo` flag: - -```bash -gh pr create -R codervisor/myrepo --title "..." --body "..." -gh issue list -R codervisor/myrepo -``` - -### GitHub Copilot Coding Agent - -Copilot coding agents use `.github/copilot-setup-steps.yml`. The `gh` CLI -is pre-installed; you just need to authenticate it. - -Add this file at `.github/copilot-setup-steps.yml`: - -```yaml -name: "Copilot Setup Steps" - -on: repository_dispatch - -jobs: - copilot-setup-steps: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Authenticate gh CLI - run: gh auth status - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} -``` - -See `templates/copilot-setup-steps.yml` for a full template with -dependency installation. - -## Setup Scripts vs SessionStart Hooks vs copilot-setup-steps - -| | Setup scripts | SessionStart hooks | copilot-setup-steps.yml | -|------------------|--------------------------|---------------------------------|----------------------------------| -| **Platform** | Claude Code cloud only | Claude Code (local + cloud) | GitHub Copilot agents only | -| **Configured in**| Environment settings UI | `.claude/settings.json` in repo | `.github/copilot-setup-steps.yml`| -| **Runs** | Before Claude launches | After Claude launches | Before Copilot agent launches | -| **Runs on resume**| No (new sessions only) | Yes (every session) | Yes | -| **Network** | Needs registry access | Needs registry access | Full GitHub Actions network | - -## Common gh Commands for Agents - -```bash -# PRs (use -R in Claude Code cloud) -gh pr create -R owner/repo --title "..." --body "..." -gh pr list -R owner/repo -gh pr view -R owner/repo -gh pr merge -R owner/repo --squash --delete-branch - -# Issues -gh issue list -R owner/repo -gh issue view 42 -R owner/repo -gh issue create -R owner/repo --title "..." --body "..." - -# API (for anything not covered by subcommands) -gh api repos/owner/repo/actions/runs -``` - -## Pitfalls - -| Symptom | Cause | Fix | -|---------|-------|-----| -| `gh: command not found` | Not installed (Claude Code cloud) | Add `apt install -y gh` to setup script | -| `HTTP 401` / auth error | `GH_TOKEN` not set | Add to environment variables in settings UI | -| `HTTP 403` on push | Token lacks `repo` scope | Regenerate PAT with `repo` scope | -| `could not determine repo` | Sandbox proxy hides git remote | Use `-R owner/repo` flag | -| `gh pr create` fails | No upstream branch | Push with `git push -u origin ` first | -| Setup script fails | No network access | Set network to "Limited" (default) or "Full" | - -## References - -- `references/cloud-auth.md` — Token auth, scopes, proxy details, troubleshooting -- `references/copilot-setup-steps.md` — Full guide to customizing the Copilot setup workflow - -## Setup & Activation - -```bash -npx skills add codervisor/forge@github-integration -g -y -``` - -Auto-activates when: user mentions "gh in cloud", "github integration", -"setup script", "copilot setup steps", or `gh` auth failures in cloud -environments. diff --git a/.agents/skills/github-integration/references/cloud-auth.md b/.agents/skills/github-integration/references/cloud-auth.md deleted file mode 100644 index 69eb7b595..000000000 --- a/.agents/skills/github-integration/references/cloud-auth.md +++ /dev/null @@ -1,282 +0,0 @@ -# Cloud Authentication Reference - -How `gh` CLI authentication works in Claude Code cloud and GitHub Copilot -coding agent environments. - -## Table of Contents -1. [Claude Code cloud architecture](#claude-code-cloud-architecture) -2. [GitHub Copilot agent architecture](#github-copilot-agent-architecture) -3. [Token types](#token-types) -4. [Configuring gh](#configuring-gh) -5. [The sandbox proxy](#the-sandbox-proxy) -6. [Network access](#network-access) -7. [Troubleshooting](#troubleshooting) - ---- - -## Claude Code Cloud Architecture - -Claude Code cloud runs sessions in **Anthropic-managed VMs** (Ubuntu 24.04). -Key facts: - -- Each session gets an isolated VM with your repo cloned -- `gh` is **not pre-installed** — must be installed via setup script -- Git auth is handled by a **dedicated proxy** (not a token in the sandbox) -- The git client uses a scoped credential that the proxy translates to your - actual GitHub auth token -- `gh` CLI needs its own auth via the `GH_TOKEN` environment variable -- The proxy restricts `git push` to the current working branch only - -### Session Lifecycle - -1. VM spins up, repo is cloned via the GitHub proxy -2. Setup script runs (if configured) — install `gh` here -3. SessionStart hooks run (if configured in `.claude/settings.json`) -4. Claude Code launches and begins working -5. On completion, changes are pushed to a branch via the proxy - -### What's Pre-installed - -The universal image includes Python, Node.js, Ruby, PHP, Java, Go, Rust, -C++, PostgreSQL 16, Redis 7.0, and common package managers. Run -`check-tools` to see the full list. - -**Not pre-installed:** `gh` CLI. Install it in your setup script. - ---- - -## GitHub Copilot Agent Architecture - -GitHub Copilot coding agents (including Claude as a Copilot agent) run in -**GitHub-managed containers** using GitHub Actions infrastructure. - -- `gh` **is pre-installed** and available immediately -- `GITHUB_TOKEN` is provided automatically via `secrets.GITHUB_TOKEN` -- Configure the environment with `.github/copilot-setup-steps.yml` -- The job **must** be named `copilot-setup-steps` - ---- - -## Token Types - -### GitHub Personal Access Token (PAT) — Claude Code Cloud - -For Claude Code cloud, you provide your own PAT: - -| Setting | Value | -|---------|-------| -| Where to create | GitHub → Settings → Developer settings → Personal access tokens | -| Recommended type | Fine-grained (scoped to specific repos) | -| Required scopes | `repo` (for full repo access) or fine-grained: `contents:write`, `pull_requests:write`, `issues:write` | -| Where to set | Claude Code → Environment Settings → Environment Variables | -| Variable name | `GH_TOKEN` | - -**Security:** The PAT is stored in Anthropic's environment settings and -injected into the VM at session start. It is not committed to the repo. - -### GITHUB_TOKEN — Copilot Agent - -For Copilot coding agents, `GITHUB_TOKEN` is provided automatically: - -| Property | Value | -|----------|-------| -| Lifetime | Scoped to the workflow run | -| Scope | Repository that triggered the session | -| Default permissions | `contents:read`, `metadata:read` | -| Configurable | Yes, via `permissions:` block in the workflow | - ---- - -## Configuring gh - -### Claude Code Cloud - -**Option 1: `GH_TOKEN` environment variable (recommended)** - -Set `GH_TOKEN` in the environment settings UI. `gh` detects it automatically. - -```bash -# Verify it works -gh auth status -``` - -**Option 2: `gh auth login --with-token`** - -If you need explicit login (rare): - -```bash -echo "$GH_TOKEN" | gh auth login --with-token -``` - -### Copilot Agent - -Pass the token in the workflow step: - -```yaml -- name: Authenticate gh CLI - run: gh auth status - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} -``` - ---- - -## The Sandbox Proxy - -Claude Code cloud routes all GitHub traffic through a **dedicated proxy**. - -### How it works - -- The git client inside the sandbox uses a scoped credential -- The proxy verifies this credential and translates it to your actual - GitHub token -- `git push` is restricted to the current working branch -- `git clone`, `git fetch`, and `git pull` work transparently - -### Impact on gh - -The proxy handles git operations, but `gh` makes its own HTTP requests to -the GitHub API. This means: - -1. `gh` needs its own token (`GH_TOKEN`) — it doesn't share the git proxy - credential -2. `gh` may not auto-detect the repo from git remotes due to the proxy - configuration — use the `-R owner/repo` flag - -```bash -# Instead of: -gh pr list - -# Use: -gh pr list -R codervisor/myrepo -``` - ---- - -## Network Access - -### Claude Code Cloud - -Three levels: - -| Level | Description | -|-------|-------------| -| **Limited** (default) | Allows common registries (npm, PyPI, crates.io, etc.) and GitHub domains | -| **Full** | Unrestricted outbound access | -| **None** | No internet (API communication to Anthropic still allowed) | - -Key allowed domains for gh (in Limited mode): -- `github.com`, `api.github.com` -- `raw.githubusercontent.com`, `objects.githubusercontent.com` -- `npm.pkg.github.com`, `ghcr.io` - -**Note:** Setup scripts that install packages (like `apt install gh`) need -network access. The default "Limited" mode allows this since Ubuntu package -repos (`archive.ubuntu.com`, `security.ubuntu.com`) are in the allowlist. - -### Copilot Agent - -Full GitHub Actions network — no restrictions beyond standard Actions limits. - ---- - -## Troubleshooting - -### gh: command not found - -**Environment:** Claude Code cloud only. - -**Cause:** `gh` is not pre-installed in the default image. - -**Fix:** Add to your setup script: -```bash -apt update && apt install -y gh -``` - -Or use a SessionStart hook: -```json -{ - "hooks": { - "SessionStart": [ - { - "hooks": [ - { - "type": "command", - "command": "if [ \"$CLAUDE_CODE_REMOTE\" = \"true\" ]; then apt update && apt install -y gh; fi", - "timeout": 120 - } - ] - } - ] - } -} -``` - -### gh auth status shows "not logged in" - -**Cause:** `GH_TOKEN` not set in the environment. - -**Fix (Claude Code cloud):** Add `GH_TOKEN=ghp_...` to Environment Settings → -Environment Variables. - -**Fix (Copilot agent):** Ensure the workflow step has: -```yaml -env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} -``` - -### "could not determine base repo" / repo not detected - -**Cause:** Sandbox proxy obscures the git remote from `gh`. - -**Fix:** Always pass `-R owner/repo`: -```bash -gh pr create -R codervisor/myrepo --title "..." -``` - -### HTTP 401 Unauthorized - -**Cause:** Token expired, revoked, or never set. - -**Fix:** -1. Check `gh auth status` -2. Verify `GH_TOKEN` is set: `echo $GH_TOKEN | head -c 10` -3. If expired, regenerate the PAT and update environment settings - -### HTTP 403 Forbidden - -**Cause:** Token lacks required permission scope. - -**Fix:** -1. Check error message for the required scope -2. Regenerate PAT with the needed scopes (at minimum: `repo`) -3. For Copilot agents, add permissions to the workflow: - ```yaml - permissions: - contents: write - pull-requests: write - ``` - -### gh works but git push fails - -**Cause:** In Claude Code cloud, git push is restricted to the current -working branch by the proxy. - -**Fix:** Ensure you're pushing to the branch Claude Code checked out. -You cannot push to other branches. - -### Setup script fails to install gh - -**Cause:** Network access is disabled or too restrictive. - -**Fix:** Set network access to "Limited" (default) or "Full" in -environment settings. The default allowlist includes Ubuntu package repos. - -### Rate limiting - -**Cause:** Too many API calls in a short period. - -**Fix:** -1. Check limits: `gh api rate_limit` -2. Use GraphQL for batch queries: `gh api graphql` -3. Add delays between bulk operations diff --git a/.agents/skills/github-integration/references/copilot-setup-steps.md b/.agents/skills/github-integration/references/copilot-setup-steps.md deleted file mode 100644 index 62e48df1c..000000000 --- a/.agents/skills/github-integration/references/copilot-setup-steps.md +++ /dev/null @@ -1,234 +0,0 @@ -# Copilot Setup Steps Reference - -Complete guide to `.github/copilot-setup-steps.yml` — the workflow that -configures cloud coding sessions for Claude Code and GitHub Copilot agents. - -## Table of Contents -1. [What it is](#what-it-is) -2. [File location](#file-location) -3. [Minimal example](#minimal-example) -4. [Full example](#full-example) -5. [Adding project dependencies](#adding-project-dependencies) -6. [Caching](#caching) -7. [Multiple language stacks](#multiple-language-stacks) -8. [Testing the workflow](#testing-the-workflow) - ---- - -## What It Is - -`copilot-setup-steps.yml` is a GitHub Actions workflow that runs when a -cloud coding session starts. It prepares the environment so the AI agent -can: - -- Authenticate with `gh` CLI -- Install project dependencies -- Build the project -- Run linters, formatters, and tests - -The workflow uses the `repository_dispatch` event and runs in the same -container that the agent session uses. - ---- - -## File Location - -Must be at exactly: -``` -.github/copilot-setup-steps.yml -``` - -Not in `.github/workflows/` — this is intentional. It's a setup config, -not a CI workflow. - ---- - -## Minimal Example - -Just gh authentication — no project-specific setup: - -```yaml -name: "Copilot Setup Steps" - -on: repository_dispatch - -jobs: - copilot-setup-steps: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Authenticate gh CLI - run: gh auth status - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} -``` - ---- - -## Full Example - -Node.js project with pnpm, linting, and build: - -```yaml -name: "Copilot Setup Steps" - -on: repository_dispatch - -jobs: - copilot-setup-steps: - runs-on: ubuntu-latest - permissions: - contents: write - pull-requests: write - issues: write - steps: - - uses: actions/checkout@v4 - - - name: Authenticate gh CLI - run: gh auth status - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - - uses: pnpm/action-setup@v4 - - - uses: actions/setup-node@v4 - with: - node-version: '22' - cache: 'pnpm' - - - name: Install dependencies - run: pnpm install --frozen-lockfile - - - name: Build - run: pnpm build - - - name: Verify linter works - run: pnpm lint --quiet -``` - ---- - -## Adding Project Dependencies - -### Node.js (pnpm) - -```yaml -- uses: pnpm/action-setup@v4 -- uses: actions/setup-node@v4 - with: - node-version: '22' - cache: 'pnpm' -- run: pnpm install --frozen-lockfile -``` - -### Node.js (npm) - -```yaml -- uses: actions/setup-node@v4 - with: - node-version: '22' - cache: 'npm' -- run: npm ci -``` - -### Rust - -```yaml -- uses: dtolnay/rust-toolchain@stable -- uses: Swatinem/rust-cache@v2 -- run: cargo build -``` - -### Python - -```yaml -- uses: actions/setup-python@v5 - with: - python-version: '3.12' - cache: 'pip' -- run: pip install -r requirements.txt -``` - -### Go - -```yaml -- uses: actions/setup-go@v5 - with: - go-version: '1.22' -- run: go mod download -``` - ---- - -## Caching - -GitHub Actions caching works in copilot-setup-steps just like in CI. -Use the `cache` parameter in setup actions (e.g., `actions/setup-node`) -or `actions/cache` directly: - -```yaml -- uses: actions/cache@v4 - with: - path: ~/.cache/some-tool - key: ${{ runner.os }}-some-tool-${{ hashFiles('**/lockfile') }} -``` - -Caching significantly speeds up repeated cloud sessions on the same repo. - ---- - -## Multiple Language Stacks - -For hybrid projects (e.g., Rust + Node.js), combine steps: - -```yaml -steps: - - uses: actions/checkout@v4 - - - name: Authenticate gh CLI - run: gh auth status - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - # Node.js - - uses: pnpm/action-setup@v4 - - uses: actions/setup-node@v4 - with: - node-version: '22' - cache: 'pnpm' - - run: pnpm install --frozen-lockfile - - # Rust - - uses: dtolnay/rust-toolchain@stable - - uses: Swatinem/rust-cache@v2 - - - run: pnpm build -``` - ---- - -## Testing the Workflow - -You can't trigger `repository_dispatch` directly from the GitHub UI. -To test: - -### 1. Trigger manually via gh CLI - -```bash -gh api repos/{owner}/{repo}/dispatches \ - --method POST \ - --field event_type=copilot-setup -``` - -### 2. Check the workflow ran - -```bash -gh run list --workflow=copilot-setup-steps.yml -gh run view --log -``` - -### 3. Validate locally - -Run the same commands from the workflow steps in your local terminal to -verify they work before committing. diff --git a/.agents/skills/github-integration/templates/copilot-setup-steps.yml b/.agents/skills/github-integration/templates/copilot-setup-steps.yml deleted file mode 100644 index e9292c7a7..000000000 --- a/.agents/skills/github-integration/templates/copilot-setup-steps.yml +++ /dev/null @@ -1,53 +0,0 @@ -# GitHub Integration — Copilot Setup Steps Template -# -# Enables GitHub CLI (`gh`) and project tools in Claude Code cloud -# and GitHub Copilot coding agent sessions. -# -# INSTALL: Copy this file to .github/copilot-setup-steps.yml in your repo. -# -# CUSTOMIZE: Update the dependency installation and build steps -# to match your project's stack. The gh auth step should stay first. - -name: "Copilot Setup Steps" - -on: repository_dispatch - -jobs: - copilot-setup-steps: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - # --- gh CLI authentication --- - # The GITHUB_TOKEN is provided automatically by the cloud session. - # This step verifies gh can use it. - - name: Authenticate gh CLI - run: gh auth status - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - # --- Node.js projects (uncomment if needed) --- - # - uses: pnpm/action-setup@v4 - # - uses: actions/setup-node@v4 - # with: - # node-version: '22' - # cache: 'pnpm' - # - name: Install dependencies - # run: pnpm install --frozen-lockfile - - # --- Rust projects (uncomment if needed) --- - # - uses: dtolnay/rust-toolchain@stable - # - uses: Swatinem/rust-cache@v2 - - # --- Python projects (uncomment if needed) --- - # - uses: actions/setup-python@v5 - # with: - # python-version: '3.12' - # - run: pip install -r requirements.txt - - # --- Build (uncomment and customize) --- - # - name: Build project - # run: npm run build - - # --- Install CLI tools globally (uncomment and customize) --- - # - run: npm install -g ./packages/cli diff --git a/.agents/skills/issue-spec/.upstream-source b/.agents/skills/issue-spec/.upstream-source deleted file mode 100644 index 9df0ab0c4..000000000 --- a/.agents/skills/issue-spec/.upstream-source +++ /dev/null @@ -1 +0,0 @@ -onsager-ai/onsager-skills \ No newline at end of file diff --git a/.agents/skills/issue-spec/SKILL.md b/.agents/skills/issue-spec/SKILL.md deleted file mode 100644 index 8e73913d8..000000000 --- a/.agents/skills/issue-spec/SKILL.md +++ /dev/null @@ -1,288 +0,0 @@ ---- -name: issue-spec -description: Create lean-spec style GitHub issues as specs for human-AI aligned implementation on the current repo. Use when asked to "create a spec", "write a spec issue", "spec this feature", "spec this", or when planning work that needs a specification before implementation. Follows the lean-spec SDD methodology — small focused specs (<2000 tokens), intent over implementation, context economy. Creates GitHub issues with Overview, Design, Plan, Test, Alignment, and Notes sections. Repo-specific area taxonomy, sister-skill names, custom body sections (e.g. Provider impact / Schema impact / Reach), and additional principles are overlaid by the consumer repo's CLAUDE.md and its `*-dev-process` / `*-pre-push` / `*-pr-lifecycle` sister skills — read those first when the repo isn't obvious. -allowed-tools: Read, Write, Edit, Glob, Grep, Bash(git diff:*), Bash(git log:*), Bash(git show:*), mcp__github__issue_write, mcp__github__issue_read, mcp__github__list_issues, mcp__github__search_issues, mcp__github__sub_issue_write, mcp__github__get_label ---- - -# issue-spec - -Create GitHub issues as lean-spec style specifications for human-AI aligned implementation on whatever repo this skill is installed in. GitHub issues are the sole spec medium — no spec files. - -This skill is the **repo-agnostic methodology** half of the contract. Each consumer repo overlays its own delta in two places: - -- **Repo CLAUDE.md** — names the GitHub slug (`codervisor/lean-spec`, `onsager-ai/onsager`, `onsager-ai/duhem`, …) and any repo-specific spec principles (e.g. Onsager's Reach + seam rule, lean-spec's provider-agnostic core + i18n, Duhem's worked-example + schema-impact). -- **Sister skills** — `-dev-process` carries the area-label taxonomy, the spec-vs-`trivial` gate, and the SDD loop wiring; `-pre-push` carries pre-push gates; `-pr-lifecycle` carries the post-push workflow (including any `pr-spec-sync` automation or the lack of it). - -When in doubt about the target repo, run `git remote -v` and read the repo's `CLAUDE.md` and its `*-dev-process` skill before drafting the spec body. - -## Why GitHub Issues, Not Files - -lean-spec uses Markdown files with YAML frontmatter for metadata. We replace that entirely with GitHub issues because: - -- **Status** → Issue state (open/closed) + status labels (`draft`, `planned`, `in-progress`) -- **Priority** → Labels (`priority:critical`, `priority:high`, `priority:medium`, `priority:low`) -- **Tags** → Labels (`area:`, `feat`, `fix`, `refactor`, `perf`) -- **Dependencies** → Issue references (`depends on #42`) and sub-issues -- **Parent/Child** → Sub-issues via `mcp__github__sub_issue_write` -- **Transitions** → Issue timeline (automatic, auditable) -- **Collaboration** → Comments, reactions, assignments, mentions - -GitHub gives us versioned metadata, collaboration, and relationship tracking for free. No CLI needed, no frontmatter to manage, no sync problems. - -## Philosophy - -Three principles from lean-spec, universal across consumer repos: - -1. **Context Economy** — Keep issue body under ~2000 tokens. Larger features split into parent + child issues. Small specs produce better AI output and better human review. -2. **Intent Over Implementation** — Document the *why* and *what*, not the *how*. Implementation details belong in PRs, not spec issues. The spec captures human intent that isn't in the code. -3. **Living Documents** — Specs evolve via issue comments and edits. Status labels track lifecycle. The issue thread becomes the decision record. - -Each consumer repo may add 1–2 repo-specific principles on top — read the repo's `CLAUDE.md` and its `*-dev-process` sister skill before drafting. Examples of overlay principles you'll find in the wild: - -- **Reach ships with the primitive** (Onsager) — new user-facing primitives must scope in nav entry, first-run flow, empty-state CTAs, and auth gating; deferring discoverability is the bad call. -- **Provider-agnostic core + i18n** (lean-spec) — changes to the provider abstraction declare `## Provider impact`; user-visible strings land in both `en` and `zh-CN`. -- **Worked example + schema impact** (Duhem) — product-surface specs ship with a minimal Verification Definition that exercises the surface; schema-touching changes declare `## Schema impact`. - -If the overlay introduces an additional issue-body section or label (e.g. `Provider impact`, `Schema impact`, `provider-impact`, `schema-impact`, `i18n`), apply it. The repo's CLAUDE.md or sister skill is authoritative for which extras it requires. - -## When to use this skill - -Use when: - -- A change touches multiple files or subsystems. -- Multiple stakeholders need alignment before implementation. -- The AI needs explicit boundaries for a non-trivial feature. -- Work will span multiple PRs (parent + child specs). -- The change touches an externally observable contract — schema, CLI surface, public API, provider trait, event manifest — *regardless of diff size*. Consumer repos may name additional always-spec surfaces in their CLAUDE.md or sister skill; honour them. - -Skip when: - -- A typo or doc-only fix. Use the `trivial` label on the PR instead. -- A one-line bug fix with an obvious reproduction. Just open a PR with `Fixes #existing`. -- The feature already has a spec issue — extend that spec, don't create another. - -**Default is spec, not trivial.** If invocation of this skill is itself the decision — the user said "spec this" or the change clearly isn't a typo/one-liner — proceed straight to Discover. Do not stop to confirm spec-vs-`trivial`. The "Skip when" list is a self-veto for unambiguously trivial diffs; everything else is a spec by default. `trivial` is a sparingly-used escape hatch (see the repo's `*-dev-process` and `*-pre-push` sister skills), not a 50/50 fork to ask about. - -## Setup - -| Parameter | Default | Example override | -|-----------|---------|-----------------| -| **Topic** | _(required)_ | `"session timeout"`, `"fix heartbeat race"` | -| **Scope** | Inferred from codebase | `"only stiglab"`, `"only the cli"` | -| **Priority** | `medium` | `critical`, `high`, `low` | -| **Labels** | Auto from type + area | `"spec, feat, area:"` | -| **Parent** | None | `#42` (umbrella issue) | - -If the user says "spec session timeout", start immediately. Do not ask clarifying questions unless the topic is genuinely ambiguous — and do not ask whether the change should be a `trivial`-labeled PR instead. Invocation of this skill *is* the decision; the "Skip when" list above is the only place that question gets re-litigated, and only for unambiguously trivial diffs. - -## Workflow - -``` -1. Discover Search existing issues and codebase -2. Design Draft the spec issue body -3. Align Partition human decisions vs AI work -4. Validate Self-check before creating -5. Publish Create GitHub issue (+ sub-issues if splitting) -``` - -### 1. Discover - -Before writing anything, understand what exists: - -- Search existing GitHub issues on the target repo for related or duplicate specs. -- Grep the codebase for types, functions, modules related to the topic. -- Read key files that will be affected. -- Check git log for recent changes in the area. -- Read the repo's `CLAUDE.md` and any canonical product doc it points at (e.g. an architecture doc, an ADR, a `docs/-spec.md`) — they ground the spec in existing commitments and identify always-spec surfaces. - -If a related spec issue already exists, reference it — don't duplicate. - -### 2. Design - -Read [references/spec-format.md](references/spec-format.md) for the section-by-section format guide. - -**Don't hard-wrap prose, list items, or blockquote lines.** GitHub renders issue and comment bodies with `breaks: true` — every newline inside a paragraph, list item, or blockquote becomes a `
`, producing visible mid-sentence breaks. Source files in many repos wrap at ~70–100 columns; **issue bodies must not**. Each paragraph, list item, and blockquote line is a single long line; only blank lines separate paragraphs, and each new bullet/quote line starts on its own line. Fenced code blocks and tables preserve formatting and are unaffected. Headings are single-line by markdown's own rules. - -Draft the issue body using the lean-spec structure: - -```markdown -## Overview -Problem statement and motivation. Why does this matter? - -## Design -Technical approach: data flow, API changes, architecture decisions. -Keep it high-level — intent, not implementation. - -## Plan -- [ ] Checklist of concrete deliverables -- [ ] Each item independently verifiable -- [ ] Order reflects implementation sequence - -## Test -- [ ] How to verify each plan item -- [ ] Include: unit tests, integration tests, manual checks - -## Notes -Tradeoffs, context, references. Optional — omit if empty. -``` - -Consumer repos may require additional sections (e.g. `## Provider impact`, `## Schema impact`, `## Worked example`) — read the repo's CLAUDE.md / sister skill for the full list and the rules for when each section is required vs. optional. Templates under [templates/](templates/issue-spec-template.md) cover the universal shape; consumer-repo overlays may extend the template. - -**Context economy check**: If the issue body exceeds ~2000 tokens, split it: - -- Create a parent issue with Overview + high-level Plan -- Create child issues (sub-issues), one per independent concern -- Each child has its own Design, Plan, Test sections -- Link children to parent via `mcp__github__sub_issue_write` - -### 3. Align - -Add an **Alignment** section to the issue body (this extends lean-spec for human-AI collaboration): - -```markdown -## Alignment - -### Human decides -- [ ] Architectural tradeoffs, scope, UX, go/no-go - -### AI implements -- [ ] Concrete code tasks tied to Plan items - -### Open questions -> Items that block AI implementation until a human decides -``` - -**Rules:** - -- Every Plan item maps to either "Human decides" or "AI implements" -- If an item requires both, split it — the decision part is human, the execution is AI -- Open questions use `>` blockquotes so they're visually distinct -- Once a human answers a question (via issue comment), update the Alignment section - -### 4. Validate - -Before creating the issue, self-check: - -- [ ] Body is under ~2000 tokens (context economy) -- [ ] Prose paragraphs, list items, and blockquote lines are not hard-wrapped (each is one long line; blank line between paragraphs, new bullet/quote line on its own) -- [ ] Overview explains *why*, not just *what* -- [ ] Design captures intent, not implementation details -- [ ] Plan items are concrete and independently verifiable -- [ ] Test items map to Plan items -- [ ] Any repo-specific required section (e.g. `## Provider impact`, `## Schema impact`) is present, or the spec provably doesn't touch that surface -- [ ] Human/AI boundaries are explicit — no "figure it out" items -- [ ] No duplicate of an existing issue -- [ ] Dependencies are referenced by issue number - -### 5. Publish - -Create the issue using `mcp__github__issue_write` against the consumer repo: - -**Title format**: `spec(): ` - -`` is drawn from the consumer repo's area-label taxonomy — read the `*-dev-process` sister skill (or the repo's CLAUDE.md if the sister skill defers) for the canonical list. Examples observed across consumer repos: `spec(stiglab): add session timeout`, `spec(provider): github provider — issue CRUD via MCP`, `spec(schema): add api/observe action type`. - -**Labels**: Apply via the issue creation: - -- `spec` — always, marks this as a spec issue -- Type: `feat`, `fix`, `refactor`, `perf` -- Area (consumer-repo taxonomy) -- Priority: `priority:critical`, `priority:high`, `priority:medium`, `priority:low` -- Status: `draft` (initial state) -- Any consumer-repo cross-cutting labels (e.g. `provider-impact`, `schema-impact`, `i18n`) when the corresponding overlay section is non-empty - -**Sub-issues**: If this is a child of a parent spec, link it using `mcp__github__sub_issue_write`. - -**After creating**, report to the user: - -- Issue number and URL -- Token count estimate (flag if over 2000) -- Any open questions that need human decisions -- Sub-issue links if the spec was split - -## Status Lifecycle via Labels - -GitHub issue state (open/closed) combined with status labels: - -``` -open + draft → open + planned → open + in-progress → closed (complete) -``` - -- **draft**: Spec created, open questions may remain. AI wrote it, human hasn't reviewed. -- **planned**: Human reviewed, decisions made, ready for implementation. Remove `draft`, add `planned`. -- **in-progress**: Someone/something is actively working (PR opened). Remove `planned`, add `in-progress`. Some consumer repos automate this transition via a `pr-spec-sync.yml` GitHub Actions workflow; others handle it manually — check the repo's `*-pr-lifecycle` sister skill. -- **closed**: All plan items done, tests passing. PR merge with `Closes #N` closes it automatically. - -**Key rule**: `draft → planned` is the human-AI alignment gate. A spec moves to `planned` only after a human reviews it and resolves open questions. The AI does not flip this label unprompted. - -## Spec Relationships via Sub-Issues - -Use GitHub sub-issues for parent/child decomposition: - -| Relationship | GitHub mechanism | When to use | -|-----------------|---------------------------------------------------------|------------------------------------------| -| **Parent/Child**| Sub-issues (`mcp__github__sub_issue_write`) | Large feature decomposed into pieces | -| **Depends On** | Issue body reference (`depends on #N`) | Spec blocked until another finishes | -| **Related** | Issue body reference (`related: #N`) | Loosely connected specs | - -**Decision rule**: Remove the dependency — does the spec still make sense? If no → sub-issue (child). If yes but blocked → depends on. - -**Example decomposition** (shape, not specific to any one repo): - -``` -spec(): umbrella feature ← parent issue -├── spec(): concern A ← sub-issue -├── spec(): concern B ← sub-issue -└── spec(): UI surface for A+B ← sub-issue -``` - -When a contract under a repo's architectural rule splits work across two subsystems (e.g. a back-end producer + a front-end consumer of an event), use the parent-plus-children shape: one parent spec captures the end-to-end slice, one child spec per subsystem captures its half. The contract lives in the parent's Plan; each child scopes to a single area label. Producer and consumer halves can land in separate PRs as long as both close before the parent does — but the parent's Plan should require a contract test that fails until both halves exist. - -## Guidance - -- **Small is better.** A 500-token spec that captures intent clearly beats a 3000-token spec that tries to cover everything. Split into sub-issues early. -- **Discover first.** Always search existing issues before creating. Duplicate specs create confusion. -- **Status labels reflect reality.** Don't label `planned` if decisions are still open. Don't label `in-progress` until a PR is open. -- **One concern per issue.** If a spec covers two independent changes, split into sub-issues with a shared parent. -- **Reference code, not concepts.** Point to actual types, functions, files — not abstract ideas. Use concrete paths like `crates//src/...` or `packages//src/...` rather than "the foo module." -- **Open questions are alignment points.** These are where AI must stop and ask a human. Make them explicit, specific, and include the impact of each decision. -- **Comments are the decision record.** When a human resolves an open question, they comment on the issue. The thread becomes the audit trail. -- **Use specs for alignment, not for everything.** Regular bugs and small tasks don't need specs. Use specs when: multiple stakeholders need alignment, intent needs persistence, or the AI needs clear boundaries. - -## Handoff to implementation - -Once a spec moves to `planned`: - -1. Create a branch referencing the issue: `claude/spec--` (Claude-owned) or any name (human-owned). -2. Follow the SDD loop in the repo's `*-dev-process` sister skill. -3. Pre-push via the repo's `*-pre-push` sister skill (which typically includes a spec-link check plus the repo's typecheck / lint / test gates). -4. PR body must include `Closes #N` (slice complete) or `Part of #N` (scaffolding). -5. On PR open, the repo's `pr-spec-sync` workflow (if present) flips the issue to `in-progress`; on merge GitHub auto-closes `Closes #N` issues and the merger ticks Plan items on `Part of #N` parents manually. See `*-pr-lifecycle`. - -## Repo-agnostic by construction; consumer overlay is required - -This skill is the **methodology**; it intentionally does not name a repo, an area taxonomy, or a set of cross-cutting labels. Every consumer repo overlays those via: - -- Its `CLAUDE.md` (repo-specific principles, target GitHub slug, always-spec surfaces). -- Its `*-dev-process` sister skill (area-label taxonomy, spec-vs-`trivial` gate, SDD loop). -- Its `*-pre-push` and `*-pr-lifecycle` sister skills (which gates run pre-push and which automation runs post-push). -- Optionally an additional product spec doc (e.g. `docs/-spec.md`, an architecture ADR set) that the repo's CLAUDE.md points at. - -Treat reading those as part of step 1 (Discover). Don't draft a spec without having loaded the consumer repo's overlay context first — a spec that names the wrong area label, misses a required section, or proposes something the repo's seam / schema / provider rule forbids is a spec the human has to rewrite. - -## References - -| Reference | When to read | -|--------------------------------------------------------|-----------------------------------------------------------| -| [references/spec-format.md](references/spec-format.md) | Always — section-by-section guide with worked examples | -| Repo's `CLAUDE.md` | Always — repo-specific principles + always-spec surfaces | -| Repo's `*-dev-process` sister skill | Always — area-label taxonomy + spec-vs-`trivial` gate | -| Repo's `*-pr-lifecycle` sister skill | When publishing — does the repo automate `pr-spec-sync`? | - -## Templates - -| Template | Purpose | -|----------------------------------------------------------------------|----------------------------------------------------------| -| [templates/issue-spec-template.md](templates/issue-spec-template.md) | Universal issue body template — copy and fill | - -Consumer repos may ship an extended template alongside this one (e.g. with a `## Provider impact` or `## Schema impact` block pre-filled). Prefer the consumer-repo extended template when present. diff --git a/.agents/skills/issue-spec/references/spec-format.md b/.agents/skills/issue-spec/references/spec-format.md deleted file mode 100644 index b4d334ed0..000000000 --- a/.agents/skills/issue-spec/references/spec-format.md +++ /dev/null @@ -1,277 +0,0 @@ -# Spec Format Reference - -Section-by-section guide for writing lean-spec style GitHub issue specs. Based on the [lean-spec SDD methodology](https://github.com/codervisor/lean-spec), adapted to use GitHub issues as the sole spec medium. - -This reference is repo-agnostic. Consumer repos overlay their area-label taxonomy, custom body sections (e.g. Provider impact, Schema impact), and additional principles via their `CLAUDE.md` and `*-dev-process` / `*-pre-push` / `*-pr-lifecycle` sister skills — read those first. - -## Metadata via GitHub Issue Features - -No YAML frontmatter — all metadata lives in native GitHub features: - -| lean-spec field | GitHub equivalent | Example | -|--------------------|-----------------------|----------------------------------------------| -| `status` | Labels | `draft`, `planned`, `in-progress` | -| `priority` | Labels | `priority:high` | -| `tags` | Labels | `area:`, `feat` | -| `depends_on` | Issue body reference | `depends on #42` | -| `parent/child` | Sub-issues | Created via `mcp__github__sub_issue_write` | -| `assignee` | Issue assignee | `@username` | -| `created/updated` | Issue timestamps | Automatic | -| `transitions` | Issue timeline | Automatic audit trail | - -### Label Taxonomy - -Apply labels when creating the issue: - -**Required:** - -- `spec` — marks this as a spec issue (always present) - -**Type** (pick one): - -- `feat` — new capability -- `fix` — bug fix -- `refactor` — restructuring without behavior change -- `perf` — performance improvement - -**Area** (pick one or more): - -Drawn from the consumer repo's area taxonomy — read the repo's `*-dev-process` sister skill (or `CLAUDE.md`) for the canonical list. Examples observed across consumer repos: `area:spine`, `area:dashboard`, `area:cli`, `area:ui`, `area:provider`, `area:schema`, `area:runtime`, `area:judge`, `area:docs`, `area:infra`. Respect each repo's architectural invariants when picking the area: a spec that crosses two areas should usually be split into per-area child specs with a shared parent. - -**Priority** (pick one): - -- `priority:critical` — blocks other work, needs immediate attention -- `priority:high` — important, should be next -- `priority:medium` — default -- `priority:low` — nice to have - -**Status** (pick one, update as lifecycle progresses): - -- `draft` — initial state, AI-generated, human review pending -- `planned` — human reviewed, decisions made, ready for implementation -- `in-progress` — actively being worked on (PR open) - -**Cross-cutting (consumer-repo overlay):** - -Some consumer repos define additional discoverability labels for cross-cutting concerns — e.g. `provider-impact` for specs that touch a provider seam, `schema-impact` for schema changes, `i18n` for user-visible string changes, `trivial` (PR-only) for specs-not-required. Apply the ones that exist in the target repo; the repo's CLAUDE.md / sister skill is authoritative. - -### Status Lifecycle - -``` -open + draft → open + planned → open + in-progress → closed -``` - -The `draft → planned` transition is the **human-AI alignment gate**. Only a human moves a spec to `planned` — this confirms: - -- Open questions are resolved -- Design approach is approved -- Scope and priority are accepted - -`planned → in-progress` happens **automatically** on PR open in repos that ship a `pr-spec-sync.yml` workflow, and **manually** in repos that don't. Check the repo's `*-pr-lifecycle` sister skill. - -`in-progress → closed` happens automatically on PR merge with a `Closes #N` keyword. `Part of #N` PRs don't close the parent; the merger ticks the parent's Plan checkboxes manually. - -## Sections - -### Overview - -**Purpose**: Why does this work matter? What problem does it solve? - -**Good overview** (note: prose, list items, and blockquote lines are *not* hard-wrapped — GitHub renders single newlines as `
` in issue bodies): - -```markdown -## Overview - -Sessions in `WAITING_INPUT` state can hang indefinitely if the user disconnects. This wastes agent capacity and leaves stale sessions in the dashboard. We need a configurable timeout that transitions idle sessions to `FAILED` after a period of inactivity. -``` - -**Bad overview:** - -```markdown -## Overview - -Add a timeout feature to sessions. -``` - -The bad version says *what* but not *why*. The AI has no context to make tradeoff decisions during implementation. - -**Guidelines:** - -- 2-4 sentences. Problem → impact → what we need. -- Reference specific code/behavior when possible. -- Don't describe the solution here — that's Design's job. - -### Design - -**Purpose**: How should this work? What's the technical approach? - -**Write intent, not implementation:** - -```markdown -## Design - -Each session gets an inactivity timer that resets on any WebSocket message. When the timer expires: -1. Emit a `SessionTimeoutWarning` event 5 minutes before deadline -2. Transition state to `Failed` with reason `session_timeout` -3. Preserve all session output collected before timeout - -The timeout duration is server-configurable via environment variable. Per-session overrides are out of scope for now. -``` - -**Guidelines:** - -- Describe data flow, state changes, API surface — not line-by-line code. -- Include what's explicitly **out of scope** to prevent scope creep. -- If design is complex, create child sub-issues for subsections. -- Reference existing architecture when relevant. -- Respect the consumer repo's architectural invariants (e.g. event-bus seam rules, provider-agnostic core, holistic verification). The repo's `CLAUDE.md` is authoritative. - -### Plan - -**Purpose**: Concrete deliverables as a checklist. Each item is independently verifiable. - -```markdown -## Plan - -- [ ] Add `SESSION_TIMEOUT` env var to server config (default: 30m) -- [ ] Implement per-session inactivity timer in `SessionManager` -- [ ] Add `SessionTimeoutWarning` event type -- [ ] Emit warning event 5 minutes before timeout -- [ ] Transition `WaitingInput → Failed` on timeout expiry -- [ ] Preserve session output on timeout (no data deletion) -- [ ] Add timeout info to `GET /api/sessions/:id` response -``` - -**Guidelines:** - -- Each item starts with a verb: Add, Implement, Update, Remove, Fix. -- Items should be small enough to verify in isolation. -- Order reflects implementation sequence. -- If a plan has more than ~10 items, the spec is too big — split into sub-issues. -- Checkboxes serve as progress tracking on the issue itself; tick them manually as `Part of #N` PRs merge (see the repo's `*-pr-lifecycle` sister skill). - -### Test - -**Purpose**: How to verify each plan item is done correctly. - -```markdown -## Test - -- [ ] Unit test: config parses valid duration strings, rejects invalid -- [ ] Unit test: timer resets on incoming message -- [ ] Integration test: session transitions to Failed after timeout -- [ ] Integration test: warning event emitted 5 minutes before timeout -- [ ] Integration test: session output preserved after timeout -- [ ] Manual: dashboard shows timeout state and warning indicator -``` - -**Guidelines:** - -- Each test item maps to one or more plan items. -- Specify test type: unit, integration, manual, type check, lint. -- Include negative cases: "rejects invalid", "does not delete". -- For manual tests, describe what to check — not exact click paths. -- Consumer repos may require additional test classes (e.g. i18n locale parity, schema validation) — read the repo's CLAUDE.md / sister skill. - -### Alignment - -**Purpose**: Explicit partition of work between human and AI. This section extends the lean-spec format for human-AI collaborative development. - -```markdown -## Alignment - -### Human decides -- [ ] Timeout default value (proposed: 30m) -- [ ] Whether to show UI warning (toast vs. banner) -- [ ] Behavior on network partition - -### AI implements -- [ ] Config parsing and validation -- [ ] Timer logic in SessionManager -- [ ] Event types and emission -- [ ] State transition + database update -- [ ] Unit and integration tests per Test section - -### Open questions -> Should timed-out sessions be retryable, or must the user create a new task? -> Impact: changes whether final state is `Failed` or `Pending`. -``` - -**Guidelines:** - -- Every Plan item maps to exactly one of: "Human decides" or "AI implements." -- Human items are decisions/tradeoffs. AI items are execution. -- Open questions block implementation — they must be resolved (via issue comments) before the `draft → planned` label transition. -- Once a human answers a question in a comment, update the Alignment section and record the decision. - -### Notes - -**Purpose**: Context, tradeoffs, references — anything that doesn't fit elsewhere. - -```markdown -## Notes - -- Considered per-session timeout overrides via API, but deferred to keep scope small. Can add in a follow-up spec. -- The timeout timer approach uses a per-session async timer. At 100+ concurrent sessions this may need optimization. -- Related: #23, #31 -``` - -**Guidelines:** - -- Tradeoffs considered and why you chose this approach. -- Performance or scalability concerns for future reference. -- Links to related issues, PRs, or external resources. -- Keep it brief — notes are context, not a second design section. -- Omit this section entirely if there's nothing to note. - -### Consumer-repo overlay sections - -Some consumer repos require additional sections in the issue body. Apply the ones that exist in the target repo: - -- **`## Provider impact`** (lean-spec) — required whenever a change touches the provider abstraction or anything crossing the markdown / github backend seam. Captures types added/removed/renamed, trait changes, per-backend semantics, migration path, breaking?-flag. -- **`## Schema impact`** (Duhem) — required whenever a change touches the Verification Definition format, action-type catalog, runtime expressions, judge semantics, or any externally observable contract. Captures fields added/removed/renamed, semantics changes, migration path for in-flight definitions, breaking?-flag. -- **`## Worked example`** (Duhem) — required when a spec introduces or modifies user-visible product surface. A minimal Verification Definition (or link to one) that exercises the surface end-to-end. -- **Reach plan items** (Onsager) — when a spec introduces a new user-facing primitive, the Plan must include nav entry, first-run flow, empty-state CTAs, and auth gating. - -The repo's CLAUDE.md / sister skill is authoritative for which extras it requires. Drop a section only if the change provably doesn't touch its surface. - -## Context Economy Rules - -Smaller specs produce better results — for both AI implementation and human review: - -| Issue body size | Action | -|-----------------|---------------------------------------------------| -| < 500 tokens | Good for bug fixes and small changes | -| 500–2000 tokens | Standard spec — covers most features | -| > 2000 tokens | **Split into parent + sub-issues** | - -**How to split:** - -1. Create a parent issue with Overview + high-level Plan listing the children. -2. Create child issues via `mcp__github__sub_issue_write`, one per independent concern. -3. Each child has its own Design, Plan, Test, Alignment sections. -4. Parent tracks overall progress; children track individual concerns. - -**Example:** - -``` -#50 spec(): umbrella feature ← parent - ├── #51 spec(): concern A ← sub-issue - ├── #52 spec(): concern B ← sub-issue - └── #53 spec(): UI surface for A+B ← sub-issue -``` - -## Title Convention - -``` -spec(): -``` - -`` is one of the consumer repo's `area:*` labels with the `area:` prefix dropped. Examples across consumer repos: - -- `spec(stiglab): add session timeout for idle sessions` -- `spec(provider): github provider — issue CRUD via MCP` -- `spec(schema): add api/observe action type` -- `spec(dashboard): show real-time node heartbeat status` -- `spec(judge): three-state verdict aggregation rules` -- `spec(infra): pin CI action versions to SHAs` diff --git a/.agents/skills/issue-spec/templates/issue-spec-template.md b/.agents/skills/issue-spec/templates/issue-spec-template.md deleted file mode 100644 index d935ae5a4..000000000 --- a/.agents/skills/issue-spec/templates/issue-spec-template.md +++ /dev/null @@ -1,46 +0,0 @@ - - - - - -## Overview - - - -## Design - - - -## Plan - -- [ ] -- [ ] -- [ ] - -## Test - -- [ ] -- [ ] - - - - - - -## Alignment - -### Human decides -- [ ] - -### AI implements -- [ ] - -### Open questions - - -> -> Impact: - -## Notes - - diff --git a/.agents/skills/lean-spec-dev-process/SKILL.md b/.agents/skills/lean-spec-dev-process/SKILL.md index fec204448..3cbb0e84b 100644 --- a/.agents/skills/lean-spec-dev-process/SKILL.md +++ b/.agents/skills/lean-spec-dev-process/SKILL.md @@ -184,12 +184,12 @@ Until automation lands on this repo, the `planned → in-progress` flip on PR op | Stage | Skill / workflow | |---------------------------------------------|-----------------------------------------------------------------| -| Write the spec | [`issue-spec`](../issue-spec/SKILL.md) | +| Write the spec | [`issue-spec`](https://github.com/onsager-ai/dev-skills/blob/main/skills/issue-spec/SKILL.md) (installed globally from `onsager-ai/dev-skills`) | | Commands, CI, publishing, i18n | [`leanspec-development`](../leanspec-development/SKILL.md) | | Pre-push checks | [`lean-spec-pre-push`](../lean-spec-pre-push/SKILL.md) | | CI triage, review, iterate | [`lean-spec-pr-lifecycle`](../lean-spec-pr-lifecycle/SKILL.md) | | On PR merge → tick Plan items | [`lean-spec-pr-lifecycle`](../lean-spec-pr-lifecycle/SKILL.md) (manual) | -| GitHub CLI / cloud auth | [`github-integration`](../github-integration/SKILL.md) | +| GitHub CLI / cloud auth | [`github-integration`](https://github.com/onsager-ai/dev-skills/blob/main/skills/github-integration/SKILL.md) (installed globally from `onsager-ai/dev-skills`) | ## Relationship to Onsager / Duhem dev process diff --git a/.agents/skills/lean-spec-pr-lifecycle/SKILL.md b/.agents/skills/lean-spec-pr-lifecycle/SKILL.md index 01ec8d431..2b8f248a9 100644 --- a/.agents/skills/lean-spec-pr-lifecycle/SKILL.md +++ b/.agents/skills/lean-spec-pr-lifecycle/SKILL.md @@ -194,7 +194,7 @@ After handling a webhook event, end with one or two sentences: what the failure | Related surface | Role | |----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| | [`lean-spec-dev-process`](../lean-spec-dev-process/SKILL.md) | Top-level SDD loop; points here for the post-push stage. | -| [`issue-spec`](../issue-spec/SKILL.md) | Creates the spec issue this PR links to. | +| [`issue-spec`](https://github.com/onsager-ai/dev-skills/blob/main/skills/issue-spec/SKILL.md) | Creates the spec issue this PR links to. Installed globally from `onsager-ai/dev-skills`. | | [`lean-spec-pre-push`](../lean-spec-pre-push/SKILL.md) | Runs before `git push`; enforces the spec-link check locally and owns the conflict walkthrough. | | [`leanspec-development`](../leanspec-development/SKILL.md) | Commands, CI workflows, publishing, changelog format, runner research. | -| [`github-integration`](../github-integration/SKILL.md) | `gh` CLI in cloud sessions (CI inspection only — not for issue/PR mutation). | +| [`github-integration`](https://github.com/onsager-ai/dev-skills/blob/main/skills/github-integration/SKILL.md) | `gh` CLI in cloud sessions (CI inspection only — not for issue/PR mutation). Installed globally from `onsager-ai/dev-skills`. | diff --git a/.agents/skills/lean-spec-pre-push/SKILL.md b/.agents/skills/lean-spec-pre-push/SKILL.md index 0fac33c91..aab0abc34 100644 --- a/.agents/skills/lean-spec-pre-push/SKILL.md +++ b/.agents/skills/lean-spec-pre-push/SKILL.md @@ -164,8 +164,8 @@ If nothing under tracked source paths changed (e.g. docs-only edits): ## What this skill does NOT cover -- Writing the spec issue — see [`issue-spec`](../issue-spec/SKILL.md). +- Writing the spec issue — see [`issue-spec`](https://github.com/onsager-ai/dev-skills/blob/main/skills/issue-spec/SKILL.md) (installed globally from `onsager-ai/dev-skills`). - Opening or managing the PR — see [`lean-spec-pr-lifecycle`](../lean-spec-pr-lifecycle/SKILL.md). - The end-to-end dev loop — see [`lean-spec-dev-process`](../lean-spec-dev-process/SKILL.md). - Commands, CI workflows, publishing pipelines — see [`leanspec-development`](../leanspec-development/SKILL.md). -- GitHub CLI in cloud sessions — see [`github-integration`](../github-integration/SKILL.md). +- GitHub CLI in cloud sessions — see [`github-integration`](https://github.com/onsager-ai/dev-skills/blob/main/skills/github-integration/SKILL.md) (installed globally from `onsager-ai/dev-skills`). diff --git a/.agents/skills/parallel-worktrees/SKILL.md b/.agents/skills/parallel-worktrees/SKILL.md deleted file mode 100644 index e28f2c65a..000000000 --- a/.agents/skills/parallel-worktrees/SKILL.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -name: parallel-worktrees -description: > - Run multiple AI coding agent sessions in parallel using git worktrees — each - agent isolated in its own worktree, working on a separate branch. Use this - skill whenever the user wants to: run two or more AI agents simultaneously on - different features or bugs, set up isolated agent workspaces in the same repo, - push parallel branches to GitHub and open/update PRs, coordinate between - concurrent agent sessions, or clean up after merging. Triggers on: "parallel - agents", "multiple agent sessions", "git worktree", "run agents in parallel", - "work on two things at once", "isolated agent workspace", "spin up another - agent", or any request involving simultaneous AI-assisted development streams. -metadata: - author: Codervisor - version: 0.1.0 - homepage: https://github.com/codervisor/forge ---- - -# Parallel Worktrees - -Run multiple AI coding sessions in parallel — each isolated in its own git -worktree, pushing to its own branch, opening its own PR. - -## When to Use This Skill - -Activate when: -- User wants to run two or more AI agents on different features/bugs at once -- User asks about `git worktree` for agent sessions -- User wants parallel PRs from a single repo without multiple clones -- User needs to set up, coordinate, or clean up concurrent agent workspaces - -## Decision Tree - -``` -What does the user need? - -Start a new parallel session? - → Create a worktree + branch (Lifecycle §1–2) - → Open a terminal/agent session pointed at the worktree path - → Brief the agent: "Work only in . Branch: ." - -Push and open a PR? - → git push -u origin - → gh pr create (GitHub PR Sync reference) - → Note related PRs in the description - -Sync a worktree with the latest main? - → Inside the worktree: git fetch origin && git rebase origin/main - → Never merge across worktrees directly - -Merge and clean up? - → Merge PR on GitHub - → git worktree remove && git branch -d - → git worktree prune - -Hit an error? - → "already checked out" → branch open elsewhere; use a new branch name - → ".git/index.lock" → two processes on same worktree; one agent per worktree - → Detached HEAD → git switch -c inside the worktree - → Stale entry after dir deleted → git worktree prune -``` - -## Core Concepts - -**Worktree vs clone** — A worktree shares the same `.git` directory as the -main checkout. No double-fetch, no disk waste. Each worktree checks out a -*different* branch. Isolated at the filesystem level; same object store. - -**One agent, one worktree, one branch** — This is the cardinal rule. Two -agents sharing a worktree will corrupt each other's index. Two agents on the -same branch will produce conflicting history. - -**PRs as the coordination channel** — Agents communicate intent through PR -titles, descriptions, and comments — not through shared files or direct -worktree reads. - -## Layout Convention - -Keep worktrees as siblings of the repo root to avoid `.gitignore` noise: - -``` -~/projects/ - myrepo/ ← main checkout (main branch) - myrepo-wt/ ← worktree root (sibling dir) - feat/auth/ ← worktree for branch feat/auth - fix/login-bug/ ← worktree for branch fix/login-bug -``` - -## Lifecycle - -### 1. Create a worktree - -```bash -# New branch (most common) -git worktree add ../myrepo-wt/feat/auth -b feat/auth - -# From an existing remote branch -git worktree add ../myrepo-wt/fix/login-bug origin/fix/login-bug -``` - -### 2. Brief the agent - -Give the agent its workspace clearly: - -``` -Working directory: /home/user/projects/myrepo-wt/feat/auth -Branch: feat/auth -Scope: implement JWT authentication — do not touch files outside this scope -``` - -The agent operates entirely within this directory. It should have no awareness -of other worktrees. - -### 3. Work and commit - -Normal git flow inside the worktree — the agent uses `git add`, `git commit` -as usual. The branch is isolated from main and all sibling worktrees. - -### 4. Push and open PR - -```bash -git push -u origin feat/auth -gh pr create \ - --title "feat(auth): implement JWT login" \ - --body "Parallel session. Related: # (if any)." -``` - -See `references/github-pr-sync.md` for draft PRs, PR templates, and linking. - -### 5. Sync with main - -```bash -# Inside the worktree -git fetch origin -git rebase origin/main # keep history linear -``` - -Run this before opening a PR and before the final merge. - -### 6. Merge and clean up - -After the PR merges on GitHub: - -```bash -# From the main repo (not inside the worktree) -git worktree remove ../myrepo-wt/feat/auth -git branch -d feat/auth -git worktree prune # removes stale metadata entries -``` - -## Branch Naming - -Use a consistent pattern so agents (and humans) can parse ownership at a -glance: - -``` -// - -feat/auth/jwt-login -fix/api/null-pointer -chore/deps/upgrade-pnpm -agent/experiment/refactor-parser ← for exploratory agent sessions -``` - -## Pitfalls - -| Symptom | Cause | Fix | -|---------|-------|-----| -| `fatal: 'branch' is already checked out` | Branch open in another worktree | Use a new branch name | -| `.git/index.lock` errors | Two processes on same worktree | One agent per worktree | -| Detached HEAD | Created from a commit SHA, not a branch | `git switch -c ` | -| Worktree path gone after reboot | Dir deleted externally | `git worktree prune`, then recreate | -| `git worktree list` shows stale entries | Dir removed without `git worktree remove` | `git worktree prune` | -| Agent edits files in main checkout | Agent not scoped to worktree path | Re-brief agent with explicit working directory | - -## References - -Read these when you need more depth: - -- `references/worktree-lifecycle.md` — Full command reference, flags, edge cases (multiple worktrees, bare repos, moving worktrees) -- `references/github-pr-sync.md` — PR creation, draft PRs, linking, status checks, merge strategies via `gh` CLI -- `references/agent-coordination.md` — Patterns for coordinating output across parallel sessions: sequencing, handoffs, shared state via PRs - -## Setup & Activation - -```bash -npx skills add codervisor/forge@parallel-worktrees -g -y -``` - -Auto-activates when: user mentions "worktree", "parallel agents", "multiple -agent sessions", or asks to work on several features simultaneously with AI. diff --git a/.agents/skills/parallel-worktrees/references/agent-coordination.md b/.agents/skills/parallel-worktrees/references/agent-coordination.md deleted file mode 100644 index e54c0afe3..000000000 --- a/.agents/skills/parallel-worktrees/references/agent-coordination.md +++ /dev/null @@ -1,224 +0,0 @@ -# Agent Coordination Reference - -Patterns for managing multiple AI agent sessions running in parallel — how to -keep them from stepping on each other, how to hand off work between them, and -how to assemble their outputs. - -## Table of Contents -1. [Core principle](#core-principle) -2. [Scoping sessions](#scoping-sessions) -3. [Dependency ordering](#dependency-ordering) -4. [Handoff patterns](#handoff-patterns) -5. [Avoiding conflicts](#avoiding-conflicts) -6. [Reviewing parallel outputs](#reviewing-parallel-outputs) -7. [Sequencing vs true parallelism](#sequencing-vs-true-parallelism) - ---- - -## Core Principle - -**Agents do not communicate with each other.** There is no message-passing, -no shared memory, no live coordination channel between concurrent sessions. -Each agent sees only its own worktree. - -All coordination happens through artifacts visible to humans and to future -agents: -- **Branch names** — declare ownership and intent -- **PR descriptions** — communicate scope, dependencies, related work -- **PR comments** — status updates, blockers, completion signals -- **Commit messages** — record decisions made during the session - -Design your parallelism so that sessions are independent. If they're not -independent, sequence them — don't try to coordinate live. - ---- - -## Scoping Sessions - -A session brief should answer: -1. **What directory** — the worktree path (absolute) -2. **What branch** — the agent's branch name -3. **What to do** — a bounded task description -4. **What not to touch** — explicit out-of-scope areas -5. **What depends on what** — if this session depends on another PR merging first - -Example brief: -``` -Working directory: /home/user/myrepo-wt/feat/auth -Branch: feat/auth -Task: Implement JWT authentication in packages/api/src/auth/*.ts. -Do not modify packages/ui or the database schema. -This session is independent — no upstream merges required. -``` - -A well-scoped session is one where the agent can complete its work, open a PR, -and never need to look at another worktree. - ---- - -## Dependency Ordering - -When sessions are not independent, make the dependency explicit and sequence -the dependent work: - -### Pattern A: Sequential hand-off - -``` -Session 1: feat/db-schema → merge first -Session 2: feat/auth → starts after Session 1 merges -``` - -Workflow: -1. Start Session 1. -2. While Session 1 is running, *plan* Session 2 but don't start it yet. -3. When Session 1's PR merges, pull main, then start Session 2. - -### Pattern B: Parallel with rebase gate - -Sessions are parallel but one must rebase on the other before merging: - -``` -Session 1: feat/user-model -Session 2: feat/profile-page (depends on user-model types) -``` - -1. Run both sessions in parallel. -2. Merge Session 1 first. -3. In Session 2's worktree: `git fetch origin && git rebase origin/main` -4. Then merge Session 2. - -### Pattern C: Stacked PRs (advanced) - -Session 2's branch is based on Session 1's branch, not main: - -```bash -# Session 2 is based on Session 1's branch -git worktree add ../myrepo-wt/feat/profile -b feat/profile feat/user-model -``` - -PR for Session 2 targets `feat/user-model`, not `main`. After Session 1 -merges, change Session 2's PR base: - -```bash -gh pr edit --base main -``` - -Use stacked PRs sparingly — they require careful ordering and rebase discipline. - ---- - -## Handoff Patterns - -### Agent completes, human reviews, another agent continues - -1. Agent 1 finishes, commits, opens PR. -2. Human reviews the PR (or uses an agent to review). -3. PR merges. -4. Human starts Agent 2, briefed to `git fetch origin && git rebase origin/main` - first to incorporate Agent 1's work. - -### Agent produces an artifact for another agent - -Avoid sharing artifacts by reading files across worktrees. Instead: -- Agent 1 commits the artifact, opens a PR. -- PR merges to main. -- Agent 2 starts fresh from main (or rebases) and reads the committed artifact. - -If the artifact is large or a PR would be too noisy, consider a shared -temporary branch: - -```bash -# Agent 1 pushes to a staging branch -git push origin feat/shared-types - -# Agent 2 rebases on the staging branch -git rebase origin/feat/shared-types -``` - -This is an edge case — prefer merging to main first. - ---- - -## Avoiding Conflicts - -### File-level isolation (preferred) - -Assign each session to a non-overlapping set of files or directories: - -``` -Session 1: packages/api/src/auth/ -Session 2: packages/api/src/payments/ -Session 3: packages/ui/src/components/ -``` - -When you can't avoid overlap on a shared file (e.g., `index.ts`, `routes.ts`): -- Only one session touches the shared file. -- Other sessions import from it but don't modify it. -- Or: sequence the sessions that touch the shared file. - -### Config and generated files - -These are common conflict magnets: -- `package.json` / `pnpm-lock.yaml` — run only one session that installs deps -- `prisma/schema.prisma` — serialize DB schema changes; don't parallelize -- Auto-generated files (GraphQL types, OpenAPI clients) — regenerate once on - main after all sessions merge - -### Pre-merge checklist (per session) - -Before marking a PR ready for merge: -- [ ] `git fetch origin && git rebase origin/main` — resolve any conflicts now -- [ ] Run tests in the worktree -- [ ] Check that no other open PR touches the same files (`gh pr list --json files`) - ---- - -## Reviewing Parallel Outputs - -When multiple sessions complete around the same time: - -1. **Merge one at a time.** Don't merge all PRs simultaneously — the first - merge changes main, which may conflict with the others. -2. **Rebase order matters.** After each merge, rebase the remaining PRs: - ```bash - git fetch origin && git rebase origin/main - git push --force-with-lease - ``` -3. **Review in dependency order.** If sessions have dependencies (Pattern A/B - above), review and merge the upstream session first. - -### Using a review agent - -You can run an agent on the review worktree to read a PR diff and leave -feedback: - -```bash -# Checkout the PR locally -gh pr checkout # this creates a local branch - -# Or in a dedicated review worktree -git worktree add ../myrepo-wt/review/ -b review/ -cd ../myrepo-wt/review/ -gh pr checkout -``` - -Brief the review agent with the PR number and what to focus on. - ---- - -## Sequencing vs True Parallelism - -Not all "parallel" work should actually run simultaneously. Use this guide: - -| Scenario | Recommendation | -|----------|---------------| -| Completely independent files/modules | True parallel — all sessions at once | -| Shared config or schema changes | Sequential — one session at a time | -| Feature + its tests | Same session — keep them together | -| Refactor + new feature | Sequential — refactor first, then feature | -| Multiple bug fixes in unrelated files | True parallel | -| Two features that both modify `main.ts` | Sequential or assign `main.ts` to one session | -| Exploratory/experimental work | True parallel — each in `agent/experiment/` branch | - -The overhead of a worktree is low. When in doubt, serialize rather than -coordinate. diff --git a/.agents/skills/parallel-worktrees/references/github-pr-sync.md b/.agents/skills/parallel-worktrees/references/github-pr-sync.md deleted file mode 100644 index bbf2a56ec..000000000 --- a/.agents/skills/parallel-worktrees/references/github-pr-sync.md +++ /dev/null @@ -1,232 +0,0 @@ -# GitHub PR Sync Reference - -How to push worktree branches to GitHub and manage pull requests via the -`gh` CLI. Assumes `gh` is authenticated (`gh auth status`). - -## Table of Contents -1. [Push a branch](#push-a-branch) -2. [Open a PR](#open-a-pr) -3. [Draft PRs](#draft-prs) -4. [Update a PR](#update-a-pr) -5. [Link related PRs](#link-related-prs) -6. [Check status](#check-status) -7. [Merge strategies](#merge-strategies) -8. [Clean up remote branches](#clean-up-remote-branches) - ---- - -## Push a branch - -From inside the worktree (or with explicit path): - -```bash -git push -u origin -``` - -The `-u` flag sets the upstream tracking reference so future `git push` and -`git pull` in that worktree work without arguments. - ---- - -## Open a PR - -```bash -gh pr create \ - --title "(): " \ - --body "$(cat <<'EOF' -## Summary -- What this PR does (1-3 bullets) - -## Notes -- Related work: # (if any) -- Agent session: - -## Test plan -- [ ] ... -EOF -)" -``` - -### Flags - -| Flag | Use | -|------|-----| -| `--base ` | Target branch (default: repo default branch) | -| `--draft` | Open as draft (see below) | -| `--assignee @me` | Assign to yourself | -| `--label