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