@dv.nghiem/flowdeck 0.2.4 → 0.3.1

package/src/skills/event-driven-architecture/SKILL.md

@@ -0,0 +1,152 @@
+# Event-Driven Architecture
+
+## When to Activate
+
+Activate when:
+- Designing or implementing message-based communication between services
+- Building systems that require asynchronous processing
+- Decoupling producers from consumers in distributed systems
+- Implementing event sourcing or audit trails
+- Setting up webhooks, message queues, or pub/sub patterns
+
+## Steps
+
+### 1. Identify Event Boundaries
+
+Define what constitutes an "event" in your system:
+- Events are **facts** about something that happened (past tense: `OrderPlaced`, `PaymentProcessed`)
+- Commands are **requests** for an action (present tense: `PlaceOrder`, `ProcessPayment`)
+- Events should be **immutable** once emitted
+
+### 2. Choose the Right Messaging Pattern
+
+| Pattern | Use Case | Examples |
+|---------|----------|----------|
+| Pub/Sub | One-to-many notification | Notifications, audit logs |
+| Message Queue | Point-to-point processing | Order processing, email sending |
+| Event Streaming | Durable, replayable event log | Event sourcing, analytics |
+| Webhooks | External system integration | HTTP callbacks |
+
+### 3. Design Event Schema
+
+```typescript
+interface Event<T> {
+  id: string;           // Unique event identifier (UUID)
+  type: string;         // Event type (e.g., "ORDER_PLACED")
+  version: string;      // Schema version for evolution
+  timestamp: string;    // ISO 8601 timestamp
+  source: string;       // Origin service name
+  data: T;             // Event payload
+  metadata?: Record<string, unknown>;  // Optional tracing/correlation
+}
+```
+
+### 4. Handle Eventual Consistency
+
+- Design consumers to be **idempotent** (safe to process twice)
+- Use **correlation IDs** to track event chains
+- Implement **dead letter queues** for failed processing
+- Set **retry policies** with exponential backoff
+
+### 5. Ensure Durability
+
+- Use persistent message storage (not in-memory)
+- Acknowledge messages only after successful processing
+- Implement **at-least-once** delivery semantics
+
+## Examples
+
+### TypeScript Event Emitter
+
+```typescript
+interface OrderEvent {
+  orderId: string;
+  customerId: string;
+  total: number;
+  items: OrderItem[];
+}
+
+class OrderEventPublisher {
+  private emitter: EventEmitter;
+
+  async publishOrderPlaced(event: OrderEvent): Promise<void> {
+    const message: Event<OrderEvent> = {
+      id: crypto.randomUUID(),
+      type: 'ORDER_PLACED',
+      version: '1.0',
+      timestamp: new Date().toISOString(),
+      source: 'order-service',
+      data: event,
+      metadata: {
+        correlationId: event.orderId,
+        partitionKey: event.customerId
+      }
+    };
+
+    await this.messageBroker.publish('orders.placed', message);
+  }
+}
+```
+
+### Message Consumer with Retry
+
+```typescript
+class OrderEventConsumer {
+  async handleOrderPlaced(event: Event<OrderEvent>): Promise<void> {
+    try {
+      // Idempotent processing
+      const existingOrder = await this.orderRepo.findById(event.data.orderId);
+      if (existingOrder) {
+        logger.info('Order already processed, skipping', { orderId: event.data.orderId });
+        return;
+      }
+
+      await this.orderService.processOrder(event.data);
+      await this.messageBroker.ack(event.id);
+    } catch (error) {
+      if (error instanceof TransientError) {
+        // Requeue with delay for retry
+        await this.messageBroker.requeue(event.id, { delay: 5000 });
+      } else {
+        // Send to dead letter queue
+        await this.messageBroker.sendToDlq(event, error);
+      }
+    }
+  }
+}
+```
+
+### Event Schema Registry
+
+```typescript
+// contracts/order-events.ts
+export const OrderPlacedEventSchema = {
+  type: 'object',
+  required: ['orderId', 'customerId', 'total', 'items'],
+  properties: {
+    orderId: { type: 'string', format: 'uuid' },
+    customerId: { type: 'string', format: 'uuid' },
+    total: { type: 'number', minimum: 0 },
+    items: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['productId', 'quantity', 'price'],
+        properties: {
+          productId: { type: 'string' },
+          quantity: { type: 'number', minimum: 1 },
+          price: { type: 'number', minimum: 0 }
+        }
+      }
+    }
+  }
+};
+```
+
+## Related Skills
+
+- api-design
+- backend-patterns
+- cqrs
+- event-sourcing
+- message-queues

