Skip to content

Latest commit

 

History

History
324 lines (242 loc) · 10.4 KB

AGENTS.md

File metadata and controls

324 lines (242 loc) · 10.4 KB

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Project Overview

This is an Agent Skill for managing Upsun Platform-as-a-Service projects via the Upsun CLI. The skill enables AI coding agents to help users with 130+ Upsun CLI commands covering deployments, environment management, backups, databases, resources, and security.

Skill Type: Documentation-based skill using progressive disclosure Target: Upsun CLI v5.6.0+ Distribution: Public skill for AI coding agents

Architecture

Progressive Disclosure Model

The skill uses a three-tier progressive disclosure architecture to minimize context usage:

  1. SKILL.md (~2,000 words) - Entry point with workflow navigation and trigger phrases
  2. references/ (11 files, ~2,000 words each) - Detailed command documentation loaded on-demand
  3. scripts/ (7 executable helpers) - Zero-context automation (only output loaded)

Key principle: Agents start at SKILL.md, navigate to specific reference files as needed. Most interactions use <10% of total documentation.

File Structure

.
├── .opencode/                  # OpenCode configuration
│   └── skills/upsun/           # Skill directory
│       ├── SKILL.md            # Main skill entry (YAML frontmatter + navigation)
│       ├── references/         # On-demand documentation (progressive disclosure)
│       │   ├── COMMAND-INDEX.md    # Alphabetical 130+ command reference
│       │   ├── environments.md     # Environment lifecycle operations
│       │   ├── deployments.md      # Deployment workflows and strategies
│       │   ├── backups.md          # Backup/restore procedures
│       │   ├── services-databases.md # Database operations (PostgreSQL, MongoDB, Redis)
│       │   ├── resources-scaling.md  # Resource allocation and autoscaling
│       │   ├── access-security.md    # Users, teams, SSH keys, SSL certs
│       │   ├── integration-variables.md # Domains, routes, env vars
│       │   ├── development-tools.md  # SSH, tunnels, logs, debugging
│       │   ├── projects-organizations.md # Project/org management
│       │   └── troubleshooting.md    # Common issues and solutions
│       └── scripts/            # Helper automation (executable, output-only)
│           ├── check-auth.sh       # Verify Upsun authentication
│           ├── health-check.sh     # 8-step environment health check
│           ├── pre-deploy-check.sh # Pre-deployment validation
│           ├── backup-with-verification.sh # Create and verify backups
│           ├── safe-restore.sh     # Safe restore with rollback
│           ├── environment-status.sh # JSON status output for automation
│           └── resource-audit.sh   # Multi-environment resource analysis
├── opencode.json               # OpenCode configuration with permissions
├── README.md                   # Installation and usage guide
├── AGENTS.md                   # Development guide (this file)
├── CHANGELOG.md                # Version history
└── LICENSE                     # Apache 2.0 license

Working with This Skill

Skill Structure

The skill follows the OpenCode skill format:

Primary location: .opencode/skills/upsun/SKILL.md

Key files:

  • .opencode/skills/upsun/SKILL.md - Main skill entry point
  • opencode.json - Permission configuration
  • All skill content under .opencode/skills/upsun/

Modifying SKILL.md

Located at .opencode/skills/upsun/SKILL.md:

YAML Frontmatter (required fields):

  • name: upsun - Skill identifier (lowercase, hyphens only, 1-64 chars)
  • description - Semantic triggers for skill activation (1-1024 chars, critical for discoverability)

Optional frontmatter fields:

  • license - License identifier (e.g., Apache-2.0)
  • compatibility - Agent compatibility (e.g., opencode)
  • metadata - Key-value pairs for additional info

Name validation rules:

  • 1-64 characters
  • Lowercase alphanumeric with single hyphen separators
  • Cannot start or end with -
  • Cannot contain consecutive --
  • Must match the directory name containing SKILL.md

Trigger Phrases: Add deployment/management keywords to description to improve activation accuracy.

Adding New Reference Documentation

Reference files follow this pattern:

# Title

## Overview
Brief category description

## Common Workflows
### Workflow 1
Use case, commands, examples

## Command Reference
### `command:name`
Description, syntax, options, examples

## Best Practices
## Related Commands
## Troubleshooting

