@financebuddha/standards 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FinanceBuddha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# @financebuddha/standards
+
+Shared engineering standards for all FinanceBuddha repositories — one installed
+package that every repo pulls its ESLint, TypeScript, Prettier, commitlint,
+secrets-scanning, and Claude-skill config from. Upgrade the package, upgrade
+every rule.
+
+## Install
+
+Published to the public npm registry under the `@financebuddha` scope:
+
+```bash
+# bun
+bun add -D @financebuddha/standards
+
+# npm
+npm install --save-dev @financebuddha/standards
+```
+
+> Installing from GitHub directly (e.g. to test an unpublished commit) also
+> works: `npm i -D github:financebuddha/engineering-standards#<ref>`.
+
+## Quick start
+
+After installing, scaffold the thin re-export config files into your project:
+
+```bash
+npx @financebuddha/standards init          # writes config files (skips existing)
+npx @financebuddha/standards init --force   # overwrite existing
+npx @financebuddha/standards init --skill   # also install the Claude skill
+```
+
+`init` writes files that **re-export** from the installed package, so nothing is
+duplicated. It prints the two manual one-liners (tsconfig + Prettier) at the end.
+
+## What's inside
+
+| Subpath / file | How you use it |
+|---|---|
+| `@financebuddha/standards/eslint/nextjs` | `export { default } from '@financebuddha/standards/eslint/nextjs'` in `eslint.config.mjs` |
+| `@financebuddha/standards/typescript/nextjs` | `{ "extends": "@financebuddha/standards/typescript/nextjs" }` in `tsconfig.json` |
+| `@financebuddha/standards/typescript/base` | tsconfig base for non-Next.js packages |
+| `@financebuddha/standards/prettier` | `"prettier": "@financebuddha/standards/prettier"` in `package.json` |
+| `@financebuddha/standards/commitlint` | `export { default } from '@financebuddha/standards/commitlint'` in `commitlint.config.js` |
+| `secrets-patterns.txt` | grep patterns for the secrets scan (CI + husky hook) |
+| `husky/*` | pre-commit (secrets scan + lint-staged) and commit-msg (commitlint) hooks |
+| `skills/pre-commit-checks.md` | Claude skill: secrets → lint → typecheck → tests |
+
+## Manual reference (what `init` automates)
+
+### ESLint — `eslint.config.mjs`
+```js
+export { default } from '@financebuddha/standards/eslint/nextjs'
+
+// To add project rules, spread the preset instead:
+//   import base from '@financebuddha/standards/eslint/nextjs'
+//   export default [...base, { rules: { 'no-console': 'warn' } }]
+```
+
+### TypeScript — `tsconfig.json`
+```json
+{
+  "extends": "@financebuddha/standards/typescript/nextjs",
+  "compilerOptions": { "paths": { "@/*": ["./*"] } }
+}
+```
+
+### Prettier — `package.json`
+```json
+{ "prettier": "@financebuddha/standards/prettier" }
+```
+
+### commitlint — `commitlint.config.js`
+```js
+export { default } from '@financebuddha/standards/commitlint'
+```
+
+### Husky — `package.json`
+```json
+{ "scripts": { "prepare": "husky" } }
+```
+Then `npx @financebuddha/standards init` drops the hooks into `.husky/`.
+
+### Claude skill
+```bash
+npx @financebuddha/standards init --skill
+# copies skills/pre-commit-checks.md → ~/.claude/skills/
+# invoke with /pre-commit-checks in any Claude Code session
+```
+
+## Secrets scanning
+
+`secrets-patterns.txt` is the single source of truth — referenced by both the
+husky `pre-commit` hook and CI (`.github/workflows/ci.yml`). Add a pattern once
+and both layers pick it up. Covers AWS keys, OpenAI/GitHub/Slack tokens, private
+key blocks, JWTs, Google API keys, and generic `secret = "…"` assignments.
+
+## Releasing a new version
+
+Releases are automated with [release-please](https://github.com/googleapis/release-please)
+driven by conventional commits — you never bump the version by hand.
+
+1. Merge conventional commits to `main` (`feat:`, `fix:`, etc.).
+2. release-please opens/updates a **"chore(main): release x.y.z"** PR that bumps
+   `package.json` + `.release-please-manifest.json` and writes `CHANGELOG.md`.
+   - `feat:` → minor (patch while < 1.0), `fix:` → patch, `feat!:`/`BREAKING CHANGE` → major.
+3. Merge that PR. release-please creates the git tag + GitHub Release, which
+   triggers the **publish** job → `npm publish --provenance --access public`.
+
+Consuming repos pick up new rules with `npm update @financebuddha/standards`
+(or bump the version range in `package.json`).
+
+### One-time setup for publishing
+
+1. **npm org** — an npm org named **`financebuddha`** must exist (owns the
+   `@financebuddha` scope). Create it at npmjs.com → Add Organization.
+2. **`NPM_TOKEN` secret** — an npm **Automation** access token with publish
+   rights to the scope, added under Settings → Secrets and variables → Actions.
+3. **release-please token** — this org disables write access for the default
+   Actions token, so add a **`RELEASE_PLEASE_TOKEN`** secret: a fine-grained PAT
+   (or classic PAT with `repo` + `workflow` scope) that can open PRs and push
+   tags on this repo. _(If an org admin instead enables Settings → Actions →
+   "Workflow permissions: read and write" + "Allow Actions to create and approve
+   pull requests", the workflow falls back to the built-in token and this secret
+   becomes unnecessary.)_
+
+## Commit convention
+
+All commits follow [Conventional Commits](https://www.conventionalcommits.org/).
+See `commitlint/config.ts` for the annotated ruleset.

package/bin/init.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * @financebuddha/standards — project initializer
+ *
+ *   npx @financebuddha/standards init [options]
+ *
+ * Scaffolds the thin "re-export" config files into the current project so that
+ * every shared rule is pulled live from this installed package (node_modules) —
+ * nothing is duplicated, so an upgrade of the package upgrades every rule.
+ *
+ * Files it can write (each skipped if it already exists, unless --force):
+ *   eslint.config.mjs        → re-exports @financebuddha/standards/eslint/nextjs
+ *   .prettierrc              → { "...": "@financebuddha/standards/prettier" } note below
+ *   commitlint.config.js     → re-exports @financebuddha/standards/commitlint
+ *   .husky/pre-commit        → secrets scan + lint-staged
+ *   .husky/commit-msg        → commitlint
+ *   secrets-patterns.txt     → copied to project root (husky hook reads it)
+ *
+ * Flags:
+ *   --force        overwrite files that already exist
+ *   --skill        also copy the pre-commit-checks Claude skill to ~/.claude/skills/
+ *   --no-husky     skip writing husky hooks
+ *   --help         show this help
+ *
+ * Note on Prettier: Prettier cannot "extend" a config the way ESLint/TS can, so
+ * the recommended approach is to set  "prettier": "@financebuddha/standards/prettier"
+ * in your package.json. This script prints that snippet rather than guessing how
+ * to edit your package.json.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, chmodSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { homedir } from 'node:os'
+
+const PKG = '@financebuddha/standards'
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const PKG_ROOT = resolve(__dirname, '..')
+const CWD = process.cwd()
+
+const args = new Set(process.argv.slice(2))
+const FORCE = args.has('--force')
+const WANT_SKILL = args.has('--skill')
+const NO_HUSKY = args.has('--no-husky')
+
+if (args.has('--help') || args.has('-h')) {
+  console.log(readFileSync(fileURLToPath(import.meta.url), 'utf8').split('*/')[0].replace(/^#![^\n]*\n/, '').replace(/\/\*\*?|^ \* ?/gm, ''))
+  process.exit(0)
+}
+
+const written = []
+const skipped = []
+
+/** Write a file unless it exists (or --force). Track outcome for the summary. */
+function place(relPath, contents, { exec = false } = {}) {
+  const dest = join(CWD, relPath)
+  if (existsSync(dest) && !FORCE) {
+    skipped.push(relPath)
+    return
+  }
+  mkdirSync(dirname(dest), { recursive: true })
+  writeFileSync(dest, contents)
+  if (exec) chmodSync(dest, 0o755)
+  written.push(relPath)
+}
+
+// ── eslint.config.mjs ─────────────────────────────────────────────────────────
+place(
+  'eslint.config.mjs',
+  `// Pulled from ${PKG}. Add project-specific rules by spreading the preset.\n` +
+    `export { default } from '${PKG}/eslint/nextjs'\n`
+)
+
+// ── commitlint.config.js ──────────────────────────────────────────────────────
+place(
+  'commitlint.config.js',
+  `// Pulled from ${PKG}.\n` + `export { default } from '${PKG}/commitlint'\n`
+)
+
+// ── secrets-patterns.txt (copied — husky hook greps it locally) ───────────────
+{
+  const dest = join(CWD, 'secrets-patterns.txt')
+  if (existsSync(dest) && !FORCE) {
+    skipped.push('secrets-patterns.txt')
+  } else {
+    copyFileSync(join(PKG_ROOT, 'secrets-patterns.txt'), dest)
+    written.push('secrets-patterns.txt')
+  }
+}
+
+// ── husky hooks ───────────────────────────────────────────────────────────────
+if (!NO_HUSKY) {
+  place('.husky/pre-commit', readFileSync(join(PKG_ROOT, 'husky/pre-commit'), 'utf8'), { exec: true })
+  place('.husky/commit-msg', readFileSync(join(PKG_ROOT, 'husky/commit-msg'), 'utf8'), { exec: true })
+}
+
+// ── Claude skill (opt-in) ─────────────────────────────────────────────────────
+if (WANT_SKILL) {
+  const skillsDir = join(homedir(), '.claude', 'skills')
+  const dest = join(skillsDir, 'pre-commit-checks.md')
+  if (existsSync(dest) && !FORCE) {
+    skipped.push('~/.claude/skills/pre-commit-checks.md')
+  } else {
+    mkdirSync(skillsDir, { recursive: true })
+    copyFileSync(join(PKG_ROOT, 'skills/pre-commit-checks.md'), dest)
+    written.push('~/.claude/skills/pre-commit-checks.md')
+  }
+}
+
+// ── Summary ───────────────────────────────────────────────────────────────────
+console.log(`\n${PKG} init\n${'─'.repeat(40)}`)
+if (written.length) {
+  console.log('Written:')
+  written.forEach((f) => console.log(`  + ${f}`))
+}
+if (skipped.length) {
+  console.log('Skipped (already exist — pass --force to overwrite):')
+  skipped.forEach((f) => console.log(`  · ${f}`))
+}
+
+console.log('\nManual steps:')
+console.log('  1. tsconfig.json — add:')
+console.log(`       { "extends": "${PKG}/typescript/nextjs" }`)
+console.log('  2. package.json — add for Prettier:')
+console.log(`       "prettier": "${PKG}/prettier"`)
+console.log('  3. Ensure husky is installed and "prepare": "husky" is in package.json scripts.')
+console.log('')

package/commitlint/config.ts

@@ -0,0 +1,21 @@
+import type { UserConfig } from '@commitlint/types'
+
+const config: UserConfig = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [
+      2, 'always',
+      ['feat','fix','docs','style','refactor','perf','test','build','ci','chore','revert'],
+    ],
+    'subject-empty':      [2, 'never'],
+    'subject-full-stop':  [2, 'never', '.'],
+    'subject-case':       [2, 'always', 'lower-case'],
+    'type-case':          [2, 'always', 'lower-case'],
+    'header-max-length':  [2, 'always', 100],
+    'body-leading-blank': [1, 'always'],
+    'footer-leading-blank':[1, 'always'],
+    'scope-case':         [2, 'always', 'lower-case'],
+  },
+}
+
+export default config

package/commitlint/index.js

@@ -0,0 +1,32 @@
+/**
+ * Shared commitlint config for FinanceBuddha repos.
+ *
+ * Importable (no TypeScript loader required). In your commitlint.config.js:
+ *   export { default } from '@financebuddha/standards/commitlint'
+ *
+ * Or extend it in commitlint.config.ts:
+ *   import base from '@financebuddha/standards/commitlint'
+ *   export default { ...base }
+ *
+ * The annotated TypeScript source of record lives in ./config.ts.
+ */
+const config = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [
+      2,
+      'always',
+      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert'],
+    ],
+    'subject-empty': [2, 'never'],
+    'subject-full-stop': [2, 'never', '.'],
+    'subject-case': [2, 'always', 'lower-case'],
+    'type-case': [2, 'always', 'lower-case'],
+    'header-max-length': [2, 'always', 100],
+    'body-leading-blank': [1, 'always'],
+    'footer-leading-blank': [1, 'always'],
+    'scope-case': [2, 'always', 'lower-case'],
+  },
+}
+
+export default config

