@ketecode/loom 0.0.0-stage → 0.1.0

package/hooks/run.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+'use strict';
+
+// kete-loom hook runner. The installer copies it with each hook's hook.js to ~/.kete-loom/hooks/ and
+// registers `node run.js <host> <hook> <event>` with each host. It turns that host's stdin payload into
+// one normalized event, calls the hook's check(), and answers in the host's own dialect. Zero
+// dependencies.
+//
+// Events: pre-shell { command, cwd }, pre-edit { files: [{ path, content }], cwd },
+// post-edit { files: [{ path }], cwd }, session-start { cwd }.
+//
+// Blocking (pre-*): exit 2 with the reason on stderr works on every host; Cursor and Copilot also get
+// their JSON verdict. Internal errors fail OPEN (exit 0): Copilot and Kete Code deny on a crashed hook,
+// so a runner bug must never block every tool call. post-edit and session-start never block.
+
+const fs = require('fs');
+const path = require('path');
+
+const pick = (o, ...keys) => {
+  for (const k of keys) if (o && typeof o[k] === 'string') return o[k];
+  return undefined;
+};
+const parseMaybe = (v) => (typeof v === 'string' ? JSON.parse(v) : v || {});
+
+// `*** Add File: p` / `*** Update File: p` (apply_patch) and `+++ b/p` (unified diff); added lines are
+// the new content.
+function parsePatch(text) {
+  const files = [];
+  let current = null;
+  for (const line of String(text || '').split('\n')) {
+    const header = /^\*\*\* (?:Add|Update) File: (.+)$/.exec(line) || /^\*\*\* Move to: (.+)$/.exec(line) || /^\+\+\+ (?:b\/)?(.+)$/.exec(line);
+    if (header && header[1] !== '/dev/null') {
+      current = { path: header[1].trim(), content: '' };
+      files.push(current);
+    } else if (current && line.startsWith('+') && !line.startsWith('+++')) current.content += `${line.slice(1)}\n`;
+  }
+  return files;
+}
+
+// A Claude-style tool_input -> [{ path, content }].
+const claudeFiles = (input) => {
+  const p = pick(input, 'file_path', 'notebook_path', 'path', 'filePath');
+  return p ? [{ path: p, content: pick(input, 'content', 'new_string', 'new_source') || '' }] : [];
+};
+
+// Tolerant reader for hosts whose edit arguments aren't fully documented (Copilot, OpenCode).
+const looseFiles = (args) => {
+  if (pick(args, 'patchText', 'patch', 'input')) return parsePatch(pick(args, 'patchText', 'patch', 'input'));
+  const p = pick(args, 'path', 'filePath', 'file_path');
+  return p ? [{ path: p, content: pick(args, 'file_text', 'content', 'new_str', 'newString', 'new_string') || '' }] : [];
+};
+
+const SHELL_TOOLS = { kete: ['shell'], copilot: ['bash', 'powershell', 'shell'], opencode: ['bash'] };
+const EDIT_TOOLS = { kete: ['edit', 'write', 'patch'], copilot: ['edit', 'create', 'str_replace_editor', 'apply_patch'], opencode: ['edit', 'write', 'apply_patch'] };
+
+// Each host's payload -> the normalized event, or null when the call isn't one this event handles.
+// Claude, Codex and Gemini filter tools with matchers at registration; the rest are filtered here.
+function normalize(host, event, j) {
+  const cwd = pick(j, 'cwd') || (Array.isArray(j.workspace_roots) && j.workspace_roots[0]) || process.env.CURSOR_PROJECT_DIR || process.cwd();
+  const tool = j.tool || j.toolName || j.tool_name;
+  const toolArgs = () => (host === 'copilot' ? parseMaybe(j.toolArgs) : j.tool_input || j.args || {});
+  if (event === 'session-start') return { cwd };
+  if (SHELL_TOOLS[host] && event === 'pre-shell' && tool && !SHELL_TOOLS[host].includes(tool)) return null;
+  if (EDIT_TOOLS[host] && event !== 'pre-shell' && tool && !EDIT_TOOLS[host].includes(tool)) return null;
+
+  if (event === 'pre-shell') {
+    const command = host === 'cursor' ? j.command : pick(toolArgs(), 'command');
+    return typeof command === 'string' ? { command, cwd } : null;
+  }
+  let files;
+  if (host === 'codex') files = parsePatch(pick(j.tool_input, 'command', 'input', 'patch'));
+  else if (host === 'cursor') files = j.file_path ? [{ path: j.file_path, content: '' }] : [];
+  else if (host === 'claude' || host === 'gemini') files = claudeFiles(j.tool_input);
+  else files = looseFiles(toolArgs());
+  return files.length ? { files, cwd } : null;
+}
+
+const SESSION_JSON = {
+  claude: (c) => ({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: c } }),
+  codex: (c) => ({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: c } }),
+  gemini: (c) => ({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: c } }),
+  kete: (c) => ({ context: c }),
+  cursor: (c) => ({ additional_context: c }),
+  copilot: (c) => ({ additionalContext: c }),
+};
+const ALLOW_JSON = { cursor: { permission: 'allow' } };
+const DENY_JSON = {
+  cursor: (reason) => ({ permission: 'deny', user_message: reason, agent_message: reason }),
+  copilot: (reason) => ({ permissionDecision: 'deny', permissionDecisionReason: reason }),
+};
+
+const EVENTS = ['pre-shell', 'pre-edit', 'post-edit', 'session-start'];
+const allow = (host, event) => ({ code: 0, stdout: event.startsWith('pre-') && ALLOW_JSON[host] ? JSON.stringify(ALLOW_JSON[host]) : '', stderr: '' });
+
+// Returns { code, stdout, stderr } so tests can drive it without a process.
+function respond(host, hookName, input, hooksDir = __dirname, event = 'pre-shell') {
+  let verdict;
+  try {
+    if (!Object.prototype.hasOwnProperty.call(SESSION_JSON, host) && host !== 'opencode') throw new Error(`unknown host "${host}"`);
+    if (!EVENTS.includes(event)) throw new Error(`unknown event "${event}"`);
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(hookName || '')) throw new Error(`bad hook name "${hookName}"`);
+    const normalized = normalize(host, event, input ? JSON.parse(input) : {});
+    if (!normalized) return allow(host, event);
+    const { check } = require(path.join(hooksDir, hookName, 'hook.js'));
+    verdict = check(normalized) || {};
+  } catch (e) {
+    const r = allow(host, event);
+    return { ...r, stderr: `kete-loom hook ${hookName}: ${e.message} (allowed)\n` };
+  }
+  if (event === 'session-start') {
+    return verdict.context && SESSION_JSON[host] ? { code: 0, stdout: JSON.stringify(SESSION_JSON[host](String(verdict.context))), stderr: '' } : allow(host, event);
+  }
+  if (!event.startsWith('pre-') || !verdict.block) return allow(host, event);
+  const reason = String(verdict.reason || `Blocked by kete-loom hook ${hookName}`);
+  return { code: 2, stdout: DENY_JSON[host] ? JSON.stringify(DENY_JSON[host](reason)) : '', stderr: `${reason}\n` };
+}
+
+if (require.main === module) {
+  const [host, hookName, event = 'pre-shell'] = process.argv.slice(2);
+  let input = '';
+  try {
+    input = fs.readFileSync(0, 'utf8');
+  } catch {
+    // no stdin: treated as an empty event
+  }
+  const r = respond(host, hookName, input, __dirname, event);
+  if (r.stdout) process.stdout.write(r.stdout);
+  if (r.stderr) process.stderr.write(r.stderr);
+  process.exitCode = r.code;
+}
+
+module.exports = { respond, normalize, parsePatch, EVENTS };

