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>

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).