package/eslint/nextjs.mjs

@@ -0,0 +1,24 @@
+/**
+ * Shared ESLint flat config for FinanceBuddha Next.js projects.
+ *
+ * Usage in eslint.config.mjs:
+ *   import config from './node_modules/@financebuddha/standards/eslint/nextjs.mjs'
+ *   export default config
+ */
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+export default defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores([
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+    "scripts/**",
+    "skills/**",
+    "coverage/**",
+  ]),
+]);

package/husky/commit-msg

@@ -0,0 +1,7 @@
+#!/usr/bin/env sh
+
+if command -v bunx >/dev/null 2>&1; then
+  bunx --no -- commitlint --edit "$1"
+else
+  npx --no -- commitlint --edit "$1"
+fi

package/husky/pre-commit

@@ -0,0 +1,36 @@
+#!/usr/bin/env sh
+
+# Resolve the repo root so the patterns file is found regardless of where the
+# hook runs from. Prefer a project-root secrets-patterns.txt (written by
+# `npx @financebuddha/standards init`), else fall back to the one shipped in
+# node_modules.
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")
+PATTERNS="$ROOT/secrets-patterns.txt"
+if [ ! -f "$PATTERNS" ]; then
+  PATTERNS="$ROOT/node_modules/@financebuddha/standards/secrets-patterns.txt"
+fi
+
+# Secrets scan on staged changes. Strip comment/blank lines from the patterns
+# file first — grep -f treats every line (including '# AWS') as a regex, which
+# would otherwise match the comments themselves.
+if [ -f "$PATTERNS" ]; then
+  CLEAN=$(grep -vE '^[[:space:]]*#|^[[:space:]]*$' "$PATTERNS")
+  if [ -n "$CLEAN" ]; then
+    SECRETS=$(git diff --cached -U0 | grep -E "$CLEAN" 2>/dev/null)
+    if [ -n "$SECRETS" ]; then
+      echo "❌  Possible secrets detected in staged changes:"
+      echo "$SECRETS"
+      echo ""
+      echo "Review the matches above. If they are false positives, remove the"
+      echo "matching lines or run 'git commit --no-verify' to bypass (use sparingly)."
+      exit 1
+    fi
+  fi
+fi
+
+# Run lint-staged (use bunx if available, else npx)
+if command -v bunx >/dev/null 2>&1; then
+  bunx lint-staged
+else
+  npx lint-staged
+fi

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@financebuddha/standards",
+  "version": "0.1.0",
+  "description": "Shared engineering standards: ESLint, TypeScript, Prettier, commitlint, secrets scanning, and Claude skills",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/financebuddha/engineering-standards.git"
+  },
+  "homepage": "https://github.com/financebuddha/engineering-standards#readme",
+  "bugs": {
+    "url": "https://github.com/financebuddha/engineering-standards/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    "./eslint/nextjs": "./eslint/nextjs.mjs",
+    "./typescript/nextjs": "./typescript/nextjs.json",
+    "./typescript/base": "./typescript/base.json",
+    "./prettier": "./prettier/config.json",
+    "./commitlint": "./commitlint/index.js",
+    "./secrets-patterns": "./secrets-patterns.txt",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "fb-standards": "bin/init.mjs"
+  },
+  "files": [
+    "bin",
+    "eslint",
+    "typescript",
+    "prettier",
+    "commitlint",
+    "skills",
+    "husky",
+    "secrets-patterns.txt"
+  ],
+  "scripts": {
+    "init": "node bin/init.mjs"
+  },
+  "keywords": [
+    "eslint-config",
+    "tsconfig",
+    "prettier-config",
+    "commitlint-config",
+    "financebuddha",
+    "engineering-standards"
+  ],
+  "peerDependencies": {
+    "eslint": ">=9",
+    "eslint-config-next": ">=15",
+    "prettier": ">=3",
+    "typescript": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "eslint": { "optional": true },
+    "eslint-config-next": { "optional": true },
+    "prettier": { "optional": true },
+    "typescript": { "optional": true }
+  }
+}

