@sixfactors-ai/codeloop 0.1.1 → 0.2.0

package/templates/commands/qa.md

@@ -0,0 +1,155 @@
+---
+description: Quality gate — run all checks before promoting a task
+argument-hint: [--strict] [--skip-tests]
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+<!-- codeloop-version: 0.2.0 -->
+
+# /qa
+
+The quality gate between coding and deployment. Runs all configured checks and gates task promotion.
+
+> **When to use `/qa` vs `/test`**: `/test` is for quick dev feedback — run a suite, check coverage, iterate. `/qa` is the formal gate — it runs everything (`quality_checks` + `diff_scan` + full test suite + coverage threshold + integrity checks) and sets the `env:local-pass` label that unlocks `/deploy staging`. Use `/qa` when the task is code-complete and ready for promotion.
+
+## Usage
+
+```bash
+/qa                # Run full QA suite for active task
+/qa --strict       # Fail on warnings too (not just errors)
+/qa --skip-tests   # Skip test suite (only run static checks)
+```
+
+## Phase 1: Gather Context
+
+1. Read `.codeloop/config.yaml` — load `test`, `quality_checks`, `diff_scan` sections
+2. Read `.codeloop/board.json` — find the active task (first `in_progress`, then `planned`)
+3. Get the git diff since the task started:
+   - If the task has commits, diff from the first commit to HEAD
+   - If no commits yet, diff from HEAD (unstaged + staged changes)
+4. Map changed files to scopes (same logic as `/commit` Phase 1)
+
+## Phase 2: Run Checks
+
+Execute each check category in order. A failure in any REQUIRED check blocks promotion.
+
+### 2.1 Static Analysis
+
+Run `quality_checks` from config for active scopes:
+
+```yaml
+quality_checks:
+  backend:
+    - name: "Typecheck"
+      command: "npx tsc --noEmit 2>&1 | tail -20"
+```
+
+Each check: run command, capture output, exit 0 = PASS, non-zero = FAIL.
+
+### 2.2 Diff Scan
+
+Run `diff_scan` rules from config against the diff (same as `/commit` Phase 1.5):
+
+```yaml
+diff_scan:
+  - pattern: "console\\.log"
+    files: "*.ts,*.js"
+    severity: CRITICAL
+    message: "console.log in production code"
+```
+
+### 2.3 Test Suite
+
+Run the test command from config (same as `/test`):
+
+```yaml
+test:
+  command: "npm test"
+  coverage_threshold: 80
+  integrity_checks: true
+```
+
+Parse results: pass/fail/skip counts and coverage percentage.
+
+If `integrity_checks: true`, scan test output for suspicious patterns:
+- Tests with zero assertions
+- `expect(true).toBe(true)` or equivalent no-op assertions
+- Skipped tests (`.skip`, `@pytest.mark.skip`) — count but don't fail
+- Caught exceptions that are silently swallowed
+
+### 2.4 Coverage Gate
+
+If `test.coverage_threshold` is set:
+- Coverage >= threshold → PASS
+- Coverage < threshold → FAIL with gap report
+
+Pass `--skip-tests` to bypass 2.3 and 2.4 (only run static checks).
+
+## Phase 3: Report
+
+```
+## QA Report
+
+**Task**: t-003 — Add user authentication
+**Scopes**: backend, tests
+**Mode**: standard (--strict would fail on warnings too)
+
+### Results
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Typecheck | ✓ PASS | Clean |
+| Lint | ✓ PASS | Clean |
+| Diff scan | ⚠ WARN | 1 TODO comment found |
+| Tests | ✓ PASS | 42/42 passed (3.2s) |
+| Coverage | ✓ PASS | 84% (threshold: 80%) |
+| Integrity | ✓ PASS | No suspicious patterns |
+
+### Verdict: PASS (1 warning)
+
+Ready to promote to review.
+```
+
+Verdicts:
+- **PASS** — all required checks pass, warnings are informational
+- **WARN** — warnings present but no failures (blocked in `--strict` mode)
+- **FAIL** — one or more required checks failed, promotion blocked
+
+### On FAIL
+
+Show each failure with details:
+- What failed and why
+- The specific output or pattern that triggered it
+- Suggestion for how to fix
+
+Use AskUserQuestion:
+- **Fix issues** — stop, user fixes and re-runs `/qa`
+- **Override and promote** — bypass the gate (adds `qa:override` label)
+- **Abort** — stop entirely
+
+### On PASS
+
+Continue to Phase 4.
+
+## Phase 4: Promote
+
+If all checks pass (or user overrides):
+
+1. **Board sync** — update the active task:
+   - Set status to `review`
+   - Add label: `env:local-pass`
+   - Add label: `qa:pass` (or `qa:override` if overridden)
+   - Remove any existing `qa:fail` label
+   - Write updated board
+
+2. **History** — append to `.codeloop/test-history.json` if tests were run
+
+3. Report: "Task t-003 promoted to review. Ready for `/deploy staging`."
+
+## Rules
+
+- **The gate is the contract.** `/qa` is what prevents "it works on my machine."
+- **Don't skip tests unless asked.** The `--skip-tests` flag exists for iteration speed, not for cheating.
+- **Warnings are informational in standard mode.** They don't block unless `--strict`.
+- **Override is tracked.** `qa:override` label is visible on the board — it's a code smell, not a secret.
+- **Run before every deploy.** `/deploy` checks for the `env:local-pass` label.

