code-quest

cc-office project overview — current phase (Claude Code web client with protocol alignment to the VS Code extension) plus the long-term RPG roadmap (Code Quest). Use when asking what this project does, planning architecture, understanding which features are built vs planned, or framing new features.

Code Quest project-specific code review checks covering import order, zod schema placement, cross-package event-name alignment, server handler middleware, channel / emitter semantics, client handler organization, React Compiler compatibility, icon facade convention, and FakeSummoner test patterns. Pairs with generic `code-review` skill. Use when reviewing Code Quest code, discussing refactor, checking a PR for protocol/handler/zod alignment, or verifying that recent changes match project conventions.

Project-specific Vitest testing reference for the **server** package (apps/server). Use when writing or modifying server-side vitest tests, fixing failing tests, testing DB / socket.io server-side, choosing mocking strategies, or working with async patterns and fake timers. For frontend tests (apps/web) see `frontend-testing`.

Inversify dependency injection patterns for the server. Use when creating or modifying DI container bindings, adding injectable services, writing tests with dependency overrides, or managing TYPES symbols.

Tailwind CSS v4 styling with @theme, @utility, and @custom-variant directives. Use when styling components, configuring design tokens, adding custom utilities, migrating from v3, or converting hardcoded colors to theme tokens. Enforces token-first design flow: look up existing @theme tokens before reaching for arbitrary values, and extend @theme when a design exceeds the token range rather than sprinkling ad-hoc `[Npx]` / `[#hex]` values.

Explains Claude Code features, skills, subagents, hooks, MCP, and CLI usage. Use when the user asks questions like "How do I...", "Can Claude...", "What is...". Provides detailed guidance on Claude Code CLI functionality.

Collects real CLI (Claude, Gemini) stream-json output as .jsonl fixture files. Use when adding new fixture scenarios, updating after CLI version changes, or covering new protocol event types.

Drizzle ORM and drizzle-kit patterns for multi-dialect setup (SQLite + MySQL). Use when creating or modifying DB schemas, writing migrations, implementing repositories, adding tables or relations, or writing database tests.

Project lint, format, and git hooks setup using Biome and Lefthook. Use when modifying biome.json, lefthook config, or troubleshooting pre-commit/pre-push hooks.

Environment variable access conventions. All env access goes through centralized config modules (apps/server/src/config.ts, apps/web/src/config.ts). Use when reading process.env, adding new env vars, or modifying config files.

Fixture-driven TDD workflow for CLI parsers and session tests. Uses real CLI JSON from DB/capture, FakeClaude segments, and .jsonl fixtures. Use when developing parsers, adding event types, or writing server pipeline tests.

Frontend data layer patterns with ky, React Query, Zod, and React Hook Form. Use when implementing API calls, building service layers, working with queries or mutations, adding form validation, or configuring error boundaries and toast notifications.

Frontend testing guide for React components, hooks, and stores using testing-library, vitest, and Storybook. Use when writing or refactoring component tests, hook tests, or choosing between test doubles. Covers six core principles (Testing Library first, Fake for external deps, Fake Component for isolation, test placement at smallest meaningful root, preserve-expect refactor discipline, unified fake file naming), query priority, userEvent patterns, and when to use Storybook play functions vs testing-library tests.

CLI stream parser development workflow. Covers the ProtocolEvent → SocketEvent pipeline, Zod schema validation, and adapter pattern. Use when creating or modifying protocol parsers, adding new event types, or debugging parse failures.

Compare cc-office protocol implementation against the real Claude Code VS Code Extension. Use when checking protocol coverage, analyzing alignment gaps, re-comparing after extension updates, or building a coverage matrix.

React Compiler 1.0 的實際行為與邊界 — 哪些 pattern 會被自動 memo（不要手動 useMemo），哪些是架構限制必須手動處理（React.memo / prop capture / DOM refs）。以 babel-plugin-react-compiler 實際編譯結果為依據。用於判斷「這個 pattern 要不要加 useMemo/useCallback/React.memo」、解讀 profiler 結果、或效能除錯。

