speccrew 0.1.0

package/.speccrew/skills/speccrew-sd-frontend/templates/SD-FRONTEND-TEMPLATE.md

@@ -0,0 +1,382 @@
+# Frontend System Design - {ModuleName}
+
+> Feature Spec Reference: {FeatureSpecPath}
+> API Contract Reference: {ApiContractPath}
+> Platform: {PlatformId} | Framework: {Framework} | Language: {Language}
+
+## 1. Design Goal
+
+{Brief description of what this module implements, referencing Feature Spec function}
+
+## 2. Component Architecture
+
+### 2.1 Component Tree
+
+<!-- AI-NOTE: ASCII component tree showing parent-child relationships. Adjust depth based on complexity. -->
+
+```
+PageContainer
+├── HeaderSection
+│   ├── SearchBar
+│   └── ActionButtons
+├── ContentArea
+│   ├── DataTable
+│   │   ├── TableHeader
+│   │   └── TableRow
+│   └── Pagination
+└── DetailDrawer
+    ├── FormSection
+    └── FooterActions
+```
+
+### 2.2 Component Summary
+
+| Component | Path | Type | Status | Description |
+|-----------|------|------|--------|-------------|
+| {Name} | `{directory}/{FileName}` | Page | [NEW]/[MODIFIED]/[EXISTING] | {Purpose} |
+| {Name} | `{directory}/{FileName}` | Component | [NEW]/[MODIFIED]/[EXISTING] | {Purpose} |
+
+## 3. Component Detail Design
+
+<!-- AI-NOTE: Repeat Section 3.N for each component. Focus on components with [NEW] or [MODIFIED] status. -->
+
+### 3.1 {ComponentName}
+
+**Purpose**: {What this component does}
+
+**Props**:
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| {prop} | {TypeScript type} | Yes/No | {value} | {description} |
+
+**Emits**:
+
+| Event | Payload Type | Description |
+|-------|-------------|-------------|
+| {event} | {TypeScript type} | {description} |
+
+**Internal State**:
+
+| State | Type | Initial Value | Description |
+|-------|------|--------------|-------------|
+| {state} | {type} | {value} | {description} |
+
+**Lifecycle & Watchers**:
+
+<!-- AI-NOTE: Describe key lifecycle hooks and watchers needed. Reference actual framework API. -->
+
+- `onMounted`: {description of initialization logic}
+- `watch({state})`: {description of reactive behavior}
+
+**Pseudo-code**:
+
+<!-- AI-NOTE: Use actual framework API syntax from techs knowledge. NOT generic code. -->
+
+```typescript
+// AI-NOTE: Example for Vue 3 Composition API
+// Adjust imports and syntax based on actual framework from techs knowledge
+import { ref, computed, onMounted, watch } from 'vue'
+import type { PropType } from 'vue'
+import { useRouter } from 'vue-router'
+import { use{StoreName}Store } from '@/stores/{store-name}'
+
+// Props definition
+const props = defineProps<{
+  {propName}: {Type}
+}>()
+
+// Emits definition
+const emit = defineEmits<{
+  {eventName}: [{payload}: {Type}]
+}>()
+
+// State
+const {stateName} = ref<{Type}>({initialValue})
+
+// Computed
+const {computedName} = computed(() => {
+  // {description}
+})
+
+// Store
+const {storeName} = use{StoreName}Store()
+
+// Methods
+const handle{Action} = async () => {
+  // {implementation logic}
+}
+
+// Lifecycle
+onMounted(() => {
+  // {initialization}
+})
+
+// Watchers
+watch({stateName}, (newVal, oldVal) => {
+  // {reactive behavior}
+})
+```
+
+#### Advanced Pseudo-code Patterns
+
+<!-- AI-NOTE: Common patterns for conditional rendering, form validation, and pagination -->
+
+```typescript
+// Conditional rendering and list iteration
+const filteredItems = computed(() => 
+  items.value.filter(item => item.status === 'active')
+)
+
+// Form validation
+const validateForm = (): boolean => {
+  const errors: Record<string, string> = {}
+  if (!formData.value.name?.trim()) {
+    errors.name = 'Name is required'
+  }
+  if (formData.value.price < 0) {
+    errors.price = 'Price must be non-negative'
+  }
+  formErrors.value = errors
+  return Object.keys(errors).length === 0
+}
+
+// Pagination boundary handling
+const loadMore = async () => {
+  if (isLoading.value || !hasMore.value) return
+  isLoading.value = true
+  try {
+    const result = await fetchPage(currentPage.value + 1)
+    if (result.items.length === 0) {
+      hasMore.value = false
+      return
+    }
+    items.value.push(...result.items)
+    currentPage.value++
+  } finally {
+    isLoading.value = false
+  }
+}
+```
+
+**Referenced APIs**:
+
+| API Name | Method | Path | Usage Context |
+|----------|--------|------|--------------|
+| {api} | GET/POST/PUT/DELETE | {path} | {when and why called} |
+
+---
+
+### 3.2 {ComponentName}
+
+<!-- AI-NOTE: Repeat the same structure as 3.1 for each additional component -->
+
+**Purpose**: {What this component does}
+
+**Props**:
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| {prop} | {TypeScript type} | Yes/No | {value} | {description} |
+
+**Emits**:
+
+| Event | Payload Type | Description |
+|-------|-------------|-------------|
+| {event} | {TypeScript type} | {description} |
+
+**Pseudo-code**:
+
+```typescript
+// AI-NOTE: Use actual framework API syntax from techs knowledge
+{implementation pseudo-code}
+```
+
+---
+
+## 4. State Management
+
+### 4.1 Store Design
+
+**Store Module**: `{store-path}/{store-name}`
+**Status**: [NEW]/[MODIFIED]/[EXISTING]
+
+**State Definition**:
+
+<!-- AI-NOTE: Use actual store pattern from techs knowledge (Pinia/Vuex/Redux/Zustand). -->
+
+```typescript
+// AI-NOTE: Example for Pinia store
+// File: src/stores/{store-name}.ts
+import { defineStore } from 'pinia'
+import type { {TypeName} } from '@/types/{module}'
+
+interface {StoreName}State {
+  {stateField}: {Type}
+}
+
+export const use{StoreName}Store = defineStore('{storeName}', {
+  state: (): {StoreName}State => ({
+    {stateField}: {initialValue}
+  }),
+
+  getters: {
+    {getterName}: (state) => state.{field}
+  },
+
+  actions: {
+    async {actionName}(params: {Type}) {
+      // {implementation}
+    }
+  }
+})
+```
+
+**Actions**:
+
+| Action | Parameters | Description | API Calls |
+|--------|-----------|-------------|-----------|
+| {action} | {params} | {description} | {api references} |
+
+**Getters/Selectors**:
+
+| Getter | Return Type | Description |
+|--------|-------------|-------------|
+| {getter} | {type} | {description} |
+
+### 4.2 State Synchronization Patterns
+
+<!-- AI-NOTE: Patterns for cross-component state sync and optimistic updates with rollback -->
+
+```typescript
+// Cross-component state synchronization
+watch(() => userStore.currentUser, (newUser, oldUser) => {
+  if (newUser && newUser.id !== oldUser?.id) {
+    // User switched - reload dependent data
+    orderStore.resetAndReload(newUser.id)
+    notificationStore.subscribe(newUser.id)
+  }
+})
+
+// Optimistic update with rollback
+const updateItem = async (id: string, data: Partial<Item>) => {
+  const previousState = { ...items.value.find(i => i.id === id) }
+  // Optimistic update
+  Object.assign(items.value.find(i => i.id === id)!, data)
+  try {
+    await api.updateItem(id, data)
+  } catch (error) {
+    // Rollback on failure
+    Object.assign(items.value.find(i => i.id === id)!, previousState)
+    throw error
+  }
+}
+```
+
+## 5. API Layer
+
+### 5.1 API Functions
+
+<!-- AI-NOTE: Follow actual API layer patterns from conventions-dev.md. Include request/response types. -->
+
+```typescript
+// AI-NOTE: File path follows conventions from techs knowledge
+// File: src/apis/{module}.ts
+
+import request from '@/utils/request'
+import type { {RequestType}, {ResponseType} } from '@/types/{module}'
+
+// API function with typed request/response
+export const {apiFunctionName} = (params: {RequestType}): Promise<{ResponseType}> => {
+  return request.{method}('{path}', params)
+}
+
+// Additional API functions...
+export const {apiFunctionName2} = (id: string): Promise<{ResponseType}> => {
+  return request.{method}(`{path}/${id}`)
+}
+```
+
+### 5.2 Error Handling
+
+| Error Code | HTTP Status | Frontend Handling | User Feedback |
+|-----------|-------------|------------------|---------------|
+| {code} | {status} | {handling logic} | {message/toast/redirect} |
+
+### 5.3 API Error Handling & Recovery
+
+<!-- AI-NOTE: Unified error handling patterns including retry logic and exponential backoff -->
+
+```typescript
+// Unified error handling
+const handleApiError = (error: AxiosError) => {
+  if (error.response?.status === 401) {
+    // Token expired - trigger refresh
+    authStore.refreshToken()
+    return
+  }
+  if (error.response?.status === 403) {
+    // Permission denied - redirect
+    router.push('/forbidden')
+    return
+  }
+  if (error.response?.status === 422) {
+    // Validation error - extract field errors
+    return error.response.data.errors
+  }
+  // Network error or timeout - show retry
+  if (!error.response) {
+    showRetryNotification(error.config)
+  }
+}
+
+// Request retry with exponential backoff
+const withRetry = async <T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> => {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn()
+    } catch (error) {
+      if (i === maxRetries - 1) throw error
+      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)))
+    }
+  }
+  throw new Error('Unreachable')
+}
+```
+
+## 6. Routing
+
+| Route Path | Route Name | Component | Guard | Lazy Load | Description |
+|-----------|------------|-----------|-------|-----------|-------------|
+| {path} | {name} | {component} | {guard type} | Yes/No | {description} |
+
+**Route Configuration**:
+
+<!-- AI-NOTE: Use actual router config format from techs knowledge. -->
+
+```typescript
+// AI-NOTE: Example for Vue Router
+{
+  path: '{path}',
+  name: '{RouteName}',
+  component: () => import('@/views/{Module}/{Page}.vue'),
+  meta: {
+    requiresAuth: true,
+    title: '{Page Title}'
+  }
+}
+```
+
+## 7. Unit Test Points
+
+| Test Target | Test Scenario | Expected Behavior |
+|-------------|--------------|-------------------|
+| {component} | {scenario description} | {expected result} |
+| {store action} | {scenario description} | {expected result} |
+| {api function} | {scenario description} | {expected result} |
+
+---
+
+**Document Status**: Draft / In Review / Published
+**Last Updated**: {Date}
+**Related Feature Spec**: [{Feature Name}]({FeatureSpecPath})

