capt-hook 3.1.0__tar.gz → 3.3.0__tar.gz

{capt_hook-3.1.0 → capt_hook-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 3.1.0
+Version: 3.3.0
 Summary: Declarative hook framework for Claude Code
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali
@@ -55,23 +55,28 @@ Description-Content-Type: text/markdown
 
 Declarative hook framework for Claude Code. Write hooks as data, test them inline, and ship them to CI in the same shape they run in production.
 
-## Install
+## Quickstart
 
-There's no install step. Run everything through [uvx](https://docs.astral.sh/uv/).
+No install step — everything runs through [uvx](https://docs.astral.sh/uv/). Pick a front door:
+
+**From your terminal:**
 
 ```bash
 uvx capt-hook init
 ```
 
-`uvx` fetches captain-hook into a throwaway environment and runs it, so you never add it to `pyproject.toml`. Every command in this README works the same way once you prefix it with `uvx`.
+**From inside Claude Code** — install the plugin, then ask Claude to set it up:
 
-## First hook
+```
+/plugin marketplace add yasyf/captain-hook
+/plugin install captain-hook@captain-hook
+```
 
-`uvx capt-hook init` scaffolds `.claude/hooks/`, wires Claude Code's settings, and installs the skills. One command and you're live.
+> set up captain hook
 
-```bash
-uvx capt-hook init
-```
+Either path lands in the same place: `.claude/hooks/` scaffolded, Claude Code's settings wired, the bundled skills installed, and the [session reviewer](#session-reviewer) watching this repo. `uvx` fetches captain-hook into a throwaway environment, so it never enters your `pyproject.toml` — and every command below works the same way once you prefix it with `uvx`.
+
+## Your first hook
 
 A hook is declarative Python with an event, some conditions, and an action. This one stops the agent from finishing a UI change it never looked at.
 
@@ -117,14 +122,15 @@ uvx capt-hook test
 
 `init` already wired Claude Code's settings. Each event runs `uvx capt-hook run <Event>`, with the event JSON arriving on stdin and the verdict written to stdout. Re-run `uvx capt-hook register-hooks` only after you add hooks on a new event; it writes `.claude/settings.local.json` for you.
 
-## Agent Skills & plugin
+## Session reviewer
 
-captain-hook ships two [Agent Skills](https://yasyf.github.io/captain-hook/docs/getting-started/skills.html) so you don't have to write hooks by hand. `bootstrapping-hooks` mines your repo's docs, CI, and git history into proposed gates and nudges. `translating-styleguides` turns a STYLEGUIDE.md into enforced rules. `uvx capt-hook init` installs both into `.claude/skills/`, or you can add them as a plugin.
+`init` also turns on the **session reviewer**. When a Claude Code session ends, it mines the transcript for the durable corrections you gave and the hooks that misfired, judges each one, and — once a pattern clears its thresholds — opens a pull request that adds a new hook or fixes the one that misfired. You review the PR like any other.
 
-```
-/plugin marketplace add yasyf/captain-hook
-/plugin install captain-hook@captain-hook
-```
+It's on by default after `init`. Turn it off for a repo with `uvx capt-hook review disable`, or skip it at setup with `uvx capt-hook init --no-review`. The [session reviewer guide](https://yasyf.github.io/captain-hook/docs/guide/session-reviewer.html) covers prerequisites (an authenticated `claude` and `gh`) and the `HOOKS_REVIEW_*` tuning knobs.
+
+## Agent Skills
+
+captain-hook ships two [Agent Skills](https://yasyf.github.io/captain-hook/docs/getting-started/skills.html) so you don't have to write hooks by hand. `bootstrapping-hooks` surveys your repo's docs, CI, and git history and proposes gates and nudges; `translating-styleguides` turns a STYLEGUIDE.md into enforced rules. Both land in `.claude/skills/` via `init` and ship as the plugin in the [Quickstart](#quickstart) — ask Claude to "set up captain hook" and `bootstrapping-hooks` takes it from there.
 
 ## What this solves
 

{capt_hook-3.1.0 → capt_hook-3.3.0}/README.md

@@ -9,23 +9,28 @@
 
 Declarative hook framework for Claude Code. Write hooks as data, test them inline, and ship them to CI in the same shape they run in production.
 
-## Install
+## Quickstart
 
-There's no install step. Run everything through [uvx](https://docs.astral.sh/uv/).
+No install step — everything runs through [uvx](https://docs.astral.sh/uv/). Pick a front door:
+
+**From your terminal:**
 
 ```bash
 uvx capt-hook init
 ```
 
-`uvx` fetches captain-hook into a throwaway environment and runs it, so you never add it to `pyproject.toml`. Every command in this README works the same way once you prefix it with `uvx`.
+**From inside Claude Code** — install the plugin, then ask Claude to set it up:
 
-## First hook
+```
+/plugin marketplace add yasyf/captain-hook
+/plugin install captain-hook@captain-hook
+```
 
-`uvx capt-hook init` scaffolds `.claude/hooks/`, wires Claude Code's settings, and installs the skills. One command and you're live.
+> set up captain hook
 
-```bash
-uvx capt-hook init
-```
+Either path lands in the same place: `.claude/hooks/` scaffolded, Claude Code's settings wired, the bundled skills installed, and the [session reviewer](#session-reviewer) watching this repo. `uvx` fetches captain-hook into a throwaway environment, so it never enters your `pyproject.toml` — and every command below works the same way once you prefix it with `uvx`.
+
+## Your first hook
 
 A hook is declarative Python with an event, some conditions, and an action. This one stops the agent from finishing a UI change it never looked at.
 
@@ -71,14 +76,15 @@ uvx capt-hook test
 
 `init` already wired Claude Code's settings. Each event runs `uvx capt-hook run <Event>`, with the event JSON arriving on stdin and the verdict written to stdout. Re-run `uvx capt-hook register-hooks` only after you add hooks on a new event; it writes `.claude/settings.local.json` for you.
 
-## Agent Skills & plugin
+## Session reviewer
 
-captain-hook ships two [Agent Skills](https://yasyf.github.io/captain-hook/docs/getting-started/skills.html) so you don't have to write hooks by hand. `bootstrapping-hooks` mines your repo's docs, CI, and git history into proposed gates and nudges. `translating-styleguides` turns a STYLEGUIDE.md into enforced rules. `uvx capt-hook init` installs both into `.claude/skills/`, or you can add them as a plugin.
+`init` also turns on the **session reviewer**. When a Claude Code session ends, it mines the transcript for the durable corrections you gave and the hooks that misfired, judges each one, and — once a pattern clears its thresholds — opens a pull request that adds a new hook or fixes the one that misfired. You review the PR like any other.
 
-```
-/plugin marketplace add yasyf/captain-hook
-/plugin install captain-hook@captain-hook
-```
+It's on by default after `init`. Turn it off for a repo with `uvx capt-hook review disable`, or skip it at setup with `uvx capt-hook init --no-review`. The [session reviewer guide](https://yasyf.github.io/captain-hook/docs/guide/session-reviewer.html) covers prerequisites (an authenticated `claude` and `gh`) and the `HOOKS_REVIEW_*` tuning knobs.
+
+## Agent Skills
+
+captain-hook ships two [Agent Skills](https://yasyf.github.io/captain-hook/docs/getting-started/skills.html) so you don't have to write hooks by hand. `bootstrapping-hooks` surveys your repo's docs, CI, and git history and proposes gates and nudges; `translating-styleguides` turns a STYLEGUIDE.md into enforced rules. Both land in `.claude/skills/` via `init` and ship as the plugin in the [Quickstart](#quickstart) — ask Claude to "set up captain hook" and `bootstrapping-hooks` takes it from there.
 
 ## What this solves
 

{capt_hook-3.1.0 → capt_hook-3.3.0}/captain_hook/cli.py

@@ -17,8 +17,9 @@ from cc_transcript.ids import SessionId
 from captain_hook.app import _state, load_gitignore, reset
 from captain_hook.context import HookContext, load_transcript
 from captain_hook.dispatch import dispatch
-from captain_hook.loader import discover_hooks
+from captain_hook.loader import CONF_MODULE, discover_hooks, discover_pack
 from captain_hook.log import setup_logging
+from captain_hook.packs import manager
 from captain_hook.review.cli import review
 from captain_hook.session import SessionStore, ensure_session
 from captain_hook.types import Event
@@ -38,6 +39,14 @@ class CliState:
         reset()
         load_gitignore(self.root)
         discover_hooks(self.hooks)
+        resolved, missing = manager.resolve_enabled_packs(self.root)
+        for pack_ in resolved:
+            discover_pack(pack_.entry.name, pack_.path)
+        if missing:
+            print(
+                f"capt-hook: packs not cached: {', '.join(missing)} — run `capt-hook pack update`",
+                file=sys.stderr,
+            )
 
 
 def example_hook_source() -> str:
@@ -187,17 +196,25 @@ def print_hook_summary(label: str, summary: dict[str, str]) -> None:
     by_status: defaultdict[str, list[str]] = defaultdict(list)
     for event, status in summary.items():
         by_status[status].append(event)
-    print(f"{label}:")
+    click.echo(f"{label}:")
     if not summary:
-        print("  no hook entries")
+        click.echo("  no hook entries")
     for event in by_status["added"]:
-        print(f"  + added {event}")
+        click.echo(f"  + added {event}")
     for event in by_status["updated"]:
-        print(f"  ~ updated {event}")
+        click.echo(f"  ~ updated {event}")
     for event in by_status["removed"]:
-        print(f"  - removed {event}")
+        click.echo(f"  - removed {event}")
     if unchanged := by_status["unchanged"]:
-        print(f"  unchanged: {', '.join(unchanged)} (already present)")
+        click.echo(f"  unchanged: {', '.join(unchanged)} (already present)")
+
+
+def regenerate_settings(state: CliState) -> None:
+    state.discover()
+    settings_path = state.root / ".claude" / "settings.local.json"
+    merged, summary = merge_settings(".claude/hooks", settings_path)
+    write_settings(settings_path, merged)
+    print_hook_summary(str(settings_path.relative_to(state.root)), summary)
 
 
 def settings_drift(root: Path) -> set[str]:
@@ -286,40 +303,51 @@ def run_event(
         print(json.dumps(output))
 
 
-def init_project(root: Path) -> None:
+def init_project(root: Path, *, review: bool = True) -> None:
+    from captain_hook.review.cli import watch_repo
+    from captain_hook.review.repo import repo_key
+
     hooks_dir = root / ".claude" / "hooks"
     hooks_dir.mkdir(parents=True, exist_ok=True)
 
     example = hooks_dir / "example.py"
-    example_created = not example.exists()
-    if example_created:
+    if not example.exists():
         example.write_text(example_hook_source())
 
     settings_path = root / ".claude" / "settings.local.json"
-    reset()
-    discover_hooks(str(hooks_dir))
+    CliState(root=root, hooks=str(hooks_dir)).discover()
     merged, summary = merge_settings(".claude/hooks", settings_path)
     write_settings(settings_path, merged)
 
     skills_summary = install_skills(root)
 
-    print(f"Scaffolded {example.relative_to(root)} + {settings_path.relative_to(root)}.")
-    print()
+    click.echo(f"Scaffolded {example.relative_to(root)} + {settings_path.relative_to(root)}.")
+    click.echo()
     print_hook_summary(str(settings_path.relative_to(root)), summary)
-    print()
-    print(".claude/skills/:")
+    click.echo()
+    click.echo(".claude/skills/:")
     for name in (n for n, status in skills_summary.items() if status == "installed"):
-        print(f"  + installed {name}")
+        click.echo(f"  + installed {name}")
     if skipped := [n for n, status in skills_summary.items() if status == "skipped"]:
-        print(f"  unchanged: {', '.join(skipped)} (already present; capt-hook skills install --force to refresh)")
-    print()
-    print("Next:")
-    print("  1. Read the quickstart: https://yasyf.github.io/captain-hook/")
-    print("  2. Edit example.py or add new files under .claude/hooks/")
-    print("  3. uvx capt-hook test       # verify inline tests")
-    print("  4. uvx capt-hook register-hooks    # re-register after adding events")
-    print("  5. /bootstrapping-hooks in Claude  # mine hooks from this repo's conventions")
-    print()
+        click.echo(f"  unchanged: {', '.join(skipped)} (already present; capt-hook skills install --force to refresh)")
+    click.echo()
+    match (review, repo_key(root)):
+        case (False, _):
+            click.echo("Session reviewer: skipped (--no-review) — `uvx capt-hook review enable` to turn it on later.")
+        case (True, None):
+            click.echo("Session reviewer: needs a git repo with a remote — `uvx capt-hook review enable` once it has one.")
+        case (True, repo):
+            watch_repo(repo)
+            click.echo(f"Session reviewer: watching {repo} — mines your ended sessions and opens hook PRs automatically.")
+            click.echo("  Stop anytime with `uvx capt-hook review disable`.")
+    click.echo()
+    click.echo("Next:")
+    click.echo("  1. Read the quickstart: https://yasyf.github.io/captain-hook/")
+    click.echo("  2. Edit example.py or add new files under .claude/hooks/")
+    click.echo("  3. uvx capt-hook test               # verify inline tests")
+    click.echo("  4. uvx capt-hook register-hooks     # re-register after adding events")
+    click.echo('  5. Ask Claude "set up captain hook" # mine guardrails from this repo (the bootstrapping-hooks skill)')
+    click.echo()
     maybe_launch_bootstrap(root)
 
 
@@ -477,10 +505,11 @@ def test(state: CliState, json_output: bool) -> None:
 
 
 @cli.command()
+@click.option("--no-review", is_flag=True, default=False, help="Skip enabling the SessionEnd session reviewer for this repo")
 @click.pass_obj
-def init(state: CliState) -> None:
-    """Scaffold the hooks directory, install bundled skills, and wire settings."""
-    init_project(state.root)
+def init(state: CliState, no_review: bool) -> None:
+    """Scaffold the hooks directory, install bundled skills, wire settings, and enable the session reviewer."""
+    init_project(state.root, review=not no_review)
 
 
 @cli.command()
@@ -505,6 +534,75 @@ def skills_install(state: CliState, force: bool) -> None:
         click.echo(f"  {status} {name}")
 
 
+@cli.group()
+def pack() -> None:
+    """Manage capt-hook packs — named collections of hooks (builtin or from GitHub)."""
+
+
+@pack.command(name="add")
+@click.argument("target")
+@click.pass_obj
+def pack_add(state: CliState, target: str) -> None:
+    """Enable a builtin pack by name, or an external pack as github:owner/repo[@ref]."""
+    try:
+        entry = (
+            manager.BuiltinPack(name=target)
+            if target in manager.builtin_packs()
+            else manager.fetch_pack(manager.PackSource.parse(target)).entry
+        )
+    except manager.PackError as e:
+        raise click.ClickException(str(e)) from e
+    manager.upsert_entry(manager.packs_toml_path(state.root), entry)
+    click.echo(f"  added {entry.name}")
+    regenerate_settings(state)
+
+
+@pack.command(name="list")
+@click.pass_obj
+def pack_list(state: CliState) -> None:
+    """List the packs enabled in .claude/hooks/packs.toml."""
+    resolved, missing = manager.resolve_enabled_packs(state.root)
+    for r in resolved:
+        match r.entry:
+            case manager.BuiltinPack():
+                kind, ref = "builtin", "-"
+            case manager.ExternalPack(source=source, commit=commit):
+                kind, ref = "github", f"{source.ref or 'HEAD'}@{commit[:7]}"
+        count = sum(1 for p in r.path.glob("*.py") if not p.stem.startswith("_") and p.stem != CONF_MODULE)
+        click.echo(f"  {r.entry.name:24} {kind:8} {ref:20} v{r.manifest.version:8} {count} hooks")
+    for name in missing:
+        click.echo(f"  {name:24} github   (not cached — run `capt-hook pack update`)")
+
+
+@pack.command(name="remove")
+@click.argument("name")
+@click.pass_obj
+def pack_remove(state: CliState, name: str) -> None:
+    """Disable a pack (leaves its content-addressed cache intact)."""
+    try:
+        manager.delete_entry(manager.packs_toml_path(state.root), name)
+    except manager.PackError as e:
+        raise click.ClickException(str(e)) from e
+    click.echo(f"  removed {name}")
+    regenerate_settings(state)
+
+
+@pack.command(name="update")
+@click.argument("name", required=False)
+@click.pass_obj
+def pack_update(state: CliState, name: str | None) -> None:
+    """Re-resolve external packs' refs to fresh commits and re-fetch."""
+    path = manager.packs_toml_path(state.root)
+    for entry in manager.read_entries(path):
+        match entry:
+            case manager.ExternalPack(name=n, source=source) if name in (None, n):
+                manager.upsert_entry(path, fresh := manager.fetch_pack(source).entry)
+                click.echo(f"  updated {n} -> {fresh.commit[:7]}")
+            case manager.BuiltinPack(name=n) if name == n:
+                click.echo(f"  {n} is builtin; it tracks the installed capt-hook version")
+    regenerate_settings(state)
+
+
 cli.add_command(review)
 
 main = cli

{capt_hook-3.1.0 → capt_hook-3.3.0}/captain_hook/loader.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 import importlib
+import importlib.machinery
 import importlib.util
 import pkgutil
+import re
 import sys
 from pathlib import Path
 from types import ModuleType
@@ -14,6 +16,7 @@ from pydantic_settings import BaseSettings
 from captain_hook.app import State, _state
 
 CONF_MODULE = "conf"
+PACK_PACKAGE_PREFIX = "captain_hook._packs"
 
 
 def build_hook_settings(module: ModuleType) -> BaseSettings | ModuleType:
@@ -61,3 +64,18 @@ def discover_hooks(hooks_dir: str | Path, state: State | None = None) -> None:
 
     for fqn in sorted(all_modules - {f"{pkg}.{CONF_MODULE}"}):
         import_or_reload(fqn, fresh_this_pass)
+
+
+def import_pack_module(fqn: str, path: Path) -> ModuleType:
+    loader = importlib.machinery.SourceFileLoader(fqn, str(path))
+    module = importlib.util.module_from_spec(importlib.machinery.ModuleSpec(fqn, loader, origin=str(path)))
+    sys.modules[fqn] = module
+    loader.exec_module(module)
+    return module
+
+
+def discover_pack(name: str, pack_dir: Path) -> None:
+    pkg = f"{PACK_PACKAGE_PREFIX}.{re.sub(r'\W', '_', name)}"
+    for path in sorted(pack_dir.glob("*.py")):
+        if not (path.stem.startswith("_") or path.stem == CONF_MODULE):
+            import_pack_module(f"{pkg}.{path.stem}", path)

capt_hook-3.3.0/captain_hook/packs/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

capt_hook-3.3.0/captain_hook/packs/general/capt-hook.toml

@@ -0,0 +1,4 @@
+name = "general"
+version = "0.1.0"
+description = "Language-agnostic guards: git/command safety, code stewardship, doc & prompt nudges, task & plan discipline, and a code-review gate."
+hooks = "."

capt_hook-3.3.0/captain_hook/packs/general/commands.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from captain_hook import (
+    Allow,
+    BaseHookEvent,
+    Block,
+    CustomCondition,
+    Event,
+    Input,
+    Tool,
+    UsedSkill,
+    block_command,
+    hook,
+    nudge,
+)
+
+block_command(
+    ["git", "stash"],
+    reason="git stash is not allowed",
+    hint="Commit your changes to a branch instead",
+    tests={
+        Input(command="git stash"): Block(),
+        Input(command="git stash pop"): Block(),
+        Input(command="git status"): Allow(),
+    },
+)
+
+
+class UnpipedGrep(CustomCondition):
+    """True when a `grep` command does not consume piped input.
+
+    Allows the stream-filter idiom (`… | grep`) while still blocking grep used
+    for file searching, whether standalone, heading a pipe, or in a `&&`/`;` chain.
+    """
+
+    def check(self, evt: BaseHookEvent) -> bool:
+        if not (cl := evt.command_line):
+            return False
+        return any(
+            cmd.matches(r"^grep\b") and (i == 0 or cl.parts[i - 1][1] != "|") for i, (cmd, _) in enumerate(cl.parts)
+        )
+
+
+hook(
+    Event.PreToolUse,
+    only_if=[Tool("Bash"), UnpipedGrep()],
+    message="BLOCKED: Use ripgrep (rg) instead of grep. Replace grep with rg, or use the built-in Grep tool.",
+    block=True,
+    tests={
+        Input(command="grep -rn foo src/"): Block(),
+        Input(command="ls | grep foo"): Allow(),
+        Input(command="cat x | grep foo | sort"): Allow(),
+        Input(command="grep foo file.py | wc -l"): Block(),
+        Input(command="grep foo a && echo done"): Block(),
+        Input(command="git log --grep=fix"): Allow(),
+        Input(command='git log --grep "fix bug"'): Allow(),
+    },
+)
+
+# Requires the codex plugin (/plugin install codex@skills from yasyf/cc-skills).
+# Delete this nudge if you don't use Codex.
+nudge(
+    """
+    Multiple tool failures detected without a /codex invocation. After 2 failed
+    approaches, get a second opinion from `/codex` before attempting a 3rd —
+    Codex catches errors that Claude may miss.
+    """,
+    skip_if=[UsedSkill("codex|codex:codex")],
+    events=Event.PostToolUseFailure,
+    when=lambda evt: evt.ctx.turn.count_failures() >= 2 and not evt.ctx.t.has_command(r"codex"),
+)

capt_hook-3.3.0/captain_hook/packs/general/docs.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from captain_hook import Allow, FilePath, Input, Tool, UsedSkill, Warn, nudge
+
+# Advisory reminder to consult the writing-docs skill (and run slop-cop) before
+# editing documentation. Fires once per session on the first doc edit and stands
+# down once the skill has been used. Advisory only, so it never blocks an edit.
+#
+# The scaffolded .claude/settings.json registers the yasyf/cc-skills marketplace
+# and enables writing-docs@skills, so the skill (and the skip_if check) activates
+# when the folder is trusted — no manual /plugin install.
+nudge(
+    "You're editing documentation. Consult the writing-docs skill first for the "
+    "Diataxis modes, voice rules, and code-sample rules, then run "
+    "`slop-cop check <file> --lang=markdown` to catch prose tells before you finish.",
+    only_if=[Tool("Write|Edit"), FilePath("**/*.md", "**/*.qmd", "docs/**", "README.md")],
+    skip_if=[UsedSkill("writing-docs|writing-docs:writing-docs")],
+    max_fires=1,
+    tests={
+        Input(tool="Write", file="docs/guide/x.qmd", content="# X"): Warn(pattern="writing-docs"),
+        Input(tool="Edit", file="src/app.py", content="x = 1"): Allow(),
+    },
+)

capt_hook-3.3.0/captain_hook/packs/general/plans.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from captain_hook import Allow, BaseHookEvent, Block, CustomCondition, Event, Input, Tool, hook
+
+
+class RewritingExistingPlan(CustomCondition):
+    """True when a Write targets a plan file (`.md` under `plans/` or `specs/`) that was
+    already written earlier this session, with no new plan cycle (EnterPlanMode) since the
+    last Write to it.
+
+    Reads from ``evt.ctx.prior`` (the window before the current turn's last exchange) so the
+    pending Write being evaluated is never itself counted as the prior edit. A write to the
+    file this session already implies it exists, so no filesystem check is needed.
+    """
+
+    def check(self, evt: BaseHookEvent) -> bool:
+        fp = evt.file
+        if not fp or fp.suffix != ".md" or not fp.under("plans/", "specs/"):
+            return False
+        if not evt.ctx.prior.has_edit_to(str(fp)):
+            return False
+        return not evt.ctx.prior.after(tool="Write", file=str(fp)).has_tool("EnterPlanMode")
+
+
+hook(
+    Event.PreToolUse,
+    only_if=[Tool("Write"), RewritingExistingPlan()],
+    message=(
+        "This plan file was already written in this planning session. Use the Edit tool "
+        "to make incremental changes instead of rewriting the entire plan with Write."
+    ),
+    block=True,
+    tests={
+        # Rewriting a plan already written this session, no new plan cycle since -> block.
+        Input(
+            tool="Write",
+            file="/x/plans/p.md",
+            content="# Plan v2",
+            transcript=[
+                {"type": "assistant", "message": {"content": [
+                    {"type": "tool_use", "name": "Write", "id": "w0",
+                     "input": {"file_path": "/x/plans/p.md", "content": "# Plan v1"}}]}},
+                {"type": "assistant", "message": {"content": [
+                    {"type": "tool_use", "name": "Write", "id": "w1",
+                     "input": {"file_path": "/x/plans/p.md", "content": "# Plan v2"}}]}},
+            ],
+        ): Block(),
+        # A new plan cycle (EnterPlanMode) started since the last write -> allow the rewrite.
+        Input(
+            tool="Write",
+            file="/x/plans/p.md",
+            content="# Plan v2",
+            transcript=[
+                {"type": "assistant", "message": {"content": [
+                    {"type": "tool_use", "name": "Write", "id": "w0",
+                     "input": {"file_path": "/x/plans/p.md", "content": "# Plan v1"}}]}},
+                {"type": "assistant", "message": {"content": [
+                    {"type": "tool_use", "name": "EnterPlanMode", "id": "p1", "input": {}}]}},
+                {"type": "assistant", "message": {"content": [
+                    {"type": "tool_use", "name": "Write", "id": "w1",
+                     "input": {"file_path": "/x/plans/p.md", "content": "# Plan v2"}}]}},
+            ],
+        ): Allow(),
+        # First write of this plan this session -> allow.
+        Input(tool="Write", file="/x/plans/p.md", content="# Plan", transcript=[]): Allow(),
+        # Not a plan file -> allow.
+        Input(tool="Write", file="/x/src/main.py", content="x = 1"): Allow(),
+    },
+)

capt_hook-3.3.0/captain_hook/packs/general/prompts.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from captain_hook import Allow, Content, Input, Tool, UsedSkill, Warn, nudge
+
+PROMPT_MARKERS = (
+    r"<instruction>|<system>|<examples>|<success_criteria>|<output_format>|"
+    r"<key_constraints>|<reasoning_framework>|<action_rules>|<preferred_patterns>|"
+    r"<persona>|<role>|<tool_persistence>|<completeness_contract>|<verification_loop>|"
+    r"You are an?\b|Your task is to\b|You will be provided with\b|"
+    r"def\s+\w*prompt\s*\(|(?i:\b(?:system|developer) prompt\b)|"
+    r"messages\s*=\s*\[|"
+    r"""["']role["']\s*:\s*["'](?:system|user|assistant|developer)["']"""
+)
+
+nudge(
+    "You're editing LLM prompt content. The `llm-prompts` skill covers positive framing, "
+    "XML structure, the prompting principles, and current per-provider model behaviors "
+    "(Claude, GPT-5.x, Gemini) — consult it before writing prompts. After editing, run "
+    "`/slop-cop-check` on the file to surface LLM-generated writing tells (overused "
+    "intensifiers, hedge stacks, em-dash pivots, throat-clearing) and revise any real hits.",
+    only_if=[Tool("Edit|Write"), Content(PROMPT_MARKERS, project_only=False)],
+    skip_if=[
+        UsedSkill("llm-prompts|llm-prompts:llm-prompts"),
+        UsedSkill("slop-cop:slop-cop-check|slop-cop:slop-cop-prose|slop-cop-check|slop-cop-prose"),
+    ],
+    tests={
+        Input(
+            file="agent.py", content='messages = [{"role": "system", "content": "You are a helpful assistant."}]\n'
+        ): Warn(),
+        Input(file="prompt.md", content="<instruction>\nSummarize the document.\n</instruction>\n"): Warn(),
+        Input(file="util.py", content="def add(a, b):\n    return a + b\n"): Allow(),
+    },
+)

capt_hook-3.3.0/captain_hook/packs/general/review.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from captain_hook import Allow, BaseHookEvent, Block, CustomCondition, Event, Input, Waiting, gate
+
+# Prose and config file extensions that shouldn't, on their own, demand a code-review pass.
+# Tailor this (and the excluded dirs below) to scope what counts as "source" for your repo.
+NON_SOURCE_SUFFIXES = (
+    ".md", ".mdx", ".rst", ".txt", ".json", ".toml",
+    ".yaml", ".yml", ".ini", ".cfg", ".lock",
+)
+
+
+class EditedSource(CustomCondition):
+    """True when the session edited a non-test source file (docs and config excluded)."""
+
+    def check(self, evt: BaseHookEvent) -> bool:
+        return any(
+            not f.is_test
+            and f.suffix not in NON_SOURCE_SUFFIXES
+            and not f.under("docs", ".claude", ".github")
+            for f in evt.ctx.t.tool_calls.named("Edit|Write").files()
+        )
+
+
+gate(
+    "You changed source files but haven't done a review pass. Before stopping, review your "
+    "changes for correctness and against STYLEGUIDE.md, and fix any issues in the code you "
+    "wrote. See: STYLEGUIDE.md.",
+    only_if=[EditedSource()],
+    skip_if=[Waiting()],
+    events=Event.Stop,
+    tests={
+        Input(transcript=[
+            {"type": "assistant", "message": {"content": [
+                {"type": "tool_use", "name": "Edit", "id": "e1",
+                 "input": {"file_path": "src/app.py", "old_string": "a", "new_string": "b"}}]}},
+        ]): Block(),
+        Input(transcript=[
+            {"type": "assistant", "message": {"content": [
+                {"type": "tool_use", "name": "Edit", "id": "e1",
+                 "input": {"file_path": "README.md", "old_string": "a", "new_string": "b"}}]}},
+        ]): Allow(),
+    },
+)