create-ai-project 1.23.1 → 1.23.3

package/.claude/skills-en/frontend-typescript-rules/SKILL.md

@@ -5,132 +5,66 @@ description: Applies React/TypeScript type safety, component design, and state m
 
 # TypeScript Development Rules (Frontend)
 
-## Frontend-Specific Anti-patterns
+Frontend-specific React/TypeScript rules for implementation: thresholds, boundary type safety, component/state design, error handling, and project conventions.
 
-In addition to universal anti-patterns, watch for these Frontend-specific issues:
+## Anti-patterns and Thresholds
+Signals that trigger a design change:
+- Prop drilling through 3+ levels → lift to Context or state management
+- Component over 300 lines → split
+- Props count over 10 → split the component (3-7 is the working range)
+- Optional props over 50% → introduce defaults or Context
+- Props nesting deeper than 2 levels → flatten
+- The same `as` assertion appearing 3+ times → revisit the type design
 
-- **Prop drilling through 3+ levels** - Should use Context API or state management
-- **Massive components (300+ lines)** - Split into smaller components
+## Type Safety at Boundaries
+Prohibit `any`; when a type is unavailable, receive it as `unknown` and narrow with a type guard. Minimize `as` (justify with a comment when unavoidable).
 
-## Type Safety in Frontend Implementation
+Inside the app, React Props/State are type-guaranteed — no `unknown` needed. At every external boundary, receive as `unknown` and narrow with a type guard before use: API responses, `localStorage`/`sessionStorage`, URL parameters, parsed JSON. Controlled-component form input stays type-safe through React synthetic events.
 
-**Type Safety in Data Flow**
-- **Frontend -> Backend**: Props/State (Type Guaranteed) -> API Request (Serialization)
-- **Backend -> Frontend**: API Response (`unknown`) -> Type Guard -> State (Type Guaranteed)
-
-**Frontend-Specific Type Scenarios**:
-- **React Props/State**: TypeScript manages types, unknown unnecessary
-- **External API Responses**: Always receive as `unknown`, validate with type guards
-- **localStorage/sessionStorage**: Treat as `unknown`, validate
-- **URL Parameters**: Treat as `unknown`, validate
-- **Form Input (Controlled Components)**: Type-safe with React synthetic events
-
-**Type Complexity Management (Frontend)**
-- **Props Design**:
-  - Props count: 3-7 props ideal (consider component splitting if exceeds 10)
-  - Optional Props: 50% or less (consider default values or Context if excessive)
-  - Nesting: Up to 2 levels (flatten deeper structures)
-- Type Assertions: Review design if used 3+ times
-- **External API Types**: Relax constraints and define according to reality (convert appropriately internally)
-
-## Coding Conventions
-
-**Component Design Criteria**
-- **Function Components (Mandatory)**: Official React recommendation, optimizable by modern tooling
-- **Classes Prohibited**: Class components completely deprecated (Exception: Error Boundary)
-- **Custom Hooks**: Standard pattern for logic reuse
-
-**Function Design**
-- **0-2 parameters maximum**: Use object for 3+ parameters
-  ```typescript
-  // Object parameter
-  function createUser({ name, email, role }: CreateUserParams) {}
-  ```
-
-**Props Design (Props-driven Approach)**
-- Props are the interface: Define all necessary information as props
-- Avoid implicit dependencies: Do not depend on global state or context without necessity
-- Type-safe: Always define Props type explicitly
-
-**Environment Variables**
-- **Use build tool's environment variable system**: `process.env` does not work in browsers
-- **No secrets on client-side**: All frontend code is public, manage secrets in backend
-
-**Dependency Injection**
-- **Custom Hooks for dependency injection**: Ensure testability and modularity
-
-**Asynchronous Processing**
-- Promise Handling: Always use `async/await`
-- Error Handling: Always handle with `try-catch` or Error Boundary
-- Type Definition: Explicitly define return value types (e.g., `Promise<Result>`)
-
-**Format Rules**
-- Semicolon omission (follow Biome settings)
-- Types in `PascalCase`, variables/functions in `camelCase`
-- Imports use absolute paths (`src/`)
+```typescript
+const raw: unknown = await (await fetch(url)).json()
+if (!isUser(raw)) throw new ValidationError('invalid user')
+const user = raw // narrowed to User
+```
 
