@fro.bot/systematic 1.22.7 → 1.23.0

package/skills/agent-browser/references/video-recording.md

@@ -0,0 +1,173 @@
+# 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

package/skills/agent-browser/templates/authenticated-session.sh

@@ -0,0 +1,105 @@
+#!/bin/bash
+# Template: Authenticated Session Workflow
+# Purpose: Login once, save state, reuse for subsequent runs
+# Usage: ./authenticated-session.sh <login-url> [state-file]
+#
+# RECOMMENDED: Use the auth vault instead of this template:
+#   echo "<pass>" | agent-browser auth save myapp --url <login-url> --username <user> --password-stdin
+#   agent-browser auth login myapp
+# The auth vault stores credentials securely and the LLM never sees passwords.
+#
+# 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 <login-url> [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..."
+    if agent-browser --state "$STATE_FILE" open "$LOGIN_URL" 2>/dev/null; then
+        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..."
+        agent-browser close 2>/dev/null || true
+    else
+        echo "Failed to load state, re-authenticating..."
+    fi
+    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

package/skills/agent-browser/templates/capture-workflow.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# Template: Content Capture Workflow
+# Purpose: Extract content from web pages (text, screenshots, PDF)
+# Usage: ./capture-workflow.sh <url> [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 <url> [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"

package/skills/agent-browser/templates/form-automation.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# Template: Form Automation Workflow
+# Purpose: Fill and submit web forms with validation
+# Usage: ./form-automation.sh <form-url>
+#
+# 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 <form-url>}"
+
+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"

