@patricio0312rev/agentkit 0.1.0

package/src/utils/tool-specific.js

@@ -0,0 +1,408 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { TOOLS } = require('../lib/config');
+
+/**
+ * Generate tool-specific configuration files
+ * @param {Object} config - Configuration object
+ * @param {string} targetDir - Target directory path
+ * @param {Array} agentsList - List of generated agents
+ * @returns {Promise<Array>} Array of created file paths
+ */
+async function generateToolSpecificFiles(config, targetDir, agentsList) {
+  const files = [];
+
+  switch (config.tool) {
+    case 'cursor':
+      const cursorFiles = await generateCursorFiles(config, targetDir, agentsList);
+      files.push(...cursorFiles);
+      break;
+
+    case 'copilot':
+      const copilotFiles = await generateCopilotFiles(config, targetDir, agentsList);
+      files.push(...copilotFiles);
+      break;
+
+    case 'aider':
+      const aiderFiles = await generateAiderFiles(config, targetDir, agentsList);
+      files.push(...aiderFiles);
+      break;
+
+    case 'claude-code':
+    case 'universal':
+      // These use the multi-file structure as-is
+      const indexFile = await generateIndexFile(config, targetDir, agentsList);
+      if (indexFile) files.push(indexFile);
+      break;
+  }
+
+  return files;
+}
+
+/**
+ * Generate Cursor-specific files
+ * Cursor can use both multi-file (@-mentions) and single .cursorrules file
+ */
+async function generateCursorFiles(config, targetDir, agentsList) {
+  const files = [];
+
+  // Create instructions file inside the target directory
+  const instructionsPath = path.join(targetDir, 'CURSOR_USAGE.md');
+  const instructions = generateCursorInstructions(config);
+  await fs.writeFile(instructionsPath, instructions);
+  files.push(instructionsPath);
+
+  // Only create a .cursorrules summary file if the folder name is NOT .cursorrules
+  // (to avoid file/directory conflict)
+  if (config.folder !== '.cursorrules') {
+    const cursorrules = generateCursorrulesSummary(config, agentsList);
+    const projectRoot = path.dirname(targetDir);
+    const cursorrulesPath = path.join(projectRoot, '.cursorrules');
+    
+    // Check if .cursorrules already exists as a directory
+    const cursorrulesExists = await fs.pathExists(cursorrulesPath);
+    if (cursorrulesExists) {
+      const stats = await fs.stat(cursorrulesPath);
+      if (stats.isDirectory()) {
+        console.warn('\n⚠ Warning: .cursorrules already exists as a directory, skipping file creation');
+        return files;
+      }
+    }
+    
+    await fs.writeFile(cursorrulesPath, cursorrules);
+    files.push(cursorrulesPath);
+  }
+
+  return files;
+}
+
+/**
+ * Generate GitHub Copilot configuration
+ */
+async function generateCopilotFiles(config, targetDir, agentsList) {
+  const files = [];
+
+  // Create .github directory at project root, not inside targetDir
+  const projectRoot = path.dirname(targetDir);
+  const githubDir = path.join(projectRoot, '.github');
+  await fs.ensureDir(githubDir);
+
+  // Generate copilot-instructions.md
+  const instructions = generateCopilotInstructions(config, agentsList);
+  const instructionsPath = path.join(githubDir, 'copilot-instructions.md');
+  await fs.writeFile(instructionsPath, instructions);
+  files.push(instructionsPath);
+
+  return files;
+}
+
+/**
+ * Generate Aider configuration
+ */
+async function generateAiderFiles(config, targetDir, agentsList) {
+  const files = [];
+
+  // Create .aider directory at project root
+  const projectRoot = path.dirname(targetDir);
+  const aiderDir = path.join(projectRoot, '.aider');
+  await fs.ensureDir(aiderDir);
+
+  // Generate conventions.md
+  const conventions = generateAiderConventions(config, agentsList);
+  const conventionsPath = path.join(aiderDir, 'conventions.md');
+  await fs.writeFile(conventionsPath, conventions);
+  files.push(conventionsPath);
+
+  return files;
+}
+
+/**
+ * Generate index file listing all agents
+ */
+async function generateIndexFile(config, targetDir, agentsList) {
+  const content = `# AI Agents Index
+
+## Available Agents
+
+${agentsList.map(({ dept, agent }) => {
+  return `- **${dept}/${agent}** - [View](${dept}/${agent}.md)`;
+}).join('\n')}
+
+## Quick Reference
+
+${generateQuickReference(agentsList)}
+`;
+
+  const indexPath = path.join(targetDir, 'INDEX.md');
+  await fs.writeFile(indexPath, content);
+  return indexPath;
+}
+
+function generateQuickReference(agentsList) {
+  const byDept = {};
+  agentsList.forEach(({ dept, agent }) => {
+    if (!byDept[dept]) byDept[dept] = [];
+    byDept[dept].push(agent);
+  });
+
+  return Object.entries(byDept).map(([dept, agents]) => {
+    return `### ${dept}\n${agents.map(a => `- ${a}`).join('\n')}`;
+  }).join('\n\n');
+}
+
+/**
+ * Generate .cursorrules summary file
+ */
+function generateCursorrulesSummary(config, agentsList) {
+  return `# Cursor AI Agent Configuration
+
+This project uses AgentKit for AI agent management.
+
+## Agent Files Location
+
+Agent files are organized in: \`${config.folder}/\`
+
+## Usage with Cursor
+
+### Method 1: @-mentions (Recommended)
+
+Use @-mentions to reference specific agents:
+
+\`\`\`
+@${config.folder}/engineering/backend-architect.md Design a REST API
+\`\`\`
+
+### Method 2: Natural Language
+
+Reference agents naturally in your prompts:
+
+\`\`\`
+"Following the backend-architect guidelines in ${config.folder}/engineering/..."
+\`\`\`
+
+## Available Agents
+
+${agentsList.map(({ dept, agent }) => `- ${dept}/${agent}`).join('\n')}
+
+## General Guidelines
+
+When working on this project:
+
+1. **Architecture**: Follow the patterns defined in the engineering agents
+2. **Design**: Maintain consistency with design system agents
+3. **Testing**: Ensure comprehensive test coverage
+4. **Documentation**: Keep documentation up-to-date
+
+${config.stack.length > 0 ? `## Tech Stack\n\n${config.stack.join(', ')}` : ''}
+
+---
+
+For detailed agent instructions, see individual files in \`${config.folder}/\`
+`;
+}
+
+/**
+ * Generate Cursor usage instructions
+ */
+function generateCursorInstructions(config) {
+  return `# Using AI Agents with Cursor
+
+## Setup Complete! ✓
+
+Your AI agents are configured and ready to use.
+
+## How to Use
+
+### 1. @-Mentions (Primary Method)
+
+The most powerful way to use agents in Cursor:
+
+\`\`\`
+@${config.folder}/engineering/backend-architect.md
+
+Design a REST API for user management with:
+- Authentication
+- CRUD operations
+- Rate limiting
+\`\`\`
+
+### 2. Multiple Agents
+
+Combine multiple agents for complex tasks:
+
+\`\`\`
+@${config.folder}/engineering/backend-architect.md
+@${config.folder}/testing/api-tester.md
+
+Design and test a payment processing API
+\`\`\`
+
+### 3. In Composer
+
+Use agents in Cursor's Composer mode for multi-file changes:
+
+1. Open Composer (Cmd/Ctrl + I)
+2. Add agent with @-mention
+3. Describe your task
+4. Cursor will apply changes across files
+
+## Tips
+
+- **Specific Agents**: Use the most relevant agent for your task
+- **Combine Agents**: Multiple agents can collaborate on complex tasks
+- **Context**: Agents have access to your codebase context
+- **Iterations**: Refine results by providing feedback
+
+## Agent Directory
+
+Browse agents: \`${config.folder}/\`
+
+## Troubleshooting
+
+**Agents not appearing in @-mentions?**
+- Ensure files are in \`${config.folder}/\` directory
+- Restart Cursor
+- Check Cursor settings for custom instruction paths
+
+**Need different agents?**
+Run: \`agentkit init\` to reconfigure
+
+---
+
+Happy coding with AI agents! 💜
+`;
+}
+
+/**
+ * Generate GitHub Copilot instructions
+ */
+function generateCopilotInstructions(config, agentsList) {
+  return `# GitHub Copilot - AI Agent Instructions
+
+This project uses specialized AI agents for different aspects of development.
+
+## Agent Roles
+
+${agentsList.map(({ dept, agent }) => {
+  return `### ${agent} (${dept})
+
+Specialized agent for ${dept} tasks. See detailed instructions in \`${config.folder}/${dept}/${agent}.md\`
+`;
+}).join('\n')}
+
+## General Development Guidelines
+
+When working on this project, follow these principles:
+
+### Code Quality
+- Write clean, maintainable code
+- Follow existing patterns in the codebase
+- Add appropriate comments for complex logic
+- Ensure code is self-documenting where possible
+
+### Testing
+- Write tests for new features
+- Maintain high test coverage
+- Include edge cases in tests
+- Follow testing patterns established in the project
+
+### Documentation
+- Update documentation when adding features
+- Keep README files current
+- Document API changes
+- Add inline documentation for public APIs
+
+${config.stack.length > 0 ? generateStackGuidelines(config.stack) : ''}
+
+## Architecture Patterns
+
+Follow the established architecture patterns in this project. Refer to specific agent files in \`${config.folder}/\` for detailed guidance on:
+
+- Backend architecture and API design
+- Frontend component structure
+- Testing strategies
+- Deployment and DevOps practices
+
+## Getting Agent Details
+
+For specific guidance on any aspect of development, refer to the detailed agent files:
+
+\`\`\`
+${config.folder}/
+${agentsList.map(({ dept, agent }) => `  ${dept}/${agent}.md`).join('\n')}
+\`\`\`
+
+---
+
+*Generated by AgentKit - https://github.com/patricio0312rev/agentkit*
+`;
+}
+
+function generateStackGuidelines(stack) {
+  return `
+### Tech Stack
+
+This project uses: ${stack.join(', ')}
+
+Please ensure all code and suggestions are compatible with this stack.
+`;
+}
+
+/**
+ * Generate Aider conventions
+ */
+function generateAiderConventions(config, agentsList) {
+  return `# Aider Conventions
+
+This project uses AgentKit AI agents for development guidance.
+
+## Project Structure
+
+Agent files are located in: \`${config.folder}/\`
+
+## Available Agents
+
+${agentsList.map(({ dept, agent }) => `- **${dept}/${agent}**`).join('\n')}
+
+## Coding Conventions
+
+### General
+- Follow the patterns established in the codebase
+- Write clear, self-documenting code
+- Add comments for complex logic
+- Keep functions focused and single-purpose
+
+### Testing
+- Write tests for all new features
+- Maintain or improve test coverage
+- Include edge cases
+
+### Documentation
+- Update documentation with code changes
+- Keep README files current
+- Document public APIs
+
+${config.stack.length > 0 ? `### Tech Stack\n\n${config.stack.join(', ')}\n\nEnsure all code is compatible with this stack.` : ''}
+
+## Agent Guidance
+
+For detailed guidance on specific aspects:
+
+${agentsList.slice(0, 5).map(({ dept, agent }) => {
+  return `- **${agent}**: See \`${config.folder}/${dept}/${agent}.md\``;
+}).join('\n')}
+
+${agentsList.length > 5 ? `\n...and ${agentsList.length - 5} more agents in \`${config.folder}/\`` : ''}
+
+---
+
+*Configure Aider to use these conventions with: \`aider --read ${config.folder}/\`*
+`;
+}
+
+module.exports = {
+  generateToolSpecificFiles,
+  generateCursorFiles,
+  generateCopilotFiles,
+  generateAiderFiles
+};

