@dv.nghiem/flowdeck 0.1.0

package/src/skills/codebase-mapping/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: codebase-mapping
+description: Systematic codebase exploration and documentation for agent context. Maps architecture, conventions, and file structure into .codebase/ files. Use when onboarding to a new project or before deep feature work.
+origin: FlowDeck
+---
+
+# Codebase Mapping Skill
+
+Produces structured documentation of a codebase that agents can read to answer "how does this project work?" without re-scanning every time.
+
+## When to Activate
+
+- Starting work on an unfamiliar codebase
+- Before a major feature that spans multiple modules
+- When `/map-codebase` command is invoked
+- When `.codebase/` is missing or stale
+
+## Output Files
+
+All outputs go to `.codebase/`:
+
+| File | Contents |
+|------|----------|
+| `ARCHITECTURE.md` | System design: layers, modules, data flow |
+| `CONVENTIONS.md` | Naming, style, patterns specific to this project |
+| `DEPENDENCIES.md` | Key external packages and what they do |
+| `INDEX.md` | File-by-file inventory |
+| `ENTRY_POINTS.md` | How the application starts and key entry files |
+
+## Mapping Sequence
+
+### Step 1: Start from the outside
+
+Read in this order:
+1. `package.json` / `pyproject.toml` / `Cargo.toml` — dependencies, scripts, metadata
+2. `README.md` — stated purpose and architecture
+3. Entry point files (main, index, app, server)
+4. Configuration files (env examples, config schemas)
+
+### Step 2: Map the directory structure
+
+Document each top-level directory's purpose:
+```
+src/
+  api/          — HTTP route handlers
+  services/     — Business logic
+  models/       — Database schemas and queries
+  utils/        — Shared helpers
+tests/          — Test files (mirror of src/)
+scripts/        — Build and deployment scripts
+```
+
+Do not guess. Read the files to confirm what each directory contains.
+
+### Step 3: Document key conventions
+
+Find examples in the code:
+- How are errors handled? (throw? return Result? error callback?)
+- How are modules exported? (default export? named exports?)
+- What is the naming pattern for files? (`UserService.ts`? `user-service.ts`?)
+- Where do interfaces/types live?
+- How is dependency injection done?
+
+Write 1-2 examples for each pattern, not a generic description.
+
+### Step 4: Document entry points
+
+```markdown
+## Entry Points
+
+- `src/index.ts` — Application bootstrap, registers routes and middleware
+- `src/workers/queue.ts` — Background job processor, runs independently
+- `scripts/migrate.ts` — Database migration runner
+```
+
+### Step 5: List key dependencies
+
+For each significant dependency, document:
+- What it is used for in this project
+- Where in the codebase it is used
+- Version (note if pinned due to known issues)
+
+## Accuracy rules
+
+- Only document what you have read — never document by assumption
+- If a file's purpose is unclear, note "purpose unclear — investigate before modifying"
+- Timestamp the mapping: `Last updated: [date]`

