familiar-cli 0.3.1__tar.gz → 0.5.0__tar.gz

{familiar_cli-0.3.1/src/familiar_cli.egg-info → familiar_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: familiar-cli
-Version: 0.3.1
+Version: 0.5.0
 Summary: compose and invoke ai agent prompts from reusable templates
 Author-email: cyberwitchery lab <contact@cyberwitchery.com>
 License-Expression: MIT
@@ -66,6 +66,20 @@ conjure conjurings to create system instructions for an agent:
 familiar conjure codex rust infra sec
 ```
 
+save composed conjurings as a reusable subagent:
+
+```bash
+familiar conjure claude python sec --save-subagent
+familiar conjure codex rust infra --save-subagent --subagent-name ship_ops
+```
+
+save an invocation as a reusable skill:
+
+```bash
+familiar invoke claude code-review --save-skill
+familiar invoke codex refactor src/foo.py --save-skill --skill-name cleanup_refactor
+```
+
 invoke an action prompt:
 
 ```bash

{familiar_cli-0.3.1 → familiar_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "familiar-cli"
-version = "0.3.1"
+version = "0.5.0"
 description = "compose and invoke ai agent prompts from reusable templates"
 readme = "readme.md"
 license = "MIT"

{familiar_cli-0.3.1 → familiar_cli-0.5.0}/readme.md

@@ -37,6 +37,20 @@ conjure conjurings to create system instructions for an agent:
 familiar conjure codex rust infra sec
 ```
 
+save composed conjurings as a reusable subagent:
+
+```bash
+familiar conjure claude python sec --save-subagent
+familiar conjure codex rust infra --save-subagent --subagent-name ship_ops
+```
+
+save an invocation as a reusable skill:
+
+```bash
+familiar invoke claude code-review --save-skill
+familiar invoke codex refactor src/foo.py --save-skill --skill-name cleanup_refactor
+```
+
 invoke an action prompt:
 
 ```bash

familiar_cli-0.5.0/src/familiar/_plugins.py

@@ -0,0 +1,44 @@
+"""Shared plugin loading utilities."""
+
+from __future__ import annotations
+
+import warnings
+from importlib.metadata import entry_points
+from typing import Any, Callable
+
+
+def load_plugins(
+    group: str,
+    validate: Callable[[Any], bool],
+    *,
+    label: str,
+    invalid_msg: str = "validation failed",
+) -> list[Any]:
+    """Load plugins from entry points with validation.
+
+    Args:
+        group: Entry point group name.
+        validate: Predicate that returns True for valid loaded objects.
+        label: Human-readable label for warning messages (e.g. "linter plugin").
+        invalid_msg: Message when validation fails.
+
+    Returns:
+        List of loaded and validated plugin objects.
+    """
+    results: list[Any] = []
+    for ep in entry_points(group=group):
+        try:
+            obj = ep.load()
+            if not validate(obj):
+                warnings.warn(
+                    f"{label} '{ep.name}': {invalid_msg}",
+                    stacklevel=2,
+                )
+                continue
+            results.append(obj)
+        except Exception as e:
+            warnings.warn(
+                f"failed to load {label} '{ep.name}': {e}",
+                stacklevel=2,
+            )
+    return results

{familiar_cli-0.3.1 → familiar_cli-0.5.0}/src/familiar/agents.py

@@ -5,15 +5,20 @@ from __future__ import annotations
 import subprocess
 import warnings
 from abc import ABC, abstractmethod
-from importlib.metadata import entry_points
 from pathlib import Path
 
+from ._plugins import load_plugins
+
 
 class Agent(ABC):
     """Base class for AI coding agents."""
 
     name: str
     output_file: str
+    skill_dir: str | None = None
+    skill_file: str = "SKILL.md"
+    subagent_dir: str | None = None
+    subagent_file: str = "AGENT.md"
 
     @abstractmethod
     def run(
@@ -21,10 +26,32 @@ class Agent(ABC):
     ) -> int:
         """Run the agent with the given prompt."""
 
+    def supports_skills(self) -> bool:
+        """Whether this agent supports reusable skill files."""
+        return self.skill_dir is not None
+
+    def skill_path(self, repo_root: Path, skill_name: str) -> Path:
+        """Build the skill path for a given skill name."""
+        if self.skill_dir is None:
+            raise ValueError(f"agent does not support skills: {self.name}")
+        return repo_root / self.skill_dir / skill_name / self.skill_file
+
+    def supports_subagents(self) -> bool:
+        """Whether this agent supports reusable subagent files."""
+        return self.subagent_dir is not None
+
+    def subagent_path(self, repo_root: Path, subagent_name: str) -> Path:
+        """Build the subagent path for a given subagent name."""
+        if self.subagent_dir is None:
+            raise ValueError(f"agent does not support subagents: {self.name}")
+        return repo_root / self.subagent_dir / subagent_name / self.subagent_file
+
 
 class CodexAgent(Agent):
     name = "codex"
     output_file = "AGENTS.md"
+    skill_dir = ".codex/skills"
+    subagent_dir = ".codex/subagents"
 
     def run(
         self, repo_root: Path, prompt: str, headless: bool, auto: bool = False
@@ -47,6 +74,8 @@ class CodexAgent(Agent):
 class ClaudeAgent(Agent):
     name = "claude"
     output_file = "CLAUDE.md"
+    skill_dir = ".claude/skills"
+    subagent_dir = ".claude/subagents"
 
     def run(
         self, repo_root: Path, prompt: str, headless: bool, auto: bool = False
@@ -68,26 +97,22 @@ def load_agents() -> dict[str, Agent]:
         Dictionary mapping agent names to Agent instances.
         Plugins that fail to load are skipped with a warning.
     """
+    plugins = load_plugins(
+        "familiar.agents",
+        lambda cls: isinstance(cls, type) and issubclass(cls, Agent),
+        label="agent plugin",
+        invalid_msg="not a valid Agent subclass",
+    )
     agents: dict[str, Agent] = {}
-    eps = entry_points(group="familiar.agents")
-
-    for ep in eps:
+    for cls in plugins:
         try:
-            cls = ep.load()
-            if not (isinstance(cls, type) and issubclass(cls, Agent)):
-                warnings.warn(
-                    f"agent plugin '{ep.name}': not a valid Agent subclass",
-                    stacklevel=2,
-                )
-                continue
             instance = cls()
             agents[instance.name] = instance
         except Exception as e:
             warnings.warn(
-                f"failed to load agent plugin '{ep.name}': {e}",
+                f"failed to load agent plugin '{cls.__name__}': {e}",
                 stacklevel=2,
             )
-
     return agents
 
 

{familiar_cli-0.3.1 → familiar_cli-0.5.0}/src/familiar/cli.py

@@ -4,11 +4,14 @@ from __future__ import annotations
 
 import argparse
 import os
+import re
 import shutil
 import subprocess
 import sys
 import tempfile
 import traceback
+import warnings
+from importlib.metadata import version
 from pathlib import Path
 
 from .agents import get_agents, get_agent
@@ -25,6 +28,7 @@ from .render import (
 EXIT_SUCCESS = 0
 EXIT_ERROR = 1  # general error (agent failed, etc.)
 EXIT_USAGE = 2  # usage error (bad args, missing files, etc.)
+_VALID_NAME = re.compile(r"^[a-z0-9_-]+$")
 
 
 class CliError(Exception):
@@ -38,6 +42,11 @@ class CliError(Exception):
         self.exit_code = exit_code
 
 
+def _agent_hint() -> str:
+    """Return a hint string listing valid agent names."""
+    return f"valid agents: {', '.join(get_agents().keys())}"
+
+
 def find_repo_root(start: Path) -> Path:
     """Find the repository root by looking for .git directory.
 
@@ -51,6 +60,25 @@ def find_repo_root(start: Path) -> Path:
     return cur
 
 
+def _remove_worktree(repo_root: Path, worktree_path: Path) -> None:
+    """Best-effort removal of a git worktree."""
+    try:
+        subprocess.run(
+            [
+                "git",
+                "-C",
+                str(repo_root),
+                "worktree",
+                "remove",
+                "--force",
+                str(worktree_path),
+            ],
+            capture_output=True,
+        )
+    except FileNotFoundError:
+        pass
+
+
 def create_worktree(repo_root: Path) -> Path:
     """Create a temporary git worktree for the repository."""
     # Ensure it's a git repo
@@ -95,10 +123,81 @@ def write_instruction(repo_root: Path, agent_name: str, system: str) -> None:
     try:
         agent = get_agent(agent_name)
     except KeyError as e:
-        raise CliError(str(e), hint=f"valid agents: {', '.join(get_agents().keys())}")
+        raise CliError(str(e), hint=_agent_hint())
     (repo_root / agent.output_file).write_text(system.strip() + "\n", encoding="utf-8")
 
 
+def write_skill(
+    repo_root: Path, agent_name: str, invocation: str, skill_name: str, prompt: str
+) -> Path:
+    """Write a reusable skill file for supported agents."""
+    if not _VALID_NAME.match(skill_name):
+        raise CliError(
+            f"invalid skill name: {skill_name}",
+            hint="use lowercase letters, numbers, underscore, or hyphen",
+        )
+
+    try:
+        agent = get_agent(agent_name)
+    except KeyError as e:
+        raise CliError(str(e), hint=_agent_hint())
+
+    if not agent.supports_skills():
+        raise CliError(f"agent does not support skills: {agent_name}")
+
+    skill_path = agent.skill_path(repo_root, skill_name)
+    skill_path.parent.mkdir(parents=True, exist_ok=True)
+    content = (
+        f"# {skill_name}\n\n"
+        "use this skill when this recurring task appears in this repository.\n\n"
+        "## generated from\n\n"
+        f"- invocation: {invocation}\n"
+        f"- agent: {agent_name}\n\n"
+        "## instructions\n\n"
+        f"{prompt.strip()}\n"
+    )
+    skill_path.write_text(content, encoding="utf-8")
+    return skill_path
+
+
+def write_subagent(
+    repo_root: Path,
+    agent_name: str,
+    conjurings: list[str],
+    subagent_name: str,
+    system: str,
+) -> Path:
+    """Write a reusable subagent file for supported agents."""
+    if not _VALID_NAME.match(subagent_name):
+        raise CliError(
+            f"invalid subagent name: {subagent_name}",
+            hint="use lowercase letters, numbers, underscore, or hyphen",
+        )
+
+    try:
+        agent = get_agent(agent_name)
+    except KeyError as e:
+        raise CliError(str(e), hint=_agent_hint())
+
+    if not agent.supports_subagents():
+        raise CliError(f"agent does not support subagents: {agent_name}")
+
+    subagent_path = agent.subagent_path(repo_root, subagent_name)
+    subagent_path.parent.mkdir(parents=True, exist_ok=True)
+    profile = ", ".join(conjurings)
+    content = (
+        f"# {subagent_name}\n\n"
+        "use this subagent when this repository needs this persistent behavior profile.\n\n"
+        "## generated from\n\n"
+        f"- conjurings: {profile}\n"
+        f"- agent: {agent_name}\n\n"
+        "## instructions\n\n"
+        f"{system.strip()}\n"
+    )
+    subagent_path.write_text(content, encoding="utf-8")
+    return subagent_path
+
+
 def parse_kv(pairs: list[str]) -> dict[str, str]:
     out: dict[str, str] = {}
     for p in pairs:
@@ -118,7 +217,7 @@ def run_agent(
     try:
         agent = get_agent(agent_name)
     except KeyError as e:
-        raise CliError(str(e), hint=f"valid agents: {', '.join(get_agents().keys())}")
+        raise CliError(str(e), hint=_agent_hint())
     try:
         return agent.run(repo_root, prompt, headless, auto=auto)
     except FileNotFoundError:
@@ -138,6 +237,14 @@ def cmd_conjure(args: argparse.Namespace) -> int:
             hint="run 'familiar list conjurings' to see available options",
         )
     write_instruction(repo_root, args.agent, system)
+    if getattr(args, "save_subagent", False):
+        subagent_name = getattr(args, "subagent_name", None) or "_".join(
+            args.conjurings
+        )
+        subagent_path = write_subagent(
+            repo_root, args.agent, args.conjurings, subagent_name, system
+        )
+        print(f"wrote subagent: {subagent_path}")
     print(f"wrote instructions for {args.agent}")
     return EXIT_SUCCESS
 
@@ -157,6 +264,14 @@ def cmd_invoke(args: argparse.Namespace) -> int:
         print(prompt)
         return EXIT_SUCCESS
 
+    if getattr(args, "save_skill", False):
+        skill_name = getattr(args, "skill_name", None) or args.invocation
+        skill_path = write_skill(
+            repo_root, args.agent, args.invocation, skill_name, prompt
+        )
+        print(f"wrote skill: {skill_path}")
+        return EXIT_SUCCESS
+
     target_dir = repo_root
     if args.worktree:
         target_dir = create_worktree(repo_root)
@@ -168,8 +283,11 @@ def cmd_invoke(args: argparse.Namespace) -> int:
             instr_file = repo_root / agent.output_file
             if instr_file.exists():
                 shutil.copy2(instr_file, target_dir / agent.output_file)
-        except (OSError, KeyError):
-            pass
+        except (OSError, KeyError) as exc:
+            warnings.warn(
+                f"failed to copy instruction file into worktree: {exc}",
+                stacklevel=2,
+            )
 
     try:
         rc = run_agent(
@@ -181,7 +299,7 @@ def cmd_invoke(args: argparse.Namespace) -> int:
         return rc
     except Exception:
         if args.worktree:
-            print(f"\nworktree remains at: {target_dir}")
+            _remove_worktree(repo_root, target_dir)
         raise
 
 
@@ -267,6 +385,11 @@ def main() -> None:
         "  familiar lint                        # validate prompts\n",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {version('familiar-cli')}",
+    )
     parser.add_argument(
         "--debug", action="store_true", help="show full traceback on error"
     )
@@ -285,6 +408,15 @@ def main() -> None:
         "conjurings", nargs="+", help="conjuring names, e.g. rust infra sec"
     )
     conjure.add_argument("--into", help="target repo path (default: current directory)")
+    conjure.add_argument(
+        "--save-subagent",
+        action="store_true",
+        help="write composed conjurings as a reusable subagent",
+    )
+    conjure.add_argument(
+        "--subagent-name",
+        help="override subagent name (default: joined conjuring names)",
+    )
     conjure.set_defaults(func=cmd_conjure)
 
     invoke = sub.add_parser(
@@ -308,6 +440,15 @@ def main() -> None:
     invoke.add_argument(
         "--worktree", action="store_true", help="run in a separate git worktree"
     )
+    invoke.add_argument(
+        "--save-skill",
+        action="store_true",
+        help="write rendered invocation as a skill and exit",
+    )
+    invoke.add_argument(
+        "--skill-name",
+        help="override skill name (default: invocation name)",
+    )
     invoke.add_argument("--kv", nargs="*", help="named arguments as key=value pairs")
     invoke.add_argument(
         "inv_args", nargs="*", help="positional arguments for the invocation"

{familiar_cli-0.3.1 → familiar_cli-0.5.0}/src/familiar/lint.py

@@ -3,12 +3,12 @@
 from __future__ import annotations
 
 import re
-import warnings
 from dataclasses import dataclass
-from importlib.metadata import entry_points
 from pathlib import Path
 from typing import Callable, Literal
 
+from ._plugins import load_plugins
+
 from .render import _SNIPPET_INCLUDE, NotFoundError, list_items, load_snippet, load_text
 
 
@@ -202,27 +202,12 @@ def load_linters(kind: Literal["conjurings", "invocations"]) -> list[LinterFunc]
     Returns:
         List of linter functions from plugins.
     """
-    linters: list[LinterFunc] = []
-    group = f"familiar.linters.{kind}"
-    eps = entry_points(group=group)
-
-    for ep in eps:
-        try:
-            func = ep.load()
-            if not callable(func):
-                warnings.warn(
-                    f"linter plugin '{ep.name}': not callable",
-                    stacklevel=2,
-                )
-                continue
-            linters.append(func)
-        except Exception as e:
-            warnings.warn(
-                f"failed to load linter plugin '{ep.name}': {e}",
-                stacklevel=2,
-            )
-
-    return linters
+    return load_plugins(
+        f"familiar.linters.{kind}",
+        callable,
+        label="linter plugin",
+        invalid_msg="not callable",
+    )
 
 
 def lint_snippet_references(

{familiar_cli-0.3.1 → familiar_cli-0.5.0}/src/familiar/render.py

@@ -118,71 +118,85 @@ def _walk_traversable(root: Traversable, prefix: str = "") -> list[tuple[str, st
     return items
 
 
-def list_snippets(repo_root: Path) -> list[tuple[str, str, bool]]:
-    """List available snippets.
-
-    Returns list of (path, first_line, is_local) tuples, sorted by path.
+def _list_resources(
+    repo_root: Path,
+    pkg: str,
+    local_subdir: str,
+    *,
+    recursive: bool = False,
+    suffix: str = "",
+) -> list[tuple[str, str, bool]]:
+    """List resources from package data and local overrides.
+
+    Items from local ``.familiar/{local_subdir}/`` override package builtins.
+
+    Args:
+        repo_root: Repository root path.
+        pkg: Package name to scan for builtins.
+        local_subdir: Subdirectory name under ``.familiar/`` for local overrides.
+        recursive: If True, scan recursively (for nested resources like snippets).
+        suffix: File suffix filter (e.g. ``".md"``). Empty string matches all files.
+
+    Returns:
+        Sorted list of ``(key, first_line, is_local)`` tuples.
     """
     items: dict[str, tuple[str, bool]] = {}
 
-    # built-ins
+    # built-in resources from package data
     try:
-        pkg_root = resources.files("familiar.data.snippets")
-        for rel, first_line in _walk_traversable(pkg_root):
-            items[rel] = (first_line, False)
+        pkg_root = resources.files(pkg)
+        if recursive:
+            for rel, first_line in _walk_traversable(pkg_root):
+                items[rel] = (first_line, False)
+        else:
+            for item in pkg_root.iterdir():
+                if suffix and not item.name.endswith(suffix):
+                    continue
+                if item.name.startswith("_"):
+                    continue
+                key = item.name[: -len(suffix)] if suffix else item.name
+                content = item.read_text(encoding="utf-8")
+                first_line = content.split("\n", 1)[0].strip()
+                items[key] = (first_line, False)
     except (FileNotFoundError, TypeError, ModuleNotFoundError):
         pass
 
     # local overrides
-    local_dir = repo_root / ".familiar" / "snippets"
+    local_dir = repo_root / ".familiar" / local_subdir
     if local_dir.is_dir():
-        for f in sorted(local_dir.rglob("*")):
-            if f.is_file() and not f.name.startswith("_"):
-                rel = str(f.relative_to(local_dir))
-                content = f.read_text(encoding="utf-8")
-                first_line = content.split("\n", 1)[0].strip()
-                items[rel] = (first_line, True)
+        files = (
+            sorted(local_dir.rglob("*")) if recursive else local_dir.glob(f"*{suffix}")
+        )
+        for f in files:
+            if not f.is_file() or f.name.startswith("_"):
+                continue
+            key = str(f.relative_to(local_dir)) if recursive else f.stem
+            content = f.read_text(encoding="utf-8")
+            first_line = content.split("\n", 1)[0].strip()
+            items[key] = (first_line, True)
 
     return [
-        (path, first_line, is_local)
-        for path, (first_line, is_local) in sorted(items.items())
+        (key, first_line, is_local)
+        for key, (first_line, is_local) in sorted(items.items())
     ]
 
 
-def list_items(repo_root: Path, kind: str) -> list[tuple[str, str, bool]]:
-    """List available conjurings or invocations.
+def list_snippets(repo_root: Path) -> list[tuple[str, str, bool]]:
+    """List available snippets.
 
-    Returns list of (name, first_line, is_local) tuples, sorted by name.
+    Returns list of (path, first_line, is_local) tuples, sorted by path.
     """
-    items: dict[str, tuple[str, bool]] = {}
+    return _list_resources(
+        repo_root, "familiar.data.snippets", "snippets", recursive=True
+    )
 
-    # built-ins
-    pkg = f"familiar.data.{kind}"
-    try:
-        pkg_files = resources.files(pkg)
-        for item in pkg_files.iterdir():
-            if item.name.endswith(".md") and not item.name.startswith("_"):
-                name = item.name[:-3]
-                content = item.read_text(encoding="utf-8")
-                first_line = content.split("\n", 1)[0].strip()
-                items[name] = (first_line, False)
-    except (FileNotFoundError, TypeError):
-        pass
 
-    # local overrides
-    local_dir = repo_root / ".familiar" / kind
-    if local_dir.is_dir():
-        for f in local_dir.glob("*.md"):
-            if not f.name.startswith("_"):
-                name = f.stem
-                content = f.read_text(encoding="utf-8")
-                first_line = content.split("\n", 1)[0].strip()
-                items[name] = (first_line, True)
+def list_items(repo_root: Path, kind: str) -> list[tuple[str, str, bool]]:
+    """List available conjurings or invocations.
 
-    return [
-        (name, first_line, is_local)
-        for name, (first_line, is_local) in sorted(items.items())
-    ]
+    Returns list of (name, first_line, is_local) tuples, sorted by name.
+    """
+    return _list_resources(repo_root, f"familiar.data.{kind}", kind, suffix=".md")
 
 
 def compose_system(repo_root: Path, conjurings: list[str]) -> str:

{familiar_cli-0.3.1 → familiar_cli-0.5.0/src/familiar_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: familiar-cli
-Version: 0.3.1
+Version: 0.5.0
 Summary: compose and invoke ai agent prompts from reusable templates
 Author-email: cyberwitchery lab <contact@cyberwitchery.com>
 License-Expression: MIT
@@ -66,6 +66,20 @@ conjure conjurings to create system instructions for an agent:
 familiar conjure codex rust infra sec
 ```
 
+save composed conjurings as a reusable subagent:
+
+```bash
+familiar conjure claude python sec --save-subagent
+familiar conjure codex rust infra --save-subagent --subagent-name ship_ops
+```
+
+save an invocation as a reusable skill:
+
+```bash
+familiar invoke claude code-review --save-skill
+familiar invoke codex refactor src/foo.py --save-skill --skill-name cleanup_refactor
+```
+
 invoke an action prompt:
 
 ```bash

{familiar_cli-0.3.1 → familiar_cli-0.5.0}/src/familiar_cli.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 pyproject.toml
 readme.md
 src/familiar/__init__.py
+src/familiar/_plugins.py
 src/familiar/agents.py
 src/familiar/cli.py
 src/familiar/lint.py

{familiar_cli-0.3.1 → familiar_cli-0.5.0}/tests/test_agents.py

@@ -68,7 +68,7 @@ class TestPluginLoadErrors:
         mock_ep.name = "invalid"
         mock_ep.load.return_value = str  # not an Agent subclass
 
-        with patch("familiar.agents.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="not a valid Agent subclass"):
                 agents = load_agents()
             assert "invalid" not in agents
@@ -79,7 +79,7 @@ class TestPluginLoadErrors:
         mock_ep.name = "broken"
         mock_ep.load.side_effect = ImportError("module not found")
 
-        with patch("familiar.agents.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="failed to load"):
                 agents = load_agents()
             assert "broken" not in agents
@@ -101,7 +101,7 @@ class TestPluginLoadErrors:
         mock_ep.name = "bad"
         mock_ep.load.return_value = BadAgent
 
-        with patch("familiar.agents.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="failed to load"):
                 agents = load_agents()
             assert "bad" not in agents
@@ -118,6 +118,24 @@ class TestCodexAgent:
         agent = CodexAgent()
         assert agent.output_file == "AGENTS.md"
 
+    def test_supports_skills(self):
+        agent = CodexAgent()
+        assert agent.supports_skills() is True
+
+    def test_skill_path(self, tmp_path):
+        agent = CodexAgent()
+        path = agent.skill_path(tmp_path, "refactor")
+        assert path == tmp_path / ".codex" / "skills" / "refactor" / "SKILL.md"
+
+    def test_supports_subagents(self):
+        agent = CodexAgent()
+        assert agent.supports_subagents() is True
+
+    def test_subagent_path(self, tmp_path):
+        agent = CodexAgent()
+        path = agent.subagent_path(tmp_path, "python_sec")
+        assert path == tmp_path / ".codex" / "subagents" / "python_sec" / "AGENT.md"
+
     def test_run_headless(self, tmp_path):
         agent = CodexAgent()
         mock_result = MagicMock()
@@ -173,6 +191,24 @@ class TestClaudeAgent:
         agent = ClaudeAgent()
         assert agent.output_file == "CLAUDE.md"
 
+    def test_supports_skills(self):
+        agent = ClaudeAgent()
+        assert agent.supports_skills() is True
+
+    def test_skill_path(self, tmp_path):
+        agent = ClaudeAgent()
+        path = agent.skill_path(tmp_path, "review")
+        assert path == tmp_path / ".claude" / "skills" / "review" / "SKILL.md"
+
+    def test_supports_subagents(self):
+        agent = ClaudeAgent()
+        assert agent.supports_subagents() is True
+
+    def test_subagent_path(self, tmp_path):
+        agent = ClaudeAgent()
+        path = agent.subagent_path(tmp_path, "python_sec")
+        assert path == tmp_path / ".claude" / "subagents" / "python_sec" / "AGENT.md"
+
     def test_run_headless(self, tmp_path):
         agent = ClaudeAgent()
 

{familiar_cli-0.3.1 → familiar_cli-0.5.0}/tests/test_cli.py

@@ -13,6 +13,7 @@ from familiar.cli import (
     write_instruction,
     parse_kv,
     run_agent,
+    main,
     cmd_conjure,
     cmd_invoke,
     cmd_list,
@@ -21,6 +22,19 @@ from familiar.cli import (
 )
 
 
+class TestVersion:
+    """tests for --version flag."""
+
+    def test_version_prints_and_exits(self, capsys):
+        with pytest.raises(SystemExit, match="0"):
+            with patch("sys.argv", ["familiar", "--version"]):
+                main()
+        captured = capsys.readouterr()
+        assert "familiar" in captured.out
+        # version string should look like a semver
+        assert any(c.isdigit() for c in captured.out)
+
+
 class TestCreateWorktree:
     """tests for git worktree creation."""
 
@@ -132,6 +146,8 @@ class TestCmdConjure:
             agent="claude",
             conjurings=["python"],
             into=str(tmp_path),
+            save_subagent=False,
+            subagent_name=None,
         )
         result = cmd_conjure(args)
         assert result == 0
@@ -144,10 +160,55 @@ class TestCmdConjure:
             agent="claude",
             conjurings=["nonexistent"],
             into=str(tmp_path),
+            save_subagent=False,
+            subagent_name=None,
         )
         with pytest.raises(CliError, match="unknown conjuring"):
             cmd_conjure(args)
 
+    def test_writes_subagent_for_claude(self, tmp_path):
+        args = argparse.Namespace(
+            agent="claude",
+            conjurings=["python", "sec"],
+            into=str(tmp_path),
+            save_subagent=True,
+            subagent_name=None,
+        )
+        result = cmd_conjure(args)
+        assert result == 0
+        subagent = tmp_path / ".claude" / "subagents" / "python_sec" / "AGENT.md"
+        assert subagent.exists()
+        content = subagent.read_text()
+        assert "conjurings: python, sec" in content
+        assert "agent: claude" in content
+
+    def test_writes_subagent_for_codex_with_custom_name(self, tmp_path):
+        args = argparse.Namespace(
+            agent="codex",
+            conjurings=["rust", "infra"],
+            into=str(tmp_path),
+            save_subagent=True,
+            subagent_name="ship_ops",
+        )
+        result = cmd_conjure(args)
+        assert result == 0
+        subagent = tmp_path / ".codex" / "subagents" / "ship_ops" / "AGENT.md"
+        assert subagent.exists()
+        content = subagent.read_text()
+        assert "conjurings: rust, infra" in content
+        assert "agent: codex" in content
+
+    def test_invalid_subagent_name_raises(self, tmp_path):
+        args = argparse.Namespace(
+            agent="claude",
+            conjurings=["python"],
+            into=str(tmp_path),
+            save_subagent=True,
+            subagent_name="Not Valid",
+        )
+        with pytest.raises(CliError, match="invalid subagent name"):
+            cmd_conjure(args)
+
 
 class TestCmdInvoke:
     """tests for invoke command."""
@@ -164,6 +225,8 @@ class TestCmdInvoke:
                 kv=None,
                 inv_args=["some code"],
                 worktree=False,
+                save_skill=False,
+                skill_name=None,
             )
             result = cmd_invoke(args)
             assert result == 0
@@ -183,6 +246,8 @@ class TestCmdInvoke:
             kv=None,
             inv_args=[],
             worktree=False,
+            save_skill=False,
+            skill_name=None,
         )
         with pytest.raises(CliError, match="unknown invocation"):
             cmd_invoke(args)
@@ -204,6 +269,8 @@ class TestCmdInvoke:
                 kv=["mykey=myvalue"],
                 inv_args=[],
                 worktree=False,
+                save_skill=False,
+                skill_name=None,
             )
             cmd_invoke(args)
             prompt = mock_run.call_args[0][2]
@@ -220,6 +287,8 @@ class TestCmdInvoke:
             kv=None,
             inv_args=["some code"],
             worktree=False,
+            save_skill=False,
+            skill_name=None,
         )
         result = cmd_invoke(args)
         assert result == 0
@@ -238,6 +307,8 @@ class TestCmdInvoke:
                 kv=None,
                 inv_args=[],
                 worktree=False,
+                save_skill=False,
+                skill_name=None,
             )
             cmd_invoke(args)
             mock_run.assert_not_called()
@@ -261,6 +332,8 @@ class TestCmdInvoke:
                         kv=None,
                         inv_args=[],
                         worktree=True,
+                        save_skill=False,
+                        skill_name=None,
                     )
                     result = cmd_invoke(args)
                     assert result == 0
@@ -270,6 +343,92 @@ class TestCmdInvoke:
                     # Check that instruction file was copied
                     mock_copy.assert_called_once()
 
+    def test_invoke_worktree_cleaned_up_on_error(self, tmp_path):
+        with patch("familiar.cli.create_worktree", return_value=tmp_path / "wt"):
+            with patch("familiar.cli.run_agent", side_effect=RuntimeError("boom")):
+                with patch("familiar.cli._remove_worktree") as mock_remove:
+                    args = argparse.Namespace(
+                        agent="claude",
+                        invocation="explain",
+                        into=str(tmp_path),
+                        headless=True,
+                        auto=False,
+                        dry_run=False,
+                        kv=None,
+                        inv_args=[],
+                        worktree=True,
+                        save_skill=False,
+                        skill_name=None,
+                    )
+                    with pytest.raises(RuntimeError, match="boom"):
+                        cmd_invoke(args)
+                    mock_remove.assert_called_once()
+
+    def test_invoke_save_skill_claude(self, tmp_path):
+        with patch("familiar.cli.run_agent") as mock_run:
+            args = argparse.Namespace(
+                agent="claude",
+                invocation="explain",
+                into=str(tmp_path),
+                headless=True,
+                auto=False,
+                dry_run=False,
+                kv=None,
+                inv_args=["some code"],
+                worktree=False,
+                save_skill=True,
+                skill_name=None,
+            )
+            result = cmd_invoke(args)
+            assert result == 0
+            skill = tmp_path / ".claude" / "skills" / "explain" / "SKILL.md"
+            assert skill.exists()
+            content = skill.read_text()
+            assert "invocation: explain" in content
+            assert "agent: claude" in content
+            mock_run.assert_not_called()
+
+    def test_invoke_save_skill_codex_custom_name(self, tmp_path):
+        with patch("familiar.cli.run_agent") as mock_run:
+            args = argparse.Namespace(
+                agent="codex",
+                invocation="refactor",
+                into=str(tmp_path),
+                headless=True,
+                auto=False,
+                dry_run=False,
+                kv=None,
+                inv_args=["src/foo.py"],
+                worktree=False,
+                save_skill=True,
+                skill_name="cleanup_refactor",
+            )
+            result = cmd_invoke(args)
+            assert result == 0
+            skill = tmp_path / ".codex" / "skills" / "cleanup_refactor" / "SKILL.md"
+            assert skill.exists()
+            content = skill.read_text()
+            assert "invocation: refactor" in content
+            assert "agent: codex" in content
+            mock_run.assert_not_called()
+
+    def test_invoke_save_skill_invalid_name(self, tmp_path):
+        args = argparse.Namespace(
+            agent="claude",
+            invocation="explain",
+            into=str(tmp_path),
+            headless=True,
+            auto=False,
+            dry_run=False,
+            kv=None,
+            inv_args=["some code"],
+            worktree=False,
+            save_skill=True,
+            skill_name="Not Valid",
+        )
+        with pytest.raises(CliError, match="invalid skill name"):
+            cmd_invoke(args)
+
 
 class TestCmdList:
     """tests for list command."""

{familiar_cli-0.3.1 → familiar_cli-0.5.0}/tests/test_lint.py

@@ -225,7 +225,7 @@ class TestLinterPlugins:
         mock_ep.name = "invalid"
         mock_ep.load.return_value = "not a function"
 
-        with patch("familiar.lint.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="not callable"):
                 linters = load_linters("conjurings")
             assert len(linters) == 0
@@ -236,7 +236,7 @@ class TestLinterPlugins:
         mock_ep.name = "broken"
         mock_ep.load.side_effect = ImportError("module not found")
 
-        with patch("familiar.lint.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="failed to load"):
                 linters = load_linters("conjurings")
             assert len(linters) == 0
@@ -258,7 +258,7 @@ class TestLinterPlugins:
         templates.mkdir(parents=True)
         (templates / "mytemplate.md").write_text("# test")
 
-        with patch("familiar.lint.entry_points") as mock_entry_points:
+        with patch("familiar._plugins.entry_points") as mock_entry_points:
             # Return our mock for templates, empty for invocations
             def ep_side_effect(group):
                 if group == "familiar.linters.conjurings":
@@ -287,7 +287,7 @@ class TestLinterPlugins:
         templates.mkdir(parents=True)
         (templates / "test.md").write_text("# test")
 
-        with patch("familiar.lint.entry_points") as mock_entry_points:
+        with patch("familiar._plugins.entry_points") as mock_entry_points:
 
             def ep_side_effect(group):
                 if group == "familiar.linters.conjurings":

{familiar_cli-0.3.1 → familiar_cli-0.5.0}/tests/test_render.py

@@ -121,6 +121,34 @@ class TestComposeSystem:
         # verify order: core, then conjurings in order
         assert system == "CORE\n\nFIRST\n\nSECOND"
 
+    def test_compose_core_only(self, tmp_path):
+        templates = tmp_path / ".familiar" / "conjurings"
+        templates.mkdir(parents=True)
+        (templates / "core.md").write_text("CORE")
+
+        system = compose_system(tmp_path, [])
+        assert system == "CORE"
+
+    def test_compose_multiple_conjurings(self, tmp_path):
+        templates = tmp_path / ".familiar" / "conjurings"
+        templates.mkdir(parents=True)
+        (templates / "core.md").write_text("CORE")
+        (templates / "a.md").write_text("A")
+        (templates / "b.md").write_text("B")
+        (templates / "c.md").write_text("C")
+
+        system = compose_system(tmp_path, ["a", "b", "c"])
+        assert system == "CORE\n\nA\n\nB\n\nC"
+
+    def test_compose_strips_whitespace(self, tmp_path):
+        templates = tmp_path / ".familiar" / "conjurings"
+        templates.mkdir(parents=True)
+        (templates / "core.md").write_text("  CORE  \n")
+        (templates / "pad.md").write_text("\n  PAD  \n\n")
+
+        system = compose_system(tmp_path, ["pad"])
+        assert system == "CORE\n\nPAD"
+
     def test_compose_missing_profile_raises(self, tmp_path):
         with pytest.raises(NotFoundError, match="unknown conjuring"):
             compose_system(tmp_path, ["nonexistent"])
@@ -137,6 +165,36 @@ class TestRenderInvocation:
         result = render_invocation(tmp_path, "greet", ["world"], {"style": "friendly"})
         assert result == "hello world, friendly"
 
+    def test_render_with_snippet_and_args(self, tmp_path):
+        snippets = tmp_path / ".familiar" / "snippets" / "test"
+        snippets.mkdir(parents=True)
+        (snippets / "header.txt").write_text("== $1 ==")
+
+        invocations = tmp_path / ".familiar" / "invocations"
+        invocations.mkdir(parents=True)
+        (invocations / "demo.md").write_text(
+            "{{> snippet:test/header.txt}}\nbody: {{mode}}"
+        )
+
+        result = render_invocation(tmp_path, "demo", ["title"], {"mode": "fast"})
+        assert result == "== title ==\nbody: fast"
+
+    def test_render_no_args(self, tmp_path):
+        invocations = tmp_path / ".familiar" / "invocations"
+        invocations.mkdir(parents=True)
+        (invocations / "plain.md").write_text("no placeholders here")
+
+        result = render_invocation(tmp_path, "plain", [], {})
+        assert result == "no placeholders here"
+
+    def test_render_arguments_placeholder(self, tmp_path):
+        invocations = tmp_path / ".familiar" / "invocations"
+        invocations.mkdir(parents=True)
+        (invocations / "all.md").write_text("run $ARGUMENTS")
+
+        result = render_invocation(tmp_path, "all", ["a", "b", "c"], {})
+        assert result == "run a b c"
+
     def test_render_missing_invocation_raises(self, tmp_path):
         with pytest.raises(NotFoundError, match="unknown invocation"):
             render_invocation(tmp_path, "nonexistent", [], {})
@@ -259,6 +317,15 @@ class TestResolveIncludes:
         with pytest.raises(NotFoundError, match="unknown snippet"):
             resolve_includes(tmp_path, text)
 
+    def test_nonexistent_among_valid_raises(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "good.txt").write_text("ok")
+
+        text = "{{> snippet:test/good.txt}} {{> snippet:test/missing.txt}}"
+        with pytest.raises(NotFoundError, match="unknown snippet"):
+            resolve_includes(tmp_path, text)
+
     def test_include_before_substitute(self, tmp_path):
         """Include resolution happens before placeholder substitution."""
         snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
@@ -325,3 +392,25 @@ class TestListSnippets:
         _, first_line, is_local = custom_items[0]
         assert is_local is True
         assert first_line == "first line here"
+
+    def test_local_override_preserves_other_builtins(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "python"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "pyproject.toml").write_text("custom")
+
+        items = list_snippets(tmp_path)
+        lookup = {p: (f, loc) for p, f, loc in items}
+        assert lookup["python/pyproject.toml"][1] is True
+        assert "rust/Cargo.toml" in lookup
+        assert lookup["rust/Cargo.toml"][1] is False
+
+    def test_local_underscore_files_excluded(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "_hidden.txt").write_text("should not appear")
+        (snippet_dir / "visible.txt").write_text("should appear")
+
+        items = list_snippets(tmp_path)
+        paths = [p for p, _, _ in items]
+        assert "test/visible.txt" in paths
+        assert "test/_hidden.txt" not in paths