package/src/skills/frontend-pattern/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: frontend-pattern
+description: Frontend development patterns — component composition, state management, URL-as-state, data fetching, and animation best practices for React/TypeScript web applications
+origin: FlowDeck
+---
+
+# Frontend Pattern Skill
+
+Implements maintainable, performant frontend patterns using React and TypeScript.
+
+## When to Activate
+
+Activate when:
+- Building new UI components
+- Setting up state management
+- Implementing data fetching
+- Adding animations or transitions
+- Structuring a new feature module
+
+## Component Patterns
+
+### Compound Components
+
+Use compound components when related UI shares state and interaction semantics:
+
+```tsx
+<Tabs defaultValue="overview">
+  <Tabs.List>
+    <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
+    <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="overview">...</Tabs.Content>
+  <Tabs.Content value="settings">...</Tabs.Content>
+</Tabs>
+```
+
+- Parent owns state via `useState` or context
+- Children consume via context — no prop drilling
+- Keeps keyboard handling, ARIA, and focus logic in the headless layer
+
+### Container / Presentational Split
+
+```tsx
+// Container — owns data loading and side effects
+function UserProfileContainer({ userId }: { userId: string }) {
+  const { data, isLoading } = useUser(userId);
+  if (isLoading) return <Skeleton />;
+  return <UserProfileView user={data} />;
+}
+
+// Presentational — receives props, renders UI
+function UserProfileView({ user }: { user: User }) {
+  return (
+    <div>
+      <Avatar src={user.avatar} />
+      <h1>{user.name}</h1>
+    </div>
+  );
+}
+```
+
+## State Management
+
+| Concern | Tooling |
+|---------|---------|
+| Server state | TanStack Query, SWR, tRPC |
+| Client state | Zustand, Jotai, signals |
+| URL state | search params, route segments |
+| Form state | React Hook Form or equivalent |
+
+**Do not duplicate server state into client stores.** Derive values instead of storing redundant computed state.
+
+## URL As State
+
+Persist shareable, bookmarkable state in the URL:
+
+```tsx
+// Good: filters, sort, pagination in URL
+const [searchParams, setSearchParams] = useSearchParams();
+const filter = searchParams.get('filter') ?? 'all';
+
+// Usage
+<button onClick={() => setSearchParams({ filter: 'active' })}>
+  Active
+</button>
+```
+
+## Data Fetching Patterns
+
+### Stale-While-Revalidate
+
+Return cached data immediately, revalidate in background:
+
+```tsx
+const { data } = useQuery({
+  queryKey: ['users', userId],
+  queryFn: () => fetchUser(userId),
+  staleTime: 5 * 60 * 1000, // 5 minutes
+});
+```
+
+### Optimistic Updates
+
+```tsx
+const mutation = useMutation({
+  mutationFn: updateUser,
+  onMutate: async (newData) => {
+    await queryClient.cancelQueries({ queryKey: ['user', newData.id] });
+    const previous = queryClient.getQueryData(['user', newData.id]);
+    queryClient.setQueryData(['user', newData.id], newData);
+    return { previous };
+  },
+  onError: (err, newData, context) => {
+    queryClient.setQueryData(['user', newData.id], context.previous);
+  },
+});
+```
+
+## CSS Custom Properties
+
+Define design tokens as CSS variables — do not hardcode values:
+
+```css
+:root {
+  --color-surface: oklch(98% 0 0);
+  --color-text: oklch(18% 0 0);
+  --color-accent: oklch(68% 0.21 250);
+
+  --text-base: clamp(1rem, 0.92rem + 0.4vw, 1.125rem);
+  --space-section: clamp(4rem, 3rem + 5vw, 10rem);
+
+  --duration-fast: 150ms;
+  --duration-normal: 300ms;
+  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+}
+```
+
+## Animation Guidelines
+
+Use compositor-friendly properties only:
+
+```
+✅ transform, opacity, clip-path, filter
+❌ width, height, top, left, margin, padding, border, font-size
+```
+
+```tsx
+// Good
+const style = { opacity: isVisible ? 1 : 0, transform: `translateY(${isVisible ? 0 : 20}px)` };
+
+// Bad
+const style = { height: isVisible ? 'auto' : 0 };
+```
+
+## Related Skills
+
+- [code-review](code-review) — Review frontend code for quality
+- [security-scan](security-scan) — Check for XSS and injection vulnerabilities
+- [test-coverage](test-coverage) — Ensure UI component tests exist

package/src/skills/hexagonal-architecture/SKILL.md

