davila7__claude-code-templates/CLAUDE_BACKUP.md

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

Node.js CLI tool for managing Claude Code components (agents, commands, MCPs, hooks, settings) with a static website for browsing and installing components. The project includes Vercel API endpoints for download tracking and Discord integration.

Essential Commands

# Development
npm install                    # Install dependencies
npm test                       # Run tests
npm version patch|minor|major  # Bump version
npm publish                    # Publish to npm

# Component catalog
python scripts/generate_components_json.py  # Update docs/components.json

# API testing
cd api && npm test             # Test API endpoints before deploy
vercel --prod                  # Deploy to production

Security Guidelines

⛔ CRITICAL: NEVER Hardcode Secrets or IDs

NEVER write API keys, tokens, passwords, project IDs, org IDs, or any identifier in code. This includes Vercel project/org IDs, Supabase URLs, Discord IDs, database connection strings, and any other infrastructure identifier. ALL must go in .env.

// ❌ WRONG
const API_KEY = "AIzaSy...";

// ✅ CORRECT
const API_KEY = process.env.GOOGLE_API_KEY;

When creating scripts with API keys:

1. Use process.env (Node.js) or os.environ.get() (Python)
2. Load from .env file using dotenv
3. Add variable to .env.example with placeholder
4. Verify .env is in .gitignore

If you accidentally commit a secret:

1. Revoke the key IMMEDIATELY
2. Generate new key
3. Update .env
4. Old key is compromised forever (git history)

Component System

Component Types

Agents (600+) - AI specialists for development tasks Commands (200+) - Custom slash commands for workflows MCPs (55+) - External service integrations Settings (60+) - Claude Code configuration files Hooks (39+) - Automation triggers Templates (14+) - Complete project configurations

Installation Patterns

# Single component
npx claude-code-templates@latest --agent frontend-developer
npx claude-code-templates@latest --command setup-testing
npx claude-code-templates@latest --hook automation/simple-notifications

# Batch installation
npx claude-code-templates@latest --agent security-auditor --command security-audit --setting read-only-mode

# Interactive mode
npx claude-code-templates@latest

Component Development

Adding New Components

CRITICAL: Use the component-reviewer agent for ALL component changes

When adding or modifying components, you MUST use the component-reviewer subagent to validate the component before committing:

Use the component-reviewer agent to review [component-path]

Component Creation Workflow:

1. Create component file in cli-tool/components/{type}/{category}/{name}.md
2. Use descriptive hyphenated names (kebab-case)
3. Include clear descriptions and usage examples
4. REVIEW with component-reviewer agent (validates format, security, naming)
5. Fix any issues identified by the reviewer
6. Run python scripts/generate_components_json.py to update catalog

The component-reviewer agent checks:

• ✅ Valid YAML frontmatter and required fields
• ✅ Proper kebab-case naming conventions
• ✅ No hardcoded secrets (API keys, tokens, passwords)
• ✅ Relative paths only (no absolute paths)
• ✅ Supporting files exist (for hooks with scripts)
• ✅ Clear, specific descriptions
• ✅ Correct category placement
• ✅ Security best practices

Example Usage:

# After creating a new agent
Use the component-reviewer agent to review cli-tool/components/agents/development-team/react-expert.md

# Before committing hook changes
Use the component-reviewer agent to review cli-tool/components/hooks/git/prevent-force-push.json

# For PR reviews with multiple components
Use the component-reviewer agent to review all modified components in cli-tool/components/

The agent will provide prioritized feedback:

• ❌ Critical Issues: Must fix before merge (security, missing fields)
• ⚠️ Warnings: Should fix (clarity, best practices)
• 📋 Suggestions: Nice to have improvements

Statuslines with Python Scripts

Statuslines can reference Python scripts that are auto-downloaded to .claude/scripts/:

// In src/index.js:installIndividualSetting()
if (settingName.includes('statusline/')) {
  const pythonFileName = settingName.split('/')[1] + '.py';
  const pythonUrl = githubUrl.replace('.json', '.py');
  additionalFiles['.claude/scripts/' + pythonFileName] = {
    content: pythonContent,
    executable: true
  };
}

Publishing Workflow

# 1. Update component catalog
python scripts/generate_components_json.py

# 2. Run tests
npm test

# 3. Check current npm version and align local version
npm view claude-code-templates version  # check latest on registry
# Edit package.json version to be one patch above the registry version

# 4. Commit version bump and push
git add package.json && git commit -m "chore: Bump version to X.Y.Z"
git push origin main

# 5. Publish to npm (requires granular access token with "Bypass 2FA" enabled)
npm config set //registry.npmjs.org/:_authToken=YOUR_GRANULAR_TOKEN
npm publish
npm config delete //registry.npmjs.org/:_authToken  # always clean up after

# 6. Tag the release
git tag vX.Y.Z && git push origin vX.Y.Z

# 7. Deploy website
vercel --prod

npm Publishing Notes:

