Genonaut Development Assistant

This skill provides comprehensive guidance for working with Genonaut, a recommender systems project for perpetual generative AI content creation (text, image, video, audio).

What This Skill Does

Provides AI agents with complete context and procedures for:

Environment setup and virtual environment management

Three-tier testing strategy (unit, database, API integration)

Database migrations with Alembic

Frontend development with Vite and Playwright E2E testing

Service management (API, Redis, Celery, PostgreSQL, ComfyUI)

Code style and architectural patterns

Documentation practices

Instructions for AI Agent

1. Initial Setup

**CRITICAL FIRST STEP**: Always activate the virtual environment before any Python work:

```bash

source env/python_venv/bin/activate

```

2. Familiarize with Project

Read documentation in this order:

1. `README.md` - Project overview

2. `docs/developer.md` - Developer guide

3. `docs/testing.md` - Testing practices

4. `docs/api.md` - API documentation

5. `docs/db.md` - Database details

6. `frontend/AGENTS.md` - Frontend-specific guidance

3. Directory Structure

`config/` - JSON configuration sets for environment-specific settings

`docs/` - Project documentation

`env/` - Environment assets (dotenv files, Python venv, Redis configs)

`frontend/` - Vite-powered frontend application

`genonaut/` - Core backend source (FastAPI, models, business logic)

`infra/` - Infrastructure and deployment tooling

`notes/` - Working documentation and task tracking (markdown files)

`test/` - Additional testing resources

4. Essential Commands

**Database:**

```bash

make init-demo # Initialize demo database

make api-demo # Start API server (demo DB)

make migrate-demo # Generate and apply DB migration

make api-test-wt2-restart # Restart API server (test DB, worktree 2)

```

**Testing:**

```bash

make test-unit # Unit tests (backend, <10s)

make test-db # Database tests (30-60s)

make test-api # API integration tests (2-5min)

make test-all # All backend tests

make frontend-test # All frontend tests

make frontend-test-unit # Frontend unit tests only

make frontend-test-e2e # Frontend E2E tests (excludes @performance)

```

**Services:**

```bash

make celery-dev # Start Celery worker

make frontend-dev # Start frontend dev server (port 5173)

make beat-status # Check Celery Beat schedule

make redis-flush-dev # Clear Redis data

```

5. Standard Operating Procedures for Any Task/Feature

Follow these steps for every feature or major task:

**a) Notes and Task Tracking:**

Create/update `.md` file in `notes/` for major tasks

Use checkboxes (`- [ ]`) not bullets (`-`) for todos

Check off completed items (`- [x]`)

Consult `notes/general-todos.md` for uncategorized todos

Move relevant todos to your working document

**b) Testing (Three-Tier Approach):**

1. **Unit tests** (`make test-unit`) - No dependencies, fastest

2. **Database tests** (`make test-db`) - Requires DB, medium speed

3. **API integration tests** (`make test-api`) - Requires API + DB, slowest

For database/API tests, initialize test DB first: `make init-test` and start test server: `make api-test`

**Frontend Testing:**

Unit: `make frontend-test-unit`

E2E: `make frontend-test-e2e` (requires backend API running)

E2E performance: `make frontend-test-e2e-performance`

All: `make frontend-test`

**CRITICAL - E2E Database Configuration:**

Always verify which database the API is connected to before debugging E2E test failures:

```bash

Check current database connection

curl http://localhost:8001/api/v1/health | python -m json.tool

For E2E testing: use test database

make api-test

For development: use demo database

make api-demo

```

**c) Frontend Changes - data-testid Attributes:**

Add/update stable `data-testid` attributes on:

New layouts and sections

List items

Loading/empty states

Interactive controls

Follow conventions in `frontend/AGENTS.md#data-test-ids` (e.g., `page-or-component-element` naming, MUI `inputProps`/`slotProps`).

**d) Browser Verification with MCP Playwright:**

**CRITICAL**: After UI/frontend changes, verify functionality using MCP Playwright tools. Do NOT rely on manual user testing.

Available tools:

`mcp__playwright__browser_navigate` - Navigate to http://localhost:5173

`mcp__playwright__browser_snapshot` - Capture accessibility snapshot (preferred for verification)

`mcp__playwright__browser_console_messages` - Check for errors/warnings

`mcp__playwright__browser_click` - Test interactions

`mcp__playwright__browser_type` - Fill forms

`mcp__playwright__browser_network_requests` - Monitor API calls

**Verification workflow:**

1. Make frontend changes

2. Start dev server: `make frontend-dev`

3. Navigate to http://localhost:5173

4. Use snapshot to see page structure

5. Check console for errors

6. Test interactions with click/type tools

7. Fix issues and re-verify

**e) Documentation:**

Add module/class/function/method docstrings

Include parameters and returns in function docstrings

Add periodic code comments for multi-step blocks

Update `README.md` if adding CLI features or major functionality

Create detailed docs in `docs/` directory when appropriate

**f) Dependencies:**

Add new Python packages (unversioned) to `requirements-unlocked.txt`

**g) Final Verification:**

Ensure full test suite passes: `make test-all` and `make frontend-test`

Run commands if no tests exist (unless inadvisable)

