@dv.nghiem/flowdeck 0.1.0

package/src/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: tdd-workflow
+description: Enforces Test-Driven Development with Red-Green-Refactor cycle and 80%+ coverage. Activate when writing new features, fixing bugs, or refactoring.
+origin: FlowDeck
+---
+
+# TDD Workflow Skill
+
+Tests before code. Always. Red-Green-Refactor is not a suggestion.
+
+## When to Activate
+
+Activate when:
+- Implementing any new feature
+- Fixing any bug
+- Refactoring existing code
+
+## Core Principles
+
+- **Tests before code** — write the failing test first, then the implementation
+- **Minimum implementation** — write the least code that makes the test pass
+- **Refactor after green** — clean up only when tests are passing
+- **80%+ coverage** — non-negotiable threshold
+
+## Workflow
+
+### Red — Write a Failing Test
+
+Write a test that describes the behavior you want. It must fail before you write any implementation.
+
+```typescript
+// AAA Pattern: Arrange, Act, Assert
+describe('calculateDiscount', () => {
+  it('should apply 10% discount for premium users', () => {
+    // Arrange
+    const user = { tier: 'premium' };
+    const price = 100;
+
+    // Act
+    const result = calculateDiscount(price, user);
+
+    // Assert
+    expect(result).toBe(90);
+  });
+
+  it('should return full price for standard users', () => {
+    // Arrange
+    const user = { tier: 'standard' };
+    const price = 100;
+
+    // Act
+    const result = calculateDiscount(price, user);
+
+    // Assert
+    expect(result).toBe(100);
+  });
+});
+```
+
+Run it: `npm test` → must fail with "cannot find function" or similar.
+
+### Green — Minimum Code to Pass
+
+Write the minimum implementation:
+
+```typescript
+function calculateDiscount(price: number, user: { tier: string }): number {
+  if (user.tier === 'premium') return price * 0.9;
+  return price;
+}
+```
+
+Run it: `npm test` → must pass.
+
+### Refactor — Clean Up While Green
+
+Now clean up the implementation:
+
+```typescript
+const DISCOUNT_RATES: Record<string, number> = {
+  premium: 0.10,
+};
+
+function calculateDiscount(price: number, user: { tier: string }): number {
+  const discountRate = DISCOUNT_RATES[user.tier] ?? 0;
+  return price * (1 - discountRate);
+}
+```
+
+Run it: `npm test` → must still pass.
+
+### Git Checkpoint
+
+After each Red-Green-Refactor cycle:
+
+```bash
+git add -A
+git commit -m "test: add calculateDiscount + implementation"
+```
+
+## Test Types
+
+| Type | When | Tools |
+|------|------|-------|
+| Unit | Functions, services with mocked deps | vitest, jest |
+| Integration | API endpoints, database queries | supertest, vitest |
+| E2E | Critical user flows | playwright, cypress |
+
+Write unit tests for every function. Integration tests for every API route. E2E only for critical paths.
+
+## Coverage Check
+
+```bash
+npx vitest --coverage          # vitest
+npx jest --coverage            # jest
+```
+
+Threshold: 80% line coverage minimum. If below, write more tests before considering the work done.
+
+## Common Mistakes
+
+- Writing tests AFTER implementation — these are not TDD tests
+- Writing tests that always pass (asserting something trivially true)
+- Skipping the Refactor step — leaving messy green code is not TDD
+- Testing implementation details instead of behavior
+- Giant tests that test multiple behaviors at once