package/mcp/atlassian.json

@@ -0,0 +1,11 @@
+{
+  "name": "atlassian",
+  "description": "Atlassian's remote MCP server for Jira and Confluence: issues, pages and search, signed in with Atlassian OAuth.",
+  "version": "0.1.0",
+  "category": "integrations",
+  "risk": "network",
+  "transport": "http",
+  "url": "https://mcp.atlassian.com/v2/mcp",
+  "auth": "oauth",
+  "homepage": "https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/"
+}

package/mcp/chrome-devtools.json

@@ -0,0 +1,18 @@
+{
+  "name": "chrome-devtools",
+  "description": "The Chrome DevTools MCP server: control and inspect a live Chrome, including console, network, performance traces and screenshots.",
+  "version": "0.1.0",
+  "category": "testing",
+  "risk": "runs-commands",
+  "transport": "stdio",
+  "command": "npx",
+  "args": [
+    "-y",
+    "chrome-devtools-mcp@latest"
+  ],
+  "auth": "none",
+  "requires": [
+    "node"
+  ],
+  "homepage": "https://github.com/ChromeDevTools/chrome-devtools-mcp"
+}

package/mcp/cloudflare.json

@@ -0,0 +1,11 @@
+{
+  "name": "cloudflare",
+  "description": "Cloudflare's remote MCP server for the Cloudflare API and docs, signed in with Cloudflare OAuth.",
+  "version": "0.1.0",
+  "category": "devops",
+  "risk": "network",
+  "transport": "http",
+  "url": "https://mcp.cloudflare.com/mcp",
+  "auth": "oauth",
+  "homepage": "https://developers.cloudflare.com/agents/model-context-protocol/mcp-servers-for-cloudflare/"
+}

