@dv.nghiem/flowdeck 0.2.3 → 0.3.0

package/src/commands/fd-status.md

@@ -0,0 +1,84 @@
+---
+description: View project status — combined status, roadmap, workspace overview, and progress
+argument-hint: [--roadmap | --workspace | --phase=N]
+---
+
+# Status
+
+View project status combining progress, roadmap, and workspace overview.
+
+**Input:** $ARGUMENTS — optional flags
+
+## Modes
+
+### Default (no flags)
+
+Read `.planning/STATE.md` and display combined status:
+
+```
+════════════════════════════════════════════════════════════
+Phase: <N>  |  Status: <status>  |  Updated: <timestamp>
+────────────────────────────────────────────────────────────
+Plan: <X> steps (<Y> complete)
+Plan confirmed: <yes/no>
+════════════════════════════════════════════════════════════
+```
+
+### Roadmap (`--roadmap`)
+
+Display project roadmap with phase statuses:
+
+```
+═══════════════════════════════════════
+PROJECT ROADMAP
+═══════════════════════════════════════
+  ✅ Phase 1: <name> — completed
+  🔄 Phase 2: <name> — in progress  ← current
+  ⏳ Phase 3: <name> — planned
+═══════════════════════════════════════
+```
+
+Read from `.planning/ROADMAP.md` and `.planning/STATE.md`.
+
+### Workspace (`--workspace`)
+
+Display overview of all registered repositories:
+
+```
+════════════════════════════════════════════════════
+WORKSPACE OVERVIEW
+════════════════════════════════════════════════════
+  frontend   — Phase 2 | in_progress  | Plan: ✅ | Updated: <time>
+  backend    — Phase 3 | completed    | Plan: ✅ | Updated: <time>
+  shared     — Phase 1 | planned      | Plan: ❌ | Updated: <time>
+────────────────────────────────────────────────────
+Total: 3 repos | 1 in progress | 1 completed | 1 planned
+════════════════════════════════════════════════════
+```
+
+Read from `.planning/config.json` for repo list, each repo's STATE.md for phase/status.
+
+### Phase Detail (`--phase=N`)
+
+Show detailed progress for a specific phase:
+
+```
+════════════════════════════════════════════════════════════
+PHASE <N> DETAIL
+════════════════════════════════════════════════════════════
+Status: <status>
+Plan file: <path>
+Plan confirmed: <yes/no>
+
+Steps:
+  ✅ Step 1: <name> — completed
+  🔄 Step 2: <name> — in progress
+  ⬜ Step 3: <name> — pending
+  ⬜ Step 4: <name> — pending
+════════════════════════════════════════════════════════════
+```
+
+## Error Handling
+
+- If `.planning/STATE.md` not found: "No active project. Run /fd-new-project first."
+- If `--phase` requested but phase directory doesn't exist: "Phase N not found."

package/src/commands/fd-write-docs.md

@@ -5,46 +5,78 @@ argument-hint: [--scope=path | --format=api,guide,readme]
 
 # Write Docs
 
-Generate documentation for the codebase or a specific scope.
+Generate accurate, up-to-date documentation from the codebase.
 
 **Input:** $ARGUMENTS — optional `--scope=<path>` and `--format=<type>`
 
 Supported formats: `api` (API reference), `guide` (usage guide), `readme` (README)  
 Default: all formats
 
-## Pipeline
+## Process
 
-### Phase 1 — Explore
+### Step 1: Explore APIs
 
-- **@researcher**: Find all public APIs, exported functions, classes, types, and their signatures
-- **@code-explorer**: Identify existing documentation, JSDoc comments, README sections
+Spawn `@mapper` to:
+- Find all exported functions, classes, and types
+- Identify public API entry points
+- Map key workflows and integration points
 
-### Phase 2 — Draft
+```bash
+# Find exports
+grep -rn "export " src/ --include="*.ts"
+# Find public interfaces
+grep -rn "export interface\|export type\|export class" src/ --include="*.ts"
+```
 
-- **@writer**: Draft documentation based on the exploration findings
-  - API docs: function signatures, parameters, return types, examples
-  - Guides: usage examples, step-by-step instructions
-  - README: project overview, install, quickstart, API summary
+### Step 2: Draft Documentation
 
-### Phase 3 — Review
+Spawn `@writer` to produce:
 
-- **@reviewer**: Check accuracy — verify all documented APIs exist and signatures are correct
-  - Flag any documentation that contradicts the implementation
-  - Flag missing documentation for public APIs
+**API Reference**
+```markdown
+## functionName(param: Type): ReturnType
 
-### Phase 4 — Finalize
+Description of what the function does.
 
-- **@writer**: Apply reviewer corrections, finalize and write documentation files
+**Parameters:**
+- `param` (Type) — description
 
-## Output Files
+**Returns:** description
 
-Based on `--format`:
-- `api` → writes or updates `docs/API.md`
-- `guide` → writes or updates `docs/GUIDE.md`
-- `readme` → updates `README.md`
+**Example:**
+\`\`\`typescript
+const result = functionName(value);
+\`\`\`
+```
 
-If `--scope` is set, documentation applies only to files within that path.
+**Usage Guide**
+- Step-by-step workflow with examples
+- Common patterns and best practices
+- Configuration options
 
-## Completion
+**Troubleshooting**
+- Common errors and their solutions
+
+### Step 3: Review for Accuracy
+
+Spawn `@reviewer` to verify:
+- Every documented function/method actually exists
+- Parameter types match the actual signatures
+- Examples are syntactically correct
+- No outdated API references
+
+### Step 4: Finalize
+
+Writer incorporates feedback and writes final docs to:
+- `README.md` — project overview and quick start
+- `docs/API.md` — complete API reference
+- `docs/USER_GUIDE.md` — detailed usage guide
+
+## Output
+
+Updated documentation files with:
+- Accurate function signatures
+- Working code examples
+- Clear explanations of behavior
 
 Report: files written/updated, public APIs documented, any gaps found.

package/src/rules/README.md

@@ -2,22 +2,23 @@
 
 Coding standards for projects using FlowDeck. These define conventions that FlowDeck agents follow automatically.
 
-## How to Use
+## How It Works
 
-Add a rule file to `opencode.json` under `instructions`:
+Rules are loaded **automatically** by the FlowDeck plugin. No manual configuration is needed — when FlowDeck is installed, all rule files in this directory are injected into OpenCode's `instructions` at startup.
+
+## Selective Rules (Optional)
+
+If you want to override the default set and load only specific rules, add them to `opencode.json` under `instructions`:
 
 ```json
 {
   "instructions": [
-    ".flowdeck/rules/common/coding-style.md",
-    ".flowdeck/rules/common/security.md",
-    ".flowdeck/rules/typescript/patterns.md"
+    "node_modules/@dv.nghiem/flowdeck/src/rules/common/coding-style.md",
+    "node_modules/@dv.nghiem/flowdeck/src/rules/typescript/patterns.md"
   ]
 }
 ```
 
-Agents will read these files and follow the conventions defined in them.
-
 ## Available Rules
 
 ### Common Rules (language-agnostic)

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