Guidelines for AI agents working on burntop.dev - gamified AI usage tracking platform with FastAPI backend, TanStack Start frontend, and Bun CLI
Comprehensive guidelines for AI coding agents working on burntop.dev - a gamified AI usage tracking platform for developers.
Monorepo structure:
Always use the bd system for task management:
```bash
bd onboard # Get started with the project
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --status in_progress # Claim work
bd close <id> # Complete work
bd sync # Sync with git
```
```bash
cd packages/backend
uv run uvicorn src.app.main:app --reload # Dev server
uv run ruff check src/ # Lint
uv run ruff format src/ # Format
uv run pytest tests/unit/test_file.py # Single file test
uv run alembic upgrade head # Run migrations
uv run alembic revision --autogenerate -m "description" # Create migration
```
```bash
cd packages/frontend
npx vitest run path/to/file.test.ts # Single file test
bun run generate:api # Regenerate API client after backend changes
```
```bash
docker compose -f docker-compose.db.yml up -d # Start PostgreSQL
cd packages/backend && uv run alembic upgrade head
docker compose -f docker-compose.db.yml down # Stop
```
Connection string: `postgresql://burntop:burntop_dev_password@localhost:5433/burntop`
1. **Strict typing**: No `any`, no `@ts-ignore` without justification
2. **Explicit return types** on all exported functions
3. **Prefer `interface` for objects**, `type` for unions
4. **Use `import type`** for type-only imports
5. **React 19 patterns**: Hooks and functional components only
6. **No `console.log`** in production code
```typescript
// 1. React/framework
import { createFileRoute } from '@tanstack/react-router';
// 2. Third-party libraries
import { z } from 'zod';
// 3. Internal (@/)
import { db } from '@/lib/db';
// 4. Relative imports
import { StatsCard } from './stats-card';
// 5. Type imports
import type { User } from '@/types';
```
1. **Python 3.12+** with type hints required
2. **Async SQLAlchemy 2.0** with `Mapped[]` type annotations
3. **Use `Decimal`** for financial calculations
4. **Use `datetime.UTC`** instead of deprecated `timezone.utc`
5. **3-layer architecture**: Router → Service → Repository (never skip layers)
```
packages/backend/src/app/{entity}/
├── models.py # SQLAlchemy ORM models
├── schemas.py # Pydantic schemas (validation)
├── repository.py # Data access layer
├── service.py # Business logic
├── router.py # FastAPI endpoints
└── dependencies.py # Dependency injection
```
1. **Frontend is client-side only** - All database operations MUST go through FastAPI backend
2. **Route files MUST NOT import `@/lib/db` directly** - Use server functions instead
3. **CLI requires Bun runtime** - Uses `bun:sqlite` for local database
4. **Dark mode only** - Base: `--bg-base: #0A0A0A`, Accent: `--ember-500: #FF6B00`
5. **No production console.log statements**
6. **Regenerate API client after backend changes**: `cd packages/frontend && bun run generate:api`
```typescript
import { cn } from '@/lib/utils';
import { Card } from '@/components/ui/card';
export function StatsCard({ className }: { className?: string }) {
return (
<Card className={cn('bg-bg-elevated border-border-default', className)} />
);
}
```
```typescript
import { useGetUserProfileApiV1UsersUsernameGet } from '@/api/users';
const { data, isLoading } = useGetUserProfileApiV1UsersUsernameGet({
username: 'johndoe'
});
```
Delegate styling, layout, and animations to the `frontend-ui-ux-engineer` agent for best results.
**MANDATORY workflow before ending any work session:**
1. **File issues for remaining work** - Create bd issues for any follow-up tasks
2. **Run quality gates** (if code changed):
- Run relevant tests
- Fix linting errors
- Verify builds pass
3. **Update issue status**:
- Close finished work with `bd close <id>`
- Update in-progress items
4. **PUSH TO REMOTE** (MANDATORY):
```bash
git pull --rebase
bd sync
git push
git status # MUST show "up to date with origin"
```
5. **Clean up** - Clear stashes, prune remote branches
6. **Verify** - Confirm all changes are committed AND pushed
7. **Hand off** - Provide context for next session
**CRITICAL**: Work is NOT complete until `git push` succeeds. NEVER stop before pushing - that leaves work stranded locally. If push fails, resolve conflicts and retry until it succeeds.
```bash
cd packages/frontend && npx vitest run path/to/file.test.ts
cd packages/backend && uv run pytest tests/unit/test_file.py
```
Run single file tests during development for fast feedback. Run full test suites before pushing.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/burntop-dev-guide/raw