familiar-cli 0.0.1__tar.gz

familiar_cli-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cyberwitchery labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

familiar_cli-0.0.1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: familiar-cli
+Version: 0.0.1
+Summary: compose and invoke ai agent prompts from reusable templates
+Author-email: cyberwitchery labs <contact@cyberwitchery.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cyberwitchery/familiar
+Project-URL: Repository, https://github.com/cyberwitchery/familiar
+Keywords: ai,agents,prompts,cli,codex,claude
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# familiar
+
+compose and invoke ai agent prompts from reusable templates.
+
+ships with a standard set of templates and invocations, or bring your own (mine are
+very much wip).
+
+## installation
+
+```
+pip install familiar-cli
+```
+
+## usage
+
+conjure profiles to create system instructions for an agent:
+
+```
+familiar conjure codex rust infra sec
+```
+
+invoke an action prompt:
+
+```
+familiar invoke codex bootstrap-rust myapp lib 1.78 mit
+```
+
+## customization
+
+add your own templates and invocations by creating files in `.familiar/` in your repo:
+
+```
+.familiar/
+  templates/
+    myprofile.md      # new profile
+    rust.md           # override built-in
+  invocations/
+    my-task.md        # new invocation
+```
+
+local files take precedence over built-ins.
+
+### placeholders
+
+invocations support placeholders:
+- `$1`, `$2`, ... - positional arguments
+- `$ARGUMENTS` - all positional arguments joined
+- `{{key}}` - named arguments passed via `--kv key=value`
+
+## license
+
+mit

familiar_cli-0.0.1/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "familiar-cli"
+version = "0.0.1"
+description = "compose and invoke ai agent prompts from reusable templates"
+readme = "readme.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "cyberwitchery labs", email = "contact@cyberwitchery.com" }
+]
+keywords = ["ai", "agents", "prompts", "cli", "codex", "claude"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Code Generators",
+]
+
+[project.urls]
+Homepage = "https://github.com/cyberwitchery/familiar"
+Repository = "https://github.com/cyberwitchery/familiar"
+
+[project.scripts]
+familiar = "familiar.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[project.optional-dependencies]
+dev = ["ruff", "mypy", "pytest"]
+
+[tool.setuptools.package-data]
+"familiar.data.templates" = ["*.md"]
+"familiar.data.invocations" = ["*.md"]
+
+[tool.ruff]
+target-version = "py39"
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true

familiar_cli-0.0.1/readme.md

@@ -0,0 +1,52 @@
+# familiar
+
+compose and invoke ai agent prompts from reusable templates.
+
+ships with a standard set of templates and invocations, or bring your own (mine are
+very much wip).
+
+## installation
+
+```
+pip install familiar-cli
+```
+
+## usage
+
+conjure profiles to create system instructions for an agent:
+
+```
+familiar conjure codex rust infra sec
+```
+
+invoke an action prompt:
+
+```
+familiar invoke codex bootstrap-rust myapp lib 1.78 mit
+```
+
+## customization
+
+add your own templates and invocations by creating files in `.familiar/` in your repo:
+
+```
+.familiar/
+  templates/
+    myprofile.md      # new profile
+    rust.md           # override built-in
+  invocations/
+    my-task.md        # new invocation
+```
+
+local files take precedence over built-ins.
+
+### placeholders
+
+invocations support placeholders:
+- `$1`, `$2`, ... - positional arguments
+- `$ARGUMENTS` - all positional arguments joined
+- `{{key}}` - named arguments passed via `--kv key=value`
+
+## license
+
+mit

familiar_cli-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

familiar_cli-0.0.1/src/familiar/__init__.py

