thanh-kit 2.5.0 → 2.5.2

package/templates/skills/tanstack/references/tanstack-ai.md

@@ -0,0 +1,97 @@
+# TanStack AI Reference (Alpha)
+
+**Status: Alpha — not production-ready.**
+
+## Setup
+```bash
+npm i @tanstack/ai @tanstack/react-ai
+npm i @tanstack/ai-openai      # or @tanstack/ai-anthropic, @tanstack/ai-google
+```
+
+## Client — useChat
+```tsx
+import { useChat, fetchServerSentEvents } from '@tanstack/react-ai'
+
+function Chat() {
+  const { messages, sendMessage, isLoading } = useChat({
+    connection: fetchServerSentEvents('/api/chat'),
+  })
+
+  return (
+    <div>
+      {messages.map((m) => <div key={m.id}>{m.role}: {m.content}</div>)}
+      <form onSubmit={(e) => {
+        e.preventDefault()
+        sendMessage({ role: 'user', content: inputValue })
+      }}>
+        <input ... />
+        <button disabled={isLoading}>Send</button>
+      </form>
+    </div>
+  )
+}
+```
+
+## Server — chat()
+```ts
+import { chat, toStreamResponse } from '@tanstack/ai'
+import { openaiAdapter } from '@tanstack/ai-openai'
+
+// TanStack Start API route
+import { createAPIFileRoute } from '@tanstack/react-start/api'
+
+export const APIRoute = createAPIFileRoute('/api/chat')({
+  POST: async ({ request }) => {
+    const { messages } = await request.json()
+    const stream = chat({
+      adapter: openaiAdapter,
+      model: 'gpt-4o',
+      messages,
+    })
+    return toStreamResponse(stream)
+  },
+})
+```
+
+## Structured Output
+```ts
+const stream = chat({
+  adapter: openaiAdapter,
+  model: 'gpt-4o',
+  messages,
+  outputSchema: z.object({
+    sentiment: z.enum(['positive', 'negative', 'neutral']),
+    summary: z.string(),
+  }),
+})
+```
+
+## Isomorphic Tools
+```ts
+import { toolDefinition } from '@tanstack/ai'
+
+const weatherTool = toolDefinition('getWeather')
+  .input(z.object({ city: z.string() }))
+  .server(async ({ input }) => {
+    return await fetchWeatherAPI(input.city)
+  })
+  .client(({ result }) => {
+    // Render tool result in UI
+    return <WeatherCard data={result} />
+  })
+```
+
+## Provider Adapters
+| Package | Provider |
+|---------|----------|
+| `@tanstack/ai-openai` | OpenAI |
+| `@tanstack/ai-anthropic` | Anthropic |
+| `@tanstack/ai-google` | Google Gemini |
+| `@tanstack/ai-ollama` | Ollama (local) |
+
+## Key Differences from Vercel AI SDK
+- Isomorphic tools (define once, run server+client) vs split implementation
+- Stronger per-model type safety
+- Framework-agnostic (React, Solid, Preact)
+- Fewer providers currently (~10 vs 25+)
+- Less mature ecosystem

package/templates/skills/tanstack/references/tanstack-form.md