6. Code and Architecture Style

Prefer **pure functions** whenever possible

Use **types** for all function/method parameters

Follow immutability principles

7. Database Migrations (Alembic)

**CRITICAL**: DO NOT edit existing version files in `genonaut/db/migrations/versions/`. Treat as immutable history.

**Migration procedure:**

1. Modify SQLAlchemy models (no raw SQL)

2. Generate migration: `make migrate-demo`

3. Verify single head: `alembic heads` (should show one revision)

4. Apply to all environments: `make migrate-demo`, `make migrate-dev`, `make migrate-test`

5. Test suite must pass after upgrades

**Important notes:**

Forward-only in production; rollbacks for local/dev only

Non-null columns: add with `server_default`, backfill, then remove default

Large table indexes: use `postgresql_concurrently=True` with `autocommit_block()`

See `docs/db-migrations.md` for detailed procedures

8. Database Environments

Three local databases:

**demo** - Canonical for local development (recommended)

**dev** - Alternative development database

**test** - Isolated for automated testing (resets frequently)

API server runs on port 8001 with demo database by default.

9. Configuration System

Two-tier configuration (lowest to highest priority):

1. `config/base.json` - Base config

2. `config/{ENV_TARGET}.json` - Environment-specific (e.g., `local-demo`)

3. `env/.env.shared` - Shared secrets

4. `env/.env.{ENV_TARGET}` - Environment secrets

5. Process environment variables

6. `env/.env` - Local overrides (gitignored)

Frontend config: `frontend/src/config/`

See `docs/configuration.md` for details.

10. Service Management

**Starting services:**

Use appropriate commands: `make start-db`, `npm run dev`, etc.

**Restarting services:**

**For API servers - ALWAYS use environment-specific commands:**

```bash

make api-demo-stop / make api-demo-restart # Demo database

make api-test-stop / make api-test-restart # Test database (worktree 1)

make api-test-wt2-stop / make api-test-wt2-restart # Worktree 2 test

make api-dev-stop / make api-dev-restart # Development database

```

**Why not use generic pkill:**

Pattern-matches exact `--env-target` flag

Prevents killing API servers in other worktrees

Includes proper cleanup with 3-second wait

**For other services:**

Use `pkill -f <process_name>` or `killall <service>`

See `docs/infra.md#api-server-management-stop-and-restart-commands` for complete list.

11. Required Running Services

During development, keep these running:

PostgreSQL

Web API (port 8001)

Redis (port 6379)

Celery queue worker

ComfyUI or ComfyUI Mock (port 8189)

Frontend (port 5173)

12. Performance Test Marking

**Backend (pytest):**

Use `@pytest.mark.performance` decorator

**Frontend Playwright E2E:**

Add `@performance` tag to test names:

```typescript

test('my test @performance', async ({ page }) => { ... })

```

Run separately: `make frontend-test-e2e-performance`

Example Usage

Scenario 1: Adding a new feature

1. Activate venv: `source env/python_venv/bin/activate`

2. Create task doc in `notes/new-feature.md` with checkboxes

3. Modify SQLAlchemy models if needed

4. Generate migration: `make migrate-demo`

5. Write unit tests, then database tests, then API tests

6. Add frontend data-testids if UI changes involved

7. Verify in browser with MCP Playwright tools

8. Add docstrings and code comments

9. Update `README.md` if needed

10. Run full test suite: `make test-all && make frontend-test`

11. Check off todos in `notes/new-feature.md`

Scenario 2: Debugging E2E test failure

1. Check which database API is connected to: `curl http://localhost:8001/api/v1/health | python -m json.tool`

2. If wrong database, restart with correct env: `make api-test-stop && make api-test`

3. Re-run E2E tests: `make frontend-test-e2e-debug`

4. Use MCP Playwright tools to manually verify behavior in browser

5. Fix issues and verify tests pass

Scenario 3: Schema change

1. Modify SQLAlchemy models (no raw SQL)

2. `make migrate-demo` to generate and apply migration

3. Apply to other environments: `make migrate-dev && make migrate-test`

4. Run full test suite to verify: `make test-all`

5. Check migration file into git

Constraints

NEVER edit existing Alembic version files

ALWAYS activate virtual environment before Python work

ALWAYS verify frontend changes with MCP Playwright tools before completion

ALWAYS use environment-specific API server stop/restart commands

ALWAYS check database connection before debugging E2E test failures

ALWAYS use checkboxes for todos, not bullets

ALWAYS run full test suite before marking features complete

Genonaut Development Assistant

Genonaut Development Assistant

What This Skill Does

Instructions for AI Agent

1. Initial Setup

2. Familiarize with Project

3. Directory Structure

4. Essential Commands

5. Standard Operating Procedures for Any Task/Feature

Check current database connection

For E2E testing: use test database

For development: use demo database

6. Code and Architecture Style

7. Database Migrations (Alembic)

8. Database Environments

9. Configuration System

10. Service Management

11. Required Running Services

12. Performance Test Marking

Example Usage

Scenario 1: Adding a new feature

Scenario 2: Debugging E2E test failure

Scenario 3: Schema change

Constraints

Reviews (0)