@dv.nghiem/flowdeck 0.2.3 → 0.3.0

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;AAkBtD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CA8G5E"}

package/docs/command-migration.md

@@ -1,175 +0,0 @@
-# Command Architecture & Migration Guide
-
-FlowDeck v2 consolidates seven individual analysis commands into four umbrella commands, reducing the top-level command surface while keeping all capabilities. The 15 workflow commands remain as separate top-level slash commands.
-
----
-
-## Command Map
-
-### Workflow commands (unchanged — 15 total)
-
-These remain as separate top-level commands:
-
-| Command | Purpose |
-|---------|---------|
-| `/fd-new-project` | Bootstrap a new project |
-| `/fd-map-codebase` | Analyse and index the codebase |
-| `/fd-settings` | Configure FlowDeck settings |
-| `/fd-discuss` | Pre-planning discussion with impact radar |
-| `/fd-plan` | Generate a phase plan |
-| `/fd-roadmap` | View / update project roadmap |
-| `/fd-dashboard` | Visual progress dashboard |
-| `/fd-ask` | Smart agent dispatch |
-| `/fd-new-feature` | Implement a new feature |
-| `/fd-fix-bug` | Fix a bug with failure replay |
-| `/fd-review-code` | Code review with impact radar |
-| `/fd-write-docs` | Generate documentation |
-| `/fd-deploy-check` | Pre-deploy safety check |
-| `/fd-progress` | View project progress |
-| `/fd-checkpoint` | Save a session checkpoint |
-| `/fd-resume` | Resume from checkpoint |
-| `/fd-multi-repo` | Multi-repo management |
-
-### Analysis commands — old → new mapping
-
-| Old command | New umbrella command | Flag |
-|-------------|---------------------|------|
-| `/fd-impact-radar` | `/fd-analyze-change` | `--impact` |
-| `/fd-blast-radius` | `/fd-analyze-change` | `--blast-radius` |
-| `/fd-regression-predict` | `/fd-analyze-change` | `--regression` |
-| `/fd-test-gap` | `/fd-analyze-change` | `--test-gap` |
-| `/fd-volatility-map` | `/fd-analyze-change` | `--volatility` |
-| `/fd-review-route` | `/fd-analyze-change` | `--review-route` |
-| `/fd-translate-intent` | `/fd-translate-intent` | *(enhanced, kept as-is)* |
-| *(new)* | `/fd-guarded-edit` | — |
-| *(new)* | `/fd-evaluate-risk` | — |
-
-### New umbrella commands (4 total)
-
-| Command | Replaces / Adds |
-|---------|----------------|
-| `/fd-analyze-change` | Combines 6 analysis commands; `--all` runs all modules |
-| `/fd-guarded-edit` | New — edit gate decision (auto/confirm/review/block) |
-| `/fd-evaluate-risk` | New — standalone risk + regression assessment |
-| `/fd-translate-intent` | Enhanced — adds `assumptions`, `recommended_option`, `clarifying_questions` |
-
----
-
-## Architecture
-
-### Command layer
-
-Commands are thin entry points that dispatch to agent pipelines or shared utilities. No analysis logic lives inside command files.
-
-```
-User runs: /fd-analyze-change --change "..." --impact --regression
-     ↓
-analyzeChangeCommand.execute()
-     ↓
-  reads: VOLATILITY.json, FAILURES.json, MEMORY.json via shared libs
-  calls: runImpactRadar(), scorePatch()
-     ↓
-  returns: unified config object with agent pipeline + aggregated data
-```
-
-### Agent layer
-
-Agents are modular and reusable across commands:
-
-| Agent | Used by |
-|-------|---------|
-| `architect` | `/fd-analyze-change`, `/fd-translate-intent`, `/fd-plan` |
-| `researcher` | `/fd-analyze-change`, `/fd-evaluate-risk`, `/fd-discuss` |
-| `tester` | `/fd-analyze-change` |
-| `reviewer` | `/fd-analyze-change`, `/fd-evaluate-risk`, `/fd-review-code` |
-| `security-auditor` | `/fd-evaluate-risk` (high/critical risk), `/fd-review-code` |
-| `risk-analyst` | `/fd-evaluate-risk`, `/fd-guarded-edit` |
-| `policy-enforcer` | `/fd-guarded-edit` |
-
-### Plugin hooks
-
-Hooks intercept tool execution and enforce safety policies at the infrastructure layer:
-
-| Hook | Function |
-|------|---------|
-| `tool.execute.before` | `toolGuardHook` — blocks dangerous read/write/bash/edit |
-| `tool.execute.before` | `guardRailsHook` — enforces execution mode (auto/guarded/review-only) |
-| `tool.execute.before` | `patchTrustHook` — scores writes/edits; blocks high-risk without approval |
-| `tool.execute.before` | `decisionTraceHook` — records every edit to DECISIONS.jsonl |
-| `session.started` | `sessionStartHook` — announces FlowDeck, loads context |
-| `command.execute.before` | Command routing — dispatches slash commands |
-
-### Shared libraries
-
-Reusable utilities consumed by multiple commands:
-
-| Module | Exports |
-|--------|---------|
-| `src/lib/impact-radar.ts` | `runImpactRadar()`, `impactRadarSummaryLines()`, `lookupPriorFailures()` |
-| `src/hooks/patch-trust.ts` | `scorePatch()` |
-| `src/hooks/guard-rails.ts` | `resolveExecutionMode()` |
-| `src/hooks/tool-guard.ts` | `checkArchConstraint()`, `isBlocked()` |
-| `src/tools/planning-state-lib.ts` | `statePath()`, `codebaseDir()`, `readPlanningState()`, `timestamp()` |
-
-### Data files (`.codebase/`)
-
-| File | Purpose |
-|------|---------|
-| `MEMORY.json` | Architecture graph — modules, ownership, types |
-| `FAILURES.json` | Failure history — root causes, tags, recurrence counts |
-| `DECISIONS.jsonl` | Append-only edit audit log |
-| `VOLATILITY.json` | Churn metrics — stability ratings per path |
-| `POLICIES.json` | Self-healing policy rules |
-| `CONSTRAINTS.md` | Forbidden paths and architectural boundaries |
-| `ARCHITECTURE.md` | High-level architecture notes (written by `/fd-map-codebase`) |
-| `STACK.md` | Technology stack reference |
-
----
-
-## Migration Plan
-
-### For existing users
-
-**All old commands still work.** No action required. Old commands were not removed.
-
-**When to migrate:**
-
-| If you used to run | Now prefer |
-|-------------------|-----------|
-| `/fd-impact-radar --change "..."` | `/fd-analyze-change --change "..." --impact` |
-| Multiple analysis commands in sequence | `/fd-analyze-change --change "..." --all` |
-| Manual pre-edit risk assessment | `/fd-evaluate-risk --change "..." --file "..."` |
-| Manually deciding whether to apply a change | `/fd-guarded-edit --file "..." --change "..."` |
-| `/fd-translate-intent --intent "..."` | Same — now returns `assumptions` and `recommended_option` |
-
-### Quick start for new workflows
-
-**Before any significant edit:**
-```bash
-# 1. Translate vague intent to concrete options
-/fd-translate-intent --intent "make checkout faster"
-
-# 2. Full pre-change analysis
-/fd-analyze-change --change "add Redis cache for checkout queries"
-
-# 3. Gate decision for the specific file
-/fd-guarded-edit --file "src/checkout/query.ts" --change "add Redis cache layer"
-```
-
-**In CI/CD pipelines:**
-```bash
-# Risk gate — fail if approval required
-/fd-evaluate-risk --change "<PR description>" --json | jq '.approval_needed'
-
-# Edit gate — fail if block decision
-/fd-guarded-edit --file "<changed file>" --json | jq '.decision == "block"'
-```
-
----
-
-## Backward compatibility notes
-
-- All 7 original intelligence commands (`/fd-impact-radar`, `/fd-blast-radius`, `/fd-regression-predict`, `/fd-test-gap`, `/fd-volatility-map`, `/fd-review-route`, `/fd-translate-intent`) remain registered and functional.
-- Their implementations were not modified (except `/fd-translate-intent` which gained `assumptions`, `recommended_option`, and `clarifying_questions` in its output spec).
-- The new umbrella commands are registered alongside the old ones — no commands were removed.
-- Existing scripts, keybindings, or workflows that call the old commands will continue to work without changes.

