Implement programmer agent system and consolidate agent infrastructure

Programmer Agent System: - Add programmer-orchestrator (Opus) for workflow coordination - Add code-planner (Sonnet) for design and planning - Add code-implementer (Sonnet) for writing code - Add code-reviewer (Sonnet) for quality review - Add /programmer command and project registration skill - Add state files for preferences and project context Agent Infrastructure: - Add master-orchestrator and linux-sysadmin agents - Restructure skills to use SKILL.md subdirectory format - Convert workflows from markdown to YAML format - Add commands for k8s and sysadmin domains - Add shared state files (model-policy, autonomy-levels, system-instructions) - Add PA memory system (decisions, preferences, projects, facts) Cleanup: - Remove deprecated markdown skills and workflows - Remove crontab example (moved to workflows) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-29 13:23:42 -08:00
parent 119d2a464e
commit 431e10b449
62 changed files with 3572 additions and 539 deletions
--- a/docs/plans/2025-12-29-pa-personal-assistant-plan-and-handoff.md
+++ b/docs/plans/2025-12-29-pa-personal-assistant-plan-and-handoff.md
@@ -0,0 +1,208 @@
+# /pa Personal Assistant — Plan + Implementation Handoff (2025-12-29)
+
+## Context
+This repo defines a Claude Code agent system under `~/.claude/`.
+
+Key conventions from `~/.claude/CLAUDE.md`:
+- Agent files are Markdown with YAML frontmatter (`agents/`).
+- Structured, machine-readable state lives in JSON (`state/`).
+- Cross-agent communication flows through `master-orchestrator`.
+- `master-orchestrator` maintains `agents/`, `state/`, `skills/`, `commands/`, `workflows/`.
+- `personal-assistant` is the user-facing UI layer with ultimate oversight.
+
+This document captures the agreed plan for making `personal-assistant` the main user interface, via a canonical `/pa` command with command-style flags.
+
+---
+
+## Goals
+- Provide a canonical entrypoint command: `/pa`.
+- Make `personal-assistant` route requests (domain+intent) and delegate execution through `master-orchestrator`.
+- Add configurable context-gathering granularity with:
+  - per-request override
+  - per-session override
+  - persistent default
+- Add persistent, structured “general instructions” memory (append-only list with UUID ids).
+- Keep documentation non-duplicative: `CLAUDE.md` stays overview; JSON holds details.
+
+---
+
+## Command Contract: `/pa`
+### File
+- `~/.claude/commands/pa.md`
+
+### Required frontmatter (match existing command patterns)
+- `name: pa`
+- `description: ...`
+- `aliases: [...]`
+
+### Parsing rules
+Support both:
+- `/pa <request>`
+- `/pa -- <request>`
+  - `--` ends flag parsing; everything after is literal request text.
+
+### Flags
+#### Request override (highest precedence)
+- `/pa --context none|minimal|moderate|comprehensive -- <request>`
+
+#### Session override (ephemeral)
+- `/pa --set-context none|minimal|moderate|comprehensive`
+- `/pa --clear-context`
+
+#### Persistent default (durable)
+- `/pa --set-default-context none|minimal|moderate|comprehensive`
+  - MUST prompt: `Proceed? [y/N]`
+
+#### Persistent memory
+- `/pa --remember -- "<instruction text>"`
+- `/pa --list-mem` (active only)
+- `/pa --list-mem --all` (includes deprecated)
+- `/pa --forget <uuid>` (soft delete: mark deprecated)
+
+#### Introspection
+- `/pa --show-config`
+- `/pa --help`
+
+---
+
+## Context Granularity Resolution (effective level)
+Precedence (highest to lowest):
+1. Request override: `--context <level>`
+2. Session override: `~/.claude/state/personal-assistant/session-context.json`
+3. Persistent default: `~/.claude/state/personal-assistant-preferences.json`
+4. Hard default: `moderate`
+
+---
+
+## Routing & Delegation Behavior
+### personal-assistant responsibilities
+Update `~/.claude/agents/personal-assistant.md` to explicitly support the `/pa` usage model.
+
+**Routing:**
+- Classify using: keywords + intent + conversation context.
+- If ambiguity remains after considering conversation context: ask the user (no guessing).
+
+**Delegation constraints:**
+- Never delegate directly to domain agents.
+- Always route execution via `master-orchestrator` with a structured payload.
+
+**Response:**
+- Present a unified user-facing result; hide internal agent boundaries unless useful.
+
+### master-orchestrator responsibilities
+No direct design changes were specified here beyond supporting:
+- structured request payloads from `personal-assistant`
+- coordination of domain agents with proper safety/autonomy enforcement
+- writing persistent state JSONs in `state/` (where applicable)
+
+---
+
+## New / Updated State Files
+### 1) Session context override (writer: user/CLI)
+- Path: `~/.claude/state/personal-assistant/session-context.json`
+- Purpose: Session-only override of context granularity
+- Resets when session ends
+
+**Schema (v1):**
+- `version` (string)
+- `current_context_level` (`none|minimal|moderate|comprehensive`)
+- `set_at` (ISO datetime string)
+- `set_by` (string, e.g. `user`)
+
+### 2) Persistent PA preferences (writer: master-orchestrator)
+- Path: `~/.claude/state/personal-assistant-preferences.json`
+- Purpose: Persistent default context granularity
+
+**Schema (v1):**
+- `version` (string)
+- `description` (string)
+- `context_gathering.default_level` (`none|minimal|moderate|comprehensive`)
+
+### 3) Persistent global memory: general instructions (writer: master-orchestrator)
+- Path: `~/.claude/state/general-instructions.json`
+- Purpose: Durable, machine-readable “general instructions” store (append-only)
+
+**Schema (v1):**
+- `version` (string)
+- `description` (string)
+- `items` (array)
+  - `id` (UUID string)
+  - `text` (string)
+  - `tags` (string[], optional)
+  - `scope` (string, optional: `global|sysadmin|k8s|...`)
+  - `created` (ISO datetime string)
+  - `created_by` (string, optional)
+  - `status` (string, optional: `active|deprecated`, default `active`)
+  - `supersedes` (string[], optional)
+
+**Deletion policy:**
+- Never delete entries; `--forget` marks `status=deprecated`.
+
+---
+
+## Documentation Work
+### 1) State schema documentation
+Create a structure-only schema document:
+- Suggested path: `~/.claude/docs/state-schemas.md`
+- Include required/optional fields and enums for:
+  - `system-instructions.json`
+  - `future-considerations.json`
+  - `model-policy.json`
+  - `autonomy-levels.json`
+  - `state/sysadmin/session-autonomy.json`
+  - `state/personal-assistant-preferences.json` (new)
+  - `state/personal-assistant/session-context.json` (new)
+  - `state/general-instructions.json` (new)
+
+### 2) CLAUDE.md overview updates
+Update `~/.claude/CLAUDE.md` “Shared State Files” table to add:
+- `~/.claude/state/personal-assistant-preferences.json` (writer: master-orchestrator)
+- `~/.claude/state/personal-assistant/session-context.json` (writer: user/CLI)
+- `~/.claude/state/general-instructions.json` (writer: master-orchestrator)
+
+---
+
+## Manual Validation Scenarios (Acceptance Checklist)
+### Parsing
+- `/pa -- --context appears in logs` should treat `--context` as literal text.
+
+### Context precedence
+- Set persistent default → set session override → request override wins.
+
+### Confirmation
+- `/pa --set-default-context <level>` prompts `Proceed? [y/N]`.
+
+### Routing and ambiguity
+- K8s request routes to K8s path via master-orchestrator.
+- Linux request routes to sysadmin path via master-orchestrator.
+- Ambiguous request triggers user clarification.
+
+### Memory ops
+- remember → list (active) → forget → list (active) hides deprecated → list --all shows deprecated
+
+---
+
+## Implementation Handoff
+### Recommended implementation order
+1. Add command file `~/.claude/commands/pa.md` describing contract and flags.
+2. Add new state file(s) with initial defaults:
+   - `state/personal-assistant-preferences.json` (persistent default)
+   - `state/personal-assistant/session-context.json` (empty or absent until set)
+   - `state/general-instructions.json` (empty `items: []`)
+3. Update `agents/personal-assistant.md` to:
+   - accept `/pa` command contract
+   - apply context precedence rules
+   - ask user on ambiguity
+   - delegate only to master-orchestrator
+4. Update `~/.claude/CLAUDE.md` shared state table.
+5. Add `~/.claude/docs/state-schemas.md`.
+6. Run through the manual validation checklist.
+
+### Notes / constraints
+- Keep files concise (per `system-instructions.json` content principles).
+- Avoid “duplicate truths”:
+  - CLAUDE.md should reference files, not restate schemas.
+  - Schema doc should define structure, not copy full JSON.
+- Respect ownership:
+  - `master-orchestrator` owns persistent state in `state/`.
+  - `user/CLI` writes session-only state files (mirroring sysadmin session autonomy).
--- a/docs/plans/2025-12-29-pa-personal-assistant-plan-revised.md
+++ b/docs/plans/2025-12-29-pa-personal-assistant-plan-revised.md
@@ -0,0 +1,215 @@
+# /pa Personal Assistant — Revised Plan (2025-12-29)
+
+## Changes from Original Plan
+
+| Decision | Original | Revised |
+|----------|----------|---------|
+| Coexistence with direct commands | Not addressed | Both patterns work: `/pa` for routing, direct commands for known ops |
+| Context level definitions | Specified levels | Abstract - PA interprets flexibly per request |
+| `general-instructions.json` owner | master-orchestrator | PA writes directly |
+| `general-instructions.json` location | `state/` | `state/personal-assistant/` |
+| Memory feature | Keep | Keep (JSON + UUID for efficiency/agent optimization) |
+
+---
+
+## Goals
+
+- Provide canonical entrypoint: `/pa`
+- PA routes requests by domain+intent, delegates via `master-orchestrator`
+- Configurable context-gathering (request/session/persistent override)
+- Persistent, structured memory optimized for agent consumption
+- Coexist with direct commands (`/deploy`, `/health`, etc.)
+
+---
+
+## Command Contract: `/pa`
+
+### File
+`~/.claude/commands/pa.md`
+
+### Frontmatter
+```yaml
+---
+name: pa
+description: Personal assistant entrypoint for routing and context-aware requests
+aliases: [assistant, ask]
+invokes: agent:personal-assistant
+---
+```
+
+### Parsing Rules
+- `/pa <request>` - natural language request
+- `/pa -- <request>` - `--` ends flag parsing, rest is literal
+
+### Flags
+
+**Context override (request-level, highest precedence):**
+- `/pa --context none|minimal|moderate|comprehensive -- <request>`
+
+**Session override (ephemeral):**
+- `/pa --set-context none|minimal|moderate|comprehensive`
+- `/pa --clear-context`
+
+**Persistent default (durable, requires confirmation):**
+- `/pa --set-default-context none|minimal|moderate|comprehensive`
+
+**Memory (PA writes directly):**
+- `/pa --remember -- "<instruction>"`
+- `/pa --list-mem` (active only)
+- `/pa --list-mem --all` (includes deprecated)
+- `/pa --forget <uuid>`
+
+**Introspection:**
+- `/pa --show-config`
+- `/pa --help`
+
+---
+
+## Context Granularity
+
+### Resolution Precedence
+1. Request override: `--context <level>`
+2. Session override: `state/personal-assistant/session-context.json`
+3. Persistent default: `state/personal-assistant-preferences.json`
+4. Hard default: `moderate`
+
+### Level Definitions
+Abstract - PA interprets flexibly based on request type:
+- `none` - Skip context gathering
+- `minimal` - Light context
+- `moderate` - Balanced (default)
+- `comprehensive` - Deep context scan
+
+Exact behavior evolves based on usage patterns.
+
+---
+
+## State Files
+
+### PA-Owned State (`state/personal-assistant/`)
+
+**1. Session context override**
+- Path: `~/.claude/state/personal-assistant/session-context.json`
+- Writer: user/CLI
+- Resets on session end
+
+```json
+{
+  "version": "1.0",
+  "current_context_level": "minimal",
+  "set_at": "2025-12-29T10:00:00Z",
+  "set_by": "user"
+}
+```
+
+**2. General instructions (memory)**
+- Path: `~/.claude/state/personal-assistant/general-instructions.json`
+- Writer: PA directly
+- Append-only with soft-delete
+
+```json
+{
+  "version": "1.0",
+  "description": "User instructions optimized for agent consumption",
+  "items": [
+    {
+      "id": "uuid-here",
+      "text": "Prefer British spelling",
+      "scope": "global",
+      "tags": ["style"],
+      "created": "2025-12-29T10:00:00Z",
+      "status": "active"
+    }
+  ]
+}
+```
+
+### Master-Orchestrator Owned State
+
+**3. Persistent PA preferences**
+- Path: `~/.claude/state/personal-assistant-preferences.json`
+- Writer: master-orchestrator
+
+```json
+{
+  "version": "1.0",
+  "description": "Persistent PA configuration",
+  "context_gathering": {
+    "default_level": "moderate"
+  }
+}
+```
+
+---
+
+## Routing Behavior
+
+### PA Responsibilities
+- Classify request by domain + intent
+- Use conversation context to reduce ambiguity
+- If still ambiguous: ask user (no guessing)
+- Delegate execution to master-orchestrator
+- Present unified result to user
+
+### Delegation
+PA never delegates directly to domain agents. Always routes via master-orchestrator:
+
+```
+User → /pa <request>
+         ↓
+    Personal Assistant (classify, gather context)
+         ↓
+    Master Orchestrator (coordinate, enforce)
+         ↓
+    Domain Agent (execute)
+         ↓
+    Results bubble up
+```
+
+### Coexistence with Direct Commands
+Both patterns valid:
+- `/pa deploy my-app` → PA classifies → routes → eventually runs deploy
+- `/deploy my-app` → Directly invokes deploy workflow
+
+Direct commands are power-user shortcuts; `/pa` is conversational interface.
+
+---
+
+## Documentation Updates
+
+### CLAUDE.md
+Add to "Shared State Files" table:
+- `state/personal-assistant-preferences.json` | PA config | master-orchestrator
+- `state/personal-assistant/session-context.json` | Session context | user/CLI
+- `state/personal-assistant/general-instructions.json` | User memory | personal-assistant
+
+### State Schemas Doc
+Add schemas for new files to `~/.claude/docs/state-schemas.md`
+
+---
+
+## Implementation Order
+
+1. Create `~/.claude/state/personal-assistant/` directory
+2. Create initial state files with defaults
+3. Create `~/.claude/commands/pa.md`
+4. Update `~/.claude/agents/personal-assistant.md` for `/pa` contract
+5. Update `~/.claude/CLAUDE.md` state table
+6. Update/create `~/.claude/docs/state-schemas.md`
+7. Manual validation per checklist
+
+---
+
+## Validation Checklist
+
+- [ ] `/pa -- --context` treats `--context` as literal text
+- [ ] Context precedence: request > session > persistent > default
+- [ ] `--set-default-context` prompts for confirmation
+- [ ] K8s request routes correctly via master-orchestrator
+- [ ] Sysadmin request routes correctly via master-orchestrator
+- [ ] Ambiguous request triggers user clarification
+- [ ] `--remember` adds to general-instructions.json
+- [ ] `--list-mem` shows active items
+- [ ] `--forget <uuid>` marks as deprecated
+- [ ] `--list-mem --all` shows deprecated items
+- [ ] Direct commands (`/deploy`, `/health`) still work independently