package/src/skills/test-coverage/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: test-coverage
+description: Enforce test-first development and measure coverage gaps. Use for new features, bug fixes, or when coverage drops below threshold. Drives the write-test → implement → verify cycle.
+origin: FlowDeck
+---
+
+# Test Coverage Skill
+
+Ensures code is tested before it is considered done. Coverage numbers are a by-product — the goal is meaningful tests that catch real bugs.
+
+## When to Activate
+
+Activate when:
+- Implementing a new feature (TDD: tests first)
+- Fixing a bug (write failing test before fix)
+- Coverage drops below threshold
+- Preparing code for review
+
+## Core Principles
+
+- 80% minimum line coverage — no exceptions
+- Tests before code, not after
+- Test behavior, not implementation
+- Every bug fix gets a regression test
+
+## Workflow
+
+1. **Write failing test** (Red) — describe the behavior you're about to implement
+2. **Implement minimum code** (Green) — make the test pass
+3. **Refactor** — clean up while keeping tests green
+4. **Run coverage** — verify 80%+ threshold
+5. **Add edge case tests** — for empty inputs, invalid inputs, error paths
+
+## Coverage Commands
+
+```bash
+# vitest
+npx vitest --coverage
+npx vitest --coverage --reporter=verbose
+
+# jest
+npx jest --coverage
+
+# view HTML report
+open coverage/index.html
+```
+
+## Coverage Report Format
+
+A passing coverage report looks like this:
+
+```
+----------|---------|----------|---------|---------|
+File      | % Stmts | % Branch | % Funcs | % Lines |
+----------|---------|----------|---------|---------|
+All files |   87.3  |   82.1   |   91.4  |   87.3  |
+ auth.ts  |   94.2  |   88.0   |  100.0  |   94.2  |
+ user.ts  |   80.1  |   76.4   |   85.7  |   80.1  |
+----------|---------|----------|---------|---------|
+
+Coverage threshold met: 80% ✅
+```
+
+A failing report looks like:
+
+```
+ services/payment.ts | 41.2 | 30.0 | 50.0 | 41.2 |
+
+Coverage threshold NOT met: 41.2% < 80% ❌
+Uncovered lines: 45-67, 89-112
+```
+
+## What to Test
+
+| Category | Examples |
+|---------|---------|
+| Happy path | Normal inputs, expected outputs |
+| Error conditions | Invalid inputs, missing fields, null |
+| Edge cases | Empty arrays, zero values, max values |
+| Auth | Unauthenticated, unauthorized, correct role |
+
+## What NOT to Test
+
+- Private methods (test via public interface)
+- Third-party library behavior
+- Simple property accessors with no logic
+- Framework internals
+
+## Troubleshooting Failures
+
+- **Test failing after refactor**: undo the refactor, fix in smaller steps
+- **Test failing after bug fix**: the test should have been failing before the fix
+- **Low coverage on new code**: add edge case tests for all branches
+- **Flaky tests**: find the shared state being mutated, isolate it

package/src/skills/test-gap-detector/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: test-gap-detector
+description: Identify which areas of a proposed change are weakly covered by tests and suggest the minimum high-value tests to add first.
+origin: FlowDeck
+---
+
+# Test Gap Detector
+
+Run `/test-gap` before implementing a feature or fix. Get back a ranked list of coverage gaps and the minimum viable tests to close them.
+
+## Gap Categories
+
+| Category | What It Means |
+|----------|--------------|
+| missing test file | Source file changed but no `*.test.*` counterpart exists |
+| untested error path | A `catch`, `else`, or error branch has no test |
+| untested branch | An `if/else` or `switch` arm has no test exercising it |
+| no integration test | A service-to-service or API call has no integration test |
+| no regression test | A previously-failed path has no regression test guarding it |
+
+## Workflow
+
+1. List all files to be changed
+2. For each file, check if a test file exists (`*.test.ts`, `*.spec.ts`, `__tests__/`)
+3. For files with tests, scan for untested branches:
+   - Count `if`, `else`, `catch`, `switch` statements
+   - Cross-reference with test file to see which paths are exercised
+4. Check `.codebase/FAILURES.json` for prior failures on these paths — flag as regression gap if no regression test exists
+5. For external calls (fetch, db.query, sendEmail), check for integration test coverage
+6. Rank gaps by risk (auth > payment > data > logic > UI)
+7. Produce minimum viable test set (top 3–5 tests)
+
+## Output Format
+
+```markdown
+## Test Gap Report
+
+### Gap Summary
+| File | Gap Type | Risk | Suggested Test |
+|------|----------|------|----------------|
+
+### Minimum Viable Test Set (top 5)
+1. **[test name]** — [file.test.ts]
+   Tests: [what it validates]
+   ```typescript
+   it('[test name]', async () => {
+     // test skeleton
+   })
+   ```
+
+### Coverage Verdict: GOOD | GAPS FOUND | CRITICAL GAPS
+```
+
+## Guidance
+
+- A test skeleton is always better than no test — write it even if incomplete
+- Auth and payment paths with no regression test = CRITICAL GAP, block merge
+- Do not add tests just to hit a coverage number — add tests for real risk paths