package/mcp/context7.json

@@ -0,0 +1,11 @@
+{
+  "name": "context7",
+  "description": "Context7 by Upstash: up-to-date, version-specific library documentation and code examples for the model. Works without a key at lower rate limits.",
+  "version": "0.1.0",
+  "category": "docs",
+  "risk": "network",
+  "transport": "http",
+  "url": "https://mcp.context7.com/mcp",
+  "auth": "oauth",
+  "homepage": "https://github.com/upstash/context7"
+}

package/mcp/fetch.json

@@ -0,0 +1,17 @@
+{
+  "name": "fetch",
+  "description": "The reference Fetch MCP server: fetch a web page and return it as Markdown for the model to read.",
+  "version": "0.1.0",
+  "category": "docs",
+  "risk": "runs-commands",
+  "transport": "stdio",
+  "command": "uvx",
+  "args": [
+    "mcp-server-fetch"
+  ],
+  "auth": "none",
+  "requires": [
+    "uvx"
+  ],
+  "homepage": "https://github.com/modelcontextprotocol/servers/tree/main/src/fetch"
+}

package/mcp/figma.json

@@ -0,0 +1,11 @@
+{
+  "name": "figma",
+  "description": "Figma's remote MCP server: bring design context (frames, components, variables) into code, signed in with Figma.",
+  "version": "0.1.0",
+  "category": "coding",
+  "risk": "network",
+  "transport": "http",
+  "url": "https://mcp.figma.com/mcp",
+  "auth": "oauth",
+  "homepage": "https://developers.figma.com/docs/figma-mcp-server/"
+}

package/mcp/git.json

@@ -0,0 +1,17 @@
+{
+  "name": "git",
+  "description": "The reference Git MCP server: read history, diffs and status and make commits in a local repository.",
+  "version": "0.1.0",
+  "category": "devops",
+  "risk": "runs-commands",
+  "transport": "stdio",
+  "command": "uvx",
+  "args": [
+    "mcp-server-git"
+  ],
+  "auth": "none",
+  "requires": [
+    "uvx"
+  ],
+  "homepage": "https://github.com/modelcontextprotocol/servers/tree/main/src/git"
+}

package/mcp/github.json

@@ -0,0 +1,11 @@
+{
+  "name": "github",
+  "description": "GitHub's official remote MCP server: repositories, issues, pull requests and Actions, signed in with GitHub OAuth.",
+  "version": "0.1.0",
+  "category": "integrations",
+  "risk": "network",
+  "transport": "http",
+  "url": "https://api.githubcopilot.com/mcp/",
+  "auth": "oauth",
+  "homepage": "https://github.com/github/github-mcp-server"
+}

package/mcp/linear.json

@@ -0,0 +1,11 @@
+{
+  "name": "linear",
+  "description": "Linear's remote MCP server: read and update issues, projects and comments, signed in with Linear OAuth.",
+  "version": "0.1.0",
+  "category": "integrations",
+  "risk": "network",
+  "transport": "http",
+  "url": "https://mcp.linear.app/mcp",
+  "auth": "oauth",
+  "homepage": "https://linear.app/docs/mcp"
+}

package/mcp/memory.json

