feat: overhaul Claude Code automation — agents, skills, hooks, docs

.claude/agents/backend-review.md

@@ -0,0 +1,123 @@
+---
+name: backend-review
+description: >
+  Review Go backend code for convention violations. Use after modifying files
+  under components/backend/. Checks for panic usage, service account misuse,
+  type assertion safety, error handling, token security, and file size.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+---
+
+# Backend Review Agent
+
+Review backend Go code against documented conventions.
+
+## Context
+
+Load these files before running checks:
+
+1. `components/backend/DEVELOPMENT.md`
+2. `components/backend/ERROR_PATTERNS.md`
+3. `components/backend/K8S_CLIENT_PATTERNS.md`
+
+## Checks
+
+### B1: No panic() in production (Blocker)
+
+```bash
+grep -rn "panic(" components/backend/ --include="*.go" | grep -v "_test.go"
+```
+
+Any match is a Blocker. Production code must return `fmt.Errorf` with context.
+
+### B2: User-scoped clients for user operations (Blocker)
+
+In `components/backend/handlers/`:
+- `DynamicClient.Resource` or `K8sClient` used for List/Get operations should use `GetK8sClientsForRequest(c)` instead
+- Acceptable uses: after RBAC validation for writes, token minting, cleanup
+
+```bash
+grep -rnE "DynamicClient\.|K8sClient\." components/backend/handlers/ --include="*.go" | grep -v "_test.go"
+```
+
+Cross-reference each match against the decision tree in `K8S_CLIENT_PATTERNS.md`.
+
+### B3: No direct type assertions on unstructured (Critical)
+
+```bash
+grep -rnE 'Object\["[^"]+"\]\.\(' components/backend/ --include="*.go" | grep -v "_test.go"
+```
+
+Must use `unstructured.NestedMap`, `unstructured.NestedString`, etc.
+
+### B4: No silent error handling (Critical)
+
+Look for empty error handling blocks:
+```bash
+rg -nUP 'if err != nil \{\s*\n\s*\}' --type go --glob '!*_test.go' components/backend/
+```
+
+Also manually inspect `if err != nil` blocks for cases where the body only contains a comment (no actual handling).
+
+### B5: No internal error exposure in API responses (Major)
+
+```bash
+grep -rn 'gin.H{"error":.*fmt\.Sprintf\|gin.H{"error":.*err\.' components/backend/handlers/ --include="*.go" | grep -v "_test.go"
+```
+
+API responses should use generic messages. Detailed errors go to logs.
+
+### B6: No tokens in logs (Blocker)
+
+```bash
+grep -rn 'log.*[Tt]oken\b\|log.*[Ss]ecret\b' components/backend/ --include="*.go" | grep -v "len(token)\|_test.go"
+```
+
+Use `len(token)` for logging, never the token value itself.
+
+### B7: Error wrapping with %w (Major)
+
+```bash
+grep -rnP 'fmt.Errorf.*%v.*\berr\b' components/backend/ --include="*.go" | grep -v "_test.go"
+```
+
+Should use `%w` for error wrapping to preserve the error chain.
+
+### B8: Files under 400 lines (Minor)
+
+```bash
+find components/backend/handlers/ -name "*.go" -not -name "*_test.go" -print0 | xargs -0 wc -l | sort -rn
+```
+
+Flag files exceeding 400 lines. Note: `sessions.go` is a known exception.
+
+## Output Format
+
+```markdown
+# Backend Review
+
+## Summary
+[1-2 sentence overview]
+
+## Findings
+
+### Blocker
+[Must fix — or "None"]
+
+### Critical
+[Should fix — or "None"]
+
+### Major
+[Important — or "None"]
+
+### Minor
+[Nice-to-have — or "None"]
+
+## Score
+[X/8 checks passed]
+```
+
+Each finding includes: file:line, problem description, convention violated, suggested fix.

.claude/agents/convention-eval.md

