@dv.nghiem/flowdeck 0.2.4 → 0.3.0

package/src/skills/agent-harness-construction/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: agent-harness-construction
+description: Build autonomous agent pipelines — construct agent loops, wire multi-agent orchestration, implement self-healing retry logic, and measure agent effectiveness
+origin: FlowDeck
+---
+
+# Agent Harness Construction Skill
+
+Constructs autonomous agent pipelines that can plan, execute, self-correct, and measure their own effectiveness.
+
+## When to Activate
+
+Activate when:
+- Building multi-agent orchestration systems
+- Implementing autonomous loops (self-correcting agents)
+- Designing agent retry and self-healing policies
+- Wiring agent-to-agent communication
+- Measuring and optimizing agent effectiveness
+
+## Agent Loop Architecture
+
+### Core Loop Pattern
+
+```
+┌─────────────────────────────────────────────┐
+│  1. OBSERVE    → Gather context state       │
+│  2. THINK      → Plan next action           │
+│  3. ACT        → Execute tool call          │
+│  4. EVALUATE   → Check result quality       │
+│  5. ADAPT      → Retry or proceed            │
+└─────────────────────────────────────────────┘
+```
+
+```typescript
+interface AgentLoop {
+  observe: () => Promise<Context>;
+  think: (ctx: Context) => Promise<Plan>;
+  act: (plan: Plan) => Promise<Result>;
+  evaluate: (result: Result) => Evaluation;
+  adapt: (evaluation: Evaluation) => 'continue' | 'retry' | 'complete';
+}
+```
+
+### Self-Healing Retry Logic
+
+```typescript
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: {
+    maxAttempts?: number;
+    backoff?: 'linear' | 'exponential';
+    onRetry?: (attempt: number, error: Error) => void;
+  } = {}
+): Promise<T> {
+  const { maxAttempts = 3, backoff = 'exponential', onRetry } = options;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt === maxAttempts) throw error;
+      const delay = backoff === 'exponential'
+        ? Math.pow(2, attempt - 1) * 1000
+        : attempt * 1000;
+      onRetry?.(attempt, error as Error);
+      await sleep(delay);
+    }
+  }
+  throw new Error('unreachable');
+}
+```
+
+## Multi-Agent Orchestration
+
+### Supervisor Pattern
+
+```typescript
+interface AgentMessage {
+  from: string;
+  to: string;
+  type: 'request' | 'response' | 'delegate' | 'result';
+  payload: unknown;
+  traceId: string;
+}
+
+class SupervisorAgent {
+  private agents: Map<string, Agent>;
+  private messageQueue: AgentMessage[] = [];
+
+  async delegate(task: Task, targetAgent: string): Promise<Result> {
+    const message: AgentMessage = {
+      from: this.id,
+      to: targetAgent,
+      type: 'delegate',
+      payload: task,
+      traceId: generateTraceId(),
+    };
+    return this.sendAndWait(message);
+  }
+
+  async parallelDelegate(tasks: Task[], agents: string[]): Promise<Result[]> {
+    return Promise.all(
+      tasks.map((task, i) => this.delegate(task, agents[i % agents.length]))
+    );
+  }
+}
+```
+
+### Council Pattern
+
+Multiple agents deliberate and vote on a decision:
+
+```typescript
+interface CouncilMember {
+  id: string;
+  specialty: 'security' | 'performance' | 'correctness';
+  vote: (proposal: Proposal) => Promise<Vote>;
+}
+
+interface CouncilDecision {
+  votes: Vote[];
+  decision: 'approve' | 'reject' | 'revise';
+  consensus: number; // 0-1
+}
+
+async function councilDeliberate(
+  proposal: Proposal,
+  members: CouncilMember[]
+): Promise<CouncilDecision> {
+  const votes = await Promise.all(members.map(m => m.vote(proposal)));
+  const approvals = votes.filter(v => v.approve).length;
+  const consensus = approvals / votes.length;
+
+  return {
+    votes,
+    decision: consensus >= 0.7 ? 'approve' : consensus >= 0.4 ? 'revise' : 'reject',
+    consensus,
+  };
+}
+```
+
+## Agent Effectiveness Measurement
+
+### Trace-Based Metrics
+
+```typescript
+interface AgentTrace {
+  traceId: string;
+  agentId: string;
+  spans: {
+    name: string;
+    startTime: number;
+    endTime: number;
+    success: boolean;
+    tokensUsed?: number;
+    error?: string;
+  }[];
+  outcome: 'success' | 'failure' | 'timeout';
+}
+
+// Track effectiveness
+function measureAgentEffectiveness(traces: AgentTrace[]): AgentMetrics {
+  return {
+    successRate: traces.filter(t => t.outcome === 'success').length / traces.length,
+    avgDuration: traces.reduce((sum, t) => {
+      const duration = t.spans[t.spans.length - 1].endTime - t.spans[0].startTime;
+      return sum + duration;
+    }, 0) / traces.length,
+    avgTokensPerTask: traces.reduce((sum, t) =>
+      sum + (t.spans.reduce((s, span) => s + (span.tokensUsed ?? 0), 0) / t.spans.length), 0
+    ) / traces.length,
+    retryRate: traces.filter(t => t.spans.some(s => s.name === 'retry')).length / traces.length,
+  };
+}
+```
+
+## Error Classification
+
+```typescript
+type ErrorCategory =
+  | 'transient'     // Network blip, timeout — retry eligible
+  | 'recoverable'   // Missing context, bad input — can fix with adaptation
+  | 'fatal';        // Auth failure, permission — cannot proceed
+
+function classifyError(error: Error): ErrorCategory {
+  if (error.message.includes('timeout') || error.message.includes('ECONNREFUSED')) {
+    return 'transient';
+  }
+  if (error.message.includes('invalid input') || error.message.includes('missing context')) {
+    return 'recoverable';
+  }
+  return 'fatal';
+}
+```
+
+## Self-Healing Policies
+
+```typescript
+interface HealingPolicy {
+  trigger: (error: Error) => boolean;
+  action: (context: AgentContext) => Promise<Action>;
+}
+
+const healingPolicies: HealingPolicy[] = [
+  {
+    trigger: (e) => e.message.includes('rate limit'),
+    action: async (ctx) => {
+      ctx.throttleDelay = Math.min(ctx.throttleDelay * 2, 60000);
+      return { type: 'backoff', delay: ctx.throttleDelay };
+    },
+  },
+  {
+    trigger: (e) => e.message.includes('context too long'),
+    action: async (ctx) => {
+      ctx.summarizeOlderHistory();
+      return { type: 'compact' };
+    },
+  },
+];
+```
+
+## Related Skills
+
+- [self-healing-policies](self-healing-policies) — Define recovery policies
+- [agent-introspection-debugging](agent-introspection-debugging) — Debug agent issues
+- [eval-harness](eval-harness) — Evaluate agent performance
+- [continuous-agent-loop](continuous-agent-loop) — Maintain persistent agent sessions

