@iservu-inc/adf-cli 0.3.0 → 0.4.12

package/README.md

@@ -1,292 +1,476 @@
-# @iservu-inc/adf-cli
-
-CLI tool for AgentDevFramework - AI-assisted development framework.
-
-## Installation
-
-### Global Installation (Recommended)
-
-```bash
-npm install -g @iservu-inc/adf-cli
-```
-
-### One-time Use (npx)
-
-```bash
-npx @iservu-inc/adf-cli init
-```
-
-## Usage
-
-### Initialize Framework
-
-Initialize AgentDevFramework in your current project:
-
-```bash
-adf init
-```
-
-The interactive init process will:
-1. Detect if this is a new or existing project
-2. Ask questions to recommend the best workflow level
-3. Optionally collect documentation URLs (e.g., API docs, design docs)
-4. Optionally collect local documentation file paths (e.g., `./docs/`, `./README.md`)
-5. Offer to deploy to your preferred development tool
-
-#### Workflow Selection Options
-
-Skip interactive questions and specify workflow directly:
-
-```bash
-# Level 1: Rapid Development (PRP)
-adf init --rapid
-
-# Level 2: Specification-Driven (Balanced)
-adf init --balanced
-
-# Level 3: BMAD Comprehensive
-adf init --comprehensive
-```
-
-#### Direct Tool Deployment
-
-Initialize and deploy to a specific tool in one command:
-
-```bash
-adf init --tool windsurf
-adf init --rapid --tool cursor
-```
-
-### Deploy to Development Tool
-
-Deploy framework configuration to your development tool:
-
-```bash
-# Deploy to specific tool
-adf deploy windsurf
-adf deploy cursor
-adf deploy vscode
-
-# List available tools
-adf deploy --list
-```
-
-**Supported Tools:**
-- windsurf
-- cursor
-- vscode
-- vscode-insider
-- kiro
-- trae
-- claude-code
-- gemini-cli
-- codex-cli
-
-### Update CLI
-
-Check for and install updates:
-
-```bash
-# Check and update interactively
-adf update
-
-# Check version only (don't install)
-adf update --check
-```
-
-Or update directly:
-
-```bash
-npm update -g @iservu-inc/adf-cli
-```
-
-### Version
-
-Check installed version:
-
-```bash
-adf --version
-adf -v
-```
-
-## What Gets Installed
-
-When you run `adf init`, the following structure is created in your project:
-
-```
-your-project/
-├── .adf/                    # Framework files (isolated)
-│   ├── context.json         # Your workflow configuration
-│   ├── scripts/             # Helper scripts
-│   └── shared/              # Templates, agents, and resources
-│       ├── agents/          # Agent definition files
-│       ├── templates/       # PRP, BMAD, Spec-Kit templates
-│       ├── mcp/             # MCP configurations
-│       └── memory/          # Framework memory/constitution
-├── .framework/              # Deployment directory
-│   └── agents/              # Deployed agent files for your tool
-├── .env.template            # Environment variables template
-├── .[tool]rules             # Tool-specific config (e.g., .windsurfrules)
-└── [your existing files]    # Completely untouched!
-```
-
-**Important:** Your `package.json` and existing project files remain completely untouched.
-
-### context.json Structure
-
-The `.adf/context.json` file contains your workflow configuration:
-
-```json
-{
-  "version": "0.1.6",
-  "workflow": "rapid",
-  "projectType": "existing",
-  "documentationUrls": [
-    "https://api.example.com/docs"
-  ],
-  "documentationFiles": [
-    "./docs/",
-    "./README.md"
-  ],
-  "createdAt": "2025-10-02T...",
-  "agents": ["dev", "qa"],
-  "templates": {
-    "prp": ["prp_story.md", "prp_task.md"],
-    "bmad": false,
-    "specKit": false
-  }
-}
-```
-
-## Workflow Levels
-
-### Level 1: Rapid Development (PRP)
-- **Time:** 5-15 minutes planning
-- **Agents:** dev, qa
-- **Best for:** Solo developers, simple projects, prototyping
-- **Templates:** PRP story, PRP task
-
-### Level 2: Specification-Driven (Balanced)
-- **Time:** 30-60 minutes planning
-- **Agents:** analyst, pm, dev, qa
-- **Best for:** Small teams, moderate complexity
-- **Templates:** Full PRP suite, spec templates
-
-### Level 3: BMAD Comprehensive
-- **Time:** 1-2+ hours planning
-- **Agents:** analyst, pm, architect, sm, dev, qa
-- **Best for:** Large teams, complex systems, strategic planning
-- **Templates:** Complete BMAD framework, governance tools
-
-## Examples
-
-### Quick Start (New Project)
-
-```bash
-# Create new project directory
-mkdir my-new-project
-cd my-new-project
-
-# Initialize with Rapid workflow
-adf init --rapid
-
-# Deploy to Cursor
-adf deploy cursor
-```
-
-### Existing Project
-
-```bash
-# Navigate to your project
-cd my-existing-project
-
-# Initialize (interactive workflow selection)
-adf init
-
-# Follow prompts to select workflow and deployment tool
-```
-
-### Enterprise Setup
-
-```bash
-# Initialize with comprehensive workflow
-adf init --comprehensive
-
-# Deploy to multiple tools
-adf deploy windsurf
-adf deploy vscode
-```
-
-## Updating Framework Files
-
-When we release updates to the framework:
-
-1. **Check for updates:**
-   ```bash
-   adf update --check
-   ```
-
-2. **Install update:**
-   ```bash
-   adf update
-   ```
-
-   Or directly:
-   ```bash
-   npm update -g @iservu-inc/adf-cli
-   ```
-
-3. **Re-initialize your project** (optional, for major updates):
-   ```bash
-   adf init
-   # Confirm overwrite when prompted
-   ```
-
-## Version History
-
-See [CHANGELOG.md](./CHANGELOG.md) for detailed version history.
-
-**Latest:** v0.1.6
-- Fixed step numbering in init success message
-- Added local documentation files collection
-- Dynamic version tracking in context.json
-- Improved error handling
-
-## Troubleshooting
-
-### Command not found
-
-If `adf` command is not found after installation:
-
-1. Check global npm bin directory is in PATH:
-   ```bash
-   npm config get prefix
-   ```
-
-2. Reinstall globally:
-   ```bash
-   npm uninstall -g @iservu-inc/adf-cli
-   npm install -g @iservu-inc/adf-cli
-   ```
-
-### Permission errors (Linux/macOS)
-
-```bash
-sudo npm install -g @iservu-inc/adf-cli
-```
-
-Or configure npm to install globally without sudo:
-```bash
-npm config set prefix ~/.npm-global
-# Add ~/.npm-global/bin to PATH
-```
-
-## Support
-
-For issues, questions, or contributions:
-- GitHub: https://github.com/iservu/adf-cli
-- Issues: https://github.com/iservu/adf-cli/issues
-
-## License
-
-MIT © iServU
+# @iservu-inc/adf-cli
+
+CLI tool for AgentDevFramework - AI-assisted development framework with multi-provider AI support.
+
+Transform your development workflow with AI-guided requirements gathering using Anthropic Claude, OpenAI GPT, Google Gemini, or OpenRouter.
+
+## Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g @iservu-inc/adf-cli
+```
+
+### One-time Use (npx)
+
+```bash
+npx @iservu-inc/adf-cli init
+```
+
+## Usage
+
+### Initialize Framework
+
+Initialize AgentDevFramework in your current project:
+
+```bash
+adf init
+```
+
+The interactive init process will:
+1. Optionally configure AI Provider (or use `adf config` later)
+2. Detect if this is a new or existing project
+3. Ask AI-guided questions to gather requirements
+4. Optionally collect documentation URLs (e.g., API docs, design docs)
+5. Optionally collect local documentation file paths (e.g., `./docs/`, `./README.md`)
+6. Automatically deploy to your preferred development tool
+
+#### Workflow Selection Options
+
+Skip interactive questions and specify workflow directly:
+
+```bash
+# Level 1: Rapid Development (PRP)
+adf init --rapid
+
+# Level 2: Specification-Driven (Balanced)
+adf init --balanced
+
+# Level 3: BMAD Comprehensive
+adf init --comprehensive
+```
+
+#### Direct Tool Deployment
+
+Initialize and deploy to a specific tool in one command:
+
+```bash
+adf init --tool windsurf
+adf init --rapid --tool cursor
+```
+
+### Configure ADF Settings
+
+Configure ADF settings like AI provider, learning system, and more:
+
+```bash
+adf config
+```
+
+This command provides an interactive menu with:
+- **AI Provider Setup** - Configure Anthropic, OpenAI, Google Gemini, or OpenRouter
+- **Learning System** - Manage interview learning data and preferences
+- Status indicators showing what's configured (green ✓), disabled (yellow ○), or has data
+- Future configuration options (coming soon)
+
+You can run `adf config` anytime to:
+- Configure AI for the first time
+- Switch AI providers or models
+- Update your API keys
+- Review learning patterns and manage learned preferences
+
+### Deploy to Development Tool
+
+Deploy framework configuration to your development tool:
+
+```bash
+# Deploy to specific tool
+adf deploy windsurf
+adf deploy cursor
+adf deploy vscode
+
+# List available tools
+adf deploy --list
+```
+
+**Supported Tools:**
+- windsurf
+- cursor
+- vscode
+- vscode-insider
+- kiro
+- trae
+- claude-code
+- gemini-cli
+- codex-cli
+
+### Update CLI
+
+Check for and install updates:
+
+```bash
+# Check and update interactively
+adf update
+
+# Check version only (don't install)
+adf update --check
+```
+
+Or update directly:
+
+```bash
+npm update -g @iservu-inc/adf-cli
+```
+
+### Version
+
+Check installed version:
+
+```bash
+adf --version
+adf -v
+```
+
+## AI Provider Configuration
+
+ADF CLI requires an AI provider to guide you through requirements gathering with intelligent follow-up questions and answer quality analysis.
+
+### Supported AI Providers
+
+- **Anthropic Claude** (Claude 3.5 Sonnet, Claude 3 Opus, etc.)
+- **OpenAI** (GPT-4, GPT-4 Turbo, GPT-3.5 Turbo, etc.)
+- **Google Gemini** (Gemini 1.5 Pro, Gemini 1.5 Flash, etc.)
+- **OpenRouter** (Access to 100+ models from multiple providers)
+
+### API Key Setup
+
+Configure your AI provider using the config command:
+
+```bash
+adf config
+```
+
+Then select "AI Provider Setup" to:
+
+1. **Select your AI provider** from the list above
+2. **Enter your API key** (securely saved to `.adf/.env`)
+3. **Choose a model** with type-to-filter autocomplete
+
+Your API key is stored locally in `.adf/.env` and never leaves your machine.
+
+**Note:** You can also configure AI during `adf init`, or skip it and configure later.
+
+**Example `.adf/.env` file:**
+```env
+ANTHROPIC_API_KEY=sk-ant-api03-...
+```
+
+### Getting API Keys
+
+- **Anthropic:** https://console.anthropic.com/
+- **OpenAI:** https://platform.openai.com/api-keys
+- **Google Gemini:** https://ai.google.dev/
+- **OpenRouter:** https://openrouter.ai/keys
+
+### AI-Powered Features
+
+The AI provider enhances your workflow by:
+
+- **Smart Question Filtering** - Automatically analyzes your project and skips irrelevant questions (e.g., UI questions for CLI tools)
+- **Learning System** - Learns from your skip behavior to improve filtering over time:
+  - Automatically detects patterns in skipped questions across sessions
+  - Generates learned rules from high-confidence patterns (75%+)
+  - Applies your preferences in future interviews with your approval
+  - Privacy-first design: all data stored locally in `.adf/learning/`
+  - Manage via `adf config` → Learning System
+- **Real-Time Answer Quality Analysis** - Scores your answers 0-100
+- **Intelligent Follow-Up Questions** - Automatically generated based on your responses
+- **Context-Aware Guidance** - Tailored suggestions for your project type
+- **Skip Functionality** - Type "skip" anytime to move forward
+
+### Changing Providers
+
+To switch AI providers or models:
+
+```bash
+adf config
+```
+
+Select "AI Provider Setup" and you'll see:
+- ✓ **Configured** status with current provider name
+- Option to reconfigure with a new provider or model
+
+Your previous API keys remain saved in `.adf/.env` for easy switching between providers.
+
+## Learning System
+
+ADF CLI includes an intelligent Learning System that improves your interview experience by learning from your behavior across sessions.
+
+### How It Works
+
+1. **Automatic Tracking** - Silently tracks your skip and answer patterns during interviews
+2. **Pattern Detection** - Analyzes your history to identify consistent preferences:
+   - Questions you always skip (e.g., deployment questions for prototype projects)
+   - Categories you frequently skip (e.g., UI questions for CLI tools)
+   - Framework-specific skips (e.g., routing questions for Next.js projects)
+   - Answer style preferences (brief vs detailed)
+3. **Rule Generation** - Converts high-confidence patterns (≥75%) into learned rules
+4. **Adaptive Filtering** - Applies learned rules in future interviews (with your approval)
+
+### Managing Learning Data
+
+Access the Learning System via:
+
+```bash
+adf config
+# Select "Learning System"
+```
+
+**Available Options:**
+
+- **View Skip History** - See most skipped questions and categories across all sessions
+- **Review Patterns** - View detected patterns by confidence level (high/medium/low)
+- **Manage Rules** - Enable, disable, or remove individual learned rules
+- **Settings** - Configure learning system behavior:
+  - Enable/disable learning system
+  - Toggle tracking, pattern detection, and filter application
+  - Adjust confidence thresholds
+  - Reset to defaults
+- **Clear Data** - Delete all learning data with confirmation
+
+### Privacy & Control
+
+- **Local Storage** - All learning data stored in `.adf/learning/` (never transmitted externally)
+- **Transparent** - View all tracked data, patterns, and rules anytime
+- **User Control** - Multiple layers:
+  - System-level: Enable/disable entire learning system
+  - Feature-level: Toggle tracking, detection, and filtering separately
+  - Rule-level: Enable/disable individual learned rules
+  - Session-level: Approve learned preferences before each interview
+- **No Surprises** - Learning system shows preview of rules before applying them
+
+### Learning Data Structure
+
+The `.adf/learning/` directory contains:
+
+```
+.adf/learning/
+├── skip-history.json       # Skip events from all sessions
+├── answer-history.json     # Answer metadata from all sessions
+├── patterns.json           # Detected patterns
+├── learned-rules.json      # Active learned rules
+├── config.json             # Learning system settings
+└── stats.json              # Learning statistics
+```
+
+### Example Workflow
+
+1. **First Interview** - Skip deployment questions because you're building a prototype
+2. **Second Interview** - Skip same deployment questions again
+3. **Third Interview** - Skip deployment questions once more
+4. **Pattern Detected** - System recognizes consistent skip pattern (100% confidence)
+5. **Rule Generated** - Creates learned rule to auto-filter deployment questions
+6. **Next Interview** - System prompts: "I've learned you typically skip deployment questions. Apply this preference?"
+7. **Your Choice** - Approve to save time, or decline to answer deployment questions this time
+
+## What Gets Installed
+
+When you run `adf init`, the following structure is created in your project:
+
+```
+your-project/
+├── .adf/                    # Framework files (isolated)
+│   ├── .env                 # AI provider API keys (gitignored, secure)
+│   ├── context.json         # Your workflow configuration
+│   ├── sessions/            # Requirements gathering sessions
+│   ├── learning/            # Learning system data (skip history, patterns, rules)
+│   ├── scripts/             # Helper scripts
+│   └── shared/              # Templates, agents, and resources
+│       ├── agents/          # Agent definition files
+│       ├── templates/       # PRP, BMAD, Spec-Kit templates
+│       ├── mcp/             # MCP configurations
+│       └── memory/          # Framework memory/constitution
+├── .framework/              # Deployment directory
+│   └── agents/              # Deployed agent files for your tool
+├── .env.template            # Environment variables template
+├── .[tool]rules             # Tool-specific config (e.g., .windsurfrules)
+└── [your existing files]    # Completely untouched!
+```
+
+**Important:** Your `package.json` and existing project files remain completely untouched.
+
+### context.json Structure
+
+The `.adf/context.json` file contains your workflow configuration:
+
+```json
+{
+  "version": "0.1.6",
+  "workflow": "rapid",
+  "projectType": "existing",
+  "documentationUrls": [
+    "https://api.example.com/docs"
+  ],
+  "documentationFiles": [
+    "./docs/",
+    "./README.md"
+  ],
+  "createdAt": "2025-10-02T...",
+  "agents": ["dev", "qa"],
+  "templates": {
+    "prp": ["prp_story.md", "prp_task.md"],
+    "bmad": false,
+    "specKit": false
+  }
+}
+```
+
+## Workflow Levels
+
+### Level 1: Rapid Development (PRP)
+- **Time:** 5-15 minutes planning
+- **Agents:** dev, qa
+- **Best for:** Solo developers, simple projects, prototyping
+- **Templates:** PRP story, PRP task
+
+### Level 2: Specification-Driven (Balanced)
+- **Time:** 30-60 minutes planning
+- **Agents:** analyst, pm, dev, qa
+- **Best for:** Small teams, moderate complexity
+- **Templates:** Full PRP suite, spec templates
+
+### Level 3: BMAD Comprehensive
+- **Time:** 1-2+ hours planning
+- **Agents:** analyst, pm, architect, sm, dev, qa
+- **Best for:** Large teams, complex systems, strategic planning
+- **Templates:** Complete BMAD framework, governance tools
+
+## Examples
+
+### Quick Start (New Project)
+
+```bash
+# Create new project directory
+mkdir my-new-project
+cd my-new-project
+
+# Initialize with Rapid workflow
+adf init --rapid
+
+# Deploy to Cursor
+adf deploy cursor
+```
+
+### Existing Project
+
+```bash
+# Navigate to your project
+cd my-existing-project
+
+# Initialize (interactive workflow selection)
+adf init
+
+# Follow prompts to select workflow and deployment tool
+```
+
+### Enterprise Setup
+
+```bash
+# Initialize with comprehensive workflow
+adf init --comprehensive
+
+# Deploy to multiple tools
+adf deploy windsurf
+adf deploy vscode
+```
+
+## Updating Framework Files
+
+When we release updates to the framework:
+
+1. **Check for updates:**
+   ```bash
+   adf update --check
+   ```
+
+2. **Install update:**
+   ```bash
+   adf update
+   ```
+
+   Or directly:
+   ```bash
+   npm update -g @iservu-inc/adf-cli
+   ```
+
+3. **Re-initialize your project** (optional, for major updates):
+   ```bash
+   adf init
+   # Confirm overwrite when prompted
+   ```
+
+## Version History
+
+See [CHANGELOG.md](./CHANGELOG.md) for detailed version history.
+
+**Latest:** v0.4.12
+- **Learning System (Phase 4.2)** - Learns from your skip behavior to improve filtering
+  - Automatic pattern detection across interview sessions
+  - Learned rule generation from high-confidence patterns
+  - Adaptive filtering with user approval
+  - Learning management CLI via `adf config`
+  - Privacy-first local storage in `.adf/learning/`
+- **Smart Question Filtering (Phase 4.1)** - Context-aware question filtering
+  - Project analysis (type, frameworks, languages)
+  - Intelligent question relevance scoring
+  - Time estimation for skipped questions
+  - User control with confidence thresholds
+- Enhanced config command with Learning System integration
+
+**Previous:** v0.3.6
+- AI-guided requirements gathering with multi-provider support
+- Real-time answer quality analysis and intelligent follow-ups
+- Secure API key persistence in `.adf/.env`
+- Dynamic model fetching with autocomplete selection
+- Enhanced UX with visible skip instructions
+- Automatic deployment to your preferred IDE
+
+## Troubleshooting
+
+### Command not found
+
+If `adf` command is not found after installation:
+
+1. Check global npm bin directory is in PATH:
+   ```bash
+   npm config get prefix
+   ```
+
+2. Reinstall globally:
+   ```bash
+   npm uninstall -g @iservu-inc/adf-cli
+   npm install -g @iservu-inc/adf-cli
+   ```
+
+### Permission errors (Linux/macOS)
+
+```bash
+sudo npm install -g @iservu-inc/adf-cli
+```
+
+Or configure npm to install globally without sudo:
+```bash
+npm config set prefix ~/.npm-global
+# Add ~/.npm-global/bin to PATH
+```
+
+## Support
+
+For issues, questions, or contributions:
+- GitHub: https://github.com/iservu/adf-cli
+- Issues: https://github.com/iservu/adf-cli/issues
+
+## License
+
+MIT © iServU