dhurandhar 1.0.2 → 2.0.0

package/AI_FEATURES.md

@@ -0,0 +1,369 @@
+# AI Features Guide
+
+**Dhurandhar v2.0.0** includes AI-powered design assistance to help you create better systems faster.
+
+---
+
+## 🤖 **AI Capabilities**
+
+1. **Smart Feature Suggestions** - AI recommends features for your project
+2. **Requirements Generation** - Auto-generate requirements from features
+3. **Entity Extraction** - Identify entities from requirements
+4. **Design Pattern Detection** - Automatically detect patterns in your design
+5. **Anti-Pattern Detection** - Find design smells and code issues
+6. **Improvement Suggestions** - Get recommendations for better design
+
+---
+
+## 🚀 **Quick Start**
+
+```bash
+# Interactive AI assistant
+dhurandhar ai
+
+# Specific AI actions
+dhurandhar ai -a features       # Feature suggestions
+dhurandhar ai -a requirements   # Generate requirements
+dhurandhar ai -a entities       # Extract entities
+dhurandhar ai -a patterns       # Detect design patterns
+dhurandhar ai -a improve        # Overall improvements
+```
+
+---
+
+## 💡 **1. Smart Feature Suggestions**
+
+### **When to Use**
+- Starting a new project
+- Brainstorming features
+- Need inspiration
+
+### **Usage**
+
+```bash
+dhurandhar ai -a features
+```
+
+Or during design:
+```bash
+dhurandhar yudhishthira
+# You'll be asked: "Would you like AI-powered feature suggestions?"
+```
+
+### **Example Output**
+
+```
+🤖 AI Feature Suggestions:
+
+1. User Authentication
+   Description: Secure login and registration
+   Dharmic Value: Protects user identity (Satya - Truth)
+
+2. User Dashboard
+   Description: Personalized user homepage
+   Dharmic Value: Empowers users (Moksha - Liberation)
+
+3. Search Functionality
+   Description: Find content quickly
+   Dharmic Value: Saves user time (Ahimsa - Non-harm)
+
+4. Notifications
+   Description: Keep users informed
+   Dharmic Value: Transparent communication (Satya - Truth)
+
+5. User Profile
+   Description: Manage personal information
+   Dharmic Value: User control (Moksha - Liberation)
+```
+
+### **AI Providers**
+
+**Mock Mode** (Default - No API key required):
+- Rule-based suggestions
+- Common features database
+- Dharmic alignment built-in
+- Great for learning
+
+**OpenAI Mode** (GPT-4):
+```bash
+export OPENAI_API_KEY=sk-...
+# Then use dhurandhar ai
+```
+- Advanced natural language understanding
+- Context-aware suggestions
+- Creative feature ideas
+
+**Anthropic Mode** (Claude 3.5 Sonnet):
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+# Then use dhurandhar ai
+```
+- Excellent reasoning
+- Dharma-aware suggestions
+- Thoughtful recommendations
+
+---
+
+## 📋 **2. Requirements Generation**
+
+### **When to Use**
+- Have features, need requirements
+- Want structured requirements
+- Speed up Phase 2 (Bhishma)
+
+### **Usage**
+
+```bash
+dhurandhar ai -a requirements
+```
+
+### **Prerequisites**
+- Complete Phase 1 (Features)
+
+### **Example Output**
+
+```
+🤖 AI-Suggested Requirements:
+
+1. System shall implement user authentication
+   Feature: User Authentication
+   Criteria: Given a user with valid credentials,
+             when they submit login form,
+             then they should be authenticated
+
+2. System shall implement user dashboard
+   Feature: User Dashboard
+   Criteria: Given an authenticated user,
+             when they access dashboard,
+             then they should see personalized content
+```
+
+---
+
+## 🗂️ **3. Entity Extraction**
+
+### **When to Use**
+- Have requirements, need entities
+- Identify domain model
+- Speed up Phase 3 (Sahadeva)
+
+### **Usage**
+
+```bash
+dhurandhar ai -a entities
+```
+
+### **How it Works**
+- Analyzes requirement text
+- Extracts common nouns (User, Order, Product, etc.)
+- Suggests entities with attributes placeholder
+
+### **Example Output**
+
+```
+🤖 AI-Suggested Entities:
+
+1. User
+2. Order
+3. Product
+4. Payment
+5. Notification
+
+💡 Use these in Phase 3 (Sahadeva)
+```
+
+---
+
+## 🔍 **4. Design Pattern Detection**
+
+### **When to Use**
+- After designing classes (Phase 6)
+- Before implementation
+- Code review
+
+### **Usage**
+
+```bash
+dhurandhar ai -a patterns
+```
+
+Or automatically during design:
+```bash
+dhurandhar arjuna
+# Pattern detection runs automatically during review
+```
+
+### **Detected Patterns**
+
+**Good Patterns** ✅:
+- **Singleton** - getInstance methods
+- **Repository** - CRUD operations (find, save, delete)
+- **Factory** - Object creation (create, build methods)
+- **Service** - Business logic (UserService, OrderService)
+
+**Anti-Patterns** ⚠️:
+- **God Class** - Too many methods (>15) or properties (>10)
+- **Circular Dependencies** - Classes depend on each other
+- **Missing Error Handling** - No error/exception methods
+
+### **Example Output**
+
+```
+✅ Design Patterns Detected:
+
+  Repository - UserRepository
+  Good! Repository pattern separates data access logic
+
+  Service - UserService
+  Service layer for business logic - excellent
+
+⚠️  Anti-Patterns Detected:
+
+  God Class - OrderService
+  Issue: OrderService has too many methods (18)
+  Suggestion: Break down into smaller, focused classes
+
+💡 Suggestions:
+
+✅ Detected 4 design patterns
+   Good architecture! Consider documenting these patterns
+
+🚨 Found 1 anti-pattern
+   Review and refactor the identified issues
+```
+
+---
+
+## 📈 **5. Improvement Suggestions**
+
+### **When to Use**
+- Any time during design
+- Before finalizing
+- Quality check
+
+### **Usage**
+
+```bash
+dhurandhar ai -a improve
+```
+
+### **What it Checks**
+- Completeness (all phases done?)
+- Quality scores (API elegance, class precision)
+- Missing components
+- Best practices
+
+### **Example Output**
+
+```
+🔍 Analyzing Overall Design Quality...
+
+⚠️  No entities defined
+    Action: Complete Phase 3 (Sahadeva)
+
+💭 Average API elegance is 65%
+   Action: Review API design in Phase 4
+
+✅ Design looks good! No critical improvements needed.
+```
+
+---
+
+## 🎯 **AI-Assisted Workflow**
+
+### **Typical Usage Pattern**
+
+```bash
+# 1. Start project with AI suggestions
+dhurandhar init
+dhurandhar yudhishthira
+# → AI suggests features (optional)
+
+# 2. Generate requirements
+dhurandhar ai -a requirements
+# → Use suggestions in Phase 2
+
+# 3. Extract entities
+dhurandhar ai -a entities
+# → Use suggestions in Phase 3
+
+# 4. Design APIs & Services
+dhurandhar nakula
+dhurandhar bheema
+
+# 5. Design classes with pattern detection
+dhurandhar arjuna
+# → AI auto-detects patterns and anti-patterns
+
+# 6. Final quality check
+dhurandhar ai -a improve
+```
+
+---
+
+## ⚙️ **Configuration**
+
+### **Using Mock Mode (No API Key)**
+Default mode - works out of the box!
+
+### **Using OpenAI**
+
+```bash
+# Set API key
+export OPENAI_API_KEY=sk-...
+
+# The AI engine will auto-detect and use GPT-4
+dhurandhar ai -a features
+```
+
+### **Using Anthropic Claude**
+
+```bash
+# Set API key
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# The AI engine will use Claude 3.5 Sonnet
+dhurandhar ai -a features
+```
+
+### **Provider Selection**
+
+The AI engine automatically selects provider:
+1. If `ANTHROPIC_API_KEY` is set → Use Claude
+2. Else if `OPENAI_API_KEY` is set → Use GPT-4
+3. Else → Use Mock mode
+
+---
+
+## 💡 **Best Practices**
+
+1. **Use AI as a starting point** - Review and refine suggestions
+2. **Don't blindly accept** - AI suggestions are helpful, not perfect
+3. **Combine with expertise** - Your domain knowledge + AI = best results
+4. **Mock mode is enough** - No API key? Mock mode works great!
+5. **Pattern detection is automatic** - Runs during Arjuna phase
+6. **Check improvements before blessing** - Run `ai -a improve` before Phase 8
+
+---
+
+## 🚨 **Limitations**
+
+- **Mock mode** is rule-based, not LLM-powered
+- **Entity extraction** is simple noun detection
+- **Pattern detection** is heuristic-based
+- **Works offline** in mock mode
+- **API costs** with OpenAI/Anthropic
+
+---
+
+## 🔮 **Future Enhancements**
+
+- More LLM providers (Gemini, Llama, etc.)
+- Fine-tuned models for dharmic design
+- Architecture recommendation
+- Performance optimization suggestions
+- Security vulnerability detection
+
+---
+
+**Next**: See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues

package/API_REFERENCE.md

@@ -0,0 +1,300 @@
+# Dhurandhar v2.0.0 - API Reference
+
+Complete CLI command reference.
+
+---
+
+## 🎯 **Core Commands**
+
+### **Initialize Project**
+```bash
+dhurandhar init
+```
+Creates `.dhurandhar/` directory and `SYSTEM_DESIGN_MAP.yaml`.
+
+**Prompts**:
+- Project name
+- Description
+- Project type (Web App, Mobile App, API Service, etc.)
+- Team size
+
+---
+
+### **Decision Registry**
+```bash
+dhurandhar decisions
+```
+View and edit Decision Registry (Ask-Once Persistence Pattern).
+
+**Options**:
+- View all decisions
+- Edit naming conventions
+- Edit error response standards
+- Edit security standards
+- Edit observability standards
+
+**Categories**:
+1. **Naming Conventions**: entities, api_endpoints, database_tables, variables, constants
+2. **Error Response Standards**: envelope_format, status_codes
+3. **Security Standards**: rate_limit, session_timeout, password requirements
+4. **Observability Standards**: metrics_prefix, log_format, trace_enabled, alert_thresholds
+
+---
+
+## 👑 **Phase Commands (8 Master Agents)**
+
+### **Phase 1: Yudhishthira (Features)**
+```bash
+dhurandhar yudhishthira
+```
+
+**Modes**:
+1. **Brainstorming Mode** - Solo feature ideation with dharmic evaluation
+2. **Party Mode** - Multi-stakeholder voting (6 personas)
+3. **Manage Decision Registry** - Edit standards
+
+**Dharmic Evaluation** (5 questions):
+- Satya (Truth)
+- Ahimsa (Non-harm)
+- Artha (Value)
+- Karma (Action)
+- Moksha (Liberation)
+
+**Output**: Features with dharmic scores and categories
+
+---
+
+### **Phase 2: Bhishma (Requirements)**
+```bash
+dhurandhar bhishma
+```
+
+**Functions**:
+1. Extract Functional Requirements (from features)
+2. Define NFRs (Performance, Security, Reliability, Scalability, Maintainability)
+3. Specify Constraints (Technical, Business, Security, Performance, Regulatory, Legacy)
+4. Define Trade-offs
+
+**Auto-population**: NFRs pre-filled from Decision Registry
+
+**Output**: Complete requirements specification with constraints
+
+---
+
+### **Phase 3: Sahadeva (Entities & Domain)**
+```bash
+dhurandhar sahadeva
+```
+
+**Functions**:
+1. Model Entities (attributes, identity, lifecycle)
+2. Define Relationships (one-to-one, one-to-many, many-to-many)
+3. Define Aggregates (root, members, boundary)
+4. Apply Cosmic Patterns (Duality, Lifecycle Orbit, Cosmic Invariant)
+
+**Registry Enforcement**: Entity/table naming conventions  
+**Constraints**: Technical, Legacy constraints displayed
+
+**Output**: Domain model with entities, relationships, aggregates, cosmic patterns
+
+---
+
+### **Phase 4: Nakula (APIs)**
+```bash
+dhurandhar nakula
+```
+
+**Functions**:
+1. Design API Endpoints (REST, GraphQL, gRPC)
+2. Check Elegance Score (0-100%)
+
+**Elegance Scoring**:
+- Naming conventions (20 points)
+- Hierarchy & versioning (20 points)
+- HTTP verbs (20 points)
+- Error handling (20 points)
+- Consistency (20 points)
+
+**Registry Enforcement**: API endpoint naming  
+**Constraints**: Technical, Security, Legacy constraints displayed
+
+**Output**: API specifications with elegance scores
+
+---
+
+### **Phase 5: Bheema (High-Level Design)**
+```bash
+dhurandhar bheema
+```
+
+**Functions**:
+1. Service Decomposition
+2. Define 7 Strategic Decisions:
+   - Persistence Strategy
+   - Communication Strategy
+   - Security Strategy
+   - Resilience Strategy
+   - Deployment Strategy
+   - Observability Strategy
+   - Scalability Strategy
+3. Review all strategies
+
+**Registry Validation**: Observability strategy vs registry  
+**Constraint Validation**: Real-time violation warnings with user confirmation  
+**Constraints**: ALL constraint types displayed
+
+**Output**: Service architecture + 7 strategic decisions
+
+---
+
+### **Phase 6: Arjuna (Low-Level Design)**
+```bash
+dhurandhar arjuna
+```
+
+**Functions**:
+1. Class Design (name, type, methods, properties)
+2. Sequence Diagrams (flows, actors, steps)
+3. Database Schema Design (auto-generated from entities)
+4. Algorithm Design
+
+**Precision Scoring**:
+- Class naming (20 points)
+- Methods (20 points)
+- Properties (15 points)
+- Cohesion (25 points)
+- SOLID principles (20 points)
+
+**Registry Enforcement**: Class/method/variable naming  
+**Constraints**: Technical, Security, Performance, Legacy constraints
+
+**Output**: Detailed class designs with precision scores, DB schemas
+
+---
+
+### **Phase 7: Bheema (Implementation)**
+```bash
+dhurandhar bheema  # Auto-detects Phase 7 mode
+```
+
+**Functions**:
+1. Plan Backend Code Generation
+2. Plan Frontend Code Generation
+3. Plan Test Generation
+4. Plan Infrastructure Setup
+5. Handle Edge Cases
+
+**Output**: Implementation roadmap with code generation plan
+
+---
+
+### **Phase 8: Draupadi (Review & Audit)**
+```bash
+dhurandhar draupadi
+```
+
+**Modes**:
+1. **Drift Detection** - Design vs implementation alignment
+2. **Compliance Check** - Standards validation (including Decision Registry)
+3. **Quality Scoring** - Overall quality assessment
+4. **Dharmic Audit** - Dark patterns, privacy, user service
+5. **Imperial Blessing** - Final approval from Yudhishthira
+6. **Generate Report** - Comprehensive audit document
+
+**Blessing Criteria**:
+- Drift < 25%
+- Quality >= 70%
+- No dark patterns
+- No privacy violations
+- Decision Registry compliant
+- Constraint satisfaction >= 80%
+
+**Output**: Audit report + Imperial Blessing (if worthy)
+
+---
+
+## 🔍 **Review Command**
+
+### **Cascading Review**
+```bash
+dhurandhar review -p <phase-name>
+```
+
+**Phase Names**:
+- `requirements-engineering` (Phase 2)
+- `entities-and-domain` (Phase 3)
+- `api-design` (Phase 4)
+- `high-level-design` (Phase 5)
+- `low-level-design` (Phase 6)
+- `implementation` (Phase 7)
+- `review-and-audit` (Phase 8)
+
+**Output**: Review results with issues, recommendations, status (approved/advisory/needs_revision)
+
+---
+
+## 📁 **Output Files**
+
+### **SYSTEM_DESIGN_MAP.yaml**
+Complete system design in structured YAML:
+- Project metadata
+- Features with dharmic evaluation
+- Requirements (FR, NFR, constraints)
+- Entities, relationships, aggregates
+- APIs with elegance scores
+- Services with 7 strategic decisions
+- Classes with precision scores
+- Database schemas
+- Implementation status
+- Audit results
+- Imperial blessing
+- Reviews history
+
+### **.dhurandhar/config.json**
+Project configuration and Decision Registry.
+
+---
+
+## 🎨 **Examples**
+
+### **Complete Workflow**
+```bash
+# 1. Initialize
+dhurandhar init
+
+# 2. Features (Party Mode)
+dhurandhar yudhishthira
+
+# 3. Requirements
+dhurandhar bhishma
+dhurandhar review -p requirements-engineering
+
+# 4. Entities
+dhurandhar sahadeva
+dhurandhar review -p entities-and-domain
+
+# 5. APIs
+dhurandhar nakula
+dhurandhar review -p api-design
+
+# 6. HLD
+dhurandhar bheema
+dhurandhar review -p high-level-design
+
+# 7. LLD
+dhurandhar arjuna
+dhurandhar review -p low-level-design
+
+# 8. Implementation
+dhurandhar bheema
+dhurandhar review -p implementation
+
+# 9. Audit + Blessing
+dhurandhar draupadi
+```
+
+**Result**: Complete `SYSTEM_DESIGN_MAP.yaml` with Imperial Blessing!
+
+---
+
+**For detailed examples, see**: `DEMO_WALKTHROUGH.md`