@iservu-inc/adf-cli 0.1.6 → 0.2.0

package/.project/docs/frameworks/FRAMEWORK-METHODOLOGIES.md

@@ -0,0 +1,449 @@
+# Framework Methodologies
+
+## Overview
+
+ADF CLI integrates four proven development frameworks into a unified tool:
+
+1. **PRP (Product Requirement Prompt)** by Wirasm
+2. **BMAD (Business Model Architecture Design)**
+3. **Spec-Kit** (Specification Framework)
+4. **Context Engineering** (AI Context Management)
+
+## Framework Selection Logic
+
+### RAPID Workflow → PRP Only
+**Use when:**
+- Quick feature development
+- Small scope projects
+- Rapid prototyping
+- Clear requirements
+
+**Time:** 5-15 minutes
+**Questions:** ~20
+**Output:** Single PRP document
+
+### BALANCED Workflow → PRP + Spec-Kit
+**Use when:**
+- Medium complexity projects
+- Need both requirements and specs
+- Team collaboration
+- Iterative development
+
+**Time:** 30-60 minutes
+**Questions:** ~50
+**Outputs:** Constitution, Specification, Plan, Tasks
+
+### COMPREHENSIVE Workflow → Full BMAD
+**Use when:**
+- Large scale projects
+- Business model uncertainty
+- Complete documentation needed
+- Long-term maintenance
+
+**Time:** 1-2+ hours
+**Questions:** 100+
+**Outputs:** PRD, Architecture, Stories, Business Model
+
+---
+
+## 1. PRP Framework
+
+### Origin
+Created by Wirasm as a concise way to communicate product requirements to AI agents.
+
+### Philosophy
+Focus on **what** needs to be built and **why**, giving AI maximum context to determine **how**.
+
+### Structure
+
+#### 1. Goal Definition
+**Purpose:** Crystal clear objective
+**Questions:**
+- What specific software feature/product are you building?
+- Who are the users?
+- What problem does it solve?
+- What does success look like?
+
+**Output Format:**
+```markdown
+## Goal
+Build a [TYPE] that allows [USERS] to [ACTION] in order to [OUTCOME].
+```
+
+#### 2. Business Justification
+**Purpose:** Why this matters now
+**Questions:**
+- Why build this now?
+- What's the business value?
+- What are the risks of not building?
+
+**Output Format:**
+```markdown
+## Business Justification
+This feature will [BUSINESS_VALUE] and addresses [PAIN_POINT].
+Not building this results in [RISKS].
+```
+
+#### 3. Contextual Intelligence
+**Purpose:** Technical landscape
+**Questions:**
+- Technology stack?
+- Platform (web/mobile/desktop)?
+- User interaction patterns?
+- Data requirements?
+- Integration points?
+
+**Output Format:**
+```markdown
+## Context
+- **Stack:** React 18, TypeScript, Node.js, PostgreSQL
+- **Platform:** Web responsive
+- **Users:** Internal team (10-50 users)
+- **Data:** User profiles, activity logs, analytics
+- **Integrations:** Slack API, GitHub API
+```
+
+#### 4. Implementation Blueprint
+**Purpose:** How to build it
+**Questions:**
+- File structure?
+- Core components?
+- Data flow?
+- API endpoints?
+- Edge cases?
+
+**Output Format:**
+```markdown
+## Implementation
+### File Structure
+- src/components/Dashboard/
+- src/api/analytics/
+- src/utils/dataProcessing/
+
+### Core Logic
+1. Fetch data from analytics API
+2. Process and aggregate by time period
+3. Render charts with React components
+4. Enable export to CSV
+
+### Edge Cases
+- No data available → show empty state
+- API timeout → retry with exponential backoff
+```
+
+#### 5. Validation
+**Purpose:** How to measure success
+**Questions:**
+- Success criteria?
+- Testing approach?
+- Metrics to track?
+
+**Output Format:**
+```markdown
+## Validation
+### Success Criteria
+- [ ] Dashboard loads in <2s
+- [ ] All charts render correctly
+- [ ] Export works for 1M+ rows
+
+### Testing
+- Unit tests for data processing
+- Integration tests for API calls
+- E2E tests for user workflows
+
+### Metrics
+- Page load time
+- User engagement (daily active users)
+- Export usage frequency
+```
+
+### PRP Benefits
+- Fast to create (5-15 min)
+- AI-friendly format
+- Focuses on outcomes
+- Prevents over-specification
+
+---
+
+## 2. Spec-Kit Framework
+
+### Origin
+Specification framework for detailed technical documentation.
+
+### Philosophy
+Bridge between business requirements and technical implementation.
+
+### Structure
+
+#### Constitution
+**Purpose:** Project principles and constraints
+**Content:**
+- Core principles
+- Non-negotiables
+- Technical constraints
+- Team conventions
+
+**Example:**
+```markdown
+## Constitution
+
+### Principles
+1. User privacy is paramount
+2. Performance over features
+3. Accessibility first
+
+### Non-Negotiables
+- No third-party analytics
+- WCAG 2.1 AA compliance
+- <100ms API response time
+
+### Constraints
+- Must work on IE11
+- Max bundle size: 500KB
+- SQLite only (no external DB)
+```
+
+#### Specification
+**Purpose:** Detailed functional spec
+**Content:**
+- User flows (step-by-step)
+- UI/UX details
+- Data models
+- API contracts
+- Error handling
+
+#### Technical Plan
+**Purpose:** Architecture and technical decisions
+**Content:**
+- System architecture
+- Component breakdown
+- Data flow diagrams
+- Performance considerations
+- Security measures
+
+#### Task Breakdown
+**Purpose:** Implementation roadmap
+**Content:**
+- Epic/Story/Task hierarchy
+- Dependencies
+- Estimates
+- Acceptance criteria
+
+### Spec-Kit Benefits
+- Comprehensive documentation
+- Team alignment
+- Reduces ambiguity
+- Enables parallel work
+
+---
+
+## 3. BMAD Framework
+
+### Origin
+Business Model Architecture Design - holistic product framework.
+
+### Philosophy
+Align business model, user needs, and technical architecture.
+
+### Structure
+
+#### Business Model Canvas
+**Components:**
+1. Customer Segments
+2. Value Propositions
+3. Channels
+4. Customer Relationships
+5. Revenue Streams
+6. Key Resources
+7. Key Activities
+8. Key Partnerships
+9. Cost Structure
+
+#### Architecture Design
+**Levels:**
+1. System Context
+2. Container Diagram
+3. Component Diagram
+4. Code Structure
+
+#### User Stories
+**Format:**
+```
+As a [ROLE]
+I want to [ACTION]
+So that [BENEFIT]
+
+Acceptance Criteria:
+- [ ] Criterion 1
+- [ ] Criterion 2
+```
+
+#### Product Requirements Document
+**Sections:**
+1. Executive Summary
+2. Problem Statement
+3. Goals and Objectives
+4. User Personas
+5. User Journeys
+6. Features and Requirements
+7. Technical Architecture
+8. Success Metrics
+9. Risks and Mitigations
+10. Timeline and Milestones
+
+### BMAD Benefits
+- Complete business alignment
+- Holistic view
+- Stakeholder buy-in
+- Long-term vision
+
+---
+
+## 4. Context Engineering
+
+### Origin
+Methodology for managing AI agent context.
+
+### Philosophy
+Keep AI agents focused and productive through structured context.
+
+### Techniques
+
+#### Context Layering
+```
+Layer 1: Project Context (always present)
+Layer 2: Current Feature Context
+Layer 3: Current Task Context
+```
+
+#### Memory Management
+- Short-term: Current conversation
+- Medium-term: Current feature
+- Long-term: Project principles
+
+#### Prompt Patterns
+- Role definition
+- Constraint specification
+- Output format examples
+- Iterative refinement
+
+### Context Engineering Benefits
+- AI stays on task
+- Consistent outputs
+- Faster iteration
+- Better quality
+
+---
+
+## Framework Combination Strategy
+
+### How Frameworks Complement Each Other
+
+```
+PRP → Quick requirements
+  ↓
+Spec-Kit → Detailed specification
+  ↓
+BMAD → Business alignment
+  ↓
+Context Engineering → AI execution
+```
+
+### ADF CLI Workflow Selection
+
+**Discovery Questions (4):**
+1. Project size/complexity?
+2. Timeline urgency?
+3. Team size?
+4. Documentation needs?
+
+**Selection Logic:**
+```
+IF quick + clear requirements → PRP
+ELSE IF medium + team collaboration → Balanced (PRP + Spec-Kit)
+ELSE IF large + business alignment → BMAD
+```
+
+### Output Synergy
+
+All frameworks produce:
+1. **Human-readable docs** for team reference
+2. **AI-optimized prompts** for development
+3. **Structured data** for tool integration
+
+---
+
+## Future Framework Extensions
+
+### Planned Additions
+
+1. **Lean Canvas** integration
+2. **Jobs to Be Done** framework
+3. **Event Storming** for domain modeling
+4. **C4 Model** for architecture
+
+### Plugin System
+
+Allow community to add custom frameworks:
+
+```javascript
+// .adf/custom-frameworks/my-framework.js
+module.exports = {
+  name: 'My Framework',
+  questions: [...],
+  generator: (answers) => {...}
+}
+```
+
+---
+
+## Framework Comparison
+
+| Aspect | PRP | Spec-Kit | BMAD |
+|--------|-----|----------|------|
+| Time | 5-15 min | 30-60 min | 1-2+ hours |
+| Scope | Single feature | Medium project | Full product |
+| Detail | High-level | Detailed | Comprehensive |
+| Outputs | 1 doc | 4 docs | 10+ docs |
+| Team Size | Solo | 2-5 | 5+ |
+| AI Friendly | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
+| Business Alignment | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| Technical Depth | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
+
+---
+
+## Best Practices
+
+### When to Use Each Framework
+
+**Use PRP when:**
+- Adding feature to existing app
+- Rapid prototyping
+- Clear requirements
+- Solo developer
+- Short timeline (<1 week)
+
+**Use Balanced when:**
+- New medium-sized project
+- Team of 2-5 developers
+- Need technical specification
+- Iterative development
+- Timeline: 2-8 weeks
+
+**Use BMAD when:**
+- New product launch
+- Business model uncertainty
+- Large team (5+ people)
+- Complex domain
+- Long-term project (3+ months)
+
+### Hybrid Approaches
+
+**PRP → BMAD:**
+Start fast with PRP, expand to BMAD as complexity grows
+
+**Spec-Kit → PRP:**
+Use Spec-Kit for planning, PRP for AI communication
+
+**Custom Mix:**
+Cherry-pick sections from each framework as needed

