Add plugin manifest and documentation for agents/workflows

- 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 <noreply@anthropic.com>

.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"
+  ]
+}

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.

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
+```