package/src/skills/codebase-onboarding/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: codebase-onboarding
+description: Systematically explores and documents an unfamiliar codebase. Use when joining a new project, setting up for the first time, or generating project documentation.
+origin: FlowDeck
+---
+
+# Codebase Onboarding Skill
+
+Systematically maps an unfamiliar codebase into structured documentation. Factual only — no speculation.
+
+## When to Activate
+
+Activate when:
+- Joining a new project for the first time
+- A new AI agent needs to understand the codebase
+- Project documentation is out of date or missing
+- Before making major architectural changes
+
+## Core Principles
+
+- **Reconnaissance before action** — fully understand before touching anything
+- **Factual, not speculative** — if uncertain, write `UNKNOWN — needs verification`
+- **Document as you explore** — write findings immediately, before moving on
+
+## Phase 1: Reconnaissance
+
+```bash
+# 1. Top-level structure
+ls -la
+
+# 2. Package manifest
+cat package.json     # Node.js
+cat go.mod           # Go
+cat Cargo.toml       # Rust
+cat requirements.txt # Python
+
+# 3. Entry points
+find . -name "index.*" -o -name "main.*" | grep -v node_modules | grep -v dist | grep -v .git
+
+# 4. Directory structure
+find . -maxdepth 2 -type d | grep -v node_modules | grep -v .git | grep -v dist
+
+# 5. Test structure
+find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules | head -20
+```
+
+Findings:
+- What framework is this? (Express, Next.js, FastAPI, etc.)
+- Where does execution start?
+- Where are the tests?
+
+## Phase 2: Architecture Mapping
+
+Read the most important files:
+1. Main entry point — understand startup sequence
+2. Route definitions — what APIs/endpoints exist?
+3. Core data models — what are the key entities?
+4. Database setup — what database, what ORM?
+5. Auth setup — how is authentication handled?
+
+Produce a component diagram:
+
+```
+Client
+  → HTTP (port 3000)
+  → Express Router (src/routes/)
+  → Services (src/services/)
+  → Repository (src/db/)
+  → PostgreSQL
+```
+
+## Phase 3: Convention Detection
+
+Read 5-10 source files and note patterns:
+
+```bash
+# Naming conventions
+grep -n "export function\|export const\|export class" src/ -r | head -20
+
+# Error handling
+grep -n "catch\|throw\|Error(" src/ -r | head -20
+
+# Async patterns
+grep -n "async\|await\|Promise" src/ -r | head -20
+```
+
+Conventions to identify:
+- Variable naming: camelCase, snake_case, or mixed?
+- Import style: relative paths, aliases, or barrel exports?
+- Error handling: throw, return Result, or callback?
+- Async pattern: async/await, promises, or callbacks?
+
+## Output Format
+
+```markdown
+# Codebase Onboarding: [Project Name]
+
+## Phase 1: Reconnaissance
+
+**Runtime**: Node.js v20 / Python 3.11 / Go 1.21
+**Framework**: Express 4.18 / FastAPI / Echo
+**Package manager**: npm / pip / cargo
+**Entry point**: `src/index.ts:1`
+**Test framework**: vitest / pytest / go test
+
+## Phase 2: Architecture
+
+**Pattern**: Layered (Routes → Services → Repository → Database)
+**Database**: PostgreSQL via Prisma ORM
+**Auth**: JWT via `src/middleware/auth.ts`
+
+**Component Diagram**:
+```
+[diagram]
+```
+
+**Key Files**:
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | HTTP server startup |
+| `src/routes/` | Route definitions |
+| `src/services/` | Business logic |
+
+## Phase 3: Conventions
+
+**Naming**: camelCase for variables, PascalCase for types
+**Imports**: relative paths within module, `@/` alias for cross-module
+**Error handling**: throws `AppError` with code, caught by middleware
+**Async**: async/await throughout
+
+## Unknown / Needs Investigation
+- [Things you could not determine from reading the code]
+```

package/src/skills/confidence-aware-planning/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: confidence-aware-planning
+description: Plan differently when the agent has low certainty — ask for clarification or narrow scope instead of pretending full understanding.
+origin: FlowDeck
+---
+
+# Confidence-Aware Planning
+
+Not every task comes with complete information. This skill enforces honest uncertainty signaling and adaptive planning when confidence is low.
+
+## Confidence Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| HIGH (≥80%) | Well-understood scope, clear precedent in codebase | Proceed to plan normally |
+| MEDIUM (40–79%) | Partial understanding, some unknowns | Surface assumptions, narrow scope, flag for review |
+| LOW (<40%) | Significant unknowns, no clear precedent | Ask clarifying questions first, do not plan until answered |
+
+## Signals That Lower Confidence
+
+- Codebase section not covered in `.codebase/ARCHITECTURE.md`
+- No prior DISCUSS.md for this feature area
+- Request touches 5+ files with unclear dependencies
+- Request uses domain jargon that doesn't appear in codebase
+- No test coverage in the affected area (no test files found)
+- File is in a volatile or critical zone per `.codebase/VOLATILITY.json`
+
+## Workflow
+
+Before planning ANY task:
+
+1. Read relevant codebase docs (ARCHITECTURE.md, STACK.md, CONVENTIONS.md)
+2. Scan affected files for context
+3. Estimate confidence level
+4. Act based on level:
+   - HIGH: proceed to `/plan`
+   - MEDIUM: write explicit assumptions at the top of PLAN.md, flag 3 highest risks
+   - LOW: stop, ask clarifying questions, do not write PLAN.md until answered
+
+## Clarifying Question Format
+
+When confidence is LOW, ask in this format:
+```
+Before I can plan this, I need to understand:
+
+1. [Question about scope/behavior]
+2. [Question about constraint or requirement]
+3. [Question about existing system behavior]
+
+I have LOW confidence because: [specific reason]
+```
+
+## Assumption Declaration Format
+
+When confidence is MEDIUM, include at the top of every plan:
+```markdown
+## Assumptions (MEDIUM confidence)
+- A1: [assumption] — if wrong, [consequence]
+- A2: [assumption] — if wrong, [consequence]
+
+## Risks
+1. [risk]: [mitigation]
+```
+
+## Non-negotiable
+
+Never write a plan that pretends HIGH confidence when the agent actually has LOW confidence. False certainty leads to wrong implementations and wasted effort.

