npm package: @iservu-inc/adf-cli
Description: CLI tool for AgentDevFramework - Agent-Native development framework with multi-provider AI support
Author: iServU
Latest version: 0.18.0

# @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 (Agent-Native)
adf init --rapid

# Level 2: Balanced (OpenSpec)
adf init --balanced

# Level 3: Comprehensive (Agent-Native)
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
```

#### Harness Mode (Long-Running Sessions)

Enable the harness protocol for multi-context-window sessions:

```bash
# Start with harness protocol
adf init --harness

# Headless mode for CI/automation
adf init --harness --headless

# Resume an existing harness run
adf init --run-id run_abc123
```

### Configure ADF Settings

Configure ADF settings like AI provider, AI analysis settings, learning system, and more:

```bash
adf config
```

This command provides an interactive menu with:
- **AI Provider Setup** - Configure Anthropic, OpenAI, Google Gemini, or OpenRouter
- **AI Analysis Settings** - Configure performance modes and AI features
- **IDE Deployment** - Deploy to multiple IDEs
- **Learning System** - Manage interview learning data and preferences
- Status indicators showing what's configured (green ✓), disabled (yellow ○), or has data

You can run `adf config` anytime to:
- Configure AI for the first time
- Switch AI providers or models
- Update your API keys
- Adjust AI analysis performance and features
- Deploy to development tools
- 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:**

**IDEs:**
- windsurf - Codeium Windsurf IDE
- cursor - Cursor AI IDE
- vscode - Visual Studio Code
- vscode-insider - VS Code Insider
- zed - Zed Editor
- antigravity - Google Antigravity

**CLI Tools:**
- claude-code - Anthropic Claude Code CLI
- opencode - OpenCode CLI
- gemini-cli - Google Gemini CLI
- deepagent - Abacus.ai DeepAgent
- generic - Generic AI tools

### 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
```

### Manage Long-Running Sessions (Harness)

The harness protocol enables long-running AI sessions across multiple context windows with cross-provider handoff:

```bash
# Start a new harness run
adf harness start --workflow balanced

# Check current run status
adf harness status

# Resume a paused run
adf harness resume

# Generate a handoff package for context window transfer
adf harness handoff

# View structured event log
adf harness events --stats

# View feature manifest and progress
adf harness manifest
```

**Key Features:**
- **Cross-Provider Handoff** - Start with Claude, resume with GPT or Gemini
- **Structured Event Logging** - JSONL audit trail with 12 event types
- **Milestone Tracking** - Question blocks mapped to trackable milestones
- **Feature Manifest** - Passes-only mutation for deliverable tracking
- **Headless Mode** - JSON-driven input for CI/CD automation
- **Provider Capability Registry** - Auto-adapts to provider context limits (200K-1M tokens)

### 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-4o, GPT-4o-mini, o1, 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 Filtering** - AI-powered question filtering based on context
- **Learning System** - Adapts to your preferences over time with pattern decay
- **Analytics Dashboard** - Comprehensive insights into time saved and learning health
- **Session Resume** - Pause and resume interviews anytime
- **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
- **Harness Protocol** - Long-running sessions across multiple context windows with cross-provider handoff

### 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.

## AI Analysis Settings

ADF CLI provides three performance modes and five configurable AI features, giving you complete control over the speed vs intelligence tradeoff during interviews.

### Performance Modes

Configure via `adf config` → AI Analysis Settings:

**Fast Mode:**
- Zero AI delays (~0.5s per answer)
- All AI features disabled
- Best for: Quick workflows, prototyping, low-priority projects

**Balanced Mode (Default):**
- 2-3 seconds per answer
- Quality Analysis, Smart Filtering, and Pattern Detection enabled
- Question Reordering and Follow-up Questions disabled
- Best for: Most projects - optimal balance of speed and intelligence

**Comprehensive Mode:**
- 4-6 seconds per answer
- All AI features enabled
- Maximum intelligence and guidance
- Best for: Complex projects, critical systems, maximum thoroughness

### Configurable AI Features

Five AI features can be toggled individually:

1. **AI-Powered Quality Analysis** (Medium Impact: 1-2s)
   - Real-time answer quality scoring (0-100)
   - Improvement suggestions for low-quality answers
   - Helps ensure comprehensive requirements gathering

2. **Intelligent Question Reordering** (High Impact: 2-3s)
   - Dynamically reorders questions based on extracted knowledge
   - Prioritizes fundamental questions first
   - Adapts interview flow to your answers

3. **AI-Generated Follow-Up Questions** (Medium Impact: 1-2s when triggered)
   - Context-specific follow-ups for incomplete answers
   - Only triggers for low-quality answers (< 70 score)
   - Helps gather missing information intelligently

4. **Pattern Detection & Learning** (Low Impact: minimal)
   - Learns from your skip behavior over time
   - Generates learned rules from patterns
   - Lightweight, runs locally