package/src/skills/volatility-map/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: volatility-map
+description: Highlight unstable zones of the repo based on commit churn, recent breakages, hotfix frequency, and unresolved TODO clusters.
+origin: FlowDeck
+---
+
+# Codebase Volatility Map
+
+Run `/volatility-map` to generate a heatmap of the most unstable parts of the codebase. Results are stored in `.codebase/VOLATILITY.json` for use by other FlowDeck features.
+
+## Stability Levels
+
+| Level | Score | Meaning |
+|-------|-------|---------|
+| stable | 0–19 | Low churn, no hotfixes, few TODOs |
+| moderate | 20–49 | Some churn, occasional fixes |
+| volatile | 50–79 | High churn or repeated hotfixes |
+| critical | 80+ | Highest risk, most likely to break |
+
+## Score Formula
+
+`score = churn_commits + (hotfix_count × 10) + (todo_count × 2)`
+
+## Data Collection Workflow
+
+1. **Churn analysis** (git log, last 90 days):
+   ```bash
+   git log --since="90 days ago" --name-only --pretty=format: | sort | uniq -c | sort -rn
+   ```
+2. **Hotfix detection** (commit messages):
+   ```bash
+   git log --since="90 days ago" --pretty=format:"%s %H" | grep -i "hotfix\|revert\|urgent\|critical"
+   ```
+3. **TODO scan** (source files):
+   ```bash
+   grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.ts" | cut -d: -f1 | sort | uniq -c
+   ```
+4. Write results to VOLATILITY.json via `volatility-map` tool
+
+## How Other Features Use This
+
+- **Patch Trust Score**: deducts points for volatile/critical files
+- **Change Impact Radar**: flags volatile files in impact reports
+- **Safe Execution Modes**: switches to `guarded` for volatile, `review-only` for critical
+- **Human Review Routing**: escalates changes to volatile files to senior reviewers
+
+## Refresh Schedule
+
+Refresh the volatility map:
+- Before any significant feature work
+- After a production incident
+- Weekly in active development periods

package/src/workflows/debug-flow.md

