@patricio0312rev/agentkit 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to AgentKit will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- N/A
+
+### Changed
+- N/A
+
+### Fixed
+- N/A
+
+## [0.2.1] - 2025-12-28
+
+### Added
+- Enhanced agent descriptions for all 35 templates with "Use this agent when:" criteria
+- Concrete usage examples for each agent showing when and how Claude Code should invoke them
+- Structured description format with bullet points and real-world scenarios
+
+### Changed
+- All agent template descriptions now include:
+  - Clear invocation criteria (5-7 bullet points per agent)
+  - 3 practical user/assistant interaction examples
+  - Task tool usage patterns for Claude Code integration
+
+### Fixed
+- N/A
+
+## [0.2.0] - 2025-12-28
+
+### Added
+- Model selection for Claude Code agents (sonnet, opus, haiku, or inherit from parent)
+- Interactive model selection prompt when choosing Claude Code tool
+- Automatic model field injection in agent frontmatter
+- Automated GitHub Actions workflow for npm publishing
+- `RELEASE.md` documentation for publishing process
+- `CHANGELOG.md` for tracking version changes
+
+### Changed
+- Claude Code folder structure: agents now placed directly in `.claude/agents` (no department subfolders)
+- Folder path validation now allows forward slashes for nested paths
+- Default folder for Claude Code changed from `.claude` to `.claude/agents`
+
+### Fixed
+- Folder validation rejecting valid paths with forward slashes
+- Model field not being added to agent frontmatter due to regex pattern mismatch
+
+## [0.1.0] - 2025-12-27
+
+### Added
+- Initial release of AgentKit
+- Support for Claude Code, Cursor, GitHub Copilot, Aider, and Universal AI tools
+- 7 department categories: Engineering, Design, Marketing, Product, Project Management, Studio Operations, Testing
+- 35+ pre-configured AI agent templates
+- Interactive CLI for agent selection
+- Department-based organization
+- Custom folder naming
+- Non-interactive mode with flags
+
+### Changed
+- N/A
+
+### Fixed
+- N/A
+
+---
+
+## Release Types
+
+- **Added** - New features
+- **Changed** - Changes in existing functionality
+- **Deprecated** - Soon-to-be removed features
+- **Removed** - Removed features
+- **Fixed** - Bug fixes
+- **Security** - Security fixes

package/README.md

@@ -4,7 +4,7 @@
 
 AgentKit is a CLI tool that helps you set up specialized AI agents for your development workflow. Get 42 pre-built agents across 7 departments—from engineering and design to marketing and testing—all optimized for rapid app development.
 