package/templates/commands/ship.md

@@ -0,0 +1,187 @@
+---
+description: Close the loop — QA, deploy staging, deploy prod, verify, close task
+argument-hint: [--from-staging] [--dry-run]
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+<!-- codeloop-version: 0.2.0 -->
+
+# /ship
+
+Orchestrate the full pipeline from QA to production. Takes a task from code-complete to done.
+
+## Usage
+
+```bash
+/ship                    # Full pipeline: QA → staging → prod → close
+/ship --from-staging     # Skip QA + staging (already staging-verified)
+/ship --dry-run          # Show what would happen without executing
+```
+
+## Overview
+
+`/ship` chains together existing skills in sequence:
+
+```
+/qa → /deploy staging → /deploy prod → /manage close
+```
+
+Each step is a gate. If any step fails, the pipeline stops and creates a regression task.
+
+## Phase 1: Pre-Flight
+
+1. Read `.codeloop/config.yaml` — verify `deploy` section exists with non-empty staging and production commands (empty string = not configured → stop)
+2. Read `.codeloop/board.json` — find the active task
+3. If no active task → stop: "No active task found. Use `/plan` to create one."
+4. Check current task labels to determine starting point:
+   - Has `env:prod-pass` → "Task already production-verified. Use `/manage close` to finish."
+   - Has `env:staging-pass` (or `--from-staging`) → skip to production deploy
+   - Has `env:local-pass` → skip to staging deploy
+   - No env labels → start from QA
+
+5. If `--dry-run`, show the plan and stop:
+   ```
+   ## Ship Plan (dry run)
+
+   **Task**: t-003 — Add user authentication
+   **Starting from**: QA (no env labels)
+
+   Steps:
+   1. Run /qa (quality gate)
+   2. Deploy to staging + verify
+   3. Deploy to production + verify
+   4. Close task + archive
+
+   No actions taken.
+   ```
+
+## Phase 2: QA Gate
+
+Skip if task already has `env:local-pass`.
+
+1. Run the same checks as `/qa`:
+   - Quality checks for active scopes
+   - Diff scan
+   - Test suite
+   - Coverage gate
+2. If **FAIL** → stop pipeline, report which check failed, create regression task
+3. If **PASS** → add `env:local-pass` label, continue
+
+Report progress:
+```
+## Ship Progress
+
+[✓] QA gate passed
+[ ] Deploy to staging
+[ ] Deploy to production
+[ ] Close task
+```
+
+## Phase 3: Deploy Staging
+
+Skip if task already has `env:staging-pass`.
+
+1. Run staging deploy command from config
+2. If deploy fails → stop pipeline, add `env:staging-fail` label, create regression task
+3. Wait 5 seconds, run staging verify command
+4. If verify fails → stop pipeline, add `env:staging-fail` label, create regression task
+5. If both succeed → add `env:staging-pass` label, continue
+
+```
+## Ship Progress
+
+[✓] QA gate passed
+[✓] Staging deployed + verified
+[ ] Deploy to production
+[ ] Close task
+```
+
+## Phase 4: Deploy Production
+
+**Always confirm before production deploy:**
+
+```
+## Production Deploy
+
+Task t-003 has passed QA and staging verification.
+
+Ready to deploy to production?
+```
+
+Use AskUserQuestion: **Deploy to production** / **Stop here** / **Abort and rollback**
+
+If confirmed:
+1. Run production deploy command from config
+2. If deploy fails → stop, add `env:prod-fail` label, create regression task
+3. Wait 5 seconds, run production verify command
+4. If verify fails → stop, add `env:prod-fail` label, create regression task
+5. If both succeed → add `env:prod-pass` label, continue
+
+```
+## Ship Progress
+
+[✓] QA gate passed
+[✓] Staging deployed + verified
+[✓] Production deployed + verified
+[ ] Close task
+```
+
+## Phase 5: Close
+
+1. Update the board task:
+   - Set status to `done`
+   - Add label: `shipped`
+2. Archive the task file:
+   - Move `tasks/todo.md` to `tasks/done/<task-slug>.md` (create dir if needed)
+3. Final report
+
+## Phase 6: Report
+
+### On Success
+
+```
+## Shipped ✓
+
+**Task**: t-003 — Add user authentication
+**Pipeline**: QA → staging → production → done
+
+| Stage | Status | Duration |
+|-------|--------|----------|
+| QA | ✓ pass | 12s |
+| Staging | ✓ deployed + verified | 45s |
+| Production | ✓ deployed + verified | 52s |
+
+Task archived to `tasks/done/add-user-authentication.md`.
+Board updated: t-003 → done.
+```
+
+### On Failure
+
+```
+## Ship Failed at: staging deploy
+
+**Task**: t-003 — Add user authentication
+**Failed step**: Deploy to staging
+**Error**: Exit code 1 — "Error: no instances available"
+
+Regression task t-006 created: "Fix: staging deploy failure for auth feature"
+Pipeline stopped. Fix the issue and re-run `/ship --from-staging`.
+```
+
+## Regression Task Creation
+
+When any step fails:
+1. Create a new task on the board:
+   - Title: "Fix: <failure summary>"
+   - Status: `backlog`
+   - Labels: `regression`, `env:<stage>-fail`
+   - Description: full error output, which step failed, and the original task reference
+2. The original task stays at its current status (not moved to done)
+
+## Rules
+
+- **Always confirm production.** Never auto-deploy to production — the human makes the final call.
+- **The pipeline is sequential.** QA → staging → prod. No skipping without explicit flags.
+- **Failure creates tracking.** Every failure gets a regression task — nothing falls through the cracks.
+- **Idempotent resumption.** `/ship` checks labels and skips already-passed stages. Safe to re-run after fixing a failure.
+- **`--from-staging` trusts staging.** Use when you've already verified staging manually or in a previous run.

