@devran-ai/kit 4.1.0

package/.agent/skills/mobile-design/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: mobile-design
+description: Mobile UI/UX patterns for iOS and Android. Touch-first, platform-respectful design with React Native/Expo focus.
+version: 1.0.0
+allowed-tools: Read, Glob, Grep
+---
+
+# Mobile Design System
+
+> **Philosophy:** Touch-first. Battery-conscious. Platform-respectful. Offline-capable.
+> **Core Principle:** Mobile is NOT a small desktop. THINK mobile constraints, ASK platform choice.
+
+---
+
+## ⚠️ CRITICAL: ASK BEFORE ASSUMING
+
+### You MUST Ask If Not Specified:
+
+- **Platform**: iOS only? Android only? Both?
+- **Framework**: React Native/Expo? Flutter?
+- **Navigation**: Tab-based? Stack? Drawer?
+- **Offline**: Required? Nice-to-have? Not needed?
+
+---
+
+## 📱 Platform Decision Matrix
+
+### When to Unify vs Diverge
+
+```
+                    UNIFY (same on both)          DIVERGE (platform-specific)
+                    ───────────────────           ──────────────────────────
+Business Logic      ✅ Always                     -
+Data Layer          ✅ Always                     -
+Core Features       ✅ Always                     -
+
+Navigation          -                             ✅ iOS: edge swipe, Android: back button
+Gestures            -                             ✅ Platform-native feel
+Icons               -                             ✅ SF Symbols vs Material Icons
+Date Pickers        -                             ✅ Native pickers feel right
+Modals/Sheets       -                             ✅ iOS: bottom sheet vs Android: dialog
+Typography          -                             ✅ SF Pro vs Roboto (or custom)
+```
+
+### Quick Reference: Platform Defaults
+
+| Element              | iOS                       | Android                    |
+| -------------------- | ------------------------- | -------------------------- |
+| **Primary Font**     | SF Pro / SF Compact       | Roboto                     |
+| **Min Touch Target** | 44pt × 44pt               | 48dp × 48dp                |
+| **Back Navigation**  | Edge swipe left           | System back button/gesture |
+| **Bottom Tab Icons** | SF Symbols                | Material Symbols           |
+| **Action Sheet**     | UIActionSheet from bottom | Bottom Sheet / Dialog      |
+| **Progress**         | Spinner                   | Linear progress (Material) |
+
+---
+
+## 🧠 Mobile UX Psychology
+
+### Fitts' Law for Touch
+
+```
+Desktop: Cursor is precise (1px)
+Mobile:  Finger is imprecise (~7mm contact area)
+
+→ Touch targets MUST be 44-48px minimum
+→ Important actions in THUMB ZONE (bottom of screen)
+→ Destructive actions AWAY from easy reach
+```
+
+### Thumb Zone (One-Handed Usage)
+
+```
+┌─────────────────────────────┐
+│      HARD TO REACH          │ ← Navigation, menu, back
+│        (stretch)            │
+├─────────────────────────────┤
+│      OK TO REACH            │ ← Secondary actions
+│       (natural)             │
+├─────────────────────────────┤
+│      EASY TO REACH          │ ← PRIMARY CTAs, tab bar
+│    (thumb's natural arc)    │ ← Main content interaction
+└─────────────────────────────┘
+        [  HOME  ]
+```
+
+### Mobile-Specific Cognitive Load
+
+| Desktop            | Mobile Difference              |
+| ------------------ | ------------------------------ |
+| Multiple windows   | ONE task at a time             |
+| Keyboard shortcuts | Touch gestures                 |
+| Hover states       | NO hover (tap or nothing)      |
+| Large viewport     | Limited space, scroll vertical |
+| Stable attention   | Interrupted constantly         |
+
+---
+
+## ⚡ React Native/Expo Performance
+
+### FlatList Optimization
+
+```typescript
+// ✅ CORRECT: Memoized renderItem + React.memo wrapper
+const ListItem = React.memo(({ item }: { item: Item }) => (
+  <View style={styles.item}>
+    <Text>{item.title}</Text>
+  </View>
+));
+
+const renderItem = useCallback(
+  ({ item }: { item: Item }) => <ListItem item={item} />,
+  []
+);
+
+// ✅ CORRECT: FlatList with all optimizations
+<FlatList
+  data={items}
+  renderItem={renderItem}
+  keyExtractor={(item) => item.id}  // Stable ID, NOT index
+  getItemLayout={(data, index) => ({
+    length: ITEM_HEIGHT,
+    offset: ITEM_HEIGHT * index,
+    index,
+  })}
+  removeClippedSubviews={true}
+  maxToRenderPerBatch={10}
+  windowSize={5}
+/>
+```
+
+### Animation Performance
+
+```
+GPU-accelerated (FAST):     CPU-bound (SLOW):
+├── transform               ├── width, height
+├── opacity                 ├── top, left, right, bottom
+└── (use these ONLY)        ├── margin, padding
+                            └── (AVOID animating these)
+```
+
+---
+
+## 📝 Pre-Development Checklist
+
+### Before Starting ANY Mobile Project
+
+- [ ] Platform(s) confirmed (iOS/Android/Both)
+- [ ] Framework chosen (Expo recommended)
+- [ ] Navigation pattern decided
+- [ ] Offline requirements clarified
+- [ ] Design system tokens defined
+
+### Before Every Screen
+
+- [ ] Touch targets ≥ 44pt
+- [ ] Primary actions in thumb zone
+- [ ] Safe area insets handled
+- [ ] Both orientations considered (or locked)
+
+### Before Release
+
+- [ ] Performance profiled
+- [ ] Memory usage checked
+- [ ] Battery impact tested
+- [ ] Accessibility verified
+
+---
+
+## 🔗 Recommended Mobile Stack
+
+| Layer      | Technology                       |
+| ---------- | -------------------------------- |
+| Framework  | Expo (managed workflow)          |
+| Navigation | Expo Router                      |
+| State      | Zustand + React Query            |
+| Storage    | expo-secure-store + AsyncStorage |
+| UI         | Custom + NativeWind (if needed)  |
+
+---
+
+## ❌ Mobile Anti-Patterns
+
+| ❌ Don't                    | ✅ Do                     |
+| --------------------------- | ------------------------- |
+| Assume platform conventions | Ask or detect platform    |
+| Use web-style hover states  | Use pressable feedback    |
+| Put CTAs at top of screen   | Keep CTAs in thumb zone   |
+| Use tiny touch targets      | Minimum 44-48px           |
+| Ignore safe areas           | Always respect insets     |
+| Over-animate                | Subtle, purposeful motion |