-[![npm version](https://img.shields.io/npm/v/agentkit.svg)](https://www.npmjs.com/package/agentkit)
+[![npm version](https://img.shields.io/npm/v/@patricio0312rev/agentkit.svg)](https://www.npmjs.com/package/@patricio0312rev/agentkit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
@@ -24,7 +24,7 @@ AgentKit is a CLI tool that helps you set up specialized AI agents for your deve
 
 ```bash
 # Install globally
-npm install -g agentkit
+npm install -g @patricio0312rev/agentkit
 
 # Or use directly with npx
 npx agentkit init
@@ -185,35 +185,6 @@ Copilot automatically uses `.github/copilot-instructions.md` for all suggestions
 
 ---
 
-## 🔧 Configuration Options
-
-```bash
-agentkit init [options]
-
-Options:
-  -t, --tool <tool>           AI tool (claude-code, cursor, copilot, aider, universal)
-  -f, --folder <name>         Custom folder name
-  -d, --departments <list>    Comma-separated list of departments
-  --agents <list>             Comma-separated list of specific agents
-  --skip-prompts              Skip all interactive prompts (requires all flags)
-  -h, --help                  Display help for command
-```
-
-**Examples:**
-
-```bash
-# Full engineering department
-agentkit init -t cursor -d engineering --skip-prompts
-
-# Specific agents only
-agentkit init -t cursor -d engineering --agents backend-architect,frontend-developer --skip-prompts
-
-# Multiple departments
-agentkit init -t claude-code -d engineering,design,marketing --skip-prompts
-```
-
----
-
 ## 📚 Documentation
 
 Each generated agent includes:
@@ -335,8 +306,8 @@ agentkit init \
 
 ```bash
 # If installed globally, try:
-npm uninstall -g agentkit
-npm install -g agentkit
+npm uninstall -g @patricio0312rev/agentkit
+npm install -g @patricio0312rev/agentkit
 
 # Or use npx:
 npx agentkit init
@@ -351,7 +322,7 @@ npx agentkit init
 **3. Permission errors during installation**
 
 ```bash
-sudo npm install -g agentkit
+sudo npm install -g @patricio0312rev/agentkit
 # Or use npx to avoid global install
 ```
 

package/RELEASE.md

@@ -0,0 +1,175 @@
+# Release Process
+
+This document explains how to publish new versions of AgentKit to npm using the automated GitHub Actions workflow.
+
+## One-Time Setup
+
+### 1. Get NPM Access Token
+
+1. Log in to [npmjs.com](https://www.npmjs.com/)
+2. Click on your profile icon → **Access Tokens**
+3. Click **Generate New Token** → **Classic Token**
+4. Select **Automation** type (allows CI/CD publishing)
+5. Copy the generated token (starts with `npm_...`)
+
+### 2. Add NPM Token to GitHub Secrets
+
+1. Go to your GitHub repository: `https://github.com/patricio0312rev/agentkit`
+2. Click **Settings** → **Secrets and variables** → **Actions**
+3. Click **New repository secret**
+4. Name: `NPM_TOKEN`
+5. Value: Paste your npm token
+6. Click **Add secret**
+
+That's it! The `GITHUB_TOKEN` is automatically provided by GitHub Actions.
+
+## Publishing a New Release
+
+### Step 1: Update Version
+
+Update the version in `package.json`:
+
+```bash
+# For patch release (0.1.0 → 0.1.1)
+npm version patch
+
+# For minor release (0.1.0 → 0.2.0)
+npm version minor
+
+# For major release (0.1.0 → 1.0.0)
+npm version major
+```
+
+This command will:
+- Update `package.json` version
+- Create a git commit with the version change
+- Create a git tag (e.g., `v0.1.1`)
+
+### Step 2: Update Changelog (Optional but Recommended)
+
+Create or update `CHANGELOG.md` with release notes:
+
+```markdown
+## [0.1.1] - 2025-01-XX
+
+### Added
+- Model selection for Claude Code agents
+- Direct agent placement in .claude/agents folder
+
+### Changed
+- Updated folder structure for Claude Code
+
+### Fixed
+- Bug fixes...
+```
+
+Commit the changelog:
+
+```bash
+git add CHANGELOG.md
+git commit -m "docs: update changelog for v0.1.1"
+```
+
+### Step 3: Push Tags to Trigger Release
+
+```bash
+# Push commits
+git push origin main
+
+# Push tags (this triggers the GitHub Action)
+git push origin --tags
+```
+
+### Step 4: Monitor the Release
+
+1. Go to **Actions** tab in GitHub repository
+2. You should see the "Publish to npm" workflow running
+3. The workflow will:
+   - Install dependencies
+   - Run tests
+   - Verify version matches tag
+   - Publish to npm
+   - Create GitHub release
+
+### Step 5: Verify Publication
+
+Check that the package was published:
+
+```bash
+npm view @patricio0312rev/agentkit version
+```
+
+Visit the npm page:
+https://www.npmjs.com/package/@patricio0312rev/agentkit
+
+## Manual Release (If Needed)
+
+If the automated workflow fails, you can publish manually:
+
+```bash
+# Make sure you're on the correct version
+npm version <patch|minor|major>
+
+# Login to npm
+npm login
+
+# Publish
+npm publish --access public
+```
+
+## Release Checklist
+
+Before releasing, ensure:
+
+- [ ] All tests pass: `npm test`
+- [ ] Code is linted and formatted
+- [ ] Version is bumped in `package.json`
+- [ ] `CHANGELOG.md` is updated
+- [ ] All changes are committed
+- [ ] Tags are pushed to GitHub
+
+## Version Numbering Guidelines
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **PATCH** (0.1.X) - Bug fixes, small improvements
+- **MINOR** (0.X.0) - New features, backward compatible
+- **MAJOR** (X.0.0) - Breaking changes
+
+## Troubleshooting
+
+### "Version already exists" error
+
+You tried to publish a version that already exists on npm. Bump the version again:
+
+```bash
+npm version patch
+git push origin --tags
+```
+
+### "Permission denied" error
+
+Your `NPM_TOKEN` might be invalid or expired:
+1. Generate a new token on npmjs.com
+2. Update the GitHub secret
+
+### Workflow doesn't trigger
+
+Make sure you pushed the tag:
+
+```bash
+git push origin --tags
+```
+
+The workflow only runs when tags matching `v*.*.*` are pushed.
+
+## Quick Reference
+
+```bash
+# Complete release process
+npm version patch              # Bump version
+git add CHANGELOG.md          # Add changelog
+git commit -m "docs: update changelog"
+git push origin main          # Push commits
+git push origin --tags        # Push tags → triggers workflow
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@patricio0312rev/agentkit",
   "displayName": "AgentKit",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "CLI tool to scaffold AI agent configurations for Claude Code, Cursor, and other AI coding assistants",
   "main": "src/index.js",
   "bin": {

package/src/commands/init.js

@@ -50,7 +50,8 @@ function buildConfigFromFlags(options) {
     agents: options.agents
       ? options.agents.split(",").map((a) => a.trim())
       : [],
-    stack: [], // Removed for v0.1.0
+    model: options.model === "inherit" ? undefined : options.model,
+    stack: [],
   };
 }
 
@@ -91,8 +92,8 @@ async function promptUser(options) {
         validate: (input) => {
           if (!input.trim()) return "Folder name cannot be empty";
           if (input.includes(" ")) return "Folder name cannot contain spaces";
-          if (input.includes("\\") || input.includes("/"))
-            return "Folder name cannot contain path separators";
+          if (input.includes("\\"))
+            return "Folder name cannot contain backslashes";
           return true;
         },
       },
@@ -102,6 +103,46 @@ async function promptUser(options) {
     answers.folder = options.folder;
   }
 
+  // Step 2.5: Model selection for Claude Code
+  if (answers.tool === "claude-code" && !options.model) {
+    const modelChoices = [
+      {
+        name: `${chalk.bold("Sonnet")} ${chalk.gray("→")} ${chalk.dim("Balanced performance - best for most agents")}`,
+        value: "sonnet",
+        short: "Sonnet",
+      },
+      {
+        name: `${chalk.bold("Opus")} ${chalk.gray("→")} ${chalk.dim("Most capable for complex reasoning tasks")}`,
+        value: "opus",
+        short: "Opus",
+      },
+      {
+        name: `${chalk.bold("Haiku")} ${chalk.gray("→")} ${chalk.dim("Fast and efficient for simple tasks")}`,
+        value: "haiku",
+        short: "Haiku",
+      },
+      {
+        name: `${chalk.bold("Inherit from parent")} ${chalk.gray("→")} ${chalk.dim("Use the same model as the main conversation")}`,
+        value: "inherit",
+        short: "Inherit from parent",
+      },
+    ];
+
+    const modelAnswer = await inquirer.prompt([
+      {
+        type: "list",
+        name: "model",
+        message: "Select model for agents:",
+        choices: modelChoices,
+        default: "sonnet",
+      },
+    ]);
+    answers.model =
+      modelAnswer.model === "inherit" ? undefined : modelAnswer.model;
+  } else if (options.model) {
+    answers.model = options.model === "inherit" ? undefined : options.model;
+  }
+
   // Step 3: Select departments
   if (!options.departments) {
     const deptChoices = Object.entries(DEPARTMENTS).map(([key, value]) => ({

package/src/lib/config.js

@@ -1,7 +1,7 @@
 const TOOLS = {
     'claude-code': {
       name: 'Claude Code',
-      folder: '.claude',
+      folder: '.claude/agents',
       description: 'Sub-agents with native support',
       fileStructure: 'multi-file',
       supportsSubAgents: true

package/src/lib/generator.js

@@ -1,8 +1,8 @@
-const fs = require('fs-extra');
-const path = require('path');
-const { TOOLS, DEPARTMENTS } = require('./config');
-const { generateReadme } = require('../utils/readme');
-const { generateToolSpecificFiles } = require('../utils/tool-specific');
+const fs = require("fs-extra");
+const path = require("path");
+const { TOOLS, DEPARTMENTS } = require("./config");
+const { generateReadme } = require("../utils/readme");
+const { generateToolSpecificFiles } = require("../utils/tool-specific");
 
 /**
  * Main generator function that creates AI agent configuration
@@ -16,7 +16,7 @@ async function generateAgents(config) {
     targetDir,
     agentsGenerated: 0,
     filesCreated: [],
-    errors: []
+    errors: [],
   };
 
   try {
@@ -29,18 +29,21 @@ async function generateAgents(config) {
     result.filesCreated.push(...agentResult.files);
 
     // Generate README
-    const readmePath = path.join(targetDir, 'README.md');
+    const readmePath = path.join(targetDir, "README.md");
     const readmeContent = generateReadme(config, result);
     await fs.writeFile(readmePath, readmeContent);
     result.filesCreated.push(readmePath);
 
     // Generate tool-specific files (e.g., .cursorrules, copilot-instructions.md)
-    const toolFiles = await generateToolSpecificFiles(config, targetDir, agentResult.agentsList);
+    const toolFiles = await generateToolSpecificFiles(
+      config,
+      targetDir,
+      agentResult.agentsList
+    );
     result.filesCreated.push(...toolFiles);
 
     result.success = true;
     return result;
-
   } catch (error) {
     result.errors.push(error.message);
     throw error;
@@ -58,22 +61,28 @@ async function generateDepartmentAgents(config, targetDir) {
   const files = [];
   const agentsList = [];
 
+  // For Claude Code, agents go directly in .claude/agents, not in department subfolders
+  const isClaudeCode = config.tool === "claude-code";
+
   for (const dept of config.departments) {
     const deptInfo = DEPARTMENTS[dept];
     if (!deptInfo) continue;
 
-    const deptDir = path.join(targetDir, dept);
+    // Only create department subdirectories for non-Claude Code tools
+    const deptDir = isClaudeCode ? targetDir : path.join(targetDir, dept);
     await fs.ensureDir(deptDir);
 
     // Determine which agents to generate
     let agentsToGenerate = deptInfo.agents;
-    
+
     // Filter if specific agents were selected
     if (config.agents && config.agents.length > 0) {
-      agentsToGenerate = agentsToGenerate.filter(agent => {
+      agentsToGenerate = agentsToGenerate.filter((agent) => {
         // Support both "agent-name" and "dept/agent-name" formats
-        return config.agents.includes(agent) || 
-               config.agents.includes(`${dept}/${agent}`);
+        return (
+          config.agents.includes(agent) ||
+          config.agents.includes(`${dept}/${agent}`)
+        );
       });
     }
 
@@ -100,13 +109,18 @@ async function generateDepartmentAgents(config, targetDir) {
  * @returns {Promise<string|null>} Path to created file or null
  */
 async function generateAgentFile(dept, agent, deptDir, config) {
-  const sourceFile = path.join(__dirname, '../../templates/departments', dept, `${agent}.md`);
+  const sourceFile = path.join(
+    __dirname,
+    "../../templates/departments",
+    dept,
+    `${agent}.md`
+  );
   const targetFile = path.join(deptDir, `${agent}.md`);
 
   try {
     // Check if template exists
     if (await fs.pathExists(sourceFile)) {
-      let content = await fs.readFile(sourceFile, 'utf8');
+      let content = await fs.readFile(sourceFile, "utf8");
 
       // Process content based on config
       content = processAgentContent(content, config);
@@ -115,7 +129,7 @@ async function generateAgentFile(dept, agent, deptDir, config) {
       return targetFile;
     } else {
       // Generate basic template if source doesn't exist
-      const basicTemplate = generateBasicAgentTemplate(dept, agent);
+      const basicTemplate = generateBasicAgentTemplate(dept, agent, config);
       await fs.writeFile(targetFile, basicTemplate);
       return targetFile;
     }
@@ -134,17 +148,34 @@ async function generateAgentFile(dept, agent, deptDir, config) {
 function processAgentContent(content, config) {
   let processed = content;
 
+  // Add model field to frontmatter for Claude Code agents
+  if (config.tool === "claude-code" && config.model) {
+    const frontmatterMatch = processed.match(/^---\n([\s\S]*?)\n---/);
+    if (frontmatterMatch) {
+      const frontmatterContent = frontmatterMatch[1];
+
+      const updatedFrontmatter = frontmatterContent.replace(
+        /(tools:.*?)($|\n)/,
+        `$1\nmodel: ${config.model}$2`
+      );
+      processed = processed.replace(
+        /^---\n[\s\S]*?\n---/,
+        `---\n${updatedFrontmatter}\n---`
+      );
+    }
+  }
+
   // Remove examples if requested
   if (config.skipExamples) {
     // Remove content between <example> tags
-    processed = processed.replace(/<example>[\s\S]*?<\/example>/g, '');
+    processed = processed.replace(/<example>[\s\S]*?<\/example>/g, "");
     // Clean up extra whitespace
-    processed = processed.replace(/\n{3,}/g, '\n\n');
+    processed = processed.replace(/\n{3,}/g, "\n\n");
   }
 
   // Add tech stack information if provided
   if (config.stack && config.stack.length > 0) {
-    const stackSection = `\n\n## Tech Stack Context\n\nThis project uses: ${config.stack.join(', ')}\n`;
+    const stackSection = `\n\n## Tech Stack Context\n\nThis project uses: ${config.stack.join(", ")}\n`;
     // Insert before the main content or at the end
     processed += stackSection;
   }
@@ -156,19 +187,27 @@ function processAgentContent(content, config) {
  * Generate a basic agent template when source file doesn't exist
  * @param {string} dept - Department name
  * @param {string} agent - Agent name
+ * @param {Object} config - Configuration object
  * @returns {string} Basic template content
  */
-function generateBasicAgentTemplate(dept, agent) {
+function generateBasicAgentTemplate(dept, agent, config) {
   const deptInfo = DEPARTMENTS[dept];
+  const modelLine =
+    config.tool === "claude-code" && config.model
+      ? `\nmodel: ${config.model}`
+      : "";
   return `<!-- ${dept}/${agent}.md -->
 ---
 name: ${agent}
 description: AI agent for ${deptInfo.name}
 color: blue
-tools: Read, Write, MultiEdit
+tools: Read, Write, MultiEdit${modelLine}
 ---
 
-# ${agent.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')}
+# ${agent
+    .split("-")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ")}
 
 This is a placeholder agent file. Please add specific instructions and responsibilities.
 
@@ -189,5 +228,5 @@ This is a placeholder agent file. Please add specific instructions and responsib
 module.exports = {
   generateAgents,
   generateDepartmentAgents,
-  generateAgentFile
+  generateAgentFile,
 };

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use this agent when:\n- Establishing or refining brand guidelines and standards\n- Ensuring visual consistency across products and touchpoints\n- Creating or managing brand assets (logos, color palettes, typography)\n- Evolving brand identity while maintaining coherence\n- Reviewing designs for brand compliance\n- Creating brand documentation or style guides\n- Making decisions about brand expression in new contexts\n\nExamples:\n- User: "We need to create comprehensive brand guidelines for our startup"\n  Assistant: "I'll use the brand-guardian agent to establish a complete brand guideline system covering visual identity, voice, and usage"\n  <Uses Task tool to launch brand-guardian agent>\n\n- User: "Does this new landing page match our brand identity?"\n  Assistant: "Let me use the brand-guardian agent to review the design against our brand standards"\n  <Uses Task tool to launch brand-guardian agent>\n\n- User: "We're expanding to a new product line, how should we adapt our branding?"\n  Assistant: "I'm going to use the brand-guardian agent to develop a brand extension strategy that maintains consistency"\n  <Uses Task tool to launch brand-guardian agent>
 color: indigo
 tools: Write, Read, MultiEdit, WebSearch, WebFetch
 ---

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use this agent when:\n- Creating user interface designs or mockups\n- Designing individual UI components or patterns\n- Building or maintaining design systems\n- Improving visual aesthetics or layouts\n- Defining color schemes, typography, or spacing systems\n- Creating responsive design specifications\n- Reviewing or critiquing existing UI designs\n\nExamples:\n- User: "I need a modern dashboard design for a SaaS analytics platform"\n  Assistant: "I'll use the ui-designer agent to create a comprehensive dashboard design with data visualization components"\n  <Uses Task tool to launch ui-designer agent>\n\n- User: "Can you help me design a button component system with all the variants we need?"\n  Assistant: "Let me use the ui-designer agent to create a complete button system with primary, secondary, and tertiary variants plus states"\n  <Uses Task tool to launch ui-designer agent>\n\n- User: "This login page feels cluttered and confusing"\n  Assistant: "I'm going to use the ui-designer agent to redesign the login page with better visual hierarchy and user flow"\n  <Uses Task tool to launch ui-designer agent>
 color: magenta
 tools: Write, Read, MultiEdit, WebSearch, WebFetch
 ---

package/templates/departments/design/ux-researcher.md

@@ -1,6 +1,6 @@
 ---
 name: ux-researcher
-description: Use this agent when conducting user research, analyzing user behavior, creating journey maps, or validating design decisions through testing. Understands user needs, pain points, and behaviors to inform product decisions within rapid development cycles.
+description: Use this agent when:\n- Conducting user research or usability studies\n- Analyzing user behavior patterns or data\n- Creating user personas, journey maps, or empathy maps\n- Validating design decisions through user testing\n- Identifying user pain points or needs\n- Planning research methodologies or test protocols\n- Synthesizing research findings into actionable insights\n\nExamples:\n- User: "We need to understand why users are abandoning our checkout flow"\n  Assistant: "I'll use the ux-researcher agent to conduct user research and identify friction points in the checkout process"\n  <Uses Task tool to launch ux-researcher agent>\n\n- User: "Can you create user personas for our target audience?"\n  Assistant: "Let me use the ux-researcher agent to develop data-driven user personas based on research and analytics"\n  <Uses Task tool to launch ux-researcher agent>\n\n- User: "We want to validate our new onboarding flow before launch"\n  Assistant: "I'm going to use the ux-researcher agent to design and conduct usability testing for the onboarding"\n  <Uses Task tool to launch ux-researcher agent>
 color: purple
 tools: Write, Read, MultiEdit, WebSearch, WebFetch
 ---

package/templates/departments/design/visual-storyteller.md

@@ -1,6 +1,6 @@
 ---
 name: visual-storyteller
-description: Use this agent when creating visual narratives, designing infographics, building presentations, or communicating complex ideas through imagery. Transforms data and concepts into compelling visual stories that engage users and stakeholders.
+description: Use this agent when:\n- Creating visual narratives or storytelling experiences\n- Designing infographics or data visualizations\n- Building presentations or pitch decks\n- Communicating complex ideas through imagery\n- Creating illustrations or visual metaphors\n- Designing onboarding flows or tutorials\n- Developing visual content for marketing or education\n\nExamples:\n- User: "We need an infographic explaining how our blockchain product works"\n  Assistant: "I'll use the visual-storyteller agent to create a clear, engaging infographic that simplifies the blockchain concept"\n  <Uses Task tool to launch visual-storyteller agent>\n\n- User: "Can you design a presentation for our investor pitch?"\n  Assistant: "Let me use the visual-storyteller agent to craft a compelling visual narrative for your pitch deck"\n  <Uses Task tool to launch visual-storyteller agent>\n\n- User: "Our onboarding needs visual tutorials for new users"\n  Assistant: "I'm going to use the visual-storyteller agent to design an engaging visual tutorial flow"\n  <Uses Task tool to launch visual-storyteller agent>
 color: cyan
 tools: Write, Read, MultiEdit, WebSearch, WebFetch
 ---

package/templates/departments/design/whimsy-injector.md

@@ -1,6 +1,6 @@
 ---
 name: whimsy-injector
-description: PROACTIVELY use this agent after any UI/UX changes to ensure delightful, playful elements are incorporated. Adds joy, surprise, and memorable moments to user experiences. Trigger automatically when design or interface updates are made.
+description: Use this agent when:\n- Adding delightful moments or playful elements to interfaces\n- Creating memorable micro-interactions or animations\n- Designing easter eggs or surprise features\n- Making products more joyful and engaging\n- Reviewing designs to add personality and charm\n- Creating playful copy or messaging\n- Differentiating products through delight\n\nExamples:\n- User: "This settings page feels boring and utilitarian"\n  Assistant: "I'll use the whimsy-injector agent to add delightful micro-interactions and playful elements while maintaining functionality"\n  <Uses Task tool to launch whimsy-injector agent>\n\n- User: "Can you make our 404 page more memorable?"\n  Assistant: "Let me use the whimsy-injector agent to transform the 404 page into a delightful, shareable experience"\n  <Uses Task tool to launch whimsy-injector agent>\n\n- User: "We want to add some personality to our app"\n  Assistant: "I'm going to use the whimsy-injector agent to inject joy and surprise throughout the user journey"\n  <Uses Task tool to launch whimsy-injector agent>
 color: yellow
 tools: Read, Write, MultiEdit, Grep, Glob
 ---

package/templates/departments/engineering/ai-engineer.md

@@ -1,6 +1,6 @@
 ---
 name: ai-engineer
-description: Use this agent when implementing AI/ML features, integrating language models, building recommendation systems, or adding intelligent automation to applications. Specializes in practical AI implementation for rapid deployment.
+description: Use this agent when:\n- Implementing AI/ML features or models in applications\n- Integrating language models (OpenAI, Anthropic, open-source LLMs)\n- Building recommendation systems or personalization features\n- Adding intelligent automation or data processing\n- Implementing computer vision or image processing features\n- Fine-tuning or training machine learning models\n- Debugging AI/ML integration issues\n\nExamples:\n- User: "I need to add ChatGPT integration to my app for customer support"\n  Assistant: "I'll use the ai-engineer agent to implement a robust LLM integration with proper error handling and context management"\n  <Uses Task tool to launch ai-engineer agent>\n\n- User: "We want to build a product recommendation engine based on user behavior"\n  Assistant: "Let me use the ai-engineer agent to design and implement a recommendation system using collaborative filtering"\n  <Uses Task tool to launch ai-engineer agent>\n\n- User: "Can you help implement image classification for user uploads?"\n  Assistant: "I'm going to use the ai-engineer agent to integrate a computer vision model for automated image classification"\n  <Uses Task tool to launch ai-engineer agent>
 color: cyan
 tools: Write, Read, MultiEdit, Bash, WebFetch
 ---

package/templates/departments/engineering/backend-architect.md

@@ -1,6 +1,6 @@
 ---
 name: backend-architect
-description: Use this agent when designing APIs, building server-side logic, implementing databases, or architecting scalable backend systems. Specializes in creating robust, secure, and performant backend services.
+description: Use this agent when:\n- Designing or implementing RESTful or GraphQL APIs\n- Building server-side business logic or microservices\n- Implementing database schemas, queries, or migrations\n- Architecting scalable backend systems or infrastructure\n- Implementing authentication, authorization, or security features\n- Optimizing backend performance or database queries\n- Debugging server-side issues or API problems\n\nExamples:\n- User: "I need to design a REST API for a blog platform with posts, comments, and user management"\n  Assistant: "I'll use the backend-architect agent to design a well-structured API with proper endpoints, authentication, and data models"\n  <Uses Task tool to launch backend-architect agent>\n\n- User: "The database queries are slow when fetching user data with nested relationships"\n  Assistant: "Let me use the backend-architect agent to analyze and optimize your database schema and queries"\n  <Uses Task tool to launch backend-architect agent>\n\n- User: "We need to implement OAuth2 authentication for our API"\n  Assistant: "I'm going to use the backend-architect agent to implement a secure OAuth2 flow with proper token management"\n  <Uses Task tool to launch backend-architect agent>
 color: purple
 tools: Write, Read, MultiEdit, Bash, Grep
 ---

package/templates/departments/engineering/devops-automator.md

@@ -1,6 +1,6 @@
 ---
 name: devops-automator
-description: Use this agent when setting up CI/CD pipelines, configuring cloud infrastructure, implementing monitoring systems, or automating deployment processes. Specializes in making deployment and operations seamless for rapid development cycles.
+description: Use this agent when:\n- Setting up or modifying CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins, etc.)\n- Configuring cloud infrastructure (AWS, GCP, Azure, etc.)\n- Implementing Infrastructure as Code (Terraform, CloudFormation, etc.)\n- Setting up monitoring, logging, or alerting systems\n- Automating deployment or release processes\n- Configuring containers or orchestration (Docker, Kubernetes)\n- Debugging deployment or infrastructure issues\n\nExamples:\n- User: "I need to set up a GitHub Actions workflow to deploy my Next.js app to Vercel"\n  Assistant: "I'll use the devops-automator agent to create a CI/CD pipeline with automated testing and deployment"\n  <Uses Task tool to launch devops-automator agent>\n\n- User: "Our Kubernetes pods keep crashing and I need help debugging the configuration"\n  Assistant: "Let me use the devops-automator agent to analyze your Kubernetes setup and identify the issue"\n  <Uses Task tool to launch devops-automator agent>\n\n- User: "We need to set up monitoring and alerts for our production API"\n  Assistant: "I'm going to use the devops-automator agent to implement a comprehensive monitoring solution with appropriate alerts"\n  <Uses Task tool to launch devops-automator agent>
 color: orange
 tools: Write, Read, MultiEdit, Bash, Grep
 ---

package/templates/departments/engineering/frontend-developer.md

@@ -1,6 +1,6 @@
 ---
 name: frontend-developer
-description: Use this agent when building user interfaces, implementing components, handling state management, or optimizing frontend performance. Excels at creating responsive, accessible, and performant web applications across frameworks.
+description: Use this agent when:\n- Building or modifying user interfaces, components, or layouts\n- Implementing responsive designs or CSS styling\n- Working with frontend frameworks (React, Vue, Angular, Svelte, etc.)\n- Creating interactive features or user interactions\n- Optimizing frontend performance or accessibility\n- Debugging frontend issues or browser compatibility problems\n- Setting up frontend build tools or configurations\n\nExamples:\n- User: "I need to create a responsive navigation bar with a hamburger menu for mobile"\n  Assistant: "I'm going to use the frontend-developer agent to design and implement this navigation component"\n  <Uses Task tool to launch frontend-developer agent>\n\n- User: "The button animations aren't working smoothly on Safari"\n  Assistant: "Let me use the frontend-developer agent to investigate and fix this browser-specific animation issue"\n  <Uses Task tool to launch frontend-developer agent>\n\n- User: "Can you help me implement a dark mode toggle?"\n  Assistant: "I'll use the frontend-developer agent to create a dark mode implementation with proper state management and styling"\n  <Uses Task tool to launch frontend-developer agent>
 color: blue
 tools: Write, Read, MultiEdit, Bash, Grep, Glob
 ---

package/templates/departments/engineering/mobile-app-builder.md

@@ -1,6 +1,6 @@
 ---
 name: mobile-app-builder
-description: Use this agent when developing mobile applications for iOS or Android, implementing native features, or optimizing mobile performance. Specializes in creating smooth, native-feeling mobile experiences across platforms.
+description: Use this agent when:\n- Building iOS, Android, or cross-platform mobile applications\n- Implementing native mobile features (camera, GPS, push notifications, etc.)\n- Optimizing mobile app performance or battery usage\n- Implementing mobile UI/UX patterns and navigation\n- Integrating mobile-specific APIs or SDKs\n- Debugging mobile app issues or platform-specific bugs\n- Setting up mobile app build and deployment configurations\n\nExamples:\n- User: "I need to build a React Native app with offline-first functionality"\n  Assistant: "I'll use the mobile-app-builder agent to create an offline-first mobile app with proper data synchronization"\n  <Uses Task tool to launch mobile-app-builder agent>\n\n- User: "The iOS app is draining battery quickly, can you investigate?"\n  Assistant: "Let me use the mobile-app-builder agent to profile and optimize the battery usage"\n  <Uses Task tool to launch mobile-app-builder agent>\n\n- User: "We need to add push notifications to our Flutter app"\n  Assistant: "I'm going to use the mobile-app-builder agent to implement push notifications with proper platform-specific handling"\n  <Uses Task tool to launch mobile-app-builder agent>
 color: green
 tools: Write, Read, MultiEdit, Bash, Grep
 ---

package/templates/departments/engineering/rapid-prototyper.md

@@ -1,6 +1,6 @@
 ---
 name: rapid-prototyper
-description: Use this agent when you need to quickly create a new application prototype, MVP, or proof-of-concept within the 6-day development cycle. Specializes in scaffolding projects, integrating trending features, and building functional demos rapidly.
+description: Use this agent when:\n- Building a new application prototype or MVP from scratch\n- Creating proof-of-concepts or demos quickly\n- Scaffolding new projects with best practices\n- Integrating trending features or technologies rapidly\n- Experimenting with new frameworks or tools\n- Building quick prototypes to validate ideas\n- Setting up starter templates or boilerplates\n\nExamples:\n- User: "I need to build a landing page with waitlist signup in the next few hours"\n  Assistant: "I'll use the rapid-prototyper agent to quickly scaffold a landing page with email collection and validation"\n  <Uses Task tool to launch rapid-prototyper agent>\n\n- User: "Can you create a proof-of-concept for a real-time chat application?"\n  Assistant: "Let me use the rapid-prototyper agent to build a minimal viable chat app with WebSocket integration"\n  <Uses Task tool to launch rapid-prototyper agent>\n\n- User: "We want to prototype a dashboard to visualize our API data"\n  Assistant: "I'm going to use the rapid-prototyper agent to create a functional dashboard prototype with data visualization"\n  <Uses Task tool to launch rapid-prototyper agent>
 color: green
 tools: Write, MultiEdit, Bash, Read, Glob, Task
 ---

package/templates/departments/engineering/test-writer-fixer.md

@@ -1,6 +1,6 @@
 ---
 name: test-writer-fixer
-description: Use this agent when code changes have been made and you need to write new tests, run existing tests, analyze failures, and fix them while maintaining test integrity. Trigger proactively after code modifications to ensure comprehensive test coverage.
+description: Use this agent when:\n- Code changes have been made and tests need to be written or updated\n- Existing tests are failing and need investigation\n- Test coverage needs to be improved\n- Test suites need refactoring or optimization\n- Debugging test failures or flaky tests\n- Setting up testing frameworks or CI/CD test pipelines\n\nExamples:\n- User: "I just added a new authentication function. Can you write tests for it?"\n  Assistant: "I'll use the test-writer-fixer agent to create comprehensive unit tests for your authentication function"\n  <Uses Task tool to launch test-writer-fixer agent>\n\n- User: "The payment processing tests are failing after my refactor"\n  Assistant: "Let me use the test-writer-fixer agent to analyze the failures and fix the tests while ensuring they still validate the correct behavior"\n  <Uses Task tool to launch test-writer-fixer agent>\n\n- User: "We need to increase test coverage for the user service module"\n  Assistant: "I'm going to use the test-writer-fixer agent to identify gaps and write additional tests for the user service"\n  <Uses Task tool to launch test-writer-fixer agent>
 color: cyan
 tools: Write, Read, MultiEdit, Bash, Grep, Glob
 ---

package/templates/departments/marketing/app-store-optimizer.md

@@ -1,6 +1,6 @@
 ---
 name: app-store-optimizer
-description: Use this agent when preparing app store listings, researching keywords, optimizing app metadata, improving conversion rates, or analyzing app store performance. Specializes in maximizing organic app store visibility and downloads.
+description: Use this agent when:\n- Preparing or optimizing app store listings (iOS, Android)\n- Researching and selecting keywords for ASO\n- Writing compelling app descriptions and titles\n- Optimizing app metadata for better visibility\n- Improving app store conversion rates\n- Analyzing app store performance and competitors\n- A/B testing app store elements\n\nExamples:\n- User: "We're launching our app on the App Store and need the listing optimized"\n  Assistant: "I'll use the app-store-optimizer agent to create a fully optimized listing with keywords and compelling copy"\n  <Uses Task tool to launch app-store-optimizer agent>\n\n- User: "Our app downloads are lower than competitors despite better reviews"\n  Assistant: "Let me use the app-store-optimizer agent to analyze and improve your app store presence"\n  <Uses Task tool to launch app-store-optimizer agent>\n\n- User: "What keywords should we target for our fitness app?"\n  Assistant: "I'm going to use the app-store-optimizer agent to conduct keyword research and optimization"\n  <Uses Task tool to launch app-store-optimizer agent>
 color: teal
 tools: Write, Read, WebSearch, WebFetch, MultiEdit
 ---

package/templates/departments/marketing/content-creator.md

@@ -1,6 +1,6 @@
 ---
 name: content-creator
-description: Use this agent for cross-platform content generation, from long-form blog posts to engaging video scripts and social media content. Specializes in adapting messaging across different formats while maintaining brand consistency.
+description: Use this agent when:\n- Creating blog posts, articles, or long-form content\n- Writing video scripts or podcast outlines\n- Generating social media content across platforms\n- Adapting content for different formats and audiences\n- Creating email newsletters or marketing copy\n- Developing content calendars or strategies\n- Repurposing content across channels\n\nExamples:\n- User: "We need a blog post explaining our new AI feature"\n  Assistant: "I'll use the content-creator agent to write an engaging, informative blog post about the AI feature"\n  <Uses Task tool to launch content-creator agent>\n\n- User: "Can you create social media posts to announce our product launch?"\n  Assistant: "Let me use the content-creator agent to craft platform-specific posts for the launch"\n  <Uses Task tool to launch content-creator agent>\n\n- User: "Turn this technical documentation into customer-friendly content"\n  Assistant: "I'm going to use the content-creator agent to transform the technical docs into accessible content"\n  <Uses Task tool to launch content-creator agent>
 color: blue
 tools: Write, Read, WebSearch, WebFetch, MultiEdit
 ---

package/templates/departments/marketing/growth-hacker.md

@@ -1,6 +1,6 @@
 ---
 name: growth-hacker
-description: Use this agent for rapid user acquisition, viral loop creation, and data-driven growth experiments. Specializes in combining marketing, product, and data analysis skills to identify and exploit growth opportunities.
+description: Use this agent when:\n- Planning rapid user acquisition strategies\n- Creating viral loops or referral systems\n- Designing and analyzing growth experiments\n- Optimizing conversion funnels\n- Implementing growth hacks or tactics\n- Analyzing user acquisition data and metrics\n- Identifying and exploiting growth opportunities\n\nExamples:\n- User: "We need to increase signups by 10x in the next month"\n  Assistant: "I'll use the growth-hacker agent to design a comprehensive growth strategy with multiple tactics"\n  <Uses Task tool to launch growth-hacker agent>\n\n- User: "Can you design a referral program that goes viral?"\n  Assistant: "Let me use the growth-hacker agent to create a viral referral system with strong incentives"\n  <Uses Task tool to launch growth-hacker agent>\n\n- User: "Our signup conversion rate is too low"\n  Assistant: "I'm going to use the growth-hacker agent to analyze and optimize the conversion funnel"\n  <Uses Task tool to launch growth-hacker agent>
 color: green
 tools: Write, Read, WebSearch, WebFetch, Bash, MultiEdit
 ---

package/templates/departments/marketing/instagram-curator.md

@@ -1,6 +1,6 @@
 ---
 name: instagram-curator
-description: Use this agent for visual content strategy, Stories, Reels, and Instagram growth tactics. Specializes in understanding the platform's algorithm, visual aesthetics, and engagement patterns to create compelling content strategies.
+description: Use this agent when:\n- Creating Instagram content strategy (posts, Stories, Reels)\n- Planning visual content calendars for Instagram\n- Optimizing for Instagram's algorithm and engagement\n- Developing Instagram growth tactics and campaigns\n- Creating caption copy and hashtag strategies\n- Analyzing Instagram performance and insights\n- Planning Instagram collaborations or influencer partnerships\n\nExamples:\n- User: "We need a month's worth of Instagram content for our brand"\n  Assistant: "I'll use the instagram-curator agent to create a comprehensive content calendar with posts, Stories, and Reels"\n  <Uses Task tool to launch instagram-curator agent>\n\n- User: "Our Instagram engagement has dropped significantly"\n  Assistant: "Let me use the instagram-curator agent to analyze and optimize your Instagram strategy"\n  <Uses Task tool to launch instagram-curator agent>\n\n- User: "What Reels content would work for our fitness app?"\n  Assistant: "I'm going to use the instagram-curator agent to develop viral Reels ideas aligned with fitness trends"\n  <Uses Task tool to launch instagram-curator agent>
 color: purple
 tools: Write, Read, WebSearch, WebFetch, MultiEdit
 ---

package/templates/departments/marketing/reddit-community-builder.md

@@ -1,6 +1,6 @@
 ---
 name: reddit-community-builder
-description: Use this agent for authentic community engagement, organic growth through valuable participation, and navigating Reddit's unique culture. Specializes in providing value first, building genuine relationships, and respecting community norms.
+description: Use this agent when:\n- Building authentic engagement on Reddit communities\n- Creating Reddit marketing strategies that respect community norms\n- Writing Reddit posts or comments that provide value\n- Identifying relevant subreddits for your product\n- Planning Reddit AMAs or community events\n- Responding to Reddit feedback or discussions\n- Growing organic presence on Reddit\n\nExamples:\n- User: "We want to promote our developer tool on Reddit without being spammy"\n  Assistant: "I'll use the reddit-community-builder agent to create a value-first Reddit strategy"\n  <Uses Task tool to launch reddit-community-builder agent>\n\n- User: "How should we respond to this Reddit thread about our product?"\n  Assistant: "Let me use the reddit-community-builder agent to craft an authentic, helpful response"\n  <Uses Task tool to launch reddit-community-builder agent>\n\n- User: "We want to launch on Product Hunt and Reddit simultaneously"\n  Assistant: "I'm going to use the reddit-community-builder agent to plan a Reddit launch strategy"\n  <Uses Task tool to launch reddit-community-builder agent>
 color: orange
 tools: Write, Read, WebSearch, WebFetch, MultiEdit
 ---

package/templates/departments/marketing/tiktok-strategist.md

@@ -1,6 +1,6 @@
 ---
 name: tiktok-strategist
-description: Use this agent for creating TikTok marketing strategies, developing viral content ideas, planning TikTok campaigns, or optimizing for TikTok's algorithm. Specializes in creating shareable moments and leveraging TikTok trends for app growth.
+description: Use this agent when:\n- Creating TikTok marketing strategies and campaigns\n- Developing viral TikTok content ideas\n- Planning TikTok video scripts or concepts\n- Optimizing for TikTok's algorithm and For You Page\n- Leveraging TikTok trends for brand awareness\n- Analyzing TikTok performance and opportunities\n- Planning TikTok influencer partnerships\n\nExamples:\n- User: "We want to launch our app on TikTok with viral content"\n  Assistant: "I'll use the tiktok-strategist agent to create a viral TikTok launch strategy with trend-aligned content"\n  <Uses Task tool to launch tiktok-strategist agent>\n\n- User: "What TikTok content would resonate with Gen Z for our productivity app?"\n  Assistant: "Let me use the tiktok-strategist agent to develop Gen Z-friendly TikTok content ideas"\n  <Uses Task tool to launch tiktok-strategist agent>\n\n- User: "How can we leverage current TikTok trends for our brand?"\n  Assistant: "I'm going to use the tiktok-strategist agent to identify and adapt trending formats"\n  <Uses Task tool to launch tiktok-strategist agent>
 color: pink
 tools: Write, Read, WebSearch, WebFetch
 ---

package/templates/departments/marketing/twitter-engager.md

@@ -1,6 +1,6 @@
 ---
 name: twitter-engager
-description: Use this agent for real-time social media engagement, trending topic leverage, and viral tweet creation. Specializes in concise communication, thread storytelling, and community building through strategic engagement on Twitter/X.
+description: Use this agent when:\n- Crafting tweets or Twitter/X threads\n- Real-time engagement with trending topics\n- Building community through Twitter interactions\n- Creating viral tweet strategies\n- Responding to mentions or customer feedback on Twitter\n- Planning Twitter campaigns or content calendars\n- Analyzing Twitter performance and opportunities\n\nExamples:\n- User: "We need to announce our product launch on Twitter with maximum impact"\n  Assistant: "I'll use the twitter-engager agent to create a viral-optimized launch thread"\n  <Uses Task tool to launch twitter-engager agent>\n\n- User: "There's a trending topic related to our industry, how should we engage?"\n  Assistant: "Let me use the twitter-engager agent to craft timely, relevant tweets for the trend"\n  <Uses Task tool to launch twitter-engager agent>\n\n- User: "How can we grow our Twitter following organically?"\n  Assistant: "I'm going to use the twitter-engager agent to develop an engagement-first growth strategy"\n  <Uses Task tool to launch twitter-engager agent>
 color: cyan
 tools: Write, Read, WebSearch, WebFetch, MultiEdit
 ---

package/templates/departments/product/feedback-synthesizer.md

@@ -1,6 +1,6 @@
 ---
 name: feedback-synthesizer
-description: Use this agent when analyzing user feedback from multiple sources, identifying patterns in user complaints or requests, synthesizing insights from reviews, or prioritizing feature development based on user input. Excels at turning raw feedback into actionable product insights.
+description: Use this agent when:\n- Analyzing user feedback from multiple sources\n- Identifying patterns in user complaints or feature requests\n- Synthesizing insights from app reviews or customer support\n- Prioritizing product improvements based on user input\n- Creating feedback reports or user insight summaries\n- Extracting actionable insights from qualitative data\n- Validating product hypotheses with user feedback\n\nExamples:\n- User: "We have hundreds of app reviews, what are users actually asking for?"\n  Assistant: "I'll use the feedback-synthesizer agent to analyze and categorize the feedback into actionable themes"\n  <Uses Task tool to launch feedback-synthesizer agent>\n\n- User: "Should we prioritize dark mode or offline support based on user feedback?"\n  Assistant: "Let me use the feedback-synthesizer agent to analyze user feedback and recommend priorities"\n  <Uses Task tool to launch feedback-synthesizer agent>\n\n- User: "Synthesize this month's customer support tickets into product insights"\n  Assistant: "I'm going to use the feedback-synthesizer agent to extract patterns and actionable insights"\n  <Uses Task tool to launch feedback-synthesizer agent>
 color: orange
 tools: Read, Write, Grep, WebFetch, MultiEdit
 ---

package/templates/departments/product/sprint-prioritizer.md

@@ -1,6 +1,6 @@
 ---
 name: sprint-prioritizer
-description: Use this agent when planning 6-day development cycles, prioritizing features, managing product roadmaps, or making trade-off decisions. Specializes in maximizing value delivery within tight timelines.
+description: Use this agent when:\n- Planning development sprints or cycles\n- Prioritizing features or product backlog items\n- Making trade-off decisions between competing priorities\n- Managing product roadmaps or timelines\n- Evaluating feature value vs. effort\n- Breaking down large initiatives into sprint-sized work\n- Resolving prioritization conflicts\n\nExamples:\n- User: "We have 20 feature requests but only capacity for 3 this sprint"\n  Assistant: "I'll use the sprint-prioritizer agent to evaluate and recommend the highest-impact features"\n  <Uses Task tool to launch sprint-prioritizer agent>\n\n- User: "Should we focus on new features or tech debt this month?"\n  Assistant: "Let me use the sprint-prioritizer agent to analyze the trade-offs and recommend a balanced approach"\n  <Uses Task tool to launch sprint-prioritizer agent>\n\n- User: "Help me plan our product roadmap for Q1"\n  Assistant: "I'm going to use the sprint-prioritizer agent to create a prioritized roadmap with sprint breakdown"\n  <Uses Task tool to launch sprint-prioritizer agent>
 color: indigo
 tools: Write, Read, TodoWrite, Grep
 ---

package/templates/departments/product/trend-researcher.md

@@ -1,6 +1,6 @@
 ---
 name: trend-researcher
-description: Use this agent when identifying market opportunities, analyzing trending topics, researching viral content, or understanding emerging user behaviors. Specializes in finding product opportunities from TikTok trends, App Store patterns, and social media virality.
+description: Use this agent when:\n- Identifying market opportunities or emerging trends\n- Analyzing trending topics in your industry\n- Researching viral content or successful products\n- Understanding emerging user behaviors or preferences\n- Discovering product opportunities from social media trends\n- Analyzing App Store or Play Store trending apps\n- Competitive trend analysis\n\nExamples:\n- User: "What are the trending features in productivity apps right now?"\n  Assistant: "I'll use the trend-researcher agent to analyze current productivity app trends and opportunities"\n  <Uses Task tool to launch trend-researcher agent>\n\n- User: "Are there any TikTok trends we could turn into product features?"\n  Assistant: "Let me use the trend-researcher agent to identify viral TikTok trends relevant to our product"\n  <Uses Task tool to launch trend-researcher agent>\n\n- User: "What's trending in the fintech space that we should know about?"\n  Assistant: "I'm going to use the trend-researcher agent to research emerging fintech trends and opportunities"\n  <Uses Task tool to launch trend-researcher agent>
 color: purple
 tools: WebSearch, WebFetch, Read, Write, Grep
 ---

package/templates/departments/project-management/experiment-tracker.md

@@ -1,6 +1,6 @@
 ---
 name: experiment-tracker
-description: PROACTIVELY use this agent when experiments are started, modified, or when results need analysis. Specializes in tracking A/B tests, feature experiments, and iterative improvements within the 6-day development cycle. Trigger automatically when experimental code paths or feature flags are introduced.
+description: Use this agent when:\n- Setting up A/B tests or feature experiments\n- Tracking ongoing experiments and their results\n- Analyzing experiment data and drawing conclusions\n- Managing feature flags or experimental code paths\n- Documenting experiment hypotheses and outcomes\n- Deciding whether to ship or kill experiments\n- Coordinating experiment timelines and milestones\n\nExamples:\n- User: "We want to A/B test two different onboarding flows"\n  Assistant: "I'll use the experiment-tracker agent to set up and track the onboarding A/B test"\n  <Uses Task tool to launch experiment-tracker agent>\n\n- User: "What were the results of last week's pricing experiment?"\n  Assistant: "Let me use the experiment-tracker agent to analyze and summarize the pricing experiment results"\n  <Uses Task tool to launch experiment-tracker agent>\n\n- User: "We have 5 experiments running, which ones should we ship?"\n  Assistant: "I'm going to use the experiment-tracker agent to evaluate all experiments and recommend decisions"\n  <Uses Task tool to launch experiment-tracker agent>
 color: blue
 tools: Read, Write, MultiEdit, Grep, Glob, TodoWrite
 ---

package/templates/departments/project-management/project-shipper.md

@@ -1,6 +1,6 @@
 ---
 name: project-shipper
-description: PROACTIVELY use this agent when approaching launch milestones, release deadlines, or go-to-market activities. Specializes in coordinating launches, managing release processes, and executing go-to-market strategies within 6-day development cycles. Trigger automatically when release dates are set or launch plans are needed.
+description: Use this agent when:\n- Planning product launches or releases\n- Coordinating go-to-market strategies\n- Managing release checklists and timelines\n- Preparing launch communications and materials\n- Coordinating cross-functional launch activities\n- Tracking launch readiness and blockers\n- Post-launch monitoring and iteration\n\nExamples:\n- User: "We're launching our new feature next week, help me coordinate"\n  Assistant: "I'll use the project-shipper agent to create a comprehensive launch plan and checklist"\n  <Uses Task tool to launch project-shipper agent>\n\n- User: "What do we need to do before we can ship this release?"\n  Assistant: "Let me use the project-shipper agent to identify all pre-launch requirements and blockers"\n  <Uses Task tool to launch project-shipper agent>\n\n- User: "Create a go-to-market plan for our Product Hunt launch"\n  Assistant: "I'm going to use the project-shipper agent to develop a complete GTM strategy"\n  <Uses Task tool to launch project-shipper agent>
 color: purple
 tools: Read, Write, MultiEdit, Grep, Glob, TodoWrite, WebSearch
 ---

package/templates/departments/project-management/studio-producer.md

@@ -1,6 +1,6 @@
 ---
 name: studio-producer
-description: PROACTIVELY use this agent when coordinating across multiple teams, allocating resources, or optimizing studio workflows. Specializes in cross-functional coordination, resource management, and process optimization within 6-day development cycles. Trigger automatically when team dependencies arise or resource conflicts occur.
+description: Use this agent when:\n- Coordinating work across multiple teams or disciplines\n- Managing resource allocation and capacity planning\n- Resolving team dependencies or blockers\n- Optimizing development workflows or processes\n- Facilitating cross-functional collaboration\n- Managing team communication and alignment\n- Identifying and addressing resource conflicts\n\nExamples:\n- User: "Design and engineering are blocked waiting on each other"\n  Assistant: "I'll use the studio-producer agent to identify and resolve the cross-team dependency"\n  <Uses Task tool to launch studio-producer agent>\n\n- User: "We have 3 projects but only 2 developers, help me allocate resources"\n  Assistant: "Let me use the studio-producer agent to optimize resource allocation across projects"\n  <Uses Task tool to launch studio-producer agent>\n\n- User: "Our sprint process feels inefficient, can you help streamline it?"\n  Assistant: "I'm going to use the studio-producer agent to analyze and optimize your workflow"\n  <Uses Task tool to launch studio-producer agent>
 color: green
 tools: Read, Write, MultiEdit, Grep, Glob, TodoWrite
 ---

package/templates/departments/studio-operations/analytics-reporter.md

@@ -1,6 +1,6 @@
 ---
 name: analytics-reporter
-description: Use this agent when analyzing metrics, generating insights from data, creating performance reports, or making data-driven recommendations. Excels at transforming raw analytics into actionable intelligence that drives studio growth and optimization.
+description: Use this agent when:\n- Analyzing product or business metrics\n- Creating performance reports or dashboards\n- Generating insights from analytics data\n- Making data-driven recommendations\n- Tracking KPIs and goals\n- Identifying trends or anomalies in data\n- Setting up analytics tracking or instrumentation\n\nExamples:\n- User: "What's our user retention looking like this month?"\n  Assistant: "I'll use the analytics-reporter agent to analyze retention metrics and identify trends"\n  <Uses Task tool to launch analytics-reporter agent>\n\n- User: "Create a report on our conversion funnel performance"\n  Assistant: "Let me use the analytics-reporter agent to generate a comprehensive funnel analysis report"\n  <Uses Task tool to launch analytics-reporter agent>\n\n- User: "Why did our engagement suddenly drop last week?"\n  Assistant: "I'm going to use the analytics-reporter agent to investigate the engagement drop"\n  <Uses Task tool to launch analytics-reporter agent>
 color: blue
 tools: Write, Read, MultiEdit, WebSearch, Grep
 ---

package/templates/departments/studio-operations/finance-tracker.md

@@ -1,6 +1,6 @@
 ---
 name: finance-tracker
-description: Use this agent when managing budgets, optimizing costs, forecasting revenue, or analyzing financial performance. Excels at transforming financial chaos into strategic clarity, ensuring studio resources generate maximum return.
+description: Use this agent when:\n- Managing budgets or financial planning\n- Optimizing costs or reducing expenses\n- Forecasting revenue or financial projections\n- Analyzing financial performance or metrics\n- Tracking expenses or spending patterns\n- Evaluating pricing strategies or models\n- Creating financial reports or statements\n\nExamples:\n- User: "Our cloud costs are getting too high, where can we optimize?"\n  Assistant: "I'll use the finance-tracker agent to analyze cloud spending and identify optimization opportunities"\n  <Uses Task tool to launch finance-tracker agent>\n\n- User: "Create a budget forecast for next quarter"\n  Assistant: "Let me use the finance-tracker agent to develop a comprehensive budget forecast"\n  <Uses Task tool to launch finance-tracker agent>\n\n- User: "Should we change our pricing model to increase revenue?"\n  Assistant: "I'm going to use the finance-tracker agent to analyze pricing options and revenue impact"\n  <Uses Task tool to launch finance-tracker agent>
 color: orange
 tools: Write, Read, MultiEdit, WebSearch, Grep
 ---

package/templates/departments/studio-operations/infrastructure-maintainer.md

@@ -1,6 +1,6 @@
 ---
 name: infrastructure-maintainer
-description: Use this agent when monitoring system health, optimizing performance, managing scaling, or ensuring infrastructure reliability. Excels at keeping studio applications running smoothly while preparing for growth and preventing disasters.
+description: Use this agent when:\n- Monitoring system health or uptime\n- Optimizing infrastructure performance or costs\n- Managing scaling or capacity planning\n- Ensuring infrastructure reliability and redundancy\n- Investigating outages or performance issues\n- Planning infrastructure upgrades or migrations\n- Implementing disaster recovery or backup strategies\n\nExamples:\n- User: "Our API response times have been degrading, can you investigate?"\n  Assistant: "I'll use the infrastructure-maintainer agent to diagnose and resolve the performance issue"\n  <Uses Task tool to launch infrastructure-maintainer agent>\n\n- User: "We're expecting 10x traffic next week, is our infrastructure ready?"\n  Assistant: "Let me use the infrastructure-maintainer agent to assess and prepare for the traffic spike"\n  <Uses Task tool to launch infrastructure-maintainer agent>\n\n- User: "Set up monitoring and alerting for our production systems"\n  Assistant: "I'm going to use the infrastructure-maintainer agent to implement comprehensive monitoring"\n  <Uses Task tool to launch infrastructure-maintainer agent>
 color: purple
 tools: Write, Read, MultiEdit, WebSearch, Grep, Bash
 ---

package/templates/departments/studio-operations/legal-compliance-checker.md

@@ -1,6 +1,6 @@
 ---
 name: legal-compliance-checker
-description: Use this agent when reviewing terms of service, privacy policies, ensuring regulatory compliance, or handling legal requirements. Excels at navigating the complex legal landscape while maintaining user trust and avoiding costly violations.
+description: Use this agent when:\n- Reviewing or drafting terms of service or privacy policies\n- Ensuring regulatory compliance (GDPR, CCPA, etc.)\n- Handling legal requirements or obligations\n- Reviewing user data handling practices\n- Creating compliance documentation\n- Assessing legal risks or exposure\n- Implementing compliance requirements in code\n\nExamples:\n- User: "Do we need to update our privacy policy for GDPR compliance?"\n  Assistant: "I'll use the legal-compliance-checker agent to review your privacy policy against GDPR requirements"\n  <Uses Task tool to launch legal-compliance-checker agent>\n\n- User: "Draft terms of service for our new SaaS platform"\n  Assistant: "Let me use the legal-compliance-checker agent to create comprehensive, compliant terms of service"\n  <Uses Task tool to launch legal-compliance-checker agent>\n\n- User: "We're adding user data export, what are the legal requirements?"\n  Assistant: "I'm going to use the legal-compliance-checker agent to identify data export compliance requirements"\n  <Uses Task tool to launch legal-compliance-checker agent>
 color: red
 tools: Write, Read, MultiEdit, WebSearch, Grep
 ---

package/templates/departments/studio-operations/support-responder.md

@@ -1,6 +1,6 @@
 ---
 name: support-responder
-description: Use this agent when handling customer support inquiries, creating support documentation, setting up automated responses, or analyzing support patterns. Excels at maintaining high-quality support while identifying product improvement opportunities.
+description: Use this agent when:\n- Handling customer support inquiries or tickets\n- Creating support documentation or FAQs\n- Setting up automated responses or chatbots\n- Analyzing support patterns or common issues\n- Training support teams or creating scripts\n- Improving support processes or workflows\n- Escalating critical support issues\n\nExamples:\n- User: "Draft a response to this customer complaint about slow performance"\n  Assistant: "I'll use the support-responder agent to craft an empathetic, helpful response"\n  <Uses Task tool to launch support-responder agent>\n\n- User: "Create an FAQ section for our most common support questions"\n  Assistant: "Let me use the support-responder agent to analyze tickets and create comprehensive FAQs"\n  <Uses Task tool to launch support-responder agent>\n\n- User: "What are the top 5 issues our users are reporting?"\n  Assistant: "I'm going to use the support-responder agent to analyze and categorize support tickets"\n  <Uses Task tool to launch support-responder agent>
 color: green
 tools: Write, Read, MultiEdit, WebSearch, Grep
 ---

package/templates/departments/testing/api-tester.md

@@ -1,6 +1,6 @@
 ---
 name: api-tester
-description: Use this agent for comprehensive API testing including performance testing, load testing, and contract testing. Specializes in ensuring APIs are robust, performant, and meet specifications before deployment.
+description: Use this agent when:\n- Testing API endpoints or services\n- Performing load or performance testing on APIs\n- Validating API contracts or specifications\n- Testing API authentication or authorization\n- Creating API test suites or automation\n- Debugging API issues or errors\n- Generating API testing documentation\n\nExamples:\n- User: "Test our REST API endpoints for the user service"\n  Assistant: "I'll use the api-tester agent to create comprehensive tests for all user service endpoints"\n  <Uses Task tool to launch api-tester agent>\n\n- User: "Can our API handle 1000 requests per second?"\n  Assistant: "Let me use the api-tester agent to run load tests and identify performance limits"\n  <Uses Task tool to launch api-tester agent>\n\n- User: "The authentication endpoint is returning 500 errors"\n  Assistant: "I'm going to use the api-tester agent to diagnose and test the authentication issue"\n  <Uses Task tool to launch api-tester agent>
 color: orange
 tools: Bash, Read, Write, Grep, WebFetch, MultiEdit
 ---

package/templates/departments/testing/performance-benchmarker.md

@@ -1,6 +1,6 @@
 ---
 name: performance-benchmarker
-description: Use this agent for comprehensive performance testing, profiling, and optimization recommendations. Specializes in measuring speed, identifying bottlenecks, and providing actionable optimization strategies.
+description: Use this agent when:\n- Running performance tests or benchmarks\n- Profiling code or application performance\n- Identifying performance bottlenecks\n- Comparing performance across changes or versions\n- Optimizing slow code or queries\n- Setting performance baselines or targets\n- Creating performance reports or metrics\n\nExamples:\n- User: "Benchmark our database queries to find slow ones"\n  Assistant: "I'll use the performance-benchmarker agent to profile and benchmark all database queries"\n  <Uses Task tool to launch performance-benchmarker agent>\n\n- User: "Did my optimization actually make things faster?"\n  Assistant: "Let me use the performance-benchmarker agent to compare before and after performance"\n  <Uses Task tool to launch performance-benchmarker agent>\n\n- User: "The homepage is loading slowly, where's the bottleneck?"\n  Assistant: "I'm going to use the performance-benchmarker agent to profile and identify the bottleneck"\n  <Uses Task tool to launch performance-benchmarker agent>
 color: red
 tools: Bash, Read, Write, Grep, MultiEdit, WebFetch
 ---

package/templates/departments/testing/test-results-analyzer.md

@@ -1,6 +1,6 @@
 ---
 name: test-results-analyzer
-description: Use this agent for analyzing test results, synthesizing test data, identifying trends, and generating quality metrics reports. Specializes in turning raw test data into actionable insights that drive quality improvements.
+description: Use this agent when:\n- Analyzing test results or test run data\n- Synthesizing test data into insights\n- Identifying patterns in test failures\n- Generating quality metrics or reports\n- Tracking test coverage over time\n- Comparing test results across versions\n- Creating test quality dashboards\n\nExamples:\n- User: "Why are our tests suddenly failing more often?"\n  Assistant: "I'll use the test-results-analyzer agent to analyze test trends and identify the cause"\n  <Uses Task tool to launch test-results-analyzer agent>\n\n- User: "Create a test quality report for this sprint"\n  Assistant: "Let me use the test-results-analyzer agent to generate a comprehensive quality report"\n  <Uses Task tool to launch test-results-analyzer agent>\n\n- User: "Which parts of our codebase have the weakest test coverage?"\n  Assistant: "I'm going to use the test-results-analyzer agent to analyze coverage and identify gaps"\n  <Uses Task tool to launch test-results-analyzer agent>
 color: yellow
 tools: Read, Write, Grep, Bash, MultiEdit, TodoWrite
 ---

package/templates/departments/testing/tool-evaluator.md

@@ -1,6 +1,6 @@
 ---
 name: tool-evaluator
-description: Use this agent when evaluating new development tools, frameworks, or services. Specializes in rapid tool assessment, comparative analysis, and making recommendations that align with the 6-day development cycle philosophy.
+description: Use this agent when:\n- Evaluating new development tools or frameworks\n- Comparing tools or libraries for a specific need\n- Assessing tool fit for your tech stack\n- Creating tool evaluation reports\n- Making build vs. buy decisions\n- Researching tool alternatives or replacements\n- Validating tool performance or reliability\n\nExamples:\n- User: "Should we use Jest or Vitest for our testing framework?"\n  Assistant: "I'll use the tool-evaluator agent to compare Jest and Vitest for your specific use case"\n  <Uses Task tool to launch tool-evaluator agent>\n\n- User: "Evaluate whether we should build our own auth or use Auth0"\n  Assistant: "Let me use the tool-evaluator agent to analyze the build vs. buy tradeoffs"\n  <Uses Task tool to launch tool-evaluator agent>\n\n- User: "What are the best monitoring tools for Node.js applications?"\n  Assistant: "I'm going to use the tool-evaluator agent to research and compare monitoring solutions"\n  <Uses Task tool to launch tool-evaluator agent>
 color: purple
 tools: WebSearch, WebFetch, Write, Read, Bash
 ---

package/templates/departments/testing/workflow-optimizer.md

@@ -1,6 +1,6 @@
 ---
 name: workflow-optimizer
-description: Use this agent for optimizing human-agent collaboration workflows and analyzing workflow efficiency. Specializes in identifying bottlenecks, streamlining processes, and ensuring smooth handoffs between human creativity and AI assistance.
+description: Use this agent when:\n- Optimizing development workflows or processes\n- Analyzing workflow efficiency and bottlenecks\n- Improving human-AI collaboration patterns\n- Streamlining repetitive tasks or processes\n- Creating workflow automation scripts\n- Evaluating and improving team processes\n- Designing efficient development pipelines\n\nExamples:\n- User: "Our code review process is taking too long, can you optimize it?"\n  Assistant: "I'll use the workflow-optimizer agent to analyze and streamline your code review workflow"\n  <Uses Task tool to launch workflow-optimizer agent>\n\n- User: "We're spending too much time on manual deployments"\n  Assistant: "Let me use the workflow-optimizer agent to design an automated deployment workflow"\n  <Uses Task tool to launch workflow-optimizer agent>\n\n- User: "How can we better collaborate between designers and developers?"\n  Assistant: "I'm going to use the workflow-optimizer agent to optimize your design-to-development handoff"\n  <Uses Task tool to launch workflow-optimizer agent>
 color: teal
 tools: Read, Write, Bash, TodoWrite, MultiEdit, Grep
 ---