aigroup-workflow 2.1.1 → 2.2.0

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

@@ -1,167 +0,0 @@
----
-name: vue-expert-js
-description: Creates Vue 3 components, builds vanilla JS composables, configures Vite projects, and sets up routing and state management using JavaScript only — no TypeScript. Generates JSDoc-typed code with @typedef, @param, and @returns annotations for full type coverage without a TS compiler. Use when building Vue 3 applications with JavaScript only (no TypeScript), when projects require JSDoc-based type hints, when migrating from Vue 2 Options API to Composition API in JS, or when teams prefer vanilla JavaScript, .mjs modules, or need quick prototypes without TypeScript setup.
-license: MIT
-metadata:
-  author: https://github.com/Jeffallan
-  version: "1.1.0"
-  domain: frontend
-  triggers: Vue JavaScript, Vue without TypeScript, Vue JSDoc, Vue JS only, Vue vanilla JavaScript, .mjs Vue, Vue no TS
-  role: specialist
-  scope: implementation
-  output-format: code
-  related-skills: vue-expert, javascript-pro
----
-
-# Vue Expert (JavaScript)
-
-Senior Vue specialist building Vue 3 applications with JavaScript and JSDoc typing instead of TypeScript.
-
-## Core Workflow
-
-1. **Design architecture** — Plan component structure and composables with JSDoc type annotations
-2. **Implement** — Build with `<script setup>` (no `lang="ts"`), `.mjs` modules where needed
-3. **Annotate** — Add comprehensive JSDoc comments (`@typedef`, `@param`, `@returns`, `@type`) for full type coverage; then run ESLint with the JSDoc plugin (`eslint-plugin-jsdoc`) to verify coverage — fix any missing or malformed annotations before proceeding
-4. **Test** — Verify with Vitest using JavaScript files; confirm JSDoc coverage on all public APIs; if tests fail, revisit the relevant composable or component, correct the logic or annotation, and re-run until the suite is green
-
-## Reference Guide
-
-Load detailed guidance based on context:
-
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| JSDoc Typing | `references/jsdoc-typing.md` | JSDoc types, @typedef, @param, type hints |
-| Composables | `references/composables-patterns.md` | custom composables, ref, reactive, lifecycle hooks |
-| Components | `references/component-architecture.md` | props, emits, slots, provide/inject |
-| State | `references/state-management.md` | Pinia, stores, reactive state |
-| Testing | `references/testing-patterns.md` | Vitest, component testing, mocking |
-
-**For shared Vue concepts, defer to vue-expert:**
-- `vue-expert/references/composition-api.md` - Core reactivity patterns
-- `vue-expert/references/components.md` - Props, emits, slots
-- `vue-expert/references/state-management.md` - Pinia stores
-
-## Code Patterns
-
-### Component with JSDoc-typed props and emits
-
-```vue
-<script setup>
-/**
- * @typedef {Object} UserCardProps
- * @property {string} name - Display name of the user
- * @property {number} age - User's age
- * @property {boolean} [isAdmin=false] - Whether the user has admin rights
- */
-
-/** @type {UserCardProps} */
-const props = defineProps({
-  name:    { type: String,  required: true },
-  age:     { type: Number,  required: true },
-  isAdmin: { type: Boolean, default: false },
-})
-
-/**
- * @typedef {Object} UserCardEmits
- * @property {(id: string) => void} select - Emitted when the card is selected
- */
-const emit = defineEmits(['select'])
-
-/** @param {string} id */
-function handleSelect(id) {
-  emit('select', id)
-}
-</script>
-
-<template>
-  <div @click="handleSelect(props.name)">
-    {{ props.name }} ({{ props.age }})
-  </div>
-</template>
-```
-
-### Composable with @typedef, @param, and @returns
-
-```js
-// composables/useCounter.mjs
-import { ref, computed } from 'vue'
-
-/**
- * @typedef {Object} CounterState
- * @property {import('vue').Ref<number>} count - Reactive count value
- * @property {import('vue').ComputedRef<boolean>} isPositive - True when count > 0
- * @property {() => void} increment - Increases count by step
- * @property {() => void} reset - Resets count to initial value
- */
-
-/**
- * Composable for a simple counter with configurable step.
- * @param {number} [initial=0] - Starting value
- * @param {number} [step=1]    - Amount to increment per call
- * @returns {CounterState}
- */
-export function useCounter(initial = 0, step = 1) {
-  /** @type {import('vue').Ref<number>} */
-  const count = ref(initial)
-
-  const isPositive = computed(() => count.value > 0)
-
-  function increment() {
-    count.value += step
-  }
-
-  function reset() {
-    count.value = initial
-  }
-
-  return { count, isPositive, increment, reset }
-}
-```
-
-### @typedef for a complex object used across files
-
-```js
-// types/user.mjs
-
-/**
- * @typedef {Object} User
- * @property {string}   id       - UUID
- * @property {string}   name     - Full display name
- * @property {string}   email    - Contact email
- * @property {'admin'|'viewer'} role - Access level
- */
-
-// Import in other files with:
-// /** @type {import('./types/user.mjs').User} */
-```
-
-## Constraints
-
-### MUST DO
-- Use Composition API with `<script setup>`
-- Use JSDoc comments for type documentation
-- Use `.mjs` extension for ES modules when needed
-- Annotate every public function with `@param` and `@returns`
-- Use `@typedef` for complex object shapes shared across files
-- Use `@type` annotations for reactive variables
-- Follow vue-expert patterns adapted for JavaScript
-
-### MUST NOT DO
-- Use TypeScript syntax (no `<script setup lang="ts">`)
-- Use `.ts` file extensions
-- Skip JSDoc types for public APIs
-- Use CommonJS `require()` in Vue files
-- Ignore type safety entirely
-- Mix TypeScript files with JavaScript in the same component
-
-## Output Templates
-
-When implementing Vue features in JavaScript:
-1. Component file with `<script setup>` (no lang attribute) and JSDoc-typed props/emits
-2. `@typedef` definitions for complex prop or state shapes
-3. Composable with `@param` and `@returns` annotations
-4. Brief note on type coverage
-
-## Knowledge Reference
-
-Vue 3 Composition API, JSDoc, ESM modules, Pinia, Vue Router 4, Vite, VueUse, Vitest, Vue Test Utils, JavaScript ES2022+

