@dv.nghiem/flowdeck 0.4.10 → 0.4.12

package/src/skills/research-first/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: research-first
+description: Strict research hierarchy before writing code — search codebase, docs, web, and registries in order.
+---
+
+# /research-first — Research Hierarchy
+
+Enforces a strict research-first workflow before any implementation. Research in order of proximity: codebase first, structured docs second, web third, registries last.
+
+## Trigger
+
+Use this skill when:
+- About to write any new function, module, or integration
+- Unsure of an API signature, behavior, or pattern
+- Creating utilities, helpers, or abstractions
+- Evaluating whether to add a dependency
+- Debugging an issue in unfamiliar code
+
+## The Four-Level Hierarchy
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     RESEARCH HIERARCHY                      │
+├─────────────────────────────────────────────────────────────┤
+│  LEVEL 1: CODEBASE                                          │
+│  ┌─────────────┐  ┌─────────────────┐                       │
+│  │  CodeGraph  │  │  grep.app       │                       │
+│  │  (indexed)  │  │  (code search)  │                       │
+│  └─────────────┘  └─────────────────┘                       │
+│  When: Need patterns, examples, or existing implementations │
+│  Escalate: If codebase has no relevant code                 │
+├─────────────────────────────────────────────────────────────┤
+│  LEVEL 2: STRUCTURED DOCS                                   │
+│  ┌─────────────────┐                                        │
+│  │  Context7 MCP   │                                        │
+│  │  (library docs) │                                        │
+│  └─────────────────┘                                        │
+│  When: Need accurate API signatures and usage               │
+│  Escalate: If library not indexed or docs incomplete        │
+├─────────────────────────────────────────────────────────────┤
+│  LEVEL 3: WEB SEARCH                                        │
+│  ┌─────────────┐  ┌─────────────┐                           │
+│  │  Exa MCP    │  │  Web fetch  │                           │
+│  │  (semantic) │  │  (direct)   │                           │
+│  └─────────────┘  └─────────────┘                           │
+│  When: Level 1-2 insufficient or library unfamiliar         │
+│  Escalate: If no authoritative source found                 │
+├─────────────────────────────────────────────────────────────┤
+│  LEVEL 4: PACKAGE REGISTRIES                                │
+│  ┌─────────────┐  ┌─────────────┐                           │
+│  │  npm / PyPI │  │  GitHub     │                           │
+│  │  (search)   │  │  (packages) │                           │
+│  └─────────────┘  └─────────────┘                           │
+│  When: Need to verify existence of utility / alternative    │
+│  Escalate: Only if nothing suitable exists                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Level 1: Codebase Search
+
+**When to use:** Always start here. Before writing anything, check if the pattern already exists in the project.
+
+**Tools:**
+- `codegraph_search` — find symbols, functions, types by name
+- `codegraph_context` — understand how a module or feature works
+- `codegraph_explore` — inspect related symbols across files
+- `grep_app_searchGitHub` — search GitHub for real-world code examples
+
+**What to look for:**
+- Existing utility functions that do what you need
+- Similar features implemented elsewhere in the project
+- Naming conventions and patterns used by the team
+- Test files that show expected usage
+
+**Escalate to Level 2 when:**
+- The codebase has no relevant implementation
+- You need library-specific API details
+- The project uses an external dependency you are unfamiliar with
+
+### Level 1 Example
+
+```
+Need: Parse a JSON configuration file with defaults
+
+Step 1: codegraph_search for "parseConfig" or "loadConfig"
+Result: Found loadConfig() in src/config/loader.ts
+
+Step 2: codegraph_context for "config loader"
+Result: Understands the loader handles JSON, YAML, and env overrides
+
+Decision: Reuse loadConfig() instead of writing a new parser.
+```
+
+## Level 2: Structured Documentation (Context7)
+
+**When to use:** You need accurate API signatures, method names, parameter types, or version-specific behavior for a library.
+
+**Tools:**
+- `context7_resolve-library-id` — find the correct Context7 ID
+- `context7_query-docs` — query structured documentation with examples
+
+**What to look for:**
+- Exact function signatures and return types
+- Code examples from official docs
+- Version-specific behavior and deprecations
+- Configuration options and defaults
+
+**Escalate to Level 3 when:**
+- The library is not indexed in Context7
+- The docs are incomplete or ambiguous
+- You need community patterns, not just API reference
+
+### Level 2 Example
+
+```
+Need: Use React useEffect cleanup correctly
+
+Step 1: context7_resolve-library-id for "React"
+Result: /facebook/react
+
+Step 2: context7_query-docs for "useEffect cleanup function examples"
+Result: Official patterns for subscription cleanup, event listener removal
+
+Decision: Use the documented cleanup pattern; no need to search further.
+```
+
+## Level 3: Web Search
+
+**When to use:** Levels 1-2 failed to answer the question, or you need community consensus, real-world patterns, or comparisons.
+
+**Tools:**
+- `exa_search` — neural search for high-quality sources
+- `webfetch` — fetch specific pages for details
+- `websearch_web_search_exa` — general web search
+
+**What to look for:**
+- Authoritative blog posts or documentation pages
+- GitHub issues or discussions explaining edge cases
+- Comparison articles when choosing between alternatives
+- Community best practices
+
+**Escalate to Level 4 when:**
+- No authoritative source answers the question
+- You are considering writing a utility and need to check if a package exists
+- You need to verify package names, versions, or alternatives
+
+### Level 3 Example
+
+```
+Need: Understand how to handle rate limiting in a specific API
+
+Step 1: Level 1 — codebase has no API client for this service
+Step 2: Level 2 — Context7 has no docs for this third-party API
+Step 3: exa_search for "[ServiceName] API rate limit headers retry-after"
+Result: Found official docs and community client implementations
+
+Decision: Implement retry with exponential backoff based on Retry-After header.
+```
+
+## Level 4: Package Registries
+
+**When to use:** Before writing any utility function, verify it does not already exist as a well-maintained package.
+
+**Tools:**
+- `grep_app_searchGitHub` — search for existing npm/PyPI packages with real usage
+- `webfetch` — check npmjs.com or pypi.org directly
+
+**What to look for:**
+- Packages that solve the exact problem
+- Download counts, maintenance status, and license compatibility
+- Bundle size and dependency tree (avoid bloat)
+
+**When to stop:**
+- A suitable package exists → adopt or extend it
+- No suitable package exists → build custom, informed by research
+
+### Level 4 Example
+
+```
+Need: Deep merge two objects with type safety
+
+Step 1-3: No existing implementation or docs answer the need
+Step 4: Search npm for "deep merge typescript"
+Result: lodash.merge (too heavy), deepmerge-ts (lightweight, typed)
+
+Decision: Install deepmerge-ts. Do not write a custom deep merge.
+```
+
+## Decision Tree
+
+```
+START: Need to implement or understand something
+        │
+        ▼
+┌───────────────────┐
+│ Search codebase   │ ──NO──▶ ┌─────────────────────┐
+│ (CodeGraph, grep) │         │ Search structured docs│
+└───────────────────┘         │ (Context7 MCP)        │
+        │YES                  └─────────────────────┘
+        ▼                             │
+   [REUSE OR MODEL                    │NO
+    AFTER EXISTING]                   ▼
+                              ┌─────────────────────┐
+                              │ Search web          │
+                              │ (Exa, webfetch)     │
+                              └─────────────────────┘
+                                    │
+                                    │NO
+                                    ▼
+                              ┌─────────────────────┐
+                              │ Check registries    │
+                              │ (npm, PyPI, GitHub) │
+                              └─────────────────────┘
+                                    │
+                                    │NO
+                                    ▼
+                              [BUILD CUSTOM]
+```
+
+## Anti-Patterns
+
+### Do NOT guess API signatures
+
+```
+❌ BAD:
+"I think the function is called fetchData(url, options)..."
+
+✅ GOOD:
+Use Context7 to query the exact signature, or use codegraph_search
+to find existing calls in the codebase.
+```
+
+### Do NOT write utility functions that already exist
+
+```
+❌ BAD:
+Write a custom deepClone() without checking if the project already
+uses a utility library or has an internal implementation.
+
+✅ GOOD:
+1. codegraph_search for "clone", "deepClone", "copy"
+2. Check package.json for lodash, ramda, or similar
+3. Only write custom if nothing suitable exists
+```
+
+### Do NOT search the web before searching the codebase
+
+```
+❌ BAD:
+Open a browser search for "how to parse JSON in TypeScript" when
+ the project already has a config loader module.
+
+✅ GOOD:
+Start with codegraph_context for "config" or "parse" to find
+internal patterns before looking externally.
+```
+
+### Do NOT load full documentation pages into context
+
+```
+❌ BAD:
+Fetch an entire docs website or README and dump it into the
+conversation context.
+
+✅ GOOD:
+Use Context7 for targeted queries. If using webfetch, request
+only the specific section or example needed.
+```
+
+## Concrete Examples
+
+### Example 1: Implementing a Retry Wrapper
+
+```
+❌ BAD APPROACH:
+- Assume the signature: async function retry(fn, retries)
+- Write a 40-line custom retry with exponential backoff
+- Discover later the project uses p-retry everywhere
+
+✅ GOOD APPROACH:
+1. codegraph_search for "retry" → finds p-retry usage in src/utils/
+2. codegraph_context for "retry pattern" → understands backoff config
+3. Reuse p-retry with project-standard options
+4. Implementation: 3 lines
+```
+
+### Example 2: Parsing a Date Format
+
+```
+❌ BAD APPROACH:
+- Write a regex: /^(\d{4})-(\d{2})-(\d{2})$/
+- Handle edge cases manually (leap years, timezones)
+- Result: 30 lines, untested, buggy
+
+✅ GOOD APPROACH:
+1. codegraph_search for "date-fns", "moment", "luxon" in imports
+2. Context7 query for date-fns parseISO documentation
+3. Use date-fns.parseISO() — battle-tested, 1 line
+```
+
+### Example 3: Validating an Email Address
+
+```
+❌ BAD APPROACH:
+- Write a regex from memory
+- Guess at what constitutes a valid email
+- Result: fragile, probably wrong
+
+✅ GOOD APPROACH:
+1. codegraph_search for "email" and "validate" or "zod"
+2. Find existing zod schema: z.string().email()
+3. Reuse the existing validation pattern
+```
+
+## Tool Reference
+
+| Tool | Level | Purpose |
+|------|-------|---------|
+| `codegraph_search` | 1 | Find symbols by name |
+| `codegraph_context` | 1 | Understand modules and features |
+| `codegraph_explore` | 1 | Inspect related symbols |
+| `grep_app_searchGitHub` | 1, 4 | Code search across GitHub |
+| `context7_resolve-library-id` | 2 | Find library in Context7 |
+| `context7_query-docs` | 2 | Query structured documentation |
+| `exa_search` | 3 | Neural web search |
+| `webfetch` | 3 | Fetch specific pages |
+| `websearch_web_search_exa` | 3 | General web search |
+
+## Cross-References
+
+- **`search-first`** — Use when evaluating whether to adopt, extend, or build. `research-first` is about the search *process*; `search-first` is about the *decision* after research.
+- **`documentation-writer`** — After researching, use this to document findings and patterns for the team.
+- **`api-design`** — When research reveals the need for new interfaces, use this skill to design them consistently.
+
+## Integration Points
+
+### With `@backend-coder`
+Before implementing any feature, the backend coder should run through Levels 1-2. Only escalate to 3-4 if the codebase and Context7 are insufficient.
+
+### With `@researcher`
+The researcher agent specializes in external discovery (Levels 2-4). The coder should handle Level 1 directly before delegating deeper research.
+
+### With `@planner`
+The planner should assume research is complete. If a plan includes "write utility X", the planner must verify via codegraph that X does not already exist.

