@dianzhong/create-harness-app 0.1.0

package/templates/harness/full/.agents/skills/vue-best-practices/references/sfc.md

@@ -0,0 +1,355 @@
+---
+title: Single-File Component Structure, Styling, and Template Patterns
+impact: MEDIUM
+impactDescription: Consistent SFC structure and styling choices improve maintainability, tooling support, and render performance
+type: best-practice
+tags:
+  [
+    vue3,
+    sfc,
+    scoped-css,
+    styles,
+    build-tools,
+    performance,
+    template,
+    v-html,
+    v-for,
+    computed,
+    v-if,
+    v-show,
+  ]
+---
+
+# Single-File Component Structure, Styling, and Template Patterns
+
+**Impact: MEDIUM** - Using SFCs with consistent structure and performant styling keeps components easier to maintain and avoids unnecessary render overhead.
+
+## Task List
+
+- Use `.vue` SFCs instead of separate `.js`/`.ts` and `.css` files for components
+- Colocate template, script, and styles in the same SFC by default
+- Use PascalCase for component names in templates and filenames
+- Prefer component-scoped styles
+- Prefer class selectors (not element selectors) in scoped CSS for performance
+- Access DOM / component refs with `useTemplateRef()` in Vue 3.5+
+- Use camelCase keys in `:style` bindings for consistency and IDE support
+- Use `v-for` and `v-if` correctly
+- Never use `v-html` with untrusted/user-provided content
+- Choose `v-if` vs `v-show` based on toggle frequency and initial render cost
+
+## Colocate template, script, and styles
+
+**BAD:**
+
+```
+components/
+├── UserCard.vue
+├── UserCard.js
+└── UserCard.css
+```
+
+**GOOD:**
+
+```vue
+<!-- components/UserCard.vue -->
+<script setup>
+import { computed } from 'vue'
+
+const props = defineProps({
+  user: { type: Object, required: true },
+})
+
+const displayName = computed(() => `${props.user.firstName} ${props.user.lastName}`)
+</script>
+
+<template>
+  <div class="user-card">
+    <h3 class="name">
+      {{ displayName }}
+    </h3>
+  </div>
+</template>
+
+<style scoped>
+.user-card {
+  padding: 1rem;
+}
+
+.name {
+  margin: 0;
+}
+</style>
+```
+
+## Use PascalCase for component names
+
+**BAD:**
+
+```vue
+<script setup>
+import userProfile from './user-profile.vue'
+</script>
+
+<template>
+  <user-profile :user="currentUser" />
+</template>
+```
+
+**GOOD:**
+
+```vue
+<script setup>
+import UserProfile from './UserProfile.vue'
+</script>
+
+<template>
+  <UserProfile :user="currentUser" />
+</template>
+```
+
+## Best practices for `<style>` block in SFCs
+
+### Prefer component-scoped styles
+
+- Use `<style scoped>` for styles that belong to a component.
+- Keep **global CSS** in a dedicated file (e.g. `src/assets/main.css`) for resets, typography, tokens, etc.
+- Use `:deep()` sparingly (edge cases only).
+
+**BAD:**
+
+```vue
+<style>
+/* ❌ leaks everywhere */
+button {
+  border-radius: 999px;
+}
+</style>
+```
+
+**GOOD:**
+
+```vue
+<style scoped>
+.button {
+  border-radius: 999px;
+}
+</style>
+```
+
+**GOOD:**
+
+```css
+/* src/assets/main.css */
+/* ✅ resets, tokens, typography, app-wide rules */
+:root {
+  --radius: 999px;
+}
+```
+
+### Use class selectors in scoped CSS
+
+**BAD:**
+
+```vue
+<template>
+  <article>
+    <h1>{{ title }}</h1>
+    <p>{{ subtitle }}</p>
+  </article>
+</template>
+
+<style scoped>
+article {
+  max-width: 800px;
+}
+h1 {
+  font-size: 2rem;
+}
+p {
+  line-height: 1.6;
+}
+</style>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <article class="article">
+    <h1 class="article-title">
+      {{ title }}
+    </h1>
+    <p class="article-subtitle">
+      {{ subtitle }}
+    </p>
+  </article>
+</template>
+
+<style scoped>
+.article {
+  max-width: 800px;
+}
+.article-title {
+  font-size: 2rem;
+}
+.article-subtitle {
+  line-height: 1.6;
+}
+</style>
+```
+
+## Access DOM / component refs with `useTemplateRef()`
+
+For Vue 3.5+: use `useTemplateRef()` to access template refs.
+
+```vue
+<script setup lang="ts">
+import { onMounted, useTemplateRef } from 'vue'
+
+const inputRef = useTemplateRef<HTMLInputElement>('input')
+
+onMounted(() => {
+  inputRef.value?.focus()
+})
+</script>
+
+<template>
+  <input ref="input" />
+</template>
+```
+
+## Use camelCase in `:style` bindings
+
+**BAD:**
+
+```vue
+<template>
+  <div :style="{ 'font-size': `${fontSize}px`, 'background-color': bg }">Content</div>
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <div :style="{ fontSize: `${fontSize}px`, backgroundColor: bg }">Content</div>
+</template>
+```
+
+## Use `v-for` and `v-if` correctly
+
+### Always provide a stable `:key`
+
+- Prefer primitive keys (`string | number`).
+- Avoid using objects as keys.
+
+**GOOD:**
+
+```vue
+<li v-for="item in items" :key="item.id">
+  <input v-model="item.text" />
+</li>
+```
+
+### Avoid `v-if` and `v-for` on the same element
+
+It leads to unclear intent and unnecessary work.
+([Reference](https://vuejs.org/guide/essentials/list.html#v-for-with-v-if))
+
+**To filter items**
+**BAD:**
+
+```vue
+<li v-for="user in users" v-if="user.active" :key="user.id">
+  {{ user.name }}
+</li>
+```
+
+**GOOD:**
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const activeUsers = computed(() => users.value.filter((u) => u.active))
+</script>
+
+<template>
+  <li v-for="user in activeUsers" :key="user.id">
+    {{ user.name }}
+  </li>
+</template>
+```
+
+**To conditionally show/hide the entire list**
+**GOOD:**
+
+```vue
+<ul v-if="shouldShowUsers">
+  <li v-for="user in users" :key="user.id">
+    {{ user.name }}
+  </li>
+</ul>
+```
+
+## Never render untrusted HTML with `v-html`
+
+**BAD:**
+
+```vue
+<template>
+  <!-- DANGEROUS: untrusted input can inject scripts -->
+  <article v-html="userProvidedContent" />
+</template>
+```
+
+**GOOD:**
+
+```vue
+<script setup>
+import DOMPurify from 'dompurify'
+
+import { computed } from 'vue'
+
+const props = defineProps<{
+  trustedHtml?: string
+  plainText: string
+}>()
+
+const safeHtml = computed(() => DOMPurify.sanitize(props.trustedHtml ?? ''))
+</script>
+
+<template>
+  <!-- Preferred: escaped interpolation -->
+  <p>{{ props.plainText }}</p>
+
+  <!-- Only for trusted/sanitized HTML -->
+  <article v-html="safeHtml" />
+</template>
+```
+
+## Choose `v-if` vs `v-show` by toggle behavior
+
+**BAD:**
+
+```vue
+<template>
+  <!-- Frequent toggles with v-if cause repeated mount/unmount -->
+  <ComplexPanel v-if="isPanelOpen" />
+
+  <!-- Rarely shown content with v-show pays initial render cost -->
+  <AdminPanel v-show="isAdmin" />
+</template>
+```
+
+**GOOD:**
+
+```vue
+<template>
+  <!-- Frequent toggles: keep in DOM, toggle display -->
+  <ComplexPanel v-show="isPanelOpen" />
+
+  <!-- Rare condition: lazy render only when true -->
+  <AdminPanel v-if="isAdmin" />
+</template>
+```

package/templates/harness/full/.agents/skills/vue-best-practices/references/state-management.md

@@ -0,0 +1,138 @@
+---
+title: State Management Strategy
+impact: HIGH
+impactDescription: Choosing the wrong store pattern can cause SSR request leaks, brittle mutation flows, and poor scaling
+type: best-practice
+tags: [vue3, state-management, pinia, composables, ssr, vueuse]
+---
+
+# State Management Strategy
+
+**Impact: HIGH** - Use the lightest state solution that fits your app architecture. SPA-only apps can use lightweight global composables, while SSR/Nuxt apps should default to Pinia for request-safe isolation and predictable tooling.
+
+## Task List
+
+- Keep state local first, then promote to shared/global only when needed
+- Use singleton composables only in non-SSR applications
+- Expose global state as readonly and mutate through explicit actions
+- Prefer Pinia for SSR/Nuxt, large apps, and advanced debugging/plugin needs
+- Avoid exporting mutable module-level reactive state directly
+
+## Choose the Lightest Store Approach
+
+- **Feature composable:** Default for reusable logic with local/feature-level state.
+- **Singleton composable or VueUse `createGlobalState`:** Small non-SSR apps needing shared app state.
+- **Pinia:** SSR/Nuxt apps, medium-to-large apps, and cases requiring DevTools, plugins, or action tracing.
+
+## Avoid Exporting Mutable Module State
+
+**BAD:**
+
+```ts
+// store/cart.ts
+import { reactive } from 'vue'
+
+export const cart = reactive({
+  items: [] as Array<{ id: string; qty: number }>,
+})
+```
+
+**GOOD:**
+
+```ts
+// composables/useCartStore.ts
+import { reactive, readonly } from 'vue'
+
+let _store: ReturnType<typeof createCartStore> | null = null
+
+function createCartStore() {
+  const state = reactive({
+    items: [] as Array<{ id: string; qty: number }>,
+  })
+
+  function addItem(id: string, qty = 1) {
+    const existing = state.items.find((item) => item.id === id)
+    if (existing) {
+      existing.qty += qty
+      return
+    }
+    state.items.push({ id, qty })
+  }
+
+  return {
+    state: readonly(state),
+    addItem,
+  }
+}
+
+export function useCartStore() {
+  if (!_store) _store = createCartStore()
+  return _store
+}
+```
+
+## Do Not Use Runtime Singletons in SSR
+
+Module singletons live for the runtime lifetime. In SSR this can leak state between requests.
+
+**BAD:**
+
+```ts
+// shared singleton reused across requests
+const cartStore = useCartStore()
+
+export function useServerCart() {
+  return cartStore
+}
+```
+
+**GOOD:**
+
+> `pinia` dependency required.
+
+```ts
+// stores/cart.ts
+import { defineStore } from 'pinia'
+
+export const useCartStore = defineStore('cart', {
+  state: () => ({
+    items: [] as Array<{ id: string; qty: number }>,
+  }),
+  actions: {
+    addItem(id: string, qty = 1) {
+      const existing = this.items.find((item) => item.id === id)
+      if (existing) {
+        existing.qty += qty
+        return
+      }
+      this.items.push({ id, qty })
+    },
+  },
+})
+```
+
+## Use `createGlobalState` for Small SPA Global State
+
+> `@vueuse/core` dependency required.
+
+If the app is non-SSR and already uses VueUse, `createGlobalState` removes singleton boilerplate.
+
+```ts
+import { createGlobalState } from '@vueuse/core'
+import { computed, ref } from 'vue'
+
+export const useAuthState = createGlobalState(() => {
+  const token = ref<string | null>(null)
+  const isAuthenticated = computed(() => token.value !== null)
+
+  function setToken(next: string | null) {
+    token.value = next
+  }
+
+  return {
+    token,
+    isAuthenticated,
+    setToken,
+  }
+})
+```

package/templates/harness/full/.agents/skills/vue-best-practices/references/updated-hook-performance.md

@@ -0,0 +1,193 @@
+---
+title: Avoid Expensive Operations in Updated Hook
+impact: MEDIUM
+impactDescription: Heavy computations in updated hook cause performance bottlenecks and potential infinite loops
+type: capability
+tags: [vue3, vue2, lifecycle, updated, performance, optimization, reactivity]
+---
+
+# Avoid Expensive Operations in Updated Hook
+
+**Impact: MEDIUM** - The `updated` hook runs after every reactive state change that causes a re-render. Placing expensive operations, API calls, or state mutations here can cause severe performance degradation, infinite loops, and dropped frames below the optimal 60fps threshold.
+
+Use `updated`/`onUpdated` sparingly for post-DOM-update operations that cannot be handled by watchers or computed properties. For most reactive data handling, prefer watchers (`watch`/`watchEffect`) which provide more control over what triggers the callback.
+
+## Task List
+
+- Never perform API calls in updated hook
+- Never mutate reactive state inside updated (causes infinite loops)
+- Use conditional checks to verify updates are relevant before acting
+- Prefer `watch` or `watchEffect` for reacting to specific data changes
+- Use throttling/debouncing if updated operations are expensive
+- Reserve updated for low-level DOM synchronization tasks
+
+**BAD:**
+
+```javascript
+// BAD: API call in updated - fires on every re-render
+export default {
+  data() {
+    return { items: [], lastUpdate: null }
+  },
+  updated() {
+    // This runs after every single state change!
+    fetch('/api/sync', {
+      method: 'POST',
+      body: JSON.stringify(this.items),
+    })
+  },
+}
+```
+
+```javascript
+// BAD: State mutation in updated - infinite loop
+export default {
+  data() {
+    return { renderCount: 0 }
+  },
+  updated() {
+    // This causes another update, which triggers updated again!
+    this.renderCount++ // Infinite loop
+  },
+}
+```
+
+```javascript
+// BAD: Heavy computation on every update
+export default {
+  updated() {
+    // Expensive operation runs on every keystroke, every state change
+    this.processedData = this.heavyComputation(this.rawData)
+    this.analytics = this.calculateMetrics(this.allData)
+  },
+}
+```
+
+**GOOD:**
+
+```javascript
+import debounce from 'lodash-es/debounce'
+
+// GOOD: Use watcher for specific data changes
+export default {
+  data() {
+    return { items: [] }
+  },
+  watch: {
+    // Only fires when items actually changes
+    items: {
+      handler(newItems) {
+        this.syncToServer(newItems)
+      },
+      deep: true,
+    },
+  },
+  methods: {
+    syncToServer: debounce((items) => {
+      fetch('/api/sync', {
+        method: 'POST',
+        body: JSON.stringify(items),
+      })
+    }, 500),
+  },
+}
+```
+
+```vue
+<!-- GOOD: Composition API with targeted watchers -->
+<script setup>
+import { useDebounceFn } from '@vueuse/core'
+import { onUpdated, ref, watch } from 'vue'
+
+const items = ref([])
+const scrollContainer = ref(null)
+
+// Watch specific data - not all updates
+watch(
+  items,
+  (newItems) => {
+    syncToServer(newItems)
+  },
+  { deep: true },
+)
+
+const syncToServer = useDebounceFn((items) => {
+  fetch('/api/sync', { method: 'POST', body: JSON.stringify(items) })
+}, 500)
+
+// Only use onUpdated for DOM synchronization
+onUpdated(() => {
+  // Scroll to bottom only if content changed height
+  if (scrollContainer.value) {
+    scrollContainer.value.scrollTop = scrollContainer.value.scrollHeight
+  }
+})
+</script>
+```
+
+```javascript
+// GOOD: Conditional check in updated hook
+export default {
+  data() {
+    return {
+      content: '',
+      lastSyncedContent: '',
+    }
+  },
+  updated() {
+    // Only act if specific condition is met
+    if (this.content !== this.lastSyncedContent) {
+      this.syncContent()
+      this.lastSyncedContent = this.content
+    }
+  },
+  methods: {
+    syncContent: debounce(() => {
+      // Sync logic
+    }, 300),
+  },
+}
+```
+
+## Valid Use Cases for Updated Hook
+
+```javascript
+// GOOD: Low-level DOM synchronization
+export default {
+  updated() {
+    // Sync third-party library with Vue's DOM
+    this.thirdPartyWidget.refresh()
+
+    // Update scroll position after content change
+    this.$nextTick(() => {
+      this.maintainScrollPosition()
+    })
+  },
+}
+```
+
+## Prefer Computed Properties for Derived Data
+
+```javascript
+// BAD: Calculating derived data in updated
+export default {
+  data() {
+    return { numbers: [1, 2, 3, 4, 5] }
+  },
+  updated() {
+    this.sum = this.numbers.reduce((a, b) => a + b, 0) // Causes another update!
+  }
+}
+
+// GOOD: Use computed property instead
+export default {
+  data() {
+    return { numbers: [1, 2, 3, 4, 5] }
+  },
+  computed: {
+    sum() {
+      return this.numbers.reduce((a, b) => a + b, 0)
+    }
+  }
+}
+```