@@ -0,0 +1,119 @@
+---
+name: debug-flow
+description: "Systematic debugging: reproduce → trace → write failing test → fix root cause → verify. Never suppress errors."
+triggers:
+  - /debug
+steps:
+  - name: reproduce
+    agent: "@debug-specialist"
+    action: Establish minimal reproduction case with expected vs actual behavior
+  - name: trace
+    agent: "@debug-specialist"
+    action: Debug-specialist traces execution path and identifies root cause
+  - name: write_test
+    agent: "@tester"
+    action: Tester writes failing regression test for the exact failure
+  - name: fix
+    agent: "@coder"
+    action: Coder fixes root cause with minimal change
+  - name: verify
+    agent: "@tester"
+    action: Run regression test + full suite to confirm fix
+---
+
+# Debug Flow
+
+## Purpose
+
+Diagnose and fix unexpected behavior systematically. Prevents symptom-fixing and ensures reproducibility.
+
+## Rules
+
+- Never suppress an error to make a test pass
+- Fix the root cause, not the symptom
+- Always write a regression test before fixing
+- Read stack traces completely — never half-read
+
+## Process
+
+### Step 1: Reproduce
+
+Document the bug precisely:
+```
+Bug: [one-line description]
+Steps to reproduce:
+  1. ...
+  2. ...
+Expected: [what should happen]
+Actual: [what does happen]
+Stack trace: [if available]
+```
+
+Confirm you can reproduce it consistently before proceeding.
+
+### Step 2: Trace
+
+Spawn `@debug-specialist` to:
+
+1. Read the complete stack trace
+2. Identify the failing function and line
+3. Trace inputs backward to find where bad data enters
+4. Check recent changes: `git log --oneline -10 -- <file>`
+5. Identify root cause (not symptom)
+
+Common root causes:
+| Symptom | Look for |
+|---------|---------|
+| null/undefined error | Missing boundary check |
+| Wrong value | Type coercion, missing validation |
+| Race condition | Missing await, shared mutable state |
+| Auth failure | Missing middleware, wrong scope check |
+| Infinite loop | Missing base case, wrong termination |
+
+### Step 3: Write Failing Test
+
+Spawn `@tester` to write a regression test:
+- Must FAIL on current code (RED)
+- Tests the exact scenario from Step 1
+- Isolated from other tests
+
+```typescript
+test('should [expected] when [condition from bug report]', () => {
+  // Arrange: set up the exact failing scenario
+  // Act: call the failing code
+  // Assert: verify expected behavior
+});
+```
+
+### Step 4: Fix
+
+Spawn `@coder` to:
+- Fix the root cause identified in Step 2
+- Minimum change to make the regression test pass
+- Do NOT touch unrelated code
+
+If the fix requires more than 20 lines: STOP, reassess scope.
+
+### Step 5: Verify
+
+```bash
+# Regression test must pass
+npm test -- --grep "regression test name"
+
+# Full suite must still pass
+npm test
+```
+
+If any unrelated test breaks: the fix has unintended side effects. Investigate before proceeding.
+
+## Output
+
+```
+## Debug Complete
+
+Bug: [description]
+Root cause: [specific cause]
+Fix: [what changed, file:line]
+Regression test: [test name] ✅ PASS
+Suite: ✅ N/N tests passing
+```

package/src/workflows/deploy-check-flow.md

@@ -0,0 +1,98 @@
+---
+name: deploy-check-flow
+description: "Pre-deployment checks: parallel tests + security scan + CVE audit + build verification → go/no-go decision"
+triggers:
+  - /deploy-check
+steps:
+  - name: parallel_checks
+    agent: "@parallel-coordinator"
+    action: Run tests, security scan, CVE audit, and build in parallel
+  - name: aggregate
+    agent: "@orchestrator"
+    action: Aggregate all results into a unified report
+  - name: decision
+    agent: "@orchestrator"
+    action: Produce explicit go/no-go decision with required fixes if no-go
+---
+
+# Deploy Check Flow
+
+## Purpose
+
+Run a comprehensive pre-deployment check suite before releasing to production.
+
+## Process
+
+### Step 1: Parallel Checks
+
+Launch four checks simultaneously:
+
+**Check A: Test Suite**
+```bash
+npm test
+```
+All tests must pass. No failures, no skips without justification.
+
+**Check B: Security Scan**
+
+Spawn `@security-auditor` to check:
+- No hardcoded secrets in changed files
+- Input validation at trust boundaries
+- Auth/authz on all protected routes
+- No CRITICAL or HIGH vulnerabilities
+
+**Check C: Dependency CVE Audit**
+```bash
+npm audit --audit-level=high
+```
+No HIGH or CRITICAL CVEs unaddressed.
+
+**Check D: Build Verification**
+```bash
+npm run build
+```
+Build must succeed with zero errors.
+
+### Step 2: Aggregate Results
+
+```
+## Pre-Deployment Check
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Tests | ✅ PASS / ❌ FAIL | N/N passed |
+| Security | ✅ PASS / ❌ FAIL | [findings] |
+| CVE Audit | ✅ PASS / ❌ FAIL | [vulnerabilities] |
+| Build | ✅ PASS / ❌ FAIL | [errors] |
+```
+
+### Step 3: Decision
+
+**🚀 GO** — all checks pass, proceed with deployment.
+
+**🛑 NO-GO** — one or more checks failed:
+```
+Verdict: NO-GO
+
+Required fixes before deploy:
+- [ ] [fix 1]
+- [ ] [fix 2]
+
+Run /deploy-check again after fixing.
+```
+
+## No-go conditions (automatic)
+
+Any of these → automatic NO-GO:
+- Test failures
+- CRITICAL security vulnerability
+- HIGH/CRITICAL CVE unpatched
+- Build error
+
+## Agent configuration
+
+| Agent | Purpose |
+|-------|---------|
+| @tester | Run test suite |
+| @security-auditor | Security vulnerability scan |
+| @researcher | CVE research and context |