• Classic npm tokens were revoked Dec 2025. Use granular access tokens from npmjs.com/settings/~/tokens
• The token must have Read and Write permissions for claude-code-templates and "Bypass 2FA" enabled
• Always remove the token from npm config after publishing (npm config delete)
• The local package.json version may drift from npm if published from CI — always check npm view claude-code-templates version first
• Never hardcode or commit tokens

API Architecture

Critical Endpoints

API endpoints live as Astro API routes in dashboard/src/pages/api/:

/api/track-download-supabase (CRITICAL)

• Tracks component downloads for analytics
• Used by CLI on every installation
• Database: Supabase (component_downloads table)

/api/discord/interactions

• Discord bot slash commands
• Features: /search, /info, /install, /popular

/api/claude-code-check

• Monitors Claude Code releases
• Vercel Cron: every 30 minutes
• Database: Neon (claude_code_versions, claude_code_changes, discord_notifications_log, monitoring_metadata tables)

Shared API Libraries

• dashboard/src/lib/api/cors.ts — CORS headers, corsResponse(), jsonResponse()
• dashboard/src/lib/api/neon.ts — Neon client factory
• dashboard/src/lib/api/auth.ts — Clerk JWT verification
• dashboard/src/lib/api/changelog-parser.ts — Claude Code changelog parser

Emergency Rollback

vercel ls                              # List deployments
vercel promote <previous-deployment>   # Rollback

Cloudflare Workers

The cloudflare-workers/ directory contains Cloudflare Worker projects that run independently from Vercel.

docs-monitor

Monitors https://code.claude.com/docs for changes every hour and sends Telegram notifications.

cd cloudflare-workers/docs-monitor
npm run dev          # Local dev
npx wrangler deploy  # Deploy

pulse (Weekly KPI Report)

Collects metrics from GitHub, Discord, Supabase, Vercel, and Google Analytics every Sunday at 14:00 UTC and sends a consolidated report via Telegram.

Architecture: Single index.js file (no npm dependencies at runtime). All source collectors, formatter, and Telegram sender in one file.

Cron: 0 14 * * 0 (Sundays 14:00 UTC / 11:00 AM Chile)

cd cloudflare-workers/pulse
npm run dev          # Local dev
npx wrangler deploy  # Deploy

# Manual trigger
curl -X POST https://pulse-weekly-report.SUBDOMAIN.workers.dev/trigger \
  -H "Authorization: Bearer $TRIGGER_SECRET"

# Test single source
curl -X POST "https://pulse-weekly-report.SUBDOMAIN.workers.dev/trigger?source=github" \
  -H "Authorization: Bearer $TRIGGER_SECRET"

# Dry run (no Telegram)
curl -X POST "https://pulse-weekly-report.SUBDOMAIN.workers.dev/trigger?send=false" \
  -H "Authorization: Bearer $TRIGGER_SECRET"

Secrets (Cloudflare):

TELEGRAM_BOT_TOKEN          # Shared with docs-monitor
TELEGRAM_CHAT_ID            # Shared with docs-monitor
GITHUB_TOKEN                # GitHub PAT (public_repo scope)
SUPABASE_URL                # Supabase project URL
SUPABASE_SERVICE_ROLE_KEY   # Supabase service role key
DISCORD_BOT_TOKEN           # Discord bot token
DISCORD_GUILD_ID            # Discord server ID
VERCEL_TOKEN                # Vercel personal access token (optional)
VERCEL_PROJECT_ID           # Vercel project ID (optional)
TRIGGER_SECRET              # For manual /trigger endpoint
GA_PROPERTY_ID              # GA4 property ID (optional)
GA_SERVICE_ACCOUNT_JSON     # Base64 service account (optional)

Graceful degradation: Each source catches its own errors. Missing secrets or API failures show ⚠️ Unavailable instead of crashing the report.

Dashboard (www.aitmpl.com)

Astro + React + Tailwind dashboard serving both www.aitmpl.com and app.aitmpl.com. Clerk auth for user collections. Source lives in dashboard/. All API endpoints are Astro API routes in the same project.

Architecture

• Framework: Astro 5 with React islands, Tailwind v4, output: 'server'
• Auth: Clerk (window.Clerk global, no ClerkProvider per island)
• Data: components.json and trending-data.json served from dashboard/public/ (same-origin)
• APIs: All endpoints in dashboard/src/pages/api/ (Astro API routes, no separate serverless project)

Featured Pages (/featured/[slug])

Featured partner integrations shown on the dashboard homepage. Two files to edit:

dashboard/src/lib/constants.ts — FEATURED_ITEMS array. Each entry has:

• name, description, logo, url (/featured/slug), tag, tagColor, category
• ctaLabel, ctaUrl, websiteUrl
• installCommand — shown in the sidebar Quick Install box
• metadata — key/value pairs shown in the Details sidebar (e.g. Components: '8')
• links — sidebar links list

dashboard/src/pages/featured/[slug].astro — Content for each slug rendered via {slug === 'brightdata' && (...)} blocks. Each block contains the full HTML content for that partner page.

When adding a skill to a featured page:

