feat: Add /pa personal assistant command and state infrastructure

Implement canonical /pa entrypoint for user requests with: - Context-aware request routing via master-orchestrator - Session and persistent context level overrides - Memory system with UUID-based general-instructions.json - State files for session context and preferences 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-28 19:59:58 -08:00
parent 73512e92a6
commit fa049a1374
7 changed files with 651 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,162 @@
+# Claude Code Shared Memory
+
+This file contains shared conventions, state file locations, and instructions that apply to all agents.
+
+## Agent System Architecture
+
+```
+Personal Assistant (Opus) - user interface + ultimate oversight
+└── Master Orchestrator (Opus) - monitor, coordinate, enforce
+    ├── linux-sysadmin (Sonnet) - workstation management
+    ├── k8s-orchestrator (Opus) - cluster management
+    │   ├── k8s-diagnostician (Sonnet)
+    │   ├── argocd-operator (Sonnet)
+    │   ├── prometheus-analyst (Sonnet)
+    │   └── git-operator (Sonnet)
+    └── network-agent (future)
+```
+
+## Shared State Files
+
+All agents MUST read and follow the processes defined in these files:
+
+| File | Purpose | Writer |
+|------|---------|--------|
+| `~/.claude/state/system-instructions.json` | Central process definitions | master-orchestrator |
+| `~/.claude/state/future-considerations.json` | Deferred features/decisions | master-orchestrator |
+| `~/.claude/state/model-policy.json` | Model selection rules | master-orchestrator |
+| `~/.claude/state/autonomy-levels.json` | Autonomy definitions | master-orchestrator |
+| `~/.claude/state/sysadmin/session-autonomy.json` | Per-session overrides | user/CLI |
+| `~/.claude/state/personal-assistant-preferences.json` | PA persistent config | master-orchestrator |
+| `~/.claude/state/personal-assistant/session-context.json` | Session context override | user/CLI |
+| `~/.claude/state/personal-assistant/general-instructions.json` | User memory | personal-assistant |
+
+## Key Processes
+
+### Model Selection
+- Start with lowest capable model (haiku → sonnet → opus)
+- Escalate only when task complexity requires
+- Log model usage for cost analysis
+
+### Cross-Agent Communication
+- All cross-agent requests route through master orchestrator
+- Master validates, routes, and logs all requests
+- Personal assistant has ultimate escalation authority
+- No direct agent-to-agent communication
+
+### Autonomy Enforcement
+- Default: conservative (confirm all write operations)
+- Session overrides apply only for current session
+- Forbidden actions always blocked regardless of autonomy level
+
+## Directory Structure
+
+```
+~/.claude/
+├── CLAUDE.md                    # This file - shared memory
+├── agents/                      # Agent definitions (Markdown + YAML frontmatter)
+├── state/                       # Shared state files (JSON)
+│   ├── sysadmin/               # Linux sysadmin agent state
+│   └── personal-assistant/     # Personal assistant agent state
+├── skills/                      # Skill definitions
+├── commands/                    # Slash command definitions
+├── workflows/                   # Workflow definitions
+└── automation/                  # Managed scripts and automation
+```
+
+## Conventions
+
+- **Agent files**: Markdown with YAML frontmatter
+- **Data files**: JSON format
+- **Logs**: JSON lines format where applicable
+- **No duplication**: Information lives in one place. CLAUDE.md = overview, state JSON = details
+
+## Maintenance
+
+See `system-instructions.json` for detailed maintenance procedures.
+
+**Key rules:**
+- master-orchestrator maintains `agents/`, `state/`, `skills/`, `commands/`, `workflows/`
+- linux-sysadmin maintains `state/sysadmin/`, `automation/`
+- personal-assistant maintains `state/personal-assistant/general-instructions.json`
+- When adding/removing agents: update agent file, supervisor's hierarchy, this diagram, and `model-policy.json`
+
+## Agent File Format
+
+All agents must use this format:
+
+```markdown
+---
+name: agent-name
+description: When to use this agent
+model: sonnet|opus|haiku
+tools: Tool1, Tool2, Tool3
+---
+
+[Agent instructions in Markdown]
+```
+
+## Component Types and Formats
+
+### Format Conventions
+
+| Component | Format | Location | Purpose |
+|-----------|--------|----------|---------|
+| **State** | JSON | `state/` | Machine-readable configuration |
+| **Agents** | Markdown + YAML frontmatter | `agents/` | Agent personas and instructions |
+| **Commands** | Markdown + YAML frontmatter | `commands/` | User-invocable shortcuts |
+| **Skills** | `SKILL.md` in subdirectory | `skills/` | Reusable capabilities |
+| **Workflows** | YAML | `workflows/` | Multi-step automation |
+
+### Component Relationships
+
+```
+User types /command
+       │
+       ▼
+   Command (thin wrapper)
+       │
+       ├─→ invokes: skill:<name>     → Reusable capability
+       ├─→ invokes: workflow:<path>  → Multi-step process
+       └─→ modifies: state:<path>    → Configuration change
+```
+
+### Command Frontmatter
+
+```yaml
+---
+name: command-name
+description: What this command does
+aliases: [alias1, alias2]
+invokes: skill:skill-name           # OR
+invokes: workflow:category/name     # OR
+modifies: state:category/file
+---
+```
+
+### Skill Structure
+
+Skills use a subdirectory with `SKILL.md`:
+
+```
+skills/
+└── skill-name/
+    └── SKILL.md
+```
+
+### Workflow Format
+
+Workflows use pure YAML for step-based automation:
+
+```yaml
+name: workflow-name
+description: What this workflow does
+trigger:
+  - schedule: "0 */6 * * *"
+  - manual: true
+steps:
+  - name: step-name
+    agent: agent-name
+    task: |
+      Task description
+```