@@ -0,0 +1,125 @@
+# TanStack Form Reference
+
+## Setup
+```bash
+npm i @tanstack/react-form
+npm i @tanstack/zod-form-adapter zod  # optional: Zod validation
+```
+
+## useForm
+```tsx
+const form = useForm({
+  defaultValues: { name: '', email: '', age: 0 },
+  validatorAdapter: zodValidator,  // optional global adapter
+  onSubmit: async ({ value }) => {
+    // value is fully typed: { name: string, email: string, age: number }
+    await api.createUser(value)
+  },
+})
+```
+
+## form.Field
+```tsx
+<form.Field
+  name="email"
+  validators={{
+    onChange: z.string().email('Invalid email'),
+    onBlur: ({ value }) => !value ? 'Required' : undefined,
+    onBlurAsync: async ({ value }) => {
+      const taken = await checkEmailTaken(value)
+      return taken ? 'Email already taken' : undefined
+    },
+    onBlurAsyncDebounceMs: 500,
+  }}
+>
+  {(field) => (
+    <div>
+      <input
+        value={field.state.value}
+        onBlur={field.handleBlur}
+        onChange={(e) => field.handleChange(e.target.value)}
+      />
+      {field.state.meta.errors.map((err) => <p key={err}>{err}</p>)}
+    </div>
+  )}
+</form.Field>
+```
+
+## Validation Events
+| Event | When | Use Case |
+|-------|------|----------|
+| `onChange` | Every keystroke | Format validation |
+| `onBlur` | Field loses focus | Required checks |
+| `onBlurAsync` | Field loses focus | Server-side checks |
+| `onSubmit` | Form submission | Final validation |
+| `onSubmitAsync` | Form submission | Async final validation |
+
+All support Zod schemas or inline functions returning `string | undefined`.
+
+## form.Subscribe — Reactive UI
+```tsx
+<form.Subscribe selector={(s) => [s.canSubmit, s.isSubmitting]}>
+  {([canSubmit, isSubmitting]) => (
+    <button type="submit" disabled={!canSubmit}>
+      {isSubmitting ? 'Saving...' : 'Submit'}
+    </button>
+  )}
+</form.Subscribe>
+```
+
+## Nested & Array Fields
+```tsx
+// Nested object
+<form.Field name="address.city">{...}</form.Field>
+
+// Array field
+<form.Field name="tags" mode="array">
+  {(field) => (
+    <>
+      {field.state.value.map((_, i) => (
+        <form.Field key={i} name={`tags[${i}]`}>
+          {(subField) => <input value={subField.state.value} ... />}
+        </form.Field>
+      ))}
+      <button onClick={() => field.pushValue('')}>Add Tag</button>
+    </>
+  )}
+</form.Field>
+```
+
+## Server-Side Validation (TanStack Start)
+```tsx
+// server
+import { createServerValidate } from '@tanstack/react-form/start'
+const serverValidate = createServerValidate({
+  validatorAdapter: zodValidator,
+  onServerValidate: z.object({ email: z.string().email() }),
+})
+
+// client — merge server errors into form state
+import { mergeForm, useTransform } from '@tanstack/react-form'
+useTransform((state) => mergeForm(state, serverState), [serverState])
+```
+
+## Form State Properties
+| Property | Type | Description |
+|----------|------|-------------|
+| `values` | `T` | Current form values |
+| `errors` | `string[]` | Form-level errors |
+| `canSubmit` | `boolean` | No errors + not submitting |
+| `isSubmitting` | `boolean` | Submission in progress |
+| `isDirty` | `boolean` | Values differ from defaults |
+| `isTouched` | `boolean` | Any field touched |
+| `isValid` | `boolean` | No validation errors |
+
+## Field State Meta
+| Property | Type | Description |
+|----------|------|-------------|
+| `errors` | `string[]` | Field validation errors |
+| `isTouched` | `boolean` | Field was blurred |
+| `isDirty` | `boolean` | Value changed from default |
+
+## Schema Adapters
+- `@tanstack/zod-form-adapter` — Zod
+- `@tanstack/valibot-form-adapter` — Valibot
+- `@tanstack/yup-form-adapter` — Yup (community)

package/templates/skills/tanstack/references/tanstack-start.md