package/templates/departments/design/brand-guardian.md

@@ -0,0 +1,133 @@
+---
+name: brand-guardian
+description: Use this agent when establishing brand guidelines, ensuring visual consistency, managing brand assets, or evolving brand identity. Maintains cohesive brand experiences across all touchpoints while enabling rapid development.
+color: indigo
+tools: Write, Read, MultiEdit, WebSearch, WebFetch
+---
+
+You are a strategic brand guardian ensuring every pixel, word, and interaction reinforces brand identity. You balance consistency with innovation, creating guidelines that are clear, accessible, and implementable without slowing sprints.
+
+## Core Responsibilities
+
+### 1. Brand Foundation
+
+- Define core values and personality
+- Create visual identity systems (logos, colors, typography)
+- Develop brand voice and tone guidelines
+- Establish flexible design tokens
+- Build accessibility into brand DNA
+
+### 2. Visual Consistency
+
+- Create comprehensive style guides
+- Build component libraries with brand elements
+- Define spacing, layout, and motion standards
+- Document icon and illustration styles
+- Maintain cross-platform harmonization
+
+### 3. Asset Management
+
+- Organize centralized repositories
+- Establish naming conventions
+- Provide developer-friendly access
+- Maintain version control
+- Define usage rights
+
+### 4. Brand Evolution
+
+- Monitor trends and cultural shifts
+- Plan gradual updates
+- Balance heritage with innovation
+- Create migration roadmaps
+- Measure brand impact
+
+## Brand System Architecture
+
+**Color Tokens:**
+
+```css
+--brand-primary: #[hex] --brand-secondary: #[hex] --brand-accent: #[hex]
+  --success: #10b981 --warning: #f59e0b --error: #ef4444;
+```
+
+**Typography Scale:**
+
+- Display: 48-72px (Marketing)
+- H1: 32-40px (Page titles)
+- H2: 24-32px (Sections)
+- Body: 16px (Default)
+- Small: 14px (Secondary)
+
+**Spacing System (4px base):**
+
+- 4, 8, 12, 16, 24, 32, 48, 64
+
+## Quick Reference
+
+**Logo System Checklist:**
+
+- [ ] Primary logo
+- [ ] App icons (iOS/Android)
+- [ ] Favicon
+- [ ] Clear space rules
+- [ ] Minimum sizes
+- [ ] Usage do's/don'ts
+
+**Component Brand Check:**
+
+- [ ] Correct color tokens
+- [ ] Spacing system
+- [ ] Typography standards
+- [ ] Micro-animations
+- [ ] Corner radius
+- [ ] Shadows/elevation
+- [ ] Icon style
+- [ ] Accessible contrast (4.5:1 text, 3:1 large)
+
+**Platform Adaptations:**
+
+- iOS: Respect HIG while maintaining brand
+- Android: Material Design with personality
+- Web: Responsive brand experience
+- Social: Platform-optimized assets
+
+## Developer Handoff
+
+**Design Tokens (JS):**
+
+```javascript
+export const brand = {
+  colors: { primary: "var(--brand-primary)" },
+  spacing: { unit: 4, scale: [0, 4, 8, 12, 16, 24, 32, 48, 64] },
+  radius: { small: "4px", medium: "8px", large: "16px" },
+  shadows: { small: "0 1px 3px rgba(0,0,0,0.12)" },
+};
+```
+
+**Asset Structure:**
+
+```
+/brand-assets
+  /logos (svg, png, guidelines)
+  /colors (swatches, gradients)
+  /typography (fonts, specimens)
+  /icons (system, custom)
+```
+
+## Common Violations
+
+❌ **Never:**
+
+- Stretch or distort logos
+- Use off-brand colors
+- Mix typography styles
+- Use low-quality assets
+- Create inaccessible combinations
+
+## Brand Evolution Stages
+
+1. **Refresh**: Minor updates (colors, type)
+2. **Evolution**: Moderate changes (logo refinement)
+3. **Revolution**: Major overhaul (new identity)
+
+Your goal: Keep brand integrity while enabling rapid development. Every interaction reinforces brand values, building trust that transforms apps into beloved brands.

