@iservu-inc/adf-cli 0.4.15 → 0.4.26

package/.project/docs/tool-integrations/IDE-CUSTOMIZATIONS.md

@@ -442,6 +442,407 @@ export function registerTools(context: vscode.ExtensionContext) {
 
 ---
 
+## 4. Custom Agent/Persona Configuration
+
+### Overview
+
+All major AI coding assistants support custom agents/personas that can be triggered with specific commands or mentions. This allows you to create specialized AI behaviors for different development tasks (e.g., PM, Architect, Developer, QA).
+
+**Key Pattern:** All agents share the same YAML configuration block but are activated differently per IDE:
+- **Windsurf:** `/.workflows/{agent}.md` - Auto-execution modes
+- **Cursor:** `@{agent}` via `.cursor/rules/{folder}/{agent}.mdc`
+- **GitHub Copilot:** Chat modes via `.github/chatmodes/{agent}.chatmode.md`
+- **Claude Code:** `/{agent}` via `.claude/commands/{folder}/agents/{agent}.md`
+- **Trae:** `@{agent}` via `.trae/rules/{agent}.md`
+
+---
+
+### Windsurf Custom Workflows
+
+**Directory:** `.windsurf/workflows/`
+
+**File Format:** `{agent-name}.md`
+
+**Structure:**
+```markdown
+---
+description: {agent-name}
+auto_execution_mode: 3
+---
+
+<!-- Powered by BMAD™ Core -->
+
+# {Agent Display Name}
+
+ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below.
+
+CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
+
+## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED
+
+```yaml
+activation-instructions:
+  - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
+  - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
+  - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
+  - DO NOT: Load any other agent files during activation
+  - ONLY load dependency files when user selects them for execution via command or request of a task
+  - The agent.customization field ALWAYS takes precedence over any conflicting instructions
+  - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
+  - STAY IN CHARACTER!
+  - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands.
+agent:
+  name: {Agent Name}
+  id: {agent-id}
+  title: {Agent Title}
+  icon: {emoji}
+  whenToUse: {Description of when to use this agent}
+persona:
+  role: {Role description}
+  style: {Communication style}
+  identity: {Identity description}
+  focus: {Primary focus}
+  core_principles:
+    - {Principle 1}
+    - {Principle 2}
+commands:
+  - help: Show numbered list of the following commands to allow selection
+  - {command-name}: {Command description}
+  - exit: Exit (confirm)
+dependencies:
+  checklists:
+    - {checklist-file.md}
+  tasks:
+    - {task-file.md}
+  templates:
+    - {template-file.yaml}
+```
+\```
+
+**Activation:** User runs `/{agent-name}` in Cascade chat
+
+**Example:** `/.workflows/pm.md` → Activated with `/pm`
+
+---
+
+### Cursor Custom Rules
+
+**Directory:** `.cursor/rules/{folder}/`
+
+**File Format:** `{agent-name}.mdc`
+
+**Structure:**
+```markdown
+---
+description:
+globs: []
+alwaysApply: false
+---
+
+# {Agent Name} Agent Rule
+
+This rule is triggered when the user types `@{agent-name}` and activates the {Agent Title} agent persona.
+
+## Agent Activation
+
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+
+```yaml
+[Same YAML configuration as Windsurf]
+```
+\```
+
+## File Reference
+
+The complete agent definition is available in [.bmad-core/agents/{agent}.md](mdc:.bmad-core/agents/{agent}.md).
+
+## Usage
+
+When the user types `@{agent-name}`, activate this {Agent Title} persona and follow all instructions defined in the YAML configuration above.
+```
+
+**Activation:** User types `@{agent-name}` in Composer/Chat
+
+**Example:** `.cursor/rules/bmad/pm.mdc` → Activated with `@pm`
+
+---
+
+### GitHub Copilot Chat Modes
+
+**Directory:** `.github/chatmodes/`
+
+**File Format:** `{agent-name}.chatmode.md`
+
+**Structure:**
+```markdown
+---
+description: "Activates the {Agent Title} agent persona."
+tools: ['changes', 'codebase', 'fetch', 'findTestFiles', 'githubRepo', 'problems', 'usages', 'editFiles', 'runCommands', 'runTasks', 'runTests', 'search', 'searchResults', 'terminalLastCommand', 'terminalSelection', 'testFailure']
+---
+
+<!-- Powered by BMAD™ Core -->
+
+# {agent-name}
+
+ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below.
+
+CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
+
+## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED
+
+```yaml
+[Same YAML configuration as Windsurf]
+```
+\```
+```
+
+**Activation:** Copilot detects `.chatmode.md` files and presents them as selectable chat modes
+
+**Example:** `.github/chatmodes/pm.chatmode.md` → Selectable chat mode in Copilot
+
+---
+
+### Claude Code Slash Commands
+
+**Directory:** `.claude/commands/{folder}/agents/`
+
+**File Format:** `{agent-name}.md`
+
+**Structure:**
+```markdown
+# /{agent-name} Command
+
+When this command is used, adopt the following agent persona:
+
+<!-- Powered by BMAD™ Core -->
+
+# {agent-name}
+
+ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below.
+
+CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
+
+## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED
+
+```yaml
+[Same YAML configuration as Windsurf]
+```
+\```
+```
+
+**Activation:** User runs `/{agent-name}` in Claude Code chat
+
+**Example:** `.claude/commands/BMad/agents/pm.md` → Activated with `/pm`
+
+**Settings File:** `.claude/settings.local.json` can reference command directories
+
+---
+
+### Trae Custom Rules
+
+**Directory:** `.trae/rules/`
+
+**File Format:** `{agent-name}.md`
+
+**Structure:**
+```markdown
+# {Agent Name} Agent Rule
+
+This rule is triggered when the user types `@{agent-name}` and activates the {Agent Title} agent persona.
+
+## Agent Activation
+
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+
+```yaml
+[Same YAML configuration as Windsurf]
+```
+\```
+
+## File Reference
+
+The complete agent definition is available in [.bmad-core/agents/{agent}.md](.bmad-core/agents/{agent}.md).
+
+## Usage
+
+When the user types `@{agent-name}`, activate this {Agent Title} persona and follow all instructions defined in the YAML configuration above.
+```
+
+**Activation:** User types `@{agent-name}` in Trae chat
+
+**Example:** `.trae/rules/pm.md` → Activated with `@pm`
+
+---
+
+### VSCode Configuration
+
+**Directory:** `.vscode/`
+
+**File Format:** `settings.json`
+
+**Structure:**
+```json
+{
+  "chat.agent.enabled": true,
+  "chat.agent.maxRequests": 15,
+  "github.copilot.chat.agent.runTasks": true,
+  "github.copilot.chat.agent.autoFix": true,
+  "chat.tools.autoApprove": false
+}
+```
+
+**Note:** VSCode agent configuration primarily leverages GitHub Copilot chatmodes (see above) or Claude Code slash commands.
+
+---
+
+### Shared Agent YAML Schema
+
+All agents use this core YAML structure:
+
+```yaml
+IDE-FILE-RESOLUTION:
+  - FOR LATER USE ONLY - NOT FOR ACTIVATION, when executing commands that reference dependencies
+  - Dependencies map to .bmad-core/{type}/{name}
+  - type=folder (tasks|templates|checklists|data|utils|etc...), name=file-name
+  - Example: create-doc.md → .bmad-core/tasks/create-doc.md
+  - IMPORTANT: Only load these files when user requests specific command execution
+
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
+
+activation-instructions:
+  - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
+  - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
+  - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
+  - DO NOT: Load any other agent files during activation
+  - ONLY load dependency files when user selects them for execution via command or request of a task
+  - The agent.customization field ALWAYS takes precedence over any conflicting instructions
+  - CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written - they are executable workflows, not reference material
+  - MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format - never skip elicitation for efficiency
+  - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
+  - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
+  - STAY IN CHARACTER!
+  - CRITICAL: On activation, ONLY greet user, auto-run `*help`, and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
+
+agent:
+  name: {Human-readable name}
+  id: {lowercase-id}
+  title: {Professional Title}
+  icon: {emoji}
+  whenToUse: {When to use this agent}
+
+persona:
+  role: {Role description}
+  style: {Communication style traits}
+  identity: {What this agent is}
+  focus: {Primary focus area}
+  core_principles:
+    - {Principle 1}
+    - {Principle 2}
+    - ...
+
+# All commands require * prefix when used (e.g., *help)
+commands:
+  - help: Show numbered list of the following commands to allow selection
+  - {command-1}: {Description}
+  - {command-2}: {Description}
+  - yolo: Toggle Yolo Mode
+  - exit: Exit (confirm)
+
+dependencies:
+  checklists:
+    - {checklist-file.md}
+  data:
+    - {data-file.md}
+  tasks:
+    - {task-file.md}
+  templates:
+    - {template-file.yaml}
+  utils:
+    - {util-file.md}
+```
+
+**Key Principles:**
+1. **Self-contained:** All agent config in YAML block, no external loads on activation
+2. **Lazy loading:** Dependencies loaded only when commands execute
+3. **Consistent interface:** All agents use `*help` and numbered menus
+4. **Task execution:** Tasks from dependencies are executable workflows, not reference
+5. **Interactive modes:** Tasks with `elicit=true` require user interaction
+
+---
+
+### Agent Activation Comparison
+
+| IDE | Directory | File Extension | Activation | Frontmatter |
+|-----|-----------|----------------|------------|-------------|
+| **Windsurf** | `.windsurf/workflows/` | `.md` | `/{agent}` | YAML: `description`, `auto_execution_mode` |
+| **Cursor** | `.cursor/rules/{folder}/` | `.mdc` | `@{agent}` | YAML: `description`, `globs`, `alwaysApply` |
+| **GitHub Copilot** | `.github/chatmodes/` | `.chatmode.md` | Chat mode selector | YAML: `description`, `tools` array |
+| **Claude Code** | `.claude/commands/{folder}/agents/` | `.md` | `/{agent}` | None (markdown header) |
+| **Trae** | `.trae/rules/` | `.md` | `@{agent}` | None (markdown header) |
+| **VSCode** | Uses Copilot or Claude | - | - | - |
+
+---
+
+### Creating New Custom Agents
+
+**Step 1: Define Agent Properties**
+```yaml
+agent:
+  name: "Sarah"              # Human name
+  id: "qa"                   # Lowercase ID for activation
+  title: "QA Engineer"       # Professional title
+  icon: "🔍"                 # Emoji icon
+  whenToUse: "Use for testing, quality assurance, and bug validation"
+```
+
+**Step 2: Define Persona**
+```yaml
+persona:
+  role: "Quality Assurance Specialist & Test Engineer"
+  style: "Meticulous, detail-oriented, systematic, thorough"
+  identity: "QA engineer focused on comprehensive testing and quality validation"
+  focus: "Creating test plans, writing test cases, and validating requirements"
+  core_principles:
+    - Test early and often
+    - Validate against requirements
+    - Document all defects clearly
+    - Focus on user experience
+    - Automate repetitive tests
+```
+
+**Step 3: Define Commands**
+```yaml
+commands:
+  - help: Show numbered list of available commands
+  - create-test-plan: Generate test plan from requirements
+  - write-test-cases: Create test cases for feature
+  - validate-feature: Validate implementation against acceptance criteria
+  - report-bug: Create detailed bug report
+  - exit: Exit QA agent mode
+```
+
+**Step 4: Define Dependencies**
+```yaml
+dependencies:
+  checklists:
+    - qa-checklist.md
+    - regression-checklist.md
+  tasks:
+    - create-test-plan.md
+    - validate-requirements.md
+  templates:
+    - test-plan-tmpl.yaml
+    - bug-report-tmpl.yaml
+```
+
+**Step 5: Generate for All IDEs**
+
+Use adf-cli generators (once implemented) or manually create files for each IDE using the patterns above.
+
+---
+
 ## Output Generation Strategy
 
 ### Per Framework

package/CHANGELOG.md

@@ -5,6 +5,86 @@ All notable changes to `@iservu-inc/adf-cli` 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).
 
