Implement programmer agent system and consolidate agent infrastructure
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>
This commit is contained in:
OpenCode Test
215
docs/plans/2025-12-29-pa-personal-assistant-plan-revised.md
Normal file
215
docs/plans/2025-12-29-pa-personal-assistant-plan-revised.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# /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
|
||||
Reference in New Issue
Block a user