From 76f41d26346e765d96f46d4688f0e95a65bfd5b3 Mon Sep 17 00:00:00 2001 From: OpenCode Test Date: Thu, 1 Jan 2026 02:34:38 -0800 Subject: [PATCH] Add plugin manifest and documentation for agents/workflows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add .claude-plugin/plugin.json for potential plugin distribution - Add agents/README.md explaining agent file purpose and usage - Add workflows/README.md clarifying that workflows are design docs, not executable automation (Claude Code doesn't natively execute YAML) This improves documentation and enables potential future portability as a plugin. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .claude-plugin/plugin.json | 17 +++++++ agents/README.md | 63 +++++++++++++++++++++++++ workflows/README.md | 97 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 177 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 agents/README.md create mode 100644 workflows/README.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..4055caa --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,17 @@ +{ + "name": "will-homelab", + "version": "1.0.0", + "description": "Personal assistant and multi-agent system for homelab management, including Gmail, Calendar, Kubernetes, and Linux administration", + "author": { + "name": "Will" + }, + "license": "MIT", + "keywords": [ + "personal-assistant", + "homelab", + "kubernetes", + "gmail", + "calendar", + "linux" + ] +} diff --git a/agents/README.md b/agents/README.md new file mode 100644 index 0000000..e74ebfe --- /dev/null +++ b/agents/README.md @@ -0,0 +1,63 @@ +# Agent Definitions + +This directory contains agent persona definitions for the multi-agent system. + +## Purpose + +Agent files define specialized personas that Claude can adopt when working on specific domains. They are: + +- **Persona documents** - Define behavior, responsibilities, and constraints +- **Reference material** - Loaded into context when the domain is relevant +- **Subagent templates** - Can be spawned via Task tool with explicit prompting + +## Active Agents + +| Agent | Model | Domain | +|-------|-------|--------| +| `personal-assistant` | Opus | User interface, top-level oversight | +| `master-orchestrator` | Opus | Cross-agent coordination, policy enforcement | +| `linux-sysadmin` | Sonnet | Workstation management | +| `k8s-orchestrator` | Opus | Kubernetes cluster management | +| `programmer-orchestrator` | Opus | Code development coordination | + +## Supporting Agents (K8s) + +| Agent | Model | Domain | +|-------|-------|--------| +| `k8s-diagnostician` | Sonnet | Cluster health, pod diagnostics | +| `argocd-operator` | Sonnet | GitOps deployments | +| `prometheus-analyst` | Sonnet | Metrics and alerting | +| `git-operator` | Sonnet | Repository operations | + +## Supporting Agents (Programming) + +| Agent | Model | Domain | +|-------|-------|--------| +| `code-planner` | Sonnet | Design and architecture | +| `code-implementer` | Sonnet | Code writing | +| `code-reviewer` | Sonnet | Code review and quality | + +## Agent File Format + +```yaml +--- +name: agent-name +description: When to use this agent +model: sonnet|opus|haiku +tools: Tool1, Tool2, ... +--- + +# Agent Name + +[Instructions in Markdown] +``` + +## Note on Execution + +Claude Code doesn't automatically spawn agents from this hierarchy. To use an agent: + +1. **Skill-based activation** - If a skill description matches, Claude uses that context +2. **Explicit Task tool** - Use Task tool with agent prompt to spawn subagent +3. **Manual prompt** - Reference agent file directly + +The hierarchy is primarily for organization and documentation. diff --git a/workflows/README.md b/workflows/README.md new file mode 100644 index 0000000..172aa93 --- /dev/null +++ b/workflows/README.md @@ -0,0 +1,97 @@ +# Workflow Definitions + +This directory contains workflow definitions for automated tasks. + +## Status + +**These are design documents, not executable automation.** + +Claude Code does not natively execute YAML workflow files. These definitions serve as: + +1. **Design documentation** - Specify what steps a workflow should perform +2. **Reference for skills** - Skills can reference workflow steps +3. **Future automation** - Can be executed via external tools (cron + headless claude) + +## Workflow Categories + +### Health Checks (`health/`) + +| Workflow | Purpose | +|----------|---------| +| `cluster-health-check.yaml` | Kubernetes cluster health | +| `cluster-daily-summary.yaml` | Daily cluster summary | + +### Deployments (`deploy/`) + +| Workflow | Purpose | +|----------|---------| +| `deploy-app.yaml` | Deploy application to Kubernetes | + +### Incident Response (`incidents/`) + +| Workflow | Purpose | +|----------|---------| +| `pod-crashloop.yaml` | Handle pod crash loops | +| `node-issue-response.yaml` | Respond to node issues | +| `resource-pressure-response.yaml` | Handle resource pressure | +| `argocd-sync-failure.yaml` | Handle ArgoCD sync failures | + +### System Admin (`sysadmin/`) + +| Workflow | Purpose | +|----------|---------| +| `health-check.yaml` | Workstation health check | +| `system-update.yaml` | System package updates | + +## Executing Workflows + +### Option 1: Manual via Claude + +Ask Claude to perform the workflow steps: + +``` +Run the sysadmin health check workflow +``` + +Claude reads the workflow file and executes steps manually. + +### Option 2: Headless Execution + +```bash +claude --print "Execute ~/.claude/workflows/sysadmin/health-check.yaml" | claude +``` + +### Option 3: External Automation (Future) + +Could integrate with: +- Cron jobs calling headless Claude +- n8n workflows +- GitHub Actions + +## Workflow Format + +```yaml +name: workflow-name +description: What this workflow does +version: "1.0.0" + +trigger: + schedule: + cron: "0 9 * * *" + manual: true + +agent: agent-name +model: sonnet|haiku + +steps: + - name: step-name + description: What this step does + commands: + - command1 + - command2 + +output: + file: path/to/output + notify: + on_warning: true +```