tap-the-sign 0.2.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "tap-the-sign",
+  "description": "Auto thermo sign-off after Plan mode plans. Requires thermo-nuclear-code-quality-review skill.",
+  "version": "0.2.0",
+  "author": {
+    "name": "tap-the-sign"
+  },
+  "hooks": "./hooks/hooks.claude.json",
+  "commands": "./commands/"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "tap-the-sign",
+  "description": "Auto thermo sign-off after Plan mode (permission_mode plan). Requires thermo-nuclear-code-quality-review skill.",
+  "version": "0.2.0",
+  "hooks": "./hooks/hooks.codex.json"
+}

package/.cursor-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "tap-the-sign",
+  "displayName": "Tap the Sign",
+  "version": "0.2.0",
+  "description": "Auto thermo sign-off after Plan mode plans. Requires thermo-nuclear-code-quality-review skill.",
+  "author": {
+    "name": "tap-the-sign"
+  },
+  "license": "MIT",
+  "keywords": ["plan-mode", "hooks", "thermonuclear", "code-quality", "tap-the-sign"],
+  "hooks": "./hooks/hooks.cursor.json",
+  "commands": "./commands/"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tap-the-sign contributors
+
+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,160 @@
+# Tap the Sign
+
+Auto **thermo sign-off** on your plan before you build.
+
+After Plan mode drafts a plan, tap-the-sign auto-sends a thermonuclear review follow-up and updates the plan with a **Thermonuclear pre-flight** section. Post-plan only — no pre-plan injection.
+
+tap-the-sign is a standalone hook add-on. It does **not** bundle the thermonuclear review rubric — install [`thermo-nuclear-code-quality-review`](https://github.com/cursor/plugins/tree/main/cursor-team-kit/skills/thermo-nuclear-code-quality-review) separately.
+
+## What it does
+
+1. You enable the hook and submit a task in **Plan mode**.
+2. When the plan draft finishes, the hook auto-sends this follow-up:
+
+```text
+@thermo-nuclear-code-quality-review
+
+Read and apply the full rubric from the thermo-nuclear-code-quality-review skill
+(code judo, 1k-line rule, spaghetti growth, HIGH/MID/LOW bar) to **this plan**
+(not a diff yet).
+
+Will this pass the next thermonuclear code review with no new items (especially HIGH or MID)?
+Did you find all the code judo opportunities?
+What changes would you make to improve confidence to high that this plan would pass
+thermonuclear code review cleanly?
+Include a **Thermonuclear pre-flight** section with this assessment in the plan.
+Be careful to not introduce any blocker higher than LOW and checking three times
+(three separate passes) for code judo opportunities.
+On Pass 3: Thermo-nuclear subagent on final diff; zero HIGH/MID.
+```
+
+3. After the plan is updated with the pre-flight section, the hook stops (no infinite loop).
+
+If the thermo skill is missing, planning still works; the auto follow-up is **skipped** with a warning in the Hooks output channel.
+
+## Quick start
+
+```bash
+npx tap-the-sign install && npx tap-the-sign install-thermo && npx tap-the-sign on
+npx tap-the-sign doctor
+```
+
+**Bun:**
+
+```bash
+bunx tap-the-sign install && bunx tap-the-sign install-thermo && bunx tap-the-sign on
+```
+
+Use Plan mode in Cursor, Claude Code, or Codex.
+
+## Install paths
+
+### 1. npm / npx
+
+```bash
+npx tap-the-sign install              # all IDEs, project-local
+npx tap-the-sign install --global     # user-global (~/.cursor, ~/.claude, ~/.codex)
+npx tap-the-sign install-thermo       # skill only (recommended)
+npx tap-the-sign install --no-codex   # subset of IDEs
+```
+
+### 2. Bun / bunx
+
+```bash
+bunx tap-the-sign install
+bunx tap-the-sign install-thermo
+bunx tap-the-sign on
+```
+
+From a repo clone:
+
+```bash
+git clone https://github.com/your-org/tap-the-sign.git
+cd tap-the-sign
+./install.bun.sh
+bun src/cli.mjs install-thermo && bun src/cli.mjs on
+```
+
+Hook scripts prefer **Bun** at runtime when `bun` is on `PATH`, otherwise Node 18+.
+
+### 3. Git plugin (IDE-native)
+
+| IDE | Install |
+|-----|---------|
+| **Cursor** | `/add-plugin your-org/tap-the-sign` |
+| **Claude Code** | `/plugin marketplace add …` then `/plugin install tap-the-sign@…` |
+| **Codex** | Install plugin; trust hooks via `/hooks` |
+
+Then run `tap-the-sign on` (or `/tap-the-sign-on` in Cursor). Plugins ship wiring, not default-on.
+
+**Thermo skill:** `tap-the-sign install-thermo` or `/add-plugin cursor-team-kit` (full plugin + subagent for Pass 3).
+
+### 4. curl / install.sh
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/your-org/tap-the-sign/main/install.sh | bash
+# then:
+npx tap-the-sign install-thermo && npx tap-the-sign on
+```
+
+Or clone and run `./install.sh` (uses Bun if installed, else Node).
+
+## Thermo skill
+
+**Recommended (skill only):**
+
+```bash
+tap-the-sign install-thermo
+# equivalent:
+npx skills add cursor/plugins --skill thermo-nuclear-code-quality-review \
+  -a cursor -a claude-code -a codex --copy -y
+```
+
+**Full plugin (includes thermo subagent for Pass 3):**
+
+```text
+/add-plugin cursor-team-kit
+```
+
+`install-thermo` installs the rubric (`SKILL.md`). The auto follow-up invokes the skill via `@thermo-nuclear-code-quality-review`. Pass 3 subagent requires `/add-plugin cursor-team-kit`.
+
+## Toggle
+
+| Command | Action |
+|---------|--------|
+| `tap-the-sign on` | Enable hook |
+| `tap-the-sign off` | Disable hook |
+| `tap-the-sign status` | Show hook + skill status |
+| `tap-the-sign doctor` | Fail if thermo skill missing |
+| `tap-the-sign doctor --fix` | Run `install-thermo` if skill missing |
+| `tap-the-sign install-thermo` | Install thermo skill via `npx skills add` |
+
+**Cursor slash commands:** `/tap-the-sign-on`, `/tap-the-sign-off`, `/tap-the-sign-status`
+
+## Requirements
+
+See [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md).
+
+- **Required for auto follow-up:** `thermo-nuclear-code-quality-review` skill
+- **Local IDE only** — Cursor Cloud Agents do not run `stop` / `beforeSubmitPrompt` hooks
+- **Codex:** review and trust hooks in `/hooks` after install
+
+## Plan mode detection
+
+| IDE | Field |
+|-----|-------|
+| Cursor | `composer_mode === "plan"` |
+| Claude Code | `permission_mode === "plan"` |
+| Codex | `permission_mode === "plan"` |
+
+## Uninstall
+
+```bash
+tap-the-sign uninstall
+```
+
+Also removes legacy `plan-sandwich` hook entries if present.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/commands/tap-the-sign-off.md

@@ -0,0 +1,2 @@
+<!-- TAP_THE_SIGN_DISABLE -->
+Disable the tap-the-sign hook.

package/commands/tap-the-sign-on.md

@@ -0,0 +1,2 @@
+<!-- TAP_THE_SIGN_ENABLE -->
+Enable the tap-the-sign hook (auto thermo sign-off after Plan mode plans).

package/commands/tap-the-sign-status.md

@@ -0,0 +1,2 @@
+<!-- TAP_THE_SIGN_STATUS -->
+Show tap-the-sign hook and thermo skill status.

package/docs/REQUIREMENTS.md

@@ -0,0 +1,99 @@
+# Requirements
+
+## Thermo skill (required for auto pre-flight)
+
+tap-the-sign **references** but does **not** include the thermonuclear review rubric.
+
+Install **`thermo-nuclear-code-quality-review`** separately.
+
+### Recommended: skill only
+
+```bash
+tap-the-sign install-thermo
+```
+
+This runs:
+
+```bash
+npx skills add cursor/plugins \
+  --skill thermo-nuclear-code-quality-review \
+  -a cursor -a claude-code -a codex \
+  --copy \
+  -y
+```
+
+### Alternative: full cursor-team-kit plugin
+
+```text
+/add-plugin cursor-team-kit
+```
+
+Includes the thermo subagent used for Pass 3 in the auto follow-up. `install-thermo` installs the rubric only.
+
+The hook follow-up invokes the skill via:
+
+```text
+@thermo-nuclear-code-quality-review
+```
+
+and instructs the agent to apply the full skill rubric to the plan.
+
+Verify installation:
+
+```bash
+tap-the-sign doctor
+```
+
+### If the skill is missing
+
+| Step | Behavior |
+|------|----------|
+| Plan mode submit | Allowed — hook arms normally |
+| Post-plan follow-up | **Skipped** — warning on stderr / systemMessage |
+| `tap-the-sign doctor` | Exits non-zero with install instructions |
+| `tap-the-sign doctor --fix` | Attempts `install-thermo` |
+
+## Runtime
+
+- **Node.js 18+** or **Bun 1+** (CLI, hook scripts, and install)
+- Hooks use Bun automatically when `bun` is on `PATH`, otherwise Node
+- **Local agent session** (not Cursor Cloud Agents for this hook)
+
+## IDE hook support
+
+| Hook event | Cursor | Claude Code | Codex |
+|------------|--------|-------------|-------|
+| Prompt submit (arm) | `beforeSubmitPrompt` | `UserPromptSubmit` | `UserPromptSubmit` |
+| Post-plan follow-up | `stop` → `followup_message` | `Stop` → `decision: block` | `Stop` → `decision: block` |
+
+## Installed files (project-local default)
+
+```text
+.cursor/hooks/tap-the-sign/      # hook scripts + runtime
+.cursor/hooks.json               # merged entries (tagged _tapTheSign)
+.cursor/commands/tap-the-sign-*.md
+.claude/settings.json            # merged hooks
+.codex/hooks.json
+.codex/hooks/tap-the-sign/
+.tap-the-sign/enabled            # toggle flag (create with tap-the-sign on)
+.tap-the-sign/state/             # per-session state (gitignored)
+```
+
+## Optional: global install
+
+```bash
+tap-the-sign install --global
+tap-the-sign install-thermo --global
+tap-the-sign on --global
+```
+
+Uses `~/.cursor/`, `~/.claude/`, `~/.codex/`, and `~/.config/tap-the-sign/`.
+
+## Skill discovery paths
+
+`tap-the-sign doctor` searches for `thermo-nuclear-code-quality-review/SKILL.md` under:
+
+- Project: `.agents/skills/`, `.cursor/skills/`, `.claude/skills/`
+- Global: `~/.cursor/skills/`, `~/.codex/skills/`, `~/.cursor/plugins/` (and cache)
+
+These cover `npx skills add` installs and cursor-team-kit plugin cache.

package/hooks/hooks.claude.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "_tapTheSign": true,
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks-bin/claude-arm.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "_tapTheSign": true,
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks-bin/claude-stop.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/hooks.codex.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "_tapTheSign": true,
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/hooks-bin/codex-arm.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "_tapTheSign": true,
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/hooks-bin/codex-stop.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/hooks.cursor.json

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeSubmitPrompt": [
+      {
+        "_tapTheSign": true,
+        "command": "${CURSOR_PLUGIN_ROOT}/hooks-bin/cursor-arm.sh"
+      }
+    ],
+    "stop": [
+      {
+        "_tapTheSign": true,
+        "command": "${CURSOR_PLUGIN_ROOT}/hooks-bin/cursor-stop.sh",
+        "loop_limit": 1
+      }
+    ]
+  }
+}

package/hooks-bin/claude-arm.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$HOOKS_DIR/tap-the-sign-env.sh"
+exec "${TAP_THE_SIGN_RUNTIME:-node}" "$HOOKS_DIR/run-hook.mjs" --event arm --host claude

package/hooks-bin/claude-stop.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$HOOKS_DIR/tap-the-sign-env.sh"
+exec "${TAP_THE_SIGN_RUNTIME:-node}" "$HOOKS_DIR/run-hook.mjs" --event stop --host claude

package/hooks-bin/codex-arm.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$HOOKS_DIR/tap-the-sign-env.sh"
+exec "${TAP_THE_SIGN_RUNTIME:-node}" "$HOOKS_DIR/run-hook.mjs" --event arm --host codex

package/hooks-bin/codex-stop.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$HOOKS_DIR/tap-the-sign-env.sh"
+exec "${TAP_THE_SIGN_RUNTIME:-node}" "$HOOKS_DIR/run-hook.mjs" --event stop --host codex

package/hooks-bin/constants.mjs

@@ -0,0 +1,33 @@
+export const SKILL_NAME = 'thermo-nuclear-code-quality-review';
+
+export const SENTINEL_ENABLE = '<!-- TAP_THE_SIGN_ENABLE -->';
+export const SENTINEL_DISABLE = '<!-- TAP_THE_SIGN_DISABLE -->';
+export const SENTINEL_STATUS = '<!-- TAP_THE_SIGN_STATUS -->';
+
+export const PHASE_IDLE = 'idle';
+export const PHASE_PLANNING = 'planning';
+export const PHASE_PREFLIGHT = 'preflight';
+export const PHASE_DONE = 'done';
+
+export const TAP_THE_SIGN_MARKER = '_tapTheSign';
+export const LEGACY_MARKERS = ['_planSandwich', TAP_THE_SIGN_MARKER];
+
+export const FOLLOW_UP_MESSAGE = `@thermo-nuclear-code-quality-review
+
+Read and apply the full rubric from the thermo-nuclear-code-quality-review skill
+(code judo, 1k-line rule, spaghetti growth, HIGH/MID/LOW bar) to **this plan**
+(not a diff yet).
+
+Will this pass the next thermonuclear code review with no new items (especially HIGH or MID)?
+Did you find all the code judo opportunities?
+What changes would you make to improve confidence to high that this plan would pass
+thermonuclear code review cleanly?
+Include a **Thermonuclear pre-flight** section with this assessment in the plan.
+Be careful to not introduce any blocker higher than LOW and checking three times
+(three separate passes) for code judo opportunities.
+On Pass 3: Thermo-nuclear subagent on final diff; zero HIGH/MID.`;
+
+export const SKILL_MISSING_WARNING =
+  'tap-the-sign: thermo-nuclear-code-quality-review skill not found. ' +
+  'Run: tap-the-sign install-thermo (or /add-plugin cursor-team-kit). ' +
+  'Skipping auto pre-flight follow-up.';

package/hooks-bin/cursor-arm.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$HOOKS_DIR/tap-the-sign-env.sh"
+exec "${TAP_THE_SIGN_RUNTIME:-node}" "$HOOKS_DIR/run-hook.mjs" --event arm --host cursor

package/hooks-bin/cursor-stop.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "$HOOKS_DIR/tap-the-sign-env.sh"
+exec "${TAP_THE_SIGN_RUNTIME:-node}" "$HOOKS_DIR/run-hook.mjs" --event stop --host cursor

package/hooks-bin/paths.mjs

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+let installScope = { global: false, projectRoot: null };
+
+function initScopeFromEnv() {
+  if (process.env.TAP_THE_SIGN_GLOBAL === '1' || process.env.PLAN_SANDWICH_GLOBAL === '1') {
+    installScope = { global: true, projectRoot: os.homedir() };
+    return;
+  }
+  const projectRoot =
+    process.env.TAP_THE_SIGN_PROJECT_ROOT ?? process.env.PLAN_SANDWICH_PROJECT_ROOT;
+  if (projectRoot) {
+    installScope = { global: false, projectRoot };
+  }
+}
+
+initScopeFromEnv();
+
+export function setInstallScope({ global = false, projectRoot = null } = {}) {
+  installScope = {
+    global,
+    projectRoot: projectRoot ?? findProjectRoot(process.cwd()),
+  };
+}
+
+export function getInstallScope() {
+  return { ...installScope };
+}
+
+export function findProjectRoot(startDir) {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    if (
+      fs.existsSync(path.join(dir, '.git')) ||
+      fs.existsSync(path.join(dir, '.cursor')) ||
+      fs.existsSync(path.join(dir, 'package.json'))
+    ) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return path.resolve(startDir);
+}
+
+export function getProjectRoot() {
+  return installScope.projectRoot ?? findProjectRoot(process.cwd());
+}
+
+export function getConfigRoots() {
+  if (installScope.global) {
+    const home = os.homedir();
+    return {
+      projectRoot: home,
+      cursorHooksDir: path.join(home, '.cursor', 'hooks', 'tap-the-sign'),
+      cursorHooksJson: path.join(home, '.cursor', 'hooks.json'),
+      cursorCommandsDir: path.join(home, '.cursor', 'commands'),
+      claudeSettings: path.join(home, '.claude', 'settings.json'),
+      codexHooksDir: path.join(home, '.codex', 'hooks', 'tap-the-sign'),
+      codexHooksJson: path.join(home, '.codex', 'hooks.json'),
+      tapTheSignDir: path.join(home, '.config', 'tap-the-sign'),
+      global: true,
+    };
+  }
+
+  const projectRoot = getProjectRoot();
+  return {
+    projectRoot,
+    cursorHooksDir: path.join(projectRoot, '.cursor', 'hooks', 'tap-the-sign'),
+    cursorHooksJson: path.join(projectRoot, '.cursor', 'hooks.json'),
+    cursorCommandsDir: path.join(projectRoot, '.cursor', 'commands'),
+    claudeSettings: path.join(projectRoot, '.claude', 'settings.json'),
+    codexHooksDir: path.join(projectRoot, '.codex', 'hooks', 'tap-the-sign'),
+    codexHooksJson: path.join(projectRoot, '.codex', 'hooks.json'),
+    tapTheSignDir: path.join(projectRoot, '.tap-the-sign'),
+    global: false,
+  };
+}
+
+export function getEnabledPath() {
+  return path.join(getConfigRoots().tapTheSignDir, 'enabled');
+}
+
+export function getStateDir() {
+  return path.join(getConfigRoots().tapTheSignDir, 'state');
+}
+
+export function resolveInstalledRunner() {
+  const roots = getConfigRoots();
+  const runner = path.join(roots.cursorHooksDir, 'run-hook.mjs');
+  if (fs.existsSync(runner)) {
+    return runner;
+  }
+  return path.join(PACKAGE_ROOT, 'src', 'hooks', 'runner.mjs');
+}