@dv.nghiem/flowdeck 0.1.0

package/src/skills/parallel-execute/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: parallel-execute
+description: Coordinate parallel agent execution for independent workstreams. Assign tasks to specialist agents by wave, merge outputs, handle conflicts. Use when a plan has parallel tasks.
+origin: FlowDeck
+---
+
+# Parallel Execute Skill
+
+Maximizes throughput by running independent work simultaneously. Manages waves, verifies independence, handles merge conflicts.
+
+## When to Activate
+
+Activate when:
+- A plan has tasks that can run simultaneously
+- Multiple independent features need to be implemented
+- Research can happen in parallel with implementation
+
+## Core Principles
+
+- Parallel = different files + no shared state + not dependent on each other
+- Always wait for an entire wave before starting the next
+- Conflicts mean the tasks weren't truly independent — reassign as sequential
+- Brief each agent completely — they are stateless
+
+## Workflow
+
+1. **Identify Wave 1** — tasks with no dependencies
+2. **Verify independence** — confirm different files, no shared state
+3. **Spawn Wave 1 simultaneously** — delegate all Wave 1 tasks at once
+4. **Wait for all Wave 1** — do not start Wave 2 until all complete
+5. **Check for conflicts** — compare files changed by each agent
+6. **Spawn Wave 2** — tasks that depend on Wave 1 outputs
+
+## Wave Structure Example
+
+```
+Wave 1 (start simultaneously — ~2 hours):
+  Track A: @coder implements UserModel in src/models/user.ts
+  Track B: @researcher documents bcrypt API for password hashing
+  Track C: @tester writes tests for UserService in src/user.test.ts
+
+[Wait for all three to complete]
+
+Wave 2 (sequential — ~2 hours):
+  Task 2.A: @coder implements auth service using outputs from Track A + B
+  Task 2.B: @writer documents the public API using outputs from Track A
+
+[Wait for 2.A and 2.B to complete]
+
+Wave 3 (review — 30 min):
+  @reviewer reviews all changes together
+```
+
+Timing example:
+- Sequential total: 6.5 hours
+- Parallel total: ~4.5 hours (30% faster)
+
+## Independence Checklist
+
+Before marking tasks as parallel:
+- [ ] Task A and Task B touch different files
+- [ ] Neither task's output is needed as input by the other
+- [ ] Both tasks can be verified independently
+- [ ] If both complete correctly, integration will be straightforward
+
+## Conflict Resolution
+
+If two agents modified the same file:
+
+```
+CONFLICT: Track A and Track C both modified src/types/user.ts
+Resolution: Assigning @coder to reconcile both versions sequentially.
+Track A change: [description]
+Track C change: [description]
+```
+
+## Output Format
+
+```markdown
+## Parallel Execution Report
+
+### Wave 1 Results (all must complete before Wave 2)
+- Track A (@coder): ✅ src/models/user.ts created
+- Track B (@researcher): ✅ bcrypt docs ready
+- Track C (@tester): ✅ 8 tests written, 8 passing
+
+### Conflicts
+None detected.
+
+### Wave 2 Starting
+Task 2.A: @coder building auth service with Wave 1 outputs
+```

package/src/skills/patch-trust-score/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: patch-trust-score
+description: Assign a confidence and risk rating to every AI-generated change. Returns safe, review-required, or high-risk verdict with specific signals.
+origin: FlowDeck
+---
+
+# Patch Trust Score
+
+Every AI-generated patch gets a trust score before it is applied. The score gates how the change is handled: auto-apply, flag for review, or block and escalate.
+
+## Score Bands
+
+| Score | Verdict | Action |
+|-------|---------|--------|
+| 80–100 | safe | Auto-apply in guarded mode |
+| 40–79 | review-required | Inline warning + human ACK |
+| 0–39 | high-risk | Block auto-apply, route to reviewer |
+
+## Risk Signals (each reduces the score)
+
+| Signal | Deduction |
+|--------|-----------|
+| File in volatile/critical volatility zone | −25 to −40 |
+| File has prior failure history | −20 |
+| Edit contains auth/crypto/payment keywords | −8 per keyword (max −30) |
+| File in arch-constrained zone | −20 |
+| No test coverage for file | −10 |
+
+## Workflow
+
+1. For every proposed write or edit:
+   a. Look up the file in `.codebase/VOLATILITY.json`
+   b. Check `.codebase/FAILURES.json` for prior failures on this file
+   c. Scan the patch content for high-risk keywords
+   d. Check `.codebase/CONSTRAINTS.md` for boundary violations
+2. Compute score (0–100, start at 100)
+3. Emit verdict with signals
+4. Route accordingly (auto / warn / block)
+
+## Integration
+
+The `patch-trust` hook runs automatically on every `write` and `edit` tool call. The score is logged to stdout and appended to `.codebase/DECISIONS.jsonl`.
+
+For manual scoring, use the `patch-trust-score` skill with a file path and change description.

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