package/.agent/skills/nodejs-patterns/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: nodejs-patterns
+description: Node.js and backend framework best practices
+triggers: [context, nodejs, nestjs, express, backend]
+---
+
+# Node.js Patterns Skill
+
+> **Purpose**: Apply professional Node.js patterns for backend development
+
+---
+
+## Overview
+
+This skill provides best practices for building scalable, maintainable Node.js applications.
+
+---
+
+## Project Structure
+
+### NestJS Structure
+
+```
+src/
+├── main.ts                    # Entry point
+├── app.module.ts              # Root module
+├── common/                    # Shared utilities
+│   ├── decorators/
+│   ├── filters/
+│   ├── guards/
+│   ├── interceptors/
+│   └── pipes/
+├── config/                    # Configuration
+│   ├── database.config.ts
+│   └── app.config.ts
+└── domains/                   # Feature modules
+    ├── users/
+    │   ├── users.module.ts
+    │   ├── users.controller.ts
+    │   ├── users.service.ts
+    │   ├── dto/
+    │   └── entities/
+    └── orders/
+```
+
+---
+
+## Dependency Injection
+
+```typescript
+// Service
+@Injectable()
+export class UserService {
+  constructor(
+    private readonly userRepository: UserRepository,
+    private readonly emailService: EmailService,
+  ) {}
+}
+
+// Controller
+@Controller("users")
+export class UserController {
+  constructor(private readonly userService: UserService) {}
+
+  @Get(":id")
+  async getUser(@Param("id") id: string) {
+    return this.userService.findById(id);
+  }
+}
+```
+
+---
+
+## Error Handling
+
+```typescript
+// Custom Exception
+export class UserNotFoundException extends NotFoundException {
+  constructor(userId: string) {
+    super(`User with ID ${userId} not found`);
+  }
+}
+
+// Global Exception Filter
+@Catch()
+export class GlobalExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+
+    const status =
+      exception instanceof HttpException
+        ? exception.getStatus()
+        : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    response.status(status).json({
+      statusCode: status,
+      message: exception.message || "Internal server error",
+      timestamp: new Date().toISOString(),
+    });
+  }
+}
+```
+
+---
+
+## Validation
+
+```typescript
+// DTO with class-validator
+export class CreateUserDto {
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @MinLength(8)
+  @Matches(/^(?=.*[A-Z])(?=.*[0-9])/)
+  password: string;
+
+  @IsOptional()
+  @IsString()
+  name?: string;
+}
+
+// Controller with validation pipe
+@Post()
+@UsePipes(new ValidationPipe({ transform: true }))
+async create(@Body() createUserDto: CreateUserDto) {
+  return this.userService.create(createUserDto);
+}
+```
+
+---
+
+## Async Patterns
+
+```typescript
+// Async/Await
+async function processOrders() {
+  const orders = await Order.findAll({ where: { status: "pending" } });
+  await Promise.all(orders.map((order) => processOrder(order)));
+}
+
+// Concurrent Limit
+import pLimit from "p-limit";
+const limit = pLimit(5); // Max 5 concurrent
+
+await Promise.all(items.map((item) => limit(() => processItem(item))));
+```
+
+---
+
+## Quick Reference
+
+| Pattern     | Usage                     |
+| :---------- | :------------------------ |
+| Module      | Feature encapsulation     |
+| Service     | Business logic            |
+| Controller  | HTTP handling             |
+| Repository  | Data access               |
+| DTO         | Data transfer             |
+| Guard       | Authorization             |
+| Interceptor | Cross-cutting             |
+| Pipe        | Transformation/Validation |