-**Clean Code Principles**
-- Delete unused code immediately
-- Delete debug `console.log()`
-- No commented-out code (manage history with version control)
-- Comments explain "why" (not "what")
+## Component and State Design
+- **Function components only.** Class components are allowed solely for Error Boundaries (no hook equivalent exists).
+- **Type Props explicitly** with a named type and destructure: `function UserCard({ user, onSelect }: UserCardProps)`. Avoid `React.FC`; type props directly on the function so the props contract stays explicit.
+- **Props-driven:** pass dependencies as props; reach into global state or Context only when needed.
+- **Custom hooks** are the unit of logic reuse and dependency injection (inject collaborators through the hook for testability).
+- **Function parameters:** 0-2 positional; for 3+ take a single options object.
+- **State shape:** type state explicitly; for multi-field state with discrete transitions, use `useReducer` with a discriminated-union action type rather than many `useState` calls.
 
 ## Error Handling
+- Surface every error: log and handle, or propagate — never swallow.
+- **Fail fast:** on an invalid state, throw rather than returning a silent fallback.
+- Represent expected failures as values with a `Result` type; reserve `throw` for unexpected/unrecoverable cases.
+- Use purpose-specific error classes extending a base `AppError` carrying a `code` (e.g. ValidationError, ApiError, NotFoundError).
+- **Layer responsibilities:** the API layer converts transport errors into domain errors; hooks propagate `AppError` upward; an Error Boundary catches render-time errors and shows fallback UI.
+- Never log secrets (password, token, apiKey, creditCard).
 
-**Absolute Rule**: Error suppression prohibited. All errors must have log output and appropriate handling.
-
-**Fail-Fast Principle**: Fail quickly on errors to prevent continued processing in invalid states
-```typescript
-// Prohibited: Unconditional fallback
-catch (error) {
-  return defaultValue // Hides error
-}
-
-// Required: Explicit failure
-catch (error) {
-  logger.error('Processing failed', error)
-  throw error // Handle with Error Boundary or higher layer
-}
-```
-
-**Result Type Pattern**: Express errors with types for explicit handling
 ```typescript
 type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
 
-// Example: Express error possibility with types
-function parseUser(data: unknown): Result<User, ValidationError> {
-  if (!isValid(data)) return { ok: false, error: new ValidationError() }
-  return { ok: true, value: data as User }
+class AppError extends Error {
+  constructor(message: string, readonly code: string, readonly statusCode = 500) {
+    super(message); this.name = this.constructor.name
+  }
 }
 ```
 
-**Custom Error Classes**
+Error Boundary — the one place a class component is required:
 ```typescript
-export class AppError extends Error {
-  constructor(message: string, public readonly code: string, public readonly statusCode = 500) {
-    super(message)
-    this.name = this.constructor.name
-  }
+class ErrorBoundary extends React.Component<{ children: React.ReactNode; fallback: React.ReactNode }, { hasError: boolean }> {
+  state = { hasError: false }
+  static getDerivedStateFromError() { return { hasError: true } }
+  render() { return this.state.hasError ? this.props.fallback : this.props.children }
 }
-// Purpose-specific: ValidationError(400), ApiError(502), NotFoundError(404)
 ```
 