+## [0.4.26] - 2025-10-04
+
+### 🔧 Improved Error Handling
+
+**Enhanced: AI Model Selection Error Messages**
+- **Problem:** When model selection fails (e.g., OpenRouter free models, unavailable models), error messages were not helpful
+- **Solution:** Added comprehensive error detection and helpful guidance for common issues
+- **Improvements:**
+  - **Privacy/Data Policy Errors:** Specific guidance for OpenRouter free models requiring privacy settings
+  - **404/Not Found Errors:** Clear explanation when models are unavailable or require specific endpoints
+  - **400/Parameter Errors:** Help for models using different API parameters (e.g., experimental models)
+  - **401/Invalid Key:** API key validation guidance
+  - **429/Rate Limit:** Rate limit detection with retry suggestion
+  - **Generic Fallback:** Helpful tip for unknown errors
+
+**Added: OpenRouter Model Recommendations**
+- Shows recommended models when 50+ models are available
+- Warns users about free model privacy requirements
+- Suggests most compatible models:
+  - anthropic/claude-sonnet-4-5
+  - openai/gpt-4-turbo
+  - google/gemini-pro-1.5
+
+**Technical Details:**
+- `ai-config.js:330-366`: Enhanced error handling with category detection
+- `ai-config.js:282-288`: Added model recommendation tip for OpenRouter
+- Error messages now provide actionable solutions, not just error text
+- All 120 tests passing
+
+**Impact:**
+- Users get clear guidance when model selection fails
+- Reduces confusion about privacy settings and model availability
+- Faster troubleshooting with specific solutions
+
+## [0.4.25] - 2025-10-04
+
+### 🔧 UX Improvements
+
+**Fixed: AI Configuration Timing**
+- **Problem:** AI configuration was happening after workflow selection questions (team size, etc.)
+- **Solution:** Moved AI configuration to init.js to execute immediately after project type detection
+- **New Flow:**
+  1. Project type detection
+  2. **AI Provider configuration** (happens here now)
+  3. Workflow selection (team size questions)
+  4. Interview questions
+- **Impact:** AI configuration now clearly appears FIRST before any workflow questions
+- **Note:** This supersedes the v0.4.15 approach of configuring AI in interviewer.js
+
+**Technical Details:**
+- `init.js:88-90`: Added AI configuration call before workflow selection
+- `init.js:114`: Pass aiConfig to Interviewer constructor
+- `interviewer.js`: AI config block skipped when aiConfig already provided
+- When AI already configured via `adf config`, shows simple confirmation message
+- All 120 tests passing
+
+### 📚 Documentation
+
+**Added: Comprehensive Custom Agent/Persona Documentation**
+- **New Section:** "Custom Agent/Persona Configuration" in IDE-CUSTOMIZATIONS.md
+- **Coverage:** Complete documentation for all major AI coding assistants
+  - Windsurf workflows (`.windsurf/workflows/`)
+  - Cursor rules (`.cursor/rules/`)
+  - GitHub Copilot chatmodes (`.github/chatmodes/`)
+  - Claude Code commands (`.claude/commands/`)
+  - Trae rules (`.trae/rules/`)
+  - VSCode settings (`.vscode/`)
+- **Key Insights:**
+  - All IDEs share same YAML configuration block
+  - Only wrapper format and activation method differ per IDE
+  - Write-once, deploy-everywhere pattern documented
+- **Includes:**
+  - Activation comparison table
+  - Shared agent YAML schema
+  - Step-by-step guide for creating new agents
+  - Real-world examples from BMAD project
+
+**File Updated:**
+- `.project/docs/tool-integrations/IDE-CUSTOMIZATIONS.md` - Added comprehensive Section 4
+
 ## [0.4.15] - 2025-10-04
 
 ### 🐛 Bug Fixes & Enhancements

