vralphy 0.2.0 → 0.3.0

package/docs/DESIGN.md

@@ -0,0 +1,537 @@
+# Design Principles
+
+The architecture and design decisions behind vralphy.
+
+## Core Principles
+
+### 1. Separation of Concerns
+
+vralphy cleanly separates three concerns:
+
+**WHAT to build** (`specs/`)
+- Feature specifications
+- Requirements and acceptance criteria
+- Written by humans
+
+**HOW to build** (`.vralphy/AGENTS.md`)
+- Operational commands (build, test, lint)
+- Project-specific patterns
+- Generated by AI, maintained by loop
+
+**WHAT'S LEFT to build** (`IMPLEMENTATION_PLAN.md`)
+- Prioritized task list
+- Updated by AI during plan/build phases
+- Living document
+
+This separation enables autonomous operation while keeping humans in control of requirements.
+
+### 2. Non-Invasive Design
+
+vralphy doesn't interfere with existing workflows:
+
+**File locations**:
+- All vralphy files in `.vralphy/` directory
+- `.vralphy/AGENTS.md` for vralphy's operational guide
+- Root `AGENTS.md` remains yours for Claude/OpenCode/Codex
+- No collision with existing AI tooling
+
+**Git-friendly**:
+- `.vralphy/` can be committed or gitignored
+- Plays nice with existing git workflows
+- Creates clean, descriptive commits
+
+### 3. Engine Abstraction
+
+Support multiple AI engines with unified interface:
+
+```typescript
+interface Engine {
+  execute(prompt: string, options: ExecuteOptions): AsyncIterable<Chunk>;
+  isAvailable(): Promise<boolean>;
+  getFlags(options: EngineFlags): string[];
+  supportsInteractive(): boolean;
+  getCommand(): string;
+}
+```
+
+**Implementations**:
+- `ClaudeEngine` - Anthropic's Claude CLI
+- `OpenCodeEngine` - OpenAI's code assistant
+- `CodexEngine` - Alternative AI engine
+
+**Auto-detection**: vralphy detects installed engines at runtime
+
+**Benefits**:
+- Users choose their preferred AI provider
+- Easy to add new engines
+- Consistent experience across engines
+
+### 4. Model Tiering
+
+Two-tier model system optimizes cost and performance:
+
+**Tier 1: Primary/Thinking** (opus by default)
+- **Purpose**: Complex reasoning, orchestration, decisions
+- **Use cases**: Planning, debugging, architecture
+- **Cost**: High, but needed for quality
+- **When**: Strategic decisions, complex analysis
+
+**Tier 2: Executor/Subagent** (sonnet by default)
+- **Purpose**: Parallel tasks, file operations
+- **Use cases**: Reading files, searching code, simple edits
+- **Cost**: Low, optimized for volume
+- **When**: Tactical execution, bulk operations
+
+**Configurable**:
+```bash
+vralphy --model opus --executor sonnet build
+```
+
+**Why?**: Expensive models for thinking, cheap models for doing.
+
+### 5. Massive Parallelism
+
+vralphy leverages parallel execution for performance:
+
+**Planning Phase**:
+```
+┌─────────────────────────────────────┐
+│ Read specs/* (250 parallel agents)  │
+├─────────────────────────────────────┤
+│ Search src/* (500 parallel agents)  │
+├─────────────────────────────────────┤
+│ Analyze (1 reasoning agent - opus)  │
+└─────────────────────────────────────┘
+```
+
+**Build Phase**:
+```
+┌─────────────────────────────────────┐
+│ Search codebase (500 parallel)      │
+├─────────────────────────────────────┤
+│ Write code (1 agent)                │
+├─────────────────────────────────────┤
+│ Run tests (1 sequential agent)      │
+├─────────────────────────────────────┤
+│ Reasoning (1 agent - opus)          │
+└─────────────────────────────────────┘
+```
+
+**Why parallel?**:
+- Reading files: IO-bound, parallelizes well
+- Building/testing: Must be sequential
+- Reasoning: Requires focused attention
+
+### 6. Context Efficiency
+
+Keep prompts lean to maximize token usage:
+
+**Operational guide** (`.vralphy/AGENTS.md`):
+- Max 60 lines
+- Commands only, no explanations
+- No changelogs or history
+- Generated once, maintained minimally
+
+**Lazy skill/agent loading**:
+- Skills stored in engine-native locations
+- Loaded on-demand when needed
+- Not injected into every prompt
+- Trigger-based discovery
+
+**Prompt templates**:
+- Stored in `.vralphy/prompts/`
+- Customizable per project
+- Interpolated with context variables
+
+**Why?**: Tokens are expensive. Load only what you need.
+
+### 7. Specification-Driven Development
+
+Specifications are the source of truth:
+
+**Specs define**:
+- What features exist
+- Expected behavior
+- Acceptance criteria
+- Edge cases
+- Dependencies
+
+**AI uses specs to**:
+- Understand requirements
+- Plan implementation
+- Verify completeness
+- Generate tests
+
+**Flow**:
+```
+Spec → Plan → Code → Tests → Verify against spec
+```
+
+**Benefits**:
+- Clear requirements
+- Testable outcomes
+- Traceable decisions
+- Team alignment
+
+### 8. Incremental Progress
+
+Small, focused changes:
+
+**Commits**:
+- One feature/fix per commit
+- Descriptive messages
+- Atomic changes
+- Frequent pushes
+
+**Iterations**:
+- Plan in small batches (3-5 iterations)
+- Build in small batches (10-20 iterations)
+- Test after each change
+- Update plan frequently
+
+**Why?**: Easier to review, debug, and rollback.
+
+### 9. Test-Driven Autonomy
+
+Tests gate progress:
+
+**Build phase logic**:
+```
+Implement feature
+  ↓
+Run tests
+  ↓
+Tests pass? → Commit + Push → Update plan → Next task
+  ↓
+Tests fail? → Debug → Run tests again
+```
+
+**Safety**:
+- Never commit failing tests
+- Debug failures automatically
+- Update `.vralphy/AGENTS.md` if test command changes
+
+**Benefits**:
+- High confidence in changes
+- Catches regressions early
+- Documents expected behavior
+
+### 10. Fail-Safe Design
+
+vralphy handles failures gracefully:
+
+**AI generation fails**:
+- `vralphy init` falls back to template
+- User notified, operation continues
+- Degraded mode still functional
+
+**Engine unavailable**:
+- `vralphy engines` shows status
+- Clear error messages
+- Installation guidance
+
+**Interrupted operations**:
+- Ctrl+C exits cleanly
+- No partial commits
+- Plan remains consistent
+
+**Missing files**:
+- `vralphy cleanup` handles gracefully
+- Reports what's missing
+- Doesn't error on not-found
+
+---
+
+## Architecture
+
+### Directory Structure
+
+```
+vralphy/
+├── src/
+│   ├── commands/           # CLI command implementations
+│   │   ├── build.ts
+│   │   ├── plan.ts
+│   │   ├── spec.ts
+│   │   ├── init.ts
+│   │   └── cleanup.ts
+│   ├── lib/
+│   │   ├── engines/        # Engine implementations
+│   │   │   ├── base.ts     # Engine interface
+│   │   │   ├── claude.ts
+│   │   │   ├── opencode.ts
+│   │   │   └── codex.ts
+│   │   ├── config.ts       # Configuration handling
+│   │   ├── prompts.ts      # Prompt templates
+│   │   ├── context.ts      # Project context gathering
+│   │   ├── init.ts         # Initialization logic
+│   │   ├── skills.ts       # Skill management
+│   │   └── agents.ts       # Agent management
+│   └── index.ts            # CLI entry point
+├── docs/                   # LLM-friendly documentation
+├── bin/
+│   └── vralphy.js          # Executable wrapper
+└── package.json
+```
+
+### Project Structure (After Init)
+
+```
+your-project/
+├── .vralphy/
+│   ├── AGENTS.md           # Operational guide
+│   └── prompts/
+│       ├── plan.md
+│       ├── build.md
+│       └── spec.md
+├── specs/                  # Specifications
+│   └── feature.md
+├── IMPLEMENTATION_PLAN.md  # Task list
+└── src/                    # Your code
+```
+
+### Data Flow
+
+**Initialization**:
+```
+Project → Context gathering → AI analysis → AGENTS.md generation → Scaffold creation
+```
+
+**Specification**:
+```
+User input → AI questions → User answers → Spec generation → Save to specs/
+```
+
+**Planning**:
+```
+.vralphy/AGENTS.md + specs/* + src/* → AI analysis → IMPLEMENTATION_PLAN.md update
+```
+
+**Building**:
+```
+IMPLEMENTATION_PLAN.md → Task selection → Code search → Implementation → Test → Commit
+     ↑                                                                           ↓
+     └───────────────────────────── Update plan ──────────────────────────────┘
+```
+
+---
+
+## Technology Choices
+
+### TypeScript
+
+**Why**: Type safety, better tooling, clearer interfaces
+
+**Benefits**:
+- Catch errors at compile time
+- IDE autocomplete
+- Self-documenting code
+
+### Commander.js
+
+**Why**: Standard CLI framework for Node.js
+
+**Benefits**:
+- Clean command syntax
+- Built-in help
+- Argument parsing
+
+### Vitest
+
+**Why**: Fast, modern testing framework
+
+**Benefits**:
+- ESM support
+- Fast execution
+- Great DX
+
+### ESM (ES Modules)
+
+**Why**: Modern JavaScript standard
+
+**Benefits**:
+- Native import/export
+- Tree-shaking
+- Future-proof
+
+---
+
+## Design Trade-offs
+
+### AI-Powered Init vs Template-Only
+
+**Decision**: AI-powered with template fallback
+
+**Trade-off**: Complexity vs quality
+- AI init: Better quality, requires engine, slower
+- Template: Always works, simpler, generic
+
+**Resolution**: Both - AI when available, template as fallback
+
+### Monorepo vs Multi-Package
+
+**Decision**: Single package (`vralphy`)
+
+**Trade-off**: Simplicity vs modularity
+- Single: Easier to install, simpler for users
+- Multi: Better code organization, reusable modules
+
+**Resolution**: Single package - user experience wins
+
+### Hardcoded Prompts vs External Files
+
+**Decision**: Both - defaults hardcoded, customizable external
+
+**Trade-off**: Convenience vs flexibility
+- Hardcoded: Works out of box, no config needed
+- External: Customizable, project-specific
+
+**Resolution**: Hardcoded defaults in code, customizable in `.vralphy/prompts/`
+
+### Auto-Commit vs Manual Review
+
+**Decision**: Auto-commit with test gates
+
+**Trade-off**: Automation vs control
+- Auto: Fully autonomous, faster
+- Manual: More control, safer
+
+**Resolution**: Auto-commit only when tests pass - best of both
+
+---
+
+## Extensibility
+
+### Adding New Engines
+
+Implement the `Engine` interface:
+
+```typescript
+class MyEngine implements Engine {
+  readonly name = 'myengine';
+
+  async *execute(prompt: string, options: ExecuteOptions): AsyncIterable<Chunk> {
+    // Implementation
+  }
+
+  async isAvailable(): Promise<boolean> {
+    // Check if engine CLI is installed
+  }
+
+  getFlags(options: EngineFlags): string[] {
+    // Return engine-specific flags
+  }
+
+  supportsInteractive(): boolean {
+    return true; // or false
+  }
+
+  getCommand(): string {
+    return 'myengine';
+  }
+}
+```
+
+Register in `src/lib/engines/index.ts`:
+```typescript
+const engines: Record<EngineName, Engine> = {
+  claude: new ClaudeEngine(),
+  opencode: new OpenCodeEngine(),
+  codex: new CodexEngine(),
+  myengine: new MyEngine(),
+};
+```
+
+### Adding New Commands
+
+1. Create command file: `src/commands/mycommand.ts`
+2. Export command function
+3. Register in `src/index.ts`
+
+Example:
+```typescript
+// src/commands/mycommand.ts
+export async function myCommand(options: MyOptions): Promise<void> {
+  // Implementation
+}
+
+// src/index.ts
+import { myCommand } from './commands/mycommand.js';
+
+program
+  .command('mycommand')
+  .description('Description')
+  .action(async (opts) => {
+    await myCommand(opts);
+  });
+```
+
+### Customizing Prompts
+
+Edit files in `.vralphy/prompts/`:
+
+- `plan.md` - Planning phase prompt
+- `build.md` - Build phase prompt
+- `spec.md` - Spec creation prompt
+
+Prompts support variables:
+- `${model}` - Primary model
+- `${executor}` - Executor model
+- `${engine}` - Engine name
+- `${skillsDir}` - Skills directory
+- `${agentsDir}` - Agents directory
+
+---
+
+## Security Considerations
+
+### No Secrets in Prompts
+
+- Never include API keys or secrets in specs
+- `.vralphy/AGENTS.md` should not contain credentials
+- AI has read access to codebase - keep secrets in env vars
+
+### Git Safety
+
+- Never run destructive git commands without user approval
+- Always create new commits (not amend) after hook failures
+- Prefer specific file staging over `git add -A`
+- Never skip git hooks (--no-verify) unless explicitly requested
+
+### Sandboxing
+
+- AI executes in project directory context
+- No access outside project directory
+- Uses project's git config and permissions
+
+---
+
+## Performance Considerations
+
+### Parallel Execution
+
+- Reading: Highly parallel (250-500 agents)
+- Writing: Sequential (1 agent)
+- Testing: Sequential (1 agent)
+- Reasoning: Focused (1 primary model)
+
+### Token Optimization
+
+- Keep `.vralphy/AGENTS.md` under 60 lines
+- Lazy-load skills and agents
+- Use cheap models for bulk operations
+- Use expensive models for reasoning
+
+### Network Efficiency
+
+- Stream responses when possible
+- Batch file reads in parallel
+- Cache repeated operations (future enhancement)
+
+---
+
+## Next Steps
+
+- Read [METHODOLOGY.md](./METHODOLOGY.md) for the Ralph approach
+- Check [WORKFLOWS.md](./WORKFLOWS.md) for usage patterns
+- See [EXAMPLES.md](./EXAMPLES.md) for real-world cases