William Valentin
94 lines
3.5 KiB
Markdown
94 lines
3.5 KiB
Markdown
# Flynn AGENTS.md
|
|
|
|
## General Rules
|
|
|
|
- **Parallelise with subagents:** For every task, use multiple subagents with the appropriate model to work more efficiently. Dispatch independent subtasks in parallel rather than executing them sequentially.
|
|
- **Subagent model selection (MANDATORY):** You MUST use the right model tier for each subagent — `claude-haiku-4.5` for fast/simple/mechanical tasks, `claude-sonnet-4.5` for default/standard implementation work, and `claude-opus-4.6` for complex reasoning or architecture decisions. Never use the same model for all subagents.
|
|
- **Commit often:** `git commit` frequently — after each meaningful unit of work, not just at the end of a task.
|
|
|
|
## Build, Lint, and Test Commands
|
|
|
|
```bash
|
|
# Build
|
|
pnpm build # Compile TypeScript to dist/
|
|
|
|
# Development
|
|
pnpm dev # Run daemon with watch mode
|
|
pnpm tui # Run TUI in minimal mode (readline)
|
|
pnpm tui:fs # Run TUI in fullscreen mode (React/Ink)
|
|
pnpm tui:dev # Run TUI with watch mode
|
|
|
|
# Run
|
|
pnpm start # Start production build
|
|
|
|
# Testing
|
|
pnpm test # Run tests in watch mode
|
|
pnpm test:run # Run tests once (no watch)
|
|
|
|
# Linting and Type Checking
|
|
pnpm lint # Run ESLint
|
|
pnpm typecheck # Run TypeScript compiler (no emit)
|
|
```
|
|
|
|
## Code Style Guidelines
|
|
|
|
### Imports
|
|
|
|
- Use `.js` extensions for imports (e.g., `import { readFileSync } from 'fs';`)
|
|
- Use `type` keyword for type-only imports: `import type { Config } from './schema.js';`
|
|
- Group imports: stdlib → third-party → local
|
|
- Export all public APIs from `index.ts`
|
|
|
|
### Naming Conventions
|
|
|
|
- **Classes/Interfaces/Types**: PascalCase (`AnthropicClient`, `NativeAgentConfig`)
|
|
- **Functions**: camelCase (`loadConfig`, `expandEnvVars`)
|
|
- **Private fields**: camelCase with underscore (`_client`, `_model`)
|
|
- **Files**: camelCase for .ts files, PascalCase for .tsx files
|
|
- **Test files**: `*.test.ts` suffix
|
|
|
|
### TypeScript Configuration
|
|
|
|
- `tsconfig.json` uses strict mode
|
|
- Target: ES2022
|
|
- Module resolution: NodeNext
|
|
- Module format: NodeNext
|
|
- Enables `declaration`, `declarationMap`, and `sourceMap` for all builds
|
|
|
|
### Error Handling
|
|
|
|
- Throw errors with descriptive messages
|
|
- Check for undefined/null with context: `throw new Error('Environment variable ${envVar} is not set')`
|
|
- In stream handlers, wrap errors in try-catch and yield error events
|
|
- Use `instanceof Error` for error type checking: `error instanceof Error ? error.message : 'Unknown error'`
|
|
- Catch errors and convert to appropriate error types with context
|
|
|
|
### React/Ink Patterns
|
|
|
|
- Use `useCallback` for event handlers to prevent unnecessary re-renders
|
|
- Use `useRef` for mutable values that don't trigger re-renders
|
|
- Define interface props explicitly
|
|
- Event handlers receive `(inputChar: string, key: KeyInfo)` as arguments
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
src/
|
|
├── config/ # YAML config + validation
|
|
├── models/ # Model providers + router
|
|
├── session/ # SQLite persistence
|
|
├── hooks/ # Confirmation engine
|
|
├── daemon/ # Lifecycle management
|
|
├── frontends/ # Telegram bot, TUI
|
|
└── backends/native/ # Agent implementation
|
|
```
|
|
|
|
## Testing
|
|
|
|
- Use Vitest for testing
|
|
- Follow `describe`/`it` pattern
|
|
- Use `expect()` for assertions
|
|
- Test both success and failure cases
|
|
- Clean up test resources (files, dirs) in `afterEach` or `it` cleanup blocks
|
|
- Mock file system and environment variables when needed
|