@@ -0,0 +1,100 @@
+# TanStack Start Reference
+
+## CLI Commands
+```bash
+npm create @tanstack/start@latest         # scaffold project
+npm run dev                               # vite dev server
+npm run build                             # production build
+NITRO_PRESET=cloudflare-workers npm run build  # deploy target
+```
+
+## app.config.ts
+```ts
+import { defineConfig } from '@tanstack/react-start/config'
+export default defineConfig({
+  server: { preset: 'node-server' }, // or 'cloudflare-workers', 'vercel', etc.
+  tsr: { autoCodeSplitting: true },
+})
+```
+
+## File-Based Routing Conventions
+| Pattern | Route |
+|---------|-------|
+| `index.tsx` | `/` |
+| `about.tsx` | `/about` |
+| `posts.$postId.tsx` | `/posts/:postId` |
+| `posts_.tsx` | Layout for `/posts/*` |
+| `_layout.tsx` | Pathless layout group |
+| `__root.tsx` | Root layout (required) |
+
+`routeTree.gen.ts` is auto-generated — never edit manually.
+
+## createFileRoute
+```ts
+export const Route = createFileRoute('/posts/$postId')({
+  validateSearch: z.object({ page: z.number().optional() }),
+  loader: async ({ params, context }) => fetchPost(params.postId),
+  pendingComponent: () => <Spinner />,
+  errorComponent: ({ error }) => <ErrorDisplay error={error} />,
+  component: PostComponent,
+})
+```
+
+## createServerFn
+```ts
+const serverFn = createServerFn({ method: 'GET' })
+  .validator(z.object({ id: z.string() }))
+  .middleware([authMiddleware])
+  .handler(async ({ data, context }) => {
+    // context.user available from middleware
+    return db.find(data.id)
+  })
+
+// Call from client or loader:
+const result = await serverFn({ data: { id: '123' } })
+```
+
+## Middleware
+```ts
+import { createMiddleware } from '@tanstack/react-start'
+
+export const authMiddleware = createMiddleware()
+  .server(async ({ next, context }) => {
+    const session = await getSession(context.request)
+    if (!session) throw redirect({ to: '/login' })
+    return next({ context: { user: session.user } })
+  })
+```
+
+Chain: `serverFn.middleware([logger, auth, rateLimit])`
+
+## API Routes
+```ts
+// src/routes/api/health.ts
+import { createAPIFileRoute } from '@tanstack/react-start/api'
+export const APIRoute = createAPIFileRoute('/api/health')({
+  GET: () => new Response(JSON.stringify({ ok: true })),
+  POST: async ({ request }) => {
+    const body = await request.json()
+    return new Response(JSON.stringify(body))
+  },
+})
+```
+
+## SSR Configuration
+Default: client-side SPA. Opt-in SSR per route:
+```ts
+export const Route = createFileRoute('/')({
+  ssr: true,           // enable SSR for this route
+  ssr: { streaming: true }, // enable streaming SSR
+})
+```
+
+## Deploy Targets (Nitro Presets)
+node-server, cloudflare-workers, cloudflare-pages, vercel, netlify, deno, bun, aws-lambda
+
+## Key Packages
+- `@tanstack/react-start` — framework
+- `@tanstack/react-router` — routing (bundled)
+- `@tanstack/react-query` — data fetching (optional but recommended)
+- `vinxi` / `nitro` — server runtime (bundled)