-**Layer-Specific Error Handling (React)**
-- Error Boundary: Catch React component errors, display fallback UI
-- Custom Hook: Detect business rule violations, propagate AppError as-is
-- API Layer: Convert fetch errors to domain errors
-
-**Structured Logging and Sensitive Information Protection**
-Never include sensitive information (password, token, apiKey, secret, creditCard) in logs
-
-**Asynchronous Error Handling in React**
-- Error Boundary setup mandatory: Catch rendering errors
-- Use try-catch with all async/await in event handlers
-- Always log and re-throw errors or display error state
-
-## Performance Optimization
-
-- Component Memoization: Use React.memo for expensive components
-- State Optimization: Minimize re-renders with proper state structure
-- Lazy Loading: Use React.lazy and Suspense for code splitting
-- Bundle Size: Monitor with the `build` script and keep under 500KB
+## Project Conventions
+- **Environment variables:** read through the build tool's env system (`process.env` is absent in the browser). Keep all secrets server-side — frontend code ships to the client.
+- **Bundle & performance:** monitor with the `build` script, keep under 500KB; memoize expensive components (`React.memo`); code-split with `React.lazy` + `Suspense`; structure state to minimize re-renders.
+- **Naming:** components/types `PascalCase`; variables/functions `camelCase`; hooks `use`-prefixed; constants `SCREAMING_SNAKE_CASE`.
+- **Imports:** absolute paths from `src/`; order: React → external libs → internal (absolute) → internal (relative) → type-only → styles/assets.
+- **Formatting:** follow Biome (semicolons and style come from project config).

package/.claude/skills-en/frontend-typescript-testing/SKILL.md

