Skip to content

getting-started.md

Latest commit

 

History

History
360 lines (250 loc) · 7.04 KB

getting-started.md

File metadata and controls

360 lines (250 loc) · 7.04 KB
Raw

Getting Started with Vibe Agent Toolkit

This guide will help you set up and start developing portable AI agents with the toolkit.

Prerequisites

Before you begin, ensure you have the following installed:

Initial Setup

1. Clone and Install

# Clone the repository
git clone https://github.com/jdutton/vibe-agent-toolkit.git
cd vibe-agent-toolkit

# Install dependencies
bun install

2. Verify Installation

# Build all packages
bun run build

# Run tests (do NOT use 'bun test' - use commands below)
vv validate            # Full validation (recommended)
# OR: bun run test:unit  # Unit tests only

# Run linting
bun run lint

# Run type checking
bun run typecheck

If all commands pass, you're ready to start developing!

Development Workflow

Day-to-Day Development

# Start development with watch mode
bun run test:watch

# In another terminal, make changes to your code
# Tests will automatically re-run

# When ready to commit:
git add .
git commit -m "feat: add new feature"
# Pre-commit hooks will run automatically

Creating Your First Package

  1. Remove the example package (if you don't need it):
rm -rf packages/example-utils
  1. Create your package:
mkdir -p packages/my-package/src packages/my-package/test
  1. Add package configuration:

Create package.json, tsconfig.json (with composite: true), and add to root tsconfig.json references. See CLAUDE.md Development Workflow section for complete details.

  1. Update root tsconfig.json:

Edit tsconfig.json to include your new package in the references array.

  1. Install and build:
bun install
bun run build

Writing Tests

Unit Tests

Create *.test.ts files alongside your source code or in test/ directory:

// packages/my-package/src/utils.test.ts
import { describe, expect, it } from 'vitest';
import { myFunction } from './utils.js';

describe('myFunction', () => {
  it('should do something', () => {
    expect(myFunction('input')).toBe('expected');
  });
});

Integration Tests

Create *.integration.test.ts files in test/integration/:

// packages/my-package/test/integration/workflow.integration.test.ts
import { describe, expect, it } from 'vitest';

describe('Workflow Integration', () => {
  it('should complete end-to-end workflow', () => {
    // Test multiple modules working together
  });
});

System Tests

Create *.system.test.ts files in test/system/:

// packages/my-package/test/system/e2e.system.test.ts
import { describe, expect, it } from 'vitest';

describe('E2E System Test', () => {
  it('should work with real services', () => {
    // Test complete system with real dependencies
  });
});

Running Validation

Before pushing code:

# Run full validation (like CI)
bun run validate

This runs:

  1. TypeScript type checking
  2. ESLint (strict)
  3. Code duplication check
  4. Build
  5. Tests
  6. Coverage report

Common Tasks

Adding a Dependency

# Add to workspace root
bun add -D some-dev-dependency

# Add to a specific package
cd packages/my-package
bun add some-dependency

# Or from root:
bun add some-dependency --filter @your-org/my-package

Updating Dependencies

# Update all dependencies
bun update

# Check for outdated packages
bun outdated

Debugging Tests

Note: Do NOT use bun test directly - use the commands below instead.

# Run a specific test file
bunx vitest packages/my-package/test/mytest.test.ts

# Run with verbose output
bun run test:unit --reporter=verbose

# Run tests matching a pattern
bun run test:unit --grep "my test pattern"

Fixing Linting Issues

# Auto-fix linting issues
bun run lint:fix

# Check specific files
bunx eslint packages/my-package/src/myfile.ts

Managing Code Duplication

# Check for new duplication
bun run duplication-check

# Update baseline after refactoring
bun run duplication-update-baseline

IDE Setup

VS Code

Recommended extensions:

  • ESLint
  • EditorConfig for VS Code
  • Vitest
  • TypeScript + JavaScript

Settings will be automatically applied from .editorconfig.

Other IDEs

The project uses .editorconfig which is supported by most modern IDEs:

  • IntelliJ IDEA / WebStorm
  • Sublime Text
  • Atom
  • And many more

Troubleshooting

Build Errors

# Clean build
bun run build:clean

# Remove all node_modules and reinstall
bun run clean
bun install

Test Failures

# Run tests with more detail
bun run test:unit --reporter=verbose

# Update snapshots if needed
bunx vitest -u

Pre-commit Hook Issues

# Reinstall hooks
rm -rf .husky
bun install

# Make hook executable
chmod +x .husky/pre-commit

Bun Installation Issues

If bun commands fail:

# Reinstall bun
curl -fsSL https://bun.sh/install | bash

# Verify installation
bun --version

Working with Agent Skills

Auditing Skills

Validate Agent Skills for quality and compatibility:

# Audit a single skill
vat agent audit my-skill/SKILL.md

# Audit all skills in a directory
vat agent audit skills/ --recursive

# View detailed validation errors
vat agent audit my-skill/SKILL.md --debug

The audit command checks for:

  • Required frontmatter fields (name, description)
  • Naming conventions (lowercase, hyphens, no reserved words)
  • Description length (max 1024 characters)
  • Link integrity (broken links, invalid paths)
  • Console compatibility (tool availability)

See Audit Command Documentation for complete validation rules.

Importing Skills

Convert Agent Skills to VAT agent format:

# Import skill to agent.yaml
vat agent import my-skill/SKILL.md

# Import with custom output path
vat agent import my-skill/SKILL.md --output my-agent/agent.yaml

# Force overwrite existing agent.yaml
vat agent import my-skill/SKILL.md --force

Typical workflow:

# 1. Create or edit SKILL.md
vim my-skill/SKILL.md

# 2. Validate before import
vat agent audit my-skill/SKILL.md

# 3. Import to VAT format
vat agent import my-skill/SKILL.md

# 4. Use VAT tooling
cd my-skill
vat test
vat package

See Import Command Documentation for more details.

Next Steps

Getting Help

  • Check existing documentation in docs/
  • Review the example package implementation
  • Read inline comments in configuration files
  • Open an issue on GitHub for bugs or questions

Happy coding! 🚀