vralphy 0.1.2 → 0.3.0

package/docs/WORKFLOWS.md

@@ -0,0 +1,808 @@
+# Common Workflows
+
+Practical workflows and patterns for using vralphy effectively.
+
+## Workflow Overview
+
+| Workflow | Use Case | Commands |
+|----------|----------|----------|
+| New Feature | Build new functionality | spec → plan → build |
+| Bug Fix | Fix reported bugs | Edit plan → build |
+| Refactoring | Improve code quality | spec → plan → build |
+| Existing Project | Add vralphy to project | init → spec → plan → build |
+| Fresh Start | Re-initialize clean | cleanup → init |
+| Quick Fix | Small changes | Edit plan → build 1-2 |
+
+---
+
+## Workflow 1: New Feature Development
+
+**Scenario**: Adding a new feature from scratch
+
+### Steps
+
+**1. Initialize (if needed)**
+```bash
+vralphy init
+# Creates .vralphy/, specs/, IMPLEMENTATION_PLAN.md
+```
+
+**2. Create specification**
+```bash
+vralphy spec user-authentication
+
+# AI asks clarifying questions:
+# - Authentication method?
+# - Password requirements?
+# - Session management?
+# - Two-factor auth?
+
+# You provide answers
+# Output: specs/user-authentication.md
+```
+
+**3. Review specification**
+```bash
+cat specs/user-authentication.md
+# Verify requirements are correct
+# Edit if needed
+```
+
+**4. Plan implementation**
+```bash
+vralphy plan 3
+
+# AI analyzes:
+# - Specification requirements
+# - Existing codebase
+# - Dependencies
+# - Test coverage
+
+# Updates: IMPLEMENTATION_PLAN.md
+```
+
+**5. Review plan**
+```bash
+cat IMPLEMENTATION_PLAN.md
+# Check task priorities
+# Verify approach makes sense
+```
+
+**6. Implement**
+```bash
+vralphy build 20
+
+# AI autonomously:
+# - Implements tasks
+# - Writes tests
+# - Runs tests
+# - Commits changes
+# - Updates plan
+```
+
+**7. Verify progress**
+```bash
+# Check remaining tasks
+cat IMPLEMENTATION_PLAN.md
+
+# Check git commits
+git log --oneline -10
+
+# Run tests manually
+npm test
+```
+
+**8. Iterate if needed**
+```bash
+# If more work needed
+vralphy plan 2
+vralphy build 10
+
+# Repeat until complete
+```
+
+### Expected Timeline
+
+- Spec creation: 5-10 minutes
+- Planning: 2-5 minutes (3 iterations)
+- Building: Varies (10-30 minutes for medium feature)
+- Total: 20-45 minutes for a medium-sized feature
+
+---
+
+## Workflow 2: Bug Fix
+
+**Scenario**: Fixing a reported bug
+
+### Steps
+
+**1. Document the bug**
+
+Edit `IMPLEMENTATION_PLAN.md` directly:
+```markdown
+# Implementation Plan
+
+## High Priority
+- [ ] Fix: Login fails when email contains + character
+- [ ] Fix: Password reset email not sending
+
+## Existing tasks...
+```
+
+**2. Let AI fix it**
+```bash
+vralphy build 5
+
+# AI will:
+# - Read the bug description
+# - Search for relevant code
+# - Identify root cause
+# - Implement fix
+# - Add test to prevent regression
+# - Commit
+```
+
+**3. Verify fix**
+```bash
+# Check fix was implemented
+git log -1 --stat
+
+# Run tests
+npm test
+
+# Manual verification
+npm run dev
+```
+
+### When to Use This Workflow
+
+- Quick fixes
+- Clear bug descriptions
+- Regression fixes
+- Edge case handling
+
+### Alternative: Spec-Based Bug Fix
+
+For complex bugs:
+```bash
+# Create a spec describing expected behavior
+vralphy spec login-edge-cases
+
+# Plan the fix
+vralphy plan 2
+
+# Implement
+vralphy build 5
+```
+
+---
+
+## Workflow 3: Refactoring
+
+**Scenario**: Improving code quality without changing behavior
+
+### Steps
+
+**1. Create refactoring spec**
+```bash
+vralphy spec refactor-auth-module
+
+# Describe:
+# - Current problems (duplication, complexity)
+# - Desired outcome (cleaner, testable)
+# - Constraints (maintain API compatibility)
+```
+
+**2. Plan the refactoring**
+```bash
+vralphy plan 5
+
+# AI analyzes:
+# - Current implementation
+# - Code smells
+# - Refactoring opportunities
+# - Test coverage gaps
+```
+
+**3. Review plan carefully**
+```bash
+cat IMPLEMENTATION_PLAN.md
+
+# Verify:
+# - Refactoring is safe
+# - Tests will catch regressions
+# - Approach is sound
+```
+
+**4. Implement incrementally**
+```bash
+# Small iterations to maintain working state
+vralphy build 3
+
+# Verify tests pass
+npm test
+
+# Continue
+vralphy build 3
+npm test
+
+# Repeat until done
+```
+
+**5. Verify no behavior changes**
+```bash
+# Run full test suite
+npm test
+
+# Check code coverage
+npm run coverage
+
+# Manual smoke testing
+npm run dev
+```
+
+### Best Practices
+
+- Small, focused refactorings
+- Test coverage first
+- One pattern at a time
+- Verify after each step
+
+---
+
+## Workflow 4: Adding vralphy to Existing Project
+
+**Scenario**: Introducing vralphy to an established codebase
+
+### Steps
+
+**1. Ensure git is clean**
+```bash
+git status
+# Commit or stash any changes
+```
+
+**2. Initialize vralphy**
+```bash
+vralphy init
+
+# AI analyzes project and generates .vralphy/AGENTS.md
+# Review the generated operational guide
+cat .vralphy/AGENTS.md
+```
+
+**3. Verify operational commands**
+```bash
+# Test commands from AGENTS.md
+npm run build
+npm test
+npm run lint
+
+# If any fail, update .vralphy/AGENTS.md
+```
+
+**4. Create specs for existing features**
+```bash
+# Document what already exists
+vralphy spec existing-api-endpoints
+vralphy spec existing-auth-system
+
+# Or create specs for new work only
+vralphy spec new-feature
+```
+
+**5. Initial planning**
+```bash
+vralphy plan 3
+
+# AI will:
+# - Discover existing implementation
+# - Identify gaps vs specs
+# - Create initial plan
+```
+
+**6. Review and adjust**
+```bash
+cat IMPLEMENTATION_PLAN.md
+
+# Remove tasks for features that already work
+# Add tasks for new features
+# Prioritize
+```
+
+**7. Start building**
+```bash
+# Start with small iteration count
+vralphy build 5
+
+# Verify everything works
+npm test
+git log -5
+
+# Increase iterations gradually
+vralphy build 10
+```
+
+### Migration Checklist
+
+- [ ] Git is clean
+- [ ] Tests already exist and pass
+- [ ] Build commands work
+- [ ] `.vralphy/AGENTS.md` is accurate
+- [ ] Initial specs created
+- [ ] First planning run completed
+- [ ] First build run successful
+- [ ] Team onboarded to workflow
+
+---
+
+## Workflow 5: Clean Slate / Re-initialization
+
+**Scenario**: Starting fresh after experimentation
+
+### Steps
+
+**1. Clean up vralphy**
+```bash
+vralphy cleanup --force
+
+# Removes:
+# - .vralphy/
+# - IMPLEMENTATION_PLAN.md
+# Keeps:
+# - specs/ (your specifications)
+```
+
+**2. Re-initialize**
+```bash
+vralphy init
+
+# Fresh .vralphy/AGENTS.md generated
+# Fresh prompt templates
+# Fresh IMPLEMENTATION_PLAN.md
+```
+
+**3. Start over**
+```bash
+# Specs are preserved
+# Ready to plan and build
+vralphy plan 2
+vralphy build 10
+```
+
+### When to Use
+
+- After major project changes
+- When `.vralphy/AGENTS.md` is stale
+- Testing different approaches
+- Onboarding new team members
+
+---
+
+## Workflow 6: Quick One-Off Changes
+
+**Scenario**: Small, focused changes
+
+### Steps
+
+**1. Add task to plan**
+```bash
+echo "- [ ] Add console.log to debug authentication" >> IMPLEMENTATION_PLAN.md
+```
+
+**2. Quick build**
+```bash
+vralphy build 1
+
+# AI implements the change
+# Commits if tests pass
+```
+
+**3. Verify**
+```bash
+git diff HEAD~1
+npm test
+```
+
+### When to Use
+
+- Debugging
+- Quick experiments
+- Small improvements
+- Documentation updates
+
+---
+
+## Workflow 7: Multi-Feature Development
+
+**Scenario**: Building several related features
+
+### Steps
+
+**1. Create multiple specs**
+```bash
+vralphy spec user-registration
+vralphy spec user-login
+vralphy spec password-reset
+vralphy spec email-verification
+```
+
+**2. Review all specs**
+```bash
+ls specs/
+# Ensure specs are complete and consistent
+```
+
+**3. Comprehensive planning**
+```bash
+vralphy plan 5
+
+# AI analyzes all specs
+# Creates unified plan
+# Identifies dependencies
+```
+
+**4. Build in priority order**
+```bash
+# AI automatically handles dependencies
+vralphy build 50
+
+# Implements features in correct order
+# Tests continuously
+# Commits incrementally
+```
+
+**5. Progress tracking**
+```bash
+# Periodically check progress
+cat IMPLEMENTATION_PLAN.md
+
+# View recent commits
+git log --oneline -20
+```
+
+### Best Practices
+
+- Define all specs upfront
+- Run planning before building
+- Use high iteration counts
+- Monitor progress regularly
+- Interrupt and re-plan if needed (Ctrl+C)
+
+---
+
+## Workflow 8: Collaborative Development
+
+**Scenario**: Multiple developers using vralphy
+
+### Setup
+
+**1. Commit vralphy files**
+```bash
+git add .vralphy/ specs/ IMPLEMENTATION_PLAN.md
+git commit -m "Add vralphy configuration"
+git push
+```
+
+**2. Team members pull**
+```bash
+git pull
+npm install -g vralphy@latest
+```
+
+### Daily Workflow
+
+**Developer A**:
+```bash
+# Morning: Pull latest
+git pull
+
+# Update plan
+vralphy plan 2
+
+# Build
+vralphy build 10
+
+# Push
+# (vralphy auto-commits and pushes)
+```
+
+**Developer B** (later):
+```bash
+# Pull latest (includes A's changes)
+git pull
+
+# Update plan (reflects A's work)
+vralphy plan 2
+
+# Build next priority items
+vralphy build 10
+```
+
+### Best Practices
+
+- Pull frequently
+- Re-plan after pulling
+- Use smaller iteration counts
+- Coordinate on high-priority items
+- Communicate via specs and plan
+
+---
+
+## Workflow 9: Testing-First Development
+
+**Scenario**: Write tests first, then implement
+
+### Steps
+
+**1. Create spec with explicit test requirements**
+```bash
+vralphy spec api-rate-limiting
+
+# Include in spec:
+# - Test scenarios
+# - Expected behavior
+# - Edge cases
+```
+
+**2. Update plan to prioritize tests**
+
+Edit `IMPLEMENTATION_PLAN.md`:
+```markdown
+## High Priority
+- [ ] Write tests for rate limiting
+- [ ] Implement rate limiting to pass tests
+```
+
+**3. Build tests first**
+```bash
+vralphy build 3
+
+# AI writes tests first
+# Tests will fail (no implementation yet)
+```
+
+**4. Build implementation**
+```bash
+vralphy build 5
+
+# AI implements to make tests pass
+```
+
+### Benefits
+
+- Clear requirements
+- No implementation without tests
+- High confidence in correctness
+
+---
+
+## Workflow 10: Documentation-Driven Development
+
+**Scenario**: Document first, then build
+
+### Steps
+
+**1. Write comprehensive spec**
+```bash
+vralphy spec comprehensive-api-docs
+
+# Include:
+# - API endpoints
+# - Request/response formats
+# - Error codes
+# - Examples
+```
+
+**2. Create README sections**
+
+Add to spec:
+```markdown
+## Documentation Requirements
+- [ ] Update README with API docs
+- [ ] Add JSDoc comments
+- [ ] Create usage examples
+```
+
+**3. Plan and build**
+```bash
+vralphy plan 3
+vralphy build 15
+
+# AI generates:
+# - Documentation
+# - Examples
+# - Comments
+# - Implementation
+```
+
+---
+
+## Common Patterns
+
+### Pattern: Checkpoint and Verify
+
+After every 5-10 build iterations:
+```bash
+# Stop and verify
+npm test
+cat IMPLEMENTATION_PLAN.md
+git log --oneline -10
+
+# Adjust if needed
+# Continue
+vralphy build 10
+```
+
+### Pattern: Plan-Build-Plan-Build
+
+For complex features:
+```bash
+# Initial plan
+vralphy plan 3
+
+# First implementation pass
+vralphy build 10
+
+# Re-plan with new knowledge
+vralphy plan 2
+
+# Continue building
+vralphy build 10
+```
+
+### Pattern: Spec Evolution
+
+Specs can evolve:
+```bash
+# Initial spec
+vralphy spec feature
+
+# Implement partially
+vralphy build 10
+
+# Update spec with new requirements
+vi specs/feature.md
+
+# Re-plan and continue
+vralphy plan 2
+vralphy build 10
+```
+
+### Pattern: Emergency Stop and Fix
+
+If build goes wrong:
+```bash
+# Stop immediately (Ctrl+C)
+
+# Check what happened
+git log -5
+git diff HEAD~1
+
+# Revert if needed
+git reset --hard HEAD~1
+
+# Fix the plan
+vi IMPLEMENTATION_PLAN.md
+
+# Resume carefully
+vralphy build 2
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+### ❌ Building Without Planning
+
+```bash
+# Bad
+vralphy build 20  # No plan!
+
+# Good
+vralphy plan 3
+vralphy build 20
+```
+
+### ❌ Too Many Iterations at Once
+
+```bash
+# Bad
+vralphy build 100  # Too much!
+
+# Good
+vralphy build 10
+# Check progress
+vralphy build 10
+```
+
+### ❌ Ignoring Failed Tests
+
+Never commit if tests fail. vralphy won't, but don't override:
+```bash
+# Bad
+git commit --no-verify  # Skips tests!
+
+# Good
+# Let vralphy handle commits after tests pass
+```
+
+### ❌ Manual Code Changes During Build
+
+```bash
+# Bad
+vralphy build 20 &  # Background
+vi src/app.ts       # Manual edit - conflict!
+
+# Good
+vralphy build 20    # Foreground
+# Wait for completion
+# Then make manual changes if needed
+```
+
+### ❌ Vague Specs
+
+```bash
+# Bad
+echo "Add authentication" > specs/auth.md
+
+# Good
+vralphy spec authentication
+# Provide detailed answers to AI questions
+```
+
+---
+
+## Tips and Tricks
+
+### Tip 1: Use --verbose for Debugging
+
+```bash
+vralphy --verbose build 2
+# Shows detailed execution
+```
+
+### Tip 2: Dry Run to Preview
+
+```bash
+vralphy --dry-run build 1
+# Shows prompt without executing
+```
+
+### Tip 3: Customize Prompts
+
+```bash
+vi .vralphy/prompts/build.md
+# Adjust AI behavior for your project
+```
+
+### Tip 4: Multiple Engines
+
+```bash
+# Use codex for planning (fast)
+vralphy --engine codex plan 3
+
+# Use claude for building (thorough)
+vralphy --engine claude build 10
+```
+
+### Tip 5: Save Checkpoints
+
+```bash
+# Before major changes
+git tag checkpoint-before-refactor
+
+# Experiment with vralphy
+vralphy build 20
+
+# Rollback if needed
+git reset --hard checkpoint-before-refactor
+```
+
+---
+
+## Next Steps
+
+- See [EXAMPLES.md](./EXAMPLES.md) for real-world examples
+- Read [METHODOLOGY.md](./METHODOLOGY.md) for deeper understanding
+- Check [COMMANDS.md](./COMMANDS.md) for command details