@@ -0,0 +1,18 @@
+{
+  "name": "memory",
+  "description": "The reference Memory MCP server: a local knowledge graph the agent can store and recall facts in across sessions.",
+  "version": "0.1.0",
+  "category": "ai",
+  "risk": "runs-commands",
+  "transport": "stdio",
+  "command": "npx",
+  "args": [
+    "-y",
+    "@modelcontextprotocol/server-memory"
+  ],
+  "auth": "none",
+  "requires": [
+    "node"
+  ],
+  "homepage": "https://github.com/modelcontextprotocol/servers/tree/main/src/memory"
+}

package/mcp/notion.json

@@ -0,0 +1,11 @@
+{
+  "name": "notion",
+  "description": "Notion's remote MCP server: search, read and edit pages and databases, signed in with Notion OAuth.",
+  "version": "0.1.0",
+  "category": "integrations",
+  "risk": "network",
+  "transport": "http",
+  "url": "https://mcp.notion.com/mcp",
+  "auth": "oauth",
+  "homepage": "https://developers.notion.com/docs/get-started-with-mcp"
+}

package/mcp/playwright.json

@@ -0,0 +1,18 @@
+{
+  "name": "playwright",
+  "description": "Microsoft's Playwright MCP server: drive a real browser through the accessibility tree to navigate, click, fill forms and check pages.",
+  "version": "0.1.0",
+  "category": "testing",
+  "risk": "runs-commands",
+  "transport": "stdio",
+  "command": "npx",
+  "args": [
+    "-y",
+    "@playwright/mcp@latest"
+  ],
+  "auth": "none",
+  "requires": [
+    "node"
+  ],
+  "homepage": "https://github.com/microsoft/playwright-mcp"
+}

package/mcp/sentry.json

@@ -0,0 +1,11 @@
+{
+  "name": "sentry",
+  "description": "Sentry's remote MCP server: search errors and issues, inspect events and triage, signed in with Sentry OAuth.",
+  "version": "0.1.0",
+  "category": "devops",
+  "risk": "network",
+  "transport": "http",
+  "url": "https://mcp.sentry.dev/mcp",
+  "auth": "oauth",
+  "homepage": "https://github.com/getsentry/sentry-mcp"
+}

package/mcp/stripe.json

@@ -0,0 +1,11 @@
+{
+  "name": "stripe",
+  "description": "Stripe's remote MCP server: work with the Stripe API and search Stripe docs, signed in with Stripe OAuth.",
+  "version": "0.1.0",
+  "category": "integrations",
+  "risk": "network",
+  "transport": "http",
+  "url": "https://mcp.stripe.com",
+  "auth": "oauth",
+  "homepage": "https://docs.stripe.com/mcp"
+}

package/mcp/supabase.json

@@ -0,0 +1,11 @@
+{
+  "name": "supabase",
+  "description": "Supabase's remote MCP server in read-only mode: inspect projects, schemas and data, and search the docs, signed in with Supabase OAuth.",
+  "version": "0.1.0",
+  "category": "data",
+  "risk": "network",
+  "transport": "http",
+  "url": "https://mcp.supabase.com/mcp?read_only=true",
+  "auth": "oauth",
+  "homepage": "https://supabase.com/docs/guides/getting-started/mcp"
+}

package/mcp/time.json

@@ -0,0 +1,17 @@
+{
+  "name": "time",
+  "description": "The reference Time MCP server: current time and timezone conversion.",
+  "version": "0.1.0",
+  "category": "meta",
+  "risk": "runs-commands",
+  "transport": "stdio",
+  "command": "uvx",
+  "args": [
+    "mcp-server-time"
+  ],
+  "auth": "none",
+  "requires": [
+    "uvx"
+  ],
+  "homepage": "https://github.com/modelcontextprotocol/servers/tree/main/src/time"
+}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@ketecode/loom",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Kete Loom: curated, tested, portable Agent Skills, subagents, commands, rules, hooks and MCP configs. One source, installable in Claude Code, Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot and Kete Code.",
+  "license": "MIT",
+  "author": "Kete-org <support@ketecode.ai>",
+  "homepage": "https://ketecode.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kete-org/kete-loom.git"
+  },
+  "bugs": "https://github.com/kete-org/kete-loom/issues",
+  "keywords": [
+    "agent-skills",
+    "skills",
+    "claude-code",
+    "codex",
+    "opencode",
+    "cursor",
+    "gemini-cli",
+    "copilot",
+    "kete-code"
+  ],
+  "bin": {
+    "kete-loom": "bin/kete-loom.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/lib/",
+    "skills/",
+    "agents/",
+    "commands/",
+    "hooks/",
+    "rules/",
+    "mcp/",
+    "profiles.json",
+    "schemas/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "node scripts/lint-skills.js",
+    "eval": "node scripts/run-evals.js",
+    "eval:estimate": "node scripts/run-evals.js --estimate",
+    "eval:live": "node scripts/run-evals.js --live",
+    "test": "node --test",
+    "check": "npm run lint && npm test && npm run eval",
+    "catalog": "node scripts/build-catalog.js",
+    "site": "node scripts/build-site.js",
+    "prepublishOnly": "npm run check"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.135.0"
+  }
+}

