ai-playbook 1.0.0

package/roles/support-engineer/skill-map.md

@@ -0,0 +1,14 @@
+# Support Engineer Skill Map
+
+## Primary Skills
+
+- `skills/support-engineering/` - Triage, diagnosis, and communication.
+- `skills/sre/` - Production signals, incidents, and reliability context.
+- `skills/software-development/` - Code-aware debugging and reproduction.
+- `skills/documentation/` - Runbooks, knowledge base entries, and handoffs.
+
+## Context
+
+- `context/communication.md` - Communication standards.
+- `context/engineering.md` - Engineering processes and ownership.
+- `projects/<project>/` - Product behavior, service context, and runbooks.

package/roles/support-engineer/splunk/README.md

@@ -0,0 +1,6 @@
+# Splunk
+
+Use this folder for support-engineering guidance related to Splunk.
+
+Add search patterns, field conventions, dashboards, alert triage, and log
+redaction guidance when this packet becomes active.

package/roles/support-engineer/triggers.md

@@ -0,0 +1,10 @@
+# Support Engineer Triggers
+
+Use the support engineer role when work involves:
+
+- Triage of customer issues, support tickets, or production symptoms.
+- Reproducing and diagnosing reported behavior.
+- Writing escalation summaries or customer-safe technical explanations.
+- Creating or updating runbooks and troubleshooting guides.
+- Investigating logs, monitoring, configuration, or environment-specific failures.
+- Closing the loop after an incident or recurring support issue.

package/roles/support-engineer/troubleshooting/README.md

@@ -0,0 +1,6 @@
+# Troubleshooting
+
+Use this folder for support-engineering troubleshooting guidance.
+
+Add diagnostic flows, symptom-to-cause maps, evidence templates, and escalation
+criteria when this packet becomes active.

package/roles/support-engineer/workflow.md

@@ -0,0 +1,9 @@
+# Support Engineer Workflow
+
+1. Capture the report, affected users, severity, timestamps, and environment.
+2. Confirm expected versus actual behavior.
+3. Reproduce the issue or gather enough evidence to narrow the path.
+4. Check recent changes, logs, metrics, traces, and configuration.
+5. Provide a workaround when available.
+6. Escalate with evidence when ownership moves to another team.
+7. Confirm resolution, document outcome, and update runbooks when needed.

package/setup.sh

