vm-cloudflare/AGENTS.md

# OpenCode Agents for CLOUDFLARE Project

This document defines custom agents and rules for working with the Cloudflare infrastructure project.

## Available Agents

### cloudflare-ops
**Purpose:** Manages Cloudflare infrastructure via Terraform and GitOps

**Tools Available:**
- filesystem (explore project structure)
- git (track and review changes)
- github (search implementations, manage PRs)
- gh_grep (find code examples on GitHub)

**When to Use:**
- Implementing Terraform changes
- Reviewing GitOps pipelines
- Creating infrastructure documentation
- Troubleshooting Cloudflare configurations

**Example Usage:**
```
/agent cloudflare-ops
I need to add a new DNS record for api.example.com and update the WAF rules. Can you use gh_grep to find similar implementations first?
```

---

### security-audit
**Purpose:** Performs security analysis and compliance checks

**Tools Available:**
- filesystem (read security policies)
- git (review audit logs)
- github (search security implementations)
- gh_grep (find security best practices)

**When to Use:**
- Auditing security configurations
- Reviewing compliance requirements
- Analyzing WAF rules
- Checking access controls

**Example Usage:**
```
/agent security-audit
Review the WAF rules in terraform/waf.tf and check if we're compliant with PCI-DSS requirements.
```

---

### data-engineer
**Purpose:** Works with databases and data processing

**Tools Available:**
- filesystem (examine data schemas)
- git (track data model changes)
- postgres (query production data)
- sqlite (work with local data)

**When to Use:**
- Working with database schemas
- Processing analytics data
- Troubleshooting data pipeline issues
- Running data queries

---

## Global Rules

These rules apply to all interactions with OpenCode in this project:

1. **Always Use Version Control**
   - When making infrastructure changes, use git to stage and review modifications
   - Commit meaningful changes with descriptive messages

2. **Search Before Implementing**
   - Before creating new Terraform resources, use gh_grep to find similar implementations
   - This helps maintain consistency and avoid reinventing the wheel

3. **Understand the Project Structure**
   - Use filesystem operations to explore the project before making changes
   - Familiar with key directories:
     - `terraform/` - Infrastructure code
     - `gitops/` - CI/CD and automation
     - `observatory/` - Monitoring and observability
     - `scripts/` - Utility scripts
     - `playbooks/` - Security and incident response playbooks

4. **Compliance-Driven Development**
   - When implementing security features, reference compliance frameworks (PCI-DSS, GDPR, etc.)
   - Document compliance mappings in resource comments
   - Use context7 to search compliance documentation when needed

5. **Validate Before Applying**
   - Always run `terraform validate` before planning
   - Always run `terraform plan` before applying changes
   - Review the plan summary for risk assessment

---

## MCP Tool Quick Reference

### filesystem
Search and read files in the project:
```
use filesystem to explore the directory structure of terraform/
```

### git
Review git history and diffs:
```
use git to show recent commits in the gitops/ directory
```

### github
Search implementations and manage repositories:
```
use github to search for similar Terraform patterns
```

### gh_grep
Find code examples on GitHub:
```
use gh_grep to find examples of Cloudflare Terraform patterns
```

### context7
Search documentation (if API key configured):
```
use context7 to find information about PCI-DSS requirements
```

---

## Environment Variables

When using MCPs that require authentication, ensure these env vars are set:

```bash
# GitHub integration
export GITHUB_TOKEN="your-github-token"

# Context7 (optional knowledge search)
export CONTEXT7_API_KEY="your-context7-key"

# Database connections (if using data-engineer agent)
export DATABASE_URL="postgresql://..."

# AWS credentials (if using AWS MCP)
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"

# Slack (if using notifications)
export SLACK_BOT_TOKEN="..."

# Linear (if using issue tracking)
export LINEAR_API_KEY="..."
```

### Multiple Accounts Configuration 🔐

For managing multiple GitHub, GitLab, or Cloudflare accounts, see: [MULTI_ACCOUNT_AUTH.md](MULTI_ACCOUNT_AUTH.md)

---

## Getting Started

1. **Initialize OpenCode**
   ```bash
   cd /Users/sovereign/Desktop/CLOUDFLARE
   opencode
   /init
   ```

2. **Check MCP Status**
   ```bash
   /mcp list
   ```

3. **Start an Agent Conversation**
   ```
   /agent cloudflare-ops
   I need to add HTTPS enforcement to all zones. Can you create a plan?
   ```

4. **Use Plan Mode for Complex Tasks**
   ```
   <TAB>  # Switch to plan mode
   Add a new tunnel configuration for production
   ```

5. **Review and Apply Changes**
   ```
   <TAB>  # Switch back to build mode
   Looks good, go ahead and implement it
   ```

---

## Troubleshooting

**MCP Server Not Starting:**
```bash
# Check which MCPs are enabled
opencode mcp list

# Try disabling problematic MCPs temporarily
# Edit opencode.jsonc and set "enabled": false for that MCP
```

**Context Limit Exceeded:**
- Some MCPs (like GitHub) add many tokens
- Disable less frequently used MCPs in the `"tools"` section
- Use per-agent tools configuration instead of global enablement

**Missing Environment Variables:**
- MCPs won't fail silently - they'll error if env vars are missing
- Check `.env` or export variables before running opencode

---

## Contributing to this File

When you learn new patterns or create reusable workflows, add them to this AGENTS.md file so other team members can benefit. 

Examples of things to document:
- New agent use cases
- Useful MCP combinations
- Common tasks and their solutions
- Links to relevant documentation

---

**Last Updated:** December 8, 2025
**OpenCode Version:** 1.0+