From gopilot
Scan the codebase for violations of gopilot conventions. Checks backend architecture, API design, schema patterns, SDK freshness, and frontend consumption patterns. Use after making changes or before committing.
npx claudepluginhub bishwas-py/gopilot --plugin gopilotThis skill uses the workspace's default tool permissions.
You are auditing the codebase against gopilot's conventions and architecture philosophy. This is not a generic linter — it checks adherence to the Go-first, backend-is-source-of-truth pipeline.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Guides MCP server integration in Claude Code plugins via .mcp.json or plugin.json configs for stdio, SSE, HTTP types, enabling external services as tools.
You are auditing the codebase against gopilot's conventions and architecture philosophy. This is not a generic linter — it checks adherence to the Go-first, backend-is-source-of-truth pipeline.
references/conventions.md for naming and structure rulesreferences/architecture.md for the pipeline and layer responsibilitiesskills/_shared/go-patterns.md for backend conventionsfrontend/svelte.config.js (Svelte) or frontend/next.config.ts (React)skills/_shared/svelte-patterns.md or skills/_shared/react-patterns.mdParse $ARGUMENTS as: [scope]
backend — check only Go backendfrontend — check only frontend SDK consumptionsdk — check SDK freshness and correctnessall (default) — check everythingScan for layer boundary violations:
| Violation | How to Detect |
|---|---|
Handler imports pgx | Handler file imports github.com/jackc/pgx directly |
| Handler contains SQL | Raw SQL strings in *_handlers.go files |
Service imports net/http | Service file imports net/http |
| Repository contains business logic | Conditionals beyond null checks in repository methods |
| Domain imports HTTP or SQL | Domain type files importing net/http or pgx |
| Cross-domain imports | One domain package importing another directly |
Check: backend/internal/api/*_handlers.go should only import huma, net/http, and domain packages.
Check: backend/internal/domain/*/service.go should never import net/http.
Check: backend/internal/domain/*/repository.go should only import pgx and its own domain types.
Scan all input/output structs in *_handlers.go:
| Issue | What's Wrong |
|---|---|
Missing doc: tag | Every field should have documentation |
| Missing validation tags | String fields without minLength:/maxLength: |
Missing json: tag | Struct fields without JSON mapping |
Bare string for enums | Should use enum:"val1,val2" tag |
| Float for money | Money fields should be int (cents) or explicit NUMERIC |
Missing Tags in operation | Huma operation without Tags means SDK can't group it |
Missing OperationID | Every operation needs a unique kebab-case ID |
Check: Every huma.Register call has OperationID, Summary, and Tags.
Check: Every Body struct field has json: and doc: tags.
| Thing | Expected | Violation Example |
|---|---|---|
| Go package | singular lowercase | items (should be item) |
| OperationID | kebab-case | listItems (should be list-items) |
| API path | plural nouns | /api/v1/item (should be /api/v1/items) |
| Handler file | snake_case _handlers.go | itemHandlers.go |
| DB table | plural snake_case | Item (should be items) |
| DB column | snake_case | createdAt (should be created_at) |
Scan backend/schema.sql:
| Issue | What's Wrong |
|---|---|
Missing IF NOT EXISTS | Non-idempotent DDL |
SERIAL or BIGSERIAL ID | Should use TEXT DEFAULT gen_random_uuid()::text |
TIMESTAMP without timezone | Should use TIMESTAMPTZ |
FLOAT/DOUBLE for money | Should use BIGINT (cents) or NUMERIC(12,2) |
PostgreSQL ENUM type | Should use TEXT with CHECK constraint |
| Foreign key without index | Every FK column needs an index |
Missing created_at/updated_at | Every table should have timestamps |
Compare backend and frontend to detect drift:
frontend/openapi.json exists/openapi.json and diff against cached versionfrontend/src/_sdk/schemas.ts exists and has schemasfrontend/src/_sdk/remotes/ has files matching the tags in the OpenAPI spec*_handlers.go files are newer than the SDK filesReport: "SDK is stale — X handlers modified since last generation. Run /gopilot:sdk to regenerate."
| Issue | What's Wrong |
|---|---|
Direct fetch() to Go API | Should use SDK remote functions |
goApi called outside _sdk/ | All Go API calls should go through SDK |
| Manually typed API response | Should import types from _sdk/schemas |
_sdk/ file manually edited | Generated files should never be hand-edited |
| Missing Valibot validation | command() without schema argument |
| Issue | What's Wrong |
|---|---|
'use server' without Zod validation | Server actions must validate input |
| Client component calling Go API directly | Should go through server functions |
| Manual type definitions matching API | Should import from _sdk/schemas |
| Issue | What's Wrong |
|---|---|
Missing docker-compose.yml | No PostgreSQL setup |
Missing backend/Makefile | No dev commands |
Missing backend/schema.sql | No declarative schema |
Missing frontend/src/_sdk/ | No SDK directory |
| Domain without all three files | Each domain needs types, repository, service |
| Handler without registered route | Handler exists but not wired in router.go |
Print a structured report:
# gopilot:check Report
## Summary
✅ 14 checks passed
⚠️ 3 warnings
❌ 2 violations
## Violations (must fix)
❌ **Layer Violation** — `backend/internal/api/item_handlers.go:45`
Handler contains raw SQL query. Move to repository.
❌ **Missing Huma Tags** — `backend/internal/api/booking_handlers.go:12`
`CreateBookingInput.Body.StartDate` missing `doc:` tag.
## Warnings (should fix)
⚠️ **SDK Stale** — `item_handlers.go` modified 2h ago, SDK last generated 3d ago.
Run `/gopilot:sdk` to regenerate.
⚠️ **Naming** — Package `backend/internal/domain/items/` should be singular `item`.
⚠️ **Schema** — Table `bookings` missing index on `user_id` foreign key.
## Passed
✅ Architecture layers clean
✅ All operations have OperationID, Summary, Tags
✅ Database schema uses idempotent DDL
✅ Frontend uses SDK remote functions (no direct fetch)
✅ All domain packages have types + repository + service
... (truncated, show first 5)
go fmt's jobgo vet