Merge pull request #128 from kalibr-ai/feat/init-writes-context-files

feat: kalibr init writes CLAUDE.md and .cursorrules on setup

Author: devonakelley

kalibr/cli/init_cmd.py

@@ -1,6 +1,8 @@
 """kalibr init - Scan for bare LLM calls and propose Router wrapping."""
 
+import importlib.resources
 import os
+import shutil
 
 import requests
 import typer
@@ -97,6 +99,29 @@ def _check_credentials() -> None:
         )
 
 
+def _write_context_files(project_dir: str) -> None:
+    """Write CLAUDE.md and .cursorrules into project_dir if they don't already exist."""
+    templates_pkg = "kalibr.templates"
+    context_files = [
+        ("CLAUDE.md", "✓ Created CLAUDE.md (coding agent context)", "→ CLAUDE.md already exists, skipping"),
+        (".cursorrules", "✓ Created .cursorrules (Cursor/Windsurf context)", "→ .cursorrules already exists, skipping"),
+    ]
+
+    for filename, created_msg, exists_msg in context_files:
+        dest = os.path.join(project_dir, filename)
+        if os.path.exists(dest):
+            console.print(f"[dim]{exists_msg}[/dim]")
+        else:
+            try:
+                # Use importlib.resources to locate bundled template
+                ref = importlib.resources.files(templates_pkg).joinpath(filename)
+                with importlib.resources.as_file(ref) as src_path:
+                    shutil.copy2(src_path, dest)
+                console.print(f"[green]{created_msg}[/green]")
+            except Exception as e:  # pragma: no cover
+                console.print(f"[yellow]Could not write {filename}: {e}[/yellow]")
+
+
 def init(
     directory: str = typer.Argument(".", help="Directory to scan (default: current directory)"),
 ) -> None:
