@iservu-inc/adf-cli 0.12.11 → 0.13.0

package/.claude/settings.local.json

@@ -18,7 +18,12 @@
       "WebFetch(domain:github.com)",
       "WebFetch(domain:antigravity.google)",
       "WebSearch",
-      "Bash(node -c:*)"
+      "Bash(node -c:*)",
+      "mcp__MCP_DOCKER__brave_web_search",
+      "Bash(adf guide:*)",
+      "WebFetch(domain:docs.windsurf.com)",
+      "mcp__MCP_DOCKER__resolve-library-id",
+      "mcp__MCP_DOCKER__get-library-docs"
     ],
     "deny": [],
     "ask": []

package/CHANGELOG.md

@@ -5,6 +5,108 @@ 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.13.0] - 2026-01-03
+
+### 🚀 Major Feature - OpenCode Multi-Agent Integration
+
+**Minor Release:** Enhanced OpenCode CLI integration with multi-provider, multi-agent support.
+
+#### Added
+
+**OpenCode Multi-Agent System:**
+- ✨ **Complete OpenCode generator rewrite** using official configuration schema
+- ✨ **Multi-provider support** - Automatically detects and configures all available AI providers from `.adf/.env`:
+  - Anthropic (Claude models)
+  - OpenAI (GPT models)
+  - Google Gemini (Gemini models)
+  - OpenRouter (100+ models)
+- ✨ **Multi-agent configuration** - Creates specialized agents based on ADF framework level:
+  - **Rapid (PRP)**: dev, qa agents
+  - **Balanced (Spec-Kit)**: analyst, pm, dev, qa agents
+  - **Comprehensive (BMAD)**: analyst, pm, architect, sm, dev, qa agents
+- ✨ **Optimal model assignment** - Each agent gets the best model for its task complexity:
+  - Powerful models (Sonnet/GPT-5/Gemini-2.5-Pro) → analyst, architect
+  - Balanced models (Haiku/GPT-4o/Gemini-1.5-Pro) → pm, dev
+  - Fast models (Haiku/GPT-4o-mini/Gemini-Flash) → qa, sm
+- ✨ **MCP server integration** - Auto-configures filesystem access via Model Context Protocol
+- ✨ **Auto-loads AGENTS.md** - References universal agent manifest and session outputs via `instructions` field
+- ✨ **Tool permissions** - Agent-specific tool access (e.g., QA can't write production code)
+
+**Incremental Deployment:**
+- 📝 **Documented incremental tool deployment** - Add tools anytime with `adf deploy <tool>` without reinitializing
+
+**Accurate Documentation:**
+- 📖 **Updated OpenCode guide** with verified information from https://opencode.ai/docs
+- 📖 Installation: `npm install -g opencode-ai@latest`
+- 📖 Configuration schema: https://opencode.ai/config.json
+- 📖 Multi-agent support highlighted in guide
+
+#### Technical Details
+
+**Modified Files:**
+- `lib/generators/opencode-generator.js` - Complete rewrite (300+ lines)
+  - `getAvailableProviders()` - Detects providers from `.adf/.env`
+  - `generateProviderConfigurations()` - Creates provider configs with env var substitution
+  - `generateAgentConfigurations()` - Maps ADF agents to OpenCode agents
+  - `getOptimalModelForAgent()` - Selects best model per agent type
+- `lib/commands/guide.js` - Updated OpenCode guide with accurate info
+- `lib/commands/deploy.js` - Already integrated (no changes needed)
+
+#### Impact
+- ✅ OpenCode leverages ALL configured AI providers automatically
+- ✅ Cost-effective: Each agent uses optimal model for its task
+- ✅ Follows official OpenCode v1.0+ configuration standards
+- ✅ Seamless integration with ADF's multi-provider AI system
+- ✅ No breaking changes - existing deployments unaffected
+
+## [0.12.14] - 2025-12-23
+
+### 🐛 Fix - Windsurf Character Limit
+
+**Patch Release:** Corrected Windsurf rule file character limit in guide.
+
+#### Fixed
+
+**Windsurf Guide Correction:**
+- 🔧 **Fixed character limit** from 6000 to **12000 characters** per rule file
+- Verified against official documentation: https://docs.windsurf.com/windsurf/cascade/memories
+- Added documentation link to guide for reference
+
+#### Impact
+- ✅ Accurate character limit for `.windsurf/rules/*.md` files
+- ✅ Users won't incorrectly split files at 6000 chars
+- ✅ Guide now matches official Windsurf documentation
+
+## [0.12.13] - 2025-12-23
+
+### 🐛 Critical Fix - Guide System Accuracy
+
+**Patch Release:** Fixed hallucinated information in `adf guide` command. All tool setup guides now use verified information from official documentation.
+
+#### Fixed
+
+**Guide System Overhaul:**
+- 🔧 **Replaced all hallucinated content** with accurate information verified via official documentation
+- Fixed installation commands, usage instructions, and file paths for all 9 supported tools
+- All guides now reference real, working documentation and commands
+
+**Tool-Specific Corrections:**
+- **Windsurf**: Accurate `.windsurf/rules/*.md` format (6000 char limit per file)
+- **Cursor**: Correct `.cursor/rules/*.mdc` format with YAML frontmatter
+- **VS Code**: Verified `.github/copilot-instructions.md` usage with GitHub Copilot
+- **Zed**: Accurate `settings.json` and MCP configuration details
+- **Antigravity**: Correct "... → Customizations" menu instructions
+- **Claude Code**: Real install script: `curl -fsSL https://claude.ai/install.sh | bash`
+- **OpenCode**: GitHub repo reference, GitHub Copilot authentication requirement
+- **Gemini CLI**: Correct package `@google/gemini-cli` and command `gemini` (not `gemini-cli`)
+- **DeepAgent**: Correct package `@abacus-ai/cli` and command `abacusai` (not `deepagent`)
+
+#### Impact
+- ✅ Users can now trust guide information to be accurate
+- ✅ Installation commands actually work as documented
+- ✅ File paths and configurations match official tool documentation
+- ✅ No more "command not found" errors from following guides
+
 ## [0.12.10] - 2025-12-23
 
 ### 🐛 Critical Bug Fixes

package/bin/adf.js

@@ -20,6 +20,7 @@ const initCommand = require('../lib/commands/init');
 const deployCommand = require('../lib/commands/deploy');
 const updateCommand = require('../lib/commands/update');
 const configCommand = require('../lib/commands/config');
+const guideCommand = require('../lib/commands/guide');
 
 const program = new Command();
 
@@ -41,6 +42,9 @@ ${chalk.cyan.bold('Quick Start:')}
   ${chalk.gray('3. Deploy to your AI coding assistant')}
   $ adf deploy
 
+  ${chalk.gray('4. Get setup instructions for your tool')}
+  $ adf guide <tool>
+
 ${chalk.cyan.bold('What is ADF?')}
   AgentDevFramework (ADF) is an AI-assisted development framework that helps
   you gather requirements through intelligent AI-guided interviews. It supports
@@ -61,9 +65,14 @@ ${chalk.cyan.bold('Getting Help:')}
   ${chalk.gray('# Detailed help for specific commands')}
   $ adf init --help
   $ adf deploy --help
+  $ adf guide --help
   $ adf config --help
   $ adf update --help
 
+  ${chalk.gray('# Get tool-specific setup guides')}
+  $ adf guide windsurf
+  $ adf guide claude-code
+
   ${chalk.gray('# Check version and install path')}
   $ adf --version
 
@@ -304,6 +313,69 @@ ${chalk.cyan.bold('Backwards Compatibility:')}
 `)
   .action(updateCommand);
 
+// adf guide
+program
+  .command('guide [tool]')
+  .description('Show setup guide for deployed tools')
+  .addHelpText('after', `
+${chalk.cyan.bold('Description:')}
+  Get detailed setup and usage instructions for AI tools after deployment.
+  Shows what files were generated, how to configure the tool, and how to start using it.
+
+${chalk.cyan.bold('Command Syntax:')}
+  ${chalk.white('adf guide [tool]')}
+
+  ${chalk.yellow('[tool]')} - (Optional) Tool name
+              If omitted, shows list of available guides
+
+${chalk.cyan.bold('Available Tools:')}
+  ${chalk.yellow('windsurf')}      - Codeium Windsurf IDE
+  ${chalk.yellow('cursor')}        - Cursor AI IDE
+  ${chalk.yellow('vscode')}        - Visual Studio Code with GitHub Copilot
+  ${chalk.yellow('zed')}           - Zed Editor
+  ${chalk.yellow('antigravity')}   - Google Antigravity
+  ${chalk.yellow('claude-code')}   - Claude Code CLI
+  ${chalk.yellow('opencode')}      - OpenCode CLI
+  ${chalk.yellow('gemini-cli')}    - Google Gemini CLI
+  ${chalk.yellow('deepagent')}     - Abacus.ai DeepAgent
+
+${chalk.cyan.bold('What You\'ll Learn:')}
+  • Which files were generated and what they do
+  • How to configure the tool to use ADF outputs
+  • How to start coding with AI assistance
+  • MCP server setup (if applicable)
+  • Keyboard shortcuts and workflows
+  • Troubleshooting common issues
+
+${chalk.cyan.bold('Examples:')}
+  ${chalk.gray('# List all available guides')}
+  $ adf guide
+
+  ${chalk.gray('# Get Windsurf setup instructions')}
+  $ adf guide windsurf
+
+  ${chalk.gray('# Learn how to use Claude Code CLI')}
+  $ adf guide claude-code
+
+  ${chalk.gray('# See Gemini CLI integration steps')}
+  $ adf guide gemini-cli
+
+${chalk.cyan.bold('Workflow:')}
+  1. Run ${chalk.white('adf init')} to gather requirements
+  2. Run ${chalk.white('adf deploy <tool>')} to deploy configurations
+  3. Run ${chalk.white('adf guide <tool>')} to learn how to use the tool
+  4. Start coding with AI assistance!
+
+${chalk.cyan.bold('What\'s in a Guide:')}
+  • 📁 Generated files with status check (✓ exists / ✗ missing)
+  • ⚙️  Step-by-step setup instructions
+  • 🔌 MCP server configuration (if applicable)
+  • 🚀 Usage examples and workflows
+  • 🔧 Troubleshooting tips
+  • 📖 Quick reference links
+`)
+  .action(guideCommand);
+
 // adf config
 program
   .command('config')

package/lib/commands/guide.js

@@ -0,0 +1,449 @@
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs-extra');
+
+const TOOL_GUIDES = {
+  'windsurf': {
+    name: 'Codeium Windsurf',
+    files: [
+      { path: '.windsurfrules', desc: 'Legacy rules file (deprecated)' },
+      { path: '.windsurf/rules/*.md', desc: 'Modular rules (max 12000 chars per file)' },
+      { path: '.windsurf/workflows/*.md', desc: 'Workflow definitions' },
+      { path: 'AGENTS.md', desc: 'Universal agent manifest (ANDF standard)' }
+    ],
+    setup: [
+      '1. Download and install Windsurf from: https://codeium.com/windsurf',
+      '2. Open your project in Windsurf IDE',
+      '3. Create .windsurf/rules/ directory for modular rules',
+      '4. Each .md file in rules/ directory auto-loaded (max 12000 chars)',
+      '5. Rules active immediately in Cascade AI'
+    ],
+    usage: [
+      '• Cmd/Ctrl+L - Open Cascade AI chat',
+      '• Rules from .windsurf/rules/*.md applied automatically',
+      '• Character limit: 12000 chars per rule file',
+      '• Split large agents across multiple .md files if needed',
+      '• Use @agents.md to reference manifest explicitly',
+      '• Workflows in .windsurf/workflows/ directory',
+      '• Docs: https://docs.windsurf.com/windsurf/cascade/memories'
+    ],
+    mcpServers: [],
+    troubleshooting: [
+      '• Rules not loading? Check each .md file is ≤12000 characters',
+      '• Verify .windsurf/rules/ directory exists',
+      '• Restart Windsurf IDE after adding new rules',
+      '• Check View → Output → Windsurf for parsing errors'
+    ]
+  },
+
+  'cursor': {
+    name: 'Cursor AI IDE',
+    files: [
+      { path: '.cursor/rules/*.mdc', desc: 'Cursor rules with YAML frontmatter' },
+      { path: '.cursorrules', desc: 'Legacy single-file rules (deprecated)' },
+      { path: 'AGENTS.md', desc: 'Universal agent manifest' },
+      { path: '.context/', desc: 'Deep context (architecture, glossary)' }
+    ],
+    setup: [
+      '1. Download and install Cursor from: https://cursor.sh',
+      '2. Open your project in Cursor',
+      '3. Create .cursor/rules/ directory',
+      '4. Add .mdc files with YAML frontmatter (see usage)',
+      '5. Rules auto-apply to Agent (Cmd/Ctrl+L) and Cmd+K'
+    ],
+    usage: [
+      '• Cmd/Ctrl+K - Inline editing with rules applied',
+      '• Cmd/Ctrl+L - Chat (Agent) with rules applied',
+      '• Rules format (.mdc file):',
+      '  ---',
+      '  title: Developer Agent',
+      '  description: Development guidelines',
+      '  ---',
+      '  [Your agent instructions here]',
+      '• Use @AGENTS.md to reference manifest',
+      '• Tab to accept AI suggestions'
+    ],
+    mcpServers: [],
+    troubleshooting: [
+      '• Rules not active? Check .cursor/rules/ directory exists',
+      '• Verify .mdc files have valid YAML frontmatter',
+      '• Restart Cursor after adding new rules',
+      '• Check Cursor Settings → Features → Rules enabled'
+    ]
+  },
+
+  'vscode': {
+    name: 'Visual Studio Code (GitHub Copilot)',
+    files: [
+      { path: '.github/copilot-instructions.md', desc: 'GitHub Copilot custom instructions' },
+      { path: '.vscode/settings.json', desc: 'Workspace settings' },
+      { path: 'AGENTS.md', desc: 'Universal agent manifest' },
+      { path: '.context/', desc: 'Deep context directory' }
+    ],
+    setup: [
+      '1. Download VS Code from: https://code.visualstudio.com',
+      '2. Install GitHub Copilot extension from marketplace',
+      '3. Create .github/copilot-instructions.md in project root',
+      '4. Copilot automatically reads instructions on chat start',
+      '5. No restart needed - instructions load per conversation'
+    ],
+    usage: [
+      '• Cmd/Ctrl+I - Inline Copilot chat',
+      '• Cmd/Ctrl+Shift+I - Copilot panel (sidebar)',
+      '• Copilot reads .github/copilot-instructions.md automatically',
+      '• Use @workspace to include entire workspace context',
+      '• Reference specific files: @filename.js',
+      '• Instructions format: Plain markdown in copilot-instructions.md',
+      '• Documentation: https://docs.github.com/copilot'
+    ],
+    mcpServers: [],
+    troubleshooting: [
+      '• Instructions not loading? Verify .github/ directory exists',
+      '• Check Copilot status icon in bottom-right corner',
+      '• Restart Copilot: Cmd/Ctrl+Shift+P → "Copilot: Restart"',
+      '• Verify GitHub Copilot subscription is active'
+    ]
+  },
+
+  'zed': {
+    name: 'Zed Editor',
+    files: [
+      { path: '.zed/settings.json', desc: 'Project-specific settings' },
+      { path: 'AGENTS.md', desc: 'Universal agent manifest' },
+      { path: '.context/', desc: 'Deep context directory' }
+    ],
+    setup: [
+      '1. Download and install Zed from: https://zed.dev',
+      '2. Open your project in Zed',
+      '3. Create .zed/settings.json in project root (optional)',
+      '4. Global settings at: ~/.config/zed/settings.json',
+      '5. MCP servers configured in settings.json'
+    ],
+    usage: [
+      '• /assistant - Open AI assistant panel',
+      '• Cmd/Ctrl+Enter - Submit to assistant',
+      '• Configure MCP servers in settings.json:',
+      '  {',
+      '    "context_servers": {',
+      '      "project": {',
+      '        "command": "npx",',
+      '        "args": ["@modelcontextprotocol/server-filesystem", ".context"]',
+      '      }',
+      '    }',
+      '  }',
+      '• Reference AGENTS.md manually in conversation'
+    ],
+    mcpServers: [
+      {
+        name: 'filesystem',
+        command: 'npx @modelcontextprotocol/server-filesystem',
+        desc: 'Provides file access via MCP protocol'
+      }
+    ],
+    troubleshooting: [
+      '• MCP servers not starting? Check Node.js installed',
+      '• Verify settings.json syntax is valid JSON',
+      '• Check Zed logs: View → Debug → Developer Tools',
+      '• Documentation: https://zed.dev/docs'
+    ]
+  },
+
+  'antigravity': {
+    name: 'Google Antigravity',
+    files: [
+      { path: 'AGENTS.md', desc: 'Universal agent manifest' },
+      { path: '.context/', desc: 'Deep context (architecture, glossary)' }
+    ],
+    setup: [
+      '1. Access Antigravity (Google internal tool)',
+      '2. Open your project or codebase',
+      '3. Click ... menu → Customizations',
+      '4. Add Rules and Workflows via customization UI',
+      '5. Rules and workflows saved automatically'
+    ],
+    usage: [
+      '• Access customizations: Click ... → Customizations',
+      '• Rules: Add custom instructions for AI behavior',
+      '• Workflows: Define multi-step processes',
+      '• Reference project files in conversation',
+      '• Use "Read AGENTS.md" to access agent manifest',
+      '• Conversational commands: "Follow dev workflow"',
+      '• .context/ directory accessible for detailed docs'
+    ],
+    mcpServers: [],
+    troubleshooting: [
+      '• Customizations not applying? Check ... → Customizations menu',
+      '• Restart Antigravity session if changes not reflected',
+      '• Verify rules syntax is correct in customization UI',
+      '• Contact Google internal support for Antigravity issues'
+    ]
+  },
+
+  'claude-code': {
+    name: 'Claude Code CLI',
+    files: [
+      { path: '.framework/agents/*.md', desc: 'Agent definition files (analyst, pm, dev, qa, etc.)' },
+      { path: '.claude/commands/', desc: 'Custom commands directory' },
+      { path: 'AGENTS.md', desc: 'Universal agent manifest' },
+      { path: '.context/', desc: 'Deep context directory' }
+    ],
+    setup: [
+      '1. Install Claude Code: curl -fsSL https://claude.ai/install.sh | bash',
+      '2. Authenticate: Follow prompts after installation',
+      '3. Navigate to your project directory',
+      '4. Custom commands in .claude/commands/ (optional)',
+      '5. Reference agent files manually in conversation'
+    ],
+    usage: [
+      '• Start chat: claude-code',
+      '• Interactive terminal-based chat with Claude',
+      '• Reference project files: "read .framework/agents/dev.md"',
+      '• Access AGENTS.md: "follow instructions in AGENTS.md"',
+      '• Custom commands: Place scripts in .claude/commands/',
+      '• Requirements: "show .adf/sessions/*/outputs/"',
+      '• Documentation: https://claude.ai/code'
+    ],
+    mcpServers: [
+      {
+        name: 'filesystem',
+        desc: 'Can be configured via .claude/settings.json',
+        command: 'Configure MCP servers in settings file'
+      }
+    ],
+    troubleshooting: [
+      '• Installation issues? Check: https://claude.ai/code',
+      '• Command not found? Restart terminal after install',
+      '• Authentication failed? Run installation script again',
+      '• Custom commands not working? Check .claude/commands/ permissions'
+    ]
+  },
+
+  'opencode': {
+    name: 'OpenCode CLI',
+    files: [
+      { path: '.opencode.json', desc: 'OpenCode multi-agent configuration' },
+      { path: 'AGENTS.md', desc: 'Universal agent manifest (auto-referenced)' },
+      { path: '.context/', desc: 'Deep context directory' }
+    ],
+    setup: [
+      '1. Install: npm install -g opencode-ai@latest',
+      '2. Or quick install: curl -fsSL https://opencode.ai/install | bash',
+      '3. Authenticate: opencode (interactive provider setup)',
+      '4. Navigate to your project directory',
+      '5. OpenCode reads .opencode.json automatically'
+    ],
+    usage: [
+      '• Start session: opencode',
+      '• Terminal-based AI coding agent (TUI)',
+      '• Supports multiple AI providers (Anthropic, OpenAI, Google, OpenRouter)',
+      '• Multi-agent system with specialized agents:',
+      '  - dev (primary): Senior software engineer',
+      '  - analyst: Business analyst for requirements',
+      '  - pm: Product manager for planning',
+      '  - architect: Solutions architect for design',
+      '  - qa: QA engineer for testing',
+      '  - sm: Scrum master for agile workflow',
+      '• Configuration schema: https://opencode.ai/config.json',
+      '• Auto-loads AGENTS.md and session outputs',
+      '• Documentation: https://opencode.ai/docs'
+    ],
+    mcpServers: [
+      {
+        name: 'project_filesystem',
+        desc: 'Provides project file access via MCP protocol',
+        command: 'npx -y @modelcontextprotocol/server-filesystem'
+      }
+    ],
+    troubleshooting: [
+      '• Command not found? Restart terminal after install',
+      '• Config errors? Validate against: https://opencode.ai/config.json',
+      '• Provider auth issues? Run: opencode (interactive setup)',
+      '• Check version: opencode --version',
+      '• Documentation: https://opencode.ai/docs',
+      '• GitHub: https://github.com/anomalyco/opencode/issues'
+    ]
+  },
+
+  'gemini-cli': {
+    name: 'Google Gemini CLI',
+    files: [
+      { path: 'GEMINI.md', desc: 'Project context and instructions for Gemini' },
+      { path: 'AGENTS.md', desc: 'Universal agent manifest' },
+      { path: '.context/', desc: 'Deep context directory' }
+    ],
+    setup: [
+      '1. Install Gemini CLI: npm install -g @google/gemini-cli',
+      '2. Configure API key: gemini auth (interactive setup)',
+      '3. Or set manually: export GOOGLE_API_KEY=your_key',
+      '4. Navigate to your project directory',
+      '5. Start CLI: gemini (not gemini-cli)'
+    ],
+    usage: [
+      '• Start session: gemini',
+      '• Interactive chat interface with Google Gemini models',
+      '• Reference project files: gemini --file path/to/file',
+      '• Use GEMINI.md for project context (reference manually)',
+      '• Access requirements: "Read .adf/sessions/*/outputs/"',
+      '• Documentation: https://geminicli.com'
+    ],
+    mcpServers: [],
+    troubleshooting: [
+      '• Command not found? Verify npm global install path in PATH',
+      '• API key issues? Run: gemini auth',
+      '• Check installation: gemini --version',
+      '• Documentation: https://geminicli.com/docs'
+    ]
+  },
+
+  'deepagent': {
+    name: 'Abacus.ai DeepAgent',
+    files: [
+      { path: '.deepagent/agents/*.md', desc: 'Agent markdown files' },
+      { path: '.deepagent/README.md', desc: 'Project overview and usage' },
+      { path: 'AGENTS.md', desc: 'Universal agent manifest' }
+    ],
+    setup: [
+      '1. Install Abacus.ai CLI: npm install -g @abacus-ai/cli',
+      '2. Authenticate: abacusai login',
+      '3. Navigate to your project directory',
+      '4. DeepAgent configurations in .deepagent/ directory',
+      '5. Use command: abacusai (not deepagent)'
+    ],
+    usage: [
+      '• Start session: abacusai',
+      '• Terminal/CLI interface for Abacus.ai platform',
+      '• Access DeepAgent features via CLI commands',
+      '• Agent markdown files can be referenced manually',
+      '• Check available commands: abacusai --help',
+      '• Documentation: https://abacus.ai/docs'
+    ],
+    mcpServers: [],
+    troubleshooting: [
+      '• Command not found? Verify npm global install: npm list -g @abacus-ai/cli',
+      '• Authentication issues? Run: abacusai login',
+      '• Check CLI version: abacusai --version',
+      '• Documentation: https://abacus.ai/docs'
+    ]
+  }
+};
+
+async function guide(tool, options) {
+  const cwd = process.cwd();
+
+  // If no tool specified, show available guides
+  if (!tool) {
+    console.log(chalk.cyan.bold('\n📚 ADF Tool Setup Guides\n'));
+    console.log(chalk.gray('Get detailed setup and usage instructions for deployed tools.\n'));
+
+    console.log(chalk.yellow('Available Guides:'));
+    console.log('');
+
+    for (const [key, toolInfo] of Object.entries(TOOL_GUIDES)) {
+      console.log(chalk.green(`  adf guide ${key.padEnd(15)}`), chalk.gray(`- ${toolInfo.name}`));
+    }
+
+    console.log('');
+    console.log(chalk.cyan('Usage:'));
+    console.log(chalk.white('  adf guide <tool>'));
+    console.log('');
+    console.log(chalk.cyan('Examples:'));
+    console.log(chalk.gray('  $ adf guide windsurf'));
+    console.log(chalk.gray('  $ adf guide claude-code'));
+    console.log(chalk.gray('  $ adf guide gemini-cli'));
+    console.log('');
+
+    return;
+  }
+
+  // Get tool guide
+  const toolGuide = TOOL_GUIDES[tool];
+  if (!toolGuide) {
+    console.error(chalk.red(`\n❌ No guide available for "${tool}"`));
+    console.log(chalk.yellow('\nRun "adf guide" to see available guides.\n'));
+    process.exit(1);
+  }
+
+  // Display guide
+  console.log(chalk.cyan.bold(`\n📚 ${toolGuide.name} Setup Guide\n`));
+  console.log(chalk.gray('━'.repeat(60)) + '\n');
+
+  // Check what files exist
+  console.log(chalk.yellow.bold('📁 Generated Files:\n'));
+  for (const file of toolGuide.files) {
+    const exists = await checkFileExists(cwd, file.path);
+    const status = exists ? chalk.green('✓') : chalk.red('✗');
+    console.log(`  ${status} ${chalk.white(file.path)}`);
+    console.log(chalk.gray(`     ${file.desc}`));
+  }
+  console.log('');
+
+  // Setup instructions
+  console.log(chalk.yellow.bold('⚙️  Setup Instructions:\n'));
+  for (const step of toolGuide.setup) {
+    console.log(chalk.gray(`  ${step}`));
+  }
+  console.log('');
+
+  // MCP Servers (if applicable)
+  if (toolGuide.mcpServers && toolGuide.mcpServers.length > 0) {
+    console.log(chalk.yellow.bold('🔌 MCP Servers:\n'));
+    for (const server of toolGuide.mcpServers) {
+      console.log(chalk.cyan(`  • ${server.name}`));
+      console.log(chalk.gray(`    ${server.desc}`));
+      if (server.command) {
+        console.log(chalk.gray(`    Command: ${server.command}`));
+      }
+      if (server.url) {
+        console.log(chalk.gray(`    URL: ${server.url}`));
+      }
+      console.log('');
+    }
+  }
+
+  // Usage instructions
+  console.log(chalk.yellow.bold('🚀 Usage:\n'));
+  for (const instruction of toolGuide.usage) {
+    console.log(chalk.gray(`  ${instruction}`));
+  }
+  console.log('');
+
+  // Troubleshooting
+  console.log(chalk.yellow.bold('🔧 Troubleshooting:\n'));
+  for (const tip of toolGuide.troubleshooting) {
+    console.log(chalk.gray(`  ${tip}`));
+  }
+  console.log('');
+
+  // Quick reference
+  console.log(chalk.gray('━'.repeat(60)) + '\n');
+  console.log(chalk.cyan.bold('📖 Quick Reference:\n'));
+  console.log(chalk.gray(`  Requirements: .adf/sessions/*/outputs/`));
+  console.log(chalk.gray(`  Universal agent config: AGENTS.md`));
+  console.log(chalk.gray(`  Deep context: .context/memory/`));
+  console.log('');
+
+  console.log(chalk.cyan('Need more help?'));
+  console.log(chalk.gray('  • Documentation: https://github.com/iservu/adf-cli#readme'));
+  console.log(chalk.gray('  • Issues: https://github.com/iservu/adf-cli/issues'));
+  console.log('');
+}
+
+/**
+ * Check if file/pattern exists
+ */
+async function checkFileExists(cwd, filePath) {
+  // Handle glob patterns
+  if (filePath.includes('*')) {
+    const dir = path.dirname(filePath);
+    const dirPath = path.join(cwd, dir);
+    if (!await fs.pathExists(dirPath)) return false;
+
+    const files = await fs.readdir(dirPath);
+    return files.length > 0;
+  }
+
+  // Regular file
+  return await fs.pathExists(path.join(cwd, filePath));
+}
+
+module.exports = guide;

package/lib/generators/opencode-generator.js

@@ -4,12 +4,18 @@ const ToolConfigGenerator = require('./tool-config-generator');
 
 /**
  * Generator for OpenCode CLI configurations
- * Creates .opencode.json with project-specific configuration
+ * Creates .opencode.json with multi-agent, multi-provider configuration
+ *
+ * OpenCode Configuration Reference:
+ * - Schema: https://opencode.ai/config.json
+ * - Docs: https://opencode.ai/docs/
+ * - Multi-provider support: Anthropic, OpenAI, Google Gemini, OpenRouter
+ * - Multi-agent support: Specialized agents for different tasks
  */
 class OpenCodeGenerator extends ToolConfigGenerator {
   /**
    * Generate OpenCode configuration
-   * @returns {Object} Generated file path
+   * @returns {Object} Generated file paths
    */
   async generate() {
     await this.initialize();
@@ -19,134 +25,288 @@ class OpenCodeGenerator extends ToolConfigGenerator {
     // Generate configuration
     const config = await this.generateConfig();
 
+    // Write with proper JSON formatting (no schema in JSON, only comments)
     await fs.writeJson(configPath, config, { spaces: 2 });
 
     return { config: configPath };
   }
 
   /**
-   * Generate .opencode.json configuration
+   * Generate .opencode.json configuration following official OpenCode schema
+   * Reference: https://opencode.ai/docs/config
    */
   async generateConfig() {
     const projectContext = await this.getProjectContext();
-    const frameworkContext = await this.getFrameworkContext();
+    const providers = await this.getAvailableProviders();
+    const agents = await this.generateAgentConfigurations(providers);
 
-    return {
-      data: {
-        directory: ".opencode"
+    const config = {
+      "$schema": "https://opencode.ai/config.json",
+
+      // Provider configurations (Anthropic, OpenAI, Google, OpenRouter, etc.)
+      "provider": await this.generateProviderConfigurations(providers),
+
+      // Default model (use the most powerful available)
+      "model": this.getDefaultModel(providers),
+
+      // Agent configurations (mapped from ADF framework)
+      "agent": agents,
+
+      // Default agent for primary interactions
+      "default_agent": this.getDefaultAgent(),
+
+      // Global tool permissions
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true,
+        "webfetch": true,
+        "patch": true
       },
-      agents: {
-        coder: {
-          model: this.getCoderModel(),
-          maxTokens: 8000
+
+      // Permission settings (ask for destructive operations)
+      "permission": {
+        "edit": "allow",
+        "bash": {
+          "git push": "ask",
+          "rm -rf": "ask",
+          "*": "allow"
         },
-        task: {
-          model: this.getTaskModel(),
-          maxTokens: 4000
-        }
-      },
-      systemPrompt: this.generateSystemPrompt(projectContext, frameworkContext),
-      projectContext: {
-        framework: this.getFrameworkName(),
-        session: this.getSessionId(),
-        outputsPath: `.adf/sessions/${this.getSessionId()}/outputs/`
+        "webfetch": "allow"
       },
-      mcpServers: {
-        filesystem: {
-          command: "npx",
-          args: ["-y", "@modelcontextprotocol/server-filesystem", this.projectPath],
-          env: {}
+
+      // Instructions - reference AGENTS.md and session outputs
+      "instructions": [
+        "AGENTS.md",
+        `.adf/sessions/${this.getSessionId()}/outputs/*.md`
+      ],
+
+      // MCP servers for filesystem access
+      "mcp": {
+        "project_filesystem": {
+          "type": "local",
+          "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", this.projectPath],
+          "enabled": true
         }
       },
-      debug: false,
-      autoCompact: true
+
+      // Server configuration for 'opencode serve'
+      "server": {
+        "port": 4096,
+        "hostname": "localhost"
+      },
+
+      // Auto-update enabled
+      "autoupdate": true
     };
+
+    return config;
   }
 
   /**
-   * Generate system prompt for OpenCode
+   * Detect available AI providers from .adf/.env
+   * Returns array of provider IDs that have API keys configured
    */
-  generateSystemPrompt(projectContext, frameworkContext) {
-    const agentRole = this.getAgentRole();
+  async getAvailableProviders() {
+    const envPath = path.join(this.projectPath, '.adf', '.env');
+    const providers = [];
+
+    if (await fs.pathExists(envPath)) {
+      const envContent = await fs.readFile(envPath, 'utf-8');
+      const lines = envContent.split('\n');
+
+      for (const line of lines) {
+        if (line.includes('ANTHROPIC_API_KEY=') && !line.startsWith('#')) {
+          providers.push('anthropic');
+        }
+        if (line.includes('OPENAI_API_KEY=') && !line.startsWith('#')) {
+          providers.push('openai');
+        }
+        if ((line.includes('GEMINI_API_KEY=') || line.includes('GOOGLE_API_KEY=')) && !line.startsWith('#')) {
+          providers.push('google');
+        }
+        if (line.includes('OPENROUTER_API_KEY=') && !line.startsWith('#')) {
+          providers.push('openrouter');
+        }
+      }
+    }
+
+    // Default to Anthropic if no providers found
+    return providers.length > 0 ? providers : ['anthropic'];
+  }
+
+  /**
+   * Generate provider configurations for OpenCode
+   * Reference: https://opencode.ai/docs/providers
+   */
+  async generateProviderConfigurations(providers) {
+    const config = {};
+
+    if (providers.includes('anthropic')) {
+      config.anthropic = {
+        "options": {
+          "apiKey": "{env:ANTHROPIC_API_KEY}"
+        },
+        "models": {}
+      };
+    }
 
-    return `You are ${agentRole} for the ${projectContext.name} project.
+    if (providers.includes('openai')) {
+      config.openai = {
+        "options": {
+          "apiKey": "{env:OPENAI_API_KEY}"
+        },
+        "models": {}
+      };
+    }
 
-FRAMEWORK: ${this.getFrameworkName()}
+    if (providers.includes('google')) {
+      config.google = {
+        "options": {
+          "apiKey": "{env:GEMINI_API_KEY}"
+        },
+        "models": {}
+      };
+    }
 
-PROJECT OVERVIEW:
-${projectContext.overview || 'AI-assisted development project'}
+    if (providers.includes('openrouter')) {
+      config.openrouter = {
+        "options": {
+          "apiKey": "{env:OPENROUTER_API_KEY}"
+        },
+        "models": {}
+      };
+    }
 
-KEY REQUIREMENTS:
-${frameworkContext.keyPoints || '- Follow project structure\n- Maintain code quality\n- Write comprehensive tests'}
+    return config;
+  }
 
-OPERATIONAL RULES:
-1. Read project documentation in .adf/sessions/${this.getSessionId()}/outputs/
-2. Follow the workflow level: ${this.framework}
-3. All code changes must pass tests
-4. Never commit secrets or API keys
-5. Follow conventional commits format
+  /**
+   * Generate agent configurations based on ADF framework level
+   * Reference: https://opencode.ai/docs/agents
+   */
+  async generateAgentConfigurations(providers) {
+    const agents = {};
+    const agentsList = this.getAgentsList();
 
-BUILD & TEST:
-- Build: ${projectContext.buildCommand || 'npm run build'}
-- Test: ${projectContext.testCommand || 'npm test'}
-- Lint: ${projectContext.lintCommand || 'npm run lint'}
+    // Map ADF agents to OpenCode agents with optimal models
+    for (const agentName of agentsList) {
+      const agentConfig = this.getAgentConfig(agentName, providers);
+      agents[agentName] = agentConfig;
+    }
 
-Generated by ADF CLI v${this.getADFVersion()}`;
+    return agents;
   }
 
   /**
-   * Get agent role based on framework
+   * Get configuration for a specific agent
    */
-  getAgentRole() {
-    const roles = {
-      'rapid': 'a Rapid Development Engineer',
-      'balanced': 'a Senior Software Engineer',
-      'comprehensive': 'a Principal Solutions Architect'
+  getAgentConfig(agentName, providers) {
+    const agentDescriptions = {
+      'analyst': 'Business analyst for requirements and specifications',
+      'pm': 'Product manager for planning and prioritization',
+      'architect': 'Solutions architect for system design and architecture decisions',
+      'sm': 'Scrum master for agile workflow and team coordination',
+      'dev': 'Senior software engineer for implementation and coding',
+      'qa': 'QA engineer for testing and quality assurance'
+    };
+
+    const config = {
+      "description": agentDescriptions[agentName] || 'AI coding assistant',
+      "mode": agentName === 'dev' ? 'primary' : 'subagent',
+      "model": this.getOptimalModelForAgent(agentName, providers)
     };
-    return roles[this.framework] || 'an AI Coding Assistant';
+
+    // Agent-specific tool permissions
+    if (agentName === 'qa') {
+      config.tools = {
+        "write": false, // QA shouldn't write production code
+        "bash": true    // Can run tests
+      };
+    } else if (agentName === 'architect' || agentName === 'analyst') {
+      config.tools = {
+        "write": false, // Analysis/design agents don't write code
+        "edit": false,
+        "bash": false
+      };
+    }
+
+    return config;
   }
 
   /**
-   * Get model for coder agent based on framework
+   * Get optimal model for each agent type based on task complexity
    */
-  getCoderModel() {
-    const models = {
-      'rapid': 'anthropic/claude-3-5-sonnet-20241022',
-      'balanced': 'anthropic/claude-sonnet-4-5-20250929',
-      'comprehensive': 'anthropic/claude-opus-4-5-20251101'
+  getOptimalModelForAgent(agentName, providers) {
+    // Model selection strategy:
+    // - Powerful models: analyst, architect (deep thinking required)
+    // - Balanced models: pm, dev (main implementation)
+    // - Fast models: qa, sm (routine tasks)
+
+    const modelTiers = {
+      powerful: this.getPowerfulModel(providers),
+      balanced: this.getBalancedModel(providers),
+      fast: this.getFastModel(providers)
+    };
+
+    const agentModelMap = {
+      'analyst': modelTiers.powerful,
+      'architect': modelTiers.powerful,
+      'pm': modelTiers.balanced,
+      'dev': modelTiers.balanced,
+      'qa': modelTiers.fast,
+      'sm': modelTiers.fast
     };
-    return models[this.framework] || 'anthropic/claude-3-5-sonnet-20241022';
+
+    return agentModelMap[agentName] || modelTiers.balanced;
   }
 
   /**
-   * Get model for task agent
+   * Get the most powerful model from available providers
    */
-  getTaskModel() {
-    return 'anthropic/claude-3-5-haiku-20241022';
+  getPowerfulModel(providers) {
+    if (providers.includes('anthropic')) return 'anthropic/claude-sonnet-4-5-20250929';
+    if (providers.includes('openai')) return 'openai/gpt-5';
+    if (providers.includes('google')) return 'google/gemini-2.5-pro';
+    if (providers.includes('openrouter')) return 'openrouter/anthropic/claude-sonnet-4';
+    return 'anthropic/claude-sonnet-4-5-20250929'; // Default
   }
 
   /**
-   * Get framework display name
+   * Get a balanced model from available providers
    */
-  getFrameworkName() {
-    const names = {
-      'rapid': 'Rapid Development (PRP)',
-      'balanced': 'Balanced (Specification-Driven)',
-      'comprehensive': 'BMAD Comprehensive (Enterprise)'
-    };
-    return names[this.framework] || this.framework;
+  getBalancedModel(providers) {
+    if (providers.includes('anthropic')) return 'anthropic/claude-haiku-4-5-20250514';
+    if (providers.includes('openai')) return 'openai/gpt-4o';
+    if (providers.includes('google')) return 'google/gemini-1.5-pro';
+    if (providers.includes('openrouter')) return 'openrouter/anthropic/claude-haiku-4';
+    return 'anthropic/claude-haiku-4-5-20250514'; // Default
   }
 
   /**
-   * Get ADF CLI version
+   * Get the fastest/cheapest model from available providers
    */
-  getADFVersion() {
-    try {
-      const packageJson = require('../../package.json');
-      return packageJson.version;
-    } catch (error) {
-      return '0.12.0';
-    }
+  getFastModel(providers) {
+    if (providers.includes('anthropic')) return 'anthropic/claude-haiku-4-5-20250514';
+    if (providers.includes('openai')) return 'openai/gpt-4o-mini';
+    if (providers.includes('google')) return 'google/gemini-1.5-flash';
+    if (providers.includes('openrouter')) return 'openrouter/google/gemini-flash-1.5';
+    return 'anthropic/claude-haiku-4-5-20250514'; // Default
+  }
+
+  /**
+   * Get default model for OpenCode
+   */
+  getDefaultModel(providers) {
+    return this.getBalancedModel(providers);
+  }
+
+  /**
+   * Get default agent based on framework
+   */
+  getDefaultAgent() {
+    // Default to 'dev' agent as primary interaction point
+    return 'dev';
   }
 }
 

package/package.json

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