package/profiles.json

@@ -0,0 +1,165 @@
+{
+  "minimal": {
+    "description": "The essentials: test-first work, verification before merge, security review and code review.",
+    "skills": [
+      "tdd-workflow",
+      "verification-loop",
+      "security-review"
+    ],
+    "agents": [
+      "code-reviewer"
+    ],
+    "commands": [
+      "review",
+      "verify"
+    ],
+    "rules": [
+      "common",
+      "security"
+    ]
+  },
+  "core": {
+    "description": "Everyday development: the essentials, planning, git, onboarding and session handoff, plus the language and framework packs this project uses.",
+    "extends": [
+      "minimal"
+    ],
+    "skills": [
+      "search-first",
+      "git-workflow",
+      "conventional-commits",
+      "codebase-onboarding",
+      "session-handoff",
+      "error-handling-patterns",
+      "refactoring-safely"
+    ],
+    "agents": [
+      "planner",
+      "security-reviewer",
+      "refactor-cleaner"
+    ],
+    "commands": [
+      "build-fix",
+      "plan-feature",
+      "commit",
+      "pr-describe",
+      "tdd",
+      "explain",
+      "save-session",
+      "resume-session",
+      "test-coverage"
+    ],
+    "rules": [
+      "testing",
+      "git"
+    ],
+    "detect": true
+  },
+  "developer": {
+    "description": "Core plus the safety hooks: block dangerous commands, --no-verify, edits to protected files and secrets in code.",
+    "extends": [
+      "core"
+    ],
+    "hooks": [
+      "block-dangerous-commands",
+      "block-no-verify",
+      "protect-files",
+      "guard-secrets"
+    ]
+  },
+  "security": {
+    "description": "Security and compliance: every security and compliance item, the essentials, and the four safety hooks.",
+    "extends": [
+      "minimal"
+    ],
+    "categories": [
+      "security",
+      "compliance"
+    ],
+    "commands": [
+      "security-scan",
+      "threat-model",
+      "deps-audit"
+    ],
+    "rules": [
+      "security"
+    ],
+    "hooks": [
+      "block-dangerous-commands",
+      "block-no-verify",
+      "protect-files",
+      "guard-secrets"
+    ]
+  },
+  "ai": {
+    "description": "Building AI features: LLM apps, prompts, evals, RAG, MCP servers, agents and ML, on top of core.",
+    "extends": [
+      "core"
+    ],
+    "categories": [
+      "ai"
+    ]
+  },
+  "data": {
+    "description": "Data work: databases, pipelines, dbt, scraping, dashboards and analysis, on top of core.",
+    "extends": [
+      "core"
+    ],
+    "categories": [
+      "data"
+    ]
+  },
+  "business": {
+    "description": "Founders and product teams: marketing, SEO, research, investor materials, writing, PRDs and operations.",
+    "categories": [
+      "business",
+      "docs"
+    ],
+    "commands": [
+      "prd",
+      "postmortem"
+    ]
+  },
+  "full": {
+    "description": "Everything in Kete Loom, including every hook.",
+    "all": true
+  },
+  "mcp-web": {
+    "description": "MCP pack for web work: Playwright and Chrome DevTools browsers, Context7 library docs and Fetch.",
+    "mcp": [
+      "playwright",
+      "chrome-devtools",
+      "context7",
+      "fetch"
+    ]
+  },
+  "mcp-code": {
+    "description": "MCP pack for code hosting and errors: GitHub, local Git and Sentry.",
+    "mcp": [
+      "github",
+      "git",
+      "sentry"
+    ]
+  },
+  "mcp-team": {
+    "description": "MCP pack for team tools: Linear, Notion and Atlassian (Jira and Confluence).",
+    "mcp": [
+      "linear",
+      "notion",
+      "atlassian"
+    ]
+  },
+  "mcp-cloud": {
+    "description": "MCP pack for cloud and payments: Cloudflare, Supabase (read-only) and Stripe.",
+    "mcp": [
+      "cloudflare",
+      "supabase",
+      "stripe"
+    ]
+  },
+  "mcp-design": {
+    "description": "MCP pack for design handoff: Figma.",
+    "mcp": [
+      "figma"
+    ]
+  }
+}

