431e10b449
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>
209 lines
7.3 KiB
Markdown
209 lines
7.3 KiB
Markdown
# /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).
|