# Vincent Framework: AI Development Guidelines

## Overview

The Vincent Scaffold SDK is a specialized framework for creating **Vincent Abilities** and **Vincent Policies** that execute on Lit Actions - a blockchain-based execution environment with strict constraints. This document provides essential guidance for AI agents working with Vincent projects.

## 🚨 CRITICAL CONSTRAINTS

### Lit Actions Environment Limitations

Vincent abilities and policies execute in a restricted environment:

- **❌ NO `globalThis`** - Standard global objects are not available
- **❌ NO `process.env`** - Environment variables cannot be accessed
- **❌ NO persistent memory** - State doesn't persist between executions
- **❌ NO file system access** - Cannot read/write files during execution
- **❌ NO standard Node.js APIs** - Limited runtime environment

### Forbidden Patterns

- **NEVER** use mock or fake data in implementations
- **NEVER** assume environment variables are available in abilities/policies
- **NEVER** rely on persistent state within the execution context
- **NEVER** use standard Node.js modules in ability/policy logic

## 🏗️ Vincent Architecture

### Core Components

1. **Vincent Abilities** - Executable actions (e.g., token transfers, API calls)
2. **Vincent Policies** - Governance rules that control ability execution
3. **Lit Actions** - Secure execution environment for abilities/policies
4. **E2E Testing Framework** - Integrated testing with blockchain simulation

### Three-Phase Execution Model

#### Abilities

1. **Precheck** - Validate inputs (runs outside Lit Actions)
2. **Execute** - Perform the operation (runs in Lit Actions)

#### Policies

1. **Precheck** - Early validation (runs outside Lit Actions)
2. **Evaluate** - Runtime checks (runs in Lit Actions)
3. **Commit** - Record state changes (runs in Lit Actions)

## 📋 Schema-Driven Development

### Required Patterns

All Vincent components MUST use Zod schemas for type safety:

```typescript
// Ability parameters
export const abilityParamsSchema = z.object({
  to: z.string().regex(/^0x[a-fA-F0-9]{40}$/, "Invalid address"),
  amount: z.string().regex(/^\d*\.?\d+$/, "Invalid amount")
});

// Result schemas for each phase
export const precheckSuccessSchema = z.object({...});
export const precheckFailSchema = z.object({...});
export const executeSuccessSchema = z.object({...});
export const executeFailSchema = z.object({...});
```

### Schema Validation Rules

- Define schemas BEFORE implementation
- Use descriptive error messages
- Export type definitions: `export type AbilityParams = z.infer<typeof abilityParamsSchema>;`
- Validate ALL inputs and outputs

## 🔧 laUtils API Usage

### Available APIs

This are available in the:

- execute() hook inside the vincent policy
- evaluate() hook inside the vincent ability

```typescript
import { laUtils } from "@lit-protocol/vincent-scaffold-sdk/la-utils";
laUtils.transaction.handler.contractCall(); // Execute contract calls
laUtils.transaction.handler.nativeSend(); // Send native tokens
laUtils.helpers.toEthAddress(); // Address utilities
```

### Usage Constraints

- **✅ CAN use** in ability `execute` hooks
- **✅ CAN use** in policy `evaluate` and `commit` hooks
- **❌ CANNOT use** in `precheck` hooks (not in Lit Actions context)

## 🏗️ Project Structure

### Directory Layout

```
vincent-packages/
├── abilities/
│   └── my-ability/
│       ├── src/lib/
│       │   ├── schemas.ts
│       │   ├── vincent-ability.ts
│       │   └── helpers/index.ts
│       ├── package.json
│       └── .gitignore
└── policies/
    └── my-policy/
        ├── src/lib/
        │   ├── schemas.ts
        │   ├── vincent-policy.ts
        │   └── helpers/index.ts
        ├── package.json
        └── .gitignore
```

## 🛠️ Development Workflow

### Creating New Abilities/Policies

1. Use CLI: `npx @lit-protocol/vincent-scaffold-sdk add ability my-ability`
2. CD into the ability or policy directory
3. Update schemas in `src/lib/schemas.ts`
4. Implement logic in `src/lib/vincent-ability.ts` or `src/lib/vincent-policy.ts`
5. Add helpers in `src/lib/helpers/index.ts` if needed
6. Update root `package.json` build script
7. Build: `npm run vincent:build`
8. Test: `npm run vincent:e2e`

## 🧪 Testing & Validation

### E2E Testing Pattern

```typescript
// Import built abilities/policies
import { bundledVincentAbility } from "../../vincent-packages/abilities/my-ability/dist/index.js";
import { vincentPolicyMetadata } from "../../vincent-packages/policies/my-policy/dist/index.js";

// Register and test
const result = await chainClient.executeAbilities({
  abilities: [myAbilityConfig],
  // ... test configuration
});
```

### Test Commands

```bash
npm run vincent:hardreset         # Reset all state and rebuild
npm run vincent:build              # Build all abilities and policies
npm run vincent:e2e:reset         # Reset E2E test state only
npm run vincent:e2e               # Run native transfer E2E tests
npm run vincent:e2e:erc20         # Run ERC-20 transfer E2E tests
```

## 🎯 Best Practices

### Code Quality

- Follow existing code patterns exactly
- Use TypeScript strictly
- Implement comprehensive error handling
- Add detailed logging for debugging
- Maintain consistent naming conventions

### Security

- Validate all inputs with Zod schemas
- Never expose sensitive data in logs
- Use proper error messages without revealing internals
- Follow principle of least privilege

### Performance

- Minimize computation in Lit Actions
- Use efficient data structures
- Cache expensive operations when possible
- Keep ability/policy logic focused and minimal

## 🚫 Common Pitfalls

1. **Using forbidden APIs** - Check Lit Actions constraints
2. **Missing schema validation** - Always validate inputs/outputs
3. **Forgetting build script updates** - New abilities won't build
4. **Incorrect import paths** - Use relative paths to dist/
5. **Mock data usage** - Never use fake data in implementations
6. **Environment variable access** - Not available in Lit Actions
7. **State persistence assumptions** - Memory doesn't persist

## 📚 Reference Implementation

Always refer to existing working examples:

- **Ability example**: `vincent-packages/abilities/native-send/`
- **Policy example**: `vincent-packages/policies/send-counter-limit/`
- **E2E tests**: `vincent-e2e/src/e2e.ts`
- **Template files**: `src/templates/ability/` and `src/templates/policy/`

## 🆘 When You Need Help

If implementation details are unclear:

1. **DO NOT** create mock or placeholder data
2. **DO NOT** make assumptions about missing information
3. **DO** ask for specific clarification about requirements
4. **DO** provide concrete examples of what information is needed
5. **DO** suggest proper solutions rather than workarounds

Remember: Vincent development requires precision due to blockchain execution constraints. When in doubt, ask for clarification rather than implementing potentially incorrect solutions.