@@ -0,0 +1,130 @@
+---
+name: convention-eval
+description: >
+  Runs all convention checks across the full codebase and produces a scored
+  alignment report. Dispatched by the /align skill.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+---
+
+# Convention Evaluation Agent
+
+Evaluate codebase adherence to documented conventions. Produce a scored report.
+
+## Context Files
+
+Load these before running checks:
+
+1. `components/backend/DEVELOPMENT.md`
+2. `components/backend/ERROR_PATTERNS.md`
+3. `components/backend/K8S_CLIENT_PATTERNS.md`
+4. `components/frontend/DEVELOPMENT.md`
+5. `components/frontend/REACT_QUERY_PATTERNS.md`
+6. `components/operator/DEVELOPMENT.md`
+7. `docs/security-standards.md`
+
+## Checks by Category
+
+### Backend (8 checks, weight: 25%)
+
+| # | Check | Severity |
+|---|-------|----------|
+| B1 | No `panic()` in production | Blocker |
+| B2 | User-scoped clients for user ops | Blocker |
+| B3 | No direct type assertions | Critical |
+| B4 | No silent error handling | Critical |
+| B5 | No internal error exposure | Major |
+| B6 | No tokens in logs | Blocker |
+| B7 | Error wrapping with %w | Major |
+| B8 | Files under 400 lines | Minor |
+
+### Frontend (8 checks, weight: 25%)
+
+| # | Check | Severity |
+|---|-------|----------|
+| F1 | No raw HTML elements | Critical |
+| F2 | No manual fetch() | Critical |
+| F3 | No `interface` declarations | Major |
+| F4 | No `any` types | Critical |
+| F5 | Components under 200 lines | Minor |
+| F6 | Loading/error states | Major |
+| F7 | Colocated single-use components | Minor |
+| F8 | Feature flag on new pages | Major |
+
+### Operator (7 checks, weight: 20%)
+
+| # | Check | Severity |
+|---|-------|----------|
+| O1 | OwnerReferences on child resources | Blocker |
+| O2 | Proper reconciliation patterns | Critical |
+| O3 | SecurityContext on Job pods | Critical |
+| O4 | Resource limits/requests | Major |
+| O5 | No `panic()` in production | Blocker |
+| O6 | Status condition updates | Critical |
+| O7 | No `context.TODO()` | Minor |
+
+### Runner (4 checks, weight: 10%)
+
+| # | Check | Severity |
+|---|-------|----------|
+| R1 | Proper async patterns | Major |
+| R2 | Credential handling | Blocker |
+| R3 | Error propagation | Critical |
+| R4 | No hardcoded secrets | Blocker |
+
+### Security (7 checks, weight: 20%)
+
+| # | Check | Severity |
+|---|-------|----------|
+| S1 | User token for user ops | Blocker |
+| S2 | RBAC before resource access | Critical |
+| S3 | Token redaction | Blocker |
+| S4 | Input validation | Major |
+| S5 | SecurityContext on pods | Critical |
+| S6 | OwnerReferences on Secrets | Critical |
+| S7 | No hardcoded credentials | Blocker |
+
+## Scoring
+
+- Each check: Pass (1) or Fail (0)
+- Category score: passes / total
+- Overall score:
+  - Full scope: weighted average across all categories
+  - Scoped runs: renormalize weights to selected categories (e.g., backend-only uses 100% backend weight)
+
+## Output Format
+
+```markdown
+# Convention Alignment Report
+
+**Scope:** [full | backend | frontend | ...]
+**Date:** [ISO date]
+**Overall Score:** [X%]
+
+## Category Scores
+
+| Category | Score | Pass | Fail | Blockers |
+|----------|-------|------|------|----------|
+| Backend  | X/8   | X    | X    | X        |
+| Frontend | X/8   | X    | X    | X        |
+| Operator | X/7   | X    | X    | X        |
+| Runner   | X/4   | X    | X    | X        |
+| Security | X/7   | X    | X    | X        |
+
+## Failures
+
+### Blockers
+[List with file:line references]
+
+### Critical
+[List with file:line references]
+
+### Major / Minor
+[List]
+
+## Recommendations
+[Top 3 priorities to improve alignment]
+```

.claude/agents/frontend-review.md

@@ -0,0 +1,116 @@
+---
+name: frontend-review
+description: >
+  Review frontend TypeScript/React code for convention violations. Use after
+  modifying files under components/frontend/src/. Checks for raw HTML elements,
+  manual fetch, any types, interface usage, component size, and missing states.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+---
+
+# Frontend Review Agent
+
+Review frontend code against documented conventions.
+
+## Context
+
+Load these files before running checks:
+
+1. `components/frontend/DEVELOPMENT.md`
+2. `components/frontend/REACT_QUERY_PATTERNS.md`
+3. `components/frontend/DESIGN_GUIDELINES.md` (if it exists)
+
+## Checks
+
+### F1: No raw HTML elements (Critical)
+
+```bash
+grep -rn "<button\|<input\|<select\|<dialog\|<textarea" components/frontend/src/ --include="*.tsx" | grep -v "components/ui/"
+```
+
+Must use Shadcn UI components from `@/components/ui/`.
+
+### F2: No manual fetch() in components (Critical)
+
+```bash
+grep -rn "fetch(" components/frontend/src/app/ components/frontend/src/components/ --include="*.tsx" --include="*.ts" | grep -v "services/api/\|src/app/api/"
+```
+
+Use React Query hooks from `@/services/queries/`.
+
+### F3: No interface declarations (Major)
+
+```bash
+grep -rn "^export interface \|^interface " components/frontend/src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules"
+```
+
+Use `type` instead of `interface`.
+
+### F4: No any types (Critical)
+
+```bash
+grep -rn ": any\b\|as any\b\|<any>" components/frontend/src/ --include="*.ts" --include="*.tsx" | grep -v "node_modules\|\.d\.ts"
+```
+
+Use proper types, `unknown`, or generic constraints.
+
+### F5: Components under 200 lines (Minor)
+
+```bash
+find components/frontend/src/ -name "*.tsx" -print0 | xargs -0 wc -l | sort -rn | head -20
+```
+
+Flag components exceeding 200 lines. Consider splitting.
+
+### F6: Loading/error/empty states (Major)
+
+For components using `useQuery`:
+- Must reference `isLoading` or `isPending`
+- Must reference `error`
+- Should handle empty data
+
+```bash
+grep -rl "useQuery\|useSessions\|useSession" \
+  components/frontend/src/app/ components/frontend/src/components/ --include="*.tsx"
+```
+
+Then check each file for `isLoading\|isPending` and `error` references.
+
+### F7: Single-use components in shared directories (Minor)
+
+Check `components/frontend/src/components/` for components imported only once. These should be co-located with their page in `_components/`.
+
+### F8: Feature flag on new pages (Major)
+
+New `page.tsx` files should reference `useWorkspaceFlag` or `useFlag` for feature gating.
+
+## Output Format
+
+```markdown
+# Frontend Review
+
+## Summary
+[1-2 sentence overview]
+
+## Findings
+
+### Blocker
+[Must fix — or "None"]
+
+### Critical
+[Should fix — or "None"]
+
+### Major
+[Important — or "None"]
+
+### Minor
+[Nice-to-have — or "None"]
+
+## Score
+[X/8 checks passed]
+```
+
+Each finding includes: file:line, problem description, convention violated, suggested fix.