@assistkick/create 1.7.0 → 1.9.0

package/templates/assistkick-product-system/tests/workflow_integration.test.ts

@@ -0,0 +1,341 @@
+/**
+ * Tests for Kanban Workflow Integration — dependency ordering,
+ * status mapping, and default workflow resolution logic.
+ * Uses node:test built-in runner.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+/**
+ * Dependency-checking logic matching WorkflowOrchestrator.runLoop.
+ * Tests the pure data transformation.
+ */
+const checkDeps = (featureId: string, graphData: any, kanbanData: any): boolean => {
+  const deps = graphData.edges
+    .filter((e: any) => e.from === featureId && e.relation === 'depends_on')
+    .map((e: any) => e.to)
+    .filter((depId: string) => graphData.nodes.some((n: any) => n.id === depId && n.type === 'feature'));
+  return deps.some((depId: string) =>
+    !kanbanData[depId] || kanbanData[depId].column !== 'done'
+  );
+};
+
+/**
+ * Simulates the Play All ordering: find next processable feature using
+ * the workflow orchestrator's dependency checking logic.
+ */
+const findNextProcessable = (
+  todoCards: { id: string; devBlocked: boolean }[],
+  graphData: any,
+  kanbanData: any,
+) => {
+  for (const card of todoCards) {
+    if (card.devBlocked) continue;
+    if (!checkDeps(card.id, graphData, kanbanData)) return card;
+  }
+  return null;
+};
+
+/**
+ * Maps workflow status to display label, matching the frontend
+ * WORKFLOW_STATUS_LABELS constant.
+ */
+const WORKFLOW_STATUS_LABELS: Record<string, string> = {
+  running: 'Running',
+  completed: 'Completed',
+  failed: 'Failed',
+  idle: 'Idle',
+};
+
+/**
+ * Default workflow resolution logic — project-specific first, then global.
+ */
+const resolveDefault = (
+  workflows: { id: string; projectId: string | null; isDefault: number }[],
+  projectId?: string,
+) => {
+  if (projectId) {
+    const projectDefault = workflows.find(
+      w => w.projectId === projectId && w.isDefault === 1,
+    );
+    if (projectDefault) return projectDefault;
+  }
+  // Fall back to global default
+  return workflows.find(w => w.projectId === null && w.isDefault === 1) || null;
+};
+
+describe('WorkflowOrchestrator dependency ordering', () => {
+  it('unblocked when all deps are done', () => {
+    const graphData = {
+      nodes: [
+        { id: 'feat_001', type: 'feature' },
+        { id: 'feat_002', type: 'feature' },
+      ],
+      edges: [{ from: 'feat_001', to: 'feat_002', relation: 'depends_on' }],
+    };
+    const kanbanData = {
+      feat_001: { column: 'todo' },
+      feat_002: { column: 'done' },
+    };
+    assert.equal(checkDeps('feat_001', graphData, kanbanData), false);
+  });
+
+  it('blocked when a dep is not done', () => {
+    const graphData = {
+      nodes: [
+        { id: 'feat_001', type: 'feature' },
+        { id: 'feat_002', type: 'feature' },
+      ],
+      edges: [{ from: 'feat_001', to: 'feat_002', relation: 'depends_on' }],
+    };
+    const kanbanData = {
+      feat_001: { column: 'todo' },
+      feat_002: { column: 'in_progress' },
+    };
+    assert.equal(checkDeps('feat_001', graphData, kanbanData), true);
+  });
+
+  it('unblocked when no depends_on edges', () => {
+    const graphData = {
+      nodes: [{ id: 'feat_001', type: 'feature' }],
+      edges: [],
+    };
+    const kanbanData = { feat_001: { column: 'todo' } };
+    assert.equal(checkDeps('feat_001', graphData, kanbanData), false);
+  });
+
+  it('ignores non-feature dependency targets', () => {
+    const graphData = {
+      nodes: [
+        { id: 'feat_001', type: 'feature' },
+        { id: 'comp_001', type: 'component' },
+      ],
+      edges: [{ from: 'feat_001', to: 'comp_001', relation: 'depends_on' }],
+    };
+    const kanbanData = { feat_001: { column: 'todo' } };
+    assert.equal(checkDeps('feat_001', graphData, kanbanData), false);
+  });
+
+  it('ignores non-depends_on relations', () => {
+    const graphData = {
+      nodes: [
+        { id: 'feat_001', type: 'feature' },
+        { id: 'feat_002', type: 'feature' },
+      ],
+      edges: [{ from: 'feat_001', to: 'feat_002', relation: 'relates_to' }],
+    };
+    const kanbanData = {
+      feat_001: { column: 'todo' },
+      feat_002: { column: 'todo' },
+    };
+    assert.equal(checkDeps('feat_001', graphData, kanbanData), false);
+  });
+});
+
+describe('findNextProcessable', () => {
+  const graphData = {
+    nodes: [
+      { id: 'feat_001', type: 'feature' },
+      { id: 'feat_002', type: 'feature' },
+      { id: 'feat_003', type: 'feature' },
+    ],
+    edges: [
+      { from: 'feat_002', to: 'feat_001', relation: 'depends_on' },
+    ],
+  };
+
+  it('returns first unblocked feature', () => {
+    const kanbanData = {
+      feat_001: { column: 'todo' },
+      feat_002: { column: 'todo' },
+    };
+    const cards = [
+      { id: 'feat_001', devBlocked: false },
+      { id: 'feat_002', devBlocked: false },
+    ];
+
+    const next = findNextProcessable(cards, graphData, kanbanData);
+    assert.equal(next!.id, 'feat_001');
+  });
+
+  it('skips features with unmet dependencies', () => {
+    const kanbanData = {
+      feat_001: { column: 'todo' },
+      feat_002: { column: 'todo' },
+      feat_003: { column: 'todo' },
+    };
+    const cards = [
+      { id: 'feat_002', devBlocked: false }, // depends on feat_001 in todo
+      { id: 'feat_001', devBlocked: false }, // no deps
+      { id: 'feat_003', devBlocked: false }, // no deps
+    ];
+
+    const next = findNextProcessable(cards, graphData, kanbanData);
+    assert.equal(next!.id, 'feat_001');
+  });
+
+  it('skips devBlocked features', () => {
+    const kanbanData = {
+      feat_001: { column: 'todo' },
+      feat_003: { column: 'todo' },
+    };
+    const cards = [
+      { id: 'feat_001', devBlocked: true },
+      { id: 'feat_003', devBlocked: false },
+    ];
+
+    const next = findNextProcessable(cards, graphData, kanbanData);
+    assert.equal(next!.id, 'feat_003');
+  });
+
+  it('returns null when all features are blocked', () => {
+    const kanbanData = {
+      feat_002: { column: 'todo' },
+    };
+    const cards = [
+      { id: 'feat_002', devBlocked: false }, // depends on feat_001 not done
+    ];
+
+    const next = findNextProcessable(cards, graphData, kanbanData);
+    assert.equal(next, null);
+  });
+});
+
+describe('Workflow status labels', () => {
+  it('maps running to Running', () => {
+    assert.equal(WORKFLOW_STATUS_LABELS['running'], 'Running');
+  });
+
+  it('maps completed to Completed', () => {
+    assert.equal(WORKFLOW_STATUS_LABELS['completed'], 'Completed');
+  });
+
+  it('maps failed to Failed', () => {
+    assert.equal(WORKFLOW_STATUS_LABELS['failed'], 'Failed');
+  });
+
+  it('maps idle to Idle', () => {
+    assert.equal(WORKFLOW_STATUS_LABELS['idle'], 'Idle');
+  });
+});
+
+describe('Workflow status resolution', () => {
+  it('running status with agent name indicates active agent node', () => {
+    const status = { status: 'running', currentAgentName: 'Developer', error: null };
+    assert.equal(status.status, 'running');
+    assert.equal(status.currentAgentName, 'Developer');
+    assert.equal(status.error, null);
+  });
+
+  it('running status without agent name indicates non-agent node', () => {
+    const status = { status: 'running', currentAgentName: null, error: null };
+    assert.equal(status.currentAgentName, null);
+  });
+
+  it('failed status includes error message', () => {
+    const status = { status: 'failed', currentAgentName: null, error: 'Agent crashed' };
+    assert.equal(status.status, 'failed');
+    assert.equal(status.error, 'Agent crashed');
+  });
+
+  it('idle status when no execution exists', () => {
+    const status = { status: 'idle', featureId: 'feat_001' };
+    assert.equal(status.status, 'idle');
+  });
+
+  it('completed status has no error', () => {
+    const status = { status: 'completed', error: null };
+    assert.equal(status.status, 'completed');
+    assert.equal(status.error, null);
+  });
+});
+
+describe('Default workflow resolution', () => {
+  const workflows = [
+    { id: 'wf-global', projectId: null, isDefault: 1 },
+    { id: 'wf-proj-1', projectId: 'proj_001', isDefault: 1 },
+    { id: 'wf-proj-2', projectId: 'proj_001', isDefault: 0 },
+    { id: 'wf-other', projectId: 'proj_002', isDefault: 1 },
+  ];
+
+  it('resolves project-specific default when available', () => {
+    const result = resolveDefault(workflows, 'proj_001');
+    assert.equal(result!.id, 'wf-proj-1');
+  });
+
+  it('falls back to global default when no project default', () => {
+    const result = resolveDefault(workflows, 'proj_999');
+    assert.equal(result!.id, 'wf-global');
+  });
+
+  it('uses global default when no projectId provided', () => {
+    const result = resolveDefault(workflows);
+    assert.equal(result!.id, 'wf-global');
+  });
+
+  it('returns null when no default exists', () => {
+    const noDefaults = [
+      { id: 'wf-1', projectId: null, isDefault: 0 },
+    ];
+    const result = resolveDefault(noDefaults);
+    assert.equal(result, null);
+  });
+
+  it('prefers project-specific over global', () => {
+    const result = resolveDefault(workflows, 'proj_002');
+    assert.equal(result!.id, 'wf-other');
+    assert.equal(result!.projectId, 'proj_002');
+  });
+});
+
+describe('Resume button visibility logic', () => {
+  it('shows resume for failed workflow on in_progress card', () => {
+    const card = { column: 'in_progress' };
+    const workflowStatus = 'failed';
+    const isActive = workflowStatus === 'running';
+    const showResume = ['in_progress', 'in_review'].includes(card.column)
+      && !isActive
+      && workflowStatus === 'failed';
+    assert.equal(showResume, true);
+  });
+
+  it('shows resume for failed workflow on in_review card', () => {
+    const card = { column: 'in_review' };
+    const workflowStatus = 'failed';
+    const isActive = workflowStatus === 'running';
+    const showResume = ['in_progress', 'in_review'].includes(card.column)
+      && !isActive
+      && workflowStatus === 'failed';
+    assert.equal(showResume, true);
+  });
+
+  it('hides resume for running workflow', () => {
+    const card = { column: 'in_progress' };
+    const workflowStatus = 'running';
+    const isActive = workflowStatus === 'running';
+    const showResume = ['in_progress', 'in_review'].includes(card.column)
+      && !isActive
+      && workflowStatus === 'failed';
+    assert.equal(showResume, false);
+  });
+
+  it('hides resume for todo card', () => {
+    const card = { column: 'todo' };
+    const workflowStatus = 'failed';
+    const isActive = workflowStatus === 'running';
+    const showResume = ['in_progress', 'in_review'].includes(card.column)
+      && !isActive
+      && workflowStatus === 'failed';
+    assert.equal(showResume, false);
+  });
+
+  it('hides resume for completed workflow', () => {
+    const card = { column: 'in_progress' };
+    const workflowStatus = 'completed';
+    const isActive = workflowStatus === 'running';
+    const showResume = ['in_progress', 'in_review'].includes(card.column)
+      && !isActive
+      && workflowStatus === 'failed';
+    assert.equal(showResume, false);
+  });
+});