@@ -0,0 +1,80 @@
+# hexagonal-architecture
+
+## When to Activate
+When building applications that must remain flexible to changing external systems (databases, APIs, UI frameworks) and need to support multiple entry points (ports) for the same business logic.
+
+## Steps
+1. **Identify the core domain** - Isolate the pure business logic that makes no references to infrastructure.
+2. **Define inbound ports** - Create interfaces (ports) for primary/ driving actors (UI, API controllers) that trigger application logic.
+3. **Define outbound ports** - Create interfaces (ports) for secondary/ driven actors (databases, external services) that the domain calls.
+4. **Implement primary adapters** - Create adapters for inbound traffic (REST controllers, GraphQL resolvers, CLI commands).
+5. **Implement secondary adapters** - Create adapters for outbound traffic (Postgres repositories, Redis caches, email gateways).
+6. **Ensure domain has no external dependencies** - The domain layer should compile and run with no imports from adapters.
+7. **Wire via dependency injection** - Connect adapters to ports at application startup.
+
+## Examples
+```typescript
+// Domain Core - Pure business logic, no infrastructure dependencies
+class Transfer {
+  constructor(
+    public readonly fromAccountId: string,
+    public readonly toAccountId: string,
+    public readonly amount: number
+  ) {}
+
+  execute(accounts: Map<string, Account>): TransferResult {
+    const from = accounts.get(this.fromAccountId)
+    const to = accounts.get(this.toAccountId)
+
+    if (!from || !to) {
+      return TransferResult.failed('Account not found')
+    }
+
+    if (!from.canDebit(this.amount)) {
+      return TransferResult.failed('Insufficient funds')
+    }
+
+    from.debit(this.amount)
+    to.credit(this.amount)
+
+    return TransferResult.success()
+  }
+}
+
+// Inbound Port (Primary Port) - Interface for driving operations
+interface TransferUseCase {
+  execute(transfer: Transfer): TransferResult
+}
+
+// Outbound Port (Secondary Port) - Interface for driven operations
+interface AccountRepository {
+  findById(id: string): Promise<Account | null>
+  save(account: Account): Promise<void>
+}
+
+interface EventBus {
+  publish(event: DomainEvent): Promise<void>
+}
+
+// Primary Adapter - REST API
+class TransferController implements TransferUseCase {
+  constructor(private readonly accounts: AccountRepository) {}
+
+  async execute(transfer: Transfer): Promise<TransferResult> {
+    const allAccounts = await this.accounts.findById(transfer.fromAccountId)
+    // ... handle via injected port
+  }
+}
+
+// Secondary Adapter - PostgreSQL implementation
+class PostgresAccountRepository implements AccountRepository {
+  constructor(private readonly db: Database) {}
+  // ... implementation
+}
+```
+
+## Related Skills
+- clean-architecture
+- layered-architecture
+- ddd-architecture
+- backend-patterns

package/src/skills/layered-architecture/SKILL.md

@@ -0,0 +1,64 @@
+# layered-architecture
+
+## When to Activate
+When building traditional monolithic or client-server applications where clear vertical separation of concerns improves maintainability (e.g., MVC applications, REST APIs, data-driven apps).
+
+## Steps
+1. **Identify natural layers** - Determine the distinct vertical tiers based on responsibility (e.g., presentation, business logic, data access).
+2. **Define layer responsibilities** - Establish clear contracts for what each layer can and cannot depend on.
+3. **Implement top-down dependencies** - Higher layers (presentation) depend on lower layers (data), but never vice versa.
+4. **Create layer interfaces** - Use interfaces or abstract classes to define how adjacent layers communicate.
+5. **Enforce layer access rules** - Use module visibility, package private, or architectural linting tools to prevent cross-layer pollution.
+6. **Keep thin layers** - Avoid bloating any single layer; if the business logic layer grows large, consider extracting domain objects.
+
+## Examples
+```typescript
+// Presentation Layer - Controllers/Handlers
+class OrderController {
+  constructor(private readonly orderService: OrderService) {}
+
+  async createOrder(req: Request, res: Response): Promise<void> {
+    const order = await this.orderService.createOrder(req.body)
+    res.status(201).json(order)
+  }
+}
+
+// Business Logic Layer - Services
+class OrderService {
+  constructor(
+    private readonly orderRepository: OrderRepository,
+    private readonly paymentGateway: PaymentGateway
+  ) {}
+
+  async createOrder(data: CreateOrderDto): Promise<Order> {
+    const order = new Order(data.items)
+
+    if (data.paymentMethod === 'prepaid') {
+      await this.paymentGateway.charge(order.total, data.paymentToken)
+    }
+
+    return this.orderRepository.save(order)
+  }
+}
+
+// Data Access Layer - Repositories
+interface OrderRepository {
+  save(order: Order): Promise<void>
+  findById(id: string): Promise<Order | null>
+  findByCustomer(customerId: string): Promise<Order[]>
+}
+
+class PostgresOrderRepository implements OrderRepository {
+  constructor(private readonly db: Database) {}
+
+  async save(order: Order): Promise<void> {
+    await this.db.query('INSERT INTO orders (...) VALUES (...)', order.toDbFormat())
+  }
+}
+```
+
+## Related Skills
+- clean-architecture
+- hexagonal-architecture
+- ddd-architecture
+- backend-patterns

