TeamForge/.claude/skills/run-teamforge/SKILL.md

name, description

name	description
run-teamforge	Build, run, and drive TeamForge. Use when asked to start TeamForge, run its tests, take a screenshot of its UI, verify a feature works, or interact with the running app.

TeamForge is a Django 6 club-management web app (members + teams). Drive it via .claude/skills/run-teamforge/driver.mjs under Playwright. The driver starts the dev server, creates a test superuser, logs in via /admin/login/, and screenshots any page.

All paths below are relative to the repo root (/Users/bernard/Code/PycharmProjects/TeamForge/).

Prerequisites

Python (≥3.12) and uv must be present. Node.js (≥18) is required for the Playwright driver.

uv sync                  # install Python deps
npm install playwright   # install Playwright (one-time, at repo root)
npx playwright install chromium   # download Chromium browser (one-time, ~90 MB)

The app connects to a PostgreSQL database. Connection is in .env:

DJANGO_DATABASE_URL=postgres://...
DJANGO_DEBUG=True

If the database isn't reachable, the server still boots but all page requests fail with 500. The .env file must exist; there is no fallback to SQLite in production mode.

Setup

uv sync
uv run python manage.py migrate   # apply migrations (idempotent)

Run (agent path)

The driver handles everything — server startup, test-user creation, login, and screenshots.

# Smoke test: starts server, screenshots members + configuration pages
node .claude/skills/run-teamforge/driver.mjs smoke

# Screenshot any page (path or full URL)
node .claude/skills/run-teamforge/driver.mjs screenshot /backend/members/
node .claude/skills/run-teamforge/driver.mjs screenshot /backend/configuration

# Stop the background server
node .claude/skills/run-teamforge/driver.mjs stop

Screenshots land in /tmp/teamforge-shots/<name>.png. Server log → /tmp/teamforge-server.log.

Auth is via a local skilltest superuser (password: skilltest123!) which the driver creates automatically on first run. The driver logs in through /admin/login/ — the app does not register django.contrib.auth URLs, so /accounts/login/ returns 404.

Run (human path)

uv run python manage.py runserver         # → http://localhost:8000
python manage.py tailwind start           # separate terminal — required for CSS

Log in at /admin/login/ or create a superuser with uv run python manage.py createsuperuser.

Test

uv run python manage.py test   # → 43 tests, all pass

---

Gotchas

• /accounts/login/ returns 404 — the URL conf (TeamForge/urls.py) only has backend/ and admin/. The @login_required decorator redirects there by default, but django.contrib.auth.urls is not included. Always log in via /admin/login/. The session cookie then works for all /backend/ views.

• avatar templatetag crashes on empty names — theme/templatetags/avatar.py:41 does first_name[0] which raises IndexError: string index out of range when either name field is blank. Every Django User used as a logged-in session must have first_name and last_name set. The driver sets them on the test user automatically.

• /backend/ dashboard is a placeholder — templates/backend/index.html contains only "TEST FILE". This is expected during development; the real UI lives at /backend/members/ and /backend/configuration.

• Tailwind CSS not served in dev — running manage.py runserver without manage.py tailwind start in a second terminal means pages render with no styles. The Playwright driver screenshots may look unstyled when Tailwind isn't running. For visual verification, start tailwind start first (or accept the unstyled capture).

• PostgreSQL required — DJANGO_DATABASE_URL in .env points to a remote PostgreSQL instance at 192.168.1.100. If that host isn't reachable, every request returns 500. There is no in-repo SQLite fallback for normal runs; the test suite creates a separate test DB automatically.

• npm install playwright must run at repo root — the driver imports playwright via Node's resolution from node_modules/ at the repo root. Running it from another directory will cause ERR_MODULE_NOT_FOUND.

Troubleshooting

• Cannot find package 'playwright': run npm install playwright at the repo root, then retry.
• Server did not start within 20s: check /tmp/teamforge-server.log. Most common cause: PostgreSQL unreachable (connection refused or timeout).
• 500 on every page after login: the logged-in user has no first_name/last_name — the avatar templatetag crashes on the base template. Fix: set names on the user via uv run python manage.py shell -c "from django.contrib.auth.models import User; u=User.objects.get(username='skilltest'); u.first_name='Skill'; u.last_name='Test'; u.save()".
• page.waitForURL timeout on login: admin login redirect failed — wrong password or user doesn't exist. The driver's ensureTestUser() recreates the user each run; if it fails, check that manage.py shell works at all.