package/src/workflows/discuss-flow.md

@@ -0,0 +1,97 @@
+---
+name: discuss-flow
+description: "Orchestrates discuss phase (context load → @discusser Q&A → pause → decisions → save)"
+triggers:
+  - /discuss
+steps:
+  - name: load_context
+    agent: "@orchestrator"
+    priority: first
+    action: Load PROJECT.md and current phase STATE.md
+  - name: determine_phase
+    agent: "@orchestrator"
+    action: Extract current phase number from STATE.md
+  - name: invoke_discusser
+    agent: "@discusser"
+    action: Spawn @discusser agent with project context
+  - name: qa_loop
+    agent: "@discusser"
+    action: Discusser asks one question at a time; user responds; repeat until all topics covered
+  - name: save_decisions
+    agent: "@discusser"
+    action: Write all decisions to .planning/phases/phase-N/DISCUSS.md with D-XX numbering
+  - name: confirm_discuss
+    agent: "@orchestrator"
+    action: Present summary to user; require explicit confirmation before marking DISCUSS.md as confirmed
+---
+
+# Discuss Flow
+
+## Purpose
+
+Extract project requirements and decisions via structured Q&A with the @discusser agent.
+
+## Process
+
+### Step 1: Load Context
+
+Read `.planning/PROJECT.md` to understand the project vision and goals.
+Read `.planning/STATE.md` to determine the current phase and context.
+
+### Step 2: Determine Phase
+
+Extract the current phase number from STATE.md.
+Decisions will be saved to `.planning/phases/phase-{N}/DISCUSS.md`.
+
+### Step 3: Invoke Discusser
+
+Spawn @discusser agent with:
+- Project context (from PROJECT.md)
+- Current phase number
+- Instructions to ask ONE question per turn
+
+### Step 4: Q&A Loop
+
+The @discusser agent asks one question at a time.
+After each user response:
+- Assign D-XX number to any new decision
+- Record: topic, choice, rationale
+- If response conflicts with previous decision, flag the conflict
+
+Continue until all required topics are covered or user says to stop early.
+
+### Step 5: Save Decisions
+
+Save all decisions to `.planning/phases/phase-N/DISCUSS.md`:
+```
+D-01: [Topic] — [Decision] ([Rationale])
+D-02: [Topic] — [Decision] ([Rationale])
+...
+```
+
+### Step 6: Confirm Discuss
+
+Present summary of decisions to user.
+Ask for explicit confirmation: "CONFIRMED" to proceed or "REVISION NEEDED" to revisit.
+
+If user confirms:
+- Update STATE.md to mark DISCUSS.md as confirmed
+- Proceed to plan phase
+
+If user requests revision:
+- Return to Step 4 (Q&A loop) for the specified topics
+
+## D-05 Compliance
+
+- Loads PROJECT.md + current phase STATE.md
+- Invokes @discusser agent
+- Saves decisions with D-XX numbering to DISCUSS.md
+- One question at a time (no compound questions)
+
+## Error Handling
+
+D-03: Fail fast with clear error
+- If PROJECT.md not found: error with "Run /new-project first"
+- If STATE.md not found: error with "Project not initialized"
+- If @discusser fails: error with "Discusser agent unavailable"
+- No partial state saved on error