package/src/skills/context-load/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: context-load
+description: Load full project context at session start. Read STATE.md, PLAN.md, PROJECT.md, CONVENTIONS.md, and ARCHITECTURE.md to brief any agent on where work stands.
+origin: FlowDeck
+---
+
+# Context Load Skill
+
+Gets any agent up to speed in under 30 seconds. Loads the minimum set of project files needed to understand what phase the work is in and what comes next.
+
+## When to Activate
+
+Activate at the start of every session, or when:
+- Starting a new OpenCode session
+- An agent seems unaware of the current project state
+- You want to brief a new agent on the project
+
+## Core Principles
+
+- Load context before asking any agent to do work
+- Read in dependency order: state first, then plan, then code conventions
+- Surface blockers immediately — don't proceed if STATE.md shows a blocker
+
+## Workflow
+
+1. **Read STATE.md** — current phase, active plan, completed steps, blockers
+2. **Read active PLAN.md** — (path from STATE.md) next tasks and success criteria
+3. **Read .planning/PROJECT.md** — project name, stack, constraints
+4. **Read .codebase/CONVENTIONS.md** — naming patterns, import style, error handling
+5. **Read .codebase/ARCHITECTURE.md** — component layout and data flow
+
+## Context Files
+
+| File | Contains | Load Order |
+|------|---------|-----------|
+| `STATE.md` | Current phase, active plan, completed steps | 1st |
+| `.planning/phases/phase-N/PLAN.md` | Tasks, success criteria | 2nd |
+| `.planning/PROJECT.md` | Project context, constraints | 3rd |
+| `.codebase/CONVENTIONS.md` | Naming, imports, patterns | 4th |
+| `.codebase/ARCHITECTURE.md` | System design, components | 5th |
+
+## Output Format
+
+After loading context, produce this briefing:
+
+```markdown
+## Project Context Loaded
+
+**Project**: [name from PROJECT.md]
+**Phase**: [N] — [phase name]
+**Status**: [discuss | plan | execute | review]
+**Active Plan**: [path to PLAN.md]
+
+**Completed Steps**: [N of M]
+**Next Step**: [next incomplete step from PLAN.md]
+
+**Blockers**: [none | description]
+
+**Stack**: [from PROJECT.md or CONVENTIONS.md]
+**Key Conventions**: [2-3 most important patterns]
+```
+
+If any file is missing, note it: "STATE.md not found — run `/new-project` to initialize."

