claude-cli-advanced-starter-pack 1.1.0 → 1.8.0

package/templates/scripts/validate-deployment.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+/**
+ * Validate Deployment Environment
+ *
+ * Pre-deployment validation for Railway, Cloudflare, Vercel, and other platforms.
+ * Checks environment variables, build artifacts, and configuration.
+ *
+ * Usage:
+ *   node validate-deployment.js --platform railway
+ *   node validate-deployment.js --platform cloudflare --project-name my-project
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+
+const PLATFORMS = {
+  railway: {
+    requiredEnv: ['RAILWAY_API_TOKEN'],
+    optionalEnv: ['RAILWAY_PROJECT_ID', 'RAILWAY_ENVIRONMENT_ID', 'RAILWAY_SERVICE_ID'],
+    buildArtifacts: ['package.json', 'Dockerfile', 'requirements.txt', 'go.mod'],
+    configFiles: ['railway.json', 'railway.toml'],
+  },
+  cloudflare: {
+    requiredEnv: ['CLOUDFLARE_API_TOKEN'],
+    optionalEnv: ['CLOUDFLARE_ACCOUNT_ID'],
+    buildArtifacts: ['dist/', 'build/', 'public/', '.next/'],
+    configFiles: ['wrangler.toml', 'wrangler.json'],
+  },
+  vercel: {
+    requiredEnv: ['VERCEL_TOKEN'],
+    optionalEnv: ['VERCEL_PROJECT_ID', 'VERCEL_ORG_ID'],
+    buildArtifacts: ['dist/', 'build/', '.next/', '.vercel/'],
+    configFiles: ['vercel.json'],
+  },
+  netlify: {
+    requiredEnv: ['NETLIFY_AUTH_TOKEN'],
+    optionalEnv: ['NETLIFY_SITE_ID'],
+    buildArtifacts: ['dist/', 'build/', 'public/'],
+    configFiles: ['netlify.toml'],
+  },
+};
+
+class DeploymentValidator {
+  constructor(platform, options = {}) {
+    this.platform = platform;
+    this.options = options;
+    this.config = PLATFORMS[platform];
+    this.errors = [];
+    this.warnings = [];
+    this.checks = [];
+  }
+
+  async validate() {
+    console.log(`\n🔍 Validating ${this.platform} deployment...\n`);
+
+    await this.checkEnvironmentVariables();
+    await this.checkBuildArtifacts();
+    await this.checkConfigFiles();
+    await this.checkGitStatus();
+    await this.platformSpecificChecks();
+
+    this.printReport();
+    return this.errors.length === 0;
+  }
+
+  async checkEnvironmentVariables() {
+    console.log('📋 Checking environment variables...');
+
+    for (const envVar of this.config.requiredEnv) {
+      if (process.env[envVar]) {
+        this.checks.push({ name: envVar, status: 'pass', message: 'Set' });
+      } else {
+        this.errors.push(`Missing required: ${envVar}`);
+        this.checks.push({ name: envVar, status: 'fail', message: 'Missing' });
+      }
+    }
+
+    for (const envVar of this.config.optionalEnv) {
+      if (process.env[envVar]) {
+        this.checks.push({ name: envVar, status: 'pass', message: 'Set (optional)' });
+      } else {
+        this.warnings.push(`Optional not set: ${envVar}`);
+        this.checks.push({ name: envVar, status: 'warn', message: 'Not set (optional)' });
+      }
+    }
+  }
+
+  async checkBuildArtifacts() {
+    console.log('📦 Checking build artifacts...');
+
+    let foundArtifact = false;
+    for (const artifact of this.config.buildArtifacts) {
+      const path = resolve(process.cwd(), artifact);
+      if (existsSync(path)) {
+        foundArtifact = true;
+        this.checks.push({ name: artifact, status: 'pass', message: 'Found' });
+      }
+    }
+
+    if (!foundArtifact) {
+      this.warnings.push('No build artifacts found. Run build command first.');
+    }
+  }
+
+  async checkConfigFiles() {
+    console.log('⚙️  Checking configuration files...');
+
+    let foundConfig = false;
+    for (const configFile of this.config.configFiles) {
+      const path = resolve(process.cwd(), configFile);
+      if (existsSync(path)) {
+        foundConfig = true;
+        this.checks.push({ name: configFile, status: 'pass', message: 'Found' });
+
+        // Validate config content
+        try {
+          const content = readFileSync(path, 'utf8');
+          if (configFile.endsWith('.json')) {
+            JSON.parse(content);
+            this.checks.push({ name: `${configFile} syntax`, status: 'pass', message: 'Valid JSON' });
+          }
+        } catch (e) {
+          this.errors.push(`Invalid ${configFile}: ${e.message}`);
+        }
+      }
+    }
+
+    if (!foundConfig) {
+      this.warnings.push(`No ${this.platform} config file found. Using defaults.`);
+    }
+  }
+
+  async checkGitStatus() {
+    console.log('🔀 Checking git status...');
+
+    try {
+      const { execSync } = await import('child_process');
+
+      // Check for uncommitted changes
+      const status = execSync('git status --porcelain', { encoding: 'utf8' });
+      if (status.trim()) {
+        this.warnings.push('Uncommitted changes detected. Consider committing first.');
+        this.checks.push({ name: 'Git status', status: 'warn', message: 'Uncommitted changes' });
+      } else {
+        this.checks.push({ name: 'Git status', status: 'pass', message: 'Clean' });
+      }
+
+      // Check branch
+      const branch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();
+      this.checks.push({ name: 'Current branch', status: 'info', message: branch });
+
+    } catch (e) {
+      this.warnings.push('Not a git repository or git not available');
+    }
+  }
+
+  async platformSpecificChecks() {
+    switch (this.platform) {
+      case 'railway':
+        await this.checkRailway();
+        break;
+      case 'cloudflare':
+        await this.checkCloudflare();
+        break;
+      case 'vercel':
+        await this.checkVercel();
+        break;
+    }
+  }
+
+  async checkRailway() {
+    // Check for Dockerfile or supported runtime
+    const hasDockerfile = existsSync(resolve(process.cwd(), 'Dockerfile'));
+    const hasPackageJson = existsSync(resolve(process.cwd(), 'package.json'));
+    const hasRequirements = existsSync(resolve(process.cwd(), 'requirements.txt'));
+
+    if (!hasDockerfile && !hasPackageJson && !hasRequirements) {
+      this.errors.push('No supported runtime detected (Dockerfile, package.json, or requirements.txt)');
+    }
+
+    // Check for Railway-specific health check endpoint
+    if (hasPackageJson) {
+      try {
+        const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
+        if (pkg.scripts?.start) {
+          this.checks.push({ name: 'Start script', status: 'pass', message: pkg.scripts.start });
+        } else {
+          this.warnings.push('No "start" script in package.json');
+        }
+      } catch (e) {
+        // Ignore
+      }
+    }
+  }
+
+  async checkCloudflare() {
+    const { projectName } = this.options;
+
+    // Check dist folder
+    const distPath = resolve(process.cwd(), 'dist');
+    if (!existsSync(distPath)) {
+      this.errors.push('dist/ folder not found. Run "npm run build" first.');
+    }
+
+    // Check for index.html in dist
+    const indexPath = resolve(distPath, 'index.html');
+    if (existsSync(distPath) && !existsSync(indexPath)) {
+      this.warnings.push('No index.html in dist/. Is this a static site?');
+    }
+
+    // Validate wrangler.toml if exists
+    const wranglerPath = resolve(process.cwd(), 'wrangler.toml');
+    if (existsSync(wranglerPath)) {
+      const content = readFileSync(wranglerPath, 'utf8');
+      if (projectName && !content.includes(projectName)) {
+        this.warnings.push(`Project name "${projectName}" not found in wrangler.toml`);
+      }
+    }
+  }
+
+  async checkVercel() {
+    // Check for .vercel folder
+    const vercelDir = resolve(process.cwd(), '.vercel');
+    if (!existsSync(vercelDir)) {
+      this.warnings.push('No .vercel folder. Run "vercel link" first.');
+    }
+  }
+
+  printReport() {
+    console.log('\n' + '='.repeat(60));
+    console.log(`📊 Validation Report: ${this.platform.toUpperCase()}`);
+    console.log('='.repeat(60));
+
+    // Print checks
+    console.log('\nChecks:');
+    for (const check of this.checks) {
+      const icon = check.status === 'pass' ? '✅' :
+                   check.status === 'fail' ? '❌' :
+                   check.status === 'warn' ? '⚠️' : 'ℹ️';
+      console.log(`  ${icon} ${check.name}: ${check.message}`);
+    }
+
+    // Print errors
+    if (this.errors.length > 0) {
+      console.log('\n❌ Errors:');
+      for (const error of this.errors) {
+        console.log(`   - ${error}`);
+      }
+    }
+
+    // Print warnings
+    if (this.warnings.length > 0) {
+      console.log('\n⚠️  Warnings:');
+      for (const warning of this.warnings) {
+        console.log(`   - ${warning}`);
+      }
+    }
+
+    // Summary
+    console.log('\n' + '-'.repeat(60));
+    if (this.errors.length === 0) {
+      console.log('✅ Validation PASSED - Ready to deploy');
+    } else {
+      console.log(`❌ Validation FAILED - ${this.errors.length} error(s) found`);
+    }
+    console.log('-'.repeat(60) + '\n');
+  }
+}
+
+// CLI entry point
+async function main() {
+  const args = process.argv.slice(2);
+  const platformIndex = args.indexOf('--platform');
+  const platform = platformIndex >= 0 ? args[platformIndex + 1] : null;
+
+  if (!platform || !PLATFORMS[platform]) {
+    console.error('Usage: node validate-deployment.js --platform <railway|cloudflare|vercel|netlify>');
+    console.error('Available platforms:', Object.keys(PLATFORMS).join(', '));
+    process.exit(1);
+  }
+
+  const options = {};
+  const projectNameIndex = args.indexOf('--project-name');
+  if (projectNameIndex >= 0) {
+    options.projectName = args[projectNameIndex + 1];
+  }
+
+  const validator = new DeploymentValidator(platform, options);
+  const success = await validator.validate();
+  process.exit(success ? 0 : 1);
+}
+
+main().catch(console.error);

package/templates/skills/agent-creator/skill.json

@@ -0,0 +1,18 @@
+{
+  "name": "agent-creator",
+  "version": "1.0.0",
+  "description": "Create Claude Code CLI agents (subagents) following best practices",
+  "category": "development",
+  "portability": 100,
+  "features": [
+    "Task tool configuration",
+    "Agent specialization patterns",
+    "Workflow integration",
+    "RAG-enhanced knowledge bases"
+  ],
+  "entryPoint": "skill.md",
+  "context": [],
+  "workflows": [],
+  "requiredTools": ["Task", "Read", "Glob", "Grep"],
+  "suggestedModel": "sonnet"
+}

package/templates/skills/agent-creator/skill.md

@@ -0,0 +1,335 @@
+---
+name: agent-creator
+description: Create Claude Code CLI agents (subagents) following best practices - proper Task tool configuration, agent specialization, workflow integration, and RAG-enhanced knowledge bases
+---
+
+# Agent Creator Skill
+
+Expert-level Claude Code agent creation following official Anthropic best practices.
+
+## When to Use This Skill
+
+This skill is automatically invoked when:
+
+- Creating new specialized agents/subagents
+- Designing agent workflows
+- Configuring agent tool access
+- Setting up multi-agent coordination
+
+## Agent Architecture Overview
+
+### What are Claude Code Agents?
+
+Agents (subagents) are specialized Claude instances launched via the `Task` tool to handle complex, multi-step tasks autonomously. They:
+
+- Run in isolated contexts with specific tool access
+- Execute tasks without interrupting main conversation
+- Return results upon completion
+- Can run in parallel for independent tasks
+
+### Agent Types
+
+| Agent Type | Description | Tools |
+|------------|-------------|-------|
+| `general-purpose` | Research, search, multi-step tasks | All tools |
+| `Explore` | Fast codebase exploration | All except Edit, Write |
+| `Plan` | Planning and discovery | All except Edit, Write |
+| `Bash` | Command execution specialist | Bash only |
+
+## Creating Custom Agents
+
+### Skill-Based Agents
+
+Agents defined as skills live in `.claude/skills/{skill-name}/`:
+
+```
+.claude/skills/
+  my-agent/
+    skill.md              # Main skill definition (YAML frontmatter)
+    context/              # Agent context files
+      README.md
+      patterns.md
+      examples.md
+    workflows/            # Sub-workflows
+      README.md
+      sub-task-1.md
+      sub-task-2.md
+```
+
+### skill.md Format
+
+```markdown
+---
+name: my-agent
+description: Brief description shown in skill list
+---
+
+# Agent Title
+
+Detailed agent instructions, patterns, and capabilities.
+
+## When to Use This Agent
+
+List specific scenarios when this agent should be invoked.
+
+## Capabilities
+
+- What this agent can do
+- Tools it has access to
+- Patterns it follows
+
+## Workflow
+
+Step-by-step process the agent follows.
+
+## Output Format
+
+What the agent returns upon completion.
+```
+
+## Agent Design Patterns
+
+### Pattern 1: Discovery Agent
+
+Purpose: Research and understand before implementation.
+
+```markdown
+---
+name: discovery-agent
+description: Research codebase, find patterns, gather requirements
+---
+
+# Discovery Agent
+
+## Purpose
+
+Explore the codebase to understand:
+- Existing patterns and conventions
+- File organization and structure
+- Dependencies and relationships
+- Potential impact areas
+
+## Workflow
+
+1. **Initial Search** - Use Glob/Grep to find relevant files
+2. **Deep Read** - Read key files to understand patterns
+3. **Map Dependencies** - Trace imports and relationships
+4. **Document Findings** - Summarize discoveries
+
+## Output
+
+Return a structured report:
+- Files discovered
+- Patterns identified
+- Key dependencies
+- Recommendations
+```
+
+### Pattern 2: Implementation Agent
+
+Purpose: Execute code changes with proper patterns.
+
+```markdown
+---
+name: implementation-agent
+description: Write code following project patterns and conventions
+---
+
+# Implementation Agent
+
+## Purpose
+
+Implement features following project standards:
+- Use established patterns
+- Maintain consistency
+- Add appropriate tests
+- Update documentation
+
+## Prerequisites
+
+- Discovery complete
+- Plan approved
+- Target files identified
+
+## Workflow
+
+1. **Read Target Files** - Understand current state
+2. **Apply Patterns** - Use project conventions
+3. **Implement Changes** - Write clean code
+4. **Add Tests** - Cover new functionality
+5. **Validate** - Ensure no regressions
+
+## Output
+
+Return implementation summary:
+- Files modified
+- Tests added
+- Breaking changes (if any)
+```
+
+### Pattern 3: QA Agent
+
+Purpose: Validate changes and ensure quality.
+
+```markdown
+---
+name: qa-agent
+description: Validate changes, run tests, verify patterns
+---
+
+# QA Agent
+
+## Purpose
+
+Ensure quality through:
+- Pattern compliance
+- Test coverage
+- Error handling
+- Performance impact
+
+## Workflow
+
+1. **Review Changes** - Examine modified files
+2. **Run Tests** - Execute relevant test suites
+3. **Check Patterns** - Verify convention compliance
+4. **Report Issues** - Document findings
+
+## Output
+
+Return QA report:
+- Tests passed/failed
+- Pattern violations
+- Recommendations
+- Sign-off status
+```
+
+### Pattern 4: Orchestrator Agent
+
+Purpose: Coordinate multiple agents for complex tasks.
+
+```markdown
+---
+name: orchestrator-agent
+description: Coordinate multi-agent workflows for complex tasks
+---
+
+# Orchestrator Agent
+
+## Purpose
+
+Coordinate complex workflows:
+- Decompose tasks
+- Assign to specialized agents
+- Aggregate results
+- Handle dependencies
+
+## Workflow
+
+1. **Analyze Task** - Understand scope
+2. **Create Plan** - Break into subtasks
+3. **Dispatch Agents** - Launch specialized agents
+4. **Monitor Progress** - Track completion
+5. **Aggregate Results** - Combine outputs
+
+## Agent Dispatch
+
+Launch agents in parallel when independent:
+- Discovery can run with initial planning
+- Implementation waits for planning
+- QA waits for implementation
+```
+
+## Task Tool Configuration
+
+### Basic Agent Launch
+
+To launch an agent, invoke the Task tool with these parameters:
+
+```json
+{
+  "description": "Research authentication patterns",
+  "prompt": "Search the codebase for authentication implementations...",
+  "subagent_type": "Explore"
+}
+```
+
+### Agent Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `description` | Yes | Short (3-5 word) task description |
+| `prompt` | Yes | Detailed task instructions |
+| `subagent_type` | Yes | Agent type to use |
+| `model` | No | Override model (sonnet, opus, haiku) |
+| `resume` | No | Agent ID to resume from |
+
+### Model Selection
+
+| Model | Best For | Cost |
+|-------|----------|------|
+| `haiku` | Quick, straightforward tasks | Lowest |
+| `sonnet` | Default, balanced | Medium |
+| `opus` | Complex reasoning | Highest |
+
+## Best Practices
+
+### Agent Design
+
+1. **Single Responsibility** - Each agent does one thing well
+2. **Clear Boundaries** - Define what agent can/cannot do
+3. **Explicit Output** - Specify return format
+4. **Error Handling** - Define failure behavior
+
+### Task Prompts
+
+1. **Be Specific** - Include all necessary context
+2. **Define Success** - What does "done" look like?
+3. **Scope Limits** - What should agent NOT do?
+4. **Output Format** - How to structure results?
+
+### Parallel Execution
+
+1. **Independence** - Only parallelize independent tasks
+2. **Single Message** - Multiple Task calls in one message
+3. **Dependencies** - Sequential tasks must wait
+
+**Parallel Execution**: In a single message, invoke the Task tool multiple times.
+
+**Sequential Execution**: For dependent tasks, wait for first agent to complete before invoking the next Task tool.
+
+### Context Management
+
+1. **Stateless** - Each agent invocation is fresh
+2. **Self-Contained** - Include all needed context in prompt
+3. **Explicit Return** - Specify what to report back
+4. **No Follow-up** - Cannot send additional messages
+
+## Creating a New Agent
+
+### Step-by-Step Process
+
+1. **Define Purpose** - What problem does this agent solve?
+2. **Identify Tools** - What tools does it need?
+3. **Design Workflow** - What steps does it follow?
+4. **Specify Output** - What does it return?
+5. **Create Skill** - Write skill.md with context
+6. **Add RAG if Needed** - Include knowledge base for domain expertise
+7. **Add to README** - Document in skills README
+8. **Test Thoroughly** - Verify in real scenarios
+
+### Checklist
+
+- [ ] skill.md with YAML frontmatter
+- [ ] Clear "When to Use" section
+- [ ] Defined workflow steps
+- [ ] Explicit output format
+- [ ] Context files if needed
+- [ ] Added to skills README
+- [ ] Tested with sample tasks
+
+## References
+
+- Task Tool: System prompt documentation
+- Skills: `.claude/skills/README.md`
+- Agents: `.claude/agents/`
+- Official Docs: https://docs.anthropic.com/en/docs/claude-code

package/templates/skills/hook-creator/skill.json

@@ -0,0 +1,18 @@
+{
+  "name": "hook-creator",
+  "version": "1.0.0",
+  "description": "Create Claude Code CLI hooks following best practices",
+  "category": "development",
+  "portability": 100,
+  "features": [
+    "JSON schema configuration",
+    "Event type handling",
+    "Matcher patterns",
+    "Error handling templates"
+  ],
+  "entryPoint": "skill.md",
+  "context": [],
+  "workflows": [],
+  "requiredTools": ["Read", "Write", "Edit"],
+  "suggestedModel": "sonnet"
+}