package/templates/commands/test.md

@@ -0,0 +1,133 @@
+---
+description: Run tests, parse results, track coverage history
+argument-hint: [suite] [--watch] [--coverage]
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+<!-- codeloop-version: 0.2.0 -->
+
+# /test
+
+Run tests, parse results, and track coverage over time.
+
+> **When to use `/test` vs `/qa`**: Use `/test` for quick feedback during development — run a specific suite, check coverage, iterate. Use `/qa` when you're ready to promote a task — it runs the full test suite plus static analysis, coverage gates, and integrity checks, and sets the `env:local-pass` label that unlocks `/deploy`. `/test` does NOT set env labels.
+
+## Usage
+
+```bash
+/test                    # Run default test command from config
+/test <suite>            # Run specific test suite or file pattern
+/test --watch            # Run in watch mode (if runner supports it)
+/test --coverage         # Run with coverage reporting
+```
+
+## Phase 1: Detect
+
+1. Read `.codeloop/config.yaml` for the `test` section:
+   ```yaml
+   test:
+     command: "npm test"
+     coverage_threshold: 80
+   ```
+2. If no `test.command` configured, auto-detect the test runner:
+   - `package.json` with `scripts.test` → use `npm test`
+   - `vitest.config.*` → `npx vitest run`
+   - `jest.config.*` → `npx jest`
+   - `pyproject.toml` with `[tool.pytest]` → `pytest`
+   - `go.mod` → `go test ./...`
+   - `Cargo.toml` → `cargo test`
+   - If nothing detected → ask the user what command to run
+
+## Phase 2: Run
+
+1. If `<suite>` argument provided, append it to the test command (e.g., `npm test -- src/auth/`)
+2. If `--watch` flag, append watch flag for the detected runner:
+   - vitest: already defaults to watch in dev, use `npx vitest`
+   - jest: `--watch`
+   - pytest: use `pytest-watch` or `ptw`
+   - go: no native watch — inform user
+3. If `--coverage` flag, append coverage flag:
+   - vitest/jest: `--coverage`
+   - pytest: `--cov`
+   - go: `-cover`
+4. Run the command, capture stdout and stderr
+
+## Phase 3: Parse Results
+
+Parse the test runner output to extract:
+
+| Field | Example |
+|-------|---------|
+| Total tests | 42 |
+| Passed | 40 |
+| Failed | 1 |
+| Skipped | 1 |
+| Duration | 3.2s |
+| Coverage % | 82% (if available) |
+| Failed test names | List of specific failures |
+
+If tests **failed**, show:
+- Each failed test name and file
+- The failure message / assertion error
+- Suggestion: which code is likely broken based on the test file path
+
+## Phase 4: Track History
+
+Update `.codeloop/test-history.json` (create if not exists):
+
+```json
+{
+  "runs": [
+    {
+      "timestamp": "2026-02-21T10:30:00Z",
+      "suite": "all",
+      "total": 42,
+      "passed": 40,
+      "failed": 1,
+      "skipped": 1,
+      "coverage": 82,
+      "duration": 3.2,
+      "commit": "abc1234"
+    }
+  ]
+}
+```
+
+Keep the last 50 runs. Older entries are dropped.
+
+Include the current git commit SHA (from `git rev-parse --short HEAD`).
+
+## Phase 5: Report
+
+```
+## Test Results
+
+**Suite**: all | **Runner**: vitest
+**Result**: 40/42 passed, 1 failed, 1 skipped (3.2s)
+**Coverage**: 82% (threshold: 80% ✓)
+
+### Failures
+- `src/auth/login.test.ts` → "expected 200, got 401"
+
+### Trend (last 5 runs)
+  42 ████████████████████ 100%
+  42 ████████████████████ 100%
+  42 ███████████████████░  95%
+  42 ████████████████████ 100%
+  42 ███████████████████░  95%  ← current
+```
+
+## Phase 6: Board Sync
+
+If `.codeloop/board.json` exists:
+- Find the active task (first `in_progress`, then `planned`)
+- Add label: `tests:pass` or `tests:fail` (replace any existing `tests:*` label)
+- If coverage available, add label: `coverage:82%` (replace any existing `coverage:*` label)
+- Write updated board
+
+## Rules
+
+- **Never modify test files.** This skill only runs and reports — it doesn't fix tests.
+- **Respect the config.** If `test.command` is set, use it. Don't override with auto-detection.
+- **Track everything.** Even skipped tests matter — a rising skip count is a warning sign.
+- **Show the trend.** History makes patterns visible — one failure vs. recurring failure.