@@ -0,0 +1,153 @@
+---
+name: performance-profiling
+description: CPU and memory profiling, N+1 query detection, bundle analysis, and render optimization. Activate when diagnosing slow performance or before production deployments.
+origin: FlowDeck
+---
+
+# Performance Profiling Skill
+
+Finds real performance bottlenecks using data. Never optimize without measuring first.
+
+## When to Activate
+
+Activate when:
+- Users report slow responses
+- A page or endpoint takes longer than expected
+- Before a production deployment of performance-sensitive changes
+- After adding features to a hot code path
+
+## Core Principles
+
+- **Measure before optimizing** — a guess about the bottleneck is almost always wrong
+- **Profile the real bottleneck** — top-line metrics first, then drill down
+- **Verify improvement with numbers** — "feels faster" is not a performance result
+
+## Workflow
+
+1. **Establish baseline** — measure current performance with actual numbers
+2. **Profile** — find where time is spent
+3. **Identify bottleneck** — the one slowest thing
+4. **Fix** — targeted change to address bottleneck
+5. **Measure improvement** — confirm the number improved
+
+## Profiling Tools
+
+```bash
+# Node.js CPU profiling
+node --prof app.js
+node --prof-process isolate-*.log | head -100
+
+# Clinic.js (visual profiler)
+npm install -g clinic
+clinic doctor -- node app.js
+clinic flame -- node app.js   # flame graph
+
+# Lighthouse (web performance)
+npx lighthouse http://localhost:3000 --output=json --output-path=./report.json
+
+# Bundle analyzer
+npx webpack-bundle-analyzer dist/stats.json
+```
+
+## Core Web Vitals Targets
+
+| Metric | Good | Needs Work | Poor |
+|--------|------|-----------|------|
+| LCP | < 2.5s | 2.5s-4s | > 4s |
+| FID | < 100ms | 100ms-300ms | > 300ms |
+| CLS | < 0.1 | 0.1-0.25 | > 0.25 |
+| TTFB | < 800ms | 800ms-1.8s | > 1.8s |
+
+## N+1 Detection
+
+```typescript
+// ❌ N+1 — 1 query for posts, N queries for authors
+const posts = await Post.findAll();
+for (const post of posts) {
+  post.author = await User.findById(post.authorId); // N queries!
+}
+
+// ✅ Single query with JOIN
+const posts = await Post.findAll({
+  include: [{ model: User, as: 'author' }]
+});
+```
+
+Detection: add query logging and look for repeated queries with different IDs.
+
+## Bundle Analysis
+
+```bash
+# Generate stats
+npm run build -- --stats
+
+# Analyze
+npx webpack-bundle-analyzer dist/stats.json
+
+# What to look for:
+# - Large libraries that could be replaced with smaller alternatives
+# - Libraries imported in full that should be tree-shaken
+# - Duplicate dependencies at different versions
+```
+
+## React Render Profiling
+
+```typescript
+// React DevTools Profiler — open in browser DevTools → Profiler tab
+// Record a user interaction, look for:
+// - Components rendering too often
+// - Renders taking >16ms (drops frame rate)
+
+// why-did-you-render (development only)
+import whyDidYouRender from '@welldone-software/why-did-you-render';
+whyDidYouRender(React, { trackAllPureComponents: true });
+```
+
+## Memory Leak Patterns
+
+```typescript
+// ❌ Event listener never removed
+useEffect(() => {
+  document.addEventListener('click', handler);
+}, []);
+
+// ✅ Cleanup
+useEffect(() => {
+  document.addEventListener('click', handler);
+  return () => document.removeEventListener('click', handler);
+}, []);
+
+// ❌ Interval never cleared
+useEffect(() => {
+  setInterval(poll, 5000);
+}, []);
+
+// ✅ Clear on unmount
+useEffect(() => {
+  const id = setInterval(poll, 5000);
+  return () => clearInterval(id);
+}, []);
+```
+
+## Performance Report Template
+
+```markdown
+## Performance Report
+
+### Baseline
+- Endpoint: GET /api/v1/users
+- P50: 340ms | P95: 1200ms | P99: 3400ms
+- Measured with: autocannon, 100 concurrent connections
+
+### Bottleneck
+- Root cause: N+1 query — 1 query per user to fetch their role
+- Evidence: query log shows 47 queries for 47 users
+
+### Fix
+- Single JOIN query in UserRepository.findAllWithRoles()
+- File: src/db/user-repo.ts
+
+### After
+- P50: 42ms | P95: 98ms | P99: 210ms
+- Improvement: 87% faster at P50
+```

