@dv.nghiem/flowdeck 0.1.0

package/src/rules/typescript/patterns.md

@@ -0,0 +1,168 @@
+# TypeScript Patterns
+
+TypeScript-specific conventions and patterns for FlowDeck projects.
+
+## Strict Mode
+
+Always on. No exceptions.
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true
+  }
+}
+```
+
+## API Response Format
+
+Use a consistent response shape for all API responses:
+
+```typescript
+interface ApiResponse<T> {
+  data: T;
+  error: null;
+  metadata?: {
+    page?: number;
+    total?: number;
+    cursor?: string;
+  };
+}
+
+interface ApiError {
+  data: null;
+  error: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+}
+
+type ApiResult<T> = ApiResponse<T> | ApiError;
+```
+
+## Custom Hooks Pattern
+
+```typescript
+// ✅ Return an object (not an array) when returning multiple values
+function useAuth() {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  const login = useCallback(async (email: string, password: string) => {
+    setLoading(true);
+    try {
+      const user = await authService.login(email, password);
+      setUser(user);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  return { user, loading, login };
+}
+
+// Naming: useXxx
+// Co-locate with the component that primarily uses it
+// Return object (not array) for more than one value
+```
+
+## Repository Pattern
+
+Interface first. Concrete implementation separate. Inject at the call site.
+
+```typescript
+// Define the interface
+interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+  create(input: CreateUserInput): Promise<User>;
+  update(id: string, patch: Partial<UpdateUserInput>): Promise<User>;
+  delete(id: string): Promise<void>;
+}
+
+// Concrete implementation
+class PostgresUserRepository implements UserRepository {
+  constructor(private readonly db: Database) {}
+
+  async findById(id: string): Promise<User | null> {
+    return this.db.query('SELECT * FROM users WHERE id = $1', [id]).then(r => r.rows[0] ?? null);
+  }
+  // ...
+}
+
+// Inject at service level — never instantiate in the method
+class UserService {
+  constructor(private readonly users: UserRepository) {}
+}
+```
+
+## Result Types for Error Handling
+
+Never throw in business logic. Use Result types.
+
+```typescript
+type Ok<T> = { ok: true; value: T };
+type Err<E> = { ok: false; error: E };
+type Result<T, E = Error> = Ok<T> | Err<E>;
+
+function ok<T>(value: T): Ok<T> {
+  return { ok: true, value };
+}
+
+function err<E>(error: E): Err<E> {
+  return { ok: false, error };
+}
+
+// Usage
+async function createUser(input: CreateUserInput): Promise<Result<User, ValidationError>> {
+  const validation = validateInput(input);
+  if (!validation.ok) return err(validation.error);
+
+  const user = await db.create(input);
+  return ok(user);
+}
+
+// Caller
+const result = await createUser(input);
+if (!result.ok) {
+  logger.error('Validation failed', result.error);
+  return res.status(422).json({ error: result.error });
+}
+res.status(201).json(result.value);
+```
+
+## TypeScript Conventions
+
+```typescript
+// ✅ Interfaces for object shapes (preferred over type aliases)
+interface User {
+  id: string;
+  email: string;
+}
+
+// ✅ Type aliases for unions and complex types
+type UserRole = 'admin' | 'user' | 'guest';
+type LoadingState = 'idle' | 'loading' | 'success' | 'error';
+
+// ✅ Explicit return types on all public functions
+async function fetchUser(id: string): Promise<User | null> { ... }
+
+// ✅ Const assertions for literal types
+const ROLES = ['admin', 'user', 'guest'] as const;
+type Role = typeof ROLES[number]; // 'admin' | 'user' | 'guest'
+
+// ✅ Discriminated unions for state machines
+type RequestState =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: User }
+  | { status: 'error'; error: string };
+
+// ❌ No implicit any
+function process(data) { ... }       // ❌
+function process(data: unknown) { } // ✅
+```

package/src/skills/api-design/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: api-design
+description: REST API design patterns for resource naming, status codes, pagination, filtering, versioning, and error responses. Activate when designing or reviewing API endpoints.
+origin: FlowDeck
+---
+
+# API Design Skill
+
+REST API design patterns. Consistent, predictable, and easy to use.
+
+## When to Activate
+
+Activate when:
+- Designing new API endpoints
+- Reviewing existing API for inconsistencies
+- Adding a new resource to an existing API
+- Evaluating an external API design
+
+## Core Principles
+
+- **Nouns, not verbs** in URLs — resources, not actions
+- **Consistent naming** — same conventions throughout
+- **Standard status codes** — use what HTTP intended
+- **No breaking changes** without versioning
+
+## Resource Design
+
+```
+✅ Good:
+GET    /api/v1/users           — list users
+GET    /api/v1/users/:id       — get user by ID
+POST   /api/v1/users           — create user
+PUT    /api/v1/users/:id       — replace user
+PATCH  /api/v1/users/:id       — update user fields
+DELETE /api/v1/users/:id       — delete user
+
+❌ Bad:
+GET  /getUsers
+POST /createUser
+GET  /deleteUser?id=123
+```
+
+## HTTP Methods and Status Codes
+
+| Method | Success Code | Use For |
+|--------|-------------|---------|
+| GET | 200 OK | Retrieve resource(s) |
+| POST | 201 Created | Create new resource |
+| PUT | 200 OK | Replace entire resource |
+| PATCH | 200 OK | Update specific fields |
+| DELETE | 204 No Content | Delete resource |
+
+**Error codes:**
+| Code | Meaning |
+|------|---------|
+| 400 | Bad Request — malformed request body |
+| 401 | Unauthorized — missing or invalid auth token |
+| 403 | Forbidden — authenticated but not authorized |
+| 404 | Not Found — resource does not exist |
+| 409 | Conflict — duplicate resource |
+| 422 | Unprocessable — valid format, failed validation |
+| 429 | Too Many Requests — rate limit exceeded |
+| 500 | Internal Server Error — unexpected server failure |
+
+## Error Response Format
+
+All errors use this standard shape:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Email address is invalid",
+    "details": [
+      { "field": "email", "message": "Must be a valid email address" }
+    ]
+  }
+}
+```
+
+## Pagination
+
+**Offset-based** (simple, but slow on large datasets):
+```
+GET /api/v1/users?page=2&limit=20
+
+Response:
+{
+  "data": [...],
+  "pagination": {
+    "page": 2,
+    "limit": 20,
+    "total": 847,
+    "pages": 43
+  }
+}
+```
+
+**Cursor-based** (efficient, consistent):
+```
+GET /api/v1/users?after=cursor_abc123&limit=20
+
+Response:
+{
+  "data": [...],
+  "pagination": {
+    "nextCursor": "cursor_def456",
+    "hasMore": true
+  }
+}
+```
+
+## Filtering and Sorting
+
+```
+GET /api/v1/users?filter[status]=active
+GET /api/v1/users?filter[role]=admin&filter[status]=active
+GET /api/v1/users?sort=-createdAt          // descending
+GET /api/v1/users?sort=lastName,firstName  // multiple fields
+```
+
+## Versioning Strategy
+
+Version in the URL path:
+```
+/api/v1/users     — current stable
+/api/v2/users     — new version with breaking changes
+```
+
+Rules:
+- Never change v1 behavior once published
+- Keep v1 running for at least 12 months after v2 ships
+- Document migration guide in CHANGELOG
+
+## Rate Limiting Headers
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 87
+X-RateLimit-Reset: 1609459200
+```
+
+Return 429 when limit exceeded with `Retry-After` header.

package/src/skills/arch-constraint-guard/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: arch-constraint-guard
+description: Block edits that violate known system boundaries, team rules, service contracts, or domain-layer separation. Reads rules from .codebase/CONSTRAINTS.md.
+origin: FlowDeck
+---
+
+# Architectural Constraint Guard
+
+Before writing any file, check if the edit violates architectural boundaries defined in `.codebase/CONSTRAINTS.md`. If it does, stop and explain the violation.
+
+## CONSTRAINTS.md Format
+
+Create `.codebase/CONSTRAINTS.md` to encode your team's architectural rules:
+
+```markdown
+## Forbidden Paths
+- src/core/         # do not modify core — all changes via PR with 2 approvals
+- src/generated/    # auto-generated, do not edit manually
+- infra/secrets/    # managed by Terraform only
+
+## Layer Rules
+- UI components MUST NOT import from services/ directly — use hooks/ or context/
+- services/ MUST NOT import from routes/ — services are framework-agnostic
+- domain/ MUST NOT import from infra/ — keep domain pure
+
+## Service Contract Rules
+- PaymentService API is frozen — no method signature changes without RFC
+- UserSchema is owned by auth-team — no schema changes without approval
+
+## Naming Conventions
+- React components: PascalCase only
+- Database tables: snake_case only
+- API endpoints: kebab-case only
+```
+
+## Workflow
+
+For every proposed write or edit:
+
+1. Read `.codebase/CONSTRAINTS.md`
+2. Check the target file path against `## Forbidden Paths`
+3. Check the import graph against `## Layer Rules`
+4. Check method signatures against `## Service Contract Rules`
+5. If any violation is found: **STOP**, report the specific rule violated, and suggest a compliant alternative
+
+## When No CONSTRAINTS.md Exists
+
+If `.codebase/CONSTRAINTS.md` does not exist:
+1. Infer boundaries from ARCHITECTURE.md (layer names, service boundaries)
+2. Apply common-sense defaults: UI does not directly query DB, domain does not call HTTP
+3. Suggest creating CONSTRAINTS.md to codify the rules you discover
+
+## Violation Report Format
+
+```
+ARCH CONSTRAINT VIOLATION
+Rule: [rule name from CONSTRAINTS.md]
+File: [target file]
+Violation: [what was attempted]
+Compliant alternative: [what to do instead]
+```

package/src/skills/blast-radius-preview/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: blast-radius-preview
+description: Show the likely downstream consequences of a proposed change — hidden dependencies, fragile integration points, and predicted breakage categories.
+origin: FlowDeck
+---
+
+# Blast Radius Preview
+
+Before committing to a change, map every system that could break. Run `/blast-radius` with a change description.
+
+## When to Activate
+
+- Before merging a change that touches shared infrastructure
+- Before modifying a public API, event schema, or DB model
+- Before changing authentication or session handling
+- Any time the Impact Radar returns HIGH
+
+## Workflow
+
+1. Load the dependency graph from `.codebase/MEMORY.json`
+2. Start from the directly changed nodes
+3. Walk the graph outward: find all services/modules that depend on the changed node
+4. At each hop, check:
+   - Is this an integration point (API call, event subscription, DB query)?
+   - Does this path have regression history in `.codebase/FAILURES.json`?
+   - Is this path covered by integration tests?
+5. Flag hidden couplings: shared mutable state, ambient context, feature flags
+6. Produce the blast radius map
+
+## Blast Radius Report Format
+
+```markdown
+## Blast Radius Report
+
+### Change
+[description]
+
+### Direct Blast (depth 1)
+| Module | Coupling Type | Test Coverage | Fragile? |
+|--------|--------------|---------------|---------|
+
+### Indirect Blast (depth 2–3)
+| Module | Via | Risk Level |
+|--------|-----|------------|
+
+### Integration Point Risks
+- [endpoint/event]: [why at risk]
+
+### Hidden Couplings
+- [module]: shared state / ambient context / feature flag
+
+### Predicted Breakage Categories
+- [ ] Performance: [reason]
+- [ ] Auth: [reason]
+- [ ] Schema: [reason]
+- [ ] Async flow: [reason]
+
+### Blast Radius: NARROW | MODERATE | WIDE
+```
+
+## Guidance
+
+- NARROW: ≤3 downstream modules, all covered by tests → safe to proceed
+- MODERATE: 4–10 downstream modules or ≥1 uncovered → add tests before merging
+- WIDE: >10 downstream modules or hits fragile integration → escalate to senior review

package/src/skills/change-impact-radar/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: change-impact-radar
+description: Predict which files, modules, APIs, tests, and database paths will be affected before making any code changes. Returns an impact map for human review.
+origin: FlowDeck
+---
+
+# Change Impact Radar
+
+Predicts blast surface before the AI touches a single file. Run `/impact-radar` with a description of the intended change.
+
+## When to Activate
+
+Activate before:
+- Any multi-file refactor
+- API contract changes
+- Schema migrations
+- Dependency upgrades
+- Auth / security changes
+
+## Workflow
+
+1. Read `.codebase/ARCHITECTURE.md` and `.codebase/STACK.md` for system context
+2. Read `.codebase/MEMORY.json` to trace the module dependency graph
+3. From the change description, identify all directly affected files
+4. Walk the dependency graph outward from affected files (depth ≤ 3 hops)
+5. Cross-reference against `.codebase/VOLATILITY.json` for fragile zones
+6. Identify test files that cover the affected modules
+7. Flag any database schema, API contracts, or config changes
+8. Produce the impact map report
+
+## Impact Map Report Format
+
+```markdown
+## Change Impact Report
+
+### Direct Impact (files you will edit)
+| File | Type | Risk |
+|------|------|------|
+
+### Indirect Impact (dependents, ≤3 hops)
+| File | Dependency Chain | Risk |
+|------|-----------------|------|
+
+### API Contracts at Risk
+- [contract name]: [why at risk]
+
+### Tests to Run / Update
+- [test file]: covers [module]
+
+### Database / Config paths
+- [path]: [what changes]
+
+### Volatility Warnings
+- [file]: marked as [stability level]
+
+### Verdict: LOW | MEDIUM | HIGH impact
+```
+
+## Guidance
+
+- If MEMORY.json does not exist, run `/map-codebase` first to build the graph.
+- If a file has no test coverage and is indirectly impacted, flag it as "coverage gap".
+- Never proceed with a HIGH impact change without human confirmation.

package/src/skills/code-review/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: code-review
+description: Systematic code review covering security vulnerabilities, logic errors, and quality issues. Returns findings ranked by severity with specific remediation steps. Use before merging any change.
+origin: FlowDeck
+---
+
+# Code Review Skill
+
+Finds real problems before they reach production. Reviews only changed code, reports only confirmed issues, and provides actionable fixes.
+
+## When to Activate
+
+Activate when:
+- You just wrote or modified code
+- A PR is ready for review
+- You want a final check before pushing
+
+## Core Principles
+
+- Report only confirmed issues — 80%+ confidence before flagging
+- Severity-ranked output: Critical → High → Medium → Pass
+- Actionable fixes: every finding includes a specific remediation
+- No style nitpicks unless they mask bugs
+
+## Workflow
+
+1. Run `git diff` or read specified files
+2. Read full file context (not just the diff)
+3. Trace call sites — who calls these functions?
+4. Apply security checklist first
+5. Apply quality checklist
+6. Report by severity
+
+## Security Checklist — CRITICAL
+
+**SQL Injection:**
+```typescript
+// ❌ CRITICAL
+const q = `SELECT * FROM users WHERE id = '${userId}'`;
+// ✅ Parameterized
+const q = db.query('SELECT * FROM users WHERE id = ?', [userId]);
+```
+
+**XSS:**
+```html
+<!-- ❌ CRITICAL -->
+element.innerHTML = userInput;
+<!-- ✅ -->
+element.textContent = userInput;
+```
+
+**Hardcoded credentials:**
+```typescript
+// ❌ CRITICAL
+const SECRET = "abc123hardcoded";
+// ✅
+const SECRET = process.env.API_SECRET;
+```
+
+**Path traversal:**
+```typescript
+// ❌ CRITICAL
+fs.readFile(`./uploads/${filename}`);
+// ✅
+fs.readFile(path.join('./uploads', path.basename(filename)));
+```
+
+## Quality Checklist — HIGH
+
+- Functions over 50 lines → extract
+- Nesting deeper than 3 levels → extract guard clauses
+- Empty or silent catch blocks → log and rethrow
+- Dead code (defined but never called) → remove
+
+## Performance — MEDIUM
+
+- N+1 queries: database call inside a loop
+- Missing pagination on list endpoints
+- Synchronous I/O in hot paths
+
+## Best Practices — LOW
+
+- Inconsistent naming within a file
+- Missing JSDoc on public functions
+- `console.log` left in production code
+
+## Output Format
+
+```markdown
+## Code Review Report
+
+### 🔴 CRITICAL (must fix before merge)
+| # | File | Line | Issue | Fix |
+|---|------|------|-------|-----|
+| 1 | auth.ts | 42 | SQL injection | Use parameterized query |
+
+### 🟠 HIGH (fix before merge)
+| # | File | Line | Issue | Fix |
+|---|------|------|-------|-----|
+
+### 🟡 MEDIUM (fix in follow-up)
+| # | File | Line | Issue | Fix |
+|---|------|------|-------|-----|
+
+### ✅ PASS
+- Auth middleware: present on all protected routes
+- Input validation: correct at all boundaries
+```

package/src/skills/code-tour/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: code-tour
+description: Creates guided code walkthroughs as structured markdown documents. Use when onboarding new developers, explaining architecture, or creating PR review guides.
+origin: FlowDeck
+---
+
+# Code Tour Skill
+
+Creates step-by-step walkthroughs of a codebase or code change. Makes complex code navigable.
+
+## When to Activate
+
+Activate when:
+- Onboarding a new developer to the codebase
+- Explaining a complex architecture to stakeholders
+- Creating a PR review guide for a large change
+- Documenting how a specific flow works (auth, billing, etc.)
+
+## Core Principles
+
+- **Audience-first** — write for someone unfamiliar with this code
+- **Verified paths** — every file path and line number must be real and current
+- **Why, not just what** — explain the design decisions, not just what the code does
+
+## Workflow
+
+1. **Identify audience** — new developer? tech lead? domain expert?
+2. **Choose scope** — full codebase? single feature? specific PR?
+3. **Read and verify** — read every file you will reference; confirm paths exist
+4. **Write tour steps** — numbered, with file path, code snippet, explanation, and why
+5. **Validate paths** — run `ls` on each referenced file to confirm it exists
+
+## Tour Format
+
+Each step follows this structure:
+
+```markdown
+### Step N: [What This Step Shows]
+
+**File**: `src/path/to/file.ts` (lines 23-45)
+
+```typescript
+// paste the relevant code snippet here
+```
+
+**What it does**: [One or two sentences explaining the code]
+
+**Why it's designed this way**: [The design rationale]
+
+**What to notice**: [The most important thing to understand]
+```
+
+## Tour Types
+
+| Type | Audience | Scope | Focus |
+|------|---------|-------|-------|
+| Onboarding | New developer | Full codebase | Entry points, key patterns, conventions |
+| Architecture | Tech lead / stakeholder | System design | Component relationships, data flow |
+| PR Review | Reviewer | Changed files | What changed, why, how to verify |
+| RCA (Root Cause Analysis) | Team | Bug site | Call path, where it broke, why |
+
+## Full Tour Template
+
+```markdown
+# Code Tour: [Title]
+
+## Audience
+[Who this tour is for]
+
+## Scope
+[What this tour covers]
+
+## Prerequisites
+- [What the reader should already know]
+
+---
+
+### Step 1: Entry Point
+
+**File**: `src/index.ts` (line 1)
+[code snippet]
+[explanation]
+
+### Step 2: [Next Concept]
+[...]
+
+---
+
+## Summary
+
+[2-3 sentences: what we walked through and what matters most]
+
+## Next Steps
+
+- [What to read next]
+- [What to try next]
+```
+
+## Output
+
+Save tours to `.codebase/tours/[topic].md` or `docs/tours/[topic].md`.