package/lib/ai/ai-config.js

@@ -278,6 +278,15 @@ async function configureAIProvider(projectPath = process.cwd()) {
   // Fetch available models
   const availableModels = await fetchAvailableModels(selectedProvider, apiKey);
 
+  // Show helpful tip about model selection
+  if (selectedProvider.id === 'openrouter' && availableModels.length > 50) {
+    console.log(chalk.gray('\n💡 Tip: Recommended models for best compatibility:'));
+    console.log(chalk.gray('   • anthropic/claude-sonnet-4-5'));
+    console.log(chalk.gray('   • openai/gpt-4-turbo'));
+    console.log(chalk.gray('   • google/gemini-pro-1.5'));
+    console.log(chalk.yellow('   ⚠️  Free models may require specific privacy settings\n'));
+  }
+
   // Model selection with autocomplete
   console.log('');
   const { model } = await inquirer.prompt([
@@ -327,6 +336,44 @@ async function configureAIProvider(projectPath = process.cwd()) {
       spinner.fail(chalk.red('AI connection failed'));
       console.log(chalk.red(`\nError: ${error.message}\n`));
 
+      // Provide specific guidance for common errors
+      const errorMsg = error.message.toLowerCase();
+
+      if (errorMsg.includes('data policy') || errorMsg.includes('privacy')) {
+        console.log(chalk.yellow('📋 Privacy/Data Policy Issue:\n'));
+        if (selectedProvider.id === 'openrouter') {
+          console.log(chalk.gray('   OpenRouter: Free models require specific privacy settings.'));
+          console.log(chalk.cyan('   Solutions:'));
+          console.log(chalk.gray('   1. Configure privacy: https://openrouter.ai/settings/privacy'));
+          console.log(chalk.gray('   2. Select a paid model instead (recommended)'));
+          console.log(chalk.gray('   3. Enable "Free model publication" in settings\n'));
+        } else {
+          console.log(chalk.gray('   The selected model may require specific account settings.'));
+          console.log(chalk.gray('   Try selecting a different model or check your provider settings.\n'));
+        }
+      } else if (errorMsg.includes('404') || errorMsg.includes('not found') || errorMsg.includes('no endpoints')) {
+        console.log(chalk.yellow('📋 Model Not Available:\n'));
+        console.log(chalk.gray('   The selected model may no longer be available or accessible.'));
+        console.log(chalk.cyan('   Solutions:'));
+        console.log(chalk.gray('   1. Select a different, more widely supported model'));
+        console.log(chalk.gray('   2. Check the provider\'s model availability'));
+        console.log(chalk.gray('   3. Some models require specific API endpoints or settings\n'));
+      } else if (errorMsg.includes('400') || errorMsg.includes('unsupported parameter')) {
+        console.log(chalk.yellow('📋 Model Parameter Incompatibility:\n'));
+        console.log(chalk.gray('   The selected model may use different API parameters.'));
+        console.log(chalk.cyan('   Solutions:'));
+        console.log(chalk.gray('   1. Try a more standard model (e.g., gpt-4-turbo, claude-3-5-sonnet)'));
+        console.log(chalk.gray('   2. Some newer/experimental models may not be fully supported yet\n'));
+      } else if (errorMsg.includes('401') || errorMsg.includes('invalid') || errorMsg.includes('unauthorized')) {
+        console.log(chalk.yellow('📋 Invalid API Key:\n'));
+        console.log(chalk.gray('   Please check that your API key is correct and active.\n'));
+      } else if (errorMsg.includes('429') || errorMsg.includes('rate limit')) {
+        console.log(chalk.yellow('📋 Rate Limit:\n'));
+        console.log(chalk.gray('   You\'ve hit the API rate limit. Please wait a moment and try again.\n'));
+      } else {
+        console.log(chalk.yellow('💡 Tip: Try selecting a more widely supported model\n'));
+      }
+
       const { retry } = await inquirer.prompt([
         {
           type: 'confirm',

package/lib/commands/init.js

@@ -85,6 +85,10 @@ async function init(options) {
   const projectType = await detectProjectType(cwd);
   spinner.succeed(`Project type: ${chalk.green(projectType.type)}`);
 
+  // Configure AI provider BEFORE workflow selection
+  console.log('');
+  const aiConfig = await configureAIProvider(cwd);
+
   // Determine workflow/framework
   let workflow;
 
@@ -105,9 +109,9 @@ async function init(options) {
   // Create .adf directory
   await fs.ensureDir(adfDir);
 
-  // AI will be configured as first block in the interview
+  // AI already configured above - pass to interviewer
   // Start interview
-  const interviewer = new Interviewer(workflow, cwd, null, null);
+  const interviewer = new Interviewer(workflow, cwd, null, aiConfig);
   const sessionPath = await interviewer.start();
 
   // Show completion message

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iservu-inc/adf-cli",
-  "version": "0.4.15",
+  "version": "0.4.26",
   "description": "CLI tool for AgentDevFramework - AI-assisted development framework with multi-provider AI support",
   "main": "index.js",
   "bin": {