@dv.nghiem/flowdeck 0.1.0

package/src/skills/deploy-check/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: deploy-check
+description: Pre-deployment checklist covering tests, security scan, CVE audit, and code review. Returns a go/no-go decision. Use before every production deployment.
+origin: FlowDeck
+---
+
+# Deploy Check Skill
+
+Systematic pre-deployment verification. Returns GO or NO-GO with specific blockers.
+
+## When to Activate
+
+Activate before any production deployment or release.
+
+## Core Principles
+
+- Every check must pass before GO
+- Any CRITICAL or HIGH finding = NO-GO
+- No exceptions without explicit documented approval
+
+## Workflow
+
+1. Run test suite — all tests must pass
+2. Run security scan — check for OWASP Top 10 issues
+3. Run CVE audit — `npm audit --audit-level=moderate`
+4. Run code review — check recent changes for quality issues
+5. Check conventional commits — verify commit messages are valid
+6. Validate environment variables — confirm all required vars are set
+7. Aggregate findings — determine GO or NO-GO
+
+## Checklist
+
+### Tests
+- [ ] `npm test` exits with code 0
+- [ ] Coverage ≥ 80% (or project threshold)
+- [ ] No skipped or pending tests (without documented reason)
+
+### Security Scan
+- [ ] No hardcoded credentials (grep for common patterns)
+- [ ] No SQL string concatenation
+- [ ] Auth middleware on all protected routes
+- [ ] Input validation at all API boundaries
+- [ ] No sensitive data in logs
+
+### CVE Audit
+```bash
+npm audit --audit-level=moderate
+```
+- [ ] Zero critical vulnerabilities
+- [ ] Zero high vulnerabilities (or documented exceptions)
+
+### Code Review
+- [ ] No CRITICAL or HIGH severity findings
+- [ ] No TODO/FIXME in changed files (unless pre-existing)
+- [ ] Error handling present on all new code paths
+
+### Conventional Commits
+- [ ] All commits since last release follow `type(scope): description` format
+- [ ] Valid types: feat, fix, refactor, docs, test, chore, perf, ci
+- [ ] Breaking changes marked with `!` or `BREAKING CHANGE:` footer
+
+### Environment Variables
+- [ ] All required env vars documented in `.env.example`
+- [ ] No `.env` file committed to git
+- [ ] Production environment has all required vars set
+- [ ] No dev/test values used in production config
+
+## Output Format
+
+```markdown
+## Deploy Check Report
+
+### Verdict: GO ✅ | NO-GO ❌
+
+### Blockers (if NO-GO)
+- [specific issue that must be fixed]
+
+### Warnings (GO with notes)
+- [non-blocking issues to track]
+
+### Passing
+- ✅ Tests: 127 passing, 0 failing
+- ✅ Security: no CRITICAL or HIGH findings
+- ✅ CVE audit: 0 vulnerabilities
+- ✅ Conventional commits: valid
+- ✅ Environment variables: all present
+```