package/rules/common.md

@@ -0,0 +1,21 @@
+---
+name: common
+description: Always-on engineering rules for any project, covering scope, verification, honesty about results, safe changes and secrets.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+- Read the code you change and the code that calls it before editing. Search for an existing helper before writing a new one.
+- Keep the change to what was asked. Mention other problems you notice instead of fixing them unasked.
+- Match the surrounding code: its naming, structure, error handling and comment style.
+- Prove a change works by running the project's own build, lint and tests. Never claim something passes without having run it.
+- Report results as they are. If a test fails, a step was skipped or you are unsure, say so plainly.
+- Never delete, skip or weaken a test to make a suite pass.
+- Handle errors where they can be handled; never swallow them silently.
+- Never put secrets, tokens or credentials in code, logs, commits or test fixtures. Read them from the environment or a secret store.
+- Ask before anything destructive or hard to undo: deleting data, force-pushing, rewriting history, dropping tables, changing production config.
+- Prefer small, reversible steps. Commit only when the user asks.

package/rules/cpp.md

@@ -0,0 +1,29 @@
+---
+name: cpp
+description: Always-on rules for modern C++ code, covering ownership and RAII, undefined behaviour, bounds and lifetimes, concurrency, headers, and sanitizer-backed build and test checks.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: read-only
+  kete-loom/paths: "**/*.cpp, **/*.cc, **/*.cxx, **/*.c++, **/*.hpp, **/*.hh, **/*.hxx, **/*.h, **/*.ipp, **/*.ixx, **/*.cppm"
+  kete-loom/owner: "Kete-org"
+---
+
+- Write to the C++ standard the project's build sets; do not use features newer than it.
+- Manage every resource with RAII. Never use raw `new`/`delete` for ownership; use `std::make_unique`, `std::make_shared` or a container.
+- Use `std::unique_ptr` by default; reach for `std::shared_ptr` only for genuinely shared ownership. Raw pointers and references never own.
+- Follow the rule of zero; if you write one of destructor, copy or move operations, define or delete all five.
+- Never return or store a reference, pointer, `std::string_view` or `std::span` to a local or temporary that will die first.
+- Never use an iterator, pointer or reference into a container after an operation that may invalidate it, such as `push_back` or `erase`.
+- Check bounds on untrusted indices; never index past the end. Prefer `std::array`, `std::vector` and `std::string` over C arrays and `char*` buffers.
+- Never use `strcpy`, `sprintf`, `gets` or other unbounded C string functions.
+- Initialize every variable, and avoid signed overflow, unchecked narrowing and C-style casts; use `static_cast` and friends.
+- Guard all shared mutable state with `std::mutex` and `std::lock_guard`/`std::scoped_lock`, or `std::atomic`; a data race is undefined behaviour.
+- Mark functions `noexcept` only when they truly cannot throw, and destructors must never throw.
+- Mark overriding functions `override`, give polymorphic bases a virtual or protected destructor, and make single-argument constructors `explicit`.
+- Never put `using namespace` in a header; use include guards or `#pragma once` as the project does.
+- Build with warnings on (for example `-Wall -Wextra`) and fix them; run tests under AddressSanitizer and UndefinedBehaviorSanitizer (`-fsanitize=address,undefined`) when the toolchain supports them.
+- Use the project's configured build system, formatter and test framework.
+
+For more, load the cpp-patterns and cpp-testing skills.