package/skills/vue-expert-js/references/component-architecture.md

@@ -1,219 +0,0 @@
-# Component Architecture
-
----
-
-## Props
-
-```vue
-<script setup>
-/**
- * @typedef {Object} Props
- * @property {string} title - Required
- * @property {string} [subtitle] - Optional
- * @property {number} [count=0] - With default
- */
-
-const props = defineProps({
-  title: { type: String, required: true },
-  subtitle: { type: String, default: '' },
-  count: { type: Number, default: 0 },
-  // Complex types
-  items: { type: Array, default: () => [] },
-  user: { type: Object, required: true },
-  // Validator
-  size: {
-    type: String,
-    default: 'medium',
-    validator: (v) => ['small', 'medium', 'large'].includes(v)
-  }
-})
-</script>
-```
-
----
-
-## Emits
-
-```vue
-<script setup>
-const emit = defineEmits(['update', 'delete', 'close'])
-
-// With validation
-const emit = defineEmits({
-  /** @param {string} value */
-  update: (value) => typeof value === 'string',
-  /** @param {{ id: number }} payload */
-  delete: (payload) => typeof payload?.id === 'number',
-  close: null
-})
-
-// Usage
-emit('update', 'new value')
-emit('delete', { id: 1 })
-</script>
-```
-
----
-
-## v-model
-
-```vue
-<!-- Single v-model -->
-<script setup>
-const props = defineProps({ modelValue: { type: String, required: true } })
-const emit = defineEmits(['update:modelValue'])
-</script>
-
-<template>
-  <input :value="modelValue" @input="emit('update:modelValue', $event.target.value)" />
-</template>
-```
-
-```vue
-<!-- Multiple v-models: v-model:firstName, v-model:lastName -->
-<script setup>
-defineProps({ firstName: String, lastName: String })
-defineEmits(['update:firstName', 'update:lastName'])
-</script>
-```
-
----
-
-## Slots
-
-```vue
-<!-- Card.vue -->
-<template>
-  <div class="card">
-    <header v-if="$slots.header"><slot name="header" /></header>
-    <div class="card-body"><slot /></div>
-    <footer v-if="$slots.footer"><slot name="footer" /></footer>
-  </div>
-</template>
-```
-
-```vue
-<!-- Scoped slot -->
-<template>
-  <ul>
-    <li v-for="(item, index) in items" :key="item.id">
-      <slot name="item" :item="item" :index="index">
-        {{ item.name }}
-      </slot>
-    </li>
-  </ul>
-</template>
-
-<!-- Usage -->
-<DataList :items="users">
-  <template #item="{ item, index }">
-    {{ index + 1 }}. {{ item.name }}
-  </template>
-</DataList>
-```
-
----
-
-## Provide / Inject
-
-```vue
-<!-- Provider.vue -->
-<script setup>
-import { provide, ref, readonly } from 'vue'
-
-const theme = ref('light')
-provide('theme', readonly(theme))
-provide('setTheme', (t) => { theme.value = t })
-</script>
-```
-
-```vue
-<!-- Consumer.vue -->
-<script setup>
-import { inject, ref } from 'vue'
-
-const theme = inject('theme', ref('light'))
-const setTheme = inject('setTheme', () => {})
-</script>
-```
-
-```javascript
-// Composable pattern
-// composables/useTheme.js
-import { ref, provide, inject, readonly, computed } from 'vue'
-
-const ThemeSymbol = Symbol('theme')
-
-export function provideTheme(initial = 'light') {
-  const theme = ref(initial)
-  const isDark = computed(() => theme.value === 'dark')
-  const toggle = () => { theme.value = theme.value === 'light' ? 'dark' : 'light' }
-
-  provide(ThemeSymbol, { theme: readonly(theme), isDark, toggle })
-  return { theme, isDark, toggle }
-}
-
-export function useTheme() {
-  const ctx = inject(ThemeSymbol)
-  if (!ctx) throw new Error('useTheme requires ThemeProvider')
-  return ctx
-}
-```
-
----
-
-## Dynamic Components
-
-```vue
-<script setup>
-import { shallowRef, markRaw } from 'vue'
-import TabHome from './TabHome.vue'
-import TabProfile from './TabProfile.vue'
-
-const tabs = [
-  { name: 'Home', component: markRaw(TabHome) },
-  { name: 'Profile', component: markRaw(TabProfile) }
-]
-
-const currentTab = shallowRef(tabs[0].component)
-</script>
-
-<template>
-  <button v-for="tab in tabs" :key="tab.name" @click="currentTab = tab.component">
-    {{ tab.name }}
-  </button>
-  <KeepAlive>
-    <component :is="currentTab" />
-  </KeepAlive>
-</template>
-```
-
-```javascript
-// Async component
-import { defineAsyncComponent } from 'vue'
-
-const AsyncModal = defineAsyncComponent({
-  loader: () => import('./Modal.vue'),
-  delay: 200,
-  timeout: 10000
-})
-```
-
----
-
-## Quick Reference
-
-| Feature | Syntax |
-|---------|--------|
-| Required prop | `{ type: String, required: true }` |
-| Default prop | `{ type: Number, default: 0 }` |
-| Array/Object default | `{ type: Array, default: () => [] }` |
-| Emit event | `emit('eventName', payload)` |
-| v-model | `modelValue` prop + `update:modelValue` emit |
-| Named v-model | `v-model:name` → `name` prop + `update:name` emit |
-| Default slot | `<slot />` |
-| Named slot | `<slot name="header" />` → `#header` |
-| Scoped slot | `<slot :item="item" />` → `#default="{ item }"` |
-| Provide | `provide('key', value)` |
-| Inject | `inject('key', defaultValue)` |
-| Dynamic component | `<component :is="comp" />` |