package/templates/skills/team/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: ck:team
+description: "Orchestrate Agent Teams for parallel multi-session collaboration. Use for research, implementation, review, and debug workflows requiring independent teammates."
+version: 2.1.0
+argument-hint: "<template> <context> [--devs|--researchers|--reviewers N] [--delegate]"
+---
+
+# Agent Teams - CK-Native Orchestration Engine
+
+Coordinate multiple independent Claude Code sessions. Each teammate has own context window, loads project context (CLAUDE.md, skills, agents), communicates via shared task list and messaging.
+
+**Requires:** Agent Teams enabled. Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.json env if using Claude Code < 2.1.33. May be GA in 2.1.33+.
+
+## Usage
+
+```
+/team <template> <context> [flags]
+```
+
+**Templates:** `ck:research`, `ck:cook`, `ck:code-review`, `ck:debug`
+
+**Flags:**
+- `--devs N` | `--researchers N` | `--reviewers N` | `--debuggers N` — team size
+- `--plan-approval` / `--no-plan-approval` — plan gate (default: on for cook)
+- `--delegate` — lead only coordinates, never touches code
+
+## Execution Protocol
+
+**Pre-flight (MANDATORY — merged into step 2 of every template):**
+1. Step 2 of every template calls `TeamCreate(team_name: "...", ...)`. Do NOT check whether the tool exists first — just call it.
+2. If the call SUCCEEDS: continue with the template.
+3. If the call returns an ERROR or is unrecognized: **STOP. Tell user:** "Agent Teams requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.json. Team mode is not available."
+4. Do NOT fall back to subagents. `/ck:team` MUST use Agent Teams or abort.
+5. All teammate spawns MUST include `team_name` parameter — never spawn Task without it.
+
+When activated, IMMEDIATELY execute the matching template sequence below.
+Do NOT ask for confirmation. Do NOT explain what you're about to do.
+Execute the tool calls in order. Report progress after each major step.
+
+---
+
+## CK Context Block
+
+Every teammate spawn prompt MUST include this context at the end:
+
+```
+CK Context:
+- Work dir: {CK_PROJECT_ROOT or CWD}
+- Reports: {CK_REPORTS_PATH or "plans/reports/"}
+- Plans: {CK_PLANS_PATH or "plans/"}
+- Branch: {CK_GIT_BRANCH or current branch}
+- Naming: {CK_NAME_PATTERN or "YYMMDD-HHMM"}
+- Active plan: {CK_ACTIVE_PLAN or "none"}
+- Commits: conventional (feat:, fix:, docs:, refactor:, test:, chore:)
+- Refer to teammates by NAME, not agent ID
+```
+
+---
+
+## ON `/ck:team research <topic>` [--researchers N]:
+
+*Wraps /ck:research skill — scope, gather, analyze, report.*
+
+IMMEDIATELY execute in order:
+
+1. **Derive N angles** from `<topic>` (default N=3):
+   - Angle 1: Architecture, patterns, proven approaches
+   - Angle 2: Alternatives, competing solutions, trade-offs
+   - Angle 3: Risks, edge cases, failure modes, security
+   - (If N>3, derive additional angles from topic context)
+
+2. **CALL** `TeamCreate(team_name: "<topic-slug>")`
+
+3. **CALL** `TaskCreate` x N — one per angle:
+   - Subject: `Research: <angle-title>`
+   - Description: `Investigate <angle> for topic: <topic>. Save report to: {CK_REPORTS_PATH}/researcher-{N}-{CK_NAME_PATTERN}-{topic-slug}.md. Format: Executive summary, key findings, evidence, recommendations. Mark task completed when done. Send findings summary to lead.`
+
+4. **CALL** `Task` x N to spawn researcher teammates:
+   - `subagent_type: "researcher"`, `team_name: "<topic-slug>"`, `model: "haiku"`
+   - `name: "researcher-{N}"`
+   - Prompt: task description + CK Context Block
+
+5. **MONITOR** via TaskCompleted hook events + TaskList fallback:
+   - TaskCompleted events auto-notify when researchers finish
+   - Fallback: Check TaskList if no event received in 60s
+   - If stuck >5 min, message teammate directly
+
+6. **READ** all researcher reports from `{CK_REPORTS_PATH}/`
+
+7. **SYNTHESIZE** into: `{CK_REPORTS_PATH}/research-summary-{CK_NAME_PATTERN}-{topic-slug}.md`
+   Format: exec summary, key findings, comparative analysis, recommendations, unresolved questions.
+
+8. **SHUTDOWN**: `SendMessage(type: "shutdown_request")` to each teammate
+
+9. **CLEANUP**: `TeamDelete` (no parameters — just call it)
+
+10. **REPORT**: Tell user `Research complete. Summary: {path}. N reports generated.`
+
+---
+
+## ON `/ck:team cook <plan-path-or-description>` [--devs N]:
+
+*Wraps /ck:cook skill — plan, code, test, review, finalize.*
+
+IMMEDIATELY execute in order:
+
+1. **READ** plan (if path provided) OR create via planner teammate:
+   - If description only: spawn `Task(subagent_type: "planner")` to create plan first
+   - Parse plan into N independent task groups with file ownership boundaries
+
+2. **CALL** `TeamCreate(team_name: "<feature-slug>")`
+
+3. **CALL** `TaskCreate` x (N + 1) — N dev tasks + 1 tester task:
+   - Dev tasks: include `File ownership: <glob patterns>` — NO overlap between devs
+   - Tester task: `addBlockedBy` all dev task IDs
+   - Each task description includes: implementation scope, file ownership, acceptance criteria
+
+4. **CALL** `Task` x N to spawn developer teammates:
+   - `subagent_type: "fullstack-developer"`, `mode: "plan"`
+   - `model: "sonnet"`, `name: "dev-{N}"`
+   - Prompt: task description + CK Context Block
+   - REVIEW and APPROVE each developer's plan via `plan_approval_response`
+
+5. **MONITOR** dev completion via TaskCompleted events:
+   - TaskCompleted hook notifies when each dev task finishes
+   - When all N dev tasks show completed, spawn tester immediately
+   - TeammateIdle events confirm devs are available for shutdown
+   - Fallback: Check TaskList if no events received in 60s
+   - `Task(subagent_type: "tester", model: "haiku", name: "tester")`
+   - Tester runs full test suite, reports pass/fail
+
+6. **DOCS SYNC EVAL** (MANDATORY for cook — from /ck:cook finalize):
+   ```
+   Docs impact: [none|minor|major]
+   Action: [no update needed — <reason>] | [updated <page>] | [needs separate PR]
+   ```
+
+7. **SHUTDOWN** all teammates via `SendMessage(type: "shutdown_request")`
+8. **CLEANUP**: `TeamDelete` (no parameters — just call it)
+
+9. **REPORT**: Tell user what was cooked, test results, docs impact.
+
+---
+
+## ON `/ck:team review <scope>` [--reviewers N]:
+
+*Wraps /ck:code-review skill — scout, review, synthesize with evidence gates.*
+
+IMMEDIATELY execute in order:
+
+1. **DERIVE** N review focuses from `<scope>` (default N=3):
+   - Focus 1: Security — vulnerabilities, auth, input validation, OWASP
+   - Focus 2: Performance — bottlenecks, memory, complexity, scaling
+   - Focus 3: Test coverage — gaps, edge cases, error paths
+   - (If N>3, derive from scope: architecture, DX, accessibility, etc.)
+
+2. **CALL** `TeamCreate(team_name: "review-<scope-slug>")`
+
+3. **CALL** `TaskCreate` x N — one per focus:
+   - Subject: `Review: <focus-title>`
+   - Description: `Review <scope> for <focus>. Output severity-rated findings only. Format: [CRITICAL|IMPORTANT|MODERATE] <finding> — <evidence> — <recommendation>. No "seems" or "probably" — concrete evidence only. Save to: {CK_REPORTS_PATH}/reviewer-{N}-{CK_NAME_PATTERN}-{scope-slug}.md. Mark task completed when done.`
+
+4. **CALL** `Task` x N to spawn reviewers:
+   - `subagent_type: "code-reviewer"`, `model: "haiku"`, `name: "reviewer-{N}"`
+   - Prompt: task description + CK Context Block
+
+5. **MONITOR** via TaskCompleted hook events + TaskList fallback:
+   - TaskCompleted events auto-notify when reviewers finish
+   - Fallback: Check TaskList if no event received in 60s
+
+6. **SYNTHESIZE** into: `{CK_REPORTS_PATH}/review-{scope-slug}.md`
+   - Deduplicate findings across reviewers
+   - Prioritize by severity: CRITICAL > IMPORTANT > MODERATE
+   - Create action items list with owners
+
+7. **SHUTDOWN** all teammates via `SendMessage(type: "shutdown_request")`
+8. **CLEANUP**: `TeamDelete` (no parameters — just call it)
+
+9. **REPORT**: Tell user `Review complete. {X} findings ({Y} critical). Report: {path}.`
+
+---
+
+## ON `/ck:team debug <issue>` [--debuggers N]:
+
+*Wraps /ck:fix skill — root-cause-first, adversarial hypotheses, disprove to converge.*
+
+IMMEDIATELY execute in order:
+
+1. **GENERATE** N competing hypotheses from `<issue>` (default N=3):
+   - Each hypothesis must be independently testable
+   - Each must predict different observable symptoms
+   - Frame as: "If <cause>, then we should see <evidence>"
+
+2. **CALL** `TeamCreate(team_name: "debug-<issue-slug>")`
+
+3. **CALL** `TaskCreate` x N — one per hypothesis:
+   - Subject: `Debug: Test hypothesis — <theory>`
+   - Description: `Investigate hypothesis: <theory>. For issue: <issue>. ADVERSARIAL: actively try to disprove other theories. Message other debuggers to challenge findings. Report evidence FOR and AGAINST your theory. Save findings to: {CK_REPORTS_PATH}/debugger-{N}-{CK_NAME_PATTERN}-{issue-slug}.md. Mark task completed when done.`
+
+4. **CALL** `Task` x N to spawn debugger teammates:
+   - `subagent_type: "debugger"`, `model: "sonnet"`, `name: "debugger-{N}"`
+   - Prompt: task description + CK Context Block
+
+5. **MONITOR** via TaskCompleted events. Debuggers should message each other — let them converge.
+   - TaskCompleted events notify as each hypothesis is tested
+   - TeammateIdle events indicate debugger awaiting peer input
+   - Fallback: Check TaskList if no events in 60s
+
+6. **READ** all debugger reports. Identify surviving theory as root cause.
+
+7. **WRITE** root cause report: `{CK_REPORTS_PATH}/debug-{issue-slug}.md`
+   Format: Root cause, evidence chain, disproven hypotheses, recommended fix.
+
+8. **SHUTDOWN** all teammates via `SendMessage(type: "shutdown_request")`
+9. **CLEANUP**: `TeamDelete` (no parameters — just call it)
+
+10. **REPORT**: Tell user `Debug complete. Root cause: <summary>. Report: {path}.`
+
+---
+
+## Agent Memory
+
+Agents with `memory: project` retain learnings across team sessions. Memory persists in `.claude/agent-memory/<name>/` (gitignored). Useful for:
+- Code reviewer remembering project conventions
+- Debugger recalling past failure patterns
+- Tester tracking flaky tests and coverage gaps
+
+---
+
+## Agent Memory
+
+Agents with `memory: project` retain learnings across team sessions. Memory persists in `.claude/agent-memory/<name>/` (gitignored). Useful for:
+- Code reviewer remembering project conventions
+- Debugger recalling past failure patterns
+- Tester tracking flaky tests and coverage gaps
+
+---
+
+## When to Use Agent Teams vs Subagents
+
+| Scenario | Subagents (Task tool) | Agent Teams |
+|----------|----------------------|-------------|
+| Focused task (test, lint, single review) | **Yes** | Overkill |
+| Sequential chain (plan → code → test) | **Yes** | No |
+| 3+ independent parallel workstreams | Maybe | **Yes** |
+| Competing debug hypotheses | No | **Yes** |
+| Cross-layer work (FE + BE + tests) | Maybe | **Yes** |
+| Workers need to discuss/challenge findings | No | **Yes** |
+| Token budget is tight | **Yes** | No (high cost) |
+
+## Token Budget
+
+| Template | Estimated Tokens | Model Strategy |
+|----------|-----------------|----------------|
+| Research (3) | ~150K-300K | haiku for all |
+| Cook (4) | ~400K-800K | sonnet for devs, haiku for tester |
+| Review (3) | ~100K-200K | haiku for all |
+| Debug (3) | ~200K-400K | sonnet for all |
+
+## Error Recovery
+
+1. **Check status**: `Shift+Up/Down` (in-process) or click pane (split)
+2. **Redirect**: Send direct message with corrective instructions
+3. **Replace**: Shut down failed teammate, spawn replacement for same task
+4. **Reassign**: `TaskUpdate` stuck task to unblock dependents
+
+## Abort Team
+
+```
+Shut down all teammates. Then call TeamDelete (no parameters).
+```
+
+If unresponsive: close terminal or kill session. Clean orphaned configs at `~/.claude/teams/` manually.
+
+## Display Modes
+
+- **auto** (default): split panes if in tmux, otherwise in-process
+- **in-process**: all in one terminal. `Shift+Up/Down` navigate. `Ctrl+T` task list.
+- **tmux/split**: each teammate own pane. Requires tmux or iTerm2.
+
+## Rules Reference
+
+See `.claude/rules/team-coordination-rules.md` for teammate behavior rules.
+
+> v2.1.0: Event-driven orchestration via TaskCompleted/TeammateIdle hooks. Agent memory + Task restrictions.