# Skills

Reusable project templates and specialized development guides for OpenCode.

## Available Skills

### backend-dev

Go backend service template using hexagonal (ports & adapters) architecture with Keycloak OIDC integration.

**Features:**
- Clean architecture with hexagonal pattern
- JWT authentication via Keycloak (keyfunc/v3)
- PostgreSQL/pgx with connection pooling
- Prometheus metrics and OpenTelemetry tracing
- PostgreSQL-based caching layer

**Quick start:**
```bash
# Clone the template
# Configure environment variables
cp .env.example .env

# Run migrations
make migrate

# Start server
make run
```

**Key env vars:**
```env
KEYCLOAK_JWKS_URL=https://auth.pharos.id/realms/production/protocol/openid-connect/certs
KEYCLOAK_CLIENT_ID=exodus
PERSISTENCE_DSN=postgres://user:pass@localhost:5432/dbname?sslmode=disable
```

See [backend-dev/SKILL.md](backend-dev/SKILL.md) for full documentation.

### internal-dashboard-frontend

Internal dashboard frontend template using Next.js 16, Mantine 9.4, and Better Auth 1.6+ as a Keycloak OIDC client. Pairs with `backend-dev` — forwards Keycloak access tokens to the Go API, which validates them via JWKS.

**Features:**
- App Router with server-first components and route group boundaries
- Mantine 9.4 UI (AppShell, theme, Notifications, ModalsProvider)
- Better Auth + Keycloak OIDC with PKCE and Postgres-backed sessions
- axios layer with auth interceptor and `ApiError` normalization
- TanStack Query + TanStack Table + Recharts
- Mantine `useForm` + Zod with shared schemas between API and forms
- Vitest + Testing Library + Playwright + MSW
- Feature-sliced layout (`src/features/<x>/{api,components,hooks,schemas,types}`)

**Quick start:**
```bash
bun create next-app dashboard-fe --typescript --app --src-dir
cd dashboard-fe
bun add @mantine/core@^9.4 @mantine/hooks@^9.4 @mantine/form@^9.4 \
  @mantine/notifications@^9.4 @mantine/modals@^9.4 @mantine/dates@^9.4 \
  better-auth@^1.6 axios zod @tanstack/react-query @tanstack/react-table recharts
cp .env.example .env.local
bun run dev
```

**Key env vars:**
```env
NEXT_PUBLIC_API_BASE_URL=http://localhost:8080
BETTER_AUTH_SECRET=<32-byte-random>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=postgres://user:pass@localhost:5432/dashboard_auth?sslmode=disable
KEYCLOAK_ISSUER=https://auth.example.com/realms/production
KEYCLOAK_CLIENT_ID=dashboard-fe
KEYCLOAK_CLIENT_SECRET=<realm-client-secret>
```

See [internal-dashboard-frontend/SKILL.md](internal-dashboard-frontend/SKILL.md) for full documentation.

### orchestrator

End-to-end software development orchestration by delegating to specialized subagents (`frontend-dev`, `backend-dev`, `devops`, `qa`, `infra`, `reviewer`). Enforces the `understand → plan → validate → delegate → review → integrate → commit → deliver` pipeline and a max-3-round review escalation rule.

**Features:**
- Delegation prompt template with Context / Tasks / Scope / Success Criteria / Constraints
- Per-task test requirement (≥80% coverage)
- Reviewer subagent gate before commit
- Rollback and escalation rules

See [orchestrator/SKILL.md](orchestrator/SKILL.md) for full documentation.

## Adding a New Skill

1. Create skill directory: `mkdir new-skill/`
2. Add `SKILL.md` with comprehensive documentation
3. Add entry to AGENTS.md
4. Add section to this README

## Documentation Conventions

- Code examples with file paths and line numbers
- Working examples (not pseudocode)
- Environment variable documentation
- Database schema migrations
- Error handling patterns