vralphy 0.1.2 → 0.3.0

package/docs/EXAMPLES.md

@@ -0,0 +1,812 @@
+# Real-World Examples
+
+Concrete examples of using vralphy in different scenarios.
+
+## Example 1: Node.js REST API
+
+### Scenario
+
+Building a REST API for a task management application.
+
+### Project Setup
+
+```bash
+mkdir task-api
+cd task-api
+npm init -y
+git init
+```
+
+### Initialize vralphy
+
+```bash
+vralphy init
+
+# Output:
+# Created:
+#   + specs/
+#   + .vralphy/AGENTS.md
+#   + .vralphy/prompts/
+#   + IMPLEMENTATION_PLAN.md
+```
+
+### Generated AGENTS.md
+
+```markdown
+## Build & Run
+- Build: `npm run build`
+- Dev: `npm run dev`
+
+## Validation
+- Tests: `npm test`
+- Lint: `npm run lint`
+
+## Tech Stack
+- Node.js + Express
+- TypeScript
+- Jest for testing
+
+## Codebase Patterns
+- REST endpoints in src/routes/
+- Business logic in src/services/
+- Data models in src/models/
+```
+
+### Create Specifications
+
+```bash
+vralphy spec task-crud
+
+# AI asks:
+# - What fields should a task have?
+# Response: id, title, description, status, createdAt, updatedAt
+
+# - What statuses are valid?
+# Response: TODO, IN_PROGRESS, DONE
+
+# - Should tasks have priorities?
+# Response: Yes - LOW, MEDIUM, HIGH
+
+# - Authentication required?
+# Response: Yes, JWT-based
+
+# Output: specs/task-crud.md
+```
+
+### Plan Implementation
+
+```bash
+vralphy plan 3
+
+# IMPLEMENTATION_PLAN.md generated:
+```
+
+```markdown
+# Implementation Plan
+
+## High Priority
+- [ ] Set up Express server with TypeScript
+- [ ] Create Task model with validation
+- [ ] Implement POST /tasks endpoint
+- [ ] Implement GET /tasks endpoint
+- [ ] Implement GET /tasks/:id endpoint
+- [ ] Implement PUT /tasks/:id endpoint
+- [ ] Implement DELETE /tasks/:id endpoint
+
+## Medium Priority
+- [ ] Add JWT authentication middleware
+- [ ] Add request validation
+- [ ] Add error handling
+- [ ] Write unit tests for routes
+- [ ] Write integration tests
+
+## Low Priority
+- [ ] Add API documentation
+- [ ] Add rate limiting
+- [ ] Add logging
+```
+
+### Build Implementation
+
+```bash
+vralphy build 20
+
+# Iteration 1: Sets up Express + TypeScript
+# Commit: "Set up Express server with TypeScript configuration"
+
+# Iteration 2: Creates Task model
+# Commit: "Add Task model with validation"
+
+# Iteration 3-7: Implements CRUD endpoints
+# Commit: "Add POST /tasks endpoint with tests"
+# Commit: "Add GET /tasks endpoint with tests"
+# ...
+
+# Iteration 8: Adds authentication
+# Commit: "Add JWT authentication middleware"
+
+# After 20 iterations, most features complete
+```
+
+### Verify Progress
+
+```bash
+cat IMPLEMENTATION_PLAN.md
+
+# Shows:
+# ✓ All high priority tasks completed
+# ✓ Most medium priority tasks completed
+# - Low priority tasks remain
+```
+
+### Continue if Needed
+
+```bash
+vralphy build 10
+
+# Completes remaining tasks
+# All tests pass
+# API ready for deployment
+```
+
+### Final Result
+
+- Working REST API with 7 endpoints
+- JWT authentication
+- Request validation
+- Error handling
+- Comprehensive test suite
+- ~40 commits with clear messages
+- Total time: ~2 hours
+
+---
+
+## Example 2: React Component Library
+
+### Scenario
+
+Creating a reusable component library for internal use.
+
+### Initialize
+
+```bash
+mkdir ui-components
+cd ui-components
+npm create vite@latest . -- --template react-ts
+git init
+vralphy init
+```
+
+### Create Specs
+
+```bash
+# Button component
+vralphy spec button-component
+
+# AI asks:
+# - Variants? Response: primary, secondary, danger
+# - Sizes? Response: small, medium, large
+# - States? Response: default, hover, active, disabled
+# - Icons? Response: Yes, optional leading/trailing
+
+# Output: specs/button-component.md
+```
+
+```bash
+# Card component
+vralphy spec card-component
+
+# Output: specs/card-component.md
+```
+
+```bash
+# Input component
+vralphy spec input-component
+
+# Output: specs/input-component.md
+```
+
+### Plan and Build
+
+```bash
+vralphy plan 5
+vralphy build 30
+
+# AI generates:
+# - Component files
+# - TypeScript types
+# - CSS modules
+# - Storybook stories
+# - Unit tests
+# - Documentation
+```
+
+### Generated Files
+
+```
+src/components/
+├── Button/
+│   ├── Button.tsx
+│   ├── Button.module.css
+│   ├── Button.test.tsx
+│   ├── Button.stories.tsx
+│   └── index.ts
+├── Card/
+│   ├── Card.tsx
+│   ├── Card.module.css
+│   ├── Card.test.tsx
+│   ├── Card.stories.tsx
+│   └── index.ts
+└── Input/
+    ├── Input.tsx
+    ├── Input.module.css
+    ├── Input.test.tsx
+    ├── Input.stories.tsx
+    └── index.ts
+```
+
+### Result
+
+- 3 fully-featured components
+- Storybook documentation
+- 100% test coverage
+- TypeScript types
+- Accessible (ARIA attributes)
+- Total time: ~1.5 hours
+
+---
+
+## Example 3: CLI Tool (TypeScript)
+
+### Scenario
+
+Building a command-line tool for data migration.
+
+### Setup
+
+```bash
+mkdir data-migrator
+cd data-migrator
+npm init -y
+git init
+vralphy init
+```
+
+### Spec Creation
+
+```bash
+vralphy spec cli-interface
+
+# AI asks about:
+# - Commands needed
+# - Flags and options
+# - Input/output formats
+# - Error handling
+
+# Output: specs/cli-interface.md
+```
+
+```bash
+vralphy spec data-transformation
+
+# AI asks about:
+# - Source formats (CSV, JSON, XML)
+# - Target formats
+# - Transformation rules
+# - Validation
+
+# Output: specs/data-transformation.md
+```
+
+### Implementation
+
+```bash
+vralphy plan 3
+vralphy build 25
+
+# AI creates:
+# - Commander.js setup
+# - CSV parser
+# - JSON transformer
+# - XML handler
+# - Validation logic
+# - Error handling
+# - Tests
+```
+
+### Usage Example
+
+Generated CLI:
+```bash
+data-migrator transform \
+  --input data.csv \
+  --output data.json \
+  --format json \
+  --validate
+
+# ✓ Parsed 1000 records
+# ✓ Validated 1000 records
+# ✓ Transformed 1000 records
+# ✓ Wrote to data.json
+```
+
+### Result
+
+- Full-featured CLI tool
+- Multiple data formats supported
+- Comprehensive validation
+- Good error messages
+- Well-tested
+- Total time: ~2 hours
+
+---
+
+## Example 4: Bug Fix in Existing Codebase
+
+### Scenario
+
+Authentication fails when email contains `+` character.
+
+### Project State
+
+- Existing Express API
+- vralphy already initialized
+- Test suite exists
+
+### Add Bug to Plan
+
+```bash
+echo "- [ ] Fix: Authentication fails for emails with + character" >> IMPLEMENTATION_PLAN.md
+```
+
+### Let AI Fix It
+
+```bash
+vralphy build 3
+
+# Iteration 1: AI searches for auth code
+# Finds: Email validation regex doesn't handle +
+
+# Iteration 2: AI fixes regex
+# Updates: src/validators/email.ts
+
+# Iteration 3: AI adds test
+# Creates: test to prevent regression
+
+# Commit: "Fix email validation to handle + character"
+```
+
+### Generated Fix
+
+```typescript
+// Before
+const emailRegex = /^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+
+// After (fixed by AI)
+const emailRegex = /^[a-zA-Z0-9._+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+//                                ^ added +
+```
+
+### Generated Test
+
+```typescript
+describe('Email Validation', () => {
+  it('should accept email with + character', () => {
+    expect(validateEmail('user+tag@example.com')).toBe(true);
+  });
+});
+```
+
+### Result
+
+- Bug fixed
+- Test added
+- 1 commit
+- Total time: ~5 minutes
+
+---
+
+## Example 5: Database Migration (Rust)
+
+### Scenario
+
+Adding Postgres support to existing SQLite-based Rust application.
+
+### Initialize
+
+```bash
+cd rust-app
+vralphy init
+
+# AI detects Rust project
+# Generates AGENTS.md:
+```
+
+```markdown
+## Build & Run
+- Build: `cargo build`
+- Run: `cargo run`
+
+## Validation
+- Tests: `cargo test`
+- Lint: `cargo clippy`
+- Check: `cargo check`
+
+## Tech Stack
+- Rust
+- SQLite (current)
+```
+
+### Create Spec
+
+```bash
+vralphy spec postgres-migration
+
+# AI asks:
+# - Keep SQLite support? Response: Yes (both)
+# - Migration strategy? Response: Abstract database layer
+# - Connection pooling? Response: Yes, using r2d2
+# - Schema migration? Response: Use diesel
+
+# Output: specs/postgres-migration.md
+```
+
+### Plan and Build
+
+```bash
+vralphy plan 5
+vralphy build 30
+
+# AI creates:
+# - Database abstraction trait
+# - SQLite implementation
+# - Postgres implementation
+# - Connection pool setup
+# - Migration scripts
+# - Tests for both databases
+```
+
+### Result
+
+- Database abstraction layer
+- Both SQLite and Postgres work
+- Connection pooling
+- Backward compatible
+- Full test coverage
+- Total time: ~3 hours
+
+---
+
+## Example 6: Adding Tests to Legacy Code
+
+### Scenario
+
+Untested JavaScript codebase needs test coverage.
+
+### Initialize
+
+```bash
+cd legacy-app
+vralphy init
+```
+
+### Create Spec
+
+```bash
+vralphy spec test-coverage
+
+# AI asks:
+# - Test framework preference? Response: Jest
+# - Coverage goal? Response: 80%
+# - Test types needed? Response: Unit + integration
+# - Priority modules? Response: auth, payments, user
+
+# Output: specs/test-coverage.md
+```
+
+### Update Plan
+
+```markdown
+# IMPLEMENTATION_PLAN.md
+
+## High Priority
+- [ ] Set up Jest configuration
+- [ ] Add tests for auth module
+- [ ] Add tests for payments module
+- [ ] Add tests for user module
+
+## Medium Priority
+- [ ] Add tests for utils
+- [ ] Add integration tests
+- [ ] Set up CI/CD with test runs
+```
+
+### Build Tests
+
+```bash
+vralphy build 40
+
+# AI:
+# - Sets up Jest
+# - Writes unit tests for each module
+# - Writes integration tests
+# - Achieves 85% coverage
+```
+
+### Result
+
+- Jest configured
+- 150+ tests added
+- 85% code coverage
+- CI/CD pipeline updated
+- Bugs found and fixed during testing
+- Total time: ~4 hours
+
+---
+
+## Example 7: Documentation Generation
+
+### Scenario
+
+API needs comprehensive documentation.
+
+### Create Spec
+
+```bash
+vralphy spec api-documentation
+
+# AI asks:
+# - Format? Response: OpenAPI 3.0
+# - Include examples? Response: Yes
+# - Authentication docs? Response: Yes, JWT
+# - Error codes? Response: Yes, all codes
+
+# Output: specs/api-documentation.md
+```
+
+### Build
+
+```bash
+vralphy build 15
+
+# AI generates:
+# - OpenAPI specification
+# - README with API overview
+# - JSDoc comments in code
+# - Postman collection
+# - Example requests/responses
+```
+
+### Generated Files
+
+```
+docs/
+├── openapi.yaml          # Full OpenAPI spec
+├── API.md                # Human-readable docs
+└── examples/
+    ├── auth.http         # Auth examples
+    ├── users.http        # User endpoints
+    └── tasks.http        # Task endpoints
+
+README.md                 # Updated with API docs
+```
+
+### Result
+
+- Complete API documentation
+- OpenAPI spec
+- Code examples
+- Postman collection
+- Total time: ~1 hour
+
+---
+
+## Example 8: Performance Optimization
+
+### Scenario
+
+Application has slow database queries.
+
+### Create Spec
+
+```bash
+vralphy spec query-optimization
+
+# AI asks:
+# - Target improvement? Response: 50% faster
+# - Problem queries? Response: User dashboard, reports
+# - Caching allowed? Response: Yes, Redis
+# - Metrics tracking? Response: Yes, add logging
+
+# Output: specs/query-optimization.md
+```
+
+### Plan and Build
+
+```bash
+vralphy plan 3
+vralphy build 20
+
+# AI:
+# - Analyzes slow queries
+# - Adds database indexes
+# - Implements Redis caching
+# - Adds query logging
+# - Writes performance tests
+```
+
+### Results
+
+- 60% query time reduction (exceeded goal)
+- Redis caching layer
+- Database indexes added
+- Performance monitoring
+- Total time: ~2 hours
+
+---
+
+## Example 9: Microservice Creation
+
+### Scenario
+
+Creating a new microservice for email notifications.
+
+### Setup
+
+```bash
+mkdir email-service
+cd email-service
+npm init -y
+git init
+vralphy init
+```
+
+### Create Specs
+
+```bash
+vralphy spec email-service-api
+vralphy spec email-templates
+vralphy spec queue-processing
+vralphy spec provider-integration
+```
+
+### Build Complete Service
+
+```bash
+vralphy plan 5
+vralphy build 50
+
+# AI builds:
+# - Express API
+# - Email templates (Handlebars)
+# - Bull queue for async processing
+# - SendGrid integration
+# - Retry logic
+# - Tests
+# - Docker setup
+# - README
+```
+
+### Result
+
+- Complete microservice
+- Queue-based processing
+- Email provider integration
+- Templating system
+- Docker containerized
+- Comprehensive tests
+- Total time: ~4 hours
+
+---
+
+## Example 10: Mobile App Backend
+
+### Scenario
+
+Building backend for a mobile todo app.
+
+### Specs
+
+```bash
+vralphy spec user-management
+vralphy spec todo-api
+vralphy spec realtime-sync
+vralphy spec offline-support
+```
+
+### Build
+
+```bash
+vralphy plan 5
+vralphy build 60
+
+# AI creates:
+# - REST API
+# - WebSocket server (realtime)
+# - Conflict resolution (offline)
+# - JWT auth
+# - Push notifications
+# - Database (Postgres)
+# - Tests
+```
+
+### Features Implemented
+
+- User registration/login
+- CRUD operations for todos
+- Real-time sync via WebSockets
+- Offline conflict resolution
+- Push notifications
+- Complete test suite
+
+### Result
+
+- Production-ready backend
+- Real-time features
+- Offline support
+- Total time: ~5 hours
+
+---
+
+## Common Patterns Across Examples
+
+### Pattern 1: Spec → Plan → Build
+
+All examples follow this pattern:
+1. Write detailed specifications
+2. Let AI plan the implementation
+3. Build autonomously
+
+### Pattern 2: Incremental Testing
+
+Every example includes tests:
+- Written alongside implementation
+- Run after each change
+- Gate commits on test success
+
+### Pattern 3: Clear Commits
+
+All examples produce clear git history:
+- Descriptive commit messages
+- Small, focused changes
+- Easy to review
+
+### Pattern 4: Documentation
+
+AI generates documentation:
+- Code comments
+- README files
+- API documentation
+- Usage examples
+
+---
+
+## Time Savings
+
+### Traditional Development vs vralphy
+
+**Example 1 (REST API)**:
+- Traditional: 8-10 hours
+- vralphy: 2 hours
+- **Savings: 75%**
+
+**Example 4 (Bug Fix)**:
+- Traditional: 30-60 minutes
+- vralphy: 5 minutes
+- **Savings: 90%**
+
+**Example 6 (Add Tests)**:
+- Traditional: 2-3 days
+- vralphy: 4 hours
+- **Savings: 80%**
+
+**Average: 70-80% time savings**
+
+---
+
+## Next Steps
+
+- Apply these patterns to your projects
+- Read [WORKFLOWS.md](./WORKFLOWS.md) for detailed workflows
+- Check [METHODOLOGY.md](./METHODOLOGY.md) for deeper understanding
+- See [COMMANDS.md](./COMMANDS.md) for command reference