Cross-references: Use relative markdown links [text](file.md#section) between references.

Creating Helper Scripts

All scripts in .opencode/skills/upsun/scripts/ must:

  • Include shebang: #!/usr/bin/env bash
  • Use set -euo pipefail for error handling
  • Check authentication via upsun auth:info --no-interaction
  • Accept PROJECT_ID and ENVIRONMENT_NAME as positional args
  • Return meaningful exit codes (0=success, 1=warning, 2=critical)
  • Use --no-interaction flag on all Upsun CLI calls
  • Include comprehensive usage documentation in comments
  • Be executable: chmod +x scripts/script-name.sh

Output: Scripts are executed, not read. Only output enters the agent's context.

Testing Helper Scripts

# Navigate to skill directory
cd .opencode/skills/upsun

# Test authentication check
./scripts/check-auth.sh

# Test health check (requires Upsun auth + project)
./scripts/health-check.sh PROJECT_ID ENVIRONMENT_NAME

# Test pre-deployment validation
./scripts/pre-deploy-check.sh PROJECT_ID ENVIRONMENT_NAME

# Test backup creation
./scripts/backup-with-verification.sh PROJECT_ID ENVIRONMENT_NAME --live

Upsun CLI Patterns

Common Command Structure

upsun COMMAND:SUBCOMMAND -p PROJECT_ID -e ENVIRONMENT_NAME [OPTIONS]

Global flags:

  • -p, --project - Project ID (13 chars, alphanumeric)
  • -e, --environment - Environment name
  • --no-interaction - Non-interactive mode (required for scripts)
  • --pipe - Output IDs only (for piping)
  • -y, --yes - Auto-confirm prompts

Namespace Organization

Commands are organized in 30 namespaces:

  • Core: activity, environment, backup, project
  • Data: db, service (mongo, redis, valkey)
  • Config: variable, integration, domain, route
  • Access: user, team, organization, auth, ssh-key, certificate
  • Resources: resources, autoscaling, metrics
  • Dev Tools: tunnel, mount, operation, repo

Authentication Pattern

Every script operation should check auth first:

if ! upsun auth:info --no-interaction >/dev/null 2>&1; then
    echo "Not authenticated. Run: upsun auth:browser-login"
    exit 1
fi

Permission Configuration

OpenCode

Configure permissions in opencode.json:

{
  "permission": {
    "skill": {
      "upsun": "allow"
    },
    "bash": {
      "upsun *": "allow"
    }
  }
}

Permission levels:

  • allow - Skill/command loads immediately
  • deny - Skill hidden from agent, access rejected
  • ask - User prompted for approval before loading

Granular bash permissions:

{
  "permission": {
    "bash": {
      "upsun auth:*": "allow",
      "upsun environment:*": "allow",
      "upsun activity:*": "allow",
      "upsun backup:*": "allow",
      "upsun project:*": "allow"
    }
  }
}

Key Design Decisions

Why Progressive Disclosure?

Problem: 130+ commands x 100 words = 13,000+ words always loaded = context bloat Solution: SKILL.md (2,000 words) + on-demand references = 70% context reduction

Why Bash Scripts vs Documentation?

Bash scripts for complex multi-step operations (backup verification, health checks):

  • Executed, not read (zero context usage for code)
  • Only output enters context
  • Reusable across sessions
  • Testable independently

Markdown docs for command reference and guidance:

  • Easier to read/navigate
  • Better for explanations
  • Searchable
  • Standard format

Why YAML Frontmatter?

Agent skill systems require YAML frontmatter with:

  • name - Unique skill identifier
  • description - Semantic triggers for activation

The description field is critical: it determines when agents activate this skill based on user queries.

Common Modifications

Adding a New Upsun Command

  1. Add to .opencode/skills/upsun/references/COMMAND-INDEX.md (alphabetical)
  2. Add to appropriate category reference (e.g., environments.md)
  3. Update .opencode/skills/upsun/SKILL.md if it's a commonly-used command
  4. Add examples to relevant workflow scripts
  5. Update CHANGELOG.md with the addition

Creating a New Helper Script

  1. Create in .opencode/skills/upsun/scripts/ with descriptive name
  2. Follow script template (shebang, error handling, auth check)
  3. Add usage documentation in header comments
  4. Make executable: chmod +x .opencode/skills/upsun/scripts/new-script.sh
  5. Reference from SKILL.md and relevant reference files
  6. Test with real Upsun project
  7. Document in CHANGELOG.md

Updating for New Upsun CLI Version

When Upsun CLI updates:

  1. Run upsun list to get new commands
  2. Check upsun COMMAND --help for new options
  3. Update .opencode/skills/upsun/references/COMMAND-INDEX.md with new commands
  4. Add new commands to category references
  5. Update CLI version in .opencode/skills/upsun/SKILL.md overview
  6. Test all helper scripts with new version
  7. Document changes in CHANGELOG.md
  8. Create GitHub release

Validation

Before Committing

# Verify opencode.json is valid JSON
cat opencode.json | jq '.'

# Verify SKILL.md YAML frontmatter is valid
head -n 10 .opencode/skills/upsun/SKILL.md

# Verify all scripts are executable
ls -l .opencode/skills/upsun/scripts/*.sh

# Check for broken markdown links
grep -r "](references/" .opencode/skills/upsun/ | grep -v "\.md"

# Verify scripts have proper shebangs
head -n 1 .opencode/skills/upsun/scripts/*.sh | grep "#!/usr/bin/env bash"

# Validate skill structure
test -f .opencode/skills/upsun/SKILL.md && echo "Skill file exists"
test -f opencode.json && echo "OpenCode config exists"

Testing Skill Activation

The skill activates when users mention:

  • "deploy to Upsun"
  • "create Upsun environment"
  • "backup Upsun"
  • "Upsun CLI commands"
  • Environment management keywords
  • Deployment workflows

Test by using these phrases in AI coding agent conversations.