package/src/skills/postgres-patterns/SKILL.md

@@ -0,0 +1,74 @@
+# postgres-patterns
+
+## When to Activate
+When designing database schemas, writing complex queries, or optimizing database performance. Use before creating migrations or writing SQL queries.
+
+## Steps
+1. **Design indexes strategically** - Create individual btree indexes on each column for multi-column searches (allows BitmapAnd)
+2. **Use EXPLAIN ANALYZE** - Always verify query plans before and after optimization
+3. **Choose correct index type** - B-tree for equality/range, Bloom for multi-column filters with high selectivity
+4. **Avoid multi-column btree on non-leading columns** - Queries on non-first columns of multi-column btree indexes will do sequential scans
+5. **Use parameterized queries** - Let the planner cache and reuse query plans
+6. **Run ANALYZE regularly** - Keep statistics fresh for optimal planner decisions
+
+## Examples
+
+```sql
+-- AVOID: Multi-column btree for non-leading column queries
+CREATE INDEX btreeidx ON tbloom (i1, i2, i3, i4, i5, i6);
+-- Query on i2 and i5 will do sequential scan, not use the index
+
+-- PREFER: Individual btree indexes for multi-column searches
+CREATE INDEX btreeidx1 ON tbloom (i1);
+CREATE INDEX btreeidx2 ON tbloom (i2);
+CREATE INDEX btreeidx3 ON tbloom (i3);
+CREATE INDEX btreeidx4 ON tbloom (i4);
+CREATE INDEX btreeidx5 ON tbloom (i5);
+CREATE INDEX btreeidx6 ON tbloom (i6);
+-- Bitmap Index Scan with BitmapAnd is used for multi-column queries
+```
+
+```sql
+-- Bloom Index for multi-column filtering (good for low selectivity columns)
+CREATE INDEX bloomidx ON tbloom USING bloom (i1, i2, i3, i4, i5, i6);
+-- More efficient than btree for queries filtering on many columns
+-- Smaller index size, faster Bitmap Index Scans
+
+-- Always verify with EXPLAIN ANALYZE
+EXPLAIN ANALYZE SELECT * FROM tbloom WHERE i2 = 898732 AND i5 = 123451;
+```
+
+```sql
+-- Query Planner Configuration (temporary fix only)
+SET enable_hashjoin = off;           -- Force nested-loop or merge join
+SET enable_seqscan = off;           -- Prefer index scans
+SET random_page_cost = 1.1;         -- Make index scans cheaper (SSD)
+SET effective_cache_size = '8GB';   -- Help planner estimate
+
+-- Better approaches:
+-- 1. Run ANALYZE to update statistics
+ANALYZE;
+-- 2. Increase statistics for specific columns
+ALTER TABLE orders SET STATISTICS = 500;
+ANALYZE orders;
+-- 3. Adjust planner cost constants (postgresql.conf)
+```
+
+```sql
+-- Repository Pattern in SQL
+-- Define standard operations
+interface OrderRepository {
+  findAll(filter: OrderFilter, pagination: Pagination): Promise<Order[]>;
+  findById(id: string): Promise<Order | null>;
+  create(order: CreateOrderDTO): Promise<Order>;
+  update(id: string, attributes: UpdateOrderDTO): Promise<Order>;
+  delete(id: string): Promise<void>;
+  count(filter?: OrderFilter): Promise<number>;
+}
+```
+
+## Related Skills
+- api-design
+- backend-patterns
+- database-migrations
+- postgres-performance

package/src/skills/python-patterns/SKILL.md