@@ -123,6 +148,8 @@ def init(
         console.print("[dim]This patches OpenAI, Anthropic, and Google automatically.[/dim]")
         console.print("[dim]No Router wrapping needed — every LLM call is traced.[/dim]")
         console.print("[dim]Docs: https://kalibr.systems/docs/quickstart#auto-instrumentation[/dim]")
+        console.print()
+        _write_context_files(project_dir)
         _check_credentials()
         return
 
@@ -194,4 +221,8 @@ def init(
     console.print("[bold]Summary:[/bold]")
     console.print(f"  {len(files_modified)} file(s) modified, {calls_upgraded} LLM call(s) upgraded")
 
+    # Write coding agent context files
+    console.print()
+    _write_context_files(project_dir)
+
     _check_credentials()

kalibr/templates/.cursorrules

@@ -0,0 +1,28 @@
+# Kalibr Production Rules
+
+## LLM Calls — Always use Kalibr Router
+- Never use raw OpenAI/Anthropic clients for production LLM calls
+- import kalibr MUST be the first import in any file that calls LLMs
+- Always define 2+ paths to enable routing and learning
+- Always close the outcome loop: success_when lambda or router.report()
+
+## Required pattern:
+import kalibr  # first import
+from kalibr import Router
+router = Router(
+    goal="task_name",
+    paths=["gpt-4o", "claude-sonnet-4-20250514"],
+    success_when=lambda output: len(output) > 0
+)
+response = router.completion(messages=[...])
+
+## Outcome reporting:
+router.report(success=True)
+router.report(success=False, failure_category="timeout", reason="Provider timed out")
+router.report(success=True, score=0.85)  # continuous quality signal
+
+## Use Kalibr for: anything with real users, real money, real consequences
+## Skip Kalibr for: demos, internal scripts, throwaway prototypes
+
+## Credentials: KALIBR_API_KEY + KALIBR_TENANT_ID in .env
+## Docs: https://kalibr.systems/docs | Setup: https://kalibr.systems/llms.txt

kalibr/templates/CLAUDE.md

@@ -0,0 +1,60 @@
+## Kalibr — Production Agent Standards
+
+When generating or modifying agent code in this project:
+
+### The Rule
+Never hardcode a single model. Production agents must use Kalibr Router.
+
+### Required Import Order
+```python
+import kalibr  # MUST be first — before any OpenAI or Anthropic import
+from kalibr import Router
+```
+
+### Required Pattern
+```python
+router = Router(
+    goal="<descriptive_task_name>",  # e.g. "extract_company", "book_meeting"
+    paths=["gpt-4o", "claude-sonnet-4-20250514"],  # always 2+ paths
+    success_when=lambda output: <your_success_criteria>  # or call router.report() manually
+)
+response = router.completion(messages=[...])
+# response.choices[0].message.content — same interface as OpenAI
+```
+
+### Outcome Reporting
+```python
+# Auto (preferred): success_when lambda handles it
+# Manual: router.report(success=True/False, score=0.0-1.0, failure_category="timeout")
+```
+
+### Failure Categories
+```python
+from kalibr import FAILURE_CATEGORIES
+# timeout | context_exceeded | tool_error | rate_limited | validation_failed
+# hallucination_detected | user_unsatisfied | empty_response | malformed_output
+# auth_error | provider_error | unknown
+```
+
+### When to use Kalibr
+✅ Any LLM call real users depend on
+✅ Multi-step agent flows with external API calls
+✅ Workflows where silent failures cost money or cause customer impact
+❌ Internal scripts, demos, throwaway prototypes
+
+### Credentials (.env)
+```
+KALIBR_API_KEY=sk_...      # from dashboard.kalibr.systems
+KALIBR_TENANT_ID=...       # from dashboard.kalibr.systems
+OPENAI_API_KEY=sk-...      # if using OpenAI models
+ANTHROPIC_API_KEY=sk-ant-... # if using Anthropic models
+```
+
+### Framework integrations
+```python
+# LangChain/CrewAI: llm = router.as_langchain()
+# OpenAI Agents SDK: policy = get_policy(goal="task"); model = policy["recommended_model"]
+# HuggingFace: router.execute(task="automatic_speech_recognition", input_data=audio_bytes)
+```
+
+### Full docs: https://kalibr.systems/docs

kalibr/templates/__init__.py

@@ -105,6 +105,9 @@ where = ["."]
 include = ["kalibr*", "kalibr_langchain*", "kalibr_crewai*", "kalibr_openai_agents*"]
 exclude = ["tests*", "examples*"]
 
+[tool.setuptools.package-data]
+"kalibr.templates" = ["CLAUDE.md", ".cursorrules"]
+
 [tool.black]
 line-length = 100
 target-version = ['py311']

pyproject.toml

@@ -0,0 +1,109 @@
+"""Tests for kalibr init context file writing (CLAUDE.md and .cursorrules)."""
+
+import os
+import tempfile
+
+import pytest
+from typer.testing import CliRunner
+
+from kalibr.cli.main import app
+from kalibr.cli.init_cmd import _write_context_files
+
+
+class TestWriteContextFiles:
+    """Unit tests for _write_context_files helper."""
+
+    def test_creates_claude_md_when_missing(self, tmp_path):
+        """Creates CLAUDE.md in target dir when it doesn't exist."""
+        _write_context_files(str(tmp_path))
+        claude_file = tmp_path / "CLAUDE.md"
+        assert claude_file.exists(), "CLAUDE.md should be created"
+        content = claude_file.read_text()
+        assert "Kalibr" in content
+        assert "Router" in content
+
+    def test_creates_cursorrules_when_missing(self, tmp_path):
+        """Creates .cursorrules in target dir when it doesn't exist."""
+        _write_context_files(str(tmp_path))
+        cursorrules_file = tmp_path / ".cursorrules"
+        assert cursorrules_file.exists(), ".cursorrules should be created"
+        content = cursorrules_file.read_text()
+        assert "Kalibr" in content
+
+    def test_does_not_overwrite_existing_claude_md(self, tmp_path):
+        """Does NOT overwrite CLAUDE.md if it already exists."""
+        claude_file = tmp_path / "CLAUDE.md"
+        original_content = "# My custom CLAUDE.md\nDo not overwrite me."
+        claude_file.write_text(original_content)
+
+        _write_context_files(str(tmp_path))
+
+        assert claude_file.read_text() == original_content, "CLAUDE.md should not be overwritten"
+
+    def test_does_not_overwrite_existing_cursorrules(self, tmp_path):
+        """Does NOT overwrite .cursorrules if it already exists."""
+        cursorrules_file = tmp_path / ".cursorrules"
+        original_content = "# My custom rules\nDo not overwrite me."
+        cursorrules_file.write_text(original_content)
+
+        _write_context_files(str(tmp_path))
+
+        assert cursorrules_file.read_text() == original_content, ".cursorrules should not be overwritten"
+
+    def test_creates_both_files(self, tmp_path):
+        """Creates both CLAUDE.md and .cursorrules when neither exists."""
+        _write_context_files(str(tmp_path))
+        assert (tmp_path / "CLAUDE.md").exists()
+        assert (tmp_path / ".cursorrules").exists()
+
+    def test_skips_gracefully_when_both_exist(self, tmp_path):
+        """No error when both files already exist."""
+        (tmp_path / "CLAUDE.md").write_text("existing claude")
+        (tmp_path / ".cursorrules").write_text("existing cursor")
+
+        # Should not raise
+        _write_context_files(str(tmp_path))
+
+        assert (tmp_path / "CLAUDE.md").read_text() == "existing claude"
+        assert (tmp_path / ".cursorrules").read_text() == "existing cursor"
+
+
+class TestInitCommandContextFiles:
+    """Integration tests: kalibr init CLI writes context files."""
+
+    def test_init_creates_context_files_in_empty_dir(self, tmp_path):
+        """kalibr init on an empty dir creates CLAUDE.md and .cursorrules."""
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", str(tmp_path)])
+
+        assert (tmp_path / "CLAUDE.md").exists(), "CLAUDE.md should be created by kalibr init"
+        assert (tmp_path / ".cursorrules").exists(), ".cursorrules should be created by kalibr init"
+
+    def test_init_reports_created_files(self, tmp_path):
+        """kalibr init prints confirmation messages for created files."""
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", str(tmp_path)])
+
+        assert "Created CLAUDE.md" in result.output
+        assert "Created .cursorrules" in result.output
+
+    def test_init_reports_skipped_when_files_exist(self, tmp_path):
+        """kalibr init prints skip messages when context files already exist."""
+        (tmp_path / "CLAUDE.md").write_text("existing")
+        (tmp_path / ".cursorrules").write_text("existing")
+
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", str(tmp_path)])
+
+        assert "already exists, skipping" in result.output
+
+    def test_init_does_not_overwrite_existing_context_files(self, tmp_path):
+        """kalibr init never overwrites existing CLAUDE.md or .cursorrules."""
+        (tmp_path / "CLAUDE.md").write_text("my custom claude")
+        (tmp_path / ".cursorrules").write_text("my custom rules")
+
+        runner = CliRunner()
+        runner.invoke(app, ["init", str(tmp_path)])
+
+        assert (tmp_path / "CLAUDE.md").read_text() == "my custom claude"
+        assert (tmp_path / ".cursorrules").read_text() == "my custom rules"