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

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