@@ -527,3 +527,8 @@ def get_thing():
 
 # ✅ Or restructure: extract shared types into a third module
 ```
+
+## Related Skills
+- backend-patterns
+- django-patterns
+- python-testing

package/src/skills/saga-architecture/SKILL.md

@@ -0,0 +1,113 @@
+# saga-architecture
+
+## When to Activate
+When coordinating distributed operations across multiple services or data stores where ACID transactions are not available and compensating actions are needed to maintain eventual consistency.
+
+## Steps
+1. **Identify the saga participants** - Determine which services or components participate in the distributed operation.
+2. **Define the saga choreography or orchestration** - Choose whether sagas will be choreographed (event-driven) or orchestrated (central coordinator).
+3. **Define each step with corresponding compensation** - For every forward action, define what compensating action undoes it.
+4. **Implement idempotent operations** - Ensure each step can be safely retried and compensation can be safely reapplied.
+5. **Handle saga failures with compensation** - On failure, execute compensations in reverse order (for orchestrating sagas) or react to failure events (for choreographing sagas).
+6. **Persist saga state** - Store saga state to survive process crashes and enable recovery.
+7. **Add timeout and retry logic** - Detect stuck sagas and advance or compensate accordingly.
+
+## Examples
+```typescript
+// Saga State
+interface SagaState<T> {
+  id: string
+  currentStep: number
+  data: T
+  status: 'pending' | 'in_progress' | 'completed' | 'compensating' | 'failed'
+}
+
+// Orchestrating Saga - Central coordinator manages steps
+class OrderProcessingSaga {
+  private readonly steps: SagaStep[]
+
+  constructor(
+    private readonly sagaOrchestrator: SagaOrchestrator,
+    private readonly inventoryService: InventoryService,
+    private readonly paymentService: PaymentService,
+    private readonly shippingService: ShippingService
+  ) {
+    this.steps = [
+      {
+        name: 'reserve_inventory',
+        execute: (state) => this.inventoryService.reserve(state.orderId, state.items),
+        compensate: (state) => this.inventoryService.release(state.orderId, state.items)
+      },
+      {
+        name: 'process_payment',
+        execute: (state) => this.paymentService.charge(state.orderId, state.total),
+        compensate: (state) => this.paymentService.refund(state.orderId, state.total)
+      },
+      {
+        name: 'initiate_shipping',
+        execute: (state) => this.shippingService.createShipment(state.orderId),
+        compensate: (state) => this.shippingService.cancelShipment(state.shipmentId)
+      }
+    ]
+  }
+
+  async execute(orderId: string): Promise<void> {
+    const state: SagaState<OrderSagaData> = {
+      id: generateId(),
+      currentStep: 0,
+      data: { orderId, items: [], total: 0 },
+      status: 'in_progress'
+    }
+
+    await this.sagaOrchestrator.start(state, this.steps)
+  }
+}
+
+// Choreography-based Saga - Events trigger reactions
+class OrderCreatedHandler {
+  constructor(private readonly eventBus: EventBus) {}
+
+  async handle(event: OrderCreatedEvent): Promise<void> {
+    // Step 1: Reserve inventory
+    try {
+      await this.inventoryService.reserve(event.orderId, event.items)
+      this.eventBus.publish(new InventoryReservedEvent(event.orderId))
+    } catch (error) {
+      this.eventBus.publish(new InventoryReservationFailedEvent(event.orderId, error.message))
+    }
+  }
+}
+
+class InventoryReservedHandler {
+  async handle(event: InventoryReservedEvent): Promise<void> {
+    // Step 2: Process payment
+    try {
+      await this.paymentService.charge(event.orderId, event.total)
+      this.eventBus.publish(new PaymentProcessedEvent(event.orderId))
+    } catch (error) {
+      // Compensate by releasing inventory
+      this.eventBus.publish(new InventoryReleaseRequestedEvent(event.orderId))
+    }
+  }
+}
+
+// Idempotent Step Implementation
+class PaymentService {
+  async charge(orderId: string, amount: Money): Promise<TransactionId> {
+    const existingTx = await this.transactionRepo.findByOrderId(orderId)
+    if (existingTx) {
+      return existingTx.id // Idempotent: return existing instead of charging again
+    }
+
+    const transaction = await this.paymentGateway.charge(amount)
+    await this.transactionRepo.save({ orderId, transaction })
+    return transaction.id
+  }
+}
+```
+
+## Related Skills
+- clean-architecture
+- hexagonal-architecture
+- ddd-architecture
+- backend-patterns

package/dist/tools/run-parallel.d.ts

@@ -1,4 +0,0 @@
-import { type ToolDefinition } from "@opencode-ai/plugin";
-import type { OpencodeClient } from "@opencode-ai/sdk";
-export declare function createRunParallelTool(client: OpencodeClient): ToolDefinition;
-//# sourceMappingURL=run-parallel.d.ts.map

package/dist/tools/run-parallel.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"run-parallel.d.ts","sourceRoot":"","sources":["../../src/tools/run-parallel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAsBtD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAiK5E"}