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:

# 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

---

Getting Started

1. Initialize OpenCode

   cd /Users/sovereign/Desktop/CLOUDFLARE
   opencode
   /init
   

2. Check MCP Status

   /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:

# 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+