package/src/skills/debug-flow/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: debug-flow
+description: Systematic debugging workflow. Reproduce the issue, isolate root cause, write a failing test, fix, verify. Use when diagnosing bugs or unexpected behavior.
+origin: FlowDeck
+---
+
+# Debug Flow Skill
+
+Finds root causes through systematic investigation. Does not guess. Does not fix symptoms.
+
+## When to Activate
+
+Activate when:
+- A bug has been reported
+- Code is producing unexpected output
+- Tests are failing intermittently
+- An error is occurring in production
+
+## Core Principles
+
+- Read stack traces completely — never skip to the middle
+- Fix root causes, not symptoms
+- Check recent changes first — `git log --oneline -20`
+- Reproduce before fixing — if you can't reproduce it, you don't understand it
+
+## Workflow
+
+1. **Reproduce** — confirm you can make the bug happen reliably
+2. **Read the full stack trace** — start from the top (error), trace to the origin
+3. **Check recent changes** — `git log --oneline -20` to find what changed
+4. **Trace execution backward** — what called the failing function? What state did it receive?
+5. **Identify root cause** — the earliest point where invariants are violated
+6. **Write a failing test** — one test that fails with the bug present
+7. **Fix** — change the minimum code to make the test pass
+8. **Verify** — run the full test suite
+
+## Common Root Causes
+
+| Symptom | Likely Cause | Investigation |
+|---------|-------------|---------------|
+| `Cannot read property of undefined` | Missing null check upstream | Trace where undefined enters |
+| Wrong calculation result | Type coercion (`"5" + 3 = "53"`) | Check input types |
+| Race condition / intermittent | Missing `await` | Find async functions called without await |
+| Auth bypass | Missing middleware | Check route definition vs working routes |
+| Infinite loop | Wrong termination condition | Log loop counter, check exit logic |
+| Memory leak | Event listener not cleaned up | Check `useEffect` returns, `removeListener` calls |
+| Promise rejection unhandled | Missing `.catch()` or `try/catch` | Check all async call sites |
+| Type error at runtime | `as any` hiding real type | Find where the cast was added |
+| Stale data in UI | Cache not invalidated | Check cache keys and invalidation logic |
+| Import error | Circular dependency or missing export | `npx madge --circular src/` |
+
+## Bisect for Regressions
+
+When something worked before but is broken now:
+
+```bash
+git bisect start
+git bisect bad                    # current is broken
+git bisect good [last-good-sha]   # last known working commit
+npm test                          # run after each checkout
+git bisect good                   # or: git bisect bad
+git bisect reset                  # when done
+```
+
+## Output Format
+
+```markdown
+## Debug Report
+
+**Root Cause**: [one sentence]
+**Evidence**: `path/to/file.ts:42` — [what the code does wrong]
+**Call Path**: request → controller → service → ❌ null dereference at line 42
+**Fix**: [specific change to make]
+**Test**: [name of the failing test that reproduces the bug]
+```

package/src/skills/decision-trace/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: decision-trace
+description: Record why the agent changed something, what evidence was used, and what assumptions were made — so code reviews become much faster.
+origin: FlowDeck
+---
+
+# Decision Trace
+
+Every non-trivial edit should be recorded in `.codebase/DECISIONS.jsonl`. This creates an append-only audit trail that makes code review and debugging faster.
+
+## When to Record a Decision
+
+Record when:
+- Editing a file that affects behavior (not just formatting/comments)
+- Choosing between two or more implementation approaches
+- Making an assumption about a requirement
+- Fixing a bug or regression
+- Changing an API contract or schema
+
+## How to Record
+
+Use the `decision-trace` tool:
+
+```json
+{
+  "action": "record",
+  "entry": {
+    "id": "auth-refactor-2024-05-01",
+    "file_path": "src/services/auth.ts",
+    "change_type": "edit",
+    "rationale": "Refactored token validation to use constant-time comparison to prevent timing attacks",
+    "evidence": [
+      "OWASP: timing attacks on string comparison",
+      "Prior failure: auth-timing-2024-03 in FAILURES.json"
+    ],
+    "assumptions": [
+      "Token format remains base64-encoded JWT",
+      "Redis cache is available for token blacklist"
+    ],
+    "alternatives_considered": [
+      "Keep string comparison (rejected: timing attack risk)",
+      "Move validation to edge (rejected: adds latency)"
+    ],
+    "risk_level": "medium",
+    "agent": "coder"
+  }
+}
+```
+
+## Automatic Recording
+
+The `decision-trace-hook` auto-records a minimal entry for every write/edit. The full entry (with rationale, evidence, assumptions) should be added by the agent explicitly using the tool above.
+
+## Querying Decisions
+
+```json
+// Get all decisions for a file
+{ "action": "get_for_file", "file_path": "src/services/auth.ts" }
+
+// Get all high-risk decisions
+{ "action": "query", "query": { "risk_level": "high", "limit": 10 } }
+```
+
+## Review Acceleration
+
+When reviewing a PR, query DECISIONS.jsonl for all files in the diff. For each entry, reviewers can quickly see the "why" without asking the author.
+
+## Guidance
+
+- Rationale should answer: "why this approach and not the obvious alternative?"
+- Evidence should be checkable: a doc URL, a failure ID, a test result
+- Assumptions should be explicit: if an assumption breaks, so does the change