package/templates/seeds/go-gotchas.md

@@ -0,0 +1,28 @@
+
+## Backend
+
+### Goroutine leaks [freq:1]
+Goroutines that block on channels or I/O without exit conditions leak memory. Always ensure goroutines can be cancelled via `context.Context` or channel close signals.
+
+### Interface nil check is not what you expect [freq:1]
+A typed nil pointer assigned to an `interface{}` variable is not `== nil`. The interface value has a non-nil type, so the nil check passes. Check the concrete value or use reflection.
+
+### Slice append can mutate shared backing array [freq:1]
+`append(slice, elem)` reuses the backing array if capacity allows. Two slices from the same source can interfere with each other. Use `copy()` or full-slice expressions (`s[:len(s):len(s)]`) for safety.
+
+### `defer` evaluates arguments immediately [freq:1]
+`defer fmt.Println(x)` captures the current value of `x`, not the value at function exit. Use a closure (`defer func() { fmt.Println(x) }()`) to capture the final value.
+
+### Error wrapping needs `%w` for unwrapping [freq:1]
+`fmt.Errorf("failed: %v", err)` creates a new error that breaks `errors.Is()` and `errors.As()`. Use `%w` instead: `fmt.Errorf("failed: %w", err)`.
+
+### Forgetting to check `rows.Err()` after iteration [freq:1]
+`database/sql` `rows.Next()` can stop due to an error, not just end-of-results. Always check `rows.Err()` after the loop.
+
+## Testing
+
+### Table-driven tests need subtests [freq:1]
+Table-driven tests without `t.Run(name, ...)` report failures against the parent test — impossible to tell which case failed. Always use `t.Run`.
+
+### Race conditions in tests [freq:1]
+Tests that spawn goroutines without `-race` detection pass locally but fail in CI. Always run `go test -race ./...` in CI.

