aidevops 2.52.1 → 2.53.1

package/.agent/tools/opencode/opencode.md

@@ -1,651 +0,0 @@
----
-description: OpenCode CLI integration and configuration
-mode: subagent
-tools:
-  read: true
-  write: true
-  edit: true
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
----
-
-# OpenCode Integration
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **Primary Agent**: `aidevops` - Full framework access
-- **Subagents**: hostinger, hetzner, wordpress, seo, code-quality, browser-automation, etc.
-- **Setup**: `./setup.sh` (from aidevops repo)
-- **MCPs disabled globally** - enabled per-agent to save context tokens
-
-**Critical Paths** (AI assistants often need these):
-
-| Purpose | Path |
-|---------|------|
-| Main config | `~/.config/opencode/opencode.json` |
-| Agent files | `~/.config/opencode/agent/*.md` |
-| Alternative config | `~/.opencode/` (some installations) |
-| aidevops agents | `~/.aidevops/agents/` (after setup.sh) |
-| Credentials | `~/.config/aidevops/mcp-env.sh` |
-
-**Key Commands**:
-
-```bash
-# Install agents
-.agent/scripts/generate-opencode-agents.sh
-
-# Check status
-.agent/scripts/generate-opencode-agents.sh
-
-# Authenticate (OAuth plugins)
-opencode auth login
-# - Google → Antigravity (Gemini/Claude via Google)
-# - Anthropic → Claude Pro/Max (direct Claude access)
-
-# In OpenCode:
-# - Tab to switch primary agents
-# - @agent-name to invoke subagents
-```text
-
-<!-- AI-CONTEXT-END -->
-
-## Overview
-
-OpenCode is a CLI AI assistant that supports specialized agents and MCP (Model Context Protocol) servers. This integration configures OpenCode with aidevops-specific agents and MCPs.
-
-## Antigravity OAuth Plugin
-
-The aidevops setup automatically installs the [opencode-antigravity-auth](https://github.com/NoeFabris/opencode-antigravity-auth) plugin, enabling Google OAuth authentication for premium model access.
-
-**Authenticate after setup:**
-
-```bash
-opencode auth login
-# Select: Google → OAuth with Google (Antigravity)
-# Press Enter to skip Project ID prompt
-```text
-
-**Available models via Antigravity:**
-
-- `gemini-3-pro-high` / `gemini-3-pro-low` / `gemini-3-flash`
-- `claude-sonnet-4-5` / `claude-sonnet-4-5-thinking` / `claude-opus-4-5-thinking`
-- `gpt-oss-120b-medium`
-
-**Multi-account load balancing:** Add multiple Google accounts for automatic rate limit distribution. Run `opencode auth login` again to add more accounts.
-
-## Anthropic OAuth Plugin
-
-The aidevops setup automatically installs the [opencode-anthropic-auth](https://github.com/anomalyco/opencode-anthropic-auth) plugin, enabling OAuth authentication for Claude Pro/Max accounts.
-
-**Authenticate after setup:**
-
-```bash
-opencode auth login
-# Select: Anthropic → Claude Pro/Max (or Create an API Key)
-# Complete OAuth flow in browser
-# Paste authorization code when prompted
-```
-
-**Authentication methods:**
-
-| Method | Use Case | Cost |
-|--------|----------|------|
-| **Claude Pro/Max** | Active subscription holders | $0 (subscription covers usage) |
-| **Create API Key** | OAuth-based key creation | Standard API rates |
-| **Manual API Key** | Existing API keys | Standard API rates |
-
-**Benefits of OAuth:**
-- Automatic token refresh (no re-authentication)
-- Beta features auto-enabled (extended thinking, etc.)
-- Zero cost for Pro/Max subscribers
-- No manual API key management
-
-**See also:** `tools/opencode/opencode-anthropic-auth.md` for detailed setup and troubleshooting.
-
-## Installation
-
-### Prerequisites
-
-1. **OpenCode CLI** installed - https://opencode.ai
-2. **aidevops framework** cloned to `~/Git/aidevops/`
-3. **MCP servers** installed (optional, per-service)
-
-### Quick Setup
-
-```bash
-# Run the setup script
-cd ~/Git/aidevops
-.agent/scripts/generate-opencode-agents.sh
-```text
-
-This creates:
-- `~/.config/opencode/agent/` directory
-- Agent markdown files for each service
-- Updates `opencode.json` with agent configurations
-
-## Agent Architecture
-
-### Primary Agent: aidevops
-
-The main agent with full framework access. Use `Tab` to switch to it.
-
-**Capabilities**:
-- All built-in tools (write, edit, bash, read, glob, grep, webfetch, task)
-- Access to all helper scripts
-- Full documentation access
-
-### Subagents
-
-Specialized agents invoked with `@agent-name`. MCPs are enabled only for relevant subagents.
-
-| Agent | Description | MCPs Enabled |
-|-------|-------------|--------------|
-| `aidevops` | Full framework (primary) | context7 |
-| `hostinger` | Hosting, WordPress, DNS | hostinger-api |
-| `hetzner` | Cloud infrastructure | hetzner-* (4 accounts) |
-| `wordpress` | Local dev, MainWP | localwp, context7 |
-| `seo` | Search Console, Ahrefs | gsc, ahrefs |
-| `code-quality` | Quality scanning + learning loop | context7 |
-| `browser-automation` | Testing, scraping | chrome-devtools, context7 |
-| `context7-mcp-setup` | Documentation | context7 |
-| `git-platforms` | GitHub, GitLab, Gitea | gh_grep, context7 |
-| `crawl4ai-usage` | Web crawling | context7 |
-| `dns-providers` | DNS management | hostinger-api (DNS) |
-| `agent-review` | Session analysis, improvements | (read/write only) |
-
-## Configuration
-
-### opencode.json Structure
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "hostinger-api": {
-      "type": "local",
-      "command": [...],
-      "enabled": false
-    }
-  },
-  "tools": {
-    "hostinger-api_*": false
-  },
-  "agent": {
-    "hostinger": {
-      "description": "...",
-      "mode": "subagent",
-      "tools": {
-        "hostinger-api_*": true
-      }
-    }
-  }
-}
-```text
-
-**Key Design**:
-- MCPs are defined but `enabled: false` (not started at launch)
-- Tools are disabled globally with `"mcp_*": false`
-- Each subagent enables its specific tools with `"mcp_*": true`
-
-This saves context tokens by only loading MCP tools when the relevant subagent is invoked.
-
-### Agent Markdown Format
-
-Agents can be defined as markdown files in `~/.config/opencode/agent/`:
-
-```markdown
----
-description: Short description for the agent
-mode: subagent
-temperature: 0.1
-tools:
-  bash: true
-  mcp-name_*: true
----
-
-# Agent Name
-
-Detailed instructions for the agent...
-```text
-
-## Usage
-
-### Switching Agents
-
-- **Tab**: Cycle through primary agents
-- **@agent-name**: Invoke a subagent
-
-### Agent Invocation Order
-
-OpenCode doesn't have built-in workflow orchestration, but agents should be invoked in logical order based on dependencies:
-
-#### Recommended Workflow Order
-
-```text
-┌─────────────────────────────────────────────────────────────────┐
-│                    DEVELOPMENT WORKFLOW                         │
-├─────────────────────────────────────────────────────────────────┤
-│  1. PLAN/RESEARCH (parallel)                                    │
-│     @context7-mcp-setup  - Get documentation                    │
-│     @seo                 - Research keywords/competitors        │
-│     @browser-automation  - Scrape/test existing sites           │
-│                                                                 │
-│  2. INFRASTRUCTURE (sequential)                                 │
-│     @dns-providers       - Configure DNS first                  │
-│     @hetzner             - Provision servers                    │
-│     @hostinger           - Setup hosting/WordPress              │
-│                                                                 │
-│  3. DEVELOPMENT (parallel)                                      │
-│     @wordpress           - Local development                    │
-│     @git-platforms       - Repository management                │
-│     @crawl4ai-usage      - Data extraction                      │
-│                                                                 │
-│  4. QUALITY (sequential)                                        │
-│     @code-standards        - Run checks, apply fixes              │
-│     @agent-review        - Session analysis + PR                │
-└─────────────────────────────────────────────────────────────────┘
-```text
-
-#### Parallel vs Sequential
-
-| Type | Agents | When to Use |
-|------|--------|-------------|
-| **Parallel** | Research agents (seo, context7, browser) | No dependencies between tasks |
-| **Sequential** | Infrastructure (dns → server → hosting) | Output of one is input to next |
-| **Always Last** | code-quality, agent-review | Requires completed work to review |
-
-#### Invoking Multiple Agents
-
-OpenCode processes one `@mention` per message. For parallel work, send separate messages:
-
-```bash
-# Parallel research (send in quick succession)
-> @seo analyze competitors for example.com
-> @context7-mcp-setup get Next.js caching docs
-> @browser-automation screenshot example.com homepage
-
-# Sequential infrastructure (wait for each to complete)
-> @dns-providers create A record for app.example.com → 1.2.3.4
-# Wait for DNS propagation...
-> @hetzner create server app-server in brandlight
-# Wait for server...
-> @hostinger deploy WordPress to app.example.com
-```text
-
-#### End-of-Session Pattern (MANDATORY)
-
-**Always end sessions with these agents in order:**
-
-1. **@code-standards** - Fix any quality issues introduced
-2. **@agent-review** - Analyze session, suggest improvements, optionally create PR
-
-```bash
-> @code-standards check and fix any issues in today's changes
-# Wait for fixes...
-> @agent-review analyze this session
-```text
-
-### Example Workflows
-
-```bash
-# Use main agent
-opencode
-> What services are available?
-
-# Invoke Hostinger subagent
-> @hostinger list all websites
-
-# Invoke Hetzner subagent
-> @hetzner list servers in brandlight account
-
-# Invoke SEO subagent
-> @seo get top queries for example.com last 30 days
-
-# Invoke code quality
-> @code-standards run ShellCheck on all scripts
-```text
-
-## CLI Testing Mode
-
-The OpenCode TUI requires a restart to pick up configuration changes (new MCPs, agents, slash commands). Use the CLI for quick testing without restarting.
-
-### When to Use CLI Testing
-
-- **New MCP servers** added to `opencode.json`
-- **Agent configuration changes** (tools, permissions)
-- **Slash commands** added or modified
-- **Quick one-off commands** with specific agents
-- **Debugging MCP connection issues**
-
-### Basic CLI Testing
-
-```bash
-# Test with specific agent (fresh config load)
-opencode run "List your available tools" --agent SEO
-
-# Test new MCP functionality
-opencode run "Use dataforseo to get SERP for 'test query'" --agent SEO
-
-# Test with different model
-opencode run "Quick test" --agent Build+ --model anthropic/claude-sonnet-4-20250514
-
-# Capture errors for debugging
-opencode run "Test the serper MCP" --agent SEO 2>&1
-```text
-
-### Persistent Server Mode (Faster Iteration)
-
-For iterative testing, use serve mode to avoid MCP cold boot on each run:
-
-```bash
-# Terminal 1: Start headless server (keeps MCPs warm)
-opencode serve --port 4096
-
-# Terminal 2: Run tests against it (fast, reuses MCP connections)
-opencode run --attach http://localhost:4096 "Test query" --agent SEO
-opencode run --attach http://localhost:4096 "Another test" --agent SEO
-
-# After config changes: Ctrl+C in Terminal 1, restart server
-```text
-
-### Testing Scenarios
-
-| Scenario | Command |
-|----------|---------|
-| New MCP added | `opencode run "List tools from [mcp]_*" --agent [agent]` |
-| MCP auth issues | `opencode run "Call [mcp]_[tool]" --agent [agent] 2>&1` |
-| Agent permissions | `opencode run "Try to write a file" --agent Plan+` |
-| Slash command | `opencode run "/new-command arg1 arg2" --agent Build+` |
-| Quick task | `opencode run "Do X quickly" --agent Build+` |
-
-### Helper Script
-
-Use the helper script for common testing tasks:
-
-```bash
-# Test if MCP is accessible
-~/.aidevops/agents/scripts/opencode-test-helper.sh test-mcp dataforseo SEO
-
-# Test agent permissions
-~/.aidevops/agents/scripts/opencode-test-helper.sh test-agent Plan+
-
-# List tools available to agent
-~/.aidevops/agents/scripts/opencode-test-helper.sh list-tools Build+
-
-# Start persistent server
-~/.aidevops/agents/scripts/opencode-test-helper.sh serve 4096
-```text
-
-### Workflow: Adding New MCP
-
-1. Edit `~/.config/opencode/opencode.json` - add MCP config
-2. Test with CLI: `opencode run "Test [mcp]" --agent [agent] 2>&1`
-3. If errors, check stderr output and fix config
-4. If working, restart TUI to use interactively
-5. Update `generate-opencode-agents.sh` to persist changes
-
-## MCP Server Configuration
-
-### Required Environment Variables
-
-Store in `~/.config/aidevops/mcp-env.sh`:
-
-```bash
-# Hostinger
-export HOSTINGER_API_TOKEN="your-token"
-
-# Hetzner (per account)
-export HCLOUD_TOKEN_AWARDSAPP="your-token"
-export HCLOUD_TOKEN_BRANDLIGHT="your-token"
-export HCLOUD_TOKEN_MARCUSQUINN="your-token"
-export HCLOUD_TOKEN_STORAGEBOX="your-token"
-
-# Google Search Console
-# Requires service account JSON file at:
-# ~/.config/aidevops/gsc-credentials.json
-```text
-
-### Installing MCP Servers
-
-```bash
-# Hostinger MCP
-npm install -g hostinger-api-mcp
-
-# Hetzner MCP
-brew install mcp-hetzner
-
-# LocalWP MCP
-brew install mcp-local-wp
-
-# Chrome DevTools MCP (auto-installed via npx)
-```text
-
-### OpenCode MCP Environment Variable Limitation
-
-**Important**: OpenCode's MCP `environment` blocks do NOT expand shell variables like `${VAR}` - they are treated as literal strings.
-
-**Solution**: Use bash wrapper pattern to expand variables at runtime:
-
-```json
-{
-  "mcp": {
-    "ahrefs": {
-      "type": "local",
-      "command": [
-        "/bin/bash",
-        "-c",
-        "API_KEY=$AHREFS_API_KEY /opt/homebrew/bin/npx -y @ahrefs/mcp@latest"
-      ],
-      "enabled": true
-    },
-    "hetzner": {
-      "type": "local",
-      "command": [
-        "/bin/bash",
-        "-c",
-        "HCLOUD_TOKEN=$HCLOUD_TOKEN_BRANDLIGHT /opt/homebrew/bin/hcloud-mcp-server"
-      ],
-      "enabled": true
-    }
-  }
-}
-```text
-
-This pattern:
-1. Uses `/bin/bash -c` to run a shell command
-2. Sets the required env var by reading from your shell environment
-3. Then executes the MCP server with that variable set
-
-## Troubleshooting
-
-### MCPs Not Loading
-
-1. Check MCP is enabled in opencode.json
-2. Verify environment variables are set
-3. Test MCP command manually
-
-### Agent Not Found
-
-1. Check file exists in `~/.config/opencode/agent/`
-2. Verify frontmatter YAML is valid
-3. Restart OpenCode
-
-### Tools Not Available
-
-1. Check tools enabled in agent config
-2. Verify glob patterns match MCP tool names
-3. Check MCP server is responding
-
-## File Locations
-
-**OpenCode Configuration:**
-
-| Path | Purpose | Notes |
-|------|---------|-------|
-| `~/.config/opencode/opencode.json` | Main configuration | MCP servers, agents, tools |
-| `~/.config/opencode/agent/*.md` | Agent markdown files | Per-agent instructions |
-| `~/.opencode/` | Alternative location | Some installations use this |
-| `~/.opencode/agent/` | Alternative agent location | Check if ~/.config not working |
-
-**aidevops Integration:**
-
-| Path | Purpose | Notes |
-|------|---------|-------|
-| `~/.aidevops/agents/` | Deployed aidevops agents | Created by setup.sh |
-| `~/.config/aidevops/mcp-env.sh` | API credentials | 600 permissions |
-| `~/Git/aidevops/.agent/` | Source agents | Development repo |
-| `~/Git/aidevops/setup.sh` | Deployment script | Copies to ~/.aidevops/ |
-
-**Troubleshooting Path Issues:**
-
-```bash
-# Check which OpenCode config is active
-ls -la ~/.config/opencode/ ~/.opencode/ 2>/dev/null
-
-# Verify agent deployment
-ls -la ~/.aidevops/agents/ 2>/dev/null
-
-# Check if aidevops agents are referenced
-grep -l "aidevops" ~/.config/opencode/agent/*.md 2>/dev/null
-```text
-
-## Permission Model Limitations
-
-### Critical: Subagent Permission Inheritance
-
-**OpenCode subagents do NOT inherit parent agent permission restrictions.**
-
-When a parent agent uses the `task` tool to spawn a subagent:
-- The subagent runs with its OWN tool permissions
-- Parent's `write: false` is NOT enforced on the subagent
-- Parent's `bash: deny` is NOT enforced on the subagent
-
-**Implications for Read-Only Agents:**
-
-| Configuration | Is Actually Read-Only? |
-|---------------|----------------------|
-| `write: false, edit: false, task: true` | NO - subagents can write |
-| `write: false, edit: false, bash: true` | NO - bash can write files |
-| `write: false, edit: false, bash: false, task: false` | YES - truly read-only |
-
-**Example**: Plan+ with `task: true` could call a subagent that creates files, defeating its read-only purpose.
-
-### Bash Escapes All Restrictions
-
-When `bash: true`, the agent can execute ANY shell command, including:
-- `echo "content" > file.txt` - creates files
-- `sed -i 's/old/new/' file.txt` - modifies files
-- `rm file.txt` - deletes files
-
-**For true read-only behavior**: Set both `bash: false` AND `task: false`
-
-### Plan+ Read-Only Configuration
-
-Plan+ is configured as strictly read-only:
-
-```json
-"Plan+": {
-  "permission": {
-    "edit": "deny",
-    "write": "deny",
-    "bash": "deny"
-  },
-  "tools": {
-    "write": false,
-    "edit": false,
-    "bash": false,
-    "task": false,
-    "read": true,
-    "glob": true,
-    "grep": true,
-    "webfetch": true
-  }
-}
-```text
-
-Use Build+ (Tab) for any operations requiring file changes.
-
-## Continuous Improvement with @agent-review
-
-**End every session by calling `@agent-review`** to analyze the conversation and improve agents:
-
-```text
-@agent-review analyze this session and suggest improvements to the agents used
-```text
-
-The review agent will:
-1. Identify which agents were used
-2. Evaluate missing, incorrect, or excessive information
-3. Suggest specific improvements to agent files
-4. Generate ready-to-apply edits
-5. **Optionally compose a PR** to contribute improvements back to aidevops
-
-**Feedback Loop:**
-
-```text
-Session → @agent-review → Improvements → Better Agents → Better Sessions
-                ↓
-         PR to aidevops repo (optional)
-```text
-
-**Contributing back:**
-
-```text
-@agent-review create a PR for improvement #2
-```text
-
-This creates a branch, applies changes, and submits a PR to `marcusquinn/aidevops`. The agent has restricted bash permissions - only `git *` and `gh pr *` commands are allowed (with confirmation).
-
-## Code Quality Learning Loop
-
-The `@code-standards` agent doesn't just fix issues - it learns from them:
-
-```text
-Quality Issue → Fix Applied → Pattern Identified → Framework Updated → Issue Prevented
-```text
-
-After fixing violations from SonarCloud, Codacy, ShellCheck, etc.:
-
-1. **Categorize the issue** - Shell scripting, security, style, architecture
-2. **Analyze root cause** - Why didn't the framework prevent this?
-3. **Update framework** - Add guidance, examples, or checklist items
-4. **Submit PR** - Contribute the prevention back to aidevops
-
-Example: Finding 15 SC2162 violations (read without -r) leads to adding clear examples in AGENTS.md's shell best practices section.
-
-## Spawning Parallel Sessions
-
-OpenCode supports multiple session patterns for parallel work.
-
-### Quick Reference
-
-```bash
-# Non-interactive execution
-opencode run "Task description" --agent Build+ --title "Task Name"
-
-# Background execution
-opencode run "Long running task" --agent Build+ &
-
-# Persistent server (reuses MCP connections)
-opencode serve --port 4097
-opencode run --attach http://localhost:4097 "Task" --agent Build+
-
-# With worktree (recommended for parallel branches)
-~/.aidevops/agents/scripts/worktree-helper.sh add feature/parallel-task
-```
-
-See `workflows/session-manager.md` for full session lifecycle guidance including:
-- Terminal tab spawning (macOS, Linux)
-- Session handoff patterns
-- Worktree integration
-- Loop completion detection
-
-## References
-
-- [OpenCode Agents Documentation](https://opencode.ai/docs/agents)
-- [OpenCode MCP Servers](https://opencode.ai/docs/mcp-servers/)
-- [aidevops Framework](https://github.com/marcusquinn/aidevops)