package/src/skills/dependency-audit/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: dependency-audit
+description: Audits npm/pip/cargo dependencies for known vulnerabilities, outdated packages, and license issues. Activate before releases or when CVE alerts are received.
+origin: FlowDeck
+---
+
+# Dependency Audit Skill
+
+Checks dependencies for security vulnerabilities, outdated versions, and license issues before they cause problems in production.
+
+## When to Activate
+
+Activate when:
+- Preparing a production release
+- Receiving a CVE alert for a dependency
+- Adding a major new dependency
+- It has been more than 30 days since last audit
+
+## Core Principles
+
+- **Security over convenience** — patch vulnerabilities before releasing
+- **Patch before releasing** — critical and high findings block deployment
+- **License compliance matters** — GPL in a commercial product can create legal problems
+
+## Workflow
+
+1. Run security audit commands
+2. Triage findings by severity
+3. Check for outdated packages
+4. Check licenses of key dependencies
+5. Produce report with recommended actions
+
+## Audit Commands
+
+```bash
+# npm
+npm audit                          # all vulnerabilities
+npm audit --audit-level=moderate   # moderate and above
+npm audit fix                      # auto-fix safe upgrades
+npm audit fix --force              # force fix (may break things — test first)
+
+# Check outdated packages
+npm outdated
+
+# Snyk (more comprehensive)
+npx snyk test
+npx snyk monitor
+
+# Python
+pip-audit                          # install: pip install pip-audit
+pip list --outdated
+
+# Rust
+cargo audit                        # install: cargo install cargo-audit
+
+# Check licenses
+npx license-checker --summary
+npx license-checker --onlyAllow 'MIT;Apache-2.0;BSD-2-Clause;BSD-3-Clause;ISC'
+```
+
+## Severity Triage
+
+| Severity | Action | Timeline |
+|----------|--------|---------|
+| Critical | Fix immediately — do not deploy | Before next commit |
+| High | Fix before release | Before next deployment |
+| Moderate | Fix in next sprint | Within 2 weeks |
+| Low | Track and fix eventually | Next maintenance window |
+
+## Common Vulnerability Patterns
+
+- **Prototype pollution** — lodash <4.17.21, merge-deep <3.0.3
+- **Path traversal** — file utility packages that accept user-controlled paths
+- **ReDoS** — regex-based parsers (moment.js, validator.js older versions)
+- **Command injection** — packages that shell out with user-controlled input
+
+## Update Strategy
+
+| Change Type | Safety | Action |
+|-------------|--------|--------|
+| Patch (x.y.Z) | Very safe | Update immediately |
+| Minor (x.Y.z) | Safe with tests | Update, run full test suite |
+| Major (X.y.z) | Breaking changes likely | Read changelog, test thoroughly |
+
+```bash
+# Safe patch/minor updates
+npm update                         # updates within version constraints
+npx npm-check-updates -u --target patch  # update only patches
+```
+
+## License Audit
+
+| License | Commercial Use | Notes |
+|---------|---------------|-------|
+| MIT | ✅ Safe | Most permissive |
+| Apache 2.0 | ✅ Safe | Patent grant included |
+| BSD-2/3 | ✅ Safe | Attribution required |
+| ISC | ✅ Safe | MIT equivalent |
+| LGPL | ⚠️ Check | OK if only linking to it |
+| GPL | ❌ Risky | Legal review required for commercial |
+| AGPL | ❌ Risky | Strongest copyleft — legal review required |
+| Unknown | ❌ Investigate | Do not ship until license is known |
+
+## Output Format
+
+```markdown
+## Dependency Audit Report
+
+### Vulnerabilities
+| Package | Severity | CVE | Fix |
+|---------|----------|-----|-----|
+| lodash@4.17.19 | High | CVE-2021-23337 | Upgrade to 4.17.21 |
+
+### Outdated Packages (Major Versions)
+| Package | Current | Latest | Breaking Changes |
+|---------|---------|--------|-----------------|
+| express | 4.17.3 | 5.0.0 | Yes — read changelog |
+
+### License Issues
+| Package | License | Issue |
+|---------|---------|-------|
+| some-pkg | GPL-3.0 | Requires legal review for commercial use |
+
+### Verdict: PASS ✅ | FAIL ❌
+FAIL if any Critical or High vulnerabilities remain unfixed.
+```