From 2bf3ed7c0e253c46d98cde27226ee12d03239639 Mon Sep 17 00:00:00 2001 From: OpenCode Test Date: Thu, 1 Jan 2026 11:55:37 -0800 Subject: [PATCH] Add top-level README and setup validation script MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: Comprehensive overview of the configuration - Quick start guide - Feature summary - Directory structure - Key commands and skills - Maintenance commands - automation/validate-setup.sh: Validation script that checks: - Directory structure - Core files - Plugin manifest - Hooks configuration and executability - Skills and their scripts - State files (JSON validity) - Gmail integration - Documentation coverage Run with: ~/.claude/automation/validate-setup.sh 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 130 ++++++++++++++++++++++++++ automation/validate-setup.sh | 172 +++++++++++++++++++++++++++++++++++ 2 files changed, 302 insertions(+) create mode 100644 README.md create mode 100755 automation/validate-setup.sh diff --git a/README.md b/README.md new file mode 100644 index 0000000..73cf304 --- /dev/null +++ b/README.md @@ -0,0 +1,130 @@ +# Will's Claude Code Configuration + +Personal assistant and multi-agent system for homelab management. + +## Quick Start + +```bash +# Start a session +claude + +# Use the personal assistant +/pa what's on my calendar today? + +# Check system health +/sysadmin:health + +# Check cluster status +/k8s:cluster-status +``` + +## Features + +| Feature | Description | +|---------|-------------| +| **Personal Assistant** | Natural language interface via `/pa` | +| **Gmail Integration** | Read emails, check urgent, search | +| **Calendar Integration** | View agenda, check schedule | +| **Kubernetes Management** | Cluster health, deployments, diagnostics | +| **System Administration** | Health checks, updates, autonomy control | +| **Usage Tracking** | Session statistics and history | + +## Directory Structure + +``` +~/.claude/ +├── .claude-plugin/ # Plugin manifest (for distribution) +├── agents/ # Agent persona definitions +├── automation/ # Systemd timers, scripts +├── commands/ # Slash commands (/pa, /gcal, etc.) +├── hooks/ # Event handlers (SessionStart, PreCompact) +├── mcp/ # MCP integrations (Gmail, delegation) +├── skills/ # Agent skills (gmail, gcal, k8s, sysadmin) +├── state/ # Shared state files (JSON) +├── workflows/ # Workflow definitions (design docs) +├── CLAUDE.md # Shared memory for all agents +└── README.md # This file +``` + +Each directory has its own README with details. + +## Key Commands + +| Command | Description | +|---------|-------------| +| `/pa ` | Natural language request to personal assistant | +| `/gcal [today\|tomorrow\|week]` | Calendar agenda | +| `/usage [today\|week\|month]` | Usage statistics | +| `/sysadmin:health` | System health check | +| `/sysadmin:update` | Package updates | +| `/k8s:cluster-status` | Kubernetes health | +| `/k8s:diagnose` | Troubleshoot K8s issues | + +## Skills (Auto-Invoked) + +Skills are triggered automatically based on your request: + +| Trigger | Skill | +|---------|-------| +| "check my email" | gmail | +| "what's on today" | gcal | +| "cluster status" | k8s-quick-status | +| "system health" | sysadmin-health | +| "usage stats" | usage | + +## Hooks + +| Event | Action | +|-------|--------| +| Session Start | Load context, check pending items | +| Pre-Compact | Remind to preserve important context | + +## Agent Hierarchy + +``` +Personal Assistant (Opus) +└── Master Orchestrator (Opus) + ├── linux-sysadmin (Sonnet) + ├── k8s-orchestrator (Opus) + │ └── k8s-diagnostician, argocd-operator, etc. + └── programmer-orchestrator (Opus) + └── code-planner, code-implementer, code-reviewer +``` + +## Configuration + +| File | Purpose | +|------|---------| +| `CLAUDE.md` | Shared instructions for all agents | +| `settings.json` | Claude Code settings | +| `state/component-registry.json` | Routing and discovery | +| `state/autonomy-levels.json` | Permission levels | + +## Plugin Installation + +This configuration can be installed as a plugin: + +```bash +# Add as local marketplace +/plugin marketplace add ~/.claude + +# Install +/plugin install will-homelab@will-homelab-dev +``` + +## Maintenance + +```bash +# Validate component registry +python3 ~/.claude/automation/validate-registry.py + +# Regenerate registry from files +python3 ~/.claude/automation/generate-registry.py + +# Check systemd timers +systemctl --user list-timers +``` + +## License + +MIT diff --git a/automation/validate-setup.sh b/automation/validate-setup.sh new file mode 100755 index 0000000..1d369c7 --- /dev/null +++ b/automation/validate-setup.sh @@ -0,0 +1,172 @@ +#!/bin/bash +# Validate the Claude Code configuration setup +# Run this after changes to ensure everything is properly configured + +set -euo pipefail + +CLAUDE_DIR="${HOME}/.claude" +ERRORS=0 +WARNINGS=0 + +# Colors +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +pass() { echo -e "${GREEN}✓${NC} $1"; } +fail() { echo -e "${RED}✗${NC} $1"; ((ERRORS++)); } +warn() { echo -e "${YELLOW}!${NC} $1"; ((WARNINGS++)); } + +echo "Validating Claude Code configuration..." +echo "" + +# Check required directories +echo "=== Directory Structure ===" +for dir in agents commands hooks mcp skills state workflows automation; do + if [[ -d "${CLAUDE_DIR}/${dir}" ]]; then + pass "${dir}/ exists" + else + fail "${dir}/ missing" + fi +done +echo "" + +# Check required files +echo "=== Core Files ===" +for file in CLAUDE.md README.md settings.json .gitignore; do + if [[ -f "${CLAUDE_DIR}/${file}" ]]; then + pass "${file} exists" + else + fail "${file} missing" + fi +done +echo "" + +# Check plugin manifest +echo "=== Plugin Structure ===" +if [[ -f "${CLAUDE_DIR}/.claude-plugin/plugin.json" ]]; then + pass "plugin.json exists" + if python3 -c "import json; json.load(open('${CLAUDE_DIR}/.claude-plugin/plugin.json'))" 2>/dev/null; then + pass "plugin.json is valid JSON" + else + fail "plugin.json is invalid JSON" + fi +else + warn "plugin.json missing (optional for local use)" +fi +echo "" + +# Check hooks +echo "=== Hooks ===" +if [[ -f "${CLAUDE_DIR}/hooks/hooks.json" ]]; then + pass "hooks.json exists" + if python3 -c "import json; json.load(open('${CLAUDE_DIR}/hooks/hooks.json'))" 2>/dev/null; then + pass "hooks.json is valid JSON" + else + fail "hooks.json is invalid JSON" + fi +else + warn "hooks.json missing" +fi + +for script in session-start.sh pre-compact.sh; do + if [[ -x "${CLAUDE_DIR}/hooks/scripts/${script}" ]]; then + pass "hooks/scripts/${script} is executable" + elif [[ -f "${CLAUDE_DIR}/hooks/scripts/${script}" ]]; then + fail "hooks/scripts/${script} exists but not executable" + fi +done +echo "" + +# Check skills +echo "=== Skills ===" +for skill in gmail gcal k8s-quick-status sysadmin-health usage programmer-add-project; do + skill_dir="${CLAUDE_DIR}/skills/${skill}" + if [[ -f "${skill_dir}/SKILL.md" ]]; then + pass "${skill}/SKILL.md exists" + + # Check for scripts directory + if [[ -d "${skill_dir}/scripts" ]]; then + script_count=$(find "${skill_dir}/scripts" -type f \( -name "*.py" -o -name "*.sh" \) | wc -l) + if [[ ${script_count} -gt 0 ]]; then + pass "${skill}/scripts/ has ${script_count} script(s)" + + # Check executability + while IFS= read -r script; do + [[ -f "$script" ]] || continue + if [[ -x "$script" ]]; then + pass "$(basename "$script") is executable" + else + fail "$(basename "$script") not executable" + fi + done < <(find "${skill_dir}/scripts" -type f \( -name "*.py" -o -name "*.sh" \) 2>/dev/null) + fi + fi + else + fail "${skill}/SKILL.md missing" + fi +done +echo "" + +# Check state files +echo "=== State Files ===" +for file in component-registry.json autonomy-levels.json model-policy.json; do + state_file="${CLAUDE_DIR}/state/${file}" + if [[ -f "${state_file}" ]]; then + pass "state/${file} exists" + if python3 -c "import json; json.load(open('${state_file}'))" 2>/dev/null; then + pass "state/${file} is valid JSON" + else + fail "state/${file} is invalid JSON" + fi + else + fail "state/${file} missing" + fi +done +echo "" + +# Check Gmail setup +echo "=== Gmail Integration ===" +if [[ -d "${CLAUDE_DIR}/mcp/gmail/venv" ]]; then + pass "Gmail venv exists" + if [[ -f "${CLAUDE_DIR}/mcp/gmail/venv/bin/python" ]]; then + pass "Gmail venv has Python" + else + fail "Gmail venv missing Python" + fi +else + warn "Gmail venv not set up" +fi + +if [[ -f "${HOME}/.gmail-mcp/credentials.json" ]]; then + pass "Gmail credentials exist" +else + warn "Gmail credentials missing (~/.gmail-mcp/credentials.json)" +fi +echo "" + +# Check READMEs +echo "=== Documentation ===" +readme_count=0 +for dir in agents commands hooks mcp skills state workflows; do + if [[ -f "${CLAUDE_DIR}/${dir}/README.md" ]]; then + readme_count=$((readme_count + 1)) + else + warn "${dir}/README.md missing" + fi +done +pass "${readme_count}/7 directory READMEs present" +echo "" + +# Summary +echo "=== Summary ===" +if [[ ${ERRORS} -eq 0 && ${WARNINGS} -eq 0 ]]; then + echo -e "${GREEN}All checks passed!${NC}" +elif [[ ${ERRORS} -eq 0 ]]; then + echo -e "${YELLOW}${WARNINGS} warning(s), 0 errors${NC}" +else + echo -e "${RED}${ERRORS} error(s), ${WARNINGS} warning(s)${NC}" +fi + +exit ${ERRORS}