package/templates/seeds/go-patterns.md

@@ -0,0 +1,22 @@
+
+## Backend
+
+### Accept interfaces, return structs [confidence:HIGH]
+Function parameters should accept interfaces for flexibility. Return concrete types so callers know exactly what they get. This maximizes testability and minimizes coupling.
+
+### Errors are values, handle them immediately [confidence:HIGH]
+Check errors on the line after the call. Don't defer error handling or collect errors for later. Each error gets handled where it occurs.
+
+### Context propagation through the call chain [confidence:HIGH]
+Pass `context.Context` as the first parameter through every function that does I/O or could be cancelled. Never store contexts in structs.
+
+### Functional options for configuration [confidence:MEDIUM]
+Use `WithTimeout(5*time.Second)` style option functions instead of large config structs. Extensible without breaking existing callers.
+
+## Testing
+
+### Table-driven tests with subtests [confidence:HIGH]
+Define test cases as a slice of structs. Run each with `t.Run(name, func(t *testing.T) {...})`. Clear, extensible, easy to add new cases.
+
+### Test helpers return errors, don't t.Fatal [confidence:MEDIUM]
+Helper functions return errors so the caller decides how to handle them. Only call `t.Fatal` at the test level, not in helpers — it makes helpers reusable.

package/templates/seeds/node-typescript-gotchas.md

@@ -0,0 +1,30 @@
+
+## Backend
+
+### Async without await silently drops errors [freq:1]
+Calling an async function without `await` returns a Promise that nobody listens to. If it throws, the error is swallowed. Always `await` or explicitly handle the returned Promise.
+
+### `transform: true` converts missing params to NaN [freq:1]
+In NestJS with `class-validator`, `@Query() n?: number` becomes `NaN` when omitted (because `Number(undefined) === NaN`). Always guard with `isNaN()` before using numeric query params.
+
+### `.save()` has race conditions [freq:1]
+Mongoose `doc.save()` overwrites the entire document. If two processes load the same doc and save, the last write wins. Use `findByIdAndUpdate()` with `$set` for atomic field updates.
+
+### Import order matters with circular dependencies [freq:1]
+TypeScript circular imports cause `undefined` at runtime when the execution order doesn't match expectations. Move shared types to a separate file that both modules import.
+
+## Frontend
+
+### Stale closures in React effects [freq:1]
+`useEffect` closures capture variable values at render time. If a cleanup function or interval references state, it sees the stale value. Use refs or `useCallback` with proper deps.
+
+### `key` prop on list items must be stable [freq:1]
+Using array index as `key` causes incorrect renders when items are reordered or deleted. Use a unique, stable identifier from the data.
+
+## Testing
+
+### Mock cleanup between tests [freq:1]
+Mocks that aren't restored between tests leak state. Use `afterEach(() => vi.restoreAllMocks())` or `jest.restoreAllMocks()` to prevent flaky cross-test contamination.
+
+### Async test assertions need `await` [freq:1]
+`expect(asyncFn()).rejects.toThrow()` without `await` passes even if the assertion fails — the test completes before the Promise resolves. Always `await expect(...)`.

package/templates/seeds/node-typescript-patterns.md

@@ -0,0 +1,27 @@
+
+## Backend
+
+### DTOs at API boundaries [confidence:HIGH]
+Never pass raw database objects to API responses. Use DTOs (Data Transfer Objects) to control exactly which fields are exposed. Prevents accidental data leaks and decouples internal schema from public API.
+
+### Dependency injection over direct imports [confidence:HIGH]
+Import the interface, inject the implementation. Makes testing trivial (swap with mocks) and keeps modules loosely coupled.
+
+### Index files for module exports [confidence:MEDIUM]
+Each module directory has an `index.ts` that re-exports its public API. Internal files stay private. Consumers import from the directory, not deep paths.
+
+## Frontend
+
+### Server components by default [confidence:MEDIUM]
+Start with server components. Only add `'use client'` when you need interactivity (event handlers, state, effects). This keeps bundle size small and data fetching simple.
+
+### Colocate state with its consumer [confidence:HIGH]
+State lives in the closest common parent of the components that need it. Don't hoist to a global store unless multiple unrelated features need the same data.
+
+## Testing
+
+### Test behavior, not implementation [confidence:HIGH]
+Tests should verify what the code does, not how it does it. Avoid asserting on internal method calls or implementation details — they break on refactors without catching real bugs.
+
+### Arrange-Act-Assert structure [confidence:HIGH]
+Every test has three clear sections: set up the data (Arrange), perform the action (Act), check the result (Assert). Keeps tests readable and focused.

