Add Claude Code skills and stop hook for documentation management

.claude/hooks/check-api-changes.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+# Stop hook: detect source file changes and prompt documentation review
+# Reads JSON from stdin to check for stop_hook_active flag
+
+INPUT=$(cat)
+
+# Infinite loop guard: if we're already in a stop hook session, exit silently
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  exit 0
+fi
+
+# Get all changed files (staged + unstaged)
+CHANGED_FILES=$(cd "$CLAUDE_PROJECT_DIR" && {
+  git diff --name-only 2>/dev/null
+  git diff --cached --name-only 2>/dev/null
+} | grep '\.kt$' | grep '^src/' | sort -u)
+
+# No source files changed — nothing to do
+if [ -z "$CHANGED_FILES" ]; then
+  exit 0
+fi
+
+FILE_LIST=$(echo "$CHANGED_FILES" | tr '\n' ', ' | sed 's/,$//')
+
+cat <<EOF
+{"decision": "block", "reason": "Source files were modified: ${FILE_LIST}. Before ending this session, check if any of these changes affect the public API. Search the documentation in /site/docs/ for references to the changed APIs and update any documentation that no longer matches the code. Use the /tone-of-voice skill for writing style guidelines."}
+EOF

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-api-changes.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/tone-of-voice.md

@@ -0,0 +1,49 @@
+# Documentation Tone of Voice
+
+Apply these tone guidelines when writing or reviewing documentation for the Aigentic documentation website in `/site`.
+
+## Key Characteristics
+
+### Conversational and Natural
+- Use everyday language rather than formal or academic phrasing
+- Write as if you're explaining concepts to a colleague
+- Avoid LLM-generated-sounding phrases like "crucial for effective" or "vital for optimal performance"
+
+### Direct and Clear
+- Get to the point without unnecessary embellishment
+- Use simple, active constructions: "This helps..." rather than "This is designed to facilitate..."
+- Choose straightforward words over complex alternatives
+
+### Practical and User-Focused
+- Focus on how features benefit the user
+- Emphasize practical outcomes rather than theoretical advantages
+- Frame explanations in terms of what users can accomplish
+
+### Approachable but Professional
+- Maintain technical accuracy while being accessible
+- Use a friendly tone without being overly casual
+- Avoid jargon when possible, but don't oversimplify technical concepts
+
+## Word Choice Examples
+
+| Instead of (Too Formal) | Use (Conversational) |
+|-------------------------|----------------------|
+| "crucial for effective" | "significantly improves" |
+| "vital for optimal" | "greatly enhances" |
+| "enables the construction of" | "helps create" |
+| "provides detailed context about" | "gives details about" |
+| "facilitates improved performance" | "makes your tools work better" |
+| "leads to enhanced outcomes" | "helps your agents work more effectively" |
+
+## Sentence Structure
+- Prefer shorter sentences with a clear subject-verb structure
+- Use bullet points for lists rather than complex, comma-separated sentences
+- Start with the benefit or main point, then explain details
+
+## Examples
+
+**Too formal/LLM-like:**
+"The description property in @AigenticParameter is crucial for effective LLM interactions, providing essential context that enables the model to make optimal decisions regarding tool utilization."
+
+**Conversational/Natural:**
+"The description property in @AigenticParameter helps improves LLM interactions. This description gives the LLM context about how and when to use your tools."

.claude/skills/update-site/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: update-site
+description: Audit and update the documentation site against the current codebase
+---
+
+# Update Site Documentation
+
+Perform a full audit of the Aigentic documentation site against the current codebase.
+
+## Instructions
+
+1. **Discover public API files**: Search `src/core/` for public Kotlin classes, interfaces, functions, and annotations that form the user-facing API. Focus on:
+   - DSL entry points and builder functions
+   - Data classes used as agent inputs/outputs
+   - Annotations (e.g., `@AigenticParameter`)
+   - Tool interfaces and implementations
+   - Outcome types and message types
+
+2. **Discover documentation files**: Search `site/docs/` for all documentation pages (`.md` and `.mdx` files).
+
+3. **Compare and identify drift**: For each documentation page, check whether:
+   - Function signatures match the current code
+   - Type names, parameter names, and return types are accurate
+   - Code examples compile against the current API
+   - Descriptions accurately reflect current behavior
+   - Imports in examples are correct
+
+4. **Update documentation**: Fix any discrepancies found. When updating:
+   - Use the `/tone-of-voice` skill for writing style guidelines
+   - Keep code examples minimal and focused
+   - Ensure imports are complete and correct
+
+5. **Verify**: Run the site build to check for errors after making changes.

.junie/guidelines.md

@@ -189,54 +189,8 @@ Using `--no-build-cache clean` ensures everything is recompiled from scratch.
 - Don't add debug logging or other println's
 - Use the YAGNI principle
 
-## Documentation Tone of Voice Guidelines
-The Aigentic documentation website in `/site` follows specific tone guidelines to ensure content is accessible and user-friendly.
-
-### Key Characteristics
-
-#### Conversational and Natural
-- Use everyday language rather than formal or academic phrasing
-- Write as if you're explaining concepts to a colleague
-- Avoid LLM-generated-sounding phrases like "crucial for effective" or "vital for optimal performance"
-
-#### Direct and Clear
-- Get to the point without unnecessary embellishment
-- Use simple, active constructions: "This helps..." rather than "This is designed to facilitate..."
-- Choose straightforward words over complex alternatives
-
-#### Practical and User-Focused
-- Focus on how features benefit the user
-- Emphasize practical outcomes rather than theoretical advantages
-- Frame explanations in terms of what users can accomplish
-
-#### Approachable but Professional
-- Maintain technical accuracy while being accessible
-- Use a friendly tone without being overly casual
-- Avoid jargon when possible, but don't oversimplify technical concepts
-
-### Word Choice Examples
-
-| Instead of (Too Formal) | Use (Conversational) |
-|-------------------------|----------------------|
-| "crucial for effective" | "significantly improves" |
-| "vital for optimal" | "greatly enhances" |
-| "enables the construction of" | "helps create" |
-| "provides detailed context about" | "gives details about" |
-| "facilitates improved performance" | "makes your tools work better" |
-| "leads to enhanced outcomes" | "helps your agents work more effectively" |
-
-### Sentence Structure
-- Prefer shorter sentences with a clear subject-verb structure
-- Use bullet points for lists rather than complex, comma-separated sentences
-- Start with the benefit or main point, then explain details
-
-### Examples
-
-**Too formal/LLM-like:**
-"The description property in @AigenticParameter is crucial for effective LLM interactions, providing essential context that enables the model to make optimal decisions regarding tool utilization."
-
-**Conversational/Natural:**
-"The description property in @AigenticParameter helps improves LLM interactions. This description gives the LLM context about how and when to use your tools."
+## Documentation Tone of Voice
+When writing or reviewing documentation for the `/site` website, use the `/tone-of-voice` skill for tone guidelines.
 
 ## Git Conventions
 

site/docs/dsl/dsl.mdx

@@ -33,7 +33,7 @@ agent<String, Answer> {
 
   // Configure your provider of choice
   openAIModel {
-    apiKey("<your-api-key")
+    apiKey("<your-api-key>")
     modelIdentifier(OpenAIModelIdentifier.GPT4OMini)
   }
 
@@ -61,21 +61,30 @@ This fluent API makes it easy to configure various aspects of your agent, includ
 Aigentic's DSL provides a consistent interface for working with different LLM providers:
 
 ```kotlin
-// OpenAI model
-val openAIModel = openAIModel {
-  apiKey("YOUR_API_KEY")
-  modelIdentifier(OpenAIModelIdentifier.GPT4Turbo)
+agent<String, Answer> {
+    // OpenAI model
+    openAIModel {
+        apiKey("YOUR_API_KEY")
+        modelIdentifier(OpenAIModelIdentifier.GPT4O)
+    }
+    // ...
 }
 
-// Gemini model
-val geminiModel = geminiModel {
-    apiKey("YOUR_API_KEY")
-    modelIdentifier(GeminiModelIdentifier.Gemini2_5FlashPreview)
+agent<String, Answer> {
+    // Gemini model
+    geminiModel {
+        apiKey("YOUR_API_KEY")
+        modelIdentifier(GeminiModelIdentifier.Gemini2_5Flash)
+    }
+    // ...
 }
 
-// Ollama model
-val ollamaModel = ollamaModel {
-    apiUrl("http://localhost:11434/v1/")
+agent<String, Answer> {
+    // Ollama model
+    ollamaModel {
+        apiUrl("http://localhost:11434/v1/")
+    }
+    // ...
 }
 ```
 
@@ -91,7 +100,7 @@ data class WeatherRequest(val location: String)
 @AigenticParameter
 data class WeatherResponse(val temperature: Double, val conditions: String)
 
-val weatherTool = create<WeatherRequest, WeatherResponse>(
+val weatherTool = createTool<WeatherRequest, WeatherResponse>(
     name = "getWeather",
     description = "Get the current weather for a location"
 ) { request ->

site/docs/dsl/providers.mdx

@@ -19,50 +19,61 @@ Aigentic supports several LLM providers out of the box:
 <Tabs>
   <TabItem value="OpenAI" label="OpenAI">
     <CodeBlock language="kotlin">
-      {`val openAIModel = openAIModel {
-    apiKey("your-api-key")
-    modelIdentifier(OpenAIModelIdentifier.GPT4O)
-    generationConfig {
-        temperature(0.7f)
-        topK(40)
-        topP(0.95f)
+      {`agent<String, Answer> {
+    openAIModel {
+        apiKey("your-api-key")
+        modelIdentifier(OpenAIModelIdentifier.GPT4O)
+        generationConfig {
+            temperature(0.7f)
+            topK(40)
+            topP(0.95f)
+        }
     }
+    // ...
 }`}
     </CodeBlock>
   </TabItem>
 
   <TabItem value="Gemini" label="Gemini">
     <CodeBlock language="kotlin">
-      {`val geminiModel = geminiModel {
-    apiKey("your-api-key")
-    modelIdentifier(GeminiModelIdentifier.Gemini2_5Flash)
-    generationConfig {
-        temperature(0.2f)
-        topK(40)
-        topP(0.8f)
+      {`agent<String, Answer> {
+    geminiModel {
+        apiKey("your-api-key")
+        modelIdentifier(GeminiModelIdentifier.Gemini2_5Flash)
+        generationConfig {
+            temperature(0.2f)
+            topK(40)
+            topP(0.8f)
+        }
     }
+    // ...
 }`}
     </CodeBlock>
   </TabItem>
 
   <TabItem value="Ollama" label="Ollama">
     <CodeBlock language="kotlin">
-      {`val ollamaModel = ollamaModel {
-    apiUrl("http://localhost:11434/v1/")
-    modelIdentifier(OllamaModelIdentifier.Llama2)
-    generationConfig {
-        // Use default settings
+      {`agent<String, Answer> {
+    ollamaModel {
+        apiUrl("http://localhost:11434/v1/")
+        generationConfig {
+            // Use default settings
+        }
     }
+    // ...
 }`}
     </CodeBlock>
   </TabItem>
 
   <TabItem value="VertexAI" label="VertexAI">
     <CodeBlock language="kotlin">
-      {`val vertexAIModel = vertexAIModel {
-    project("your-project-id")
-    location("your-location")
-    modelIdentifier(VertexAIModelIdentifier.Gemini2_5Flash)
+      {`agent<String, Answer> {
+    vertexAIModel {
+        project("your-project-id")
+        location("your-location")
+        modelIdentifier(VertexAIModelIdentifier.Gemini2_5Flash)
+    }
+    // ...
 }`}
     </CodeBlock>
   </TabItem>
@@ -97,7 +108,9 @@ val vertexAgent = agent<String, Summary> {
         location("your-location")
         modelIdentifier(VertexAIModelIdentifier.Gemini2_5Flash)
     }
-    task("Summarize the text as title + bullets")
+    task("Summarize the text as title + bullets") {
+        addInstruction("Return a title and bullet points")
+    }
     // No tools added → structured output request
 }
 ```
@@ -108,13 +121,13 @@ All model implementations in Aigentic implement the `Model` interface, which def
 
 ```kotlin
 interface Model {
-    val authentication: Authentication
     val modelIdentifier: ModelIdentifier
     val generationSettings: GenerationSettings
 
     suspend fun sendRequest(
         messages: List<Message>,
         tools: List<ToolDescription>,
+        structuredOutputParameter: Parameter?,
     ): ModelResponse
 }
 ```