@iservu-inc/adf-cli 0.1.6 → 0.2.0

package/.project/docs/tool-integrations/IDE-CUSTOMIZATIONS.md

@@ -0,0 +1,578 @@
+# IDE Tool Customizations
+
+## Overview
+
+ADF CLI generates tool-specific configurations to integrate framework outputs directly into IDE workflows.
+
+**Supported Tools:**
+1. Windsurf (Codeium)
+2. Cursor
+3. VS Code (GitHub Copilot / Claude Code)
+
+---
+
+## 1. Windsurf Customizations
+
+### File Structure
+
+```
+project/
+├── .windsurfrules              # Main rules file
+├── .windsurfrules/
+│   ├── memories/
+│   │   ├── project-context.md
+│   │   ├── architecture.md
+│   │   └── coding-standards.md
+│   ├── slash-commands/
+│   │   ├── review-prd.md
+│   │   ├── implement-story.md
+│   │   └── check-requirements.md
+│   └── workflows/
+│       ├── feature-development.yaml
+│       └── code-review.yaml
+```
+
+### .windsurfrules Format
+
+```markdown
+# Project Rules
+
+## Context
+[From PRP/BMAD outputs]
+
+## Constraints
+[From Constitution]
+
+## Code Standards
+[From Technical Plan]
+
+## AI Behavior
+- Always reference PRD before implementing
+- Follow architecture patterns defined in architecture.md
+- Validate against success criteria
+- Ask clarifying questions if requirements unclear
+```
+
+### Memories
+
+**Purpose:** Long-term context retention
+
+**project-context.md:**
+```markdown
+# Project Context
+
+## Goal
+[PRP Goal section]
+
+## Tech Stack
+[PRP Context section]
+
+## User Personas
+[BMAD Personas]
+
+## Key Principles
+[Constitution principles]
+```
+
+**architecture.md:**
+```markdown
+# System Architecture
+
+[C4 diagrams from BMAD]
+[Component breakdown from Spec-Kit]
+[Data flow from PRP]
+```
+
+### Slash Commands
+
+**Purpose:** Quick actions within Cascade chat
+
+**/review-prd:**
+```markdown
+Review the current code against the PRD requirements.
+Check for:
+- [ ] All acceptance criteria met
+- [ ] Edge cases handled
+- [ ] Performance requirements satisfied
+```
+
+**/implement-story [ID]:**
+```markdown
+Implement user story {ID} following:
+1. Review story acceptance criteria
+2. Check architecture for component location
+3. Follow code standards
+4. Write tests first
+5. Implement feature
+6. Verify against success criteria
+```
+
+### Workflows
+
+**Purpose:** Multi-step automations
+
+**feature-development.yaml:**
+```yaml
+name: Feature Development
+steps:
+  - name: Review Requirements
+    action: load_prd
+  - name: Create Branch
+    action: git_branch
+    pattern: "feature/{story-id}-{description}"
+  - name: Implement
+    action: cascade_chat
+    context: [prd, architecture, story]
+  - name: Test
+    action: run_tests
+  - name: Review
+    action: self_review
+```
+
+### Flow System Integration
+
+**Purpose:** Real-time AI assistance
+
+**Configuration:**
+```json
+{
+  "flow": {
+    "enabled": true,
+    "context": [
+      ".windsurfrules/memories/project-context.md",
+      ".windsurfrules/memories/architecture.md"
+    ],
+    "rules": ".windsurfrules",
+    "autoComplete": {
+      "checkRequirements": true,
+      "suggestPatterns": true
+    }
+  }
+}
+```
+
+---
+
+## 2. Cursor Customizations
+
+### File Structure
+
+```
+project/
+├── .cursorrules                    # Main rules (alternative)
+├── .cursor/
+│   ├── rules                       # Main rules (primary)
+│   ├── commands/
+│   │   ├── check-requirements.md
+│   │   └── implement-feature.md
+│   ├── modes/
+│   │   ├── architect.md
+│   │   └── reviewer.md
+│   ├── hooks/
+│   │   ├── pre-commit.js
+│   │   └── post-generate.js
+│   └── notepads/
+│       ├── current-task.md
+│       └── decisions-log.md
+```
+
+### .cursor/rules Format
+
+```markdown
+# Project Rules
+
+You are a senior developer working on {PROJECT_NAME}.
+
+## Context Files
+- PRD: .adf/sessions/{session}/outputs/prd.md
+- Architecture: .adf/sessions/{session}/outputs/architecture.md
+- Constitution: .adf/sessions/{session}/outputs/constitution.md
+
+## Always Follow
+1. Read PRD before implementing features
+2. Follow architecture patterns
+3. Validate against acceptance criteria
+4. Write tests first
+5. Check constitution for constraints
+
+## Code Style
+[From technical plan]
+
+## Forbidden
+[From constitution non-negotiables]
+```
+
+### Custom Modes
+
+**Purpose:** Different AI personalities for different tasks
+
+**architect.md:**
+```markdown
+You are a system architect. When reviewing code:
+- Focus on architectural patterns
+- Check component boundaries
+- Validate data flow
+- Ensure scalability
+- Review performance implications
+
+Reference: .adf/sessions/{session}/outputs/architecture.md
+```
+
+**reviewer.md:**
+```markdown
+You are a code reviewer. Check for:
+- Requirements compliance (against PRD)
+- Code quality and standards
+- Test coverage
+- Edge case handling
+- Security vulnerabilities
+- Performance issues
+
+Be thorough but constructive.
+```
+
+### MCP (Model Context Protocol) Integration
+
+**Purpose:** Extend Cursor with custom tools
+
+**tools/requirements-checker.js:**
+```javascript
+// MCP tool to validate code against requirements
+export default {
+  name: "check_requirements",
+  description: "Validate implementation against PRD requirements",
+  parameters: {
+    feature_id: "string"
+  },
+  async execute({ feature_id }) {
+    const prd = await loadPRD();
+    const feature = prd.features[feature_id];
+    const code = await getCurrentFile();
+
+    return validateAgainstRequirements(code, feature);
+  }
+}
+```
+
+### Hooks
+
+**Purpose:** Automated checks during development
+
+**pre-commit.js:**
+```javascript
+// Check if code meets requirements before commit
+const { loadPRD, validateCode } = require('./utils');
+
+async function preCommit(files) {
+  const prd = await loadPRD();
+  const results = await validateCode(files, prd);
+
+  if (results.missingRequirements.length > 0) {
+    console.log("Missing requirements:", results.missingRequirements);
+    return false; // Block commit
+  }
+
+  return true;
+}
+```
+
+### Notepads
+
+**Purpose:** Persistent context within Cursor
+
+**current-task.md:**
+```markdown
+# Current Task: Implement User Dashboard
+
+## Story
+[User story from BMAD]
+
+## Requirements
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+## Decisions Made
+- Using React Query for data fetching
+- Chart.js for visualizations
+- Daily aggregation in backend
+
+## Questions
+- Max data points to display?
+```
+
+---
+
+## 3. VS Code Customizations
+
+### File Structure
+
+```
+project/
+├── .github/
+│   └── copilot-instructions.md     # GitHub Copilot
+├── .vscode/
+│   ├── settings.json
+│   └── tasks.json
+├── .claude/
+│   ├── commands/
+│   │   ├── review.md
+│   │   └── implement.md
+│   └── context/
+│       └── project.md
+```
+
+### GitHub Copilot Instructions
+
+**Purpose:** Guide Copilot's code generation
+
+**.github/copilot-instructions.md:**
+```markdown
+# Copilot Instructions for {PROJECT_NAME}
+
+## Project Context
+[PRP Goal + Context]
+
+## Architecture
+[Component structure from Spec-Kit]
+
+## Code Style
+- TypeScript strict mode
+- Functional components (React)
+- Async/await (no callbacks)
+- Descriptive variable names
+
+## Patterns to Use
+- Custom hooks for logic reuse
+- Context for global state
+- Error boundaries for error handling
+
+## Patterns to Avoid
+- Class components
+- Inline styles
+- Direct DOM manipulation
+
+## Testing
+- Jest + React Testing Library
+- Test files: *.test.ts
+- Coverage minimum: 80%
+
+## When Generating Code
+1. Check PRD in .adf/sessions/{session}/outputs/
+2. Follow architecture patterns
+3. Include error handling
+4. Add TypeScript types
+5. Write accompanying tests
+```
+
+### Custom Chat Modes
+
+**Purpose:** Different Copilot behaviors
+
+**VS Code settings.json:**
+```json
+{
+  "github.copilot.chat.modes": {
+    "architect": {
+      "instructions": "Focus on system design and architecture patterns. Reference architecture.md.",
+      "context": [
+        ".adf/sessions/{session}/outputs/architecture.md"
+      ]
+    },
+    "implementer": {
+      "instructions": "Implement features according to PRD. Write tests first.",
+      "context": [
+        ".adf/sessions/{session}/outputs/prd.md",
+        ".adf/sessions/{session}/outputs/specification.md"
+      ]
+    },
+    "reviewer": {
+      "instructions": "Review code against requirements and best practices.",
+      "context": [
+        ".adf/sessions/{session}/outputs/constitution.md"
+      ]
+    }
+  }
+}
+```
+
+### Claude Code Integration
+
+**Purpose:** Claude-specific configurations
+
+**.claude/commands/review.md:**
+```markdown
+# Review Command
+
+Review the current file against:
+1. PRD requirements (.adf/sessions/{session}/outputs/prd.md)
+2. Architecture patterns (.adf/sessions/{session}/outputs/architecture.md)
+3. Constitution constraints (.adf/sessions/{session}/outputs/constitution.md)
+
+Provide:
+- Compliance status
+- Missing requirements
+- Improvement suggestions
+```
+
+### Language Model Tools API
+
+**Purpose:** Extend VS Code AI with custom tools
+
+**tools/requirement-lookup.ts:**
+```typescript
+import * as vscode from 'vscode';
+
+export function registerTools(context: vscode.ExtensionContext) {
+  const tool = vscode.lm.registerTool('requirement-lookup', {
+    description: 'Look up requirements from PRD',
+    async invoke(parameters: { feature_id: string }) {
+      const prdPath = '.adf/sessions/{session}/outputs/prd.md';
+      const content = await vscode.workspace.fs.readFile(
+        vscode.Uri.file(prdPath)
+      );
+
+      // Parse PRD and return relevant requirement
+      return parseRequirement(content.toString(), parameters.feature_id);
+    }
+  });
+
+  context.subscriptions.push(tool);
+}
+```
+
+---
+
+## Output Generation Strategy
+
+### Per Framework
+
+**PRP → Simple Integration**
+- Single .windsurfrules file
+- Single .cursorrules file
+- Single copilot-instructions.md
+- Reference prp.md for all context
+
+**Balanced → Structured Integration**
+- Separate memory files per output
+- Multiple slash commands
+- Custom modes for each phase
+- Reference constitution, specification, plan
+
+**BMAD → Comprehensive Integration**
+- Full workflow automation
+- MCP tools for requirement validation
+- Hooks for compliance checking
+- Multiple notepads for tracking
+- Reference all BMAD outputs
+
+### Template Variables
+
+All generated files use variables:
+
+```
+{PROJECT_NAME}       - From session metadata
+{SESSION_ID}         - Current session ID
+{FRAMEWORK}          - rapid/balanced/comprehensive
+{OUTPUT_PATH}        - Path to outputs directory
+{TECH_STACK}         - From PRP context
+{PRINCIPLES}         - From constitution
+```
+
+### Example Generated File
+
+**.windsurfrules (from PRP):**
+```markdown
+# Rules for {PROJECT_NAME}
+
+## Project Goal
+{PRP_GOAL}
+
+## Tech Stack
+{PRP_TECH_STACK}
+
+## Implementation Guidelines
+{PRP_IMPLEMENTATION_BLUEPRINT}
+
+## Success Criteria
+{PRP_VALIDATION}
+
+## AI Instructions
+When implementing features:
+1. Read the full PRP: .adf/sessions/{SESSION_ID}/outputs/prp.md
+2. Follow the implementation blueprint exactly
+3. Validate against success criteria
+4. Ask if requirements are unclear
+```
+
+---
+
+## Future Enhancements
+
+### Planned
+
+1. **JetBrains IDEs** (IntelliJ, WebStorm, etc.)
+2. **Neovim** with Copilot.vim
+3. **Zed Editor**
+4. **Sublime Text** with AI plugins
+
+### Advanced Features
+
+1. **Real-time Requirement Sync**
+   - Update IDE rules when PRD changes
+   - Hot reload configurations
+
+2. **Requirement Traceability**
+   - Link code to specific requirements
+   - Show coverage in IDE
+
+3. **AI Pair Programming**
+   - Step-by-step feature implementation
+   - Guided by framework outputs
+
+4. **Automated Testing**
+   - Generate tests from acceptance criteria
+   - Validate against success metrics
+
+---
+
+## Tool Comparison
+
+| Feature | Windsurf | Cursor | VS Code |
+|---------|----------|--------|---------|
+| Custom Rules | ✅ | ✅ | ✅ |
+| Memories | ✅ | ❌ | ❌ |
+| Slash Commands | ✅ | ✅ | ❌ |
+| Custom Modes | ❌ | ✅ | ✅ |
+| Workflows | ✅ | ❌ | ⚠️ (tasks) |
+| Hooks | ❌ | ✅ | ⚠️ (extensions) |
+| MCP Support | ❌ | ✅ | ❌ |
+| Notepads | ❌ | ✅ | ❌ |
+| Tools API | ❌ | ⚠️ (MCP) | ✅ |
+
+✅ = Native support
+⚠️ = Partial/alternative support
+❌ = Not available
+
+---
+
+## Implementation Priority
+
+### Phase 2A: Basic Integration
+1. Generate .windsurfrules (simple format)
+2. Generate .cursorrules (simple format)
+3. Generate copilot-instructions.md
+
+### Phase 2B: Advanced Features
+1. Windsurf memories
+2. Cursor custom modes
+3. VS Code custom chat modes
+
+### Phase 2C: Automation
+1. Windsurf workflows
+2. Cursor hooks
+3. VS Code tools API
+
+### Phase 2D: All Tools
+1. JetBrains
+2. Neovim
+3. Zed

package/CHANGELOG.md

@@ -7,6 +7,121 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [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

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
+};