package/.agent/skills/parallel-agents/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: parallel-agents
+description: Multi-agent orchestration patterns for complex tasks requiring multiple domain expertise or comprehensive analysis.
+version: 1.0.0
+allowed-tools: Read, Glob, Grep
+---
+
+# Native Parallel Agents
+
+> **Purpose**: Enable coordinating multiple specialized agents through Devran AI Kit's native agent system while maintaining Trust-Grade governance.
+
+## Overview
+
+This skill enables coordinating multiple specialized agents for complex tasks. Unlike external scripts, this approach keeps all orchestration within the kit's control while applying Trust-Grade governance protocols.
+
+---
+
+## When to Use Orchestration
+
+✅ **Good for:**
+
+- Complex tasks requiring multiple expertise domains
+- Code analysis from security, performance, and quality perspectives
+- Comprehensive reviews (architecture + security + testing)
+- Feature implementation needing backend + frontend + database work
+- Trust-Grade verticals (Auth, Payment, etc.)
+
+❌ **Not for:**
+
+- Simple, single-domain tasks
+- Quick fixes or small changes
+- Tasks where one agent suffices
+
+---
+
+## Native Agent Invocation
+
+### Single Agent
+
+```
+Use the security-reviewer agent to audit authentication
+```
+
+### Sequential Chain
+
+```
+First, use the architect to review structure.
+Then, use the code-reviewer to check implementation.
+Finally, use the tdd-guide to verify test coverage.
+```
+
+### With Context Passing
+
+```
+Use the planner to break down the feature.
+Based on that plan, have the architect design the structure.
+Then, have the tdd-guide create test specifications.
+```
+
+### Resume Previous Work
+
+```
+Resume agent [agentId] and continue with additional requirements.
+```
+
+---
+
+## Orchestration Patterns
+
+### Pattern 1: Feature Vertical (Trust-Grade Standard)
+
+```
+Agents: planner → architect → [domain-agents] → tdd-guide → e2e-runner
+
+1. planner: Break down feature into tasks
+2. architect: Design component structure
+3. [domain-agents]: Implement by domain
+4. tdd-guide: Create/verify unit tests
+5. e2e-runner: Create/verify E2E tests
+6. Synthesize all deliverables
+```
+
+### Pattern 2: Code Review Comprehensive
+
+```
+Agents: code-reviewer → security-reviewer → synthesis
+
+1. code-reviewer: Quality and patterns review
+2. security-reviewer: Security posture audit
+3. Synthesize with prioritized findings
+```
+
+### Pattern 3: Security Audit
+
+```
+Agents: security-reviewer → architect → tdd-guide
+
+1. security-reviewer: Vulnerability assessment
+2. architect: Secure architecture patterns
+3. tdd-guide: Security test specifications
+```
+
+### Pattern 4: Build Recovery
+
+```
+Agents: build-error-resolver → refactor-cleaner → tdd-guide
+
+1. build-error-resolver: Fix immediate errors
+2. refactor-cleaner: Clean up technical debt
+3. tdd-guide: Add regression tests
+```
+
+---
+
+## Available Agents
+
+| Agent                  | Expertise     | Trigger Phrases                     |
+| ---------------------- | ------------- | ----------------------------------- |
+| `architect`            | System Design | "design", "structure", "pattern"    |
+| `planner`              | Task Planning | "plan", "roadmap", "breakdown"      |
+| `code-reviewer`        | Code Quality  | "review", "check", "audit"          |
+| `security-reviewer`    | Security      | "security", "auth", "vulnerability" |
+| `tdd-guide`            | Unit Testing  | "test", "TDD", "coverage"           |
+| `e2e-runner`           | E2E Testing   | "e2e", "playwright", "integration"  |
+| `build-error-resolver` | Build Issues  | "error", "compile", "typescript"    |
+| `refactor-cleaner`     | Refactoring   | "refactor", "clean", "improve"      |
+| `doc-updater`          | Documentation | "docs", "readme", "document"        |
+| `knowledge-agent`      | Knowledge     | "learn", "pattern", "remember"      |
+
+---
+
+## Synthesis Protocol
+
+After all agents complete, synthesize findings:
+
+```markdown
+## Orchestration Synthesis
+
+### Task Summary
+
+[What was accomplished]
+
+### Agent Contributions
+
+| Agent             | Finding         |
+| ----------------- | --------------- |
+| architect         | Designed X      |
+| security-reviewer | Identified Y    |
+| tdd-guide         | Created Z tests |
+
+### Consolidated Deliverables
+
+1. **Code Changes**: [summary]
+2. **Test Coverage**: [metrics]
+3. **Documentation**: [updates]
+
+### Action Items
+
+- [ ] Complete remaining tasks
+- [ ] Run verification loop
+- [ ] Update session state
+```
+
+---
+
+## Trust-Grade Integration
+
+### Pre-Orchestration Checklist
+
+- [ ] Verify session state is current
+- [ ] Check for active blockers
+- [ ] Load relevant governance rules
+- [ ] Confirm scope with user if complex
+
+### Post-Orchestration Protocol
+
+- [ ] Run verification-loop skill
+- [ ] Update session-state.json
+- [ ] Trigger continuous-learning if patterns detected
+- [ ] Document in knowledge base if novel approach
+
+---
+
+## Best Practices
+
+1. **Logical Order**: Discovery → Design → Implementation → Testing
+2. **Share Context**: Pass relevant findings to subsequent agents
+3. **Single Synthesis**: One unified report, not separate outputs
+4. **Verify Changes**: Always include tdd-guide for code modifications
+5. **Maintain Governance**: Apply Trust-Grade protocols throughout
+
+---
+
+## Key Benefits
+
+- ✅ **Single session** - All agents share context
+- ✅ **AI-controlled** - Orchestrated autonomously
+- ✅ **Trust-Grade** - Governance maintained throughout
+- ✅ **Resume support** - Can continue previous agent work
+- ✅ **Context passing** - Findings flow between agents

