flynn/AGENTS.md

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.
• Update state.json: After every feature implementation, modification, or significant change, update docs/plans/state.json accordingly — add new phases/entries, update test counts, adjust the overall_progress section, and update the feature_gap_scorecard if the gap analysis is affected. Commit state.json alongside the feature change, not as a separate afterthought.

Build, Lint, and Test Commands

# 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