Socket.IO event handling patterns for server and client. Use when implementing socket handlers, adding real-time events, creating client socket hooks, or modifying handler registration.

Zod v4 schema validation patterns and integration with Drizzle ORM and React Hook Form. Use when creating or modifying Zod schemas, adding validation logic, using zodResolver, or migrating from Zod v3 to v4.

FakeSummoner test harness for **client-side** tests — React component/context/hook tests that need socket + pipeline. Covers renderWithWorkspace, renderWithChannel, multi-tab scenarios, state injection vs full pipeline. For server tests see `fake-summoner-server` skill.

FakeSummoner test harness for **server-side** tests — socket handlers, channel integration, pipeline, DB, CLI process. Use when writing or debugging server tests that need real socket.io + in-memory DB + fake CLI process. For client tests see `fake-summoner-client` skill.

Cross-cutting testing conventions (async patterns, vitest API cheatsheet, className assertion) shared across client and server tests. Frontend-specific rules (6 core principles, test double decision flow, Fake Component, test placement) live in `frontend-testing`; server-specific patterns (DB / socket.io server) live in `vitest-testing (server)`. Use for general test hygiene not tied to a specific package.

React hooks and Context conventions for this project. Covers custom hook extraction rules, Context splitting (state vs actions), dependency management with biome useExhaustiveDependencies, and ref/callback patterns. Use when writing or reviewing custom hooks, Context providers, or component re-render optimization.

Roadmap (not yet implemented). Code Quest RPG vision for cc-office — CodeLand world, 11 systems, HP/MP/EXP/Gold mechanics, battle-trigger rules, pixel-art visual style. Use when designing future RPG features, discussing long-term direction, or reading legacy docs under `docs/ui-design/`. Current architecture: see `project-overview`.

cc-office TDD workflow — Red-Green-Refactor cycle, expect-immutability rule during refactor, test pyramid, naming (AAA), and refactor discipline. Use when writing new code, refactoring, designing test structure, fixing failing tests in a principled way, or onboarding to this project's TDD conventions. Pairs with generic `tdd` skill and `test-doubles` theory.

**Roadmap — 尚未實作。** Battle management system (Code Quest RPG vision) — AI dispatch, multi-battle handling, worktree-based battle isolation. See `rpg-roadmap` / `project-overview` for framing. Use when designing future combat flow, planning parallel AI battles, or reading legacy design docs.

**Roadmap — 尚未實作。** Dual-mode map system (2D overhead + dialogue mode) and location structure (Code Quest RPG vision). See `rpg-roadmap` / `project-overview` for framing. Use when designing future map/scene features, town/wilderness/dungeon content, or reading legacy design docs.

CLI provider capability differences across Claude, Gemini, and other providers. Use when implementing provider-specific logic, discovering CLI behavioral differences, adding new provider support, or encountering limitations where not all CLIs support the same flags.

Express server patterns with TypeScript, InversifyJS, and Socket.IO. Use when creating or modifying HTTP endpoints, middleware, route handlers, CORS config, graceful shutdown, or writing supertest integration tests.

Reference guide for comparing cc-office UI against the real Claude Code VS Code Extension via live MCP debugmcp inspection. Use when building or redesigning UI components, aligning visuals with the extension, creating OpenSpec changes for UI alignment, or unsure what the extension renders for a given element.

MSW v2 patterns for API mocking in Vitest tests. Use when setting up API mocks, writing HTTP handlers, simulating network errors, or configuring msw/node for component and integration tests.

Component-driven development with Storybook 10. Use when creating or documenting React components, writing stories or interaction tests, designing UI variations, or syncing stories after component changes.

Zustand state management patterns including stores, slices, selectors, and middleware. Use when creating or modifying zustand stores, optimizing re-renders, integrating socket events with state, or testing stores.

PTY-based multi-session architecture for Code Quest. Covers three-layer design, node-pty spawn config, and worktree isolation. Use when implementing or modifying session management, PTY spawning, or terminal integration.