aidevops 2.52.1

package/.agent/tools/browser/stagehand.md

@@ -0,0 +1,421 @@
+---
+description: Stagehand AI browser automation with natural language
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: true
+  task: true
+---
+
+# Stagehand AI Browser Automation Integration
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: AI-powered browser automation with natural language control
+- **Languages**: JavaScript (npm) + Python (pip)
+- **Setup JS**: `bash .agent/scripts/stagehand-helper.sh setup`
+- **Setup Python**: `bash .agent/scripts/stagehand-python-helper.sh setup`
+- **Setup Both**: `bash .agent/scripts/setup-mcp-integrations.sh stagehand-both`
+
+**Core Primitives**:
+- `act("click login button")` - Natural language actions
+- `extract("get price", z.number())` - Structured data with Zod/Pydantic schemas
+- `observe()` - Discover available actions on page
+- `agent.execute("complete checkout")` - Autonomous workflows
+
+**Config**: `~/.aidevops/stagehand/.env`
+**Env Vars**: `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`, `STAGEHAND_ENV=LOCAL`, `STAGEHAND_HEADLESS=false`
+
+**Key Advantage**: Self-healing automation that adapts when websites change
+<!-- AI-CONTEXT-END -->
+
+**AI-powered browser automation with natural language control - Available in both JavaScript and Python**
+
+> **🆕 NEW**: Stagehand is now available in both JavaScript and Python! Choose the language that best fits your workflow.
+
+## 🚀 **Choose Your Language**
+
+| **JavaScript** | **Python** |
+|----------------|------------|
+| ✅ Native web ecosystem | ✅ Data science & ML integration |
+| ✅ npm/yarn package management | ✅ Pydantic schema validation |
+| ✅ TypeScript + Zod validation | ✅ async/await patterns |
+| ✅ Node.js runtime | ✅ Rich Python ecosystem |
+| **Best for**: Web developers, Node.js projects | **Best for**: Data scientists, Python developers |
+
+### **Quick Setup**
+
+```bash
+# JavaScript Version
+bash .agent/scripts/stagehand-helper.sh setup
+
+# Python Version
+bash .agent/scripts/stagehand-python-helper.sh setup
+
+# Both Versions
+bash .agent/scripts/setup-mcp-integrations.sh stagehand-both
+```
+
+## 🎯 **Overview**
+
+Stagehand is a revolutionary browser automation framework that combines the power of AI with the precision of code. Unlike traditional automation tools that require brittle selectors, or pure AI agents that can be unpredictable, Stagehand lets you choose exactly how much AI to use in your automation workflows.
+
+### **🌟 Key Features**
+
+- **🧠 AI-Powered Actions**: Use natural language to interact with web pages
+- **📊 Structured Data Extraction**: Pull data with schemas using Zod validation
+- **🔍 Intelligent Observation**: Discover available actions on any page
+- **🤖 Autonomous Agents**: Automate entire workflows with AI decision-making
+- **🔒 Local-First**: Works with local browsers for complete privacy
+- **⚡ Self-Healing**: Adapts when websites change, reducing maintenance
+
+### **🆚 Stagehand vs Traditional Tools**
+
+| Feature | Traditional Tools | Stagehand | Pure AI Agents |
+|---------|------------------|-----------|----------------|
+| **Reliability** | Brittle selectors | ✅ Self-healing | Unpredictable |
+| **Flexibility** | Manual updates | ✅ AI adaptation | High but chaotic |
+| **Control** | Full control | ✅ Precise control | Limited control |
+| **Maintenance** | High | ✅ Low | Variable |
+| **Debugging** | Complex | ✅ Transparent | Difficult |
+
+## 🚀 **Quick Start**
+
+### **Installation**
+
+```bash
+# Complete setup (recommended)
+bash .agent/scripts/stagehand-helper.sh setup
+
+# Or step by step
+bash .agent/scripts/stagehand-helper.sh install
+bash .agent/scripts/stagehand-helper.sh create-example
+```
+
+### **Basic Usage**
+
+```javascript
+import { Stagehand } from "@browserbasehq/stagehand";
+import { z } from "zod";
+
+const stagehand = new Stagehand({
+    env: "LOCAL", // Use local browser
+    verbose: 1
+});
+
+await stagehand.init();
+
+// Navigate and interact with natural language
+await stagehand.page.goto("https://example.com");
+await stagehand.act("click the login button");
+
+// Extract structured data
+const data = await stagehand.extract(
+    "get the price and title",
+    z.object({
+        price: z.number(),
+        title: z.string()
+    })
+);
+
+await stagehand.close();
+```
+
+## 🛠️ **Core Primitives**
+
+### **1. Act - Natural Language Actions**
+
+Execute actions using natural language descriptions:
+
+```javascript
+// Simple actions
+await stagehand.act("click the submit button");
+await stagehand.act("fill in the email field with user@example.com");
+await stagehand.act("scroll down to see more content");
+
+// Complex interactions
+await stagehand.act("select 'Premium' from the subscription dropdown");
+await stagehand.act("upload the file from the desktop");
+```
+
+### **2. Extract - Structured Data Extraction**
+
+Pull structured data from pages with schema validation:
+
+```javascript
+// Simple extraction
+const price = await stagehand.extract(
+    "extract the product price",
+    z.number()
+);
+
+// Complex structured data
+const productInfo = await stagehand.extract(
+    "extract product details",
+    z.object({
+        name: z.string().describe("Product name"),
+        price: z.number().describe("Price in USD"),
+        rating: z.number().describe("Star rating out of 5"),
+        reviews: z.array(z.string()).describe("Customer review texts"),
+        inStock: z.boolean().describe("Whether item is in stock")
+    })
+);
+```
+
+### **3. Observe - Discover Available Actions**
+
+Find out what actions are possible on the current page:
+
+```javascript
+// Discover all interactive elements
+const actions = await stagehand.observe();
+
+// Find specific types of actions
+const buttons = await stagehand.observe("find all clickable buttons");
+const forms = await stagehand.observe("find all form fields");
+const links = await stagehand.observe("find navigation links");
+```
+
+### **4. Agent - Autonomous Workflows**
+
+Let AI handle entire workflows autonomously:
+
+```javascript
+const agent = stagehand.agent({
+    cua: true, // Enable Computer Use Agent
+    model: "google/gemini-2.5-computer-use-preview-10-2025"
+});
+
+// High-level task execution
+await agent.execute("complete the checkout process");
+await agent.execute("find and apply for software engineer jobs");
+await agent.execute("research competitor pricing and create a report");
+```
+
+## 🔧 **Configuration**
+
+### **Environment Variables**
+
+Create `~/.aidevops/stagehand/.env`:
+
+```bash
+# AI Provider (choose one)
+OPENAI_API_KEY=your_openai_api_key_here
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+
+# Browser Configuration
+STAGEHAND_ENV=LOCAL          # LOCAL or BROWSERBASE
+STAGEHAND_HEADLESS=false     # Show browser window
+STAGEHAND_VERBOSE=1          # Logging level
+STAGEHAND_DEBUG_DOM=true     # Debug DOM interactions
+
+# Optional: Browserbase (for cloud browsers)
+BROWSERBASE_API_KEY=your_browserbase_api_key_here
+BROWSERBASE_PROJECT_ID=your_browserbase_project_id_here
+```
+
+### **Advanced Configuration**
+
+```javascript
+const stagehand = new Stagehand({
+    env: "LOCAL",
+    verbose: 1,
+    debugDom: true,
+    headless: false,
+    browserOptions: {
+        args: [
+            "--disable-web-security",
+            "--disable-features=VizDisplayCompositor"
+        ]
+    },
+    modelName: "gpt-4o", // or "claude-3-5-sonnet-20241022"
+    modelClientOptions: {
+        apiKey: process.env.OPENAI_API_KEY
+    }
+});
+```
+
+## 📚 **Examples**
+
+### **E-commerce Automation**
+
+```javascript
+// Product research automation
+await stagehand.page.goto("https://amazon.com");
+await stagehand.act("search for 'wireless headphones'");
+
+const products = await stagehand.extract(
+    "extract top 5 products with details",
+    z.array(z.object({
+        name: z.string(),
+        price: z.number(),
+        rating: z.number(),
+        reviewCount: z.number()
+    }))
+);
+
+console.log("Found products:", products);
+```
+
+### **Social Media Automation**
+
+```javascript
+// LinkedIn post engagement
+await stagehand.page.goto("https://linkedin.com/feed");
+await stagehand.act("scroll down to see more posts");
+
+const posts = await stagehand.observe("find posts with engagement buttons");
+await stagehand.act("like the first post about AI technology");
+```
+
+### **Data Collection**
+
+```javascript
+// News article scraping
+await stagehand.page.goto("https://news-website.com");
+
+const articles = await stagehand.extract(
+    "extract all article headlines and summaries",
+    z.array(z.object({
+        headline: z.string(),
+        summary: z.string(),
+        author: z.string(),
+        publishDate: z.string()
+    }))
+);
+```
+
+## 🔗 **Integration with AI DevOps Framework**
+
+### **MCP Integration**
+
+Stagehand can be integrated with the framework's MCP system:
+
+```bash
+# Add Stagehand MCP server (if available)
+bash .agent/scripts/setup-mcp-integrations.sh stagehand
+```
+
+### **Browser Automation Ecosystem**
+
+Stagehand complements existing browser automation tools:
+
+- **Chrome DevTools MCP**: For debugging and performance analysis
+- **Playwright MCP**: For cross-browser testing
+- **Local Browser Automation**: For privacy-focused automation
+- **Stagehand**: For AI-powered, natural language automation
+
+### **Quality Integration**
+
+```bash
+# Run quality checks on Stagehand scripts
+bash .agent/scripts/linters-local.sh ~/.aidevops/stagehand/
+
+# Lint JavaScript/TypeScript files
+bash .agent/scripts/linter-manager.sh install javascript
+```
+
+## 🎯 **Use Cases**
+
+### **🛒 E-commerce & Shopping**
+
+- Product research and price comparison
+- Automated purchasing workflows
+- Inventory monitoring
+- Review and rating analysis
+
+### **📊 Data Collection & Research**
+
+- Web scraping with AI adaptation
+- Competitive analysis automation
+- Market research data gathering
+- Content aggregation
+
+### **🧪 Testing & QA**
+
+- User journey testing
+- Form validation testing
+- Cross-browser compatibility
+- Accessibility testing
+
+### **📱 Social Media Management**
+
+- Content scheduling and posting
+- Engagement automation (ethical)
+- Analytics data collection
+- Community management
+
+### **💼 Business Process Automation**
+
+- Lead generation workflows
+- CRM data entry automation
+- Report generation
+- Administrative task automation
+
+## 🔒 **Security & Privacy**
+
+### **Local-First Approach**
+
+- **Complete Privacy**: All automation runs on your local machine
+- **No Data Transmission**: Sensitive data never leaves your environment
+- **Full Control**: You control all browser instances and data
+- **Enterprise Ready**: Perfect for confidential business processes
+
+### **Ethical Guidelines**
+
+- **Respect Terms of Service**: Always comply with website ToS
+- **Rate Limiting**: Use appropriate delays between actions
+- **Authentic Interactions**: Focus on genuine, valuable automation
+- **Legal Compliance**: Ensure all automation is legally compliant
+
+## 🛠️ **Helper Commands**
+
+```bash
+# Installation and setup
+bash .agent/scripts/stagehand-helper.sh install      # Install Stagehand
+bash .agent/scripts/stagehand-helper.sh setup        # Complete setup
+bash .agent/scripts/stagehand-helper.sh status       # Check installation
+
+# Development and testing
+bash .agent/scripts/stagehand-helper.sh create-example  # Create example script
+bash .agent/scripts/stagehand-helper.sh run-example     # Run basic example
+bash .agent/scripts/stagehand-helper.sh logs            # View logs
+
+# Maintenance
+bash .agent/scripts/stagehand-helper.sh clean        # Clean cache and logs
+```
+
+## 📖 **Resources**
+
+### **Official Documentation**
+
+- **Stagehand Docs**: https://docs.stagehand.dev
+- **GitHub Repository**: https://github.com/browserbase/stagehand
+- **Quickstart Guide**: https://docs.stagehand.dev/v3/first-steps/quickstart
+
+### **AI DevOps Framework Integration**
+
+- **Browser Automation**: docs/BROWSER-AUTOMATION.md
+- **MCP Integrations**: docs/MCP-INTEGRATIONS.md
+- **Quality Standards**: .agent/tools/code-review/code-standards.md
+
+### **Community & Support**
+
+- **Discord**: https://discord.gg/stagehand
+- **Slack**: https://join.slack.com/t/stagehand-dev/shared_invite/...
+- **GitHub Issues**: https://github.com/browserbase/stagehand/issues
+
+---
+
+**🎉 Ready to revolutionize your browser automation with AI? Get started with Stagehand today!**
+
+```bash
+bash .agent/scripts/stagehand-helper.sh setup
+```