5. **Smart Question Filtering** (Low Impact: minimal)
   - Analyzes project type and context
   - Filters out irrelevant questions automatically
   - Saves time on specialized projects (CLI tools, APIs, etc.)

### Configuration

Access AI Analysis Settings:

```bash
adf config
# Select "AI Analysis Settings"
```

Settings are saved to `.adf/analysis-config.json` and apply to all future interviews.

**Performance Mode Display:**
At interview start, you'll see:
```
🎛️  AI Analysis Mode: Balanced
   (Configure via: adf config → AI Analysis Settings)
```

## 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. **Pattern Decay** - Automatically keeps patterns fresh and relevant:
   - Inactive patterns lose confidence over time using exponential decay
   - High-confidence patterns (≥90%) decay slower than weak patterns
   - Patterns reconfirmed by your behavior get +10 confidence boost
   - Stale patterns (confidence <40 or inactive 6+ months) automatically removed
   - User-approved patterns protected (decay at half rate)
5. **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)
│   ├── harness/             # Harness protocol data (when --harness enabled)
│   │   ├── current-run.json # Active run pointer
│   │   └── runs/            # Run data, context windows, events
│   ├── scripts/             # Helper scripts
│   └── shared/              # Templates, agents, and resources
│       ├── agents/          # Agent definition files
│       ├── templates/       # Agent-Native and OpenSpec 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,
    "openSpec": false
  }
}
```

## Workflow Levels

### Level 1: Rapid (Agent-Native)
- **Time:** 5-15 minutes planning
- **Agents:** dev, qa
- **Best for:** Solo developers, simple projects, prototyping
- **Templates:** Rapid story, Rapid task

### Level 2: Balanced (OpenSpec)
- **Time:** 30-60 minutes planning
- **Agents:** analyst, pm, dev, qa
- **Best for:** Small teams, moderate complexity, iterative requirements
- **Templates:** OpenSpec proposal, Spec deltas

### Level 3: Comprehensive (Agent-Native)
- **Time:** 1-2+ hours planning
- **Agents:** analyst, pm, architect, sm, dev, qa
- **Best for:** Large teams, complex systems, strategic orchestration
- **Templates:** Complete agent-native suite, 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.18.0 (2026-02-23)
- **Harness Engineering Protocol (v0.18.0)** - Minor release
  - ✨ **Long-Running Sessions** - Manage AI sessions across multiple context windows with structured handoff
  - ✨ **Cross-Provider Handoff** - Start a session with Claude, resume with GPT-5.2 or Gemini 3.1 Pro
  - ✨ **Headless/CI Mode** - JSON-driven automation for CI/CD pipelines
  - ✨ **Structured Event Logging** - JSONL audit trail with 12 event types
  - ✨ **Provider Capability Registry** - Auto-adapts to Anthropic (200K/1M), OpenAI (400K), Google (1M)
  - ✨ **New Commands** - `adf harness start|resume|status|handoff|events|manifest`

**Previous Releases:**
- **v0.17.5 (2025-12-23)** - A2A protocol integration, template sync, question consolidation
- **v0.16.0 (2026-01-21)** - Custom artifact import, learning rules exchange
- **v0.15.0 (2026-01-13)** - Advanced Learning Analytics Dashboard
- **v0.14.0 (2026-01-12)** - Project Context Synthesis & Extended Tool Support

- **v0.10.0 (2025-10-27)** - Pattern Decay Algorithm
  - Time-based exponential decay for inactive patterns
  - Confidence-based decay rates (high/medium/low)
  - Automatic pattern cleanup and renewal system
  - 40+ comprehensive tests for decay functionality

- **v0.9.1 (2025-10-05)** - AI Analysis Settings
- **AI Analysis Settings (v0.9.0)** - Performance modes and configurable AI features
  - Three performance modes: Fast, Balanced, Comprehensive
  - Five individually configurable AI features
  - Complete control over speed vs intelligence tradeoff
  - New configuration category in `adf config`
  - Performance mode display at interview start
- **Resume from Exit (v0.8.0)** - Resume interviews after exit
  - Type `exit` or press Ctrl+C to save progress and quit
  - Resume with `adf init` continues from last question
  - Already-answered questions automatically skipped
  - Graceful quit handling everywhere
- **UX Improvements (v0.5.1-v0.7.1)** - Enhanced user experience
  - Terminal input restoration (v0.7.1)
  - Better existing project detection with clear options
  - Post-install information display
  - Configuration validation and auto-reset

**Previous Releases:**
- **v0.5.0** - Intelligent Answer Analysis & Dynamic Question Pipeline
- **v0.4.36** - Multi-IDE Improvements & Config Command Enhancement
- **v0.4.12** - Learning System (Phase 4.2) & Smart Question Filtering (Phase 4.1)
- **v0.3.6** - Configuration Command & Optional AI Setup
- **v0.3.4** - Multi-Provider AI Integration (Anthropic, OpenAI, Google, OpenRouter)
- **v0.2.0** - Quality-Based Progress Tracking & Resume Capability
- **v0.1.0** - Initial Release

## 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