bragdoc.ai - instructions for code-generating LLMS

# bragdoc.ai - instructions for code-generating LLMS

Every time you choose to apply a rule(s), explicitly state the rule(s) in the output. You can abbreviate the rule description to a single word or phrase.

## Project Context

The project is called bragdoc.ai and is a chatbot that helps users keep a brag document about their achievements at work. Key features:
- Reads/listens to user messages, creates rows in a Achievements table for each achievement the user mentioned
- Creates weekly/monthly/performance review documents based on the data in the Achievements table
- Integrates with GitHub to extract achievements from commit messages and pull request descriptions

Note that not all features are implemented yet, but the core idea is to help users keep a brag document about their achievements at work. Each Achievement can be linked to a Company (there is a Companies table in the db), and a Project (there is a Projects table in the db), though both are optional.

## Code Style and Structure
- Write concise, technical TypeScript code with accurate examples
- Prefer iteration and modularization over code duplication
- Structure repository files as follows:

```
├── PLAN.md                   # Scratch file for planning and executing an unit of work
├── README.md                 # Project README
├── FEATURES.md               # Contains a list of features supported by the project
├── TODO.md                   # TODO List file
├── ai-docs/                  # Documentation and examples for you to refer to
├── app/
│   ├── (auth)/               # Auth UI and API
│   └── (chat)/               # Chat UI and API
├── components/               # Shared UI components specific to bragdoc.ai 
│   └── ui/                   # ShadCN UI components like labels, inputs, buttons, etc.
├── evals/                    # Braintrust Evals for the various LLM calls
│   ├── context-brag/         # Complex use cases pull many brags out of many messages
│   ├── conversation-gen/     # Generates plausible conversation histories for other evals
│   └── single-brag/          # Single Brag Evaluation
├── hooks/                    # Shared React hooks
├── lib/                      # Core library code
│   ├── ai/                   # AI/LLM function implementations
│   ├── db/                   # Database schema and queries
│   └── editor/               # Editor code
├── research/                 # Research and documentation about the project, the market, etc
├── features/                 # Documents that describe features to implement
├── public/
│   ├── fonts/                # Static font assets
│   └── images/               # Static image assets
└── test/                     # Test cases
```

## URL Structure
- The project has a single base URL: `https://bragdoc.ai`, when deployed into production
- /register - register a new user
- /login - login a user
- /chat - main view for logged-in users, shows the chatbot and chat history
- / - home page, mostly marketing. Prominent CTA to logged-in users to go to /chat

## Tech Stack

These are the core technologies and libraries used in the project. 
Please ask before using anything not in the following list of libraries and technologies:

### Core
- TypeScript
- React
- Next.js
- Node.js

### UI & Styling
- Tailwind CSS
- Radix UI (Component Library)
- Shadcn UI (UI Component System)
- Framer Motion (Animations)
- Sonner (Toast Notifications)
- Geist (Typography)
- ProseMirror (Rich Text Editor Framework)

### Data & Backend
- PostgreSQL
- Drizzle ORM (Database ORM)
- Zod (Schema Validation)
- SWR (Data Fetching)

### AI & Auth
- Vercel AI SDK
- NextAuth.js
- Braintrust (LLM Evaluation Framework)

### Development Tools
- pnpm (Package Management)
- Biome (Linting and Formatting)
- Changesets (Version Management)

## Naming Conventions
- use lowercase with dashes for directories (e.g. `components/form-wizard`)
- Favor named exports for components and utilities
- use PascalCase for component files (e.g. VisaForm.tsx)
- use camelCase for utility files (e.g. generateText.ts)

## TypeScript Usage
- Use TypeScript for all code; prefer interfaces over types
- Avoid using React.FC
- Use import and export instead of require
- Use `tsx` for running TypeScript files directly
- Example: `pnpm tsx path/to/file.ts`
- Maintain proper type definitions in `types.ts` files

## UI and Styling
- Use Tailwind CSS for styling
- Use Shadcn UI and Radix UI for UI components
- Use `npx shadcn@latest add <component-name>` to add a new shadcn component
- When adding new shadcn component, document the installation command
- The project supports dark mode, and must continue to do so