@@ -140,8 +140,10 @@ describe('Button', () => {
 
 ## Test Design Patterns
 
+Test user-visible results, not implementation details. Query by accessibility (`getByRole`/`getByLabelText`/`getByText`), not `getByTestId` or `container.querySelector`. Cover empty, error, and loading/async states, not only the happy path; await async UI with `findBy*`.
+
 ```typescript
-// Correct: test user-visible results
+// Test the user-visible result
 it('increments count when clicked', async () => {
   const user = userEvent.setup()
   render(<Counter />)
@@ -149,10 +151,10 @@ it('increments count when clicked', async () => {
   expect(screen.getByText('Count: 1')).toBeInTheDocument()
 })
 
-// Avoid: testing implementation details
-it('calls setState', () => {
-  const setState = vi.spyOn(React, 'useState')
-  render(<Counter />)
-  // ...
+// Error state: override the handler for one test
+it('shows an error message on API failure', async () => {
+  server.use(http.get('/api/users', () => new HttpResponse(null, { status: 500 })))
+  render(<UserList />)
+  expect(await screen.findByText('Something went wrong')).toBeInTheDocument()
 })
 ```

package/.claude/skills-en/subagents-orchestration-guide/SKILL.md

@@ -158,7 +158,7 @@ Subagents respond in JSON format. Key fields for orchestrator decisions:
 | code-verifier | status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against Design Doc (pass `code_paths` scoped to changed files) | Flag discrepancies for document-reviewer |
 | task-executor | Input: `task_file` (required in orchestrated flows); optional Fix Mode signals `requiredFixes` or `incompleteImplementations` — when either is non-empty, skip `task_already_completed` and extend allowed list with each item's `file_path` / `location` (parse `location` as `file[:line]`); each `incompleteImplementations[]` entry may carry `type: "missing_logic" \| "hollow_test"` and the executor branches its fix action by `type`. Output: status (escalation_needed/completed), filesModified[], testsAdded, requiresTestReview, runnableCheck{level, executed, command, result, substance, substanceIssue, reason}, escalation_type ∈ {task_file_not_found, task_already_completed, target_files_missing, design_compliance_violation, similar_function_found, similar_component_found, investigation_target_not_found, out_of_scope_file, dependency_version_uncertain, binding_decision_violation, test_environment_not_ready}. | On escalation_needed: handle by escalation_type |
 | quality-fixer | Input: `task_file` (path to current task file — always pass this in orchestrated flows), `filesModified` (extract from the upstream implementation step's response — passes the task's write set as the primary scope for stub-detection; falls back to `git diff HEAD` when omitted), `runnableCheck` (extract from the upstream implementation step's response — passes the test execution evidence including `substance` and `substanceIssue` so the substance check has the runtime signal; omit when the upstream did not run tests). Status: approved/stub_detected/blocked. `stub_detected` → `incompleteImplementations[]` items carry `type: "missing_logic" \| "hollow_test"`; route back to the implementation step (which branches its fix action on `type`), then re-run quality-fixer. `blocked` → see quality-fixer blocked handling below | On stub_detected: re-invoke the implementation step. On blocked: see handling below |
-| document-reviewer | approvalReady (true/false) | Proceed to next step on true; request fixes on false |
+| document-reviewer | verdict.decision (approved/approved_with_conditions/needs_revision/rejected) | Proceed on approved/approved_with_conditions; request fixes on needs_revision; escalate on rejected |
 | design-sync | sync_status (NO_CONFLICTS/CONFLICTS_FOUND) | On CONFLICTS_FOUND: present conflicts to user before proceeding |
 | integration-test-reviewer | status (approved/needs_revision/blocked), requiredFixes | On needs_revision: re-invoke the routed executor in Fix Mode with the same task_file and requiredFixes[] |
 | security-reviewer | status (approved/approved_with_notes/needs_revision/blocked), findings, notes, requiredFixes | On needs_revision: create a consolidated fix task file with the affected file paths from `requiredFixes[].location` populated into Target Files, then invoke the routed executor in Fix Mode with that task_file and the `requiredFixes[]` array, then quality-fixer, then re-invoke security-reviewer to verify resolution. On blocked: escalate to user with the blocking findings — fix is not within the agent layer's authority |
@@ -175,7 +175,7 @@ When quality-fixer returns `status: "blocked"`, discriminate by `reason`:
 When receiving new features or change requests, I first request requirement analysis from requirement-analyzer.
 According to scale determination:
 
-### Large Scale (6+ Files) - 13 Steps (backend) / 15 Steps (frontend/fullstack)
+### Large Scale (6+ Files) - 14 Steps (backend) / 16 Steps (frontend/fullstack)
 
 1. requirement-analyzer → Requirement analysis + Check existing PRD **[Stop]**
 2. prd-creator → PRD creation
@@ -190,10 +190,11 @@ According to scale determination:
 11. document-reviewer → Design Doc review (pass code-verifier results as code_verification; cross-layer: per Design Doc)
 12. design-sync → Consistency verification **[Stop: Design Doc Approval]**
 13. acceptance-test-generator → Test skeleton generation, pass to work-planner (*1)
-14. work-planner → Work plan creation **[Stop: Batch approval]**
-15. task-decomposer → Autonomous execution → Completion report
+14. work-planner → Work plan creation
+15. document-reviewer → Work plan review (doc_type: WorkPlan; pass the Design Doc path so AC/contract/state coverage is traceable). On `needs_revision`: re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions` — the plan is a derivation of the Design Doc, so plan-fidelity findings need no user adjudication. On `rejected`: escalate to user. **[Stop: Batch approval]**
+16. task-decomposer → Autonomous execution → Completion report
 
-### Medium Scale (3-5 Files) - 9 Steps (backend) / 11 Steps (frontend/fullstack)
+### Medium Scale (3-5 Files) - 10 Steps (backend) / 12 Steps (frontend/fullstack)
 
 1. requirement-analyzer → Requirement analysis **[Stop]**
 2. **(frontend/fullstack only)** Ask user for prototype code → ui-spec-designer → UI Spec creation (UI Spec informs component structure for technical design)
@@ -204,8 +205,9 @@ According to scale determination:
 7. document-reviewer → Design Doc review (pass code-verifier results as code_verification; cross-layer: per Design Doc)
 8. design-sync → Consistency verification **[Stop: Design Doc Approval]**
 9. acceptance-test-generator → Test skeleton generation, pass to work-planner (*1)
-10. work-planner → Work plan creation **[Stop: Batch approval]**
-11. task-decomposer → Autonomous execution → Completion report
+10. work-planner → Work plan creation
+11. document-reviewer → Work plan review (doc_type: WorkPlan; pass the Design Doc path so AC/contract/state coverage is traceable). On `needs_revision`: re-invoke work-planner (update) and re-review until `approved`/`approved_with_conditions` — the plan is a derivation of the Design Doc, so plan-fidelity findings need no user adjudication. On `rejected`: escalate to user. **[Stop: Batch approval]**
+12. task-decomposer → Autonomous execution → Completion report
 
 ### Small Scale (1-2 Files) - 2 Steps
 

package/.claude/skills-en/task-analyzer/references/skills-index.yaml

@@ -192,21 +192,19 @@ skills:
   # Frontend-specific Skills
   frontend-typescript-rules:
     skill: "frontend-typescript-rules"
-    tags: [frontend, react, implementation, type-safety, function-components, props-driven, async, refactoring, coding-style]
-    typical-use: "React component creation, Props type definitions, frontend TypeScript development"
+    tags: [frontend, react, implementation, type-safety, component-design, props-driven, hooks, error-handling, conventions]
+    typical-use: "React component creation, Props/state design, error handling, frontend TypeScript implementation rules"
     size: small
     key-references:
-      - "React Function Components - React Official"
-      - "Props-driven Design - React Best Practices"
-      - "YAGNI Principle - Kent Beck"
-      - "Clean Code - Robert C. Martin"
-      - "TypeScript satisfies Operator - Microsoft"
+      - "React Function Components - React docs"
+      - "Type guards at external boundaries (unknown narrowing)"
+      - "Result type and Error Boundary error handling"
     sections:
-      - "Frontend-Specific Anti-patterns"
-      - "Type Safety in Frontend Implementation"
-      - "Coding Conventions"
+      - "Anti-patterns and Thresholds"
+      - "Type Safety at Boundaries"
+      - "Component and State Design"
       - "Error Handling"
-      - "Performance Optimization"
+      - "Project Conventions"
 
   frontend-typescript-testing:
     skill: "frontend-typescript-testing"

package/.claude/skills-ja/documentation-criteria/references/plan-template.md

@@ -4,6 +4,7 @@
 種別: feature|fix|refactor
 想定影響範囲: Xファイル
 関連Issue/PR: #XXX（該当する場合）
+レビュースコープ: [Design Docとタスク対象から導出した変更予定ファイルの範囲。既存作業に対する改訂計画の場合はベースブランチ + diff範囲]
 <!-- 下記の行はmedium / large規模のみ — small規模はこのplan-templateではなくtask-templateを使用する。値の行は末尾コメントを付けず、下流のパーサがbare statusの抽出（pending | ready | escalated）を行えるように保つこと。 -->
 Implementation Readiness: pending
 
@@ -26,6 +27,10 @@ Implementation Readiness: pending
 - **成功基準**: [Design Docから抽出]
 - **失敗時の対応**: [Design Docから抽出]
 
+### 証明戦略
+- **証明義務の出所**: [スケルトンが存在する場合はテストスケルトンの注釈（主要な故障モード、証明義務）。存在しない場合は各ACの主要な故障モード]
+- **タスクごとの伝播**: 主張を実装する各タスクは Proof Obligations（task template参照）を記録し、下流のレビューがテストが主張を証明しているか（単に実行されるだけでないか）を判定できるようにする
+
 ## 品質保証メカニズム（Design Docより）
 
 変更対象領域で採用された品質ゲート。本計画の各タスクはこれらのメカニズムを満たす必要がある。
@@ -48,6 +53,21 @@ Design Docの各技術要件をカバーするタスクへのマッピング。
 
 **ギャップステータス値**: `covered`（タスクあり）、`gap`（タスクなし — 備考に理由必須、計画承認前にユーザー確認が必要）
 
+## 故障モードチェックリスト
+
+この実装が防ぐべきドメイン非依存の故障カテゴリ。8カテゴリすべてを列挙し、各カテゴリの該当列に yes/no を記入し、該当する各カテゴリにカバーするタスクを挙げる。エントリにはプロジェクト固有の名称を含めない。
+
+| カテゴリ | 該当? | カバーするタスク |
+|---|---|---|
+| same-value | yes/no | [Phase X タスクY] |
+| no-op | yes/no | |
+| empty input | yes/no | |
+| invalid option | yes/no | |
+| missing config | yes/no | |
+| unavailable boundary | yes/no | |
+| shared-state dependency | yes/no | |
+| rollback-only visibility | yes/no | |
+
 ## UI Specコンポーネント → タスクマッピング
 
 入力にUI Specが含まれる場合のみ本セクションを記載する。UI Specに記述された各コンポーネントを実装するタスクへのマッピング。task-decomposerはこの表を読み込み、対応するUI Specセクションを各タスクのInvestigation Targetsに伝播させる。UI Specがない場合は本セクションを省略する。

package/.claude/skills-ja/documentation-criteria/references/task-template.md

@@ -56,9 +56,21 @@ Metadata:
 - **失敗時の対応**: [検証失敗時の対処 — 例: 「続行前にアプローチを再評価」「ユーザーにエスカレーション」]
 - **検証レベル**: [L1: エンドユーザー機能としての動作確認 / L2: 新規テスト追加・パス / L3: ビルドエラーなし]
 
+## Proof Obligations
+（このタスクが実装するACまたは主張ごとに1エントリ。スケルトンの注釈がある場合はそこから、なければACの主要な故障モードから導出する。各テストは主張を証明すること。下記ブロックを主張ごとに繰り返し、見出しにAC IDまたは主張IDを記載して下流のレビューが主張ごとにカバレッジを解決できるようにする。）
+
+### Obligation: [AC IDまたは主張ID]
+- **主張**: [ACが約束する振る舞い]
+- **主要な故障モード**: [テストがレッドになるリグレッション]
+- **検証する境界**: [テストが通過する公開/統合境界、または "in-process unit"]
+- **状態アサーション**: [状態変更を伴う主張では 操作前 → 操作 → 操作後 の観察可能な状態。それ以外は "N/A"]
+- **モック境界の根拠**: [どの境界をモックしてよいか、その理由。すべて実物なら "none"]
+- **残余**: [この証明で未確立のまま残る事項があれば記載]
+
 ## Completion Criteria
 - [ ] 追加した全テストがパス
 - [ ] Operation Verification Methods に基づく動作確認完了
+- [ ] 各 Proof Obligation が満たされている: テストが主要な故障モードでレッドになり、指定された境界を通過する
 - [ ] 成果物作成完了（調査・設計タスクの場合）
 - [ ] （Binding Decisionsがある場合）全てのCompliance Checkが最終実装に対して`Y`と評価され、根拠（file:line、テスト結果、またはコマンド出力）がInvestigation Notesに記録されている
 

package/.claude/skills-ja/frontend-technical-spec/SKILL.md

@@ -17,10 +17,10 @@ TypeScriptベースのReactアプリケーション実装。アーキテクチ
 - デフォルト値設定と必須チェックの適切な実装
 
 ```typescript
-// ビルドツールの環境変数（公開値のみ）
+// ビルドツールの環境変数（公開値のみ。クライアント公開変数は VITE_ 接頭辞が必要）
 const config = {
-  apiUrl: import.meta.env.API_URL || 'http://localhost:3000',
-  appName: import.meta.env.APP_NAME || 'My App'
+  apiUrl: import.meta.env.VITE_API_URL || 'http://localhost:3000',
+  appName: import.meta.env.VITE_APP_NAME || 'My App'
 }
 
 // フロントエンドでは動作しない