AI Agents

SonicJS uses AI-powered Claude agents to automate development workflows, releases, SEO optimization, and marketing tasks. These agents are available when using Claude Code with the SonicJS repository.

Overview

The SonicJS project includes 13 specialized AI agents that help maintainers and contributors work more efficiently. Each agent is designed for specific tasks and follows established best practices.

Agent Categories

Development Agents

Full Stack Developer Agent

Command: /fullstack-dev or /sonicjs-fullstack-dev

The primary development agent for implementing features in SonicJS. This agent enforces a structured workflow with mandatory planning, testing, and documentation.

Usage:

/fullstack-dev plan [feature]     # Create implementation plan
/fullstack-dev implement          # Start implementing approved plan
/fullstack-dev test unit [feature]  # Write unit tests
/fullstack-dev test e2e [feature]   # Write E2E tests
/fullstack-dev review             # Run all tests and report status

PR Maker Agent

Command: /sonicjs-pr-maker

A specialized agent that automates the entire PR lifecycle: creating well-formatted pull requests, monitoring CI/CD pipelines, analyzing failures, and automatically fixing issues including E2E test failures.

Usage:

/sonicjs-pr-maker                  # Create PR and monitor until CI passes
/sonicjs-pr-maker create           # Create PR only (no monitoring)
/sonicjs-pr-maker monitor 123      # Monitor existing PR #123
/sonicjs-pr-maker fix 123          # Analyze and fix failing PR #123

Retry Strategy: The agent attempts fixes up to 3 times. If the same test fails after 3 attempts, it reports the issue and asks for guidance.

PR Fixer Agent

Command: /sonicjs-pr-fixer

Handles problematic pull requests including fork PRs that need cherry-picking, Dependabot PRs that need E2E tests enabled, and any PR needing fixes before merge.

Usage:

/sonicjs-pr-fixer fork 532       # Cherry-pick fork PR with attribution
/sonicjs-pr-fixer dependabot     # List and enable e2e on Dependabot PRs
/sonicjs-pr-fixer dependabot all # Enable e2e on all Dependabot PRs
/sonicjs-pr-fixer fix 532        # Checkout and fix any PR

PR Maker Agent

Command: /sonicjs-pr-maker

Creates Pull Requests, monitors CI/CD pipelines, analyzes failures, and automatically fixes issues including unit test, build, and E2E test failures. This agent automates the entire PR lifecycle from creation to passing CI.

Usage:

/sonicjs-pr-maker                # Create PR and monitor until CI passes
/sonicjs-pr-maker create         # Create PR only (no monitoring)
/sonicjs-pr-maker monitor 558    # Monitor existing PR checks
/sonicjs-pr-maker fix 558        # Analyze and fix failing PR

Workflow Example:

1. Agent analyzes your branch changes
2. Creates PR with conventional commit title (feat:, fix:, etc.)
3. Monitors CI checks every 30 seconds
4. If checks fail, downloads logs and artifacts
5. Identifies failure type and applies fix
6. Pushes fix and resumes monitoring
7. Reports success when all checks pass

Release & DevOps Agents

Release Engineer Agent

Command: /release-engineer or /sonicjs-release-engineer

Manages npm package releases and dependency updates for SonicJS. Handles version bumping, npm publishing, GitHub releases, and changelog updates.

Usage:

/release-engineer update   # Update npm dependencies
/release-engineer patch    # Publish patch release (x.x.X)
/release-engineer minor    # Publish minor release (x.X.0)
/release-engineer major    # Publish major release (X.0.0)
/release-engineer beta     # Publish beta pre-release
/release-engineer status   # Check current version and npm status

Release Announcement Agent

Command: /release-announcement or /sonicjs-release-announcement

Creates compelling release announcements for Discord, Twitter/X, and the website. Generates platform-specific content with proper formatting.

Usage:

/release-announcement generate  # Generate content for current version
/release-announcement post      # Post to all platforms
/release-announcement dry-run   # Preview without posting
/release-announcement discord   # Post to Discord only
/release-announcement twitter   # Post to Twitter only

Dependabot Manager Agent

Command: /dependabot-manager

Manages automated dependency update PRs from Dependabot. Enables E2E tests on Dependabot PRs by pushing empty commits (changes the actor from bot to human).

Usage:

/dependabot-manager         # List open Dependabot PRs
/dependabot-manager all     # Process all Dependabot PRs
/dependabot-manager 123,124 # Process specific PRs

SEO Agents

SEO Expert Agent

Command: /seo or /sonicjs-seo