package/.speccrew/skills/speccrew-sd-mobile/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: speccrew-sd-mobile
+description: Mobile System Design SOP. Guide System Designer Agent to generate platform-specific mobile detailed design documents by filling technology implementation details into the Feature Spec skeleton. Reads techs knowledge to determine actual framework syntax (Flutter/React Native) and conventions.
+tools: Read, Write, Glob, Grep
+---
+
+# Trigger Scenarios
+
+- System Designer Agent dispatches this skill with platform context (platform_id, techs paths, Feature Spec paths)
+- Feature Spec has been confirmed, user requests mobile system design
+- User asks "Create mobile design for this platform" or "Generate mobile module design"
+
+# Workflow
+
+## Step 1: Read Inputs
+
+Read in order:
+
+1. **Feature Spec document(s)**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-feature-spec.md`
+2. **API Contract**: `speccrew-workspace/iterations/{number}-{type}-{name}/02.feature-design/[feature-name]-api-contract.md`
+3. **Mobile techs knowledge** (paths from agent context):
+   - `speccrew-workspace/knowledges/techs/{platform_id}/tech-stack.md`
+   - `speccrew-workspace/knowledges/techs/{platform_id}/architecture.md`
+   - `speccrew-workspace/knowledges/techs/{platform_id}/conventions-design.md`
+   - `speccrew-workspace/knowledges/techs/{platform_id}/conventions-dev.md`
+4. **Design template**: `speccrew-sd-mobile/templates/SD-MOBILE-TEMPLATE.md`
+5. **Index template**: `speccrew-sd-mobile/templates/INDEX-TEMPLATE.md`
+
+## Step 2: Analyze Existing Code Structure
+
+Use Glob/Grep to understand current codebase:
+
+| Target | Glob Pattern | Purpose |
+|--------|-------------|---------|
+| Screen/Page directory | `lib/screens/**/*.dart` or `src/screens/**/*.tsx` | Understand screen organization |
+| Widget/Component directory | `lib/widgets/**/*.dart` or `src/components/**/*` | Understand widget organization |
+| State management | `lib/providers/**/*.dart` or `src/stores/**/*` | Understand state pattern |
+| Navigation configuration | `lib/router/**/*.dart` or `src/navigation/**/*` | Understand routing structure |
+| API layer | `lib/api/**/*.dart` or `src/api/**/*` | Understand API encapsulation pattern |
+| Local storage | `lib/storage/**/*.dart` or `src/storage/**/*` | Understand persistence patterns |
+| Naming conventions | Various | Identify actual naming patterns in use |
+
+Document findings for reference in later steps.
+
+## Step 3: Extract Functions from Feature Spec
+
+Parse Feature Spec to identify all functions (Section 2.N pattern).
+
+For each function, extract:
+
+| Aspect | Content to Extract |
+|--------|-------------------|
+| Mobile prototype | UI flow description from Feature Spec |
+| Interaction flow | User actions and system responses |
+| Backend API calls | Required API endpoints from API Contract |
+| Data requirements | Fields and structures needed |
+| Platform features | Camera, GPS, push notifications, biometrics, etc. |
+
+Mark each function's screens/widgets as:
+
+| Marker | Meaning | Example |
+|--------|---------|---------|
+| `[EXISTING]` | Reuse current screen/widget | `[EXISTING] UserProfileScreen` |
+| `[MODIFIED]` | Enhance/change existing | `[MODIFIED] OrderList - add pull-to-refresh` |
+| `[NEW]` | Create brand new | `[NEW] ProductDetailPage` |
+
+**Checkpoint A: Present function extraction summary to user for confirmation.**
+
+## Step 4: Generate Module Design Documents
+
+For each function (or logical group of closely related functions = one module):
+
+### 4.1 Read Template
+
+Read `SD-MOBILE-TEMPLATE.md` for document structure.
+
+### 4.2 Fill Technology-Specific Details
+
+Fill each section with technology-specific implementation details:
+
+| Section | Technology-Specific Content |
+|---------|----------------------------|
+| Screen/widget tree | Use actual framework patterns (Flutter Widgets / React Native Components) |
+| Props/Parameters | Type definitions from conventions-dev.md |
+| State management | Actual pattern (Provider/Bloc/Riverpod for Flutter, Redux/MobX for React Native) |
+| API layer | Actual HTTP client (Dio for Flutter, Axios/fetch for React Native) |
+| Navigation | Actual router config (GoRouter for Flutter, React Navigation for React Native) |
+| Local storage | Actual storage solution (SharedPreferences/Hive/SQLite/MMKV) |
+| Platform features | Actual plugin APIs (camera, geolocator, local_notifications, etc.) |
+| Pseudo-code | MUST use actual framework syntax from techs knowledge |
+
+### 4.3 Write Module Design
+
+Write to: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/{module}-design.md`
+
+**Key Rules for Pseudo-code**:
+- MUST use actual framework API syntax from techs knowledge
+- NOT generic pseudo-code
+- Include actual import statements
+- Use actual state management/API patterns from conventions
+
+## Step 5: Generate Platform INDEX.md
+
+After all module designs are complete:
+
+### 5.1 Read Template
+
+Read `INDEX-TEMPLATE.md` for document structure.
+
+### 5.2 Fill Platform-Level Summary
+
+| Section | Content Source |
+|---------|---------------|
+| Tech stack summary | tech-stack.md |
+| Target platforms | tech-stack.md (iOS/Android min versions) |
+| Shared design decisions | architecture.md, conventions-design.md |
+| State management strategy | architecture.md state management section |
+| Base widgets/components | conventions-design.md shared components |
+| API client configuration | conventions-dev.md HTTP client section |
+| Authentication pattern | architecture.md authentication section |
+| Third-party SDKs | tech-stack.md dependencies |
+
+### 5.3 Build Module List
+
+Create table with links to each module design document.
+
+### 5.4 Write INDEX
+
+Write to: `speccrew-workspace/iterations/{number}-{type}-{name}/03.system-design/{platform_id}/INDEX.md`
+
+## Step 6: Present Summary
+
+Present to user:
+
+```
+Mobile System Design Summary for: {feature-name}
+Platform: {platform_id}
+
+Module Design Documents: {count}
+├── {module1}-design.md
+├── {module2}-design.md
+└── ...
+
+Key Design Decisions:
+- State Management: {approach}
+- Navigation Strategy: {approach}
+- API Layer: {approach}
+- Local Storage: {approach}
+- Platform Features: {list}
+
+Concerns/Trade-offs:
+- {list any concerns}
+```
+
+**Ask user to confirm:**
+1. Are the screen architectures appropriate?
+2. Is the state management strategy correct?
+3. Do the pseudo-code patterns match project conventions?
+4. Are all API calls from API Contract covered?
+5. Are platform-specific features (permissions, native integration) properly handled?
+
+# Key Rules
+
+| Rule | Description |
+|------|-------------|
+| **Actual Framework Syntax** | All pseudo-code MUST use actual framework/library syntax from techs knowledge, NOT generic code |
+| **API Contract READ-ONLY** | API Contract is reference only - do not modify |
+| **One Module Per Function Group** | Each module design document maps to one or more related Feature Spec functions |
+| **Status Markers Required** | Use [EXISTING], [MODIFIED], [NEW] markers for all screens, widgets, and store modules |
+| **Follow Techs Conventions** | Naming, directory structure, patterns must follow techs knowledge |
+| **Platform-Specific Handling** | Properly handle iOS/Android differences, permissions, and native integrations |
+| **Offline Support** | Consider offline-first patterns where applicable |
+
+# Checklist
+
+- [ ] All techs knowledge documents loaded before design
+- [ ] Existing code structure analyzed via Glob/Grep
+- [ ] Every Feature Spec function covered in a module design
+- [ ] All API calls from API Contract referenced correctly
+- [ ] Pseudo-code uses actual framework syntax (not generic)
+- [ ] Screen/widget naming follows conventions-dev.md
+- [ ] State management follows architecture.md patterns
+- [ ] Navigation follows conventions-design.md
+- [ ] Local storage strategy documented
+- [ ] Platform permissions and native integrations documented
+- [ ] App lifecycle handling documented
+- [ ] INDEX.md generated with complete module list
+- [ ] All files written to correct paths under 03.system-design/{platform_id}/
+- [ ] Checkpoint A passed: function extraction confirmed with user