package/src/skills/session-persistence/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: session-persistence
+description: Maintain continuity across FlowDeck sessions by loading previous context, checkpointing mid-session state, and writing structured summaries at session end.
+origin: FlowDeck
+---
+
+# Session Persistence
+
+FlowDeck sessions are bounded by context windows. This skill ensures work survives across sessions without losing state, decisions, or momentum.
+
+## When to Activate
+
+Activate at:
+- **Session start** — before any agent does work
+- **Mid-session** — when context exceeds 60% of the window
+- **Session end** — before closing the workspace
+
+## Core Principles
+
+- Load before you act. Never start work without reading the prior session summary.
+- Checkpoint early and often. Ephemeral state is lost when the context window rolls over.
+- Summaries are append-only. Each session adds a new entry; old entries rotate monthly.
+- STATE.md owns the plan. SESSION_SUMMARY.md owns the narrative. Do not duplicate.
+
+---
+
+## Phase 1: Session Start
+
+**Goal**: Bring the agent up to speed on what happened in the previous session and what remains.
+
+### Files to Read
+
+| File | Purpose | Max Chars | Required |
+|------|---------|-----------|----------|
+| `.planning/STATE.md` | Current phase, active plan, blockers, steps completed | 10,000 | Yes |
+| `.planning/SESSION_SUMMARY.md` | Prior session narratives, decisions, failures, remaining work | 15,000 | Yes |
+| `.planning/phases/phase-N/PLAN.md` | Active plan with tasks and success criteria | 8,000 | If referenced in STATE.md |
+| `.codebase/DECISIONS.jsonl` | Recent decisions relevant to active work | 5,000 | Query last 10 entries |
+
+### Information to Capture
+
+1. **Phase and status** — from STATE.md
+2. **Last completed step** — what was finished
+3. **Next pending step** — what should happen now
+4. **Blockers** — anything preventing progress
+5. **Approaches that failed** — avoid repeating them
+6. **Key decisions** — links to DECISIONS.jsonl entries
+7. **Files modified** — what changed recently
+8. **Test status** — green, failing, or unknown
+
+### Commands to Use
+
+```
+/fd-resume          # Load STATE.md and latest SESSION_SUMMARY.md entry
+/fd-status          # Show current phase, next step, and blocker summary
+```
+
+### Context Bounding Rules
+
+- If SESSION_SUMMARY.md exceeds 15,000 chars, read only the **last 3 entries**.
+- If there are more than 10 entries total, archive entries older than 30 days.
+- Never load the full git history — use `git log --oneline -10` if needed.
+
+### Startup Briefing Format
+
+After loading, produce:
+
+```markdown
+## Session Resume
+
+**Phase**: [N] — [name] | **Status**: [discuss | plan | execute | review]
+**Plan**: [path or "none"]
+**Last Step Completed**: [step number + name]
+**Next Step**: [step number + name]
+**Blockers**: [none | description]
+
+**Context from Previous Session**:
+- [What was attempted]
+- [What worked]
+- [What failed]
+- [What remains]
+
+**Key Decisions**: [links to DECISIONS.jsonl entries]
+**Files Modified**: [list]
+**Tests**: [passing | failing | unknown]
+```
+
+---
+
+## Phase 2: Mid-Session Checkpoint
+
+**Goal**: Save ephemeral state before the context window rolls over or before switching tasks.
+
+### When to Checkpoint
+
+- Context window is > 60% full
+- Before running a long command (build, test suite, migration)
+- Before switching agents or workflows
+- Before pausing for research or discussion
+
+### What to Save
+
+| Data | Storage | Tool |
+|------|---------|------|
+| Current plan step | `.planning/STATE.md` | `planning-state` |
+| Partial implementation notes | `.planning/SESSION_SUMMARY.md` | Append to latest entry |
+| Decisions made this session | `.codebase/DECISIONS.jsonl` | `decision-trace` |
+| Files modified | `git status` + `git diff --name-only` | Read from git |
+
+### Command to Use
+
+```
+/fd-checkpoint      # Save current state to STATE.md and update SESSION_SUMMARY.md
+```
+
+### Checkpoint Content
+
+A checkpoint is a lightweight update to the current SESSION_SUMMARY.md entry. Include:
+
+- **Timestamp** — when the checkpoint occurred
+- **Current step** — what is in progress
+- **Partial results** — what is working so far
+- **Open questions** — what is blocking or unclear
+- **Next action** — what to do immediately after resuming
+
+---
+
+## Phase 3: Session End
+
+**Goal**: Write a durable narrative summary so the next session can resume without re-discovering context.
+
+### Files to Write
+
+| File | Action | Max Size |
+|------|--------|----------|
+| `.planning/SESSION_SUMMARY.md` | Append new entry | Rotate when file exceeds 50 KB |
+| `.planning/STATE.md` | Update completed steps, status | Keep under 5 KB |
+| `.codebase/DECISIONS.jsonl` | Record any pending decisions | Append only |
+
+### Information to Capture
+
+1. **Session timestamp** — start and end time
+2. **Phase and step** — what was being worked on
+3. **Approaches that worked** — with evidence (test output, build success, etc.)
+4. **Approaches attempted but failed** — with reason for failure
+5. **What remains to do** — next steps with clear boundaries
+6. **Key decisions made** — with links to DECISIONS.jsonl entries
+7. **Files modified** — full list with one-line purpose
+8. **Tests status** — which tests pass, which fail, which are new
+9. **Blockers for next session** — anything that needs resolution
+
+---
+
+## SESSION_SUMMARY.md Format
+
+Each entry is a level-2 section with a standard structure.
+
+### Required Sections
+
+```markdown
+## Session YYYY-MM-DD HH:MM
+
+**Phase**: [N] — [phase name]
+**Plan**: [path to PLAN.md]
+**Step Worked On**: [step number + name]
+**Agents Involved**: [@agent-name, ...]
+
+### What Worked
+
+- [Approach 1] — Evidence: [test output / build success / deployed status]
+- [Approach 2] — Evidence: [commit hash / PR link / log snippet]
+
+### What Was Attempted But Failed
+
+- [Approach] — Reason: [why it failed] — Lesson: [what to try instead]
+
+### Remaining Work
+
+- [ ] [Next step 1]
+- [ ] [Next step 2]
+
+### Key Decisions
+
+- [Decision 1] — See `.codebase/DECISIONS.jsonl`:[entry-id]
+- [Decision 2] — See `.codebase/DECISIONS.jsonl`:[entry-id]
+
+### Files Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `src/...` | Added | ... |
+| `src/...` | Edited | ... |
+
+### Tests
+
+| Test File | Status | Notes |
+|-----------|--------|-------|
+| `tests/...` | Passing | ... |
+| `tests/...` | Failing | ... |
+| `tests/...` | New | ... |
+
+### Blockers
+
+- [none | description]
+```
+
+---
+
+## Template: SESSION_SUMMARY.md
+
+```markdown
+# Session Summaries
+
+> Rotate monthly. Archive entries older than 30 days to `.planning/archive/summaries-YYYY-MM.md`.
+
+## Session 2026-06-10 14:00
+
+**Phase**: 2 — Implementation
+**Plan**: `.planning/phases/phase-2/PLAN.md`
+**Step Worked On**: 2.3 — Add billing service
+**Agents Involved**: [@backend-coder, @tester]
+
+### What Worked
+
+- Using Stripe's `SubscriptionSchedule` for phased rollouts — Evidence: `npm test tests/billing.test.ts` passes
+- Mocking the Stripe API with `stripe-mock` in CI — Evidence: CI run #412 green
+
+### What Was Attempted But Failed
+
+- Direct webhook signature verification in the controller — Reason: secret rotation broke tests — Lesson: Move verification to a dedicated middleware with fallback secrets
+
+### Remaining Work
+
+- [ ] Wire webhook handler to the event bus
+- [ ] Add idempotency key checks
+- [ ] Update API docs
+
+### Key Decisions
+
+- Use `SubscriptionSchedule` over `Subscription` for enterprise plans — See `.codebase/DECISIONS.jsonl`:billing-schedule-2026-06-10
+
+### Files Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `src/services/billing.ts` | Added | Core billing logic |
+| `src/middleware/webhook-verify.ts` | Added | Stripe signature verification |
+| `tests/billing.test.ts` | Added | Unit tests for billing service |
+
+### Tests
+
+| Test File | Status | Notes |
+|-----------|--------|-------|
+| `tests/billing.test.ts` | Passing | 12/12 tests green |
+| `tests/webhook.test.ts` | Failing | 2/5 fail — signature mismatch in test fixtures |
+
+### Blockers
+
+- Need Stripe test secret key to fix webhook fixtures. Ask DevOps.
+```
+
+---
+
+## Anti-Patterns
+
+### Do Not Load Old Context Into New Unrelated Work
+
+If a new feature or bug fix is unrelated to the previous session's work, skip loading the full SESSION_SUMMARY.md. Read STATE.md only to confirm the current phase, then start fresh. Loading stale context pollutes the agent's reasoning with irrelevant constraints.
+
+**Signal to skip**: The new task's files do not overlap with the prior session's `Files Modified` list.
+
+### Do Not Let SESSION_SUMMARY.md Grow Unbounded
+
+When the file exceeds 50 KB:
+1. Create `.planning/archive/summaries-YYYY-MM.md`
+2. Move all entries older than 30 days into the archive
+3. Keep only the last 30 days in the active file
+
+**Why**: Large summaries slow down session startup and waste context window space.
+
+### Do Not Duplicate Information Already in STATE.md
+
+SESSION_SUMMARY.md is narrative. STATE.md is structural.
+
+| Belongs in STATE.md | Belongs in SESSION_SUMMARY.md |
+|---------------------|-------------------------------|
+| Phase number, plan path | What was attempted and why |
+| Completed step list | Which approaches worked or failed |
+| Blocker IDs | Detailed blocker context and mitigation |
+| Next step reference | What remains to do with boundaries |
+
+If STATE.md says "Step 2.3 complete", SESSION_SUMMARY.md should say "Step 2.3 complete — used SubscriptionSchedule approach, tests green".
+
+---
+
+## FlowDeck Commands Reference
+
+| Command | Phase | Purpose |
+|---------|-------|---------|
+| `/fd-resume` | Start | Load STATE.md and latest SESSION_SUMMARY.md entry |
+| `/fd-checkpoint` | Mid | Save current state before context rolls over |
+| `/fd-status` | Any | Show phase, next step, blockers, and test status |
+
+---
+
+## Related Skills
+
+- **[context-load](context-load/SKILL.md)** — Loads the structural context (STATE.md, PLAN.md, PROJECT.md). Use at session start before reading SESSION_SUMMARY.md.
+- **[plan-task](plan-task/SKILL.md)** — Breaks work into waves with verifiable steps. Use when the remaining work in SESSION_SUMMARY.md needs re-planning.
+- **[decision-trace](decision-trace/SKILL.md)** — Records the why behind changes. Link to DECISIONS.jsonl entries from SESSION_SUMMARY.md.
+- **[failure-replay-engine](failure-replay-engine/SKILL.md)** — Tracks failures to avoid repeating them. Check before attempting an approach that failed in a prior session.
+
+---
+
+## Guidance
+
+- **One summary per session**. If a session spans multiple days, append a sub-section with the new date rather than creating a new top-level entry.
+- **Evidence over claims**. "Tests pass" is weak. "`npm test` exits 0, 14/14 tests in `billing.test.ts` green" is strong.
+- **Link, don't repeat**. Reference DECISIONS.jsonl entries by ID instead of copying rationale into the summary.
+- **Be honest about failures**. A failed approach with a clear lesson is more valuable than a vague success.