package/src/skills/plan-task/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: plan-task
+description: Break complex features into a phased implementation plan with wave-structured parallel tasks, dependency graph, and verifiable success criteria. Use before starting any multi-file feature.
+origin: FlowDeck
+---
+
+# Plan Task Skill
+
+Turns vague feature requests into concrete, executable plans. Each step maps to a file, has a verification, and fits within a working session.
+
+## When to Activate
+
+Activate when:
+- A feature touches more than 2 files
+- You are unsure what order to implement things
+- Multiple people need to work on the feature in parallel
+- The feature involves data model changes or API changes
+
+## Core Principles
+
+- Foundation first: types → data → services → routes → UI
+- Steps must be independently verifiable
+- No step longer than 2-3 hours of work
+- Success criteria must be observable (not "it works")
+
+## Task Sizing Guide
+
+| Size | Duration | Action |
+|------|----------|--------|
+| Too small | < 30 min | Combine with a related task |
+| Right size | 1-3 hours | Keep as is |
+| Too large | > 3 hours | Split into two steps in separate waves |
+
+## Workflow
+
+1. **Parse requirements** — list every behavior the feature must have
+2. **Map to files** — which files must change for each behavior?
+3. **Build dependency graph** — which changes depend on others?
+4. **Group into waves** — independent changes in same wave
+5. **Write success criteria** — one observable outcome per requirement
+
+## Wave Assignment Rules
+
+**Same wave (run in parallel):**
+- Different files, no shared mutable state
+- Neither task reads the other's output
+
+**Next wave:**
+- Integration tasks (wiring together Wave 1 outputs)
+- Review and documentation
+- Any task that reads output produced by Wave 1
+
+## Plan Format
+
+```markdown
+# Plan: [Feature Name]
+
+## Objective
+[What this delivers and why]
+
+## Wave 1 — Foundation (parallel)
+
+### Task 1.A — [Name]
+- **Agent**: @coder
+- **File**: `src/models/subscription.ts`
+- **Scope**: Create Subscription model with id, userId, status, expiresAt
+- **Verify**: `npx tsc --noEmit` passes
+
+### Task 1.B — [Name]
+- **Agent**: @researcher
+- **Scope**: Document Stripe subscription API
+- **Verify**: Research covers: create, cancel, webhook events
+
+## Wave 2 — Implementation (after Wave 1)
+
+### Task 2.A — [Name]
+- **Agent**: @coder
+- **Depends on**: Task 1.A, Task 1.B
+- **File**: `src/services/billing-service.ts`
+- **Scope**: Implement subscribe(), cancel(), handleWebhook()
+- **Verify**: `npm test src/billing.test.ts` passes
+
+## Success Criteria
+- [ ] [Observable outcome 1]
+- [ ] [Observable outcome 2]
+- [ ] `npm test` exits 0
+- [ ] `npx tsc --noEmit` exits 0
+```
+
+## Success Criteria Quality
+
+```
+✅ Good: "User can log in with email+password and receives a JWT"
+❌ Bad: "Authentication works"
+
+✅ Good: "GET /users/:id returns 404 when user does not exist"
+❌ Bad: "Error handling works"
+
+✅ Good: "npm test produces 0 failures"
+❌ Bad: "Tests pass"
+```