Add PreToolUse reminder hooks for artifact skills

A retrospective on PR #25 traced repeated rework to hand-rolling a PR
instead of invoking the create-pr skill. Add non-blocking PreToolUse
hooks that route gh pr create / gh issue create toward their skills and
print the staged-vs-unstaged file lists before git commit, so the
conventions stay in front of the agent at the moment it acts.

Each check is its own small module over a shared stdin/stdout contract
in scripts/hooks/, registered per-check in a committed .claude/settings
.json and covered by unit tests.

Closes #27

Author: jeffhorn-nava

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "python3 -m scripts.hooks.pr_create" },
+          { "type": "command", "command": "python3 -m scripts.hooks.issue_create" },
+          { "type": "command", "command": "python3 -m scripts.hooks.git_commit" }
+        ]
+      }
+    ]
+  }
+}

scripts/hooks/__init__.py

@@ -0,0 +1,35 @@
+"""Shared plumbing for the PreToolUse Bash reminder hooks.
+
+Each sibling module is one check. A check defines a pure `reminder(command) -> str | None`
+and, under `__main__`, calls `run(reminder)`. This module owns the single I/O contract with
+Claude Code so the checks stay pure and self-evident: read the Bash command from the hook
+payload on stdin, and, when a check returns text, emit it as non-blocking `additionalContext`
+that the harness injects into the model's context. Nothing here blocks the tool.
+"""
+import json
+import sys
+
+
+def command_from_stdin():
+    """The Bash command string from the hook payload on stdin, or '' if unavailable."""
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        return ""
+    return (payload.get("tool_input") or {}).get("command") or ""
+
+
+def emit(message):
+    """Inject `message` into the model's context (non-blocking)."""
+    json.dump(
+        {"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": message}},
+        sys.stdout,
+    )
+
+
+def run(reminder):
+    """Wire a check's `reminder(command)` to the hook I/O contract. Always returns 0."""
+    message = reminder(command_from_stdin())
+    if message:
+        emit(message)
+    return 0

scripts/hooks/git_commit.py

@@ -0,0 +1,38 @@
+"""Before `git commit`, surface the staged vs unstaged file lists.
+
+A commit records only what is staged. Printing the three lists at commit time makes a missing
+`git add` visible in context, so the intended change set and the staged set can be reconciled
+before the commit lands.
+"""
+import subprocess
+import sys
+
+from scripts.hooks import run
+
+
+def _git(*args):
+    """Trimmed stdout of a git command, or '' on any failure."""
+    try:
+        result = subprocess.run(["git", *args], capture_output=True, text=True, timeout=5)
+        return result.stdout.strip()
+    except Exception:
+        return ""
+
+
+def reminder(command):
+    if "git commit" not in command:
+        return None
+    staged = _git("diff", "--cached", "--name-only") or "(none)"
+    unstaged = _git("diff", "--name-only") or "(none)"
+    untracked = _git("ls-files", "--others", "--exclude-standard") or "(none)"
+    return (
+        "git commit reminder. Confirm the staged set matches your intended change set "
+        "before committing.\n\n"
+        f"Staged (will be committed):\n{staged}\n\n"
+        f"Modified but NOT staged:\n{unstaged}\n\n"
+        f"Untracked:\n{untracked}"
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(run(reminder))

scripts/hooks/issue_create.py

@@ -0,0 +1,17 @@
+"""Nudge `gh issue create` toward the create-issue skill."""
+import sys
+
+from scripts.hooks import run
+
+REMINDER = (
+    "Reminder: open issues through the create-issue skill. It picks the matching template, "
+    "runs review-draft, and files with the right label."
+)
+
+
+def reminder(command):
+    return REMINDER if "gh issue create" in command else None
+
+
+if __name__ == "__main__":
+    sys.exit(run(reminder))

scripts/hooks/pr_create.py

@@ -0,0 +1,18 @@
+"""Nudge `gh pr create` toward the create-pr skill."""
+import sys
+
+from scripts.hooks import run
+
+REMINDER = (
+    "Reminder: open PRs through the create-pr skill. It fills "
+    ".github/PULL_REQUEST_TEMPLATE.md, runs review-draft, and opens the PR as a draft. "
+    "If you are already inside create-pr, proceed."
+)
+
+
+def reminder(command):
+    return REMINDER if "gh pr create" in command else None
+
+
+if __name__ == "__main__":
+    sys.exit(run(reminder))

tests/test_hook_reminders.py

@@ -0,0 +1,52 @@
+import io
+import json
+
+from scripts.hooks import command_from_stdin, run
+from scripts.hooks import git_commit, issue_create, pr_create
+
+
+def test_pr_create_matches_even_in_compound_command():
+    assert pr_create.reminder("cd repo && gh pr create --draft") == pr_create.REMINDER
+
+
+def test_issue_create_matches():
+    assert issue_create.reminder("gh issue create --label bug") == issue_create.REMINDER
+
+
+def test_checks_ignore_unrelated_commands():
+    assert pr_create.reminder("ls -la") is None
+    assert issue_create.reminder("git status") is None
+    assert git_commit.reminder("echo hi") is None
+
+
+def test_git_commit_lists_staged_and_unstaged(monkeypatch):
+    outputs = {
+        ("diff", "--cached", "--name-only"): "a.py",
+        ("diff", "--name-only"): "b.py",
+        ("ls-files", "--others", "--exclude-standard"): "c.py",
+    }
+    monkeypatch.setattr(git_commit, "_git", lambda *args: outputs[args])
+    message = git_commit.reminder("git commit -m x")
+    assert "a.py" in message and "b.py" in message and "c.py" in message
+    assert "Staged (will be committed)" in message
+
+
+def test_command_from_stdin_handles_bad_input(monkeypatch):
+    monkeypatch.setattr("sys.stdin", io.StringIO("not json"))
+    assert command_from_stdin() == ""
+
+
+def test_run_emits_valid_hook_json(monkeypatch):
+    out = io.StringIO()
+    monkeypatch.setattr("sys.stdin", io.StringIO(json.dumps({"tool_input": {"command": "x"}})))
+    monkeypatch.setattr("sys.stdout", out)
+    assert run(lambda command: "hello") == 0
+    assert json.loads(out.getvalue())["hookSpecificOutput"]["additionalContext"] == "hello"
+
+
+def test_run_is_silent_when_check_returns_none(monkeypatch):
+    out = io.StringIO()
+    monkeypatch.setattr("sys.stdin", io.StringIO(json.dumps({"tool_input": {"command": "x"}})))
+    monkeypatch.setattr("sys.stdout", out)
+    assert run(lambda command: None) == 0
+    assert out.getvalue() == ""