@iservu-inc/adf-cli 0.11.0 → 0.12.9

package/.adf/learning/stats.json

@@ -0,0 +1,9 @@
+{
+  "version": "1.0",
+  "totalSessions": 12,
+  "totalSkips": 114,
+  "totalAnswers": 66,
+  "patternsDetected": 15,
+  "rulesApplied": 6,
+  "lastUpdated": "2025-11-04T11:13:36.502Z"
+}

package/.claude/settings.local.json

@@ -2,15 +2,22 @@
   "permissions": {
     "allow": [
       "Bash(npm test:*)",
-      "Bash(git commit -m \"$(cat <<''EOF''\ndocs: Update documentation for v0.10.0 release\n\n- Updated CHANGELOG.md with comprehensive v0.10.0 entry\n  * Pattern Decay Algorithm documentation\n  * Technical implementation details\n  * Use cases and examples\n  * Test coverage information\n  \n- Updated README.md version history\n  * Added v0.10.0 as latest release\n  * Pattern decay feature highlights\n  \n- Updated SESSION-STATUS.md\n  * Current version: v0.10.0\n  * Latest achievements and test coverage\n  * Phase 6 status\n  \n- Fixed test export issues in pattern-detector.js\n  * Added standalone function exports for testing\n  * Fixed applyDecayToStoredPatterns return value\n  \n- Fixed decay-manager.js config handling\n  * Use default config when decayConfig not initialized\n  * Prevents null reference errors in tests\n\nTest Status: 231/239 passing (96.7%)\n- Core decay functionality fully working\n- 8 edge case failures in Date mocking (to fix in v0.10.1)\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nEOF\n)\")",
-      "Bash(npm publish)",
-      "mcp__archon__find_projects",
-      "mcp__archon__find_tasks",
+      "Bash(npm publish:*)",
       "Bash(npm view:*)",
+      "Bash(npm config:*)",
       "Bash(git add:*)",
       "Bash(git commit:*)",
       "Bash(git tag:*)",
-      "Bash(git push:*)"
+      "Bash(git push:*)",
+      "mcp__archon__find_projects",
+      "mcp__archon__find_tasks",
+      "Bash(adf doctor:*)",
+      "Bash(adf --help:*)",
+      "Bash(claude doctor)",
+      "WebFetch(domain:openrouter.ai)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:antigravity.google)",
+      "WebSearch"
     ],
     "deny": [],
     "ask": []

package/CHANGELOG.md

@@ -5,6 +5,116 @@ 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.12.0] - 2025-12-22
+
+### 🎯 Agent-Native Development Framework (ANDF) Standard Implementation
+
+**MAJOR FEATURE:** Complete implementation of the ANDF specification, bringing industry-standard AI agent configuration to ADF CLI with enhanced IDE support.
+
+#### What's New
+
+**AGENTS.md Standard Compliance:**
+- **YAML Frontmatter** - Agent metadata with `name`, `description`, and `tools` fields
+- **MCP Tools Configuration** - Model Context Protocol server integration (project_context, archon)
+- **Structured Sections** - 8 ANDF-compliant sections for consistent AI agent guidance
+  - § 1: Operational Rules (High Priority)
+  - § 2: Build & Test Commands
+  - § 3: Project Structure
+  - § 4: Workflow Directives
+  - § 5-8: Framework-specific content (PRP/Balanced/BMAD)
+- **Auto-Discovery** - Next-generation AI tools automatically detect and consume AGENTS.md
+
+**.context/ Directory Support:**
+- **Context Manager** - New utility for managing agent-accessible deep context
+- **architecture.md** - Auto-generated system architecture from session outputs
+  - PRP: Extracts goal, context intelligence, and blueprint
+  - Balanced: Combines specification, plan, and constitution
+  - BMAD: Uses existing architecture or generates from PRD
+- **glossary.md** - Automatically extracts domain terminology from interview transcripts
+- **MCP Access** - Files accessible via Model Context Protocol filesystem server
+
+**Zed Editor Support (NEW):**
+- **Full Generator** - Complete Zed editor configuration generation
+- **MCP Integration** - Context servers configured (project_context, archon)
+- **Agent Configuration** - Model selection based on framework complexity
+  - Rapid: Claude Sonnet + Gemini Flash
+  - Balanced: Mixed models for optimization
+  - Comprehensive: Premium models (Claude Sonnet, Gemini Exp)
+- **Keymap Support** - Agent switching shortcuts (Ctrl+Shift+A, Ctrl+Enter, etc.)
+- **Symlink Strategy** - `.zed/rules -> ../AGENTS.md` (Unix/Mac) with Windows fallback
+
+**Google Antigravity Support (NOW IMPLEMENTED):**
+- **Full Generator** - Complete Antigravity agent configuration
+- **YAML Configuration** - `.antigravity/agents.yaml` with AGENTS.md mount
+- **File System Access** - Read-only access to AGENTS.md, .context/, and sessions
+- **Security** - Excludes sensitive files (.env, node_modules, .git)
+- **Smart System Prompt** - Instructs agent to read AGENTS.md immediately on startup
+- **Model Selection** - Gemini models based on framework (Flash/Thinking/Exp)
+
+#### Enhanced Features
+
+**All Original IDE Support Maintained:**
+- ✅ Windsurf - Full generator (unchanged)
+- ✅ Cursor - Full generator (unchanged)
+- ✅ VS Code / VS Code Insider - Full generator (unchanged)
+- ✅ Kiro, Trae, Claude Code, Gemini CLI, Codex CLI - Generic configs (unchanged)
+- ✅ **Zed** - NEW full generator
+- ✅ **Antigravity** - NEW full generator (previously listed, now implemented)
+
+**Deployment Enhancements:**
+- `.context/` directory created automatically on all deployments
+- AGENTS.md generated with ANDF compliance for all frameworks
+- Architecture and glossary populated from interview data
+- All 11 IDE tools supported with enhanced configurations
+
+#### Technical Details
+
+**New Files:**
+- `lib/utils/context-manager.js` - Context directory management (500+ lines)
+- `lib/generators/zed-generator.js` - Zed editor configurations (250+ lines)
+- `lib/generators/antigravity-generator.js` - Antigravity configurations (150+ lines)
+
+**Modified Files:**
+- `lib/generators/agents-md-generator.js` - ANDF compliance implementation (~250 lines added)
+- `lib/generators/index.js` - Export new generators
+- `lib/commands/deploy.js` - Integrate context manager and new generators
+- `tests/agents-md-generator.test.js` - Updated for ANDF format
+
+**Documentation:**
+- `CLAUDE.md` - Added comprehensive ANDF architecture section
+- `.adf/feature-audit.md` - Feature comparison and gaps analysis
+- `.adf/implementation-plan.md` - Implementation roadmap
+- `.adf/final-summary.md` - Complete implementation summary
+
+#### Keywords Added
+- `zed` - Zed Editor support
+- `antigravity` - Google Antigravity support
+- `andf` - Agent-Native Development Framework
+- `agents-md` - AGENTS.md standard
+- `mcp` - Model Context Protocol
+
+#### Backward Compatibility
+- ✅ **100% Backward Compatible** - All changes are additive
+- ✅ All existing IDE deployments continue to work
+- ✅ No breaking changes to API or CLI commands
+- ✅ Existing sessions and learning data unaffected
+
+#### Upgrade Path
+No migration needed. Simply upgrade and run:
+```bash
+npm update -g @iservu-inc/adf-cli
+adf deploy <tool>  # Now includes ANDF features
+```
+
+#### Benefits
+- **Industry Standard** - AGENTS.md follows emerging ANDF specification
+- **Better AI Guidance** - Structured operational rules and workflow directives
+- **Deep Context** - Architecture and terminology preserved for AI agents
+- **Expanded IDE Support** - 11 total IDEs (2 new full generators)
+- **MCP Ready** - Integrated with Model Context Protocol for next-gen tools
+
+---
+
 ## [0.11.0] - 2025-11-04
 
 ### 📊 Learning Analytics Dashboard - Phase 6.2