package/docs/commands/fd-analyze-change.md

@@ -1,107 +0,0 @@
-# /fd-analyze-change
-
-**Umbrella analysis command** — runs up to 6 analysis modules in a single pass and produces a consolidated pre-change risk report.
-
-Replaces individual calls to `/fd-impact-radar`, `/fd-blast-radius`, `/fd-regression-predict`, `/fd-test-gap`, `/fd-volatility-map`, and `/fd-review-route`.
-
----
-
-## Usage
-
-```
-/fd-analyze-change --change "<what's changing>" [flags]
-```
-
-## Arguments
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--change` | string | — | Description of the proposed change |
-| `--scope` | string | `"all"` | Module or file path scope |
-| `--files` | string | — | Comma-separated file paths |
-| `--depth` | number | `2` | Blast radius traversal depth |
-| `--impact` | boolean | false | Run impact radar module |
-| `--blast-radius` | boolean | false | Run blast radius module |
-| `--regression` | boolean | false | Run regression prediction module |
-| `--test-gap` | boolean | false | Run test gap detection module |
-| `--volatility` | boolean | false | Run volatility map module |
-| `--review-route` | boolean | false | Run reviewer routing module |
-| `--all` | boolean | false | Force all modules (default when no module flags given) |
-| `--json` | boolean | false | Return raw JSON instead of table |
-
-**Default behaviour:** If no module flags are specified, all 6 modules run automatically.
-
----
-
-## Output
-
-```
-════════════════════════════════════════════════════════════════
-fd-analyze-change
-────────────────────────────────────────────────────────────────
-  Change:   update JWT token expiry
-  Scope:    all
-  Modules:  impact-radar, blast-radius, regression-predict, test-gap, volatility-map, review-route
-────────────────────────────────────────────────────────────────
-  ⚠ Affected zones:   src/auth/, src/session/, src/middleware/
-  ⚠ Known failures:   F-023, F-031
-  ≈ Regression cats:  auth, performance, async-flow...
-  ✗ Test gap types:   5 gap patterns checked
-  → Route to:          security, backend
-────────────────────────────────────────────────────────────────
-  ⚠ HIGH RISK: 3 volatile zone(s), 2 known failure(s), 1 fragile pattern(s)
-════════════════════════════════════════════════════════════════
-```
-
-### Top-level fields returned
-
-| Field | Description |
-|-------|-------------|
-| `modules_run` | Which analysis modules were executed |
-| `affected_zones` | Volatile/critical file paths matching the change |
-| `recommended_reviewers` | Reviewer types suggested (security, backend, infra, etc.) |
-| `risk_summary` | Human-readable risk advisory |
-| `risk_score` | Numeric score 0–100 (higher = lower risk) |
-| `config` | Full agent pipeline config dispatched to agents |
-
----
-
-## Examples
-
-```bash
-# Full analysis before editing auth middleware
-/fd-analyze-change --change "replace JWT with session tokens" --files "src/auth/token.ts"
-
-# Impact + regression only (partial analysis)
-/fd-analyze-change --change "refactor database connection pool" --impact --regression
-
-# JSON output for scripting
-/fd-analyze-change --change "update payment webhook handler" --json
-
-# Deep blast radius (3 levels)
-/fd-analyze-change --change "extract user service" --blast-radius --depth 3
-```
-
----
-
-## Old commands (still supported)
-
-These individual commands remain available and still work. Use `/fd-analyze-change` for combined analysis:
-
-| Old command | Equivalent flag |
-|-------------|----------------|
-| `/fd-impact-radar` | `--impact` |
-| `/fd-blast-radius` | `--blast-radius` |
-| `/fd-regression-predict` | `--regression` |
-| `/fd-test-gap` | `--test-gap` |
-| `/fd-volatility-map` | `--volatility` |
-| `/fd-review-route` | `--review-route` |
-
----
-
-## Agents dispatched
-
-- `researcher` — traces dependency graph from changed paths
-- `architect` — maps blast radius to configured depth, flags integration points
-- `tester` — estimates coverage gaps per regression category and test gap types
-- `reviewer` — ranks gaps by risk and confirms routing

package/docs/commands/fd-dashboard.md

@@ -1,11 +0,0 @@
----
-description: Open project dashboard — displays phase progress, milestones, and blockers
----
-Run the FlowDeck dashboard to view project progress.
-
-## What Next?
-
-1. **Start feature work** → `/fd-new-feature [description]`
-2. **Fix a bug** → `/fd-fix-bug [issue]`
-3. **View roadmap** → `/fd-roadmap`
-4. **Check progress** → `/fd-progress`