## Error Handling
- Implement proper error boundaries in React components

## Security
- Sanitize user inputs
- Handle any sensitive data properly

## Testing
- Use Jest for unit testing
- Use @types/jest for TypeScript support
- Use ts-jest for TypeScript integration
- Use @testing-library/jest-dom for DOM testing utilities
- @swc/jest for faster test execution
- Braintrust Evals should be created each time we add an LLM call. See the `eval.ts` files in the `evals` directory for examples

## Git Usage
Commit Message Prefixes:
- "fix:" for bug fixes
- "feat: " for new features
- "docs: " for documentation changes
- "refactor: " for code refactoring
- "test: " for adding or updating tests
- "chore: " for changes that don't modify src or test files
- "perf: " for performance improvements
- "style: " for changes that do not affect the meaning of the code

Rules:
- Keep the summary line concise
- Include description for non-obvious changes
- Reference issue numbers when applicable

## Documentation
- Maintain a clear README.md file that outlines the project's purpose, features, and usage.
- Include comments for complex logic
- Ensure each file has a clear purpose and is well-documented.

## Development Workflow
- When starting a new task, first create a detailed plan and save it in the PLAN.md file.
- Each time you complete a task, update the PLAN.md file and add the task to the TODAY.md file.
- Use git for version control to track changes and manage codebase.
- Follow semantic versioning for releases
- Use `pnpm changeset` to create changelogs (this is the @changesets/cli plugin for pnpm)
- Implement proper code review process
- Test in multiple environments
- Keep the TODO.md file up to date
- Write any scripts in TypeScript
- Keep an up to date LOG.md file in the features/some-feature directory. Each time you do something related to that feature, write a log entry in the LOG.md file.

## Windsurf Specific
- Automatically suggest additions to the .windsurfrules file where best practices are discussed or updated during the generation process, if the content does not exist in the file already.

## When writing functional specifications

- Save the file in the `features/` directory, inside a subdirectory named after the feature
- Call the file requirements.md in that directory
- Provide a status enum for the feature - "not started", "in progress", "complete"
- Provide a high-level description of the feature
- Provide an in-depth description of the implementation
- If the feature is already partly implemented, provide a description of what already exists
- If this feature should build off existing code, provide a description of that here
- Consider what already exists in the app, and what you were asked to create
- Do no add any time estimates
- Write a detailed technical specification for the feature
- Write a list of all files in the repo that are expected to be affected by the feature
- If the feature has a backend component, produce specifications for any API routes added
- Identify areas where errors may occur, and how they should be handled
- If new node modules are needed, provide a list of them
- If the feature requires any new UI components, provide a list of them
- Do not mention analytics-related tasks
- Write a section about security considerations, if there are any
- Write a section about performance considerations, if there are any
- Write a section about accessibility considerations, if there are any
- Write a section about testing considerations, if there are any

## When writing plans

- Do not add time estimates
- Write a detailed plan for the feature, including tasks and dependencies
- Put tasks into a logical order
- describe, expect, test, beforeAll, afterAll, beforeEach and so on are available globally - do not import them

## When writing logs

- Keep the LOG.md file up to date in the features/some-feature directory.
- Each time you do some work related to that feature, write a log entry in the LOG.md file.
- Document decisions taken as well as actions taken - for example if we decided to defer UI testing to a later date, leave as much context as necessary in the LOG.md file so that you can pick up where you left off later

## Scripts

### Visual Testing and Screenshots
- Use the screenshot utility in [scripts/capture-page-screenshots.ts](cci:7://file:///Users/ed/Code/brag-ai/scripts/capture-page-screenshots.ts:0:0-0:0) to capture and compare light/dark mode versions of pages
- Run with: `pnpm tsx scripts/capture-page-screenshots.ts [url]`
- Screenshots are saved to `temp/[page-name]-light.png` and `temp/[page-name]-dark.png`
- Use this utility when making significant UI changes, especially those affecting dark mode support
- Compare screenshots before and after changes to ensure visual consistency