package/src/skills/api-design/SKILL.md

@@ -141,3 +141,8 @@ X-RateLimit-Reset: 1609459200
 ```
 
 Return 429 when limit exceeded with `Retry-After` header.
+
+## Related Skills
+- backend-patterns
+- postgres-patterns
+- api-connector-builder

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

@@ -0,0 +1,105 @@
+# backend-patterns
+
+## When to Activate
+When implementing backend services, APIs, or server-side logic. Use when designing service layers, data access patterns, or middleware.
+
+## Steps
+1. **Identify the service layer** - Determine if you need a service layer to orchestrate business logic
+2. **Apply Repository Pattern** - Encapsulate data access behind repository interfaces for testability
+3. **Use Dependency Injection** - Pass dependencies explicitly rather than creating them inside classes
+4. **Implement error handling** - Add comprehensive error handling with appropriate HTTP status codes
+5. **Add middleware/logging** - Log requests, responses, and errors consistently
+
+## Examples
+
+```typescript
+// Service Layer with Repository Pattern
+interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  findAll(filter?: UserFilter): Promise<User[]>;
+  create(attributes: CreateUserDTO): Promise<User>;
+  update(id: string, attributes: UpdateUserDTO): Promise<User>;
+  delete(id: string): Promise<void>;
+}
+
+class UserService {
+  constructor(private readonly userRepository: UserRepository) {}
+
+  async getUser(id: string): Promise<User> {
+    const user = await this.userRepository.findById(id);
+    if (!user) {
+      throw new NotFoundError(`User with id ${id} not found`);
+    }
+    return user;
+  }
+
+  async createUser(dto: CreateUserDTO): Promise<User> {
+    const existing = await this.userRepository.findByEmail(dto.email);
+    if (existing) {
+      throw new ConflictError('User with this email already exists');
+    }
+    return this.userRepository.create(dto);
+  }
+}
+
+// Dependency Injection Container
+const container = new Container();
+container.register('userRepository', () => new PostgresUserRepository());
+container.register('userService', () => new UserService(container.resolve('userRepository')));
+```
+
+```typescript
+// Error Handling with Custom Exceptions
+class AppError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode: number = 500
+  ) {
+    super(message);
+    this.name = 'AppError';
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(message: string) {
+    super(message, 'NOT_FOUND', 404);
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(
+    message: string,
+    public readonly details?: Record<string, string[]>
+  ) {
+    super(message, 'VALIDATION_ERROR', 422);
+  }
+}
+
+// Global Error Handler Middleware
+function errorHandler(err: Error, req: Request, res: Response, next: NextFunction) {
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      error: {
+        code: err.code,
+        message: err.message,
+        details: err instanceof ValidationError ? err.details : undefined,
+      },
+    });
+  }
+  console.error('Unhandled error:', err);
+  return res.status(500).json({
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'An unexpected error occurred',
+    },
+  });
+}
+```
+
+## Related Skills
+- api-design
+- postgres-patterns
+- python-patterns
+- layered-architecture
+- ddd-architecture

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

@@ -0,0 +1,85 @@
+# clean-architecture
+
+## When to Activate
+When designing or implementing a new feature or service that needs clear separation of concerns, testability, and independence from frameworks, databases, or UI libraries.
+
+## Steps
+1. **Identify the core business logic** - Determine the essential domain rules that would exist even if the application had no UI, database, or external services.
+2. **Define the boundary** - Draw a clear boundary between the inner circles (entities, use cases) and outer circles (interfaces, infrastructure).
+3. **Place dependencies pointing inward** - Dependencies should always point toward the center. The inner circle knows nothing about the outer circle.
+4. **Define ports (interfaces)** - Create interfaces in the domain layer that define how the outside world can interact with it.
+5. **Implement adapters** - Create concrete implementations (adapters) for databases, web frameworks, external APIs, etc. in the outer layers.
+6. **Wire everything via dependency injection** - Use a composition root or DI container to assemble the application.
+
+## Examples
+```typescript
+// Domain Layer - Enterprise Business Rules (innermost circle)
+class Order {
+  constructor(
+    private readonly id: string,
+    private readonly items: OrderItem[],
+    private readonly status: OrderStatus
+  ) {}
+
+  get total(): number {
+    return this.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
+  }
+
+  canBeFulfilled(): boolean {
+    return this.status === 'pending' && this.items.length > 0
+  }
+}
+
+// Application Layer - Application Business Rules
+interface OrderRepository {
+  findById(id: string): Promise<Order | null>
+  save(order: Order): Promise<void>
+}
+
+interface NotificationService {
+  sendOrderConfirmation(order: Order): Promise<void>
+}
+
+class PlaceOrderUseCase {
+  constructor(
+    private readonly orderRepo: OrderRepository,
+    private readonly notifier: NotificationService
+  ) {}
+
+  async execute(orderData: OrderData): Promise<Order> {
+    const order = new Order(orderData.id, orderData.items, 'pending')
+
+    if (!order.canBeFulfilled()) {
+      throw new InvalidOrderError('Order cannot be fulfilled')
+    }
+
+    await this.orderRepo.save(order)
+    await this.notifier.sendOrderConfirmation(order)
+
+    return order
+  }
+}
+
+// Infrastructure Layer - Interface Adapters (outermost circle)
+class PostgresOrderRepository implements OrderRepository {
+  async findById(id: string): Promise<Order | null> {
+    // Database implementation
+  }
+
+  async save(order: Order): Promise<void> {
+    // Database implementation
+  }
+}
+
+class EmailNotificationService implements NotificationService {
+  async sendOrderConfirmation(order: Order): Promise<void> {
+    // Email implementation
+  }
+}
+```
+
+## Related Skills
+- layered-architecture
+- hexagonal-architecture
+- ddd-architecture
+- backend-patterns

package/src/skills/cqrs/SKILL.md

@@ -0,0 +1,230 @@
+# CQRS (Command Query Responsibility Segregation)
+
+## When to Activate
+
+Activate when:
+- Designing read-heavy or write-heavy systems separately
+- Implementing complex domain models with divergent read/write logic
+- Building systems that need different data representations for reading vs. writing
+- Scaling read and write workloads independently
+- Implementing event sourcing alongside specialized read models
+
+## Steps
+
+### 1. Separate Command and Query Models
+
+| Aspect | Command | Query |
+|--------|---------|-------|
+| Purpose | Modify state | Read state |
+| Returns | Void / ACK | Data |
+| Side Effects | Yes | No |
+| Complexity | Business logic | Data shaping |
+
+Commands and queries should use **different models** with different schemas optimized for their specific use case.
+
+### 2. Design Command Side
+
+- Commands are **intent-based** (present tense: `PlaceOrder`, `UpdatePrice`)
+- Validate business rules **before** executing
+- Return success/failure, not data
+- Keep command handlers small and focused
+
+```typescript
+interface Command {
+  id: string;          // Correlation ID
+  type: string;        // Command type
+  payload: unknown;    // Command data
+  metadata: {
+    userId: string;
+    timestamp: string;
+    correlationId: string;
+  };
+}
+
+interface CommandHandler<T extends Command> {
+  execute(command: T): Promise<CommandResult>;
+}
+```
+
+### 3. Design Query Side
+
+- Queries are **data-focused** (past/read tense: `GetUserOrders`, `FindActiveProducts`)
+- Queries should be **side-effect free**
+- Return **read-optimized** data structures (possibly denormalized)
+- Support pagination, filtering, sorting
+
+```typescript
+interface Query {
+  id: string;
+  type: string;
+  parameters: Record<string, unknown>;
+  pagination?: { page: number; limit: number };
+  sorting?: { field: string; direction: 'asc' | 'desc' }[];
+}
+
+interface QueryHandler<T extends Query> {
+  execute(query: T): Promise<QueryResult>;
+}
+```
+
+### 4. Implement Synchronization
+
+When commands and queries share data:
+
+1. **Synchronous** (same DB): Update the read model transactionally
+2. **Asynchronous** (event-driven): Project events to read models
+3. **Dual writes**: Update both models, handle eventual consistency
+
+```typescript
+// Synchronous synchronization
+async function placeOrder(command: PlaceOrderCommand): Promise<void> {
+  const order = Order.create(command.payload);
+
+  await this.transactionManager.execute(async (tx) => {
+    // Write to command model
+    await this.orderRepo.save(order, tx);
+
+    // Synchronize to read model
+    const readModel = {
+      orderId: order.id,
+      customerId: order.customerId,
+      status: order.status,
+      total: order.total,
+      placedAt: order.placedAt
+    };
+    await this.orderReadRepo.save(readModel, tx);
+  });
+}
+```
+
+### 5. Handle Eventual Consistency
+
+If read and write models are updated asynchronously:
+
+- Document **expected consistency lag**
+- Design UIs to handle stale data gracefully
+- Implement **cache invalidation** strategies
+- Use **version numbers** or timestamps for cache validation
+
+## Examples
+
+### Command Implementation
+
+```typescript
+// commands/place-order.command.ts
+interface PlaceOrderCommand {
+  orderId?: string;        // Optional, generated if not provided
+  customerId: string;
+  items: OrderItem[];
+  paymentMethod: 'CARD' | 'PAYPAL';
+}
+
+class PlaceOrderCommandHandler implements CommandHandler<PlaceOrderCommand> {
+  async execute(command: PlaceOrderCommand): Promise<CommandResult> {
+    // 1. Validate command
+    const validation = this.validate(command);
+    if (!validation.success) {
+      return CommandResult.failure(validation.errors);
+    }
+
+    // 2. Check business invariants
+    const customer = await this.customerRepo.findById(command.customerId);
+    if (!customer.isActive) {
+      return CommandResult.failure('Customer account is not active');
+    }
+
+    // 3. Create aggregate
+    const order = Order.create({
+      id: command.orderId,
+      customerId: command.customerId,
+      items: command.items
+    });
+
+    // 4. Persist
+    await this.orderRepo.save(order);
+
+    // 5. Emit event for async processing
+    await this.eventBus.publish(OrderPlacedEvent.fromOrder(order));
+
+    return CommandResult.success({ orderId: order.id });
+  }
+}
+```
+
+### Query Implementation
+
+```typescript
+// queries/get-order-details.query.ts
+interface GetOrderDetailsQuery {
+  orderId: string;
+  includeItems?: boolean;
+}
+
+interface OrderDetailsReadModel {
+  orderId: string;
+  customerId: string;
+  customerName: string;
+  status: string;
+  total: number;
+  placedAt: string;
+  items?: OrderItemReadModel[];
+}
+
+class GetOrderDetailsQueryHandler implements QueryHandler<GetOrderDetailsQuery, OrderDetailsReadModel> {
+  async execute(query: GetOrderDetailsQuery): Promise<OrderDetailsReadModel> {
+    const order = await this.readModelRepo.findOrderWithDetails(query.orderId);
+
+    if (!order) {
+      throw new QueryNotFoundError('Order not found');
+    }
+
+    const result: OrderDetailsReadModel = {
+      orderId: order.orderId,
+      customerId: order.customerId,
+      customerName: order.customerName,
+      status: order.status,
+      total: order.total,
+      placedAt: order.placedAt
+    };
+
+    if (query.includeItems) {
+      result.items = await this.readModelRepo.findOrderItems(query.orderId);
+    }
+
+    return result;
+  }
+}
+```
+
+### Mediator Pattern for CQRS
+
+```typescript
+class CqrsMediator {
+  private commandHandlers: Map<string, CommandHandler<any>>;
+  private queryHandlers: Map<string, QueryHandler<any>>;
+
+  async send<T>(message: Command | Query): Promise<CommandResult | QueryResult> {
+    const handler = message instanceof Command
+      ? this.commandHandlers.get(message.type)
+      : this.queryHandlers.get(message.type);
+
+    if (!handler) {
+      throw new HandlerNotFoundError(message.type);
+    }
+
+    return handler.execute(message);
+  }
+}
+
+// Usage
+const result = await mediator.send(new PlaceOrderCommand({ ... }));
+const orderDetails = await mediator.send(new GetOrderDetailsQuery({ orderId: '123' }));
+```
+
+## Related Skills
+
+- api-design
+- event-driven-architecture
+- backend-patterns
+- event-sourcing
+- hexagonal-architecture