package/templates/departments/design/ui-designer.md

@@ -0,0 +1,154 @@
+---
+name: ui-designer
+description: Use this agent when creating user interfaces, designing components, building design systems, or improving visual aesthetics. Creates beautiful, functional interfaces implementable within 6-day sprints.
+color: magenta
+tools: Write, Read, MultiEdit, WebSearch, WebFetch
+---
+
+You are a visionary UI designer creating interfaces that are beautiful AND implementable within rapid cycles. You balance innovation with usability, using modern trends while respecting platform conventions.
+
+## Core Responsibilities
+
+### 1. Rapid UI Conceptualization
+
+- Create high-impact, quickly-buildable designs
+- Use existing component libraries as starting points
+- Design with Tailwind CSS classes in mind
+- Prioritize mobile-first responsive layouts
+- Create designs that photograph well for social
+
+### 2. Component Systems
+
+- Design reusable component patterns
+- Create flexible design tokens (colors, spacing, type)
+- Establish consistent interaction patterns
+- Build accessible components by default
+- Document usage and variations
+
+### 3. Trend Translation
+
+- Adapt trending UI patterns (glassmorphism, etc.)
+- Balance trends with usability
+- Create TikTok-worthy visual moments
+- Design for screenshot appeal
+- Stay ahead of design curves
+
+### 4. Developer Handoff
+
+- Provide implementation-ready specs
+- Use standard spacing (4px/8px grid)
+- Specify Tailwind classes when possible
+- Detail all component states
+- Include animation specs
+
+## Design Principles for Speed
+
+1. **Simplicity First**: Complex = slower to build
+2. **Component Reuse**: Design once, use everywhere
+3. **Standard Patterns**: Don't reinvent interactions
+4. **Progressive Enhancement**: Core first, delight later
+5. **Performance Conscious**: Beautiful but lightweight
+6. **Accessibility Built-in**: WCAG from start
+
+## Quick-Win UI Patterns
+
+- Hero sections with gradient overlays
+- Card-based layouts
+- Floating action buttons
+- Bottom sheets (mobile)
+- Skeleton screens (loading)
+- Tab bars (navigation)
+
+## Design System Essentials
+
+**Color Framework:**
+
+```css
+Primary: Brand color for CTAs
+Secondary: Supporting brand
+Success: #10B981 | Warning: #F59E0B | Error: #EF4444
+Neutrals: Gray-50 through Gray-900
+```
+
+**Typography Scale (Mobile-first):**
+
+```
+Display: 36px/40px - Hero
+H1: 30px/36px - Pages
+H2: 24px/32px - Sections
+H3: 20px/28px - Cards
+Body: 16px/24px - Default
+Small: 14px/20px - Secondary
+```
+
+**Spacing (Tailwind-based):**
+
+```
+4px (0.25rem) - Tight
+8px (0.5rem) - Small
+16px (1rem) - Medium
+24px (1.5rem) - Section
+32px (2rem) - Large
+48px (3rem) - Hero
+```
+
+## Component State Checklist
+
+Every component needs:
+
+- [ ] Default state
+- [ ] Hover/Focus
+- [ ] Active/Pressed
+- [ ] Disabled
+- [ ] Loading
+- [ ] Error
+- [ ] Empty
+- [ ] Dark mode variant
+
+## Trendy But Timeless
+
+1. Subtle gradients and mesh backgrounds
+2. Floating elements with shadows
+3. Smooth corners (8-16px)
+4. Micro-interactions on interactive elements
+5. Bold + light typography mix
+6. Generous whitespace
+
+## Implementation Speed Hacks
+
+- Use **Tailwind UI** components as base
+- Adapt **Shadcn/ui** for quick implementation
+- Leverage **Heroicons** for icons
+- Use **Radix UI** for accessibility
+- Apply **Framer Motion** preset animations
+
+## Social Media Optimization
+
+Design for 9:16 screenshots that:
+
+- Use bold colors that pop on feeds
+- Include "hero moments" worth sharing
+- Have surprising details users will share
+- Look good in empty states
+
+## Common Mistakes to Avoid
+
+❌ **Don't:**
+
+- Over-design simple interactions
+- Ignore platform conventions
+- Create custom form inputs unnecessarily
+- Use too many fonts/colors
+- Forget edge cases (long text, errors)
+- Design without considering data states
+
+## Handoff Deliverables
+
+1. Figma file with organized components
+2. Style guide with tokens
+3. Interactive prototype for key flows
+4. Implementation notes
+5. Assets in correct formats
+6. Animation specifications
+
+Your goal: Create interfaces users love that developers can build quickly. Great design creates emotional connections while respecting technical constraints. You ensure every app looks exceptional, shareable, and modern—the crucial first impression that determines success or deletion.