capt-hook 0.2.0__tar.gz → 0.4.0__tar.gz

{capt_hook-0.2.0 → capt_hook-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 0.2.0
+Version: 0.4.0
 Summary: Declarative hook framework for Claude Code
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali
@@ -32,10 +32,11 @@ Requires-Dist: loguru>=0.7.3
 Requires-Dist: pytest>=8.0 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24 ; extra == 'dev'
 Requires-Dist: pyright>=1.1 ; extra == 'dev'
+Requires-Dist: pyyaml>=6 ; extra == 'dev'
 Requires-Dist: ruff>=0.8 ; extra == 'dev'
 Requires-Python: >=3.12
 Project-URL: Homepage, https://github.com/yasyf/captain-hook
-Project-URL: Documentation, https://captain-hook.readthedocs.io
+Project-URL: Documentation, https://yasyf.github.io/captain-hook/
 Project-URL: Repository, https://github.com/yasyf/captain-hook
 Project-URL: Issues, https://github.com/yasyf/captain-hook/issues
 Project-URL: Changelog, https://github.com/yasyf/captain-hook/blob/main/CHANGELOG.md
@@ -46,7 +47,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/capt-hook.svg)](https://pypi.org/project/capt-hook/)
 [![Python](https://img.shields.io/pypi/pyversions/capt-hook.svg)](https://pypi.org/project/capt-hook/)
-[![Docs](https://readthedocs.org/projects/captain-hook/badge/?version=latest)](https://captain-hook.readthedocs.io)
+[![Docs](https://github.com/yasyf/captain-hook/actions/workflows/docs.yml/badge.svg)](https://yasyf.github.io/captain-hook/)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm_Noncommercial_1.0.0-blue.svg)](https://github.com/yasyf/captain-hook/blob/main/LICENSE)
 
 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.
@@ -99,6 +100,15 @@ capt-hook generate-settings > .claude/settings.local.json
 
 The next time Claude tries `git stash`, captain-hook returns a deny with your reason and hint.
 
+## Agent skills & plugin
+
+Don't want to write hooks by hand? capt-hook ships two [Agent Skills](https://yasyf.github.io/captain-hook/docs/getting-started/skills.html) — `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 them into `.claude/skills/`, or get them as a plugin:
+
+```
+/plugin marketplace add yasyf/captain-hook
+/plugin install captain-hook@captain-hook
+```
+
 ## What problems does this solve?
 
 - **Block dangerous tool calls** before they execute (`PreToolUse`) — force-push, package-manager footguns, raw `rm -rf`.
@@ -108,6 +118,6 @@ The next time Claude tries `git stash`, captain-hook returns a deny with your re
 
 ## Docs
 
-[Read the docs](https://captain-hook.readthedocs.io) for the full guide: conditions, primitives, LLM hooks, workflows, state, and real-world patterns.
+[Read the docs](https://yasyf.github.io/captain-hook/) for the full guide: conditions, primitives, LLM hooks, workflows, state, and real-world patterns.
 
-Working on captain-hook itself? See the [development guide](https://captain-hook.readthedocs.io/en/latest/development/).
+Working on captain-hook itself? See the [development guide](https://yasyf.github.io/captain-hook/docs/development/).

{capt_hook-0.2.0 → capt_hook-0.4.0}/README.md

@@ -2,7 +2,7 @@
 
 [![PyPI](https://img.shields.io/pypi/v/capt-hook.svg)](https://pypi.org/project/capt-hook/)
 [![Python](https://img.shields.io/pypi/pyversions/capt-hook.svg)](https://pypi.org/project/capt-hook/)
-[![Docs](https://readthedocs.org/projects/captain-hook/badge/?version=latest)](https://captain-hook.readthedocs.io)
+[![Docs](https://github.com/yasyf/captain-hook/actions/workflows/docs.yml/badge.svg)](https://yasyf.github.io/captain-hook/)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm_Noncommercial_1.0.0-blue.svg)](https://github.com/yasyf/captain-hook/blob/main/LICENSE)
 
 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.
@@ -55,6 +55,15 @@ capt-hook generate-settings > .claude/settings.local.json
 
 The next time Claude tries `git stash`, captain-hook returns a deny with your reason and hint.
 
+## Agent skills & plugin
+
+Don't want to write hooks by hand? capt-hook ships two [Agent Skills](https://yasyf.github.io/captain-hook/docs/getting-started/skills.html) — `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 them into `.claude/skills/`, or get them as a plugin:
+
+```
+/plugin marketplace add yasyf/captain-hook
+/plugin install captain-hook@captain-hook
+```
+
 ## What problems does this solve?
 
 - **Block dangerous tool calls** before they execute (`PreToolUse`) — force-push, package-manager footguns, raw `rm -rf`.
@@ -64,6 +73,6 @@ The next time Claude tries `git stash`, captain-hook returns a deny with your re
 
 ## Docs
 
-[Read the docs](https://captain-hook.readthedocs.io) for the full guide: conditions, primitives, LLM hooks, workflows, state, and real-world patterns.
+[Read the docs](https://yasyf.github.io/captain-hook/) for the full guide: conditions, primitives, LLM hooks, workflows, state, and real-world patterns.
 
-Working on captain-hook itself? See the [development guide](https://captain-hook.readthedocs.io/en/latest/development/).
+Working on captain-hook itself? See the [development guide](https://yasyf.github.io/captain-hook/docs/development/).

capt_hook-0.4.0/captain_hook/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "captain-hook",
+  "displayName": "Captain Hook",
+  "description": "Skills for the capt-hook declarative hook framework: bootstrap gates and nudges from a repo's conventions, and translate style guides into enforced StyleRules.",
+  "author": { "name": "Yasyf Mohamedali", "email": "yasyfm@gmail.com" },
+  "homepage": "https://yasyf.github.io/captain-hook/",
+  "repository": "https://github.com/yasyf/captain-hook",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "keywords": ["claude-code", "hooks", "guardrails", "styleguide"]
+}

capt_hook-0.4.0/captain_hook/__init__.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+from captain_hook import style as style
+from captain_hook.app import hook as hook
+from captain_hook.app import on as on
+from captain_hook.app import register as register
+from captain_hook.command import Command as Command
+from captain_hook.command import CommandLine as CommandLine
+from captain_hook.command import Redirect as Redirect
+from captain_hook.context import HookContext as HookContext
+from captain_hook.events import (
+    BaseHookEvent as BaseHookEvent,
+)
+from captain_hook.events import (
+    NotificationEvent as NotificationEvent,
+)
+from captain_hook.events import (
+    PostToolUseEvent as PostToolUseEvent,
+)
+from captain_hook.events import (
+    PostToolUseFailureEvent as PostToolUseFailureEvent,
+)
+from captain_hook.events import (
+    PreCompactEvent as PreCompactEvent,
+)
+from captain_hook.events import (
+    PreToolUseEvent as PreToolUseEvent,
+)
+from captain_hook.events import (
+    StopEvent as StopEvent,
+)
+from captain_hook.events import (
+    SubagentStartEvent as SubagentStartEvent,
+)
+from captain_hook.events import (
+    SubagentStopEvent as SubagentStopEvent,
+)
+from captain_hook.events import (
+    ToolHookEvent as ToolHookEvent,
+)
+from captain_hook.events import (
+    UserPromptSubmitEvent as UserPromptSubmitEvent,
+)
+from captain_hook.file import File as File
+from captain_hook.primitives import (
+    GateVerdict as GateVerdict,
+)
+from captain_hook.primitives import (
+    NudgeVerdict as NudgeVerdict,
+)
+from captain_hook.primitives import (
+    PromptCheckVerdict as PromptCheckVerdict,
+)
+from captain_hook.primitives import (
+    block_command as block_command,
+)
+from captain_hook.primitives import (
+    gate as gate,
+)
+from captain_hook.primitives import (
+    llm_evaluate as llm_evaluate,
+)
+from captain_hook.primitives import (
+    llm_gate as llm_gate,
+)
+from captain_hook.primitives import (
+    llm_nudge as llm_nudge,
+)
+from captain_hook.primitives import (
+    prompt_check as prompt_check,
+)
+from captain_hook.primitives import (
+    warn_command as warn_command,
+)
+
+# audit/lint/nudge are imported from their defining modules, not the
+# primitives package: the package attribute and the submodule share a name,
+# and an alias targeting captain_hook.primitives.<name> resolves to the
+# module under static analysis (griffe), shadowing the function.
+from captain_hook.primitives.audit import audit as audit
+from captain_hook.primitives.lint import lint as lint
+from captain_hook.primitives.nudge import nudge as nudge
+from captain_hook.primitives.workflow import (
+    Artifact as Artifact,
+)
+from captain_hook.primitives.workflow import (
+    Step as Step,
+)
+from captain_hook.primitives.workflow import (
+    Workflow as Workflow,
+)
+from captain_hook.primitives.workflow import (
+    text_matches as text_matches,
+)
+from captain_hook.primitives.workflow import (
+    workflow as workflow,
+)
+from captain_hook.prompt import Prompt as Prompt
+from captain_hook.session import SessionSlot as SessionSlot
+from captain_hook.session import SessionStore as SessionStore
+from captain_hook.session import session_state as session_state
+from captain_hook.settings import HooksSettings as HooksSettings
+from captain_hook.settings import build_settings as build_settings
+from captain_hook.signals.nlp import Clause as Clause
+from captain_hook.signals.nlp import NlpSignal as NlpSignal
+from captain_hook.signals.nlp import Phrase as Phrase
+from captain_hook.state import (
+    HookState as HookState,
+)
+from captain_hook.state import (
+    PrimitiveState as PrimitiveState,
+)
+from captain_hook.state import (
+    workflow_state as workflow_state,
+)
+from captain_hook.tasks import Task as Task
+from captain_hook.tasks import Tasks as Tasks
+from captain_hook.testing import (
+    Allow as Allow,
+)
+from captain_hook.testing import (
+    Block as Block,
+)
+from captain_hook.testing import (
+    InlineTests as InlineTests,
+)
+from captain_hook.testing import (
+    Input as Input,
+)
+from captain_hook.testing import (
+    TranscriptFixture as TranscriptFixture,
+)
+from captain_hook.testing import (
+    Warn as Warn,
+)
+from captain_hook.tools import EditOp as EditOp
+from captain_hook.tools import TaskOp as TaskOp
+from captain_hook.tools import WriteOp as WriteOp
+from captain_hook.transcript import (
+    ToolUse as ToolUse,
+)
+from captain_hook.transcript import (
+    ToolUseQuery as ToolUseQuery,
+)
+from captain_hook.transcript import (
+    ToolUseSequence as ToolUseSequence,
+)
+from captain_hook.transcript import (
+    Transcript as Transcript,
+)
+from captain_hook.transcript import (
+    TranscriptMessage as TranscriptMessage,
+)
+from captain_hook.transcript import (
+    TranscriptSlice as TranscriptSlice,
+)
+from captain_hook.transcript import (
+    Turn as Turn,
+)
+from captain_hook.transcript.inputs import (
+    AgentInput as AgentInput,
+)
+from captain_hook.transcript.inputs import (
+    BashInput as BashInput,
+)
+from captain_hook.transcript.inputs import (
+    EditInput as EditInput,
+)
+from captain_hook.transcript.inputs import (
+    FileInputBase as FileInputBase,
+)
+from captain_hook.transcript.inputs import (
+    GenericInput as GenericInput,
+)
+from captain_hook.transcript.inputs import (
+    GlobInput as GlobInput,
+)
+from captain_hook.transcript.inputs import (
+    GrepInput as GrepInput,
+)
+from captain_hook.transcript.inputs import (
+    InputBase as InputBase,
+)
+from captain_hook.transcript.inputs import (
+    ReadInput as ReadInput,
+)
+from captain_hook.transcript.inputs import (
+    SkillInput as SkillInput,
+)
+from captain_hook.transcript.inputs import (
+    TaskCreateInput as TaskCreateInput,
+)
+from captain_hook.transcript.inputs import (
+    TaskUpdateInput as TaskUpdateInput,
+)
+from captain_hook.transcript.inputs import (
+    WriteInput as WriteInput,
+)
+from captain_hook.transcript.models import ContentBlock as ContentBlock
+from captain_hook.transcript.models import ToolResult as ToolResult
+from captain_hook.types import (
+    Action as Action,
+)
+from captain_hook.types import (
+    Agent as Agent,
+)
+from captain_hook.types import (
+    Content as Content,
+)
+from captain_hook.types import (
+    CustomCondition as CustomCondition,
+)
+from captain_hook.types import (
+    Event as Event,
+)
+from captain_hook.types import (
+    FilePath as FilePath,
+)
+from captain_hook.types import (
+    HookResult as HookResult,
+)
+from captain_hook.types import (
+    InPlanMode as InPlanMode,
+)
+from captain_hook.types import (
+    RanCommand as RanCommand,
+)
+from captain_hook.types import (
+    ReadFile as ReadFile,
+)
+from captain_hook.types import (
+    Signal as Signal,
+)
+from captain_hook.types import (
+    Signals as Signals,
+)
+from captain_hook.types import (
+    SourceEdits as SourceEdits,
+)
+from captain_hook.types import (
+    TCondition as TCondition,
+)
+from captain_hook.types import (
+    TestFile as TestFile,
+)
+from captain_hook.types import (
+    Tool as Tool,
+)
+from captain_hook.types import (
+    TouchedFile as TouchedFile,
+)
+from captain_hook.types import (
+    UsedSkill as UsedSkill,
+)
+from captain_hook.types import (
+    Waiting as Waiting,
+)

{capt_hook-0.2.0 → capt_hook-0.4.0}/captain_hook/cli.py

@@ -1,14 +1,18 @@
 from __future__ import annotations
 
-import argparse
 import importlib.resources
 import json
 import os
+import shutil
+import subprocess
 import sys
 from collections import defaultdict
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
+import click
+
 from captain_hook.app import _state, load_gitignore, reset
 from captain_hook.context import HookContext
 from captain_hook.dispatch import dispatch
@@ -19,6 +23,20 @@ from captain_hook.transcript import Transcript
 from captain_hook.types import Event
 
 DIST_NAME = "capt-hook"
+EVENT_NAMES = ", ".join(n for e in Event if (n := e.name))
+MARKETPLACE = {"captain-hook": {"source": {"source": "github", "repo": "yasyf/captain-hook"}}}
+PLUGIN_ID = "captain-hook@captain-hook"
+
+
+@dataclass(frozen=True, slots=True)
+class CliState:
+    root: Path
+    hooks: str
+
+    def discover(self) -> None:
+        reset()
+        load_gitignore(self.root)
+        discover_hooks(self.hooks)
 
 
 def example_hook_source() -> str:
@@ -26,6 +44,68 @@ def example_hook_source() -> str:
     return (importlib.resources.files("captain_hook") / "templates" / "example_hook.py.tmpl").read_text()
 
 
+def install_skills(root: Path, *, force: bool = False) -> dict[str, str]:
+    """Copy the bundled Claude Code skills into ``root/.claude/skills``.
+
+    Args:
+        root: Project root receiving the skills.
+        force: Replace existing skill directories wholesale instead of skipping them.
+
+    Returns:
+        Per-skill status of ``"installed"``, ``"replaced"``, or ``"skipped"``.
+    """
+    dest_root = root / ".claude" / "skills"
+    summary: dict[str, str] = {}
+    with importlib.resources.as_file(importlib.resources.files("captain_hook") / "skills") as src_root:
+        for skill in sorted(p for p in src_root.iterdir() if p.is_dir()):
+            dest = dest_root / skill.name
+            if dest.exists() and not force:
+                summary[skill.name] = "skipped"
+                continue
+            if dest.exists():
+                shutil.rmtree(dest)
+                summary[skill.name] = "replaced"
+            else:
+                summary[skill.name] = "installed"
+            shutil.copytree(skill, dest)
+    return summary
+
+
+def register_marketplace(root: Path) -> None:
+    """Enable the captain-hook plugin marketplace in ``root/.claude/settings.local.json``.
+
+    Merges ``extraKnownMarketplaces`` and ``enabledPlugins`` entries into the
+    existing settings so the bundled skills track the repository as a plugin.
+    """
+    settings_path = root / ".claude" / "settings.local.json"
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    existing = json.loads(settings_path.read_text()) if settings_path.exists() else {}
+    merged = existing | {
+        "extraKnownMarketplaces": existing.get("extraKnownMarketplaces", {}) | MARKETPLACE,
+        "enabledPlugins": existing.get("enabledPlugins", {}) | {PLUGIN_ID: True},
+    }
+    settings_path.write_text(json.dumps(merged, indent=2) + "\n")
+
+
+def maybe_launch_bootstrap(root: Path) -> bool:
+    """Offer to launch Claude with the ``bootstrapping-hooks`` skill after ``init``.
+
+    Only fires in an interactive session with the ``claude`` CLI on PATH; CI and
+    scripted runs skip the prompt entirely. On acceptance, the captain-hook plugin
+    marketplace is registered in ``.claude/settings.local.json`` before launching.
+
+    Returns:
+        Whether Claude was launched.
+    """
+    if not (sys.stdin.isatty() and shutil.which("claude")):
+        return False
+    if not click.confirm("Bootstrap hooks now? (launches Claude with the bootstrapping-hooks skill)", default=True):
+        return False
+    register_marketplace(root)
+    subprocess.run(["claude", "/bootstrapping-hooks"], cwd=root, check=False)
+    return True
+
+
 def generate_settings(hooks_dir: str = ".claude/hooks", from_source: str = DIST_NAME) -> dict[str, Any]:
     events_by_async: defaultdict[bool, set[str]] = defaultdict(set)
     for entry in _state.hooks:
@@ -158,6 +238,8 @@ def init_project(root: Path) -> None:
     merged, summary = merge_init_settings(".claude/hooks", settings_path)
     settings_path.write_text(json.dumps(merged, indent=2) + "\n")
 
+    skills_summary = install_skills(root)
+
     print(f"Scaffolded {example.relative_to(root)} + {settings_path.relative_to(root)}.")
     print()
     print(f"{settings_path.relative_to(root)}:")
@@ -170,11 +252,20 @@ def init_project(root: Path) -> None:
     if unchanged:
         print(f"  unchanged: {', '.join(unchanged)} (already present)")
     print()
+    print(".claude/skills/:")
+    for name in (n for n, status in skills_summary.items() if status == "installed"):
+        print(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: docs/getting-started/quickstart.md")
+    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. capt-hook test       # verify inline tests")
     print("  4. capt-hook generate-settings    # rewire after adding events")
+    print("  5. /bootstrapping-hooks in Claude  # mine hooks from this repo's conventions")
+    print()
+    maybe_launch_bootstrap(root)
 
 
 def show_logs(session: str | None = None, tail: int | None = None) -> None:
@@ -212,41 +303,6 @@ def show_logs(session: str | None = None, tail: int | None = None) -> None:
     print("\n".join(lines[-tail:] if tail else lines))
 
 
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog="capt-hook",
-        description="Captain Hook — declarative hook framework for Claude Code lifecycle events.",
-    )
-    parser.add_argument(
-        "--hooks",
-        default=None,
-        help="Path to hooks package directory (default: $CLAUDE_PROJECT_DIR/.claude/hooks)",
-    )
-    parser.add_argument("--root", default=None, help="Project root for gitignore and session resolution")
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    run_parser = sub.add_parser("run", help="Dispatch a hook event (reads JSON from stdin, writes JSON to stdout)")
-    run_parser.add_argument("event", help=f"Event type: {', '.join(n for e in Event if (n := e.name))}")
-    run_parser.add_argument("--async", dest="async_", action="store_true", default=False, help="Run async hooks only")
-
-    settings_parser = sub.add_parser(
-        "generate-settings", help="Generate Claude Code settings JSON for .claude/settings.local.json"
-    )
-    settings_parser.add_argument("--hooks-dir", default=".claude/hooks", help="Hooks directory relative to project root")
-    settings_parser.add_argument("--no-merge", action="store_true", help="Output standalone JSON instead of merging")
-    settings_parser.add_argument("--from", dest="from_source", default=DIST_NAME, help=f"Package source for uvx --from (local path or PyPI spec, default: {DIST_NAME})")
-
-    test_parser = sub.add_parser("test", help="Run inline tests from all registered hooks")
-    test_parser.add_argument("--json", dest="json_output", action="store_true", help="Emit one JSON record per test (CI mode)")
-    sub.add_parser("init", help="Scaffold hooks directory, bin script, and settings")
-
-    logs_parser = sub.add_parser("logs", help="View a recent captain-hook session log")
-    logs_parser.add_argument("--session", default=None, help="Session id or transcript path (hashed) to view")
-    logs_parser.add_argument("--tail", type=int, default=None, help="Show only the last N lines")
-
-    return parser
-
-
 def expected_kinds_from_state() -> dict[str, str]:
     out: dict[str, str] = {}
     for entry in _state.hooks:
@@ -305,37 +361,91 @@ def run_tests(json_output: bool = False) -> None:
         sys.exit(1)
 
 
-def main() -> None:
-    parser = build_parser()
-    args = parser.parse_args()
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option(
+    "--hooks",
+    default=None,
+    help="Path to hooks package directory (default: $CLAUDE_PROJECT_DIR/.claude/hooks)",
+)
+@click.option("--root", "root_path", default=None, help="Project root for gitignore and session resolution")
+@click.pass_context
+def cli(ctx: click.Context, hooks: str | None, root_path: str | None) -> None:
+    """Captain Hook — declarative hook framework for Claude Code lifecycle events."""
+    root = Path(root_path) if root_path else Path(env) if (env := os.environ.get("CLAUDE_PROJECT_DIR")) else Path.cwd()
+    ctx.obj = CliState(root=root, hooks=hooks or str(root / ".claude" / "hooks"))
+
+
+@cli.command(
+    short_help="Dispatch a hook event (reads JSON from stdin, writes JSON to stdout)",
+    help=(
+        "Dispatch a hook event (reads JSON from stdin, writes JSON to stdout).\n\n"
+        f"EVENT is one of: {EVENT_NAMES}."
+    ),
+)
+@click.argument("event")
+@click.option("--async", "async_", is_flag=True, default=False, help="Run async hooks only")
+@click.pass_obj
+def run(state: CliState, event: str, async_: bool) -> None:
+    state.discover()
+    run_event(event, async_=async_, root=state.root)
+
+
+@cli.command(name="generate-settings")
+@click.option("--hooks-dir", default=".claude/hooks", help="Hooks directory relative to project root")
+@click.option("--no-merge", is_flag=True, default=False, help="Output standalone JSON instead of merging")
+@click.option(
+    "--from",
+    "from_source",
+    default=DIST_NAME,
+    help=f"Package source for uvx --from (local path or PyPI spec, default: {DIST_NAME})",
+)
+@click.pass_obj
+def generate_settings_cmd(state: CliState, hooks_dir: str, no_merge: bool, from_source: str) -> None:
+    """Generate Claude Code settings JSON for .claude/settings.local.json."""
+    state.discover()
+    if no_merge:
+        click.echo(generate_settings_json(hooks_dir, from_source=from_source))
+    else:
+        settings_path = state.root / ".claude" / "settings.local.json"
+        click.echo(json.dumps(merge_settings(hooks_dir, settings_path, from_source=from_source), indent=2))
 
-    project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
-    root = Path(args.root) if args.root else Path(project_dir) if project_dir else Path.cwd()
-    hooks = args.hooks or str(root / ".claude" / "hooks")
 
-    if args.command == "init":
-        init_project(root)
-        return
+@cli.command()
+@click.option("--json", "json_output", is_flag=True, default=False, help="Emit one JSON record per test (CI mode)")
+@click.pass_obj
+def test(state: CliState, json_output: bool) -> None:
+    """Run inline tests from all registered hooks."""
+    state.discover()
+    run_tests(json_output=json_output)
 
-    if args.command == "logs":
-        show_logs(session=args.session, tail=args.tail)
-        return
 
-    reset()
-    load_gitignore(root)
-    discover_hooks(hooks)
-
-    match args.command:
-        case "run":
-            run_event(args.event, async_=args.async_, root=root)
-        case "generate-settings":
-            if args.no_merge:
-                print(generate_settings_json(args.hooks_dir, from_source=args.from_source))
-            else:
-                settings_path = root / ".claude" / "settings.local.json"
-                merged = merge_settings(args.hooks_dir, settings_path, from_source=args.from_source)
-                print(json.dumps(merged, indent=2))
-        case "test":
-            run_tests(json_output=args.json_output)
-        case _:
-            parser.error(f"Unknown command: {args.command}")
+@cli.command()
+@click.pass_obj
+def init(state: CliState) -> None:
+    """Scaffold the hooks directory, install bundled skills, and wire settings."""
+    init_project(state.root)
+
+
+@cli.command()
+@click.option("--session", default=None, help="Session id or transcript path (hashed) to view")
+@click.option("--tail", type=int, default=None, help="Show only the last N lines")
+def logs(session: str | None, tail: int | None) -> None:
+    """View a recent captain-hook session log."""
+    show_logs(session=session, tail=tail)
+
+
+@cli.group()
+def skills() -> None:
+    """Manage the bundled Claude Code skills."""
+
+
+@skills.command(name="install")
+@click.option("--force", is_flag=True, default=False, help="Replace skills that already exist in .claude/skills")
+@click.pass_obj
+def skills_install(state: CliState, force: bool) -> None:
+    """Copy the bundled skills into .claude/skills/."""
+    for name, status in install_skills(state.root, force=force).items():
+        click.echo(f"  {status} {name}")
+
+
+main = cli