package/src/skills/documentation-writer/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: documentation-writer
+description: Writes technical documentation including README, API docs, changelogs, and inline comments. Activate when documentation needs to be created or updated.
+origin: FlowDeck
+---
+
+# Documentation Writer Skill
+
+Writes documentation that developers actually read. Accurate over comprehensive. Examples over prose.
+
+## When to Activate
+
+Activate when:
+- New code was written and needs documentation
+- Existing docs are outdated or wrong
+- A README needs to be created
+- API docs need to be updated after a signature change
+
+## Core Principles
+
+- **Accurate over comprehensive** — wrong docs are worse than no docs
+- **Examples over prose** — show, don't describe
+- **Keep it current** — every code change triggers a doc review
+
+## Workflow
+
+1. Identify what changed (git diff)
+2. Find affected documentation (grep for function/class names)
+3. Update each doc with accurate content
+4. Verify all code examples work
+
+## README Structure
+
+```markdown
+# Project Name
+
+One-sentence description of what this does.
+
+[![Build](badge)] [![Coverage](badge)] [![License](badge)]
+
+## Quick Start
+
+```bash
+npm install my-package
+```
+
+```typescript
+import { myFunction } from 'my-package';
+const result = myFunction('input');
+```
+
+## Installation
+
+```bash
+npm install my-package
+# or
+yarn add my-package
+```
+
+## Usage
+
+[Most common use cases with working examples]
+
+## API Reference
+
+[Link to detailed API docs or inline for small libraries]
+
+## Contributing
+
+[How to contribute, run tests, submit PRs]
+
+## License
+
+MIT
+```
+
+## API Doc Format
+
+```markdown
+### `functionName(param1, param2?)`
+
+One sentence: what it does.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| param1 | string | Yes | The user's email address |
+| param2 | Options | No | Config (default: `{}`) |
+
+**Returns:** `Promise<User>` — the created user.
+
+**Throws:** `ValidationError` if email is invalid.
+
+**Example:**
+```typescript
+const user = await createUser('me@example.com');
+console.log(user.id); // "usr_abc123"
+```
+```
+
+## Changelog Format
+
+Follow [Keep a Changelog](https://keepachangelog.com):
+
+```markdown
+## [Unreleased]
+
+### Added
+- User can now reset password via email link
+
+### Fixed
+- Login button was disabled after failed attempt
+
+### Changed
+- `createUser()` now accepts `Options` instead of separate parameters
+
+### Deprecated
+- `getUserData()` — use `fetchUserProfile()` instead
+
+### Removed
+- Removed `legacyAuth()` (deprecated in v1.1)
+```
+
+## Inline Comment Guidelines
+
+**DO comment:**
+```typescript
+// Binary search: O(log n) — dataset is always sorted on insert
+function findUser(users: User[], id: string): User | null { ... }
+
+// WARNING: mutates input array for performance — clone before passing if needed
+function sortInPlace(items: Item[]): void { ... }
+
+// Using exponential backoff: API rate limit is 1 req/sec sustained
+async function fetchWithRetry(url: string, retries = 3): Promise<Response> { ... }
+```
+
+**DON'T comment:**
+```typescript
+// increment counter
+counter++;
+
+// return user email
+return user.email;
+```
+
+## Quality Checklist
+
+- [ ] All code examples are syntactically correct
+- [ ] Examples work when pasted into the project
+- [ ] No dead links
+- [ ] Consistent terminology throughout
+- [ ] README quick start works on a fresh clone
+- [ ] Changelog entry added for all meaningful changes

package/src/skills/failure-replay-engine/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: failure-replay-engine
+description: Learn from reverted commits, failed deployments, flaky tests, and bug fixes so the agent avoids repeating the same mistakes in this repo.
+origin: FlowDeck
+---
+
+# Failure Replay Engine
+
+FlowDeck remembers every failure that has been recorded in this repo. Before making a change, check the failure history for patterns that match your current task.
+
+## Failure Types Tracked
+
+| Type | Example |
+|------|---------|
+| reverted_commit | A commit that was rolled back within 48h |
+| failed_deployment | A deployment that caused incidents |
+| flaky_test | A test that fails intermittently |
+| bug_fix | A fix for a production bug |
+| build_failure | A change that broke CI |
+
+## Workflow
+
+### Before Making a Change
+
+1. Query `.codebase/FAILURES.json` for failures matching the affected paths
+2. If a pattern is found with `recurrence_count >= 2`, surface a warning
+3. Include the failure context in your planning rationale
+
+### After a Failure is Identified
+
+1. Record it with the `failure-replay` tool
+2. Include: type, description, affected_paths, root_cause, fix_applied, tags
+
+### Recording a Failure
+
+```json
+{ "action": "record", "entry": {
+    "id": "auth-jwt-expiry-2024-03",
+    "type": "bug_fix",
+    "description": "JWT tokens expired before refreshing, locking out users",
+    "affected_paths": ["src/services/auth.ts", "src/middleware/validate-token.ts"],
+    "root_cause": "Clock skew between services caused premature expiry",
+    "fix_applied": "Added 30s clock skew buffer to expiry check",
+    "tags": ["auth", "jwt", "timing"]
+}}
+```
+
+## Querying Before Editing
+
+Always query before touching auth, payment, schema, or async paths:
+```json
+{ "action": "query", "query": { "path_prefix": "src/services/auth", "limit": 5 } }
+```
+
+## Guidance
+
+- Recurring failures (recurrence_count ≥ 3) indicate a systemic issue — escalate to architect
+- Mark failures as resolved only after a regression test is green for 2 consecutive CI runs
+- Do not delete failure records — they are the repo's institutional memory

package/src/skills/git-release/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: git-release
+description: Create consistent releases and changelogs from merged PRs. Proposes semantic version bump, drafts release notes, and provides a copy-pasteable release command.
+origin: FlowDeck
+---
+
+# Git Release Skill
+
+Creates releases with consistent versioning, accurate changelogs, and proper tagging.
+
+## When to Activate
+
+Activate when:
+- A milestone is complete and ready to ship
+- You need to cut a release tag
+- You need to generate a CHANGELOG entry
+
+## Core Principles
+
+- Semver strictly: major.minor.patch
+- Conventional commits drive the version bump automatically
+- Changelog is for humans: group by type, use plain language
+- One release per tag — no force-pushing tags
+
+## Workflow
+
+1. **Collect commits** — `git log [last-tag]..HEAD --oneline`
+2. **Determine version bump** from commits:
+   - Breaking change (`!` or `BREAKING CHANGE:`) → major bump
+   - `feat:` → minor bump
+   - `fix:`, `refactor:`, `perf:` → patch bump
+   - `docs:`, `test:`, `chore:` → no version bump (unless last release)
+3. **Draft changelog** — group commits by type
+4. **Update CHANGELOG.md** — prepend new version under `## Unreleased`
+5. **Tag and push** — provide the exact commands
+
+## Conventional Commits Types
+
+| Type | Version Bump | Description |
+|------|-------------|-------------|
+| `feat` | minor | New feature |
+| `fix` | patch | Bug fix |
+| `perf` | patch | Performance improvement |
+| `refactor` | patch | Code change, no behavior change |
+| `docs` | none | Documentation only |
+| `test` | none | Adding or updating tests |
+| `chore` | none | Maintenance, dependencies |
+| `ci` | none | CI/CD configuration |
+| `feat!` or `BREAKING CHANGE:` | major | Breaking API change |
+
+## Changelog Format
+
+Follow Keep a Changelog (keepachangelog.com):
+
+```markdown
+## [1.2.0] — 2024-01-15
+
+### Added
+- User authentication via JWT (feat: add JWT auth)
+- Password reset via email (feat: add password reset)
+
+### Fixed
+- Token expiry calculation was off by one day (fix: correct token expiry)
+
+### Changed
+- Migrated from bcrypt to argon2 for better security (refactor: use argon2)
+```
+
+## Release Commands
+
+```bash
+# After updating CHANGELOG.md
+git add CHANGELOG.md
+git commit -m "chore(release): v1.2.0"
+git tag -a v1.2.0 -m "Release v1.2.0"
+git push origin main --tags
+```
+
+## Output Format
+
+```markdown
+## Release Proposal: v[X.Y.Z]
+
+**Version bump**: patch | minor | major
+**Reason**: [breaking change / new feature / bug fix]
+
+### CHANGELOG entry (copy into CHANGELOG.md):
+[formatted changelog section]
+
+### Release commands:
+```bash
+[copy-pasteable commands]
+```
+```

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

@@ -0,0 +1,177 @@
+---
+name: git-workflow
+description: Branching strategies, conventional commits, PR templates, and merge vs rebase guidance. Activate when starting features, creating PRs, or managing releases.
+origin: FlowDeck
+---
+
+# Git Workflow Skill
+
+Clean, reviewable git history. Small commits, descriptive messages, reviewed before merge.
+
+## When to Activate
+
+Activate when:
+- Starting a new feature or bug fix
+- Creating a pull request
+- Managing a release
+- Resolving merge conflicts
+
+## Core Principles
+
+- **Small, atomic commits** — one logical change per commit
+- **Descriptive messages** — reader understands the change without reading the diff
+- **Linear history preferred** — rebase local branches before creating PR
+- **Review before merge** — no self-merges on shared branches
+
+## Branch Naming Convention
+
+```
+feature/user-authentication      — new features
+fix/login-redirect-loop          — bug fixes
+chore/update-dependencies        — maintenance
+release/v1.2.0                   — release preparation
+hotfix/critical-null-dereference — urgent production fixes
+refactor/extract-auth-middleware — code restructuring
+docs/update-api-reference        — documentation only
+```
+
+## Conventional Commits Format
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+| Type | Version Bump | When to Use |
+|------|-------------|-------------|
+| `feat` | minor | New feature for the user |
+| `fix` | patch | Bug fix for the user |
+| `perf` | patch | Performance improvement |
+| `refactor` | patch | Code change, no behavior change |
+| `docs` | none | Documentation only |
+| `test` | none | Adding or fixing tests |
+| `chore` | none | Dependencies, tooling, CI |
+| `ci` | none | CI/CD configuration |
+| `build` | none | Build system changes |
+
+### Examples
+
+```
+feat(auth): add JWT token refresh endpoint
+fix(auth): correct token expiry off-by-one error
+perf(db): replace N+1 query with single JOIN
+refactor(user): extract password validation to separate module
+docs(api): document authentication endpoints
+test(auth): add coverage for token expiry edge cases
+chore(deps): update express to 4.18.2
+ci(github): add node 20 to test matrix
+feat!: remove deprecated v1 API endpoints
+```
+
+### Breaking Changes
+
+```
+feat!: remove deprecated getUserData() function
+
+BREAKING CHANGE: getUserData() has been removed.
+Use fetchUserProfile() instead.
+Migration: replace all calls to getUserData() with fetchUserProfile().
+```
+
+## PR Template
+
+**Title**: Same format as a commit: `feat(auth): add password reset`
+
+**Description**:
+```markdown
+## What
+[What this PR does in 1-3 sentences]
+
+## Why
+[Why this change is needed]
+
+## How to Test
+1. [Step 1]
+2. [Step 2]
+3. Expected result: [what should happen]
+
+## Checklist
+- [ ] Tests added or updated
+- [ ] Documentation updated
+- [ ] No breaking changes (or documented)
+- [ ] Ran `npm test` locally
+```
+
+## Rebase vs Merge
+
+| Situation | Strategy | Command |
+|-----------|---------|---------|
+| Local feature branch before PR | Rebase | `git rebase main` |
+| PR integration to main | Merge (preserves history) | GitHub "Merge PR" |
+| Small feature PR | Squash merge | GitHub "Squash and merge" |
+| Long-lived branch | Merge (preserves branch history) | `git merge --no-ff` |
+| Force-push to shared branch | Never | — |
+
+```bash
+# Before creating PR — rebase to clean up
+git fetch origin
+git rebase origin/main
+git push --force-with-lease    # safe force push (only if no one else pushed)
+```
+
+## Release Process
+
+```bash
+# 1. Create release branch
+git checkout -b release/v1.2.0
+
+# 2. Update version
+npm version minor                # updates package.json + creates tag
+
+# 3. Update CHANGELOG
+# (add entry under ## [1.2.0])
+
+# 4. Commit
+git add CHANGELOG.md package.json
+git commit -m "chore(release): v1.2.0"
+
+# 5. Tag
+git tag -a v1.2.0 -m "Release v1.2.0"
+
+# 6. Push
+git push origin release/v1.2.0 --tags
+
+# 7. Create PR → merge → done
+```
+
+## Git Commands Reference
+
+```bash
+# Undo last commit (keep changes staged)
+git reset --soft HEAD~1
+
+# Undo last commit (discard changes)
+git reset --hard HEAD~1
+
+# Fix commit message
+git commit --amend -m "new message"
+
+# Squash last 3 commits
+git rebase -i HEAD~3
+
+# Cherry-pick a commit to another branch
+git cherry-pick [commit-sha]
+
+# Find when a bug was introduced
+git bisect start
+git bisect bad                  # current is broken
+git bisect good [good-sha]      # last known good
+
+# Stash changes
+git stash                       # save
+git stash pop                   # restore
+```