xonecas.io
53129
Pa

PAT / commit b71e5fc

feat: use a more concise agents file.

xonecas2025-12-19 b71e5fc2d48b6310c1403bb837537423f27bfa55 parent 08425e6

2 files changed

AGENTS.md+51−124
@@ -1,127 +1,54 @@
1-# AGENTS.md
2-
3-This is a personal assistant project, that renders a simple assistant chat layout as a web page, and provides access to an agentic model running locally via ollama. The project uses Next.js for it's typescript framework TailwindCSS for it's styling, and Ollama's typescript/javascript library itself for querying the model.
4-
5-You are assisting a developer to implement new features, fix bugs, and maintain the project.
6-
7-## Project Commands
8-
9-All commands should be run from the project root directory.
10-Commands are listed in [package.json](./package.json) in the scripts section. Use npm to run commands: `npm run <command>`.
11-
12-## Dependencies
13-
14-Use only these existing dependencies.
15-Do NOT add new dependencies without explicit approval.
16-Dependencies are listed in the file [package.json](./package.json).
17-
18-## Code Style Guidelines
19-
20-Always make sure the code is linted, formatted and the tests are passing.
21-Always update existing tests.
22-Add tests when prompted only.
23-
24-### Code Style Rules
25-
26-1. **File Organization**:
27- - Use Next.js App Router structure (`app/` directory)
28- - API routes in `app/api/[route]/route.ts`
29- - Library utilities in `src/lib/`
30- - Reusable components in `src/components/`
31- - Icon components in `src/components/icons/`
32- - Custom React hooks in `src/hooks/`
33- - Test files use `.test.ts` or `.test.tsx` extension (e.g., `ratelimit.test.ts`)
34- - TypeScript types are imported directly from `src/lib/db/schema` (Drizzle ORM inferred types)
35- - Use TypeScript for all code files (`.ts`, `.tsx`)
36-
37-2. **Component Style**:
38- - Use functional components with React hooks
39- - Use `"use client"` directive for client components
40- - Export default for page components
41- - Use named exports for utility functions
42-
43-3. **Naming Conventions**:
44- - Functions: `camelCase` (e.g., `sendMessage`) or `PascalCase` for main API functions (e.g., `OllamaChat`)
45- - Components: `PascalCase` (e.g., `Home`, `RootLayout`)
46- - Interfaces: `PascalCase` (e.g., `OllamaMessage`, `OllamaChatResponse`)
47- - Constants: `UPPER_SNAKE_CASE` or `camelCase` depending on scope
48-
49-4. **TypeScript Types**:
50- - Use interfaces for object shapes
51- - Use type annotations for function parameters and return types
52- - Prefer explicit types over `any`
53- - Use JSDoc comments for function documentation
54-
55-5. **Async/Await**:
56- - Always use `async/await` instead of promises with `.then()`
57- - Use `try/catch` for error handling in async functions
58- - API routes should return `NextResponse` objects
59-
60-6. **Styling**:
61- - Avoid using CSS
62- - Use TailwindCSS utility classes exclusively
63- - Inline Tailwind classes in JSX
64-
65-7. **Code Formatting**:
66- - Use Prettier for code formatting: `npm run format` to format all files
67- - Prettier configuration is in `.prettierrc`
68-
69-8. **Error Handling**:
70- - Use `lib/debug` for debug information
71- - Return user-friendly error messages in API responses
72- - Handle API errors gracefully with try/catch blocks
73- - The UI should always reflect errors to the user
74-
75-9. **Imports**:
76- - Use absolute imports with `@/` prefix for local files (e.g., `import PaperPlaneIcon from "@/src/components/icons/PaperPlaneIcon"`)
77- - Group imports: external packages first, then local imports
78- - Use named imports from libraries (e.g., `import { NextResponse } from "next/server"`)
79- - Use default imports for component files (e.g., `import PaperPlaneIcon from "@/src/components/icons/PaperPlaneIcon"`)
80- - Path alias `@/` is configured in `tsconfig.json` to point to the project root
1+# Agent Instructions
2+
3+## Important Instructions
4+
5+- **Never make assumptions** - Ask for clarification instead.
6+- **Never ignore errors, warnings, or issues** - Address them immediately.
7+- **Never install, uninstall, or delete anything** without explicit authorization.
8+- **Never commit or add to git secrets and passwords.**
9+- **Never add code that is not used** - only add the minimum necessary to satisfy the task.
10+- **Always do exactly what was asked** - Don't add anything that wasn't explicitly mentioned.
11+- **Always lint and typecheck** changes using `npm run lint` and `npm run typecheck`.
12+- **Always write modular, testable code** - Prefer small, focused functions and components, easy to re-use.
13+
14+## Coding Guidelines
15+
16+### TypeScript
17+- Use strict typing - avoid `any`, prefer type inference where appropriate.
18+- Export types/interfaces alongside implementations.
19+- Use the types provided by dependencies when possible, avoid creating types for 3rd party code.
20+- Use Drizzle ORM type inference: `typeof table.$inferSelect` and `typeof table.$inferInsert`.
21+
22+### Code Organization
23+- Use path aliases: `@/` for root imports (e.g., `@/src/components/...`).
24+- Follow modular structure: `src/components/`, `src/hooks/`, `src/lib/`, `app/api/`.
25+- Keep files focused - one main export per file when possible.
26+
27+### Documentation
28+- Add JSDoc comments for exported functions with `@param` and `@returns`.
29+- Keep commenting to a minimum. We should only add comments when the code is not self-explanatory
30+
31+### Naming Conventions
32+- `camelCase` for functions, variables, and hooks (e.g., `useLocalStorage`, `handleSubmit`).
33+- `PascalCase` for components, types, and interfaces (e.g., `MessageInput`, `MessageInputRef`).
34+- `kebab-case` for file names (except React components which use PascalCase).
35+
36+### React Patterns
37+- Use functional components with hooks.
38+- Use `forwardRef` when ref forwarding is needed.
39+- Properly type component props and refs.
40+- Handle loading and error states explicitly.
41+
42+### Error Handling
43+- Use try-catch blocks for async operations.
44+- Return proper HTTP status codes in API routes (400, 404, 500).
45+- Log errors using the `debug` utility from `@/src/lib/debug`.
46+
47+### Database
48+- Use Drizzle ORM query builder patterns.
49+- Use `eq()`, `asc()`, `desc()` from `drizzle-orm` for queries.
8150
8251 ### Testing
52+- Write tests using Vitest for complex logic.
53+- Keep tests in `src/tests/` mirroring the source structure.
8354
84-- **Configuration**: `vitest.config.ts` - Configures Vitest with TypeScript support and path aliases
85-- **Test Files**: Test files use `.test.ts` or `.test.tsx` extension and are located alongside the code they test
86-- **Test Commands**:
87- - `npm test` - Run tests in watch mode
88- - `npm run test:run` - Run tests once and exit
89-- **Mocking**: Tests use Vitest's mocking capabilities to isolate units (e.g., cache module is mocked in rate limiter tests)
90-
91-### Database Integration (Drizzle ORM)
92-
93-- **Database**: PostgreSQL using postgres driver
94-- **Connection**: Requires `DATABASE_URL` environment variable (format: `postgresql://user:password@host:port/database`)
95-- **Docker Setup**: PostgreSQL runs in Docker container via `npm run start:docker` script
96- - Container name: `postgres`
97- - Default port: `5432` (configurable via `POSTGRES_PORT` env var)
98- - Default database: `personal_assistant` (configurable via `POSTGRES_DB` env var)
99- - Default user: `postgres` (configurable via `POSTGRES_USER` env var)
100- - Requires `POSTGRES_PASSWORD` environment variable
101- - Data persisted in Docker volume `postgres_data`
102-- **Schema**: Defined in `src/lib/db/schema.ts`
103-- **Types**: Type definitions for `Thread` and `Message` are exported from `src/lib/db/schema` using Drizzle's `$inferSelect` (import directly from schema, e.g., `import type { Thread, Message } from "@/src/lib/db/schema"`)
104-- **Configuration**: `drizzle.config.ts` defines schema path and database connection
105-- **Migrations**: Generated in `drizzle/` directory using `npm run db:generate`
106-- **Usage**: Import `db` from `src/lib/db/index.ts` to query the database
107-
108-## Development Workflow
109-
110-1. Make code changes
111-2. Ask the user to test in browser
112-3. Update existing tests and add more if prompted to.
113-4. Format code: `npm run format`
114-5. Check for errors in compilation: `npm run typecheck`
115-6. Run linter: `npm run lint` **NEVER USE IGNORE COMMENTS**
116-7. Run tests: `npm run test:run` (verify all tests pass)
117-
118-## Important Constraints
119-
120-- **DO NOT** add new npm packages without explicit approval
121-- **DO NOT** Commit secrets or API keys, edit `node_modules/` or `vendor/`
122-- **DO NOT** Erase any data without explicit approval
123-- **DO** maintain existing code style and patterns
124-
125-# Known issues:
126-
127-The google based websearch can randomly fail with Request Entity not found. Generating a new custom search engine ID fixes the issue. Google has ignored all efforts to report this issue to them.
TODO.md+0−18
@@ -1,18 +0,0 @@
1-# TODO:
2-
3-## BUGS:
4-
5-- so far so good?
6-
7-## New features:
8-
9-- Sidebar improvements, more information about the thread quickly
10-- Text input, we should be able to press a button and record a prompt.
11-- Text to voice, we should have a button to have the models replies be read with text to voice.
12-
13-# new thread setting: User Prompt
14-
15-- Add a new thread setting called user prompt, a string, this setting should be persisted in the threads table and default to null
16-- Update the system prompt generation to include the user prompt if it is not null
17-
18-Extract the system prompt generation from the route file into it's own file in lib/ollama/system-prompt