package/skills/agent-native-audit/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: agent-native-audit
+description: Run comprehensive agent-native architecture review with scored principles
+argument-hint: '[optional: specific principle to audit]'
+disable-model-invocation: true
+---
+
+# Agent-Native Architecture Audit
+
+Conduct a comprehensive review of the codebase against agent-native architecture principles, launching parallel sub-agents for each principle and producing a scored report.
+
+## Core Principles to Audit
+
+1. **Action Parity** - "Whatever the user can do, the agent can do"
+2. **Tools as Primitives** - "Tools provide capability, not behavior"
+3. **Context Injection** - "System prompt includes dynamic context about app state"
+4. **Shared Workspace** - "Agent and user work in the same data space"
+5. **CRUD Completeness** - "Every entity has full CRUD (Create, Read, Update, Delete)"
+6. **UI Integration** - "Agent actions immediately reflected in UI"
+7. **Capability Discovery** - "Users can discover what the agent can do"
+8. **Prompt-Native Features** - "Features are prompts defining outcomes, not code"
+
+## Workflow
+
+### Step 1: Load the Agent-Native Skill
+
+First, invoke the agent-native-architecture skill to understand all principles:
+
+```
+/systematic:agent-native-architecture
+```
+
+Select option 7 (action parity) to load the full reference material.
+
+### Step 2: Launch Parallel Sub-Agents
+
+Launch 8 parallel sub-agents using the task tool with `subagent_type: Explore`, one for each principle. Each agent should:
+
+1. Enumerate ALL instances in the codebase (user actions, tools, contexts, data stores, etc.)
+2. Check compliance against the principle
+3. Provide a SPECIFIC SCORE like "X out of Y (percentage%)"
+4. List specific gaps and recommendations
+
+<sub-agents>
+
+**Agent 1: Action Parity**
+```
+Audit for ACTION PARITY - "Whatever the user can do, the agent can do."
+
+Tasks:
+1. Enumerate ALL user actions in frontend (API calls, button clicks, form submissions)
+   - Search for API service files, fetch calls, form handlers
+   - Check routes and components for user interactions
+2. Check which have corresponding agent tools
+   - Search for agent tool definitions
+   - Map user actions to agent capabilities
+3. Score: "Agent can do X out of Y user actions"
+
+Format:
+## Action Parity Audit
+### User Actions Found
+| Action | Location | Agent Tool | Status |
+### Score: X/Y (percentage%)
+### Missing Agent Tools
+### Recommendations
+```
+
+**Agent 2: Tools as Primitives**
+```
+Audit for TOOLS AS PRIMITIVES - "Tools provide capability, not behavior."
+
+Tasks:
+1. Find and read ALL agent tool files
+2. Classify each as:
+   - PRIMITIVE (good): read, write, store, list - enables capability without business logic
+   - WORKFLOW (bad): encodes business logic, makes decisions, orchestrates steps
+3. Score: "X out of Y tools are proper primitives"
+
+Format:
+## Tools as Primitives Audit
+### Tool Analysis
+| Tool | File | Type | Reasoning |
+### Score: X/Y (percentage%)
+### Problematic Tools (workflows that should be primitives)
+### Recommendations
+```
+
+**Agent 3: Context Injection**
+```
+Audit for CONTEXT INJECTION - "System prompt includes dynamic context about app state"
+
+Tasks:
+1. Find context injection code (search for "context", "system prompt", "inject")
+2. Read agent prompts and system messages
+3. Enumerate what IS injected vs what SHOULD be:
+   - Available resources (files, drafts, documents)
+   - User preferences/settings
+   - Recent activity
+   - Available capabilities listed
+   - Session history
+   - Workspace state
+
+Format:
+## Context Injection Audit
+### Context Types Analysis
+| Context Type | Injected? | Location | Notes |
+### Score: X/Y (percentage%)
+### Missing Context
+### Recommendations
+```
+
+**Agent 4: Shared Workspace**
+```
+Audit for SHARED WORKSPACE - "Agent and user work in the same data space"
+
+Tasks:
+1. Identify all data stores/tables/models
+2. Check if agents read/write to SAME tables or separate ones
+3. Look for sandbox isolation anti-pattern (agent has separate data space)
+
+Format:
+## Shared Workspace Audit
+### Data Store Analysis
+| Data Store | User Access | Agent Access | Shared? |
+### Score: X/Y (percentage%)
+### Isolated Data (anti-pattern)
+### Recommendations
+```
+
+**Agent 5: CRUD Completeness**
+```
+Audit for CRUD COMPLETENESS - "Every entity has full CRUD"
+
+Tasks:
+1. Identify all entities/models in the codebase
+2. For each entity, check if agent tools exist for:
+   - Create
+   - Read
+   - Update
+   - Delete
+3. Score per entity and overall
+
+Format:
+## CRUD Completeness Audit
+### Entity CRUD Analysis
+| Entity | Create | Read | Update | Delete | Score |
+### Overall Score: X/Y entities with full CRUD (percentage%)
+### Incomplete Entities (list missing operations)
+### Recommendations
+```
+
+**Agent 6: UI Integration**
+```
+Audit for UI INTEGRATION - "Agent actions immediately reflected in UI"
+
+Tasks:
+1. Check how agent writes/changes propagate to frontend
+2. Look for:
+   - Streaming updates (SSE, WebSocket)
+   - Polling mechanisms
+   - Shared state/services
+   - Event buses
+   - File watching
+3. Identify "silent actions" anti-pattern (agent changes state but UI doesn't update)
+
+Format:
+## UI Integration Audit
+### Agent Action → UI Update Analysis
+| Agent Action | UI Mechanism | Immediate? | Notes |
+### Score: X/Y (percentage%)
+### Silent Actions (anti-pattern)
+### Recommendations
+```
+
+**Agent 7: Capability Discovery**
+```
+Audit for CAPABILITY DISCOVERY - "Users can discover what the agent can do"
+
+Tasks:
+1. Check for these 7 discovery mechanisms:
+   - Onboarding flow showing agent capabilities
+   - Help documentation
+   - Capability hints in UI
+   - Agent self-describes in responses
+   - Suggested prompts/actions
+   - Empty state guidance
+   - Slash commands (/help, /tools)
+2. Score against 7 mechanisms
+
+Format:
+## Capability Discovery Audit
+### Discovery Mechanism Analysis
+| Mechanism | Exists? | Location | Quality |
+### Score: X/7 (percentage%)
+### Missing Discovery
+### Recommendations
+```
+
+**Agent 8: Prompt-Native Features**
+```
+Audit for PROMPT-NATIVE FEATURES - "Features are prompts defining outcomes, not code"
+
+Tasks:
+1. Read all agent prompts
+2. Classify each feature/behavior as defined in:
+   - PROMPT (good): outcomes defined in natural language
+   - CODE (bad): business logic hardcoded
+3. Check if behavior changes require prompt edit vs code change
+
+Format:
+## Prompt-Native Features Audit
+### Feature Definition Analysis
+| Feature | Defined In | Type | Notes |
+### Score: X/Y (percentage%)
+### Code-Defined Features (anti-pattern)
+### Recommendations
+```
+
+</sub-agents>
+
+### Step 3: Compile Summary Report
+
+After all agents complete, compile a summary with:
+
+```markdown
+## Agent-Native Architecture Review: [Project Name]
+
+### Overall Score Summary
+
+| Core Principle | Score | Percentage | Status |
+|----------------|-------|------------|--------|
+| Action Parity | X/Y | Z% | ✅/⚠️/❌ |
+| Tools as Primitives | X/Y | Z% | ✅/⚠️/❌ |
+| Context Injection | X/Y | Z% | ✅/⚠️/❌ |
+| Shared Workspace | X/Y | Z% | ✅/⚠️/❌ |
+| CRUD Completeness | X/Y | Z% | ✅/⚠️/❌ |
+| UI Integration | X/Y | Z% | ✅/⚠️/❌ |
+| Capability Discovery | X/Y | Z% | ✅/⚠️/❌ |
+| Prompt-Native Features | X/Y | Z% | ✅/⚠️/❌ |
+
+**Overall Agent-Native Score: X%**
+
+### Status Legend
+- ✅ Excellent (80%+)
+- ⚠️ Partial (50-79%)
+- ❌ Needs Work (<50%)
+
+### Top 10 Recommendations by Impact
+
+| Priority | Action | Principle | Effort |
+|----------|--------|-----------|--------|
+
+### What's Working Excellently
+
+[List top 5 strengths]
+```
+
+## Success Criteria
+
+- [ ] All 8 sub-agents complete their audits
+- [ ] Each principle has a specific numeric score (X/Y format)
+- [ ] Summary table shows all scores and status indicators
+- [ ] Top 10 recommendations are prioritized by impact
+- [ ] Report identifies both strengths and gaps
+
+## Optional: Single Principle Audit
+
+If $ARGUMENTS specifies a single principle (e.g., "action parity"), only run that sub-agent and provide detailed findings for that principle alone.
+
+Valid arguments:
+- `action parity` or `1`
+- `tools` or `primitives` or `2`
+- `context` or `injection` or `3`
+- `shared` or `workspace` or `4`
+- `crud` or `5`
+- `ui` or `integration` or `6`
+- `discovery` or `7`
+- `prompt` or `features` or `8`
+