@iservu-inc/adf-cli 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,253 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [0.2.0] - 2025-10-03
+
+### 🚀 MAJOR RELEASE: Quality-Based Progress Tracking & Resume Capability
+
+This is a **paradigm shift** in how ADF CLI measures progress. Instead of counting questions, we now measure **information richness** - recognizing that 3 thorough answers can be worth more than 20 shallow ones.
+
+### Added
+
+**Quality-Based Progress System:**
+- Information Richness Score (0-100%) - weighted metric combining completion and quality
+- Real-time answer quality analysis with 0-100 scoring
+- Quality metrics tracking: word count, keywords, required elements, detail level, technical depth
+- Automatic follow-up question skipping for high-quality answers (score >= 85)
+- Quality feedback displayed to users after each answer
+
+**Resume Capability:**
+- Full session save/quit/resume from exact point of interruption
+- Session Manager to detect and list resumable sessions
+- User prompted to resume or start new on `adf init`
+- All context preserved: answers, transcript, quality metrics, current block
+
+**Triple-Redundant Auto-Save:**
+- Main progress file: `_progress.json`
+- Backup file: `_progress.backup.json`
+- Append-only log: `_progress-log.md`
+- Emergency fallback: `_emergency-{timestamp}.json` (if all else fails)
+- Auto-save after every answer, block completion, and state change
+
+**Comprehensive Testing:**
+- 33 unit tests with 78% code coverage
+- Test coverage: 78% statements, 63% branches, 77% functions, 79% lines
+- Tests for quality analyzer, progress tracker, session manager
+- Emergency recovery scenarios tested
+
+**Project Documentation:**
+- Complete `.project/` documentation structure
+- Chat history tracking (current and completed)
+- Architecture documentation (system design, data flow)
+- Framework methodologies documentation
+- Tool integrations specification
+- Project vision and goals
+
+### New Files
+
+- `lib/frameworks/answer-quality-analyzer.js` - Comprehensive quality scoring engine
+- `lib/frameworks/progress-tracker.js` - Real-time progress with quality metrics
+- `lib/frameworks/session-manager.js` - Session listing and resume prompts
+- `tests/answer-quality-analyzer.test.js` - 16 unit tests
+- `tests/progress-tracker.test.js` - 12 unit tests
+- `tests/session-manager.test.js` - 5 unit tests
+- `jest.config.js` - Jest testing configuration
+- `.project/chats/` - Chat history tracking
+- `.project/docs/` - Complete project documentation
+
+### Changed
+
+**Interviewer Engine:**
+- Integrated quality analyzer - evaluates every answer
+- Auto-save after each answer with quality metrics
+- Block start/complete/skip tracking
+- Quality feedback display to users
+- Smart follow-up skipping based on quality
+
+**Init Command:**
+- Session resume detection on startup
+- Prompts user to resume or start new
+- Framework parameter tracking for resume
+
+**Progress Display:**
+- Old: `"3/20 questions (15%)"`
+- New: `"📊 Information Richness: ✨ 75% | Avg Quality: 82%"`
+- Shows blocks, questions, words, and quality metrics
+- Emoji indicators for richness levels (🌟 ✨ 💫 ⭐)
+
+### Quality Scoring System
+
+**Metrics (0-100 total):**
+- Word count: up to 30 points (50+ words = max)
+- Keyword presence: up to 20 points
+- Required elements: up to 25 points (platform, tech, user interaction, etc.)
+- Detail level: up to 15 points (bullets, examples, multiple sentences)
+- Technical depth: up to 10 points (tech stack, versions, tools)
+
+**Thresholds:**
+- Score >= 70: Comprehensive answer
+- Score >= 85: Can skip follow-up questions
+
+**Information Richness Formula:**
+```
+informationRichness = (completionFactor * 0.4) + (qualityFactor * 0.6) * 100
+```
+Weighted 60% toward quality, 40% toward completion.
+
+### Breaking Changes
+
+None - fully backward compatible with v0.1.x
+
+### Technical Debt Addressed
+
+- Bulletproof data persistence (zero data loss)
+- Comprehensive error recovery
+- Test coverage for core components
+- Project documentation structure
+
+### Next Steps
+
+- **Option B (Phase 2)**: IDE Tool Integrations
+  - Windsurf customizations (.windsurfrules, memories, workflows)
+  - Cursor customizations (.cursorrules, modes, MCP, hooks)
+  - VS Code customizations (copilot-instructions, chat modes, tools API)
+
+### Migration Guide
+
+No migration needed. Existing sessions from v0.1.x will continue to work. New features will be available for new sessions created with v0.2.0.
+
+## [0.1.6] - 2025-10-02
+
+### Fixed
+- Fixed step numbering in init success message
+  - Steps now number correctly (1, 2, 3) when deployment is completed
+  - Steps number correctly (1, 2, 3, 4) when deployment is skipped
+  - Eliminated confusing jump from step 2 to step 4
+
+### Documentation
+- Updated README.md with comprehensive usage examples
+- Added context.json structure documentation
+- Added documentation about local file paths feature
+- Added detailed "What Gets Installed" section with complete directory structure
+
+## [0.1.5] - 2025-10-02
+
+### Added
+- New question in init workflow: "Do you have local documentation files to include?"
+  - Allows users to specify local file paths (e.g., `./docs/`, `./README.md`)
+  - Added `documentationFiles` array to context.json structure
+  - Complements existing `documentationUrls` field
+
+### Changed
+- Init workflow now collects both remote URLs and local file paths for documentation
+- Enhanced context.json to track local documentation references
+
+## [0.1.4] - 2025-10-02
+
+### Fixed
+- Fixed context.json to use actual CLI version instead of hardcoded "0.1.01"
+  - Now dynamically reads version from package.json
+  - context.json correctly reflects which version of CLI was used to initialize
+
+### Changed
+- Updated `project-detector.js` to import package.json for version tracking
+
+## [0.1.3] - 2025-10-02
+
+### Fixed
+- Fixed critical `ReferenceError` in init command
+  - `deployNow` variable was referenced outside its scope
+  - Caused initialization to crash after displaying success message
+  - Properly scoped variable to fix error
+
+### Changed
+- Improved variable scoping in init.js for better reliability
+
+## [0.1.2] - 2025-10-02
+
+### Documentation
+- Updated README.md with correct package name throughout
+- Fixed all installation command references to use `@iservu-inc/adf-cli`
+- Updated 8 instances of package name in documentation
+
+## [0.1.1] - 2025-10-02
+
+### Fixed
+- Fixed update command to check correct package name on npm registry
+  - Was checking `@iservu/adf-cli` instead of `@iservu-inc/adf-cli`
+  - Updated npm registry URLs in update.js
+
+## [0.1.0] - 2025-10-02
+
+### Added
+- Initial release of AgentDevFramework CLI tool
+- Three workflow levels:
+  - Level 1: Rapid Development (PRP) - 5-15 min planning
+  - Level 2: Specification-Driven (Balanced) - 30-60 min planning
+  - Level 3: BMAD Comprehensive - 1-2+ hour planning
+- Interactive `adf init` command with intelligent workflow recommendations
+- Support for multiple development tools:
+  - Windsurf, Cursor, VS Code, VS Code Insider
+  - Kiro, Trae, Claude Code, Gemini CLI, Codex CLI
+- `adf deploy` command for deploying to development tools
+- `adf update` command for checking and installing CLI updates
+- Automatic project type detection (new vs existing)
+- Documentation URL collection during initialization
+- Agent deployment based on workflow level:
+  - Rapid: dev, qa
+  - Balanced: analyst, pm, dev, qa
+  - Comprehensive: analyst, pm, architect, sm, dev, qa
+- Template copying and configuration generation
+- Environment template creation (.env.template)
+- Framework memory and constitution files
+- MCP configuration support
+
+### Commands
+- `adf init [--rapid|--balanced|--comprehensive] [--tool <tool>]` - Initialize framework
+- `adf deploy [tool] [--list]` - Deploy to development tool
+- `adf update [--check]` - Update CLI to latest version
+- `adf --version` - Show CLI version
+- `adf --help` - Show help information
+
+### Project Structure
+Creates isolated `.adf/` directory with:
+- context.json - Workflow configuration
+- scripts/ - Helper scripts
+- shared/ - Templates, agents, MCP configs, memory files
+
+Deploys to `.framework/` directory with:
+- agents/ - Deployed agent definition files
+
+Creates tool-specific configuration files:
+- .windsurfrules, .cursorrules, .vscode/settings.json, etc.
+
+## Package Naming History
+
+### Scope Change
+- Original name: `@iservu/adf-cli` (failed to publish - scope mismatch)
+- Updated to: `@iservu-inc/adf-cli` (matches npm username `iservu-inc`)
+- First successful publish: v0.1.0
+
+---
+
+## Links
+
+- [npm Package](https://www.npmjs.com/package/@iservu-inc/adf-cli)
+- [GitHub Repository](https://github.com/iServU/adf-cli)
+- [Issue Tracker](https://github.com/iServU/adf-cli/issues)
+
+## Release Notes Format
+
+### Types of Changes
+- **Added** for new features
+- **Changed** for changes in existing functionality
+- **Deprecated** for soon-to-be removed features
+- **Removed** for now removed features
+- **Fixed** for any bug fixes
+- **Security** for vulnerability fixes

package/README.md

@@ -26,6 +26,13 @@ Initialize AgentDevFramework in your current project:
 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:
@@ -109,22 +116,48 @@ When you run `adf init`, the following structure is created in your project:
 ```
 your-project/
 ├── .adf/                    # Framework files (isolated)
-│   ├── scripts/
-│   │   ├── prp.ps1
-│   │   ├── spec.ps1
-│   │   └── ...
-│   ├── shared/
-│   │   ├── bmad/
-│   │   ├── templates/
-│   │   ├── spec-kit/
-│   │   └── prp/
-│   └── context.json         # Your workflow configuration
+│   ├── 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)
@@ -211,7 +244,13 @@ When we release updates to the framework:
 
 ## Version History
 
-- `0.1.01` - Initial release
+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
 

package/jest.config.js

@@ -0,0 +1,20 @@
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/tests/**/*.test.js'],
+  collectCoverageFrom: [
+    'lib/frameworks/answer-quality-analyzer.js',
+    'lib/frameworks/progress-tracker.js',
+    'lib/frameworks/session-manager.js',
+    '!lib/**/*.test.js',
+    '!**/node_modules/**'
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 60,
+      functions: 70,
+      lines: 70,
+      statements: 70
+    }
+  },
+  testTimeout: 10000
+};

package/lib/commands/init.js

@@ -5,18 +5,33 @@ const chalk = require('chalk');
 const ora = require('ora');
 const {
   detectProjectType,
-  getWorkflowRecommendation,
-  generateContextFile
+  getWorkflowRecommendation
 } = require('../utils/project-detector');
-const { copyTemplates } = require('../utils/copy-templates');
+const Interviewer = require('../frameworks/interviewer');
+const SessionManager = require('../frameworks/session-manager');
 const { deployToTool } = require('./deploy');
 
 async function init(options) {
-  console.log(chalk.cyan.bold('\n🚀 AgentDevFramework Initialization\n'));
+  console.log(chalk.cyan.bold('\n🚀 AgentDevFramework - Software Development Requirements\n'));
 
   const cwd = process.cwd();
   const adfDir = path.join(cwd, '.adf');
 
+  // Check for resumable sessions FIRST (before asking to overwrite)
+  const sessionManager = new SessionManager(cwd);
+  const existingSession = await sessionManager.promptToResume();
+
+  if (existingSession) {
+    // Resume existing session
+    const interviewer = new Interviewer(existingSession.progress.framework || 'balanced', cwd, existingSession);
+    const sessionPath = await interviewer.start();
+
+    console.log(chalk.green.bold('\n✨ Requirements gathering complete!\n'));
+    console.log(chalk.cyan(`📁 Session saved to: ${sessionPath}\n`));
+
+    return;
+  }
+
   // Check if already initialized
   if (await fs.pathExists(adfDir)) {
     const { overwrite } = await inquirer.prompt([
@@ -41,132 +56,59 @@ async function init(options) {
   const projectType = await detectProjectType(cwd);
   spinner.succeed(`Project type: ${chalk.green(projectType.type)}`);
 
-  // Determine workflow
+  // Determine workflow/framework
   let workflow;
 
   if (options.rapid) {
     workflow = 'rapid';
-    console.log(chalk.blue('Using Level 1 (Rapid Development) - from --rapid flag'));
+    console.log(chalk.blue('\nUsing: PRP Framework (Rapid Development) - from --rapid flag'));
   } else if (options.balanced) {
     workflow = 'balanced';
-    console.log(chalk.blue('Using Level 2 (Balanced) - from --balanced flag'));
+    console.log(chalk.blue('\nUsing: PRP + Spec-Kit (Balanced) - from --balanced flag'));
   } else if (options.comprehensive) {
     workflow = 'comprehensive';
-    console.log(chalk.blue('Using Level 3 (Comprehensive) - from --comprehensive flag'));
+    console.log(chalk.blue('\nUsing: BMAD Framework (Comprehensive) - from --comprehensive flag'));
   } else {
     // Interactive workflow selection
     workflow = await getWorkflowRecommendation(projectType);
   }
 
-  // Gather documentation URLs (optional)
-  const { hasDocs } = await inquirer.prompt([
-    {
-      type: 'confirm',
-      name: 'hasDocs',
-      message: 'Do you have documentation URLs to include?',
-      default: false
-    }
-  ]);
+  // Create .adf directory
+  await fs.ensureDir(adfDir);
 
-  let documentationUrls = [];
-  if (hasDocs) {
-    const { urls } = await inquirer.prompt([
-      {
-        type: 'input',
-        name: 'urls',
-        message: 'Enter documentation URLs (comma-separated):',
-        filter: (input) => input.split(',').map(url => url.trim()).filter(Boolean)
-      }
-    ]);
-    documentationUrls = urls;
-  }
+  // Start AI-guided interview
+  console.log(chalk.gray('\n' + '━'.repeat(60)) + '\n');
 
-  // Gather local documentation files (optional)
-  const { hasLocalDocs } = await inquirer.prompt([
-    {
-      type: 'confirm',
-      name: 'hasLocalDocs',
-      message: 'Do you have local documentation files to include? (use "." as the project root folder & add like so "./docs/")',
-      default: false
-    }
-  ]);
+  const interviewer = new Interviewer(workflow, cwd);
+  const sessionPath = await interviewer.start();
 
-  let documentationFiles = [];
-  if (hasLocalDocs) {
-    const { files } = await inquirer.prompt([
-      {
-        type: 'input',
-        name: 'files',
-        message: 'Enter local documentation paths (comma-separated, e.g., ./docs/, ./README.md):',
-        filter: (input) => input.split(',').map(file => file.trim()).filter(Boolean)
-      }
-    ]);
-    documentationFiles = files;
-  }
-
-  // Copy framework templates
-  const copySpinner = ora('Copying framework files...').start();
-  await copyTemplates(cwd);
-  copySpinner.succeed('Framework files copied to .adf/');
-
-  // Generate context file
-  const context = generateContextFile({
-    workflow,
-    projectType: projectType.type,
-    documentationUrls,
-    documentationFiles,
-    timestamp: new Date().toISOString()
-  });
-
-  await fs.writeJson(path.join(adfDir, 'context.json'), context, { spaces: 2 });
-  console.log(chalk.green('✓ Created .adf/context.json'));
-
-  // Copy .env.template to project root
-  const envTemplateSrc = path.join(__dirname, '../templates/.env.template');
-  const envTemplateDest = path.join(cwd, '.env.template');
-
-  if (await fs.pathExists(envTemplateSrc)) {
-    await fs.copy(envTemplateSrc, envTemplateDest);
-    console.log(chalk.green('✓ Created .env.template'));
-  }
-
-  // Deploy to tool if specified
-  let deployNow = false;
+  // Show next steps
+  console.log(chalk.cyan('📋 Next Steps:\n'));
+  console.log(chalk.gray(`  1. Review your requirements: ${sessionPath}/outputs/`));
+  console.log(chalk.gray(`  2. Share the output files with your AI coding assistant`));
+  console.log(chalk.gray(`  3. Start building based on the detailed requirements\n`));
 
+  // Optional: Deploy to tool
   if (options.tool) {
     console.log('');
     await deployToTool(options.tool, { silent: false });
-    deployNow = true;
   } else {
-    // Ask if they want to deploy now
-    const response = await inquirer.prompt([
+    const { deployNow } = await inquirer.prompt([
       {
         type: 'confirm',
         name: 'deployNow',
-        message: 'Deploy to a development tool now?',
-        default: true
+        message: 'Deploy framework to a development tool?',
+        default: false
       }
     ]);
 
-    deployNow = response.deployNow;
-
     if (deployNow) {
       const { tool } = await inquirer.prompt([
         {
           type: 'list',
           name: 'tool',
-          message: 'Select deployment tool:',
-          choices: [
-            'windsurf',
-            'cursor',
-            'vscode',
-            'vscode-insider',
-            'kiro',
-            'trae',
-            'claude-code',
-            'gemini-cli',
-            'codex-cli'
-          ]
+          message: 'Select tool:',
+          choices: ['windsurf', 'cursor', 'vscode', 'claude-code', 'gemini-cli']
         }
       ]);
 
@@ -175,19 +117,7 @@ async function init(options) {
     }
   }
 
-  // Success message
-  console.log(chalk.green.bold('\n✨ Initialization complete!\n'));
-
-  console.log(chalk.cyan('Next steps:'));
-  console.log(chalk.gray('  1. Review .adf/context.json'));
-  console.log(chalk.gray('  2. Copy .env.template to .env and configure'));
-  if (!deployNow) {
-    console.log(chalk.gray('  3. Run "adf deploy <tool>" to deploy to your editor'));
-  }
-  console.log(chalk.gray('  4. Check documentation: .adf/shared/templates/\n'));
-
-  console.log(chalk.blue(`Workflow: ${workflow === 'rapid' ? 'Level 1 (Rapid)' : workflow === 'balanced' ? 'Level 2 (Balanced)' : 'Level 3 (Comprehensive)'}`));
-  console.log(chalk.gray('Run "adf deploy --list" to see available tools\n'));
+  console.log(chalk.green.bold('\n✅ All done! Happy coding! 🚀\n'));
 }
 
 module.exports = init;