claude-code/docs/plans/2025-12-29-pa-personal-assistant-plan-revised.md

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