package/prettier/config.json

@@ -0,0 +1,8 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "plugins": []
+}

package/secrets-patterns.txt

@@ -0,0 +1,32 @@
+# FinanceBuddha secret scan patterns
+# Used by CI (grep -Ef secrets-patterns.txt) and the pre-commit-checks Claude skill.
+# Each line is a regex matched against git diff output.
+
+# AWS
+AKIA[0-9A-Z]{16}
+
+# OpenAI
+sk-[A-Za-z0-9]{20,}
+
+# GitHub tokens
+ghp_[A-Za-z0-9]{36}
+gho_[A-Za-z0-9]{36}
+github_pat_[A-Za-z0-9_]{82}
+
+# Slack
+xox[baprs]-[A-Za-z0-9-]{10,}
+
+# Private keys
+-----BEGIN (RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY
+
+# JWT (3-part base64url)
+eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}
+
+# Google API keys
+AIza[0-9A-Za-z_-]{35}
+
+# Google OAuth client ID
+[0-9]+-[0-9A-Za-z_]{32}\.apps\.googleusercontent\.com
+
+# Generic credential assignments (password/secret/key = "value")
+(password|passwd|pwd|secret|api_key|apikey|api-key|auth_token|access_token|client_secret|private_key|encryption_key)\s*[:=]\s*["'][^"']{8,}["']