package/CLAUDE.md

@@ -0,0 +1,479 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ADF CLI (`@iservu-inc/adf-cli`) is a Node.js CLI tool for AgentDevFramework - an AI-assisted development framework that helps developers gather requirements through intelligent AI-guided interviews. It supports multiple AI providers (Anthropic, OpenAI, Google Gemini, OpenRouter) and deploys workflow configurations to various development tools (Windsurf, Cursor, VS Code, Claude Code, etc.).
+
+**Key Features:**
+- Multi-provider AI integration for intelligent requirements gathering
+- Three workflow levels: Rapid (PRP), Balanced (Spec-Kit), Comprehensive (BMAD)
+- Learning system that adapts to user preferences over time with pattern decay
+- Dynamic question pipeline that extracts knowledge and reorders questions
+- Smart question filtering based on project context
+- Multi-IDE deployment support
+- Session management with resume capability
+- Analytics dashboard for learning system insights
+
+## Development Commands
+
+### Testing
+```bash
+# Run all tests with coverage
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+**Test Configuration:**
+- Tests located in `tests/` directory
+- Test files use pattern `*.test.js`
+- Jest configuration in `jest.config.js`
+- Coverage thresholds: 60% branches, 70% functions/lines/statements
+- Test timeout: 10 seconds
+
+### Local Development
+```bash
+# Install dependencies
+npm install
+
+# Link globally for local testing
+npm link
+
+# Test CLI commands locally
+adf init
+adf config
+adf deploy --list
+adf update --check
+
+# Unlink when done
+npm unlink -g @iservu-inc/adf-cli
+```
+
+### Publishing
+```bash
+# Pre-publish validation runs automatically
+npm publish
+
+# Dry run to see what would be published
+npm publish --dry-run
+```
+
+**Note:** The `prepublishOnly` script runs `lib/utils/pre-publish-check.js` to validate the package before publishing.
+
+## Architecture
+
+### Core System Flow
+
+1. **Entry Point** (`bin/adf.js`)
+   - Commander.js-based CLI with 4 main commands: init, config, deploy, update
+   - Routes to command handlers in `lib/commands/`
+
+2. **Commands** (`lib/commands/`)
+   - `init.js` - Initialize framework, detect project, start interview session
+   - `config.js` - Configure AI provider, analysis settings, learning system
+   - `deploy.js` - Deploy to development tools (Windsurf, Cursor, VS Code, etc.)
+   - `update.js` - Check for and install CLI updates
+
+3. **Interview System** (`lib/frameworks/`)
+   - `interviewer.js` - Main interview orchestrator with AI integration
+   - `questions.js` - Framework-specific question definitions (PRP, Balanced, BMAD)
+   - `session-manager.js` - Session persistence and resume capability
+   - `progress-tracker.js` - Quality-based progress tracking
+   - `answer-quality-analyzer.js` - Real-time answer quality scoring
+   - `output-generators.js` - Generate PRD, specs, stories from answers
+
+4. **AI Layer** (`lib/ai/`)
+   - `ai-client.js` - Unified interface for Anthropic, OpenAI, Google, OpenRouter
+   - `ai-config.js` - AI provider configuration and API key management
+   - `analysis-config.js` - Performance modes (Fast/Balanced/Comprehensive) and feature toggles
+
+5. **Analysis Pipeline** (`lib/analysis/`)
+   - `dynamic-pipeline.js` - Orchestrates intelligent question system
+   - `answer-analyzer.js` - Extracts structured information from answers
+   - `knowledge-graph.js` - Builds knowledge graph from extracted info
+   - `question-mapper.js` - Maps knowledge to questions for filtering/reordering
+
+6. **Learning System** (`lib/learning/`)
+   - `skip-tracker.js` - Tracks user skip behavior across sessions
+   - `pattern-detector.js` - Detects patterns in skip/answer history
+   - `decay-manager.js` - Applies time-based decay to pattern confidence
+   - `rule-generator.js` - Converts patterns to learned rules
+   - `learning-manager.js` - Orchestrates learning system operations
+   - `analytics.js` - Generates comprehensive analytics (680 lines)
+   - `analytics-view.js` - CLI dashboard for analytics visualization (530 lines)
+   - `analytics-exporter.js` - Export analytics to JSON/CSV (240 lines)
+   - `storage.js` - Persistent storage for learning data
+
+7. **Filters & Analyzers** (`lib/filters/`, `lib/analyzers/`)
+   - `question-filter.js` - AI-powered smart filtering based on project context
+   - `project-analyzer.js` - Analyzes project type, tech stack, patterns
+
+8. **Generators** (`lib/generators/`)
+   - `tool-config-generator.js` - Base class for IDE configuration generation
+   - `windsurf-generator.js` - Windsurf `.windsurfrules` generation
+   - `cursor-generator.js` - Cursor `.cursorrules` generation
+   - `vscode-generator.js` - VS Code `settings.json` generation
+   - `agents-md-generator.js` - Agent markdown file deployment
+
+### Data Storage Structure
+
+Projects using ADF CLI have this structure:
+```
+project-root/
+├── .adf/                          # Main ADF directory
+│   ├── .env                       # API keys (gitignored)
+│   ├── context.json               # Workflow configuration
+│   ├── analysis-config.json       # AI analysis settings
+│   ├── sessions/                  # Interview sessions
+│   │   └── {timestamp}_{workflow}/
+│   │       ├── _metadata.json     # Session metadata
+│   │       ├── _progress.json     # Progress state
+│   │       ├── _transcript.json   # Interview transcript
+│   │       ├── knowledge-graph.json  # Extracted knowledge
+│   │       └── outputs/           # Generated docs (PRD, specs, etc.)
+│   ├── learning/                  # Learning system data
+│   │   ├── skip-history.json      # Skip events
+│   │   ├── answer-history.json    # Answer metadata
+│   │   ├── patterns.json          # Detected patterns
+│   │   ├── learned-rules.json     # Active rules
+│   │   ├── config.json            # Learning settings
+│   │   └── stats.json             # Statistics
+│   └── shared/                    # Framework templates & agents
+│       ├── agents/                # Agent definitions (PM, Dev, QA, etc.)
+│       ├── templates/             # PRP, BMAD, Spec-Kit templates
+│       └── memory/                # Framework memory
+└── .framework/                    # Deployed to development tool
+    └── agents/                    # Tool-specific agent files
+```
+
+### AI Provider Integration
+
+The `AIClient` class (`lib/ai/ai-client.js`) provides a unified interface across providers:
+
+**Supported Providers:**
+- `anthropic` - Claude models via `@anthropic-ai/sdk`
+- `openai` - GPT models via `openai` SDK
+- `google` - Gemini models via `@google/generative-ai`
+- `openrouter` - 100+ models via OpenRouter (OpenAI-compatible API)
+
+**Key Methods:**
+- `sendMessage(prompt, options)` - Unified message interface
+- Provider-specific methods: `anthropicRequest()`, `openaiRequest()`, `googleRequest()`, `openrouterRequest()`
+
+**API Keys:**
+- Stored in `.adf/.env` (never committed)
+- Environment variables: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`
+- Loaded via `loadEnvIntoProcess()` in `ai-config.js`
+
+### Learning System Architecture
+
+**Pattern Lifecycle:**
+1. **Tracking** - `SkipTracker` records skip/answer events per session
+2. **Detection** - `PatternDetector` analyzes history for consistent patterns (≥75% confidence, ≥3 sessions)
+3. **Decay** - `DecayManager` applies exponential decay to inactive patterns
+4. **Rules** - `RuleGenerator` converts high-confidence patterns to learned rules
+5. **Application** - Rules auto-filter questions (with user approval)
+6. **Analytics** - Dashboard visualizes performance and insights
+
+**Pattern Types:**
+- `consistent_skip` - Same question skipped repeatedly
+- `category_pattern` - Most questions in category skipped
+- `framework_pattern` - Framework-specific skip patterns
+- `user_preference` - Answer style preferences
+
+**Decay Algorithm:**
+- Exponential decay: `newConfidence = currentConfidence * e^(-λt)`
+- High confidence (≥90%): λ = 0.001 (slower decay)
+- Medium confidence (75-89%): λ = 0.002
+- Low confidence (<75%): λ = 0.005 (faster decay)
+- User-approved patterns: decay at half rate
+- Patterns <40% confidence or inactive 6+ months removed automatically
+
+### Question Pipeline
+
+The dynamic pipeline (`DynamicPipeline` class) orchestrates intelligent question flow:
+
+1. **Answer Processing:**
+   - `AnswerAnalyzer` extracts structured info (tech stack, patterns, constraints)
+   - `KnowledgeGraph` stores extracted knowledge with confidence scores
+   - Saves knowledge graph to session for resume capability
+
+2. **Question Filtering:**
+   - `QuestionMapper` maps knowledge items to relevant questions
+   - Questions auto-skipped when knowledge confidence ≥75%
+   - Reduces redundant questions dynamically
+
+3. **Question Reordering:**
+   - Fundamental questions prioritized first
+   - Questions reordered based on extracted knowledge
+   - Ensures logical flow adapted to user's answers
+
+**Performance Impact:**
+- Fast Mode: All features disabled (~0.5s per answer)
+- Balanced Mode: Quality + Filtering + Patterns (~2-3s per answer)
+- Comprehensive Mode: All features enabled (~4-6s per answer)
+
+### Workflow Levels
+
+Three workflow tiers with different agents and templates:
+
+**Level 1: Rapid (PRP)**
+- Agents: dev, qa
+- Templates: PRP story, PRP task
+- Questions: 20 core questions
+- Output: `prp.md` (single document)
+
+**Level 2: Balanced (Spec-Kit)**
+- Agents: analyst, pm, dev, qa
+- Templates: Full PRP suite, spec templates
+- Questions: 30+ questions
+- Outputs: `constitution.md`, `specification.md`, `plan.md`, `tasks.md`
+
+**Level 3: Comprehensive (BMAD)**
+- Agents: analyst, pm, architect, sm, dev, qa
+- Templates: Complete BMAD framework
+- Questions: 40+ questions
+- Outputs: `prd.md`, `architecture.md`, `stories.md`
+
+### Deployment System
+
+**Tool Generators:**
+Each tool has a generator that transforms session outputs into tool-specific configs:
+
+- **Windsurf** (`.windsurfrules`) - Single markdown file with all context
+- **Cursor** (`.cursorrules`) - Single markdown file with all context
+- **VS Code** (`settings.json`) - JSON with custom instructions and file attachments
+- **Generic Tools** - Deploy agent markdown files to `.framework/agents/`
+
+**Deployment Flow:**
+1. Find latest completed session
+2. Load session outputs (PRP/BMAD/Spec-Kit)
+3. Generate tool-specific config
+4. Write to project root (`.windsurfrules`, `.cursorrules`, etc.)
+5. Copy agent files to `.framework/agents/` if needed
+
+## Agent-Native Architecture & AGENTS.md Standard
+
+### The Emerging Standard
+
+`AGENTS.md` is emerging as the de-facto standard for "Agent-Native" repositories - a single, predictable manifest that next-generation AI development tools (GitHub Copilot, Cursor, Google Antigravity, Zed) are trained to look for automatically.
+
+**Key Principles:**
+- **Single Source of Truth** - One manifest file instead of scattered tool-specific configs
+- **Manifest-Driven Architecture** - The `AGENTS.md` acts as "the kernel" that IDEs "mount" or "ingest"
+- **Standardized Interface** - Predictable format replaces ad-hoc rule files
+- **Auto-Discovery** - Tools automatically detect and consume the manifest
+
+### Current ADF Architecture vs. AGENTS.md Pattern
+
+**Current State (v0.11.0):**
+```
+project-root/
+├── .windsurfrules          # Tool-specific file
+├── .cursorrules            # Tool-specific file
+├── .vscode/settings.json   # Tool-specific file
+└── .adf/                   # Framework storage
+    ├── sessions/
+    └── shared/
+        └── agents/         # Agent definitions
+```
+
+**Agent-Native Pattern:**
+```
+project-root/
+├── AGENTS.md               # [KERNEL] Single source of truth
+├── .context/               # [DEEP STORAGE] Referenced by AGENTS.md
+│   ├── memory/
+│   │   ├── architecture.md
+│   │   └── glossary.md
+│   └── skills/             # Executable agent tools
+├── .zed/
+│   └── rules              # SYMLINK -> ../AGENTS.md
+├── .antigravity/
+│   └── agents.yaml        # Mounts AGENTS.md
+└── .vscode/
+    └── settings.json      # References AGENTS.md
+```
+
+### Relationship to ADF's `.adf/` Directory
+
+The `.adf/` directory serves a different purpose than `AGENTS.md`:
+
+**`.adf/` - Framework Internal Storage:**
+- Interview sessions and transcripts
+- Learning system data (patterns, rules, analytics)
+- AI configuration and API keys
+- Session-specific outputs (PRDs, specs, stories)
+- This is ADF's "brain" - not meant for AI agent consumption
+
+**`AGENTS.md` - Agent Manifest:**
+- Operational rules and directives for AI assistants
+- Build/test/deploy commands
+- Project structure and conventions
+- References to deep context (`.context/memory/`)
+- This is what AI coding assistants read during development
+
+### Potential Evolution Path
+
+ADF CLI could evolve to support the AGENTS.md standard:
+
+**Phase 1: Generate AGENTS.md Alongside Tool Configs**
+- Keep current `.windsurfrules`, `.cursorrules` generation
+- Additionally generate root-level `AGENTS.md` with consolidated rules
+- Populate from session outputs and agent definitions
+
+**Phase 2: AGENTS.md as Primary, Tool Configs Reference It**
+- Generate `AGENTS.md` as the source of truth
+- Tool-specific configs become thin wrappers that reference it
+- Use symlinks for tools that support it (Zed: `.zed/rules -> ../AGENTS.md`)
+
+**Phase 3: Standardized Context Structure**
+- Move deep context to `.context/memory/` (architecture, glossary)
+- Keep `.adf/` for ADF-internal data (sessions, learning)
+- `AGENTS.md` references `.context/` for detailed info
+
+### AGENTS.md Template Structure
+
+Based on the emerging standard, an `AGENTS.md` should contain:
+
+```markdown
+---
+name: Project Architect
+description: Expert in [tech stack]
+tools:
+  - name: archon
+    url: http://[mcp-server]/mcp
+---
+
+# AGENTS.md - The Agent Manifest
+
+## 1. Operational Rules (High Priority)
+- **Source of Truth**: Consult `.context/memory/architecture.md`
+- **Security**: Never output `.env` secrets
+- **Testing**: All changes must pass test suite
+
+## 2. Build & Test Commands
+- **Build**: npm run build
+- **Test**: npm test
+- **Lint**: npm run lint
+
+## 3. Project Structure
+- `/.context`: Deep memory and shared context
+- `/src`: Application source code
+- `/.adf`: Framework data (do not modify)
+
+## 4. Workflow Directives
+- **Commits**: Use Conventional Commits
+- **Refactoring**: Prioritize readability
+```
+
+### Integration with MCP Servers
+
+The AGENTS.md pattern works well with Model Context Protocol (MCP) servers:
+
+**Context Servers Referenced in AGENTS.md:**
+```yaml
+tools:
+  - name: archon
+    url: http://archon.ad.iservu.cc:8051/mcp
+    description: Internal API documentation and RAG
+  - name: project_context
+    command: npx @modelcontextprotocol/server-filesystem
+    args: [".context"]
+```
+
+**IDE Configuration (Zed Example):**
+```json
+{
+  "context_servers": {
+    "archon": {
+      "url": "http://archon.ad.iservu.cc:8051/mcp"
+    },
+    "project_context": {
+      "command": "npx",
+      "args": ["@modelcontextprotocol/server-filesystem", ".context"]
+    }
+  }
+}
+```
+
+### Implementation Considerations for ADF
+
+When adding AGENTS.md support to ADF CLI:
+
+1. **Preserve Backward Compatibility** - Continue supporting existing tool configs
+2. **Opt-In Initially** - Make AGENTS.md generation optional via flag or config
+3. **Smart Merging** - If user has existing `AGENTS.md`, merge ADF content intelligently
+4. **Context Mapping** - Map `.adf/shared/memory/` to `.context/memory/` structure
+5. **Template Customization** - Allow users to customize AGENTS.md template per project type
+6. **Symlink Support** - Create symlinks for tools that support it (check OS compatibility)
+
+### Future Direction
+
+The industry is moving toward:
+- **Standardized Manifests** - `AGENTS.md` as the universal entry point
+- **MCP Integration** - Tools reference context via Model Context Protocol
+- **Declarative Agent Behavior** - YAML/frontmatter for structured agent config
+- **Tool Agnostic** - One manifest works across all AI coding assistants
+
+ADF CLI is well-positioned to support this evolution while maintaining its core value: intelligent requirements gathering and workflow scaffolding.
+
+## Important Patterns
+
+### Session Resumption
+- Sessions saved incrementally to `_progress.json`
+- Graceful exit via Ctrl+C or typing "exit"
+- Resume picks up from last answered question
+- Knowledge graph and transcript preserved
+
+### Error Handling
+- AI requests wrapped in try/catch with descriptive errors
+- File operations use `fs-extra` for atomic writes
+- Graceful degradation when AI features disabled
+- Configuration validation with auto-reset on corruption
+
+### Configuration Validation
+- AI config validates API keys and model availability
+- Analysis config has sensible defaults (Balanced mode)
+- Learning config has feature toggles and thresholds
+- Auto-reset corrupted configs with user notification
+
+### Testing Approach
+- Unit tests for analyzers, generators, learning modules
+- Mock AI client for deterministic testing
+- Jest with 70% coverage threshold
+- Test files mirror source structure (`tests/` directory)
+
+## Key Constraints & Design Decisions
+
+1. **No External Databases** - All data stored in JSON files in `.adf/` directory for portability
+2. **Privacy First** - Learning data never leaves user's machine, all stored locally
+3. **API Keys Security** - Never stored in session files, only in `.adf/.env` (gitignored)
+4. **Provider Agnostic** - Unified AI interface allows easy provider switching
+5. **Graceful Degradation** - All AI features can be disabled (Fast mode)
+6. **Idempotent Deploys** - Deploying multiple times is safe (overwrites configs)
+7. **Session Isolation** - Each interview session independent, supports multiple concurrent projects
+
+## Agent Templates
+
+Agent files in `lib/templates/shared/agents/` define AI agent behaviors:
+- `analyst.md` - Business analyst (Balanced/BMAD)
+- `architect.md` - Solutions architect (BMAD)
+- `dev.md` - Developer (all workflows)
+- `pm.md` - Product manager (Balanced/BMAD)
+- `qa.md` - QA engineer (all workflows)
+- `sm.md` - Scrum master (BMAD)
+
+These are deployed to development tools as context for AI assistants.
+
+## OpenSpec Templates
+
+New OpenSpec templates added in v0.11.0+ for AI-driven change management:
+- `openspec-proposal.md` - Change proposal template
+- `openspec-delta.md` - Change impact analysis
+- `openspec-tasks.md` - Implementation tasks
+
+Located in `lib/templates/shared/templates/`.