@@ -0,0 +1,9 @@
+"""familiar - compose and invoke ai agent prompts."""
+from importlib.metadata import version, PackageNotFoundError
+
+__all__ = ["agents", "render", "cli"]
+
+try:
+    __version__ = version("familiar-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"

familiar_cli-0.0.1/src/familiar/agents.py

@@ -0,0 +1,56 @@
+"""Agent implementations for familiar."""
+from __future__ import annotations
+
+import subprocess
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+
+class Agent(ABC):
+    """Base class for AI coding agents."""
+
+    name: str
+    output_file: str
+
+    @abstractmethod
+    def run(self, repo_root: Path, prompt: str, headless: bool) -> int:
+        """Run the agent with the given prompt."""
+
+
+class CodexAgent(Agent):
+    name = "codex"
+    output_file = "AGENTS.md"
+
+    def run(self, repo_root: Path, prompt: str, headless: bool) -> int:
+        if headless:
+            cmd = ["codex", "exec", "-C", str(repo_root), "-"]
+            proc = subprocess.run(cmd, input=prompt, text=True)
+            return proc.returncode
+        else:
+            cmd = ["codex", "-C", str(repo_root), prompt]
+            return subprocess.call(cmd)
+
+
+class ClaudeAgent(Agent):
+    name = "claude"
+    output_file = "CLAUDE.md"
+
+    def run(self, repo_root: Path, prompt: str, headless: bool) -> int:
+        if headless:
+            cmd = ["claude", "-p", prompt]
+        else:
+            cmd = ["claude", prompt]
+        return subprocess.call(cmd)
+
+
+AGENTS: dict[str, Agent] = {
+    "codex": CodexAgent(),
+    "claude": ClaudeAgent(),
+}
+
+
+def get_agent(name: str) -> Agent:
+    """Get an agent by name."""
+    if name not in AGENTS:
+        raise SystemExit(f"unknown agent: {name}")
+    return AGENTS[name]

familiar_cli-0.0.1/src/familiar/cli.py

@@ -0,0 +1,123 @@
+"""Command-line interface for familiar."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from .agents import AGENTS, get_agent
+from .render import compose, NotFoundError
+
+
+def find_repo_root(start: Path) -> Path:
+    cur = start.resolve()
+    for p in [cur] + list(cur.parents):
+        if (p / ".git").exists():
+            return p
+    return cur
+
+
+def ensure_fam_dir(repo_root: Path) -> Path:
+    d = repo_root / ".familiar"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def config_path(repo_root: Path, agent_name: str) -> Path:
+    return ensure_fam_dir(repo_root) / f"{agent_name}.json"
+
+
+def load_config(repo_root: Path, agent_name: str) -> dict[str, Any]:
+    p = config_path(repo_root, agent_name)
+    if p.exists():
+        cfg: dict[str, Any] = json.loads(p.read_text(encoding="utf-8"))
+        return cfg
+    return {}
+
+
+def save_config(repo_root: Path, agent_name: str, cfg: dict[str, Any]) -> None:
+    p = config_path(repo_root, agent_name)
+    p.write_text(json.dumps(cfg, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def write_instruction(repo_root: Path, agent_name: str, system: str) -> None:
+    agent = get_agent(agent_name)
+    (repo_root / agent.output_file).write_text(system.strip() + "\n", encoding="utf-8")
+
+
+def parse_kv(pairs: list[str]) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for p in pairs:
+        if '=' not in p:
+            raise SystemExit(f"expected key=value, got: {p}")
+        k, v = p.split('=', 1)
+        out[k.strip()] = v.strip()
+    return out
+
+
+def run_agent(repo_root: Path, agent_name: str, prompt: str, headless: bool) -> int:
+    agent = get_agent(agent_name)
+    try:
+        return agent.run(repo_root, prompt, headless)
+    except FileNotFoundError:
+        raise SystemExit(f"{agent_name} not found in PATH")
+
+
+def cmd_conjure(args: argparse.Namespace) -> int:
+    repo_root = find_repo_root(Path(args.into or os.getcwd()))
+    try:
+        system, _, _ = compose(repo_root, args.profiles, invocation="__noop__", args=[], kv={})
+    except NotFoundError as e:
+        raise SystemExit(str(e))
+    write_instruction(repo_root, args.agent, system)
+    save_config(repo_root, args.agent, {"profiles": args.profiles})
+    print(f"wrote instructions for {args.agent}")
+    return 0
+
+
+def cmd_invoke(args: argparse.Namespace) -> int:
+    repo_root = find_repo_root(Path(args.into or os.getcwd()))
+    cfg = load_config(repo_root, args.agent)
+    profiles = args.profiles if args.profiles is not None else cfg.get("profiles", [])
+    if not profiles:
+        print("warning: no profiles specified, using core only", file=sys.stderr)
+    kv = parse_kv(args.kv or [])
+    try:
+        _, _, full = compose(repo_root, profiles, args.invocation, args.inv_args or [], kv)
+    except NotFoundError as e:
+        raise SystemExit(str(e))
+    return run_agent(repo_root, args.agent, full, headless=args.headless)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="familiar", description="conjure and invoke familiars")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    agent_choices = list(AGENTS.keys())
+
+    conjure = sub.add_parser("conjure", help="compose system instructions for an agent")
+    conjure.add_argument("agent", choices=agent_choices)
+    conjure.add_argument("profiles", nargs="+", help="profile names, e.g. rust infra sec")
+    conjure.add_argument("--into", help="target repo path (default: current directory)")
+    conjure.set_defaults(func=cmd_conjure)
+
+    invoke = sub.add_parser("invoke", help="render an invocation and run the agent")
+    invoke.add_argument("agent", choices=agent_choices)
+    invoke.add_argument("invocation")
+    invoke.add_argument("--into", help="target repo path (default: current directory)")
+    invoke.add_argument("--headless", action="store_true", help="run without interactive UI")
+    invoke.add_argument("--profiles", nargs="*", default=None, help="override saved profiles")
+    invoke.add_argument("--kv", nargs="*", help="named arguments as key=value pairs")
+    invoke.add_argument("inv_args", nargs="*", help="positional arguments for the invocation")
+    invoke.set_defaults(func=cmd_invoke)
+
+    args = parser.parse_args()
+    rc = args.func(args)
+    raise SystemExit(rc)
+
+
+if __name__ == "__main__":
+    main()

familiar_cli-0.0.1/src/familiar/data/invocations/__noop__.md

@@ -0,0 +1 @@
+<!-- noop invocation for conjure command -->

familiar_cli-0.0.1/src/familiar/data/invocations/add-tests.md

@@ -0,0 +1,26 @@
+task: add tests.
+
+inputs
+- $ARGUMENTS (required): module path or symbol name.
+
+preconditions
+- if target is missing/unclear: ask what to test and where; stop.
+
+steps
+- identify the unit under test and its contract.
+- write tests for:
+  - happy path
+  - one edge case
+  - one failure mode
+- prefer table/parametrized tests.
+- avoid heavy mocking unless necessary; if you mock: explain why.
+- run the test suite.
+
+acceptance
+- tests are deterministic (no time/network/external dependencies).
+- tests are minimal and readable.
+- test command succeeds.
+
+output
+- unified diff.
+- exact test command to run.

familiar_cli-0.0.1/src/familiar/data/invocations/bootstrap-python.md

@@ -0,0 +1,20 @@
+bootstrap a new python project.
+
+arguments:
+- package name: $1
+- type: $2 (cli|lib)
+- python version: $3 (optional, default 3.9)
+- license: $4 (optional)
+
+actions:
+- create pyproject.toml with metadata.
+- set up src layout.
+- add a minimal readme.
+- configure ruff and mypy.
+- add a minimal test.
+
+acceptance:
+- `ruff check`, `mypy .`, and `pytest` succeed.
+
+output:
+- show diffs and exact commands.

familiar_cli-0.0.1/src/familiar/data/invocations/bootstrap-rust.md

@@ -0,0 +1,28 @@
+task: bootstrap a new rust crate.
+
+inputs (positional)
+- $1 crate_name (required)
+- $2 crate_type: bin|lib (required)
+- $3 msrv (optional; e.g. 1.78)
+- $4 license (optional; e.g. mit, apache-2.0)
+
+preconditions
+- if crate_name or crate_type is missing/invalid: ask and stop.
+- if target directory exists: ask whether to abort or integrate; do not overwrite by default.
+
+steps
+- create crate: `cargo new <crate_name> --<crate_type>`.
+- ensure project builds.
+- add README.md with: one-line purpose + quickstart commands.
+- if msrv provided: encode it (ask preferred mechanism if unclear; do not invent).
+- add minimal test if none exists.
+- run fmt/clippy/test.
+
+acceptance
+- `cargo fmt` succeeds.
+- `cargo clippy --all-targets --all-features -- -D warnings` succeeds.
+- `cargo test --all-features` succeeds.
+
+output
+- unified diff only for files changed/created.
+- verification commands (exact).

familiar_cli-0.0.1/src/familiar/data/invocations/code-review.md

@@ -0,0 +1,10 @@
+review: $ARGUMENTS
+
+actions:
+- check for correctness, clarity, and maintainability.
+- identify potential bugs or edge cases.
+- suggest improvements without over-engineering.
+
+output:
+- list issues by severity (high/medium/low).
+- include specific file:line references.

familiar_cli-0.0.1/src/familiar/data/invocations/explain.md

@@ -0,0 +1,9 @@
+explain: $ARGUMENTS
+
+actions:
+- identify the relevant code paths and data flow.
+- describe what it does, why, and how.
+- note any non-obvious behavior or edge cases.
+
+output:
+- concise explanation with references to specific files/lines.

familiar_cli-0.0.1/src/familiar/data/invocations/implement-feature.md

@@ -0,0 +1,26 @@
+task: implement a feature from a spec.
+
+inputs (named)
+- {{spec}} (required): file path in repo OR pasted spec text.
+
+preconditions
+- if spec is empty: ask for a file path or pasted spec; stop.
+- if spec is ambiguous or missing acceptance criteria: ask up to 5 clarifying questions; stop.
+
+steps
+- restate the spec in 1-2 sentences.
+- extract explicit acceptance criteria (bullets). if none: propose criteria and ask for confirmation; stop.
+- list files you will change (paths).
+- write failing tests first when feasible.
+- implement the smallest change that satisfies the criteria.
+- run format/lint/type/tests.
+
+acceptance
+- all existing tests pass.
+- new tests cover the main path + one edge case.
+- no new deps or public api changes unless explicitly approved.
+
+output
+- plan (restatement + file list).
+- unified diff.
+- verification commands.

familiar_cli-0.0.1/src/familiar/data/invocations/infra-change.md

@@ -0,0 +1,25 @@
+task: infrastructure change plan.
+
+inputs
+- $ARGUMENTS (required): desired change (what/why), target env (dev/prod), constraints.
+
+preconditions
+- if required info is missing (env, region, account, constraints): ask; stop.
+- do not propose or apply production changes without explicit approval.
+
+steps
+- list touched components and assumptions.
+- describe blast radius and failure modes.
+- propose rollout steps (staged) and rollback steps.
+- highlight least-privilege and exposure risks.
+- include verification commands (plan/dry-run/diff/apply checks).
+
+acceptance
+- plan is actionable, ordered, and includes rollback.
+- no broad permissions or public exposure without explicit justification.
+- diffs are minimal (only if asked to implement).
+
+output
+- plan (rollout + rollback).
+- diffs (only if asked).
+- verification commands.

familiar_cli-0.0.1/src/familiar/data/invocations/refactor.md

@@ -0,0 +1,14 @@
+refactor: $ARGUMENTS
+
+goals:
+- improve structure without changing behavior.
+- keep diffs minimal and reviewable.
+
+actions:
+- describe the current state and proposed changes.
+- list files you will touch.
+- implement in small steps.
+- ensure tests still pass.
+
+output:
+- show diffs and how to verify behavior is unchanged.

familiar_cli-0.0.1/src/familiar/data/invocations/security-review.md

@@ -0,0 +1,28 @@
+task: security review.
+
+inputs
+- $ARGUMENTS (optional): scope. if empty, infer from current diff/repo context.
+
+preconditions
+- if scope is unclear and no obvious target exists: ask what to review; stop.
+
+steps
+- identify trust boundaries and attacker-controlled inputs.
+- confirm authn/authz expectations.
+- check for:
+  - injection (sql, shell, template, path)
+  - unsafe deserialization / parsing
+  - secrets handling
+  - permissions / privilege escalation
+  - insecure defaults
+- produce a ranked list of issues.
+
+deliverables
+- findings ranked by severity (high/med/low) with concrete mitigations.
+- for each high item: smallest patch suggestion.
+- verification steps for each mitigation (tests/commands).
+
+output
+- findings (ranked bullets).
+- recommended changes (diff only if requested).
+- verification commands/tests.

familiar_cli-0.0.1/src/familiar/data/templates/core.md

@@ -0,0 +1,25 @@
+# agent core
+
+## goals
+- ship the smallest correct change.
+- keep existing conventions. no drive-by refactors.
+- be deterministic. no creativity unless asked.
+
+## hard rules
+- if required inputs are missing or ambiguous, ask before coding.
+- do not add dependencies, change public apis, or run destructive commands without explicit approval.
+- never output secrets. never suggest logging secrets.
+
+## workflow
+- restate the task in 1-2 sentences.
+- list the exact files you will change (paths).
+- if uncertainty remains: ask targeted questions (max 5).
+- implement in small steps.
+- after changes: run format + lint + tests (or state exactly why you cannot).
+- finish with a short verification plan.
+
+## output format
+- section: plan (task restatement + file list).
+- section: changes (unified diff).
+- section: verification (commands to run).
+- section: notes (only if needed; max 5 bullets).

familiar_cli-0.0.1/src/familiar/data/templates/infra.md

@@ -0,0 +1,23 @@
+# infra profile
+
+## discipline
+- plan first: describe change, blast radius, rollout, rollback.
+- never touch production without explicit confirmation.
+- minimize diffs; avoid churn in generated files.
+
+## safety rules
+- least privilege for iam/rbac/security groups.
+- do not open 0.0.0.0/0 unless explicitly required and documented.
+- pin versions where practical (providers, modules, images).
+- secrets: reference secret stores; do not inline credentials.
+
+## workflow
+- list touched components and assumptions.
+- propose staged rollout steps and rollback steps.
+- include verification commands (dry-run/plan/apply checks).
+- call out risks and mitigations.
+
+## output
+- section: plan (steps + rollback).
+- section: diffs (only if asked to implement).
+- section: verification (commands).

familiar_cli-0.0.1/src/familiar/data/templates/python.md

@@ -0,0 +1,24 @@
+# python profile
+
+## commands
+- format: ruff format
+- lint: ruff check
+- type: mypy .
+- test: pytest -q
+
+## rules
+- keep functions small; push complexity into pure helpers.
+- write tests for edge cases; prefer pytest parametrization.
+- do not widen public apis without explicit approval.
+- do not add new dependencies without explicit approval.
+- prefer explicit types at module boundaries.
+
+## workflow
+- follow existing project structure and naming.
+- add tests that fail before the fix/feature (when possible).
+- keep diffs minimal; avoid unrelated cleanup.
+- run format + lint + type + tests, or say exactly why you cannot.
+
+## output
+- show a unified diff.
+- list the exact commands to verify (ruff/mypy/pytest).

familiar_cli-0.0.1/src/familiar/data/templates/rust.md

@@ -0,0 +1,24 @@
+# rust profile
+
+## commands
+- format: cargo fmt
+- lint: cargo clippy --all-targets --all-features -- -d warnings
+- test: cargo test --all-features
+- build: cargo build --all-features
+
+## rules
+- do not introduce new crates unless you ask first.
+- avoid unsafe. if unavoidable: justify + minimize surface + add tests.
+- prefer explicit error types; do not swallow errors.
+- prefer small, composable functions; avoid clever macros.
+- do not change public apis without explicit approval.
+
+## workflow
+- locate existing patterns in the crate and follow them.
+- write or update tests first when feasible.
+- keep diffs minimal; avoid reformatting unrelated code.
+- ensure msrv/toolchain constraints are respected; ask if unknown.
+
+## output
+- show a unified diff.
+- list the exact cargo commands to verify (fmt/clippy/test).

familiar_cli-0.0.1/src/familiar/data/templates/sec.md

@@ -0,0 +1,24 @@
+# security profile
+
+## tasks
+- identify trust boundaries and attacker-controlled inputs.
+- confirm authn/authz expectations (who can do what).
+- look for injection risks, unsafe defaults, and privilege escalation.
+- check for secret leakage in logs, errors, traces, metrics.
+- validate inputs early; fail closed; secure defaults.
+
+## prohibitions
+- do not weaken tls/crypto settings.
+- do not add debug logging for tokens/headers/payloads with secrets.
+- do not suggest storing secrets in repo, env files, or plaintext config.
+- do not propose broad permissions (admin/*) as a shortcut.
+
+## deliverables
+- top risks with mitigations (bulleted, ranked).
+- smallest patch for the highest-risk item first (if implementation requested).
+- verification steps (tests/commands) for each mitigation.
+
+## output
+- section: findings (ranked bullets).
+- section: recommended changes (diffs if requested).
+- section: verification (commands/tests).

familiar_cli-0.0.1/src/familiar/render.py

@@ -0,0 +1,69 @@
+"""Render system and user prompts from templates and invocations."""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from importlib import resources
+
+_VALID_NAME = re.compile(r"^[a-z0-9_-]+$")
+
+
+class NotFoundError(Exception):
+    """Raised when a template or invocation is not found."""
+
+
+def load_text(repo_root: Path, kind: str, name: str) -> str:
+    """Load a template or invocation; local overrides in .familiar override package data."""
+    if not _VALID_NAME.match(name):
+        raise NotFoundError(f"invalid {kind.rstrip('s')} name: {name}")
+    override = repo_root / ".familiar" / kind / f"{name}.md"
+    if override.exists():
+        return override.read_text(encoding="utf-8")
+    pkg = f"familiar.data.{kind}"
+    try:
+        return (resources.files(pkg) / f"{name}.md").read_text(encoding="utf-8")
+    except (FileNotFoundError, TypeError):
+        # TypeError: some python versions raise this for missing resources
+        raise NotFoundError(f"unknown {kind.rstrip('s')}: {name}")
+
+
+def substitute(text: str, args: list[str], kv: dict[str, str]) -> str:
+    """Substitute $1, $2, ... $ARGUMENTS and {{key}} placeholders.
+
+    Note: positional args are substituted before kv args, so user-supplied
+    args containing {{foo}} could get expanded. This is low risk in practice.
+    """
+    missing: list[str] = []
+
+    def repl(m: re.Match[str]) -> str:
+        ident = m.group(1)
+        if ident == "ARGUMENTS":
+            return " ".join(args).strip()
+        if ident.isdigit():
+            idx = int(ident) - 1
+            if 0 <= idx < len(args):
+                return args[idx]
+            missing.append(f"${ident}")
+            return ""
+        return m.group(0)
+
+    text = re.sub(r"\$(ARGUMENTS|\d+)", repl, text)
+    if missing:
+        print(f"warning: missing arguments: {', '.join(missing)}", file=sys.stderr)
+    for k, v in kv.items():
+        text = text.replace(f"{{{{{k}}}}}", v)
+    return text
+
+
+def compose(repo_root: Path, profiles: list[str], invocation: str, args: list[str], kv: dict[str, str]) -> tuple[str, str, str]:
+    """Compose system and user sections from selected profiles and invocation."""
+    core = load_text(repo_root, "templates", "core").strip()
+    parts: list[str] = [core]
+    for p in profiles:
+        parts.append(load_text(repo_root, "templates", p).strip())
+    system = "\n\n".join(parts)
+    inv = load_text(repo_root, "invocations", invocation).strip()
+    user = substitute(inv, args, kv)
+    full = f"{system}\n\n---\n\n{user}\n"
+    return system, user, full

familiar_cli-0.0.1/src/familiar_cli.egg-info/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: familiar-cli
+Version: 0.0.1
+Summary: compose and invoke ai agent prompts from reusable templates
+Author-email: cyberwitchery labs <contact@cyberwitchery.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cyberwitchery/familiar
+Project-URL: Repository, https://github.com/cyberwitchery/familiar
+Keywords: ai,agents,prompts,cli,codex,claude
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# familiar
+
+compose and invoke ai agent prompts from reusable templates.
+
+ships with a standard set of templates and invocations, or bring your own (mine are
+very much wip).
+
+## installation
+
+```
+pip install familiar-cli
+```
+
+## usage
+
+conjure profiles to create system instructions for an agent:
+
+```
+familiar conjure codex rust infra sec
+```
+
+invoke an action prompt:
+
+```
+familiar invoke codex bootstrap-rust myapp lib 1.78 mit
+```
+
+## customization
+
+add your own templates and invocations by creating files in `.familiar/` in your repo:
+
+```
+.familiar/
+  templates/
+    myprofile.md      # new profile
+    rust.md           # override built-in
+  invocations/
+    my-task.md        # new invocation
+```
+
+local files take precedence over built-ins.
+
+### placeholders
+
+invocations support placeholders:
+- `$1`, `$2`, ... - positional arguments
+- `$ARGUMENTS` - all positional arguments joined
+- `{{key}}` - named arguments passed via `--kv key=value`
+
+## license
+
+mit

familiar_cli-0.0.1/src/familiar_cli.egg-info/SOURCES.txt

@@ -0,0 +1,28 @@
+LICENSE
+pyproject.toml
+readme.md
+src/familiar/__init__.py
+src/familiar/agents.py
+src/familiar/cli.py
+src/familiar/render.py
+src/familiar/data/invocations/__noop__.md
+src/familiar/data/invocations/add-tests.md
+src/familiar/data/invocations/bootstrap-python.md
+src/familiar/data/invocations/bootstrap-rust.md
+src/familiar/data/invocations/code-review.md
+src/familiar/data/invocations/explain.md
+src/familiar/data/invocations/implement-feature.md
+src/familiar/data/invocations/infra-change.md
+src/familiar/data/invocations/refactor.md
+src/familiar/data/invocations/security-review.md
+src/familiar/data/templates/core.md
+src/familiar/data/templates/infra.md
+src/familiar/data/templates/python.md
+src/familiar/data/templates/rust.md
+src/familiar/data/templates/sec.md
+src/familiar_cli.egg-info/PKG-INFO
+src/familiar_cli.egg-info/SOURCES.txt
+src/familiar_cli.egg-info/dependency_links.txt
+src/familiar_cli.egg-info/entry_points.txt
+src/familiar_cli.egg-info/requires.txt
+src/familiar_cli.egg-info/top_level.txt

familiar_cli-0.0.1/src/familiar_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

familiar_cli-0.0.1/src/familiar_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+familiar = familiar.cli:main

familiar_cli-0.0.1/src/familiar_cli.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+ruff
+mypy
+pytest

familiar_cli-0.0.1/src/familiar_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+familiar