dotvibe Development Assistant

Expert agent for developing and maintaining **dotvibe**, a toolbox for coding agents that provides context-aware code search and powerful CLI utilities.

What This Skill Does

This skill helps you work on the dotvibe codebase following its strict architectural principles:

Core Architecture Principles

1. Functional Programming (NO CLASSES)

**NEVER create classes. Always use functional patterns:**

```typescript

// ❌ BAD - No classes

export class TokenTracker { ... }

// ✅ GOOD - Higher-order functions

export const createTokenTracker = (context: ThreadContext) => {

let state = { currentTokens: context.currentTokens }

return {

addTokens: (tokens: TokenEstimate) => {

state.currentTokens += tokens.totalTokens

return state.currentTokens

},

getProgress: () => formatProgress(state.currentTokens, context.maxTokens)

}

}

```

2. Test-Driven Development (CRITICAL)

**🚨 MANDATORY: Write tests FIRST, then implement. NO CODE BEFORE TESTS.**

```typescript

// 1. Create test file FIRST

// tests/core/new-feature.test.ts

describe('NewFeature', () => {

it('should handle basic functionality', () => {

// Test implementation

})

})

// 2. Run test (it should FAIL) - Red phase

// deno test tests/core/new-feature.test.ts

// 3. Implement minimal code to pass - Green phase

// src/infra/new-feature.ts

// 4. Refactor while keeping tests passing - Refactor phase

```

3. Effect-TS Patterns (KISS Principle)

```typescript

// ✅ Use Effect for async operations with error handling

Effect.tryPromise({

try: () => fileExists(path),

catch: (error) => createFileSystemError(error, path, 'Failed to check file')

})

// ✅ Error handling with tagged unions

export type VibeError =

| StorageError

| ConfigError

| ProcessingError

| NetworkError

// ❌ Don't use Effect for simple sync transformations

```

4. Dynamic Path Resolution

```typescript

// ❌ BAD - Hardcoded paths

const wasmPath = '/home/user/.cache/deno/npm/...'

// ✅ GOOD - Dynamic resolution

const wasmPath = await resolveWasmPath('tree-sitter-typescript')

const configPath = await resolveConfigPath('.vibe/config.json')

const dbPath = await resolveDatabasePath('surreal://localhost:8000')

```

Step-by-Step Instructions

When Adding a New Feature

1. **Create feature specification in prd.md** with acceptance criteria

2. **🚨 WRITE TESTS FIRST** (TDD approach - this is non-negotiable)

- Create test file in appropriate directory (`tests/core/`, `tests/agent/`, `tests/integration/`)

- Write test cases that describe desired behavior

- Run tests to verify they fail (red phase)

3. **Implement minimal code** to pass tests (green phase)

4. **Refactor** while keeping tests passing (refactor phase)

5. **Add @tested_by annotations** to all functions

6. **Verify all tests pass**: `deno test --allow-all`

7. **Update documentation** (ARCHITECTURE.md, CHANGELOG.md if needed)

When Refactoring Code

1. **Ensure existing tests cover the code** being refactored

2. **Run tests before changes**: `deno test --allow-all`

3. **Make incremental changes** while keeping tests green

4. **Remove any classes** - convert to functional patterns

5. **Eliminate hardcoded paths** - use dynamic resolution

6. **Update @tested_by annotations** if function signatures change

7. **Run tests after changes** to verify behavior preserved

When Fixing Bugs

1. **Write a failing test** that reproduces the bug (TDD)

2. **Run the test** to confirm it fails

3. **Fix the implementation** to pass the test

4. **Verify all tests pass**: `deno test --allow-all`

5. **Update @tested_by annotations** if needed

6. **Document the fix** in CHANGELOG.md

When Adding Dependencies

1. **Verify it's necessary** - prefer built-in Deno/stdlib solutions

2. **Check compatibility** with Deno runtime

3. **Update deno.json** imports map

4. **Update CLAUDE.md** Technology Stack section

5. **Write tests** for integration with new dependency

Technology Stack

File Structure

```

src/

├── infra/ # Consolidated primitives (config, storage, embeddings, errors, AST, logger)

├── agent/ # Clean agent system with composable primitives

├── commands/ # CLI entry points (init, index, query)

tests/

├── core/ # Core module tests

├── agent/ # Agent system tests

└── integration/ # End-to-end tests

```

Critical Rules (NEVER Violate)

❌ NEVER Do:

✅ ALWAYS Do:

Testing Commands

```bash

Core module tests

deno test tests/core/

Agent system tests

deno test tests/agent/

Full test suite

deno test --allow-all

CLI integration tests

./vibe index test_simple.ts

./vibe query "interface"

```

Build Commands

```bash

Build production binary

deno task build

Cross-platform builds

deno task build:cross-platform

Type checking

deno task check

```

Important Notes

Documentation Files