package/.agent/skills/performance-profiling/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: performance-profiling
+description: Performance profiling principles. Core Web Vitals, measurement, analysis, and optimization.
+version: 1.0.0
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Performance Profiling
+
+> Measure, analyze, optimize — in that order.
+
+---
+
+## 1. Core Web Vitals
+
+### Targets
+
+| Metric  | Good    | Poor    | Measures      |
+| ------- | ------- | ------- | ------------- |
+| **LCP** | < 2.5s  | > 4.0s  | Loading       |
+| **INP** | < 200ms | > 500ms | Interactivity |
+| **CLS** | < 0.1   | > 0.25  | Stability     |
+
+### When to Measure
+
+| Stage       | Tool                       |
+| ----------- | -------------------------- |
+| Development | Local Lighthouse           |
+| CI/CD       | Lighthouse CI              |
+| Production  | RUM (Real User Monitoring) |
+
+---
+
+## 2. Profiling Workflow
+
+### The 4-Step Process
+
+```
+1. BASELINE → Measure current state
+2. IDENTIFY → Find the bottleneck
+3. FIX      → Make targeted change
+4. VALIDATE → Confirm improvement
+```
+
+### Tool Selection
+
+| Problem     | Tool                 |
+| ----------- | -------------------- |
+| Page load   | Lighthouse           |
+| Bundle size | Bundle analyzer      |
+| Runtime     | DevTools Performance |
+| Memory      | DevTools Memory      |
+| Network     | DevTools Network     |
+
+---
+
+## 3. Bundle Analysis
+
+### What to Look For
+
+| Issue              | Indicator          |
+| ------------------ | ------------------ |
+| Large dependencies | Top of bundle      |
+| Duplicate code     | Multiple chunks    |
+| Unused code        | Low coverage       |
+| Missing splits     | Single large chunk |
+
+### Optimization Actions
+
+| Finding        | Action                  |
+| -------------- | ----------------------- |
+| Big library    | Import specific modules |
+| Duplicate deps | Dedupe, update versions |
+| Route in main  | Code split              |
+| Unused exports | Tree shake              |
+
+---
+
+## 4. Runtime Profiling
+
+### Performance Tab
+
+| Pattern            | Meaning              |
+| ------------------ | -------------------- |
+| Long tasks (>50ms) | UI blocking          |
+| Many small tasks   | Batching opportunity |
+| Layout/paint       | Rendering bottleneck |
+| Script             | JS execution         |
+
+### Memory Tab
+
+| Pattern        | Meaning          |
+| -------------- | ---------------- |
+| Growing heap   | Possible leak    |
+| Large retained | Check references |
+| Detached DOM   | Not cleaned up   |
+
+---
+
+## 5. Common Bottlenecks
+
+| Symptom            | Likely Cause              |
+| ------------------ | ------------------------- |
+| Slow initial load  | Large JS, render blocking |
+| Slow interactions  | Heavy event handlers      |
+| Jank during scroll | Layout thrashing          |
+| Growing memory     | Leaks, retained refs      |
+
+---
+
+## 6. Quick Win Priorities
+
+| Priority | Action              | Impact |
+| -------- | ------------------- | ------ |
+| 1        | Enable compression  | High   |
+| 2        | Lazy load images    | High   |
+| 3        | Code split routes   | High   |
+| 4        | Cache static assets | Medium |
+| 5        | Optimize images     | Medium |
+
+---
+
+## 7. Anti-Patterns
+
+| ❌ Don't          | ✅ Do                |
+| ----------------- | -------------------- |
+| Guess at problems | Profile first        |
+| Micro-optimize    | Fix biggest issue    |
+| Optimize early    | Optimize when needed |
+| Ignore real users | Use RUM data         |
+
+---
+
+> **Remember:** The fastest code is code that doesn't run. Remove before optimizing.