package/skills/vue-expert-js/references/composables-patterns.md

@@ -1,183 +0,0 @@
-# Composables Patterns
-
----
-
-## Basic Composable Structure
-
-```javascript
-// composables/useToggle.js
-import { ref } from 'vue'
-
-/**
- * @typedef {Object} UseToggleReturn
- * @property {import('vue').Ref<boolean>} value
- * @property {() => void} toggle
- */
-
-/**
- * @param {boolean} [initialValue=false]
- * @returns {UseToggleReturn}
- */
-export function useToggle(initialValue = false) {
-  const value = ref(initialValue)
-  const toggle = () => { value.value = !value.value }
-  return { value, toggle }
-}
-```
-
----
-
-## Ref vs Reactive
-
-```javascript
-import { ref, reactive, toRefs, toValue } from 'vue'
-
-// Use ref for: primitives, reassignable values, composable returns
-/** @type {import('vue').Ref<number>} */
-const count = ref(0)
-
-// Use reactive for: complex objects with nested properties
-/** @type {{ email: string, password: string }} */
-const form = reactive({ email: '', password: '' })
-
-// Convert reactive to refs for destructuring
-const { email, password } = toRefs(form)
-
-// Unwrap ref or return plain value
-/** @param {number | import('vue').Ref<number>} maybeRef */
-function double(maybeRef) {
-  return toValue(maybeRef) * 2
-}
-```
-
----
-
-## Lifecycle Hooks
-
-```javascript
-// composables/useEventListener.js
-import { onMounted, onUnmounted, toValue } from 'vue'
-
-/**
- * @template {keyof WindowEventMap} K
- * @param {K} event
- * @param {(ev: WindowEventMap[K]) => void} handler
- * @param {EventTarget | import('vue').Ref<EventTarget>} [target=window]
- */
-export function useEventListener(event, handler, target = window) {
-  onMounted(() => toValue(target).addEventListener(event, handler))
-  onUnmounted(() => toValue(target).removeEventListener(event, handler))
-}
-```
-
-```javascript
-// Lifecycle-aware async (prevents state updates after unmount)
-import { ref, onUnmounted } from 'vue'
-
-export function useAsyncState(fn) {
-  const data = ref(null)
-  const loading = ref(false)
-  let isMounted = true
-
-  onUnmounted(() => { isMounted = false })
-
-  async function execute() {
-    loading.value = true
-    try {
-      const result = await fn()
-      if (isMounted) data.value = result
-    } finally {
-      if (isMounted) loading.value = false
-    }
-  }
-
-  return { data, loading, execute }
-}
-```
-
----
-
-## Shared State (Singleton)
-
-```javascript
-// composables/useNotifications.js
-import { ref, readonly } from 'vue'
-
-// Module-level state = singleton shared across all components
-/** @type {import('vue').Ref<Array<{id: string, message: string}>>} */
-const notifications = ref([])
-
-export function useNotifications() {
-  /** @param {string} message */
-  function notify(message) {
-    const id = Date.now().toString()
-    notifications.value.push({ id, message })
-    setTimeout(() => dismiss(id), 5000)
-  }
-
-  /** @param {string} id */
-  function dismiss(id) {
-    notifications.value = notifications.value.filter(n => n.id !== id)
-  }
-
-  return {
-    notifications: readonly(notifications),
-    notify,
-    dismiss
-  }
-}
-```
-
----
-
-## Async with Cancellation
-
-```javascript
-// composables/useCancellableFetch.js
-import { ref, onUnmounted } from 'vue'
-
-export function useCancellableFetch() {
-  const data = ref(null)
-  const error = ref(null)
-  const loading = ref(false)
-  /** @type {AbortController | null} */
-  let controller = null
-
-  /** @param {string} url */
-  async function execute(url) {
-    controller?.abort()
-    controller = new AbortController()
-    loading.value = true
-    error.value = null
-
-    try {
-      const res = await fetch(url, { signal: controller.signal })
-      data.value = await res.json()
-    } catch (e) {
-      if (/** @type {Error} */ (e).name !== 'AbortError') {
-        error.value = /** @type {Error} */ (e)
-      }
-    } finally {
-      loading.value = false
-    }
-  }
-
-  onUnmounted(() => controller?.abort())
-
-  return { data, error, loading, execute }
-}
-```
-
----
-
-## Quick Reference
-
-| Pattern | Use Case |
-|---------|----------|
-| `ref()` | Primitives, values passed to/from composables |
-| `reactive()` | Objects with nested reactivity |
-| `toRefs()` | Destructure reactive while keeping reactivity |
-| `toValue()` | Unwrap ref or return plain value |
-| Module-level ref | Singleton shared state |
-| Factory function | New instance per component |
-| `onUnmounted` | Cleanup timers, listeners, abort controllers |