tribunal-kit 2.4.6 → 3.1.0

package/.agent/skills/vue-expert/SKILL.md

@@ -1,119 +1,225 @@
----
-name: vue-expert
-description: Vue 3 Composition API and modern Vue ecosystem expert. Use when building Vue applications, optimizing reactivity, component architecture, Nuxt 3 development, performance tuning, and State Management (Pinia).
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
-applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
----
-
-# Vue Expert - Claude Code Sub-Agent
-
-You are a senior Vue expert with expertise in Vue 3 Composition API and the modern Vue ecosystem. Your focus spans reactivity mastery, component architecture, performance optimization, and full-stack development with emphasis on creating maintainable applications that leverage Vue's elegant simplicity.
-
-## Configuration & Context Assessment
-When invoked:
-1. Query context manager for Vue project requirements and architecture
-2. Review component structure, reactivity patterns, and performance needs
-3. Analyze Vue best practices, optimization opportunities, and ecosystem integration
-4. Implement modern Vue solutions with reactivity and performance focus
-
----
-
-## The Vue Excellence Checklist
-- Vue 3 best practices followed completely
-- Composition API utilized effectively
-- TypeScript integration proper maintained
-- Component tests > 85% achieved
-- Bundle optimization completed thoroughly
-- SSR/SSG support implemented properly
-- Accessibility standards met consistently
-- Performance optimized successfully
-
----
-
-## Core Architecture Decision Framework
-
-### Reactivity Mastery & Composition API
-*   **Composition API Patterns:** Setup function, reactive refs, reactive objects, computed properties, watchers, lifecycle hooks, provide/inject.
-*   **Reactivity Optimization:** Ref vs reactive, shallow reactivity, computed efficiency, watch vs watchEffect, effect scope, minimal ref unwrapping, memory management.
-
-### Component Design & Ecosystem
-*   **Component Architecture:** Composables design, renderless components, scoped slots, dynamic/async components, teleport usage, and transition effects.
-*   **State Management (Pinia):** Store design, actions/getters, plugins usage, devtools integration, persistence, module patterns, and type safety.
-*   **Ecosystem Integration:** VueUse utilities, Vue Router advanced, Vite configuration, Vue Test Utils, Vitest setup.
-
-### Extreme Performance Optimization
-*   Component lazy loading
-*   Tree shaking & Bundle splitting
-*   Virtual scrolling & Memoization
-*   Reactive optimization & Render optimization
-
----
-
-## Nuxt 3 Development
-
-Build universal Vue applications that excel in speed and SEO:
--   Universal rendering & Edge caching strategies
--   File-based routing & Auto imports
--   Server API routes (Nitro server)
--   Data fetching & SEO optimization
--   Monitoring setup & Analytics integrated
-
----
-
-## Testing & Quality Assurance
-
-*   **Testing Coverage:** Component testing, Composable testing, Store testing, E2E (Cypress), Visual regression, Performance, Accessibility.
-*   **TypeScript Accuracy:** Component typing, Props validation, Emit typing, Ref typing, Composable types, Store typing, Strict mode.
-*   **Enterprise Patterns:** Micro-frontends, Design systems, Error handling, Logging systems, CI/CD integration.
-
----
-
-## Output Format
-
-When this skill produces or reviews code, structure your output as follows:
-
-```
-━━━ Vue Expert Report ━━━━━━━━━━━━━━━━━━━━━━━━
-Skill:       Vue Expert
-Language:    [detected language / framework]
-Scope:       [N files · N functions]
-─────────────────────────────────────────────────
-✅ Passed:   [checks that passed, or "All clean"]
-⚠️  Warnings: [non-blocking issues, or "None"]
-❌ Blocked:  [blocking issues requiring fix, or "None"]
-─────────────────────────────────────────────────
-VBC status:  PENDING → VERIFIED
-Evidence:    [test output / lint pass / compile success]
-```
-
-**VBC (Verification-Before-Completion) is mandatory.**
-Do not mark status as VERIFIED until concrete terminal evidence is provided.
-
-
----
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/tribunal-frontend`**
-**Active reviewers: `logic` · `security` · `frontend` · `type-safety`**
-
-### ❌ Forbidden AI Tropes in Vue
-1. **Sloppy Layout Generation** — never build UI without explicit dimensional boundaries. You MUST apply strict numeric design tokens (e.g. 4px grid spacing) and explicit flex/grid layouts.
-2. **Using Options API inappropriately** — always prefer Composition API (`<script setup>`) in Vue 3 projects.
-3. **Mutating props directly** — never mutate props; always emit updates using `defineEmits` or implement `v-model`.
-4. **Overusing Vuex** — never hallucinate Vuex in a modern Vue 3 project; Pinia is the standard.
-4. **Losing reactivity** — destructuring reactive objects without `toRefs()` or pulling store state without `storeToRefs()`.
-5. **Missing `key` in `v-for`** — always provide a unique, stable key. No using iteration index as the key.
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before generating Vue/Nuxt code:
-```text
-✅ Did I maximize Composition API and `<script setup>` usage?
-✅ Are there any reactivity losses in destructured props or state?
-✅ Did I ensure no sensitive environment variables leak to the client (`useRuntimeConfig` private keys)?
-✅ Did I use proper async component loading for heavy dependencies?
-✅ Did I implement complete TypeScript coverage (emit types, prop types, refs)?
-```
+---
+name: vue-expert
+description: Vue 3.5+ Composition API. Script setup, reactive refs, computed, watchers, composables, Pinia, Vue Router 4, Nuxt 4. Use when building Vue/Nuxt applications.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 3.1.0
+last-updated: 2026-04-06
+---
+
+# Vue 3.5+ & Nuxt 4 — Dense Reference
+
+## Hallucination Traps (Read First)
+- ❌ Options API (`data()`, `methods:`, `computed:`) → ✅ `<script setup lang="ts">`
+- ❌ `defineComponent()` with `<script setup>` → ✅ redundant, skip it
+- ❌ `defineModel` in Vue < 3.4 → ✅ added in 3.4+
+- ❌ `ref.value` in template → ✅ auto-unwrapped in template (no `.value`)
+- ❌ `reactive()` for primitives → ✅ use `ref()` — `reactive()` breaks on reassign
+- ❌ `watch(state.count, ...)` (primitive) → ✅ `watch(() => state.count, ...)`
+- ❌ `onBeforeMount` for data fetch → ✅ use `await` directly in `<script setup>` + `<Suspense>`
+- ❌ Pinia `this.$store` → ✅ `useStore()` from `pinia`
+- ❌ `useRoute()` / `useRouter()` outside setup → ✅ only works inside `<script setup>` or composables
+
+---
+
+## `<script setup>` — The Only Way
+
+```vue
+<script setup lang="ts">
+import { ref, computed, watch, onMounted } from "vue";
+
+// Props
+const props = defineProps<{ title: string; count?: number }>();
+// With defaults:
+const props = withDefaults(defineProps<{ variant?: "primary" | "secondary" }>(), { variant: "primary" });
+
+// Emits
+const emit = defineEmits<{ update: [value: string]; delete: [id: number] }>();
+
+// v-model (Vue 3.4+)
+const modelValue = defineModel<string>();          // default model
+const count = defineModel<number>("count");         // named model
+
+// Expose to parent ref
+defineExpose({ reset: () => {}, focus: () => {} });
+</script>
+```
+
+---
+
+## Reactivity
+
+```ts
+// ref — for primitives and objects (access via .value in JS, auto-unwrap in template)
+const count = ref(0);
+count.value++;
+
+// reactive — for objects (loses reactivity on reassign/destructure)
+const state = reactive({ name: "Alice", age: 25 });
+// ❌ const { name } = state; // loses reactivity
+// ✅ const name = computed(() => state.name);
+
+// computed — cached, re-runs only when deps change
+const doubled = computed(() => count.value * 2);
+const fullName = computed({
+  get: () => `${first.value} ${last.value}`,
+  set: (v) => { [first.value, last.value] = v.split(" "); },
+});
+
+// watch
+watch(count, (newVal, oldVal) => {}); // immediate: false by default
+watch(() => props.id, fetchUser, { immediate: true });
+watchEffect(() => { console.log(count.value); }); // auto-tracks deps
+```
+
+---
+
+## Composables (Custom Hooks)
+
+```ts
+// useCounter.ts
+export function useCounter(initial = 0) {
+  const count = ref(initial);
+  const increment = () => count.value++;
+  const reset = () => (count.value = initial);
+  return { count: readonly(count), increment, reset };
+}
+
+// useAsyncData.ts
+export function useAsyncData<T>(fn: () => Promise<T>) {
+  const data = ref<T | null>(null);
+  const error = ref<Error | null>(null);
+  const loading = ref(false);
+  async function execute() {
+    loading.value = true;
+    try { data.value = await fn(); }
+    catch (e) { error.value = e as Error; }
+    finally { loading.value = false; }
+  }
+  execute();
+  return { data, error, loading, refresh: execute };
+}
+```
+
+---
+
+## Pinia
+
+```ts
+// stores/counter.ts
+import { defineStore } from "pinia";
+export const useCounterStore = defineStore("counter", () => {
+  const count = ref(0);                 // Setup Store (preferred)
+  const doubled = computed(() => count.value * 2);
+  function increment() { count.value++; }
+  return { count, doubled, increment };
+});
+
+// Usage in component:
+const store = useCounterStore();
+// ❌ const { count } = store;        // loses reactivity!
+// ✅ const count = storeToRefs(store).count;
+import { storeToRefs } from "pinia";
+const { count } = storeToRefs(store);
+
+// Persist plugin:
+import { createPinia } from "pinia";
+import piniaPluginPersistedstate from "pinia-plugin-persistedstate";
+const pinia = createPinia().use(piniaPluginPersistedstate);
+```
+
+---
+
+## Vue Router 4
+
+```ts
+// router/index.ts
+import { createRouter, createWebHistory } from "vue-router";
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    { path: "/", component: () => import("./views/Home.vue") }, // lazy-loaded
+    { path: "/user/:id", component: UserView, props: true },    // props:true passes params as props
+    { path: "/:pathMatch(.*)*", component: NotFound },          // 404 catch-all
+  ],
+});
+// Route guards
+router.beforeEach(async (to, from) => {
+  if (to.meta.requiresAuth && !isLoggedIn()) return { name: "Login" };
+});
+
+// In component:
+import { useRouter, useRoute } from "vue-router";
+const router = useRouter();
+const route = useRoute();
+router.push({ name: "User", params: { id: 42 } });
+const userId = route.params.id as string;
+```
+
+---
+
+## Templates
+
+```vue
+<template>
+  <!-- v-model -->
+  <input v-model="email" />
+  <MyInput v-model:title="title" v-model:count="count" />  <!-- named model -->
+  
+  <!-- v-for with key (ALWAYS set key) -->
+  <li v-for="item in items" :key="item.id">{{ item.name }}</li>
+  
+  <!-- Dynamic components -->
+  <component :is="currentTab" />
+  
+  <!-- Teleport — render in a different DOM node -->
+  <Teleport to="body"><Modal v-if="showModal" /></Teleport>
+  
+  <!-- Transition -->
+  <Transition name="fade" mode="out-in">
+    <component :is="view" :key="view" />
+  </Transition>
+  
+  <!-- Suspense (async components / composables with await) -->
+  <Suspense><AsyncComponent /><template #fallback>Loading...</template></Suspense>
+</template>
+
+<style>
+/* Transition CSS */
+.fade-enter-active, .fade-leave-active { transition: opacity 0.3s; }
+.fade-enter-from, .fade-leave-to { opacity: 0; }
+</style>
+```
+
+---
+
+## Nuxt 4
+
+```
+auto-imports:    ref, computed, useRoute, useFetch — no imports needed
+composables/:    auto-imported by filename
+server/api/:     server routes (GET/POST)
+pages/:          file-based routing
+layouts/:        layout components
+middleware/:     route guards
+```
+
+```ts
+// pages/users/[id].vue
+const { id } = useRoute().params;                       // auto-imported
+const { data, error, refresh } = await useFetch(`/api/users/${id}`, {
+  lazy: false,        // SSR: wait for data before rendering
+  server: true,       // fetch on server (default)
+  transform: (r) => r.user,
+});
+// ❌ TRAP: useFetch in Nuxt ≠ @tanstack/react-query. It's Nuxt-specific.
+// ❌ TRAP: useAsyncData key must be UNIQUE per page/component
+```
+
+---
+
+## Performance
+- ✅ Use `v-memo` for expensive list items that rarely change
+- ✅ `defineAsyncComponent(() => import("./Heavy.vue"))` for code splitting
+- ✅ `:key` on `<component :is>` forces re-mount on route change (prevents stale state)
+- ❌ Avoid deeply nested reactive objects — use `shallowRef`/`shallowReactive` for large data
+- ❌ Never mutate props — emit events instead