@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)

npm install -g @iservu-inc/adf-cli

One-time Use (npx)

npx @iservu-inc/adf-cli init

Usage

Initialize Framework

Initialize AgentDevFramework in your current project:

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:

# 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:

adf init --tool windsurf
adf init --rapid --tool cursor

Harness Mode (Long-Running Sessions)

Enable the harness protocol for multi-context-window sessions:

# 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:

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:

# 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:

# Check and update interactively
adf update

# Check version only (don't install)
adf update --check

Or update directly:

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:

# 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:

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:

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:

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:

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:

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:

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:

{
  "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)

# 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

# Navigate to your project
cd my-existing-project

# Initialize (interactive workflow selection)
adf init

# Follow prompts to select workflow and deployment tool

Enterprise Setup

# 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:

   adf update --check

2. Install update:

   adf update

   Or directly:

   npm update -g @iservu-inc/adf-cli

3. Re-initialize your project (optional, for major updates):

   adf init
   # Confirm overwrite when prompted

Version History

See 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:

   npm config get prefix

2. Reinstall globally:

   npm uninstall -g @iservu-inc/adf-cli
   npm install -g @iservu-inc/adf-cli

Permission errors (Linux/macOS)

sudo npm install -g @iservu-inc/adf-cli

Or configure npm to install globally without sudo:

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