package/.project/docs/goals/PROJECT-VISION.md

@@ -0,0 +1,112 @@
+# ADF CLI - Project Vision & Goals
+
+## Vision Statement
+
+Create the definitive AI-driven requirements gathering tool that transforms vague ideas into comprehensive, actionable development documentation through intelligent conversation.
+
+## Core Problem
+
+Developers and teams struggle with:
+1. Creating comprehensive requirements documents
+2. Maintaining AI agent focus throughout development
+3. Choosing the right framework (PRP/BMAD/Spec-Kit)
+4. Integrating frameworks with their IDE tools
+5. Losing work due to incomplete sessions
+
+## Solution
+
+A CLI tool that:
+- Guides users through intelligent, adaptive interviews
+- Measures information quality, not question count
+- Never loses user data (triple-redundant saves)
+- Generates framework-specific outputs
+- Integrates directly into IDE tools (Windsurf, Cursor, VS Code)
+- Supports resume capability for long sessions
+
+## Success Criteria
+
+### User Experience
+- [ ] User can complete PRP interview in <15 minutes
+- [ ] User can save and resume any session
+- [ ] Zero data loss, even during crashes
+- [ ] Clear progress indication based on information richness
+- [ ] Smooth integration with IDE tools
+
+### Technical
+- [ ] 100% test coverage for data persistence
+- [ ] Triple-redundant save system with emergency fallback
+- [ ] Quality-based progress tracking (not just question count)
+- [ ] Resume capability from exact point of interruption
+- [ ] Tool-specific outputs for Windsurf, Cursor, VS Code
+
+### Business
+- [ ] NPM package published and maintained
+- [ ] Documentation complete and clear
+- [ ] Community adoption and feedback
+- [ ] Regular updates based on framework evolution
+
+## Target Users
+
+### Primary
+- Solo developers starting new projects
+- Teams needing structured requirements
+- AI-assisted development practitioners
+
+### Secondary
+- Product managers creating PRDs
+- Technical leads planning architecture
+- Open source maintainers documenting features
+
+## Competitive Advantage
+
+1. **Quality over Quantity**: First tool to measure information richness vs question count
+2. **Never Lose Data**: Most robust save system in CLI tools
+3. **Framework Expertise**: Deep integration with proven methodologies (PRP, BMAD, Spec-Kit)
+4. **Tool Integration**: Direct IDE integration, not just file generation
+5. **Adaptive Intelligence**: Questions adapt based on answer quality
+
+## Roadmap
+
+### Phase 1: Core System (Current)
+- Quality-based progress tracking
+- Triple-redundant saves
+- Resume capability
+- Framework-specific outputs
+
+### Phase 2: Tool Integration
+- Windsurf customizations
+- Cursor customizations
+- VS Code customizations
+- Deploy command enhancements
+
+### Phase 3: Intelligence
+- Smart question skipping based on previous answers
+- Context-aware follow-ups
+- Multi-session learning
+- Suggested improvements to answers
+
+### Phase 4: Community
+- Plugin system for custom frameworks
+- Shareable interview templates
+- Community question database
+- Analytics and insights
+
+## Key Metrics
+
+### Quality Metrics
+- Information Richness Score (0-100%)
+- Average Answer Quality (0-100%)
+- Comprehensive Answers Count
+- Total Word Count
+
+### Session Metrics
+- Session Completion Rate
+- Resume Success Rate
+- Average Time per Framework
+- Data Loss Incidents (target: 0)
+
+### Adoption Metrics
+- NPM Downloads
+- GitHub Stars
+- Issue Resolution Time
+- Community Contributions