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

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

{
  "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

{
  "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

{
  "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