package/templates/skills/assistkick-developer/SKILL.md

@@ -13,6 +13,9 @@ with the project spec and kanban exclusively through the tools below.
 
 All tools live in `assistkick-product-system/packages/shared/tools/` and are run with `npx tsx`.
 
+## References
+- For React development best practices, see [react_development_guidelines.md](references/react_development_guidelines.md)
+
 ## Session Start Protocol
 1. Call `get_status` — understand current project state
 2. Call `get_kanban --column todo` — identify which features are available to implement

package/templates/skills/assistkick-developer/references/react_development_guidelines.md

@@ -0,0 +1,225 @@
+# React Development Guidelines (2026)
+
+## Core Principles
+
+### Use React 19+ Features
+- **React Compiler** is the default — do not manually wrap in `useMemo`, `useCallback`, or `React.memo` unless profiling shows a specific need. The compiler handles memoization automatically.
+- **Server Components** are the default rendering model. Only add `'use client'` when the component needs interactivity (event handlers, state, effects, browser APIs).
+- **Server Actions** (`'use server'`) for mutations — prefer over custom API routes for form submissions and data mutations.
+- **`use()` hook** for reading promises and context inside render. Replaces many patterns that previously required `useEffect` + `useState`.
+- **`useActionState`** for form state management — replaces the old `useFormState` pattern.
+- **`useOptimistic`** for optimistic UI updates during async transitions.
+- **`<form action={...}>`** — use the action prop on forms for progressive enhancement.
+
+### Component Design
+- **One component per file** — every component lives in its own file. No exceptions. If you need a helper component, extract it to a separate file.
+- **Never define a component inside another component** — nested component definitions cause remounts on every render and destroy state. Extract inner components to their own files and import them.
+- **Function components only** — never use class components.
+- **Arrow function exports** — `export const MyComponent = () => { ... }`.
+- **Props destructuring** in the parameter list — `({ title, onClose }) => ...`.
+- **Co-locate related code** — keep component, types, and styles in the same directory.
+- **Single responsibility** — one component does one thing. Extract when a component exceeds ~100 lines or has multiple concerns.
+- **Composition over configuration** — prefer children and render props over deeply nested prop objects.
+- **Always check the design system first** — before creating any new component, check if a matching component already exists in the project's design system. Reuse and extend existing design system components rather than building from scratch.
+
+### State Management
+- **Local state first** — `useState` for component-scoped state.
+- **Zustand** for shared client state — lightweight, no boilerplate, works well with React 19.
+  - One store per domain concern (e.g., `useAuthStore`, `useUIStore`).
+  - Use selectors to subscribe to specific slices: `useStore(state => state.count)`.
+  - Keep stores flat — avoid deeply nested state objects.
+  - Use `immer` middleware only when state updates are genuinely complex.
+- **Do not use** `useReducer` for complex state — Zustand stores are simpler and more testable.
+- **URL state** for filters, pagination, search — use `useSearchParams` or the router.
+- **Server state** — use the framework's data loading (Server Components, loaders) rather than client-side fetching libraries when possible.
+
+### Data Fetching
+- **Server Components** for initial data loading — fetch directly in the component, no `useEffect`.
+- **Server Actions** for mutations — define with `'use server'`, call from client components.
+- **`use()` hook** to unwrap promises passed from Server Components to Client Components.
+- **Avoid `useEffect` for fetching** — it causes waterfalls, race conditions, and no caching. Use the framework's data loading primitives instead.
+- **When client-side fetching is needed** (real-time, user-triggered), use `fetch` + `use()` or a minimal wrapper. Keep it simple.
+
+### Hooks
+- **Custom hooks** for reusable logic — prefix with `use`, keep them focused on one concern.
+- **`useRef`** for DOM references and mutable values that don't trigger re-renders.
+- **`useEffect`** only for synchronization with external systems (DOM manipulation, subscriptions, timers). Never for data fetching or derived state.
+- **`useId`** for generating unique IDs for accessibility attributes.
+- **No `useEffect` chains** — if one effect sets state that triggers another effect, restructure the logic.
+
+### Styling — Tailwind CSS v4 Migration
+- **All new components must use Tailwind CSS v4 classes** — do not create new `.css` files or add new CSS rules to existing stylesheets.
+- **Migrate existing CSS when touching a component** — if you modify a component that uses CSS, convert its styles to Tailwind classes as part of the same change.
+- **Use Tailwind utilities directly in JSX** — `className="flex items-center gap-2 p-4 rounded-lg bg-white"`.
+- **Use `@apply` sparingly** — only when a utility combination is repeated across many elements in the same component and extraction to a shared component isn't practical.
+- **Design tokens via Tailwind theme** — use theme values (`text-primary`, `bg-surface`) rather than hardcoded hex colors.
+
+### TypeScript
+- **Strict mode always** — `strict: true` in tsconfig.
+- **Interface for component props** — `interface Props { ... }` defined above the component.
+- **Avoid `any`** — use `unknown` and narrow, or define proper types.
+- **Infer when possible** — don't annotate what TypeScript can infer (return types, simple variables).
+- **Discriminated unions** for variant props — not boolean flags.
+- **`satisfies`** operator for type-safe object literals while preserving inference.
+- **Generic components** when the component works with multiple data shapes.
+
+## Patterns
+
+### File & Directory Structure
+```
+src/
+  components/         # Shared UI components
+    button/
+      button.tsx
+      button.test.tsx
+  features/           # Feature-specific modules
+    auth/
+      components/
+      hooks/
+      stores/
+      actions/
+  lib/                # Utilities and helpers
+  types/              # Shared type definitions
+```
+
+### Component File Structure
+```tsx
+// 1. Imports
+import { useState } from 'react'
+import { Button } from '@/components/button/button'
+
+// 2. Types
+interface Props {
+  title: string
+  onClose: () => void
+}
+
+// 3. Component
+export const Dialog = ({ title, onClose }: Props) => {
+  const [isOpen, setIsOpen] = useState(false)
+
+  return (
+    <div role="dialog" aria-label={title}>
+      <h2>{title}</h2>
+      <Button onClick={onClose}>Close</Button>
+    </div>
+  )
+}
+```
+
+### Zustand Store Pattern
+```tsx
+import { create } from 'zustand'
+
+interface AuthState {
+  user: User | null
+  isLoading: boolean
+  login: (credentials: Credentials) => Promise<void>
+  logout: () => void
+}
+
+export const useAuthStore = create<AuthState>((set) => ({
+  user: null,
+  isLoading: false,
+  login: async (credentials) => {
+    set({ isLoading: true })
+    const user = await authApi.login(credentials)
+    set({ user, isLoading: false })
+  },
+  logout: () => set({ user: null }),
+}))
+
+// Usage — always use selectors
+const user = useAuthStore((s) => s.user)
+```
+
+### Server Component + Client Component Split
+```tsx
+// page.tsx (Server Component — no 'use client')
+import { db } from '@/lib/db'
+import { ItemList } from './item_list'
+
+export const Page = async () => {
+  const items = await db.query.items.findMany()
+  return <ItemList items={items} />
+}
+
+// item_list.tsx (Client Component — needs interactivity)
+'use client'
+import { useState } from 'react'
+
+interface Props {
+  items: Item[]
+}
+
+export const ItemList = ({ items }: Props) => {
+  const [filter, setFilter] = useState('')
+  const filtered = items.filter((i) => i.name.includes(filter))
+
+  return (
+    <div>
+      <input value={filter} onChange={(e) => setFilter(e.target.value)} />
+      {filtered.map((item) => <div key={item.id}>{item.name}</div>)}
+    </div>
+  )
+}
+```
+
+### Form with Server Action
+```tsx
+// actions.ts
+'use server'
+import { db } from '@/lib/db'
+
+export const createItem = async (formData: FormData) => {
+  const name = formData.get('name') as string
+  await db.insert(items).values({ name })
+}
+
+// form.tsx
+'use client'
+import { useActionState } from 'react'
+import { createItem } from './actions'
+
+export const CreateItemForm = () => {
+  const [state, action, isPending] = useActionState(createItem, null)
+
+  return (
+    <form action={action}>
+      <input name="name" required />
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create'}
+      </button>
+    </form>
+  )
+}
+```
+
+## Anti-Patterns to Avoid
+
+- **No `useEffect` for derived state** — compute during render instead.
+- **No prop drilling beyond 2 levels** — use Zustand or composition.
+- **No `index` as `key`** in dynamic lists — use stable unique IDs.
+- **No barrel files** (`index.ts` re-exports) — they break tree-shaking and slow builds.
+- **No default exports** — use named exports for better refactoring and imports.
+- **No `React.FC`** — just type the props directly, it's simpler and more flexible.
+- **No manual memoization** unless the React Compiler is explicitly disabled and profiling shows a need.
+- **No `useEffect` + `setState` for data fetching** — use Server Components or the framework's data loading.
+- **No new CSS files** — we are incrementally migrating from CSS to Tailwind CSS v4. All new components must use Tailwind classes exclusively. When touching existing components that use CSS, migrate their styles to Tailwind as part of the change.
+- **No `any` type** — use `unknown` and narrow, or define the actual type.
+
+## Accessibility Baseline
+- Every interactive element is keyboard accessible.
+- Images have `alt` text; decorative images use `alt=""`.
+- Form inputs have associated `<label>` elements.
+- Use semantic HTML (`<nav>`, `<main>`, `<article>`, `<button>`) — not `div` with `onClick`.
+- Color is never the sole indicator of state.
+- Use `useId()` for dynamic `id`/`aria-*` attributes.
+
+## Performance
+- **React Compiler handles memoization** — trust it, don't fight it.
+- **Lazy load routes and heavy components** — `React.lazy()` + `Suspense`.
+- **Virtualize long lists** — use `@tanstack/react-virtual` for lists > 100 items.
+- **Avoid layout thrashing** — batch DOM reads/writes, use `useLayoutEffect` only when needed.
+- **Image optimization** — use the framework's `<Image>` component or `loading="lazy"`.
+- **Code split at the route level** — each route loads only what it needs.