The main SEO agent for SonicJS. Handles keyword research, blog content generation, documentation SEO optimization, and technical SEO audits.

Usage:

/seo audit         # Audit current SEO status
/seo keywords      # Generate keyword research report
/seo blog [topic]  # Generate a blog post
/seo meta [page]   # Generate optimized meta tags
/seo sitemap       # Create/update sitemap.xml
/seo schema [type] # Generate JSON-LD structured data

SEO Blog Agent

Command: /seo-blog or /sonicjs-seo-blog

Generates SEO-optimized blog posts (1500-2500 words) with proper structure, TL;DR boxes for featured snippets, and metadata.

Output Location: www/src/app/blog/[slug]/page.mdx

Content Types:

• Tutorials and step-by-step guides
• Comparison posts (SonicJS vs competitors)
• Technical deep dives
• Use case articles
• Migration guides

SEO Keywords Agent

Command: /seo-keywords or /sonicjs-seo-keywords

Performs keyword research to identify ranking opportunities. Analyzes competitors (Strapi, Sanity, Contentful, Payload CMS, Directus) and finds content gaps.

Output: Keyword research report with:

• High priority keywords with search volume
• Quick win opportunities
• Content gaps vs competitors
• Recommended content calendar

SEO Audit Agent

Command: /seo-audit or /sonicjs-seo-audit

Performs comprehensive SEO audits of the SonicJS documentation website.

Audit Categories:

• Technical SEO (sitemap, robots.txt, meta tags, canonicals)
• On-Page SEO (titles, descriptions, OpenGraph)
• Content SEO (thin content, keyword opportunities)
• Structured Data (JSON-LD, Organization, Article schema)

SEO Sitemap Agent

Command: /seo-sitemap or /sonicjs-seo-sitemap

Creates or updates the sitemap.xml for the documentation website. Can generate dynamic sitemaps via Next.js or static XML files.

Discord Sync Agent

Command: /seo-discord-sync or /sonicjs-seo-discord-sync

Transforms valuable Discord discussions into searchable web content. Creates FAQs, troubleshooting guides, and community showcases from real Discord conversations.

Output Locations:

• www/src/app/faq/page.mdx - FAQ from Discord Q&A
• www/src/app/showcase/page.mdx - Community projects
• www/src/app/troubleshooting/page.mdx - Common issues and solutions

Marketing Agents

Social Media Agent

Command: /social-post or /sonicjs-social-post

Posts announcements to Discord and Twitter/X using configured webhooks and API credentials.

Usage:

# Post to Discord
node scripts/social/post-discord.js "Your message here"

# Post to Twitter
node scripts/social/post-twitter.js "Your tweet here"

# Post to both platforms
node scripts/social/post-both.js "Your announcement"

Auto-Hashtags: #SonicJS #CloudflareCMS #OpenSource #Webdev

Blog Image Agent

Command: /blog-image or /sonicjs-blog-image

Generates professional blog post images using OpenAI's DALL-E API with SonicJS brand guidelines.

Output Location: www/public/images/blog/[slug]/

Using Agents

Prerequisites

1. Claude Code - Install from claude.ai/code
2. SonicJS Repository - Clone the repository locally
3. Environment Variables - Set up required API keys for certain agents

Invoking Agents

Open the SonicJS repository in Claude Code and use slash commands:

# Start a full stack development session
/fullstack-dev plan add-dark-mode-toggle

# Publish a new release
/release-engineer minor

# Generate an SEO blog post
/seo-blog Building a REST API with SonicJS

# Enable E2E tests on Dependabot PRs
/dependabot-manager all

Environment Variables

Some agents require API keys. Set these in your environment or .env file:

# Discord (for announcements)
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# Twitter/X (for announcements)
TWITTER_API_KEY=your_api_key
TWITTER_API_SECRET=your_api_secret
TWITTER_ACCESS_TOKEN=your_access_token
TWITTER_ACCESS_SECRET=your_access_secret

# OpenAI (for image generation)
OPENAI_API_KEY=your_openai_key

Agent Configuration

Agents are defined as Markdown files in .claude/commands/:

.claude/
├── commands/
│   ├── sonicjs-fullstack-dev.md
│   ├── sonicjs-release-engineer.md
│   ├── sonicjs-seo.md
│   └── ... (12 agent files)
├── instructions.md
└── settings.json

Questions?

If you have questions about using the AI agents:

1. Check the agent file - Each .claude/commands/*.md file has detailed instructions
2. Ask in Discord - Our community can help
3. Open an issue - For bugs or feature requests