Merge pull request #131 from kalibr-ai/fix/rebase-pr127-templates

feat: coding agent context templates (CLAUDE.md + .cursorrules)

Author: devonakelley

README.md

@@ -58,6 +58,21 @@ response = router.completion(
 )
 ```
 
+## Coding Agent Setup
+
+If you're using Claude Code, Cursor, Windsurf, or any coding agent to build with Kalibr, add the appropriate context file to your project so the agent generates Router-based code by default.
+
+**Claude Code / Codex / OpenClaw:**
+Copy [templates/CLAUDE.md](templates/CLAUDE.md) to your project root as `CLAUDE.md`
+
+**Cursor / Windsurf:**
+Copy [templates/.cursorrules](templates/.cursorrules) to your project root as `.cursorrules`
+
+Once added, your coding agent will automatically:
+- Use `Router` instead of raw LLM clients
+- Always put `import kalibr` first
+- Include outcome reporting in every agent it builds
+
 ## Agent Starter Template
 
 Need a production-ready agent scaffold with Kalibr already wired in?
@@ -72,8 +87,7 @@ pip install -r requirements.txt
 python agent.py
 ```
 
-Includes  with Router wired in,  and  for coding agents, , and . Routes between  and  out of the box.
-
+Includes Router wired in, CLAUDE.md and .cursorrules for coding agents, and routes between gpt-4o-mini and claude-sonnet out of the box.
 
 ## Multimodal Routing
 

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

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