package/templates/seeds/python-gotchas.md

@@ -0,0 +1,30 @@
+
+## Backend
+
+### Mutable default arguments are shared [freq:1]
+`def foo(items=[])` — the default list is created once and shared across all calls. Mutations persist between invocations. Use `items=None` and create inside the function.
+
+### `is` vs `==` for comparisons [freq:1]
+`is` checks identity (same object in memory), `==` checks equality (same value). Use `is` only for `None`, `True`, `False`. For everything else, use `==`.
+
+### Silent exception swallowing [freq:1]
+Bare `except:` or `except Exception:` with just `pass` hides real bugs. Always log the exception or re-raise. If you must catch broadly, at least log at warning level.
+
+### Circular imports cause ImportError at runtime [freq:1]
+Two modules importing each other works in some cases but fails unpredictably depending on import order. Move shared types/interfaces to a third module.
+
+### `datetime.now()` uses local timezone [freq:1]
+`datetime.now()` returns naive local time. For servers, always use `datetime.now(timezone.utc)` or `datetime.utcnow()` to avoid timezone confusion.
+
+## Database
+
+### SQLAlchemy session not committed [freq:1]
+Forgetting `session.commit()` after inserts/updates — changes exist in memory but never reach the database. Use context managers or explicit commit calls.
+
+## Testing
+
+### Fixtures that share mutable state [freq:1]
+`@pytest.fixture(scope="module")` with mutable objects (dicts, lists) causes test pollution. Use `scope="function"` (default) for isolation, or return fresh copies.
+
+### Async test functions need pytest-asyncio [freq:1]
+`async def test_something()` silently passes without actually running unless `pytest-asyncio` is installed and `@pytest.mark.asyncio` is applied.

package/templates/seeds/python-patterns.md

@@ -0,0 +1,19 @@
+
+## Backend
+
+### Pydantic models at API boundaries [confidence:HIGH]
+Use Pydantic `BaseModel` for request/response validation. Never pass raw dicts through API layers — models enforce schema, generate docs, and catch invalid data early.
+
+### Context managers for resource cleanup [confidence:HIGH]
+Database connections, file handles, temporary directories — use `with` statements to guarantee cleanup. Prevents resource leaks on exceptions.
+
+### Type hints everywhere [confidence:MEDIUM]
+All function signatures have type hints. Use `mypy` or `pyright` in CI. Catches bugs at static analysis time instead of runtime.
+
+## Testing
+
+### Factories over fixtures for test data [confidence:MEDIUM]
+Use factory functions (or `factory_boy`) to create test data with sensible defaults. Override only the fields relevant to each test. More readable than complex fixture chains.
+
+### Test behavior, not implementation [confidence:HIGH]
+Verify what the function returns or what side effects occur — not which internal methods were called. Implementation-coupled tests break on every refactor.

package/templates/seeds/universal-gotchas.md

@@ -0,0 +1,11 @@
+
+## General
+
+### Never commit secrets [freq:1]
+API keys, tokens, passwords in code or config files. Use environment variables or a secrets manager. Even if you "remove it later," git history is forever.
+
+### Merge conflicts need manual review [freq:1]
+Auto-resolved merge conflicts (especially in lock files, generated code, or schema files) can silently break things. Always verify the merged result compiles and tests pass.
+
+### File permissions in git [freq:1]
+Accidentally committing executable bits (`chmod +x`) on files that don't need it. Check `git diff --stat` for mode changes before committing.

package/templates/seeds/universal-patterns.md

@@ -0,0 +1,11 @@
+
+## General
+
+### Error-first control flow [confidence:HIGH]
+Check error conditions and return/throw early. Keep the happy path at the lowest indentation level. Reduces nesting, improves readability.
+
+### One logical change per commit [confidence:HIGH]
+Each commit should be a single, reviewable unit. Mixing refactors with features makes review harder and reverts riskier.
+
+### Config in version control [confidence:HIGH]
+All configuration (except secrets) lives in the repo. If a new developer can't `git clone && make dev` and have a working setup, something is missing.