# Skills Repository

OpenCode skill collection for reusable project templates and specialized development guides.

## Structure

- Each subdirectory = one skill domain
- `SKILL.md` in each directory contains comprehensive usage instructions

## Adding New Skills

1. Create directory: `mkdir new-skill/`
2. Add `SKILL.md` with comprehensive documentation

## Current Skills

| Directory | Description |
|-----------|-------------|
| `backend-dev/` | Go hexagonal architecture template with Keycloak JWT auth |
| `internal-dashboard-frontend/` | Next.js 16 + Mantine 9.4 + Better Auth dashboard template |
| `orchestrator/` | End-to-end development orchestration |

---

# backend-dev Skill

Go backend service template using hexagonal (ports & adapters) architecture.

## Tech Stack
- Gin web framework
- PostgreSQL/pgx
- Prometheus metrics
- OpenTelemetry tracing
- Keycloak JWT authentication (keyfunc/v3)
- OpenBao v2 for secrets management

## Key Environment Variables
```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
```

## Keycloak JWT Claims Mapping
| JWT Claim | Field |
|-----------|-------|
| `nip` | Primary key (VARCHAR(20)) |
| `name` | Full name |
| `email` | Email (non-unique) |
| `resource_access.{client_id}.roles` | Authorization roles |

## Authentication Flow
1. Backend acts as OAuth2 Resource Server (validates Bearer tokens)
2. JWT validated locally via Keycloak JWKS (no client secret)
3. User auto-created/updated on each authentication
4. Roles extracted from `resource_access.{client_id}.roles`

## Documentation

Main entry: [backend-dev/SKILL.md](backend-dev/SKILL.md)

Detailed references:
- [ARCHITECTURE.md](backend-dev/references/ARCHITECTURE.md) - Hexagonal patterns, DDD, provider
- [12-FACTOR.md](backend-dev/references/12-FACTOR.md) - All 12 factors with Go examples
- [CONFIGURATION.md](backend-dev/references/CONFIGURATION.md) - OpenBao, env, provider wiring
- [AUTHENTICATION.md](backend-dev/references/AUTHENTICATION.md) - Keycloak JWT integration
- [DATABASE.md](backend-dev/references/DATABASE.md) - PostgreSQL schema, migrations
- [DEPLOYMENT.md](backend-dev/references/DEPLOYMENT.md) - Docker, CI/CD, admin CLI
- [CODING-STANDARDS.md](backend-dev/references/CODING-STANDARDS.md) - REST, SOLID, error handling

## Design Principles

- **SOLID**: SRP (one usecase per operation), DIP (depend on ports)
- **Hexagonal Architecture**: Domain → Ports → Adapters
- **12-Factor Compliance**: All factors implemented
- **NEVER Skip Error Checking**: Always handle or return errors
- **NEVER Use Panic**: Return errors to parent

## Database
- `users` table with `nip` as primary key
- `cache.entries` unlogged table for caching

---

# orchestrator Skill

End-to-end software development orchestration by delegating to specialized subagents.

## Execution Pattern
```
understand → plan → validate → delegate → review → integrate → commit → deliver
```

## Subagent Types
| Type | Use For |
|------|---------|
| `frontend-dev` | React/Vue/UI implementation |
| `backend-dev` | API, business logic, services |
| `devops` | CI/CD, deployment, containers |
| `qa` | Test strategy, automation |
| `infra` | Cloud, architecture, networking |
| `reviewer` | Code review, specification validation |

## Critical Rules
1. Every code task gets a test
2. Every completed task gets reviewed before commit
3. Never commit failing tests
4. Escalate after 3 review rounds
5. Commit only after completion

## Blocked Handling
```
Stuck on issue → Spawn investigative subagent → Still stuck → Escalate to user
```

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

---

# internal-dashboard-frontend Skill

Internal dashboard frontend template using Next.js 16, Mantine 9.4, and Better Auth 1.6+ as a Keycloak OIDC client.

## Tech Stack
- Next.js 16+ (App Router, RSC)
- Mantine 9.4+ (UI, theme, notifications, modals, forms)
- Better Auth 1.6+ with genericOAuth plugin → Keycloak
- axios (auth interceptor + TanStack Query integration)
- Zod (shared schemas between API and forms)
- TanStack Table v8, Recharts
- Vitest + Testing Library + Playwright
- bun package manager

## Key Environment Variables
```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>
```

## Authentication Flow
1. User clicks "Continue with Keycloak" on `/login`
2. Better Auth redirects to Keycloak via OIDC (PKCE)
3. Keycloak issues code → Better Auth exchanges for tokens
4. Better Auth stores session in Postgres, sets session cookie
5. axios interceptor reads Keycloak access token via Better Auth server helper
6. Go backend validates `Authorization: Bearer <keycloak_access_token>` via JWKS (see backend-dev)

## Documentation

Main entry: [internal-dashboard-frontend/SKILL.md](internal-dashboard-frontend/SKILL.md)

Detailed references:
- [ARCHITECTURE.md](internal-dashboard-frontend/references/ARCHITECTURE.md) - App Router, providers tree, server/client boundaries, feature-sliced layout
- [AUTHENTICATION.md](internal-dashboard-frontend/references/AUTHENTICATION.md) - Better Auth + Keycloak OIDC, middleware, axios interceptor
- [UI-AND-THEMING.md](internal-dashboard-frontend/references/UI-AND-THEMING.md) - Mantine 9.4 setup, AppShell, theme, Notifications, ModalsProvider
- [DATA-FETCHING.md](internal-dashboard-frontend/references/DATA-FETCHING.md) - axios setup, TanStack Query, query keys factory
- [FORMS-AND-VALIDATION.md](internal-dashboard-frontend/references/FORMS-AND-VALIDATION.md) - Mantine form + Zod, shared schemas
- [TABLES-AND-CHARTS.md](internal-dashboard-frontend/references/TABLES-AND-CHARTS.md) - TanStack Table, Recharts
- [TESTING.md](internal-dashboard-frontend/references/TESTING.md) - Vitest + Testing Library + Playwright + MSW
- [CODING-STANDARDS.md](internal-dashboard-frontend/references/CODING-STANDARDS.md) - TypeScript strict, ESLint, Prettier, accessibility
- [DEPLOYMENT.md](internal-dashboard-frontend/references/DEPLOYMENT.md) - Docker, CI/CD, env management

## Design Principles

- **Server-First**: Default to RSC; client components only when needed
- **Route Group Boundaries**: `(public)` for login/logout, `(authed)` for everything else
- **Providers Tree at Root**: Single composition in `providers.tsx`
- **Feature-Sliced Layout**: Each feature owns its api/components/hooks/schemas/types
- **Strict TypeScript**: `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`
- **Env Safety**: Zod-validated at boot; `NEXT_PUBLIC_*` only for client
- **Accessibility Baseline**: WCAG AA, semantic HTML, keyboard-reachable

## Integration with backend-dev

- Forwards Keycloak access tokens to Go backend (no API changes required)
- Reuses backend-dev's OpenBao configuration for secrets management
- Mirrors the backend-dev `ApiError` shape for typed error handling

---

## Skill Documentation Conventions

- Use Go-style code blocks with line numbers for large sections
- Include complete file paths in code block headers
- Provide working examples, not pseudocode
- Document both happy path AND error handling
- Include database schema migrations
- Add environment variable examples