@dv.nghiem/flowdeck 0.1.0

package/src/rules/common/coding-style.md

@@ -0,0 +1,120 @@
+# Coding Style
+
+Language-agnostic coding conventions followed by all FlowDeck agents.
+
+## Immutability
+
+Always create new objects and arrays. Never mutate parameters.
+
+```typescript
+// ❌ NEVER — mutating a parameter
+function addRole(user: User, role: string): void {
+  user.roles.push(role);
+}
+
+// ✅ ALWAYS — return new object
+function addRole(user: User, role: string): User {
+  return { ...user, roles: [...user.roles, role] };
+}
+```
+
+## KISS / DRY / YAGNI
+
+| Principle | Rule |
+|-----------|------|
+| **KISS** (Keep It Simple) | The simplest solution that works is the right solution |
+| **DRY** (Don't Repeat Yourself) | Extract duplication only when you have 3+ identical instances |
+| **YAGNI** (You Aren't Gonna Need It) | Don't add features for hypothetical future needs |
+
+```typescript
+// ❌ YAGNI — configurable for no reason
+function createUser(email: string, options: {
+  hashAlgorithm?: 'bcrypt' | 'argon2';  // only ever bcrypt in practice
+  saltRounds?: number;
+  legacyCompatMode?: boolean;
+}) { ... }
+
+// ✅ Simple
+function createUser(email: string, password: string): Promise<User> { ... }
+```
+
+## File Organization
+
+- Many small, focused files > few large files
+- **Typical file size**: 200-400 lines
+- **Maximum**: 800 lines — if larger, split it
+- **One responsibility per file**: `user-service.ts`, not `all-services.ts`
+
+## Error Handling
+
+Handle errors explicitly at every level. Never swallow errors silently.
+
+```typescript
+// ❌ Silent catch — hides failures
+try {
+  await saveUser(user);
+} catch (e) {}
+
+// ❌ Logging without rethrowing — caller doesn't know it failed
+try {
+  await saveUser(user);
+} catch (e) {
+  console.error(e);
+}
+
+// ✅ Explicit — log context, rethrow or convert to domain error
+try {
+  await saveUser(user);
+} catch (error) {
+  logger.error('Failed to save user', { userId: user.id, error });
+  throw new ServiceError('USER_SAVE_FAILED', { cause: error });
+}
+```
+
+Errors propagate upward unless you have a specific reason to handle them at this level.
+
+## Input Validation
+
+Validate all external inputs at the system boundary:
+
+```typescript
+// System boundaries where validation is required:
+// - API endpoints (HTTP request body, query params, headers)
+// - File uploads (type, size, content)
+// - Environment variables (on startup)
+// - User input from forms
+
+// ✅ Validate at the boundary — not deep in business logic
+router.post('/users', async (req, res) => {
+  const result = createUserSchema.safeParse(req.body);
+  if (!result.success) {
+    return res.status(422).json({ error: result.error.flatten() });
+  }
+  const user = await userService.create(result.data);
+  res.status(201).json(user);
+});
+```
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|-----------|---------|
+| Variables | camelCase | `userEmail`, `isActive` |
+| Functions | camelCase | `createUser()`, `fetchProfile()` |
+| Types / Interfaces | PascalCase | `User`, `CreateUserInput` |
+| Classes | PascalCase | `UserService`, `PaymentGateway` |
+| React Components | PascalCase | `UserCard`, `LoginForm` |
+| Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT` |
+| Files | kebab-case | `user-service.ts`, `auth-middleware.ts` |
+| Directories | kebab-case | `user-management/`, `api-routes/` |
+
+## Code Smells to Avoid
+
+| Smell | Threshold | Fix |
+|-------|-----------|-----|
+| Deep nesting | > 3 levels | Extract guard clauses or helper functions |
+| Magic numbers | Any unlabeled number | Name the constant: `MAX_ITEMS = 100` |
+| Long functions | > 50 lines | Extract smaller functions |
+| Boolean parameters | Any `doThing(true)` | Use options object: `doThing({ verbose: true })` |
+| Long argument lists | > 3 parameters | Use an options object |
+| Implicit any | Any untyped value | Add explicit type annotation |

package/src/rules/common/git-workflow.md

@@ -0,0 +1,77 @@
+# Git Workflow
+
+Conventional commits, clean history, and structured PR workflow.
+
+## Conventional Commit Format
+
+```
+type(scope): description
+
+[optional body — explain the why, not the what]
+
+[optional footer — breaking changes, issue references]
+```
+
+All commits on the main branch must follow this format.
+
+## Commit Types
+
+| Type | Version Bump | When to Use | Example |
+|------|-------------|-------------|---------|
+| `feat` | minor | New feature | `feat(auth): add JWT refresh endpoint` |
+| `fix` | patch | Bug fix | `fix(auth): correct token expiry calculation` |
+| `perf` | patch | Performance | `perf(db): replace N+1 with single JOIN query` |
+| `refactor` | patch | Restructure | `refactor(user): extract password validation` |
+| `docs` | none | Documentation | `docs(api): document authentication endpoints` |
+| `test` | none | Tests | `test(auth): add coverage for expired tokens` |
+| `chore` | none | Maintenance | `chore(deps): update express to 4.18.2` |
+| `ci` | none | CI/CD | `ci(github): add node 20 to test matrix` |
+| `build` | none | Build system | `build: switch to esbuild` |
+
+### Breaking Changes
+
+```
+feat!: remove deprecated v1 authentication endpoints
+
+BREAKING CHANGE: The /api/v1/auth/* endpoints have been removed.
+Migrate to /api/v2/auth/* before upgrading.
+See MIGRATION.md for details.
+```
+
+## Branch Naming
+
+```
+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 fix
+refactor/extract-auth-middleware     — restructuring
+docs/update-api-reference            — docs only
+```
+
+## PR Workflow
+
+1. Create branch from `main` with proper naming
+2. Make small, atomic commits with conventional messages
+3. Rebase onto latest `main` before creating PR
+4. Create PR with descriptive title and description
+5. Requires at least 1 reviewer approval
+6. All checks must pass (tests, types, lint)
+7. Merge via squash merge for small features, regular merge for large ones
+
+## Rebase vs Merge
+
+| Situation | Use | Command |
+|-----------|-----|---------|
+| Local feature before PR | Rebase | `git rebase origin/main` |
+| PR → main | Squash (small features) or Merge (large) | GitHub UI |
+| Release branch | Merge with `--no-ff` | `git merge --no-ff release/v1.2.0` |
+| **Never** | Force-push to main | — |
+
+## Commit Hygiene
+
+- **Atomic commits** — one logical change per commit
+- **No WIP commits** on shared branches
+- **Fix typos** by amending the last commit (`git commit --amend`), not a new commit
+- **No "fix build" commits** — fix locally, amend, and force-push the feature branch

package/src/rules/common/security.md

@@ -0,0 +1,94 @@
+# Security Standards
+
+Security requirements that apply to all code. These are checked before every merge and deployment.
+
+## Pre-Commit Security Checklist
+
+Before every commit touching auth, data access, or API routes:
+
+- [ ] No hardcoded credentials, API keys, or secrets
+- [ ] All database queries use parameterized inputs (no string concatenation)
+- [ ] Input validated at all API boundaries
+- [ ] Auth middleware present on all protected routes
+- [ ] No passwords, tokens, or sensitive data in log statements
+- [ ] New dependencies checked for known CVEs (`npm audit`)
+
+## Secret Management
+
+```typescript
+// ❌ NEVER — hardcoded secret
+const JWT_SECRET = "my-super-secret-key-abc123";
+
+// ✅ ALWAYS — environment variable
+const JWT_SECRET = process.env.JWT_SECRET;
+if (!JWT_SECRET) throw new Error('JWT_SECRET environment variable is required');
+```
+
+Rules:
+- Use `process.env` for all secrets
+- Use `.env.local` (never `.env`) for local development
+- Add `.env*` to `.gitignore` (verify it's there)
+- Use a secret manager (AWS Secrets Manager, Vault) in production
+- Rotate any secret that was accidentally committed
+
+## OWASP Top 10 Quick Reference
+
+| ID | Vulnerability | One-Line Check |
+|----|--------------|---------------|
+| A01 | Broken Access Control | Does every protected route check auth AND authorization? |
+| A02 | Cryptographic Failures | Is sensitive data encrypted in transit and at rest? |
+| A03 | Injection | Are all queries parameterized? All shell commands sanitized? |
+| A04 | Insecure Design | Is there rate limiting? Account lockout after failed logins? |
+| A05 | Security Misconfiguration | Is debug mode off? Are default credentials changed? |
+| A06 | Vulnerable Components | Does `npm audit` show zero critical/high? |
+| A07 | Auth Failures | Are JWTs validated? Sessions invalidated on logout? |
+| A08 | Integrity Failures | Is all user input validated before processing? |
+| A09 | Logging Failures | Are errors logged? Are passwords/tokens excluded from logs? |
+| A10 | SSRF | Are server-side URL fetches restricted to allowlisted domains? |
+
+## Security Response Protocol
+
+**If a secret is accidentally committed:**
+1. Rotate the secret immediately — assume it is compromised
+2. Force-push or use BFG Repo Cleaner to remove from git history
+3. Audit access logs for the period the secret was exposed
+4. Notify your security team
+
+```bash
+# Remove secret from git history (after rotating it)
+git filter-branch --force --index-filter \
+  'git rm --cached --ignore-unmatch path/to/secret-file' \
+  --prune-empty --tag-name-filter cat -- --all
+```
+
+## Input Validation Requirements
+
+Validate at every trust boundary:
+
+```typescript
+// Required validations for every external input:
+// 1. Type — is it a string? number? object?
+// 2. Length — is it within expected bounds?
+// 3. Format — does it match the expected pattern?
+// 4. Range — for numbers, within acceptable range?
+
+// ✅ Example with Zod
+const createUserSchema = z.object({
+  email: z.string().email().max(255),
+  password: z.string().min(8).max(128),
+  role: z.enum(['user', 'admin']).default('user'),
+});
+```
+
+For security-critical fields (passwords, tokens, IDs): **reject** invalid input, do not sanitize.
+
+## Rate Limiting Requirements
+
+All public-facing endpoints must have rate limiting:
+
+```typescript
+// Minimum rate limits:
+// - Authentication endpoints: 5 attempts per minute per IP
+// - Public API: 100 requests per minute per user/IP
+// - Password reset: 3 attempts per hour per email
+```

package/src/rules/common/testing.md

@@ -0,0 +1,105 @@
+# Testing Standards
+
+All code must meet these testing standards before being considered done.
+
+## Minimum Coverage
+
+**80% line coverage** — non-negotiable.
+
+```bash
+npx vitest --coverage          # vitest
+npx jest --coverage            # jest
+```
+
+A task is not complete until coverage is ≥ 80%.
+
+## TDD Workflow
+
+Follow Red-Green-Refactor for all new code:
+
+1. **Red** — write a failing test that describes the desired behavior
+2. **Green** — write the minimum code to make it pass
+3. **Refactor** — clean up while keeping tests green
+4. **Commit** — commit the test + implementation together
+
+Never write implementation before writing a failing test.
+
+## Test Types
+
+| Type | Purpose | Tools | When Required |
+|------|---------|-------|--------------|
+| Unit | Functions in isolation, mocked deps | vitest, jest | Every function with logic |
+| Integration | API + database end-to-end | supertest, vitest | Every API route |
+| E2E | Full user flow in browser | playwright, cypress | Critical user journeys |
+
+## AAA Pattern
+
+Every test uses Arrange-Act-Assert:
+
+```typescript
+describe('UserService.create', () => {
+  it('should throw ValidationError when email format is invalid', async () => {
+    // Arrange
+    const service = new UserService(mockDb);
+    const input = { email: 'not-an-email', password: 'valid-pass' };
+
+    // Act
+    const result = service.create(input);
+
+    // Assert
+    await expect(result).rejects.toThrow('ValidationError');
+  });
+});
+```
+
+## Test Naming
+
+Test names describe behavior in plain language:
+
+```typescript
+// ✅ Describes behavior
+it('should return empty array when user has no orders')
+it('should throw AuthError when token is expired')
+it('should send confirmation email after successful registration')
+
+// ❌ Vague
+it('test1')
+it('works')
+it('handles the error case')
+```
+
+Format: `should [expected behavior] when [condition]`
+
+## Test Organization
+
+- **Co-locate** tests with source: `user-service.ts` → `user-service.test.ts`
+- Or use a parallel `__tests__/` directory — be consistent within the project
+- One `describe` block per module or class
+- Group related tests with nested `describe` blocks
+
+## What to Test
+
+- Public interfaces and API contracts
+- Error conditions and edge cases
+- Auth scenarios (unauthenticated, unauthorized, correct role)
+- Empty inputs, null, undefined
+- Boundary values (max length, zero, negative numbers)
+
+## What NOT to Test
+
+- Private methods (test via public interface)
+- Third-party library behavior
+- Simple getters with no logic
+- Framework internals (Express routing, ORM query builder)
+
+## Troubleshooting Test Failures
+
+| Situation | Action |
+|-----------|--------|
+| Test fails after code change | Fix the implementation |
+| Test fails after refactor | Undo the refactor; take smaller steps |
+| Test fails and assertion is wrong | Fix the assertion (rare — verify carefully) |
+| Tests are flaky | Find and isolate the shared mutable state |
+| Coverage below 80% | Add tests for uncovered branches and edge cases |
+
+**Never change a test to make it pass unless the assertion logic itself is wrong.**

package/src/rules/golang/patterns.md

@@ -0,0 +1,187 @@
+# Go Patterns
+
+Go conventions for FlowDeck projects.
+
+## Always Handle Errors Explicitly
+
+Never discard error return values with `_`. Every error must be checked and either handled or propagated.
+
+```go
+// ❌ Silently discarding the error
+result, _ := parseConfig(path)
+
+// ✅ Check and handle or propagate
+result, err := parseConfig(path)
+if err != nil {
+    return fmt.Errorf("startup: %w", err)
+}
+```
+
+## Error String Style
+
+Error strings must be lowercase and have no trailing punctuation. They are often wrapped and appear mid-sentence in logs.
+
+```go
+// ❌ Uppercase, trailing period
+errors.New("Connection refused.")
+
+// ✅ Lowercase, no trailing punctuation
+errors.New("connection refused")
+fmt.Errorf("user %d: record not found", id)
+```
+
+## Interface Naming
+
+- Single-method interfaces: use the method name with the `-er` suffix.
+- Multi-method interfaces: use a noun that describes the role.
+
+```go
+// ✅ Single-method
+type Reader interface { Read(p []byte) (int, error) }
+type Stringer interface { String() string }
+type Notifier interface { Notify(ctx context.Context, msg Message) error }
+
+// ✅ Multi-method
+type UserStore interface {
+    FindByID(ctx context.Context, id int64) (*User, error)
+    Save(ctx context.Context, u *User) error
+}
+```
+
+## Exported Names Must Have Doc Comments
+
+Every exported function, type, method, and variable requires a doc comment beginning with the name.
+
+```go
+// ❌ Missing doc comment
+func ProcessOrder(o *Order) error { ... }
+
+// ✅ Doc comment starting with the name
+// ProcessOrder validates and persists an order, charging the associated payment method.
+func ProcessOrder(o *Order) error { ... }
+```
+
+## context.Context as First Parameter
+
+All functions that perform I/O, call external services, or could be long-running must accept `context.Context` as their first parameter.
+
+```go
+// ❌ No context — cannot be cancelled or carry deadlines
+func FetchUser(id int64) (*User, error) { ... }
+
+// ✅ context.Context first
+func FetchUser(ctx context.Context, id int64) (*User, error) { ... }
+```
+
+## Never panic for Expected Errors
+
+Use `panic` only for programmer errors (invariant violations, impossible states). Use error returns for expected failure modes.
+
+```go
+// ❌ panic for expected failure
+func ParseConfig(data []byte) Config {
+    var cfg Config
+    if err := json.Unmarshal(data, &cfg); err != nil {
+        panic(err)  // config may be invalid at runtime — this is expected
+    }
+    return cfg
+}
+
+// ✅ Return error for expected failure
+func ParseConfig(data []byte) (Config, error) {
+    var cfg Config
+    if err := json.Unmarshal(data, &cfg); err != nil {
+        return Config{}, fmt.Errorf("parse config: %w", err)
+    }
+    return cfg, nil
+}
+```
+
+## Table-Driven Tests
+
+Any function with more than one meaningful input/output combination requires a table-driven test using `t.Run`.
+
+```go
+func TestDivide(t *testing.T) {
+    cases := []struct {
+        name    string
+        a, b    float64
+        want    float64
+        wantErr bool
+    }{
+        {name: "simple division", a: 10, b: 2, want: 5},
+        {name: "divide by zero", a: 5, b: 0, wantErr: true},
+        {name: "negative divisor", a: 9, b: -3, want: -3},
+    }
+    for _, tc := range cases {
+        t.Run(tc.name, func(t *testing.T) {
+            got, err := Divide(tc.a, tc.b)
+            if (err != nil) != tc.wantErr {
+                t.Fatalf("Divide(%v, %v) err = %v, wantErr %v", tc.a, tc.b, err, tc.wantErr)
+            }
+            if !tc.wantErr && got != tc.want {
+                t.Errorf("Divide(%v, %v) = %v, want %v", tc.a, tc.b, got, tc.want)
+            }
+        })
+    }
+}
+```
+
+## Static Analysis
+
+All code must pass:
+
+```bash
+go vet ./...
+staticcheck ./...
+golangci-lint run
+```
+
+Run these in CI before merge. Do not suppress linter warnings without a comment explaining why.
+
+## Avoid Global State
+
+Prefer dependency injection via struct fields over package-level variables. Global state makes testing and concurrent use difficult.
+
+```go
+// ❌ Package-level global
+var defaultClient = &http.Client{Timeout: 10 * time.Second}
+
+func Fetch(url string) ([]byte, error) {
+    resp, err := defaultClient.Get(url)
+    ...
+}
+
+// ✅ Injected via struct
+type APIClient struct {
+    http *http.Client
+}
+
+func NewAPIClient(http *http.Client) *APIClient {
+    return &APIClient{http: http}
+}
+
+func (c *APIClient) Fetch(ctx context.Context, url string) ([]byte, error) {
+    req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
+    resp, err := c.http.Do(req)
+    ...
+}
+```
+
+## Never Start Goroutines in init() or Package-Level Vars
+
+Goroutines started at package init time cannot be cancelled, cannot propagate errors, and make test isolation impossible.
+
+```go
+// ❌ Goroutine in init
+func init() {
+    go backgroundWorker()  // leaks, cannot cancel, runs in every test
+}
+
+// ✅ Start goroutines from an explicit lifecycle method
+type Worker struct { done chan struct{} }
+
+func (w *Worker) Start(ctx context.Context) {
+    go w.run(ctx)
+}
+```