@@ -0,0 +1,204 @@
+#!/bin/bash
+# setup.sh
+# Purpose: Sync ai-playbook to Claude Code, Codex, Gemini, Warp, and other AI tool directories
+
+set -e
+
+PLAYBOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOME_DIR="$HOME"
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "AI Playbook Setup"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "Syncing from: $PLAYBOOK_DIR"
+echo "Home: $HOME_DIR"
+echo ""
+
+# Color codes
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Counters
+SYNCED=0
+SKIPPED=0
+
+# Function to sync to a directory
+sync_to_dir() {
+    local tool_name="$1"
+    local target_dir="$2"
+    local folders="$3"  # Space-separated list of folders to sync
+
+    echo -n "Setting up $tool_name... "
+
+    if [ ! -d "$target_dir" ]; then
+        mkdir -p "$target_dir"
+    fi
+
+    # Sync each folder
+    for folder in $folders; do
+        src="$PLAYBOOK_DIR/$folder"
+        dst="$target_dir/$folder"
+
+        if [ -d "$src" ]; then
+            rm -rf "$dst" 2>/dev/null || true
+            cp -r "$src" "$dst"
+        fi
+    done
+
+    # Also copy README and other key files
+    for file in README.md CLAUDE.md; do
+        if [ -f "$PLAYBOOK_DIR/$file" ]; then
+            cp "$PLAYBOOK_DIR/$file" "$target_dir/" 2>/dev/null || true
+        fi
+    done
+
+    echo -e "${GREEN}✓${NC}"
+    SYNCED=$((SYNCED + 1))
+}
+
+# Claude Code / Claude CLI
+if [ -d "$HOME_DIR/.claude" ]; then
+    echo "• Claude Code detected"
+    sync_to_dir "Claude Code" "$HOME_DIR/.claude/playbook" \
+        "agents commands hooks prompts skills patterns knowledge roles context"
+fi
+
+# Codex (GitHub CLI with Copilot)
+if command -v gh &> /dev/null; then
+    echo "• GitHub CLI detected"
+    GH_CONFIG="${HOME_DIR}/.config/gh"
+    if [ -d "$GH_CONFIG" ]; then
+        CODEX_DIR="$GH_CONFIG/extensions/playbook"
+        mkdir -p "$CODEX_DIR"
+        sync_to_dir "Codex" "$CODEX_DIR" \
+            "agents commands hooks prompts skills patterns knowledge roles context"
+    fi
+fi
+
+# Gemini (Google AI)
+if [ -d "$HOME_DIR/.config/google-ai" ] || [ -f "$HOME_DIR/.gemini_api_key" ]; then
+    echo "• Gemini detected"
+    GEMINI_DIR="$HOME_DIR/.config/google-ai/playbook"
+    mkdir -p "$GEMINI_DIR"
+    sync_to_dir "Gemini" "$GEMINI_DIR" \
+        "agents commands hooks prompts skills patterns knowledge roles context"
+fi
+
+# Warp (Terminal)
+if [ -d "$HOME_DIR/.warp" ] || [ -d "$HOME_DIR/Library/Application Support/Warp" ]; then
+    echo "• Warp detected"
+    WARP_DIR="${HOME_DIR}/Library/Application Support/Warp/playbook"
+    mkdir -p "$WARP_DIR"
+    sync_to_dir "Warp" "$WARP_DIR" \
+        "commands hooks prompts skills patterns knowledge"
+fi
+
+# Cursor (Editor)
+if [ -d "$HOME_DIR/.config/Cursor" ] || [ -d "$HOME_DIR/Library/Application Support/Cursor" ]; then
+    echo "• Cursor detected"
+    CURSOR_DIR="$HOME_DIR/.config/Cursor/playbook"
+    mkdir -p "$CURSOR_DIR"
+    sync_to_dir "Cursor" "$CURSOR_DIR" \
+        "agents commands hooks prompts skills patterns knowledge roles"
+fi
+
+# VS Code with Copilot
+if [ -d "$HOME_DIR/.config/Code" ] || [ -d "$HOME_DIR/Library/Application Support/Code" ]; then
+    echo "• VS Code detected"
+    VSCODE_DIR="${HOME_DIR}/.vscode-playbook"
+    mkdir -p "$VSCODE_DIR"
+    sync_to_dir "VS Code" "$VSCODE_DIR" \
+        "commands hooks prompts skills patterns"
+fi
+
+# JetBrains IDEs
+if [ -d "$HOME_DIR/.config/JetBrains" ] || [ -d "$HOME_DIR/Library/Application Support/JetBrains" ]; then
+    echo "• JetBrains detected"
+    JETBRAINS_DIR="$HOME_DIR/.jetbrains-playbook"
+    mkdir -p "$JETBRAINS_DIR"
+    sync_to_dir "JetBrains" "$JETBRAINS_DIR" \
+        "commands hooks prompts skills patterns"
+fi
+
+# Aider (CLI)
+if command -v aider &> /dev/null; then
+    echo "• Aider detected"
+    AIDER_DIR="$HOME_DIR/.aider/playbook"
+    mkdir -p "$AIDER_DIR"
+    sync_to_dir "Aider" "$AIDER_DIR" \
+        "agents commands prompts skills patterns knowledge"
+fi
+
+# Continue (IDE extension)
+if [ -d "$HOME_DIR/.continue" ]; then
+    echo "• Continue detected"
+    CONTINUE_DIR="$HOME_DIR/.continue/playbook"
+    mkdir -p "$CONTINUE_DIR"
+    sync_to_dir "Continue" "$CONTINUE_DIR" \
+        "agents prompts skills patterns knowledge"
+fi
+
+# LM Studio
+if [ -d "$HOME_DIR/.lm-studio" ]; then
+    echo "• LM Studio detected"
+    LMSTUDIO_DIR="$HOME_DIR/.lm-studio/playbook"
+    mkdir -p "$LMSTUDIO_DIR"
+    sync_to_dir "LM Studio" "$LMSTUDIO_DIR" \
+        "prompts skills patterns knowledge"
+fi
+
+# Ollama
+if command -v ollama &> /dev/null; then
+    echo "• Ollama detected"
+    OLLAMA_DIR="$HOME_DIR/.ollama/playbook"
+    mkdir -p "$OLLAMA_DIR"
+    sync_to_dir "Ollama" "$OLLAMA_DIR" \
+        "prompts skills patterns knowledge"
+fi
+
+# Generic playbook directory
+GENERIC_DIR="$HOME_DIR/.ai-playbook"
+if [ ! -d "$GENERIC_DIR" ]; then
+    mkdir -p "$GENERIC_DIR"
+    echo "• Creating generic playbook directory"
+    sync_to_dir "Generic" "$GENERIC_DIR" \
+        "agents commands hooks prompts skills patterns knowledge roles context"
+else
+    echo "• Generic playbook directory exists (skipping)"
+    SKIPPED=$((SKIPPED + 1))
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Setup Complete"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "Synced to $SYNCED locations"
+echo ""
+
+# List where playbook is available
+echo "Playbook is now available at:"
+echo ""
+
+[ -d "$HOME_DIR/.claude/playbook" ] && echo "  • ~/.claude/playbook"
+[ -d "$HOME_DIR/.config/gh/extensions/playbook" ] && echo "  • ~/.config/gh/extensions/playbook"
+[ -d "$HOME_DIR/.config/google-ai/playbook" ] && echo "  • ~/.config/google-ai/playbook"
+[ -d "$HOME_DIR/Library/Application Support/Warp/playbook" ] && echo "  • ~/Library/Application Support/Warp/playbook"
+[ -d "$HOME_DIR/.config/Cursor/playbook" ] && echo "  • ~/.config/Cursor/playbook"
+[ -d "$HOME_DIR/.vscode-playbook" ] && echo "  • ~/.vscode-playbook"
+[ -d "$HOME_DIR/.jetbrains-playbook" ] && echo "  • ~/.jetbrains-playbook"
+[ -d "$HOME_DIR/.aider/playbook" ] && echo "  • ~/.aider/playbook"
+[ -d "$HOME_DIR/.continue/playbook" ] && echo "  • ~/.continue/playbook"
+[ -d "$HOME_DIR/.lm-studio/playbook" ] && echo "  • ~/.lm-studio/playbook"
+[ -d "$HOME_DIR/.ollama/playbook" ] && echo "  • ~/.ollama/playbook"
+[ -d "$HOME_DIR/.ai-playbook" ] && echo "  • ~/.ai-playbook"
+
+echo ""
+echo "Usage:"
+echo "  • Reference in prompts: @~/.ai-playbook/prompts"
+echo "  • Use in tools: Import from tool-specific location"
+echo "  • Reference folders: agents/, skills/, patterns/, etc."
+echo ""
+echo "To update, re-run: bash setup.sh"