package/.agent/tools/build-agent/agent-review.md

@@ -0,0 +1,224 @@
+---
+description: Systematic review and improvement of agent instructions
+mode: subagent
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: false
+  glob: true
+  grep: true
+  webfetch: false
+  task: true
+---
+
+# Agent Review - Reviewing and Improving Agents
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Systematic review and improvement of agent instructions
+- **Trigger**: End of session, user correction, observable failure
+- **Output**: Proposed improvements with evidence and scope
+
+**Review Checklist**:
+1. Instruction count - over budget?
+2. Universal applicability - task-specific content?
+3. Duplicate detection - same guidance elsewhere?
+4. Code examples - still accurate? authoritative?
+5. AI-CONTEXT block - captures essentials?
+
+**Self-Assessment Triggers**:
+- User corrects agent response
+- Commands/paths fail
+- Contradiction with authoritative sources
+- Staleness indicators (versions, deprecated APIs)
+
+**Process**: Complete task first, cite evidence, check duplicates, propose specific fix, ask permission
+
+**Testing**: Use OpenCode CLI to test agent/config changes without restarting TUI:
+
+```bash
+opencode run "Test query" --agent [agent-name]
+```text
+
+See `tools/opencode/opencode.md` for CLI testing patterns.
+
+<!-- AI-CONTEXT-END -->
+
+## Agent Review Process
+
+### When to Review
+
+1. **End of significant session** - After complex multi-step tasks
+2. **User correction** - Immediate trigger for targeted review
+3. **Observable failure** - Commands fail, paths don't exist
+4. **Periodic maintenance** - Scheduled review cycles
+
+### When Agents Should Suggest @agent-review
+
+All agents should suggest calling `@agent-review` at these points:
+
+1. **After PR merge** - Capture what worked in the PR process
+2. **After release** - Document release learnings
+3. **After fixing multiple issues** - Pattern recognition opportunity
+4. **After user correction** - Immediate improvement opportunity
+5. **Before starting unrelated work** - Clean context boundary
+6. **After long session** - Capture accumulated learnings
+
+**Suggestion format:**
+
+```text
+---
+Session complete. Consider running @agent-review to:
+- Capture patterns from {specific accomplishment}
+- Identify improvements to {agents used}
+- Document {any corrections or failures}
+
+Options:
+1. Run @agent-review now
+2. Start new session (clean context)
+3. Continue in current session
+---
+```
+
+See `workflows/session-manager.md` for full session lifecycle guidance.
+
+### Review Checklist
+
+For each agent file under review:
+
+#### 1. Instruction Count
+
+- Count discrete instructions (bullets, rules, directives)
+- Target: <50 for main agents, <100 for detailed subagents
+- If over budget: consolidate, move to subagent, or remove
+
+#### 2. Universal Applicability
+
+- Is every instruction relevant to >80% of tasks?
+- Task-specific content should move to subagents
+- Check for edge cases that became main content
+
+#### 3. Duplicate Detection
+
+```bash
+# Search for similar instructions across all agents
+rg "pattern" .agent/
+
+# Check specific files that might overlap
+diff .agent/file1.md .agent/file2.md
+```text
+
+- Same concept should have single authoritative source
+- Cross-references okay, duplicated instructions not okay
+
+#### 4. Code Examples Audit
+
+For each code example:
+- Is it authoritative (the reference implementation)?
+- Does it still work? Test if possible
+- Are secrets properly placeholder'd?
+- Could it be a `file:line` reference instead?
+
+#### 5. AI-CONTEXT Block Quality
+
+- Does condensed version capture all essentials?
+- Is it readable without the detailed section?
+- Would an AI get stuck with only the AI-CONTEXT?
+
+### Improvement Proposal Format
+
+When proposing changes:
+
+```markdown
+## Agent Improvement Proposal
+
+**File**: `.agent/[path]/[file].md`
+**Issue**: [Brief description]
+**Evidence**: [Specific failure, contradiction, or user feedback]
+
+**Related Files** (checked for duplicates):
+- `.agent/[other-file].md` - [relationship]
+- `.agent/[another-file].md` - [relationship]
+
+**Proposed Change**:
+[Specific before/after or description]
+
+**Impact Assessment**:
+- [ ] No conflicts with other agents
+- [ ] Instruction count impact: [+/- N]
+- [ ] Tested if code example
+```text
+
+### Common Improvement Patterns
+
+#### Consolidating Instructions
+
+```markdown
+# Before (5 instructions)
+- Use local variables
+- Assign parameters to locals
+- Never use $1 directly
+- Pattern: local var="$1"
+- This prevents issues
+
+# After (1 instruction)
+- Pattern: `local var="$1"` for all parameters
+```text
+
+#### Moving to Subagent
+
+```markdown
+# Before (in main AGENTS.md)
+## Database Schema Guidelines
+[50 lines of detailed rules]
+
+# After (in AGENTS.md)
+See `aidevops/architecture.md` for schema guidelines
+
+# After (in architecture.md)
+## Database Schema Guidelines
+[50 lines of detailed rules]
+```text
+
+#### Replacing Code with Reference
+
+```markdown
+# Before
+Here's the error handling pattern:
+```bash
+if ! result=$(command); then
+    echo "Error: $result"
+    return 1
+fi
+```text
+
+## After
+
+See error handling pattern at `.agent/scripts/hostinger-helper.sh:145`
+
+```text
+
+### Session Review Workflow
+
+At end of significant session:
+
+1. **Note any corrections** - What did user correct?
+2. **Note any failures** - What didn't work as expected?
+3. **Check instructions used** - Which agents were relevant?
+4. **Propose improvements** - Following format above
+5. **Ask permission** - User decides if changes are made
+
+### Contributing Improvements
+
+Improvements to aidevops agents benefit all users:
+
+1. Create improvement proposal
+2. Make changes in `~/Git/aidevops/`
+3. Run quality check: `.agent/scripts/linters-local.sh`
+4. Commit with descriptive message
+5. Create PR to upstream
+
+See `workflows/release-process.md` for contribution workflow.