1. Add a new card <div class="flex gap-3 ..."> inside the Skills Layer section of the relevant {slug === '...'} block
2. Update installCommand in constants.ts to include the new skill
3. Increment metadata.Components count in constants.ts

Current featured slugs: brightdata, neon-instagres, claudekit, braingrid

Vercel Project Setup

Single Vercel project serves all domains:

Project	Domains	Root Directory
aitmpl-dashboard	www.aitmpl.com, aitmpl.com (redirect), app.aitmpl.com	dashboard

The legacy root project (aitmpl) is archived — only its .vercel.app subdomain remains.

Deployment

ALWAYS use the deployer agent (.claude/agents/deployer.md) for all deployments. It runs pre-deploy checks (auth, git status, API tests) and handles the full pipeline safely. Never deploy manually.

npm run deploy             # Deploy www + app.aitmpl.com
npm run deploy:dashboard   # Same as above

CI/CD: Pushes to main auto-deploy via GitHub Actions (.github/workflows/deploy.yml):

• Changes in dashboard/** trigger deploy

Required GitHub Secrets (Settings > Secrets > Actions):

• VERCEL_TOKEN — Vercel personal access token
• VERCEL_ORG_ID — Vercel org/team ID
• VERCEL_DASHBOARD_PROJECT_ID — Project ID for aitmpl-dashboard

Environment Variables (Vercel)

# Clerk
PUBLIC_CLERK_PUBLISHABLE_KEY=xxx
CLERK_SECRET_KEY=xxx

# Data
PUBLIC_COMPONENTS_JSON_URL=/components.json

# GitHub OAuth
PUBLIC_GITHUB_CLIENT_ID=xxx
GITHUB_CLIENT_SECRET=xxx

# Supabase (download tracking)
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=xxx

# Neon Database
NEON_DATABASE_URL=postgresql://user:pass@host/db?sslmode=require

# Discord
DISCORD_APP_ID=xxx
DISCORD_BOT_TOKEN=xxx
DISCORD_PUBLIC_KEY=xxx
DISCORD_WEBHOOK_URL_CHANGELOG=https://discord.com/api/webhooks/xxx

Known Issues & Solutions

Node v24 breaks fs.writeFileSync on Vercel

• Node v24 has a bug with writeFileSync in Vercel's build environment
• Solution: Dashboard project is pinned to Node 22.x (set via Vercel API/dashboard)

Vercel CLI ignores local .vercel/project.json

• The CLI often resolves to the parent directory's project. Use VERCEL_ORG_ID and VERCEL_PROJECT_ID env vars to force the correct project.

Local Development

cd dashboard
npm install
npx astro dev --port 4321   # Dashboard + APIs at http://localhost:4321

Data Files

Component Catalog

• docs/components.json — Generated catalog (source of truth)
• dashboard/public/components.json — Copy served by the dashboard
• dashboard/public/trending-data.json — Trending/download stats

Data Flow

1. scripts/generate_components_json.py scans cli-tool/components/
2. Generates docs/components.json with embedded content
3. Copy to dashboard/public/components.json for the dashboard to serve
4. Dashboard loads JSON and renders component cards
5. Download tracking via /api/track-download-supabase

Legacy Static Site (docs/)

The docs/ directory contains the old static HTML site (no longer deployed to www). Blog articles in docs/blog/ are still referenced externally.

Blog Article Creation

Use the CLI skill to create blog articles:

/create-blog-article @cli-tool/components/{type}/{category}/{name}.json

This automatically:

1. Generates AI cover image
2. Creates HTML with SEO optimization
3. Updates docs/blog/blog-articles.json

Code Standards

Path Handling

• Use relative paths: .claude/scripts/, .claude/hooks/
• Never hardcode absolute paths or home directories
• Use path.join() for cross-platform compatibility

Naming Conventions

• Files: kebab-case.js, PascalCase.js (for classes)
• Functions/Variables: camelCase
• Constants: UPPER_SNAKE_CASE
• Components: hyphenated-names

Error Handling

• Use try/catch for async operations
• Provide helpful error messages
• Log errors with context
• Implement fallback mechanisms

Testing

npm test                 # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report

Aim for 70%+ test coverage. Test critical paths and error handling.

Common Issues

API endpoint returns 404 after deploy

• API routes must be in dashboard/src/pages/api/ as Astro API routes
• Export named HTTP methods: export const POST: APIRoute, export const GET: APIRoute

Download tracking not working

• Check Vercel logs: vercel logs aitmpl.com --follow
• Verify environment variables in Vercel dashboard
• Test endpoint manually with curl

Components not updating on website

• Run python scripts/generate_components_json.py
• Copy docs/components.json to dashboard/public/components.json
• Deploy and clear browser cache

Important Notes

• Component catalog: Always regenerate after adding/modifying components
• API tests: Required before production deploy (breaks download tracking)
• Secrets: Never commit API keys (use environment variables)
• Paths: Use relative paths for all project files
• Backwards compatibility: Don't break existing component installations