Agent Guidelines - Spotify Playlist Extractor

Commands

Frontend dev:

cd frontend && pnpm run dev

| build:

pnpm run build

| lint:

pnpm run lint

Backend dev:

cd backend && ./start.sh

uvicorn main:app --reload

Test backend:

cd backend && pytest

| single test:

pytest tests/test_auth.py::test_login_redirect

Test frontend: No pnpmscript configured. Run tests with
```
npx vitest
```
if needed.

Code Style

TypeScript/React

Imports: (1) React, (2) third-party libs, (3) router, (4) local API/utils, (5) components, (6) context
Types: Always use explicit interfaces for props/state. Union types for nullables (
```
string | null
```
). Avoid
```
any
```
except for untyped external data.
Naming: PascalCase components/interfaces, camelCase functions/vars, UPPER_SNAKE_CASE constants
Components: Presentational use props, containers use hooks/context. State → handlers → JSX.
Error handling:
```
try-catch
```
with
```
err: any
```
, optional chaining (
```
?.
```
), user-facing alerts
The project uses Tailwind v4 for styling. DO NOT USE ANY v3 RELATED styling!
Seldom use inline styles. Prefer Tailwind classes.

Python/FastAPI

Imports: (1) stdlib, (2) FastAPI/third-party, (3) local relative imports
Types: Use type hints on all functions.
```
Optional[T]
```
for nullables,
```
List[Dict[str, Any]]
```
for complex structures.
Naming: snake_case functions/vars, UPPER_SNAKE_CASE constants,
```
_prefix
```
for private
Error handling:
```
HTTPException
```
for API errors, print statements for debugging, early returns for validation
Endpoints: Docstring → parse body → validate → retrieve session → business logic → JSONResponse

Standards

Max 20 lines per method (logic). Separate concerns. No speculative abstractions.
Test with accessibility queries (
```
getByRole
```
,
```
getByLabelText
```
). Mock external dependencies.
Use
```
async
```
/
```
await
```
consistently. FastAPI endpoints always
```
async def
```
.

Agents & rules:

For bug reports, invoke
```
@bug-hunter
```
to investigate and fix bugs by finding root causes, not just symptoms. The bug hunter will trace the issue, identify the underlying problem, and implement a proper fix.
Start each feature by invoking
```
@architect
```
to plan the implementation: identify files to change, steps to take, and potential issues.
After making major code changes, automatically invoke
```
@code-reviewer
```
to review modified changes for quality, correctness, security, and best practices.
After code review passes, automatically invoke
```
@quality-assurance
```
to run tests (
```
pnpm test
```
), lint (
```
pnpm run lint
```
), and build (
```
pnpm build
```
) — all must pass before the task is complete.
Never skip QA — always run quality-assurance after code changes, even for small changes.
If you need to search the codebase for patterns or understand architecture, use
```
@explore
```
for fast file/code searches.
For creating OpenCode skills, invoke
```
@skill-contributor
```
to create skills or identify skill opportunities using
```
@explore
```
.
Never document something if not explicitly asked — only provide documentation when requested.

Commands

Frontend dev:

cd frontend && pnpm run dev

| build:

pnpm run build

| lint:

pnpm run lint

Backend dev:

cd backend && ./start.sh

uvicorn main:app --reload

Test backend:

cd backend && pytest

| single test:

pytest tests/test_auth.py::test_login_redirect

Test frontend: No pnpmscript configured. Run tests with

npx vitest

if needed.

Code Style

Imports: (1) React, (2) third-party libs, (3) router, (4) local API/utils, (5) components, (6) context

Types: Always use explicit interfaces for props/state. Union types for nullables (

string | null

). Avoid

any

except for untyped external data.

Naming: PascalCase components/interfaces, camelCase functions/vars, UPPER_SNAKE_CASE constants

Components: Presentational use props, containers use hooks/context. State → handlers → JSX.

Error handling:

try-catch

with

err: any

, optional chaining (

?.

), user-facing alerts

The project uses Tailwind v4 for styling. DO NOT USE ANY v3 RELATED styling!

Seldom use inline styles. Prefer Tailwind classes.

Imports: (1) stdlib, (2) FastAPI/third-party, (3) local relative imports

Types: Use type hints on all functions.

Optional[T]

for nullables,

List[Dict[str, Any]]

for complex structures.

Naming: snake_case functions/vars, UPPER_SNAKE_CASE constants,

_prefix

for private

Error handling:

HTTPException

for API errors, print statements for debugging, early returns for validation

Endpoints: Docstring → parse body → validate → retrieve session → business logic → JSONResponse

Standards

Max 20 lines per method (logic). Separate concerns. No speculative abstractions.

Test with accessibility queries (

getByRole

getByLabelText

). Mock external dependencies.

Use

async

await

consistently. FastAPI endpoints always

async def

Agents & rules:

For bug reports, invoke

@bug-hunter

to investigate and fix bugs by finding root causes, not just symptoms. The bug hunter will trace the issue, identify the underlying problem, and implement a proper fix.

Start each feature by invoking

@architect

to plan the implementation: identify files to change, steps to take, and potential issues.

After making major code changes, automatically invoke

@code-reviewer

to review modified changes for quality, correctness, security, and best practices.

After code review passes, automatically invoke

@quality-assurance

to run tests (

pnpm test

), lint (

pnpm run lint

), and build (

pnpm build

) — all must pass before the task is complete.

Never skip QA — always run quality-assurance after code changes, even for small changes.

If you need to search the codebase for patterns or understand architecture, use

@explore

for fast file/code searches.

For creating OpenCode skills, invoke

@skill-contributor

to create skills or identify skill opportunities using

@explore

Never document something if not explicitly asked — only provide documentation when requested.

Agent Guidelines - Spotify Playlist Extractor

Agent Guidelines - Spotify Playlist Extractor

Commands

Code Style

TypeScript/React

Python/FastAPI

Standards

Related Skills

Markdown Converter

Nano Banana Pro

1password

Agent Guidelines - Spotify Playlist Extractor

Commands

Code Style

TypeScript/React

Python/FastAPI

Standards