package/skills/.claude/README.md

@@ -0,0 +1,7 @@
+# Claude Skill Notes
+
+Use this folder for Claude-specific skill packaging notes or compatibility
+guidance.
+
+Keep reusable model behavior in `models/claude/` and general skills in
+`skills/`.

package/skills/README.md

@@ -0,0 +1,21 @@
+# Skills
+
+Use this folder for reusable capability packets.
+
+Each skill should explain when to use it, what context to load, how to proceed,
+what to produce, and how to verify completion.
+
+## Standard Packet
+
+```text
+skills/<skill-name>/
++-- README.md
++-- skill.md
++-- examples.md
++-- checklists.md
++-- workflows.md
++-- templates/
+```
+
+Minimal skills may start with `README.md`, `skill.md`, and `examples.md`, but
+active references should not point to missing files.

package/skills/ai-agents/README.md

@@ -0,0 +1,207 @@
+# AI Agents
+
+## Overview
+
+The **AI Agents** skill enables AI models to design, build, deploy, and maintain production-grade autonomous agent systems that can reason, take actions, and solve complex problems using tools and external integrations.
+
+This skill covers agent architecture design, LLM integration, tool/function design, workflow orchestration, error handling, observability, and deployment strategies for single-agent and multi-agent systems.
+
+---
+
+# Goals
+
+The primary goals of this skill are:
+
+* Design reliable agent systems
+* Implement effective tool interactions
+* Build scalable multi-agent architectures
+* Ensure production observability
+* Manage costs and performance
+* Implement safety guardrails
+* Create maintainable agent code
+* Optimize for reliability and resilience
+* Provide comprehensive monitoring
+* Enable autonomous decision-making with oversight
+
+---
+
+# Capabilities
+
+This skill can assist with:
+
+## Agent Design
+
+* Single-agent systems
+* Multi-agent coordination
+* Agent architectures and frameworks
+* Tool design and specifications
+* Workflow orchestration
+* State management
+
+## Implementation
+
+* LLM integration
+* Tool/function implementations
+* Agent loop implementation
+* Error handling patterns
+* Timeout management
+* Retry logic
+
+## Integration
+
+* External API integration
+* Cloud provider tools
+* Database access
+* Authentication and authorization
+* Rate limiting
+* Resource management
+
+## Operations
+
+* Agent monitoring
+* Performance tracking
+* Cost management
+* Health checks
+* Logging and debugging
+* Alert configuration
+
+---
+
+# When to Use
+
+Use this skill when:
+
+* Designing new agent systems
+* Building tool integrations
+* Creating multi-agent workflows
+* Implementing autonomous systems
+* Setting up agent monitoring
+* Optimizing agent performance
+* Testing agent implementations
+* Debugging agent behavior
+* Scaling agent systems
+* Managing agent costs
+
+---
+
+# Expected Workflow
+
+The AI Agents skill follows this workflow:
+
+```text
+Define Objectives & Constraints
+        ↓
+Design Agent Architecture
+        ↓
+Specify Tools & Functions
+        ↓
+Implement Agent Loop
+        ↓
+Integrate External Systems
+        ↓
+Test & Validate
+        ↓
+Deploy & Monitor
+        ↓
+Optimize & Scale
+```
+
+---
+
+# Inputs
+
+Typical inputs include:
+
+* Problem statements
+* Business objectives
+* Existing tools/APIs
+* System requirements
+* Scalability requirements
+* Cost constraints
+* Security requirements
+* Integration specifications
+
+---
+
+# Outputs
+
+Typical outputs include:
+
+* Agent architecture designs
+* Tool specifications
+* Implementation code
+* Test suites
+* Deployment configurations
+* Monitoring dashboards
+* Cost estimates
+* Performance reports
+* Documentation
+
+---
+
+# Related Skills
+
+This skill commonly works alongside:
+
+* Software Development
+* Architecture
+* DevOps
+* QA
+* Security
+* Performance
+* Documentation
+
+---
+
+# Best Practices
+
+Always:
+
+* Define clear agent objectives
+* Design simple, focused tools
+* Implement comprehensive error handling
+* Monitor costs continuously
+* Test thoroughly before deployment
+* Implement proper logging
+* Use timeouts appropriately
+* Cache when beneficial
+* Document tool specifications clearly
+* Implement safety guardrails
+
+Never:
+
+* Assume tools always succeed
+* Skip error handling
+* Deploy without monitoring
+* Ignore token limits
+* Expose credentials or sensitive data
+* Implement agents without testing
+* Mix agent logic with business logic
+* Hardcode API keys
+* Deploy untested agent frameworks
+* Ignore cost implications
+
+---
+
+# Success Criteria
+
+A successful agent system should:
+
+* Reliably accomplish defined objectives
+* Handle errors gracefully
+* Operate within resource and cost constraints
+* Provide clear observability
+* Scale appropriately
+* Be maintainable and debuggable
+* Follow security best practices
+* Have clear documentation
+* Be ready for production deployment
+* Support human oversight when needed
+
+---
+
+# Version
+
+**Version:** 1.0
+
+This skill is intended to evolve as new agent frameworks, LLM capabilities, and orchestration patterns emerge.