package/skills/pre-commit-checks.md

@@ -0,0 +1,167 @@
+---
+name: pre-commit-checks
+description: >
+  Run the full pre-commit quality gate: secrets scan → lint → typecheck → tests.
+  Auto-fixes lint errors where possible, diagnoses and fixes failing tests, then
+  reports a timed pass/fail summary. Use this skill before every commit or release,
+  when asked to "check everything", "run pre-commit", "make sure it's clean",
+  "ready to commit?", or any time you want to verify the codebase is in a shippable
+  state. Also use proactively after making multiple code changes in one session.
+---
+
+# Pre-Commit Checks
+
+Run every step in order. Do not skip ahead. A later step failing does not
+excuse an earlier step — fix each issue in the step where it appears before
+moving on.
+
+## Step 1 — Detect the package manager and project root
+
+```bash
+# Prefer bun if present, otherwise npm/yarn
+cd <project-root>
+which bun && RUNNER="bun run" || RUNNER="npm run"
+```
+
+For the shield project the runner is always `bun run`.
+
+## Step 2 — Secrets scan
+
+Scan staged files for accidental secrets before any code reaches the remote.
+Run all three checks; report every hit — do not stop at the first one.
+
+### 2a — Blocked file types (binary / credential files that should never commit)
+
+```bash
+git diff --cached --name-only | grep -Ei \
+  '\.(pem|p8|p12|pfx|key|keystore|jks|cer|crt|der|ppk|asc)$|^\.env(\.|$)|id_rsa|id_ed25519|id_ecdsa|id_dsa' \
+  && echo "BLOCKED FILES FOUND" || true
+```
+
+Any match is an **automatic FAIL**. Instruct the user to `git reset HEAD <file>`
+and add the pattern to `.gitignore` before proceeding.
+
+### 2b — High-confidence secret patterns in staged content
+
+```bash
+git diff --cached -U0 | grep -nE \
+  'AKIA[0-9A-Z]{16}|sk-[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{36}|gho_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{82}|xox[baprs]-[A-Za-z0-9-]{10,}|-----BEGIN (RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}|AIza[0-9A-Za-z_-]{35}|[0-9]+-[0-9A-Za-z_]{32}\.apps\.googleusercontent\.com' \
+  && echo "POSSIBLE SECRETS FOUND" || echo "No high-confidence secrets detected"
+```
+
+Any match: surface it to the user verbatim, identify the file and line number
+from the diff context, and **stop** — do not commit. The user must review and
+either remove the secret or confirm it is a false positive (e.g. test fixture
+with a clearly fake value like `sk-test-fake-key-for-unit-tests`).
+
+### 2c — Generic high-entropy / common key patterns in staged content
+
+```bash
+git diff --cached -U0 | grep -nEi \
+  '(password|passwd|pwd|secret|api_key|apikey|api-key|auth_token|access_token|client_secret|private_key|encryption_key)\s*[:=]\s*["'"'"'][^"'"'"']{8,}["'"'"']' \
+  && echo "CREDENTIAL ASSIGNMENTS FOUND" || echo "No credential assignments detected"
+```
+
+Flag any non-test, non-example matches to the user. Matches in files under
+`__tests__/`, `__mocks__/`, `*.test.*`, `*.spec.*`, or `*.example.*` may be
+false positives — confirm with the user before blocking.
+
+### 2d — .env files not listed in .gitignore
+
+```bash
+git diff --cached --name-only | grep -E '^\.env' | while read f; do
+  grep -qxF "$f" .gitignore 2>/dev/null || grep -qxF "/$f" .gitignore 2>/dev/null || \
+    echo "WARNING: $f is staged but not in .gitignore"
+done
+```
+
+Any `.env*` file staged that is not covered by `.gitignore` is an **automatic FAIL**.
+
+---
+
+**If the secrets scan is fully clean**, output:
+```
+✓ Secrets scan — no issues found
+```
+and continue to Step 3.
+
+## Step 3 — Lint
+
+```bash
+time bun run lint 2>&1
+```
+
+**If lint exits non-zero:**
+1. Run `bun run lint:fix` to auto-fix what ESLint can.
+2. Re-run `bun run lint` and capture the remaining output.
+3. For any errors that lint:fix could not resolve, read the flagged files and
+   fix them manually (one at a time — don't batch-guess).
+4. Re-run lint a final time to confirm exit 0.
+
+**Common lint patterns in this project:**
+- Unused imports → remove them
+- `any` type → narrow to the real type or use `unknown`
+- Missing return types on exported functions → add them
+- React hooks dependency array warnings → fix the dependency, don't suppress
+
+## Step 4 — Typecheck
+
+```bash
+time bun run typecheck 2>&1
+```
+
+TypeScript errors are **never suppressed with `@ts-ignore` or `as any`** unless
+there is a pre-existing justification comment. Fix each error properly:
+- Missing property → add it to the type or interface
+- Wrong type → correct the calling code
+- Module not found → check the import path / tsconfig paths
+
+Re-run typecheck after every fix to confirm the error is gone, not shifted.
+
+## Step 5 — Tests
+
+```bash
+time bun run test 2>&1
+```
+
+**If tests fail:**
+1. Read the full failure output — identify the exact test name and file.
+2. Open the test file and read the failing assertion.
+3. Open the production file it is testing and understand why the behaviour
+   changed.
+4. Fix the production code **or** update the test (update tests only when the
+   behaviour change was intentional — new feature, intentional refactor).
+5. Re-run `bun run test` to confirm all tests pass.
+
+Never delete or skip a test just to make the suite green — diagnose and fix the
+underlying issue.
+
+## Step 6 — Final summary
+
+After all checks pass, output a summary block like this:
+
+```
+✅ Pre-commit checks passed
+─────────────────────────────────────
+  secrets    ✓   clean
+  lint       ✓   1.2s
+  typecheck  ✓   4.7s
+  tests      ✓   3.6s   559 passed
+─────────────────────────────────────
+  Total      ✓   9.5s
+Ready to commit.
+```
+
+If any step cannot be fixed within a reasonable number of attempts (3–4 tries),
+stop and surface the remaining error to the user with a clear description of
+what is failing and why, rather than looping forever.
+
+## Scope note
+
+This skill covers **pre-commit quality gates only**. It does not:
+- Bump version numbers
+- Create git commits or tags
+- Push to remote
+
+For releasing, use `bun run release` (patch), `bun run release:minor`, or
+`bun run release:major` after this skill exits successfully.

package/typescript/base.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "FinanceBuddha Base",
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["esnext"],
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "exclude": ["node_modules", "coverage"]
+}

package/typescript/nextjs.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "FinanceBuddha Next.js",
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules", "scripts", "coverage"]
+}