codehava-agent-kit 1.0.1 → 2.0.0

package/templates/.agent/skills/agents-md/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: agents-md
+description: This skill should be used when the user asks to "create AGENTS.md", "update AGENTS.md", "maintain agent docs", "set up CLAUDE.md", or needs to keep agent instructions concise. Enforces research-backed best practices for minimal, high-signal agent documentation.
+risk: unknown
+source: community
+---
+
+# Maintaining AGENTS.md
+
+AGENTS.md is the canonical agent-facing documentation. Keep it minimal—agents are capable and don't need hand-holding. Target under 60 lines; never exceed 100. Instruction-following quality degrades as document length increases.
+
+## File Setup
+
+1. Create `AGENTS.md` at project root
+2. Create symlink: `ln -s AGENTS.md CLAUDE.md`
+
+## Before Writing
+
+Analyze the project to understand what belongs in the file:
+
+1. **Package manager** — Check for lock files (`pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `uv.lock`, `poetry.lock`)
+2. **Linter/formatter configs** — Look for `.eslintrc`, `biome.json`, `ruff.toml`, `.prettierrc`, etc. (don't duplicate these in AGENTS.md)
+3. **CI/build commands** — Check `Makefile`, `package.json` scripts, CI configs for canonical commands
+4. **Monorepo indicators** — Check for `pnpm-workspace.yaml`, `nx.json`, Cargo workspace, or subdirectory `package.json` files
+5. **Existing conventions** — Check for existing CONTRIBUTING.md, docs/, or README patterns
+
+## Writing Rules
+
+- **Headers + bullets** — No paragraphs
+- **Code blocks** — For commands and templates
+- **Reference, don't embed** — Point to existing docs: "See `CONTRIBUTING.md` for setup" or "Follow patterns in `src/api/routes/`"
+- **No filler** — No intros, conclusions, or pleasantries
+- **Trust capabilities** — Omit obvious context
+- **Prefer file-scoped commands** — Per-file test/lint/typecheck commands over project-wide builds
+- **Don't duplicate linters** — Code style lives in linter configs, not AGENTS.md
+
+## Required Sections
+
+### Package Manager
+Which tool and key commands only:
+```markdown
+## Package Manager
+Use **pnpm**: `pnpm install`, `pnpm dev`, `pnpm test`
+```
+
+### File-Scoped Commands
+Per-file commands are faster and cheaper than full project builds. Always include when available:
+```markdown
+## File-Scoped Commands
+| Task | Command |
+|------|---------|
+| Typecheck | `pnpm tsc --noEmit path/to/file.ts` |
+| Lint | `pnpm eslint path/to/file.ts` |
+| Test | `pnpm jest path/to/file.test.ts` |
+```
+
+### Commit Attribution
+Always include this section. Agents should use their own identity:
+```markdown
+## Commit Attribution
+AI commits MUST include:
+```
+Co-Authored-By: (the agent model's name and attribution byline)
+```
+Example: `Co-Authored-By: Claude Sonnet 4 <noreply@example.com>`
+```
+
+### Key Conventions
+Project-specific patterns agents must follow. Keep brief.
+
+## Optional Sections
+
+Add only if truly needed:
+- API route patterns (show template, not explanation)
+- CLI commands (table format)
+- File naming conventions
+- Project structure hints (point to critical files, flag legacy code to avoid)
+- Monorepo overrides (subdirectory `AGENTS.md` files override root)
+
+## Anti-Patterns
+
+Omit these:
+- "Welcome to..." or "This document explains..."
+- "You should..." or "Remember to..."
+- Linter/formatter rules already in config files (`.eslintrc`, `biome.json`, `ruff.toml`)
+- Listing installed skills or plugins (agents discover these automatically)
+- Full project-wide build commands when file-scoped alternatives exist
+- Obvious instructions ("run tests", "write clean code")
+- Explanations of why (just say what)
+- Long prose paragraphs
+
+## Example Structure
+
+```markdown
+# Agent Instructions
+
+## Package Manager
+Use **pnpm**: `pnpm install`, `pnpm dev`
+
+## Commit Attribution
+AI commits MUST include:
+```
+Co-Authored-By: (the agent model's name and attribution byline)
+```
+
+## File-Scoped Commands
+| Task | Command |
+|------|---------|
+| Typecheck | `pnpm tsc --noEmit path/to/file.ts` |
+| Lint | `pnpm eslint path/to/file.ts` |
+| Test | `pnpm jest path/to/file.test.ts` |
+
+## API Routes
+[Template code block]
+
+## CLI
+| Command | Description |
+|---------|-------------|
+| `pnpm cli sync` | Sync data |
+```

package/templates/.agent/skills/agents-v2-py/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: agents-v2-py
+description: "Build container-based Foundry Agents with Azure AI Projects SDK (ImageBasedHostedAgentDefinition). Use when creating hosted agents with custom container images in Azure AI Foundry."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Azure AI Hosted Agents (Python)
+
+Build container-based hosted agents using `ImageBasedHostedAgentDefinition` from the Azure AI Projects SDK.
+
+## Installation
+
+```bash
+pip install azure-ai-projects>=2.0.0b3 azure-identity
+```
+
+**Minimum SDK Version:** `2.0.0b3` or later required for hosted agent support.
+
+## Environment Variables
+
+```bash
+AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
+```
+
+## Prerequisites
+
+Before creating hosted agents:
+
+1. **Container Image** - Build and push to Azure Container Registry (ACR)
+2. **ACR Pull Permissions** - Grant your project's managed identity `AcrPull` role on the ACR
+3. **Capability Host** - Account-level capability host with `enablePublicHostingEnvironment=true`
+4. **SDK Version** - Ensure `azure-ai-projects>=2.0.0b3`
+
+## Authentication
+
+Always use `DefaultAzureCredential`:
+
+```python
+from azure.identity import DefaultAzureCredential
+from azure.ai.projects import AIProjectClient
+
+credential = DefaultAzureCredential()
+client = AIProjectClient(
+    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+    credential=credential
+)
+```
+
+## Core Workflow
+
+### 1. Imports
+
+```python
+import os
+from azure.identity import DefaultAzureCredential
+from azure.ai.projects import AIProjectClient
+from azure.ai.projects.models import (
+    ImageBasedHostedAgentDefinition,
+    ProtocolVersionRecord,
+    AgentProtocol,
+)
+```
+
+### 2. Create Hosted Agent
+
+```python
+client = AIProjectClient(
+    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+    credential=DefaultAzureCredential()
+)
+
+agent = client.agents.create_version(
+    agent_name="my-hosted-agent",
+    definition=ImageBasedHostedAgentDefinition(
+        container_protocol_versions=[
+            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
+        ],
+        cpu="1",
+        memory="2Gi",
+        image="myregistry.azurecr.io/my-agent:latest",
+        tools=[{"type": "code_interpreter"}],
+        environment_variables={
+            "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+            "MODEL_NAME": "gpt-4o-mini"
+        }
+    )
+)
+
+print(f"Created agent: {agent.name} (version: {agent.version})")
+```
+
+### 3. List Agent Versions
+
+```python
+versions = client.agents.list_versions(agent_name="my-hosted-agent")
+for version in versions:
+    print(f"Version: {version.version}, State: {version.state}")
+```
+
+### 4. Delete Agent Version
+
+```python
+client.agents.delete_version(
+    agent_name="my-hosted-agent",
+    version=agent.version
+)
+```
+
+## ImageBasedHostedAgentDefinition Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `container_protocol_versions` | `list[ProtocolVersionRecord]` | Yes | Protocol versions the agent supports |
+| `image` | `str` | Yes | Full container image path (registry/image:tag) |
+| `cpu` | `str` | No | CPU allocation (e.g., "1", "2") |
+| `memory` | `str` | No | Memory allocation (e.g., "2Gi", "4Gi") |
+| `tools` | `list[dict]` | No | Tools available to the agent |
+| `environment_variables` | `dict[str, str]` | No | Environment variables for the container |
+
+## Protocol Versions
+
+The `container_protocol_versions` parameter specifies which protocols your agent supports:
+
+```python
+from azure.ai.projects.models import ProtocolVersionRecord, AgentProtocol
+
+# RESPONSES protocol - standard agent responses
+container_protocol_versions=[
+    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
+]
+```
+
+**Available Protocols:**
+| Protocol | Description |
+|----------|-------------|
+| `AgentProtocol.RESPONSES` | Standard response protocol for agent interactions |
+
+## Resource Allocation
+
+Specify CPU and memory for your container:
+
+```python
+definition=ImageBasedHostedAgentDefinition(
+    container_protocol_versions=[...],
+    image="myregistry.azurecr.io/my-agent:latest",
+    cpu="2",      # 2 CPU cores
+    memory="4Gi"  # 4 GiB memory
+)
+```
+
+**Resource Limits:**
+| Resource | Min | Max | Default |
+|----------|-----|-----|---------|
+| CPU | 0.5 | 4 | 1 |
+| Memory | 1Gi | 8Gi | 2Gi |
+
+## Tools Configuration
+
+Add tools to your hosted agent:
+
+### Code Interpreter
+
+```python
+tools=[{"type": "code_interpreter"}]
+```
+
+### MCP Tools
+
+```python
+tools=[
+    {"type": "code_interpreter"},
+    {
+        "type": "mcp",
+        "server_label": "my-mcp-server",
+        "server_url": "https://my-mcp-server.example.com"
+    }
+]
+```
+
+### Multiple Tools
+
+```python
+tools=[
+    {"type": "code_interpreter"},
+    {"type": "file_search"},
+    {
+        "type": "mcp",
+        "server_label": "custom-tool",
+        "server_url": "https://custom-tool.example.com"
+    }
+]
+```
+
+## Environment Variables
+
+Pass configuration to your container:
+
+```python
+environment_variables={
+    "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+    "MODEL_NAME": "gpt-4o-mini",
+    "LOG_LEVEL": "INFO",
+    "CUSTOM_CONFIG": "value"
+}
+```
+
+**Best Practice:** Never hardcode secrets. Use environment variables or Azure Key Vault.
+
+## Complete Example
+
+```python
+import os
+from azure.identity import DefaultAzureCredential
+from azure.ai.projects import AIProjectClient
+from azure.ai.projects.models import (
+    ImageBasedHostedAgentDefinition,
+    ProtocolVersionRecord,
+    AgentProtocol,
+)
+
+def create_hosted_agent():
+    """Create a hosted agent with custom container image."""
+    
+    client = AIProjectClient(
+        endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        credential=DefaultAzureCredential()
+    )
+    
+    agent = client.agents.create_version(
+        agent_name="data-processor-agent",
+        definition=ImageBasedHostedAgentDefinition(
+            container_protocol_versions=[
+                ProtocolVersionRecord(
+                    protocol=AgentProtocol.RESPONSES,
+                    version="v1"
+                )
+            ],
+            image="myregistry.azurecr.io/data-processor:v1.0",
+            cpu="2",
+            memory="4Gi",
+            tools=[
+                {"type": "code_interpreter"},
+                {"type": "file_search"}
+            ],
+            environment_variables={
+                "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+                "MODEL_NAME": "gpt-4o-mini",
+                "MAX_RETRIES": "3"
+            }
+        )
+    )
+    
+    print(f"Created hosted agent: {agent.name}")
+    print(f"Version: {agent.version}")
+    print(f"State: {agent.state}")
+    
+    return agent
+
+if __name__ == "__main__":
+    create_hosted_agent()
+```
+
+## Async Pattern
+
+```python
+import os
+from azure.identity.aio import DefaultAzureCredential
+from azure.ai.projects.aio import AIProjectClient
+from azure.ai.projects.models import (
+    ImageBasedHostedAgentDefinition,
+    ProtocolVersionRecord,
+    AgentProtocol,
+)
+
+async def create_hosted_agent_async():
+    """Create a hosted agent asynchronously."""
+    
+    async with DefaultAzureCredential() as credential:
+        async with AIProjectClient(
+            endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+            credential=credential
+        ) as client:
+            agent = await client.agents.create_version(
+                agent_name="async-agent",
+                definition=ImageBasedHostedAgentDefinition(
+                    container_protocol_versions=[
+                        ProtocolVersionRecord(
+                            protocol=AgentProtocol.RESPONSES,
+                            version="v1"
+                        )
+                    ],
+                    image="myregistry.azurecr.io/async-agent:latest",
+                    cpu="1",
+                    memory="2Gi"
+                )
+            )
+            return agent
+```
+
+## Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `ImagePullBackOff` | ACR pull permission denied | Grant `AcrPull` role to project's managed identity |
+| `InvalidContainerImage` | Image not found | Verify image path and tag exist in ACR |
+| `CapabilityHostNotFound` | No capability host configured | Create account-level capability host |
+| `ProtocolVersionNotSupported` | Invalid protocol version | Use `AgentProtocol.RESPONSES` with version `"v1"` |
+
+## Best Practices
+
+1. **Version Your Images** - Use specific tags, not `latest` in production
+2. **Minimal Resources** - Start with minimum CPU/memory, scale up as needed
+3. **Environment Variables** - Use for all configuration, never hardcode
+4. **Error Handling** - Wrap agent creation in try/except blocks
+5. **Cleanup** - Delete unused agent versions to free resources
+
+## Reference Links
+
+- [Azure AI Projects SDK](https://pypi.org/project/azure-ai-projects/)
+- [Hosted Agents Documentation](https://learn.microsoft.com/azure/ai-services/agents/how-to/hosted-agents)
+- [Azure Container Registry](https://learn.microsoft.com/azure/container-registry/)
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/templates/.agent/skills/ai-agent-development/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: ai-agent-development
+description: "AI agent development workflow for building autonomous agents, multi-agent systems, and agent orchestration with CrewAI, LangGraph, and custom agents."
+category: granular-workflow-bundle
+risk: safe
+source: personal
+date_added: "2026-02-27"
+---
+
+# AI Agent Development Workflow
+
+## Overview
+
+Specialized workflow for building AI agents including single autonomous agents, multi-agent systems, agent orchestration, tool integration, and human-in-the-loop patterns.
+
+## When to Use This Workflow
+
+Use this workflow when:
+- Building autonomous AI agents
+- Creating multi-agent systems
+- Implementing agent orchestration
+- Adding tool integration to agents
+- Setting up agent memory
+
+## Workflow Phases
+
+### Phase 1: Agent Design
+
+#### Skills to Invoke
+- `ai-agents-architect` - Agent architecture
+- `autonomous-agents` - Autonomous patterns
+
+#### Actions
+1. Define agent purpose
+2. Design agent capabilities
+3. Plan tool integration
+4. Design memory system
+5. Define success metrics
+
+#### Copy-Paste Prompts
+```
+Use @ai-agents-architect to design AI agent architecture
+```
+
+### Phase 2: Single Agent Implementation
+
+#### Skills to Invoke
+- `autonomous-agent-patterns` - Agent patterns
+- `autonomous-agents` - Autonomous agents
+
+#### Actions
+1. Choose agent framework
+2. Implement agent logic
+3. Add tool integration
+4. Configure memory
+5. Test agent behavior
+
+#### Copy-Paste Prompts
+```
+Use @autonomous-agent-patterns to implement single agent
+```
+
+### Phase 3: Multi-Agent System
+
+#### Skills to Invoke
+- `crewai` - CrewAI framework
+- `multi-agent-patterns` - Multi-agent patterns
+
+#### Actions
+1. Define agent roles
+2. Set up agent communication
+3. Configure orchestration
+4. Implement task delegation
+5. Test coordination
+
+#### Copy-Paste Prompts
+```
+Use @crewai to build multi-agent system with roles
+```
+
+### Phase 4: Agent Orchestration
+
+#### Skills to Invoke
+- `langgraph` - LangGraph orchestration
+- `workflow-orchestration-patterns` - Orchestration
+
+#### Actions
+1. Design workflow graph
+2. Implement state management
+3. Add conditional branches
+4. Configure persistence
+5. Test workflows
+
+#### Copy-Paste Prompts
+```
+Use @langgraph to create stateful agent workflows
+```
+
+### Phase 5: Tool Integration
+
+#### Skills to Invoke
+- `agent-tool-builder` - Tool building
+- `tool-design` - Tool design
+
+#### Actions
+1. Identify tool needs
+2. Design tool interfaces
+3. Implement tools
+4. Add error handling
+5. Test tool usage
+
+#### Copy-Paste Prompts
+```
+Use @agent-tool-builder to create agent tools
+```
+
+### Phase 6: Memory Systems
+
+#### Skills to Invoke
+- `agent-memory-systems` - Memory architecture
+- `conversation-memory` - Conversation memory
+
+#### Actions
+1. Design memory structure
+2. Implement short-term memory
+3. Set up long-term memory
+4. Add entity memory
+5. Test memory retrieval
+
+#### Copy-Paste Prompts
+```
+Use @agent-memory-systems to implement agent memory
+```
+
+### Phase 7: Evaluation
+
+#### Skills to Invoke
+- `agent-evaluation` - Agent evaluation
+- `evaluation` - AI evaluation
+
+#### Actions
+1. Define evaluation criteria
+2. Create test scenarios
+3. Measure agent performance
+4. Test edge cases
+5. Iterate improvements
+
+#### Copy-Paste Prompts
+```
+Use @agent-evaluation to evaluate agent performance
+```
+
+## Agent Architecture
+
+```
+User Input -> Planner -> Agent -> Tools -> Memory -> Response
+              |          |        |        |
+         Decompose   LLM Core  Actions  Short/Long-term
+```
+
+## Quality Gates
+
+- [ ] Agent logic working
+- [ ] Tools integrated
+- [ ] Memory functional
+- [ ] Orchestration tested
+- [ ] Evaluation passing
+
+## Related Workflow Bundles
+
+- `ai-ml` - AI/ML development
+- `rag-implementation` - RAG systems
+- `workflow-automation` - Workflow patterns

package/templates/.agent/skills/ai-agents-architect/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: ai-agents-architect
+description: "I build AI systems that can act autonomously while remaining controllable. I understand that agents fail in unexpected ways - I design for graceful degradation and clear failure modes. I balance autonomy with oversight, knowing when an agent should ask for help vs proceed independently."
+risk: unknown
+source: "vibeship-spawner-skills (Apache 2.0)"
+date_added: "2026-02-27"
+---
+
+# AI Agents Architect
+
+**Role**: AI Agent Systems Architect
+
+I build AI systems that can act autonomously while remaining controllable.
+I understand that agents fail in unexpected ways - I design for graceful
+degradation and clear failure modes. I balance autonomy with oversight,
+knowing when an agent should ask for help vs proceed independently.
+
+## Capabilities
+
+- Agent architecture design
+- Tool and function calling
+- Agent memory systems
+- Planning and reasoning strategies
+- Multi-agent orchestration
+- Agent evaluation and debugging
+
+## Requirements
+
+- LLM API usage
+- Understanding of function calling
+- Basic prompt engineering
+
+## Patterns
+
+### ReAct Loop
+
+Reason-Act-Observe cycle for step-by-step execution
+
+```javascript
+- Thought: reason about what to do next
+- Action: select and invoke a tool
+- Observation: process tool result
+- Repeat until task complete or stuck
+- Include max iteration limits
+```
+
+### Plan-and-Execute
+
+Plan first, then execute steps
+
+```javascript
+- Planning phase: decompose task into steps
+- Execution phase: execute each step
+- Replanning: adjust plan based on results
+- Separate planner and executor models possible
+```
+
+### Tool Registry
+
+Dynamic tool discovery and management
+
+```javascript
+- Register tools with schema and examples
+- Tool selector picks relevant tools for task
+- Lazy loading for expensive tools
+- Usage tracking for optimization
+```
+
+## Anti-Patterns
+
+### ❌ Unlimited Autonomy
+
+### ❌ Tool Overload
+
+### ❌ Memory Hoarding
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Agent loops without iteration limits | critical | Always set limits: |
+| Vague or incomplete tool descriptions | high | Write complete tool specs: |
+| Tool errors not surfaced to agent | high | Explicit error handling: |
+| Storing everything in agent memory | medium | Selective memory: |
+| Agent has too many tools | medium | Curate tools per task: |
+| Using multiple agents when one would work | medium | Justify multi-agent: |
+| Agent internals not logged or traceable | medium | Implement tracing: |
+| Fragile parsing of agent outputs | medium | Robust output handling: |
+| Agent workflows lost on crash or restart | high | Use durable execution (e.g. DBOS) to persist workflow state: |
+
+## Related Skills
+
+Works well with: `rag-engineer`, `prompt-engineer`, `backend`, `mcp-builder`, `dbos-python`
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.