agentic-team-templates 0.3.0

package/src/index.js

@@ -0,0 +1,521 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+// Available templates
+const TEMPLATES = {
+  'blockchain': {
+    description: 'Smart contracts, DeFi protocols, and Web3 applications (Solidity, Foundry, Viem)',
+    rules: ['defi-patterns.md', 'gas-optimization.md', 'overview.md', 'security.md', 'smart-contracts.md', 'testing.md', 'web3-integration.md']
+  },
+  'cli-tools': {
+    description: 'Command-line applications and developer tools (Cobra, Commander, Click)',
+    rules: ['architecture.md', 'arguments.md', 'distribution.md', 'error-handling.md', 'overview.md', 'testing.md', 'user-experience.md']
+  },
+  'documentation': {
+    description: 'Technical documentation standards (READMEs, API docs, ADRs, code comments)',
+    rules: ['adr.md', 'api-documentation.md', 'code-comments.md', 'maintenance.md', 'overview.md', 'readme-standards.md']
+  },
+  'fullstack': {
+    description: 'Full-stack web applications (Next.js, Nuxt, SvelteKit, Remix)',
+    rules: ['api-contracts.md', 'architecture.md', 'overview.md', 'shared-types.md', 'testing.md']
+  },
+  'mobile': {
+    description: 'Mobile applications (React Native, Flutter, native iOS/Android)',
+    rules: ['navigation.md', 'offline-first.md', 'overview.md', 'performance.md', 'testing.md']
+  },
+  'utility-agent': {
+    description: 'AI agent utilities with context management and hallucination prevention',
+    rules: ['action-control.md', 'context-management.md', 'hallucination-prevention.md', 'overview.md', 'token-optimization.md']
+  },
+  'web-backend': {
+    description: 'Backend APIs and services (REST, GraphQL, microservices)',
+    rules: ['api-design.md', 'authentication.md', 'database-patterns.md', 'error-handling.md', 'overview.md', 'security.md', 'testing.md']
+  },
+  'web-frontend': {
+    description: 'Frontend web applications (SPAs, SSR, static sites, PWAs)',
+    rules: ['accessibility.md', 'component-patterns.md', 'overview.md', 'performance.md', 'state-management.md', 'styling.md', 'testing.md']
+  }
+};
+
+const SHARED_RULES = [
+  'code-quality.md',
+  'communication.md', 
+  'core-principles.md',
+  'git-workflow.md',
+  'security-fundamentals.md'
+];
+
+// Colors
+const colors = {
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  blue: (s) => `\x1b[34m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+};
+
+function printBanner() {
+  console.log(colors.blue(`
+╔═══════════════════════════════════════════════════════════╗
+║              Cursor Templates Installer                   ║
+╚═══════════════════════════════════════════════════════════╝
+`));
+}
+
+function printHelp() {
+  console.log(`${colors.yellow('Usage:')}
+  npx cursor-templates <templates...>
+
+${colors.yellow('Options:')}
+  --list, -l     List available templates
+  --help, -h     Show this help message
+  --dry-run      Show what would be installed
+  --force, -f    Overwrite existing files (default: skip)
+
+${colors.yellow('Examples:')}
+  npx cursor-templates web-frontend
+  npx cursor-templates web-frontend web-backend
+  npx cursor-templates fullstack
+  npx cursor-templates mobile utility-agent
+  npx cursor-templates web-backend --force
+
+${colors.dim('Shared rules (code-quality, security, git-workflow, etc.) are always included.')}
+${colors.dim('Identical files are skipped. Modified files are preserved; ours saved as *-1.md.')}
+`);
+}
+
+function printTemplates() {
+  console.log(colors.yellow('Available Templates:\n'));
+  
+  for (const [name, info] of Object.entries(TEMPLATES)) {
+    console.log(`  ${colors.green(name)}`);
+    console.log(`    ${info.description}\n`);
+  }
+  
+  console.log(colors.blue('Shared rules (always included):'));
+  for (const rule of SHARED_RULES) {
+    console.log(`  - ${rule.replace('.md', '')}`);
+  }
+  console.log();
+}
+
+/**
+ * Check if two files have identical content
+ */
+function filesMatch(file1, file2) {
+  try {
+    const content1 = fs.readFileSync(file1, 'utf8');
+    const content2 = fs.readFileSync(file2, 'utf8');
+    return content1 === content2;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get alternate filename with -1 suffix (e.g., code-quality.md -> code-quality-1.md)
+ */
+function getAlternateFilename(filepath) {
+  const dir = path.dirname(filepath);
+  const ext = path.extname(filepath);
+  const base = path.basename(filepath, ext);
+  return path.join(dir, `${base}-1${ext}`);
+}
+
+/**
+ * Copy file, handling existing files intelligently
+ * @returns {{ status: string, destFile: string }}
+ *   status: 'copied' | 'skipped' | 'renamed' | 'updated'
+ *   destFile: actual destination path (may differ if renamed)
+ */
+function copyFile(src, dest, force = false) {
+  const destDir = path.dirname(dest);
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+  
+  const exists = fs.existsSync(dest);
+  
+  if (!exists) {
+    // File doesn't exist - copy normally
+    fs.copyFileSync(src, dest);
+    return { status: 'copied', destFile: dest };
+  }
+  
+  if (force) {
+    // Force mode - overwrite
+    fs.copyFileSync(src, dest);
+    return { status: 'updated', destFile: dest };
+  }
+  
+  // File exists - check if it matches our template
+  if (filesMatch(src, dest)) {
+    // Same content - skip
+    return { status: 'skipped', destFile: dest };
+  }
+  
+  // Different content - save ours alongside with -1 suffix
+  const altDest = getAlternateFilename(dest);
+  fs.copyFileSync(src, altDest);
+  return { status: 'renamed', destFile: altDest };
+}
+
+function generateClaudeMdContent(installedTemplates) {
+  const templateList = installedTemplates
+    .map(t => `- **${t}**: ${TEMPLATES[t].description}`)
+    .join('\n');
+
+  const templateRuleTables = installedTemplates.map(template => {
+    const rules = TEMPLATES[template].rules
+      .map(rule => `| \`${template}-${rule}\` | ${rule.replace('.md', '').replace(/-/g, ' ')} guidelines |`)
+      .join('\n');
+    
+    return `
+#### ${template.charAt(0).toUpperCase() + template.slice(1)} Rules
+
+| Rule | Purpose |
+|------|---------|
+${rules}`;
+  }).join('\n');
+
+  return `# CLAUDE.md - Development Guide
+
+This project uses AI-assisted development with Cursor. The rules in \`.cursorrules/\` provide domain-specific guidance for the AI assistant.
+
+---
+
+## Quick Reference
+
+### Installed Templates
+
+- **Shared** (always included): Core principles, code quality, security, git workflow, communication
+${templateList}
+
+### Rule Files
+
+All rules are in \`.cursorrules/\`. The AI assistant automatically reads these when working on your project.
+
+#### Shared Rules (Apply to All Code)
+
+| Rule | Purpose |
+|------|---------|
+| \`core-principles.md\` | Honesty, simplicity, testing requirements |
+| \`code-quality.md\` | SOLID, DRY, clean code patterns |
+| \`security-fundamentals.md\` | Zero trust, input validation, secrets |
+| \`git-workflow.md\` | Commits, branches, PRs, safety |
+| \`communication.md\` | Direct, objective, professional |
+${templateRuleTables}
+
+---
+
+## Development Principles
+
+### 1. Honesty Over Output
+
+- If something doesn't work, say it doesn't work
+- If you don't know, say you don't know
+- Never hide errors or suppress warnings
+- Admit mistakes early
+
+### 2. Security First
+
+- Zero trust: Every input is hostile until proven otherwise
+- Validate and sanitize all inputs
+- No secrets in code or logs
+- Least privilege principle
+
+### 3. Tests Are Required
+
+- No feature is complete without tests
+- Green CI or it didn't happen
+- Test behavior, not implementation
+
+### 4. Code Quality
+
+- SOLID principles
+- DRY (Don't Repeat Yourself)
+- Functional programming bias
+- Explicit over implicit
+
+---
+
+## Definition of Done
+
+A feature is complete when:
+
+- [ ] Code written and reviewed
+- [ ] Tests written and passing
+- [ ] No linting errors
+- [ ] Security reviewed
+- [ ] Documentation updated
+- [ ] Committed with conventional commit message
+
+---
+
+## Customization
+
+### Adding Project-Specific Rules
+
+1. Create new \`.md\` files in \`.cursorrules/\`
+2. Follow the existing naming convention
+3. Include clear examples and anti-patterns
+
+### Modifying Existing Rules
+
+Edit files directly in \`.cursorrules/\`. Changes take effect immediately.
+
+### Updating Templates
+
+Re-run the installer to update (will overwrite existing rules):
+
+\`\`\`bash
+npx cursor-templates ${installedTemplates.join(' ')}
+\`\`\`
+
+---
+
+## Resources
+
+- [Cursor Documentation](https://cursor.sh/docs)
+`;
+}
+
+function generateClaudeMd(targetDir, installedTemplates) {
+  const content = generateClaudeMdContent(installedTemplates);
+  fs.writeFileSync(path.join(targetDir, 'CLAUDE.md'), content);
+}
+
+function generateClaudeMdToPath(targetDir, installedTemplates, destPath) {
+  const content = generateClaudeMdContent(installedTemplates);
+  fs.writeFileSync(destPath, content);
+}
+
+function install(targetDir, templates, dryRun = false, force = false) {
+  const cursorrules = path.join(targetDir, '.cursorrules');
+  
+  if (!dryRun && !fs.existsSync(cursorrules)) {
+    fs.mkdirSync(cursorrules, { recursive: true });
+  }
+
+  console.log(`${colors.blue('Installing to:')} ${targetDir}`);
+  if (!force) {
+    console.log(colors.dim('(identical files skipped, modified files preserved with ours saved as *-1.md)'));
+  }
+  console.log();
+
+  const stats = { copied: 0, skipped: 0, updated: 0, renamed: 0 };
+  const renamedFiles = [];
+
+  // 1. Install shared rules
+  console.log(colors.green('► Installing shared rules...'));
+  for (const rule of SHARED_RULES) {
+    const src = path.join(TEMPLATES_DIR, '_shared', rule);
+    const dest = path.join(cursorrules, rule);
+    
+    if (dryRun) {
+      const exists = fs.existsSync(dest);
+      if (!exists) {
+        console.log(`  ${colors.dim('[copy]')} ${rule}`);
+      } else if (force) {
+        console.log(`  ${colors.dim('[update]')} ${rule}`);
+      } else if (filesMatch(src, dest)) {
+        console.log(`  ${colors.yellow('[skip]')} ${rule} (identical)`);
+      } else {
+        const altName = path.basename(getAlternateFilename(dest));
+        console.log(`  ${colors.blue('[rename]')} ${rule} → ${altName}`);
+      }
+    } else {
+      const result = copyFile(src, dest, force);
+      stats[result.status]++;
+      if (result.status === 'skipped') {
+        console.log(`  ${colors.yellow('[skip]')} ${rule} (identical)`);
+      } else if (result.status === 'renamed') {
+        const altName = path.basename(result.destFile);
+        renamedFiles.push({ original: rule, renamed: altName });
+        console.log(`  ${colors.blue('[rename]')} ${rule} → ${altName}`);
+      } else {
+        console.log(`  ${colors.dim(`[${result.status}]`)} ${rule}`);
+      }
+    }
+  }
+  console.log();
+
+  // 2. Install template-specific rules
+  for (const template of templates) {
+    console.log(colors.green(`► Installing ${template} template...`));
+    
+    for (const rule of TEMPLATES[template].rules) {
+      const src = path.join(TEMPLATES_DIR, template, '.cursorrules', rule);
+      const dest = path.join(cursorrules, `${template}-${rule}`);
+      const destName = `${template}-${rule}`;
+      
+      if (dryRun) {
+        const exists = fs.existsSync(dest);
+        if (!exists) {
+          console.log(`  ${colors.dim('[copy]')} ${destName}`);
+        } else if (force) {
+          console.log(`  ${colors.dim('[update]')} ${destName}`);
+        } else if (filesMatch(src, dest)) {
+          console.log(`  ${colors.yellow('[skip]')} ${destName} (identical)`);
+        } else {
+          const altName = path.basename(getAlternateFilename(dest));
+          console.log(`  ${colors.blue('[rename]')} ${destName} → ${altName}`);
+        }
+      } else {
+        const result = copyFile(src, dest, force);
+        stats[result.status]++;
+        if (result.status === 'skipped') {
+          console.log(`  ${colors.yellow('[skip]')} ${destName} (identical)`);
+        } else if (result.status === 'renamed') {
+          const altName = path.basename(result.destFile);
+          renamedFiles.push({ original: destName, renamed: altName });
+          console.log(`  ${colors.blue('[rename]')} ${destName} → ${altName}`);
+        } else {
+          console.log(`  ${colors.dim(`[${result.status}]`)} ${destName}`);
+        }
+      }
+    }
+    console.log();
+  }
+
+  // 3. Generate CLAUDE.md
+  const claudePath = path.join(targetDir, 'CLAUDE.md');
+  const claudeExists = fs.existsSync(claudePath);
+  
+  console.log(colors.green('► Generating CLAUDE.md...'));
+  if (dryRun) {
+    if (!claudeExists) {
+      console.log(`  ${colors.dim('[copy]')} CLAUDE.md`);
+    } else if (force) {
+      console.log(`  ${colors.dim('[update]')} CLAUDE.md`);
+    } else {
+      console.log(`  ${colors.blue('[rename]')} CLAUDE.md → CLAUDE-1.md`);
+    }
+  } else if (!claudeExists) {
+    generateClaudeMd(targetDir, templates);
+    console.log(`  ${colors.dim('[copied]')} CLAUDE.md`);
+    stats.copied++;
+  } else if (force) {
+    generateClaudeMd(targetDir, templates);
+    console.log(`  ${colors.dim('[updated]')} CLAUDE.md`);
+    stats.updated++;
+  } else {
+    // Save ours as CLAUDE-1.md
+    const altClaudePath = path.join(targetDir, 'CLAUDE-1.md');
+    generateClaudeMdToPath(targetDir, templates, altClaudePath);
+    renamedFiles.push({ original: 'CLAUDE.md', renamed: 'CLAUDE-1.md' });
+    console.log(`  ${colors.blue('[rename]')} CLAUDE.md → CLAUDE-1.md`);
+    stats.renamed++;
+  }
+  console.log();
+
+  // Summary
+  console.log(colors.green('════════════════════════════════════════════════════════════'));
+  console.log(colors.green('✓ Installation complete!\n'));
+  
+  console.log(colors.yellow('Summary:'));
+  console.log(`  - ${stats.copied} files created`);
+  if (stats.updated > 0) {
+    console.log(`  - ${stats.updated} files updated`);
+  }
+  if (stats.skipped > 0) {
+    console.log(`  - ${stats.skipped} files skipped (identical to template)`);
+  }
+  if (stats.renamed > 0) {
+    console.log(`  - ${colors.blue(`${stats.renamed} files saved as *-1.md`)} (yours preserved)`);
+  }
+  console.log();
+  
+  console.log(colors.yellow('Templates installed:'));
+  console.log('  - _shared (always included)');
+  for (const template of templates) {
+    console.log(`  - ${template}`);
+  }
+  console.log();
+  
+  if (renamedFiles.length > 0) {
+    console.log(colors.blue('Files saved alongside existing (your files preserved):'));
+    for (const { original, renamed } of renamedFiles) {
+      console.log(`  - ${original} → ${renamed}`);
+    }
+    console.log(colors.dim('\nReview the -1 files and merge changes as needed.'));
+    console.log(colors.dim('Use --force to overwrite existing files instead.'));
+    console.log();
+  }
+  
+  console.log(colors.blue('Next steps:'));
+  console.log('  1. Review CLAUDE.md for any customization');
+  console.log('  2. Commit the new files to your repository');
+  console.log();
+}
+
+export function run(args) {
+  const templates = [];
+  let dryRun = false;
+  let force = false;
+
+  // Parse arguments
+  for (const arg of args) {
+    switch (arg) {
+      case '--list':
+      case '-l':
+        printBanner();
+        printTemplates();
+        process.exit(0);
+        break;
+      case '--help':
+      case '-h':
+        printBanner();
+        printHelp();
+        process.exit(0);
+        break;
+      case '--dry-run':
+        dryRun = true;
+        break;
+      case '--force':
+      case '-f':
+        force = true;
+        break;
+      default:
+        if (arg.startsWith('-')) {
+          console.error(colors.red(`Error: Unknown option '${arg}'`));
+          printHelp();
+          process.exit(1);
+        }
+        templates.push(arg);
+    }
+  }
+
+  printBanner();
+
+  // Validate
+  if (templates.length === 0) {
+    console.error(colors.red('Error: No templates specified\n'));
+    printHelp();
+    process.exit(1);
+  }
+
+  for (const template of templates) {
+    if (!TEMPLATES[template]) {
+      console.error(colors.red(`Error: Unknown template '${template}'\n`));
+      printTemplates();
+      process.exit(1);
+    }
+  }
+
+  if (dryRun) {
+    console.log(colors.yellow('DRY RUN - No changes will be made\n'));
+  }
+
+  if (force) {
+    console.log(colors.yellow('FORCE MODE - Existing files will be overwritten\n'));
+  }
+
+  // Install to current directory
+  install(process.cwd(), templates, dryRun, force);
+}

package/templates/_shared/code-quality.md

@@ -0,0 +1,162 @@
+# Code Quality Standards
+
+Universal code quality principles applicable across all languages and frameworks.
+
+## SOLID Principles
+
+### Single Responsibility (S)
+One function, one job. One class, one purpose.
+
+```
+// Good
+function validateEmail(email: string): boolean { ... }
+function sendEmail(email: string, body: string): void { ... }
+
+// Bad
+function validateAndSendEmail(email: string, body: string): boolean { ... }
+```
+
+### Open/Closed (O)
+Extend via composition, not modification.
+
+```
+// Good: Extend behavior through composition
+const enhancedLogger = compose(addTimestamp, addContext)(baseLogger);
+
+// Bad: Modify existing code to add features
+function logger(msg) {
+  if (config.addTimestamp) { ... }  // Adding more conditionals over time
+}
+```
+
+### Liskov Substitution (L)
+Subtypes must be substitutable for their base types.
+
+### Interface Segregation (I)
+Small, focused interfaces over large, general ones.
+
+### Dependency Inversion (D)
+Depend on abstractions, not concrete implementations.
+
+```
+// Good: Inject dependencies
+function processOrder(orderRepo: OrderRepository) { ... }
+
+// Bad: Import concrete implementations
+import { MySQLOrderRepo } from './mysql-repo';
+function processOrder() { const repo = new MySQLOrderRepo(); ... }
+```
+
+## DRY (Don't Repeat Yourself)
+
+- Abstract repeated patterns into utilities
+- Create reusable components/functions
+- One source of truth for validation logic, constants, configurations
+- BUT: Don't over-abstract. Three similar lines is often better than a premature abstraction.
+
+## Clean Code Practices
+
+### Naming
+- Use intention-revealing names
+- Avoid abbreviations unless universally understood
+- Be consistent with naming conventions
+- Names should be searchable
+
+```
+// Good
+const maxConnectionRetries = 3;
+const userEmailAddress = getEmail(user);
+
+// Bad
+const max = 3;
+const e = getE(u);
+```
+
+### Functions
+- Keep functions small (ideally < 20 lines)
+- Functions should do one thing
+- Minimize arguments (0-3 is ideal)
+- Avoid side effects when possible
+- Return early to reduce nesting
+
+```
+// Good: Return early
+function getDiscount(user) {
+  if (!user) return 0;
+  if (!user.isPremium) return 0;
+  return user.discountRate;
+}
+
+// Bad: Deep nesting
+function getDiscount(user) {
+  if (user) {
+    if (user.isPremium) {
+      return user.discountRate;
+    }
+  }
+  return 0;
+}
+```
+
+### Comments
+- Code should be self-documenting
+- Comments explain *why*, not *what*
+- Delete commented-out code (that's what git is for)
+- Keep comments up-to-date or delete them
+
+```
+// Good: Explains why
+// Using retry logic because the external API is flaky during peak hours
+await retryWithBackoff(apiCall, 3);
+
+// Bad: Explains what (obvious from code)
+// Increment counter by 1
+counter++;
+```
+
+## Error Handling
+
+- Never swallow errors silently
+- Provide meaningful error messages
+- Fail fast with clear diagnostics
+- Handle errors at the appropriate level
+
+```
+// Good
+function parseConfig(path: string): Result<Config, ConfigError> {
+  const content = readFile(path);
+  if (!content.ok) {
+    return err(new ConfigError(`Failed to read config at ${path}: ${content.error}`));
+  }
+  // ...
+}
+
+// Bad
+function parseConfig(path: string): Config | null {
+  try {
+    // ...
+  } catch (e) {
+    return null;  // Caller has no idea what went wrong
+  }
+}
+```
+
+## Immutability
+
+Prefer immutable data structures and pure functions.
+
+```
+// Good: Immutable update
+const updatedUser = { ...user, name: newName };
+
+// Bad: Mutation
+user.name = newName;
+```
+
+## Avoid Over-Engineering
+
+- Only make changes that are directly requested or clearly necessary
+- Don't add features, refactor code, or make "improvements" beyond what was asked
+- Don't add error handling for scenarios that can't happen
+- Don't create helpers or abstractions for one-time operations
+- Don't design for hypothetical future requirements