prime git:20260626.d9fb956A

Immutable. This exact content is served forever at /api/v1/blob/fb4d1555b2cf3934.

---
name: prime
description: "Use when onboarding to the Valor AI codebase, understanding the system architecture, or when the user asks 'how does this work'. Comprehensive codebase orientation guide."
disable-model-invocation: true
---

# Prime - Codebase Onboarding

Get up to speed on the Valor AI system to add new features effectively.

## What This Is

This is **Valor** - an AI coworker that runs on its own Mac. Not an assistant, not a tool - a colleague with agency. The supervisor assigns work, Valor executes autonomously.

**You ARE this codebase.** When users say "you" or "your features," they mean this code.

## Current Architecture

```
Telegram → Python Bridge (Telethon) → Claude Agent SDK → Claude API
```

**Key components:**
- **Python Bridge** (`bridge/telegram_bridge.py`): Handles Telegram user account via Telethon
- **Claude Agent SDK** (`agent/sdk_client.py`): AI orchestration, calls Claude API
- **MCP Servers** (`.mcp.json`): Modular capabilities (Sentry, Notion, etc.); GitHub via `gh` CLI
- **Identity Config** (`config/identity.json`): Structured identity data + persona segments

## Directory Layout

```
ai/                          # This repo
├── .claude/skills/          # Project-specific skills
├── .claude/skills-global/   # Cross-repo shared skills (/prime, /pthread, /sdlc)
├── agent/                   # Claude Agent SDK integration
├── bridge/                  # Telegram bridge
├── config/identity.json      # Structured identity data
├── config/personas/segments/ # Composable prompt segments
├── scripts/valor-service.sh # Service management
├── docs/                    # Documentation
└── CLAUDE.md                # Development guide (READ THIS)
```

## Read These Files

**In order:**
1. `CLAUDE.md` - Development principles, commands, architecture
2. `config/personas/segments/` - Valor's identity, work patterns, and tools

## How to Add Features

### New Claude Code Skill

Create `.claude/skills-global/<name>/SKILL.md` for cross-repo skills, or `.claude/skills/<name>/SKILL.md` for project-specific ones.

### Permission Model

| Pattern | Behavior | Use For |
|---------|----------|---------|
| `accept` | Auto-approve | Read ops (list, get) |
| `prompt` | Ask user | Write ops (create, update) |
| `reject` | Block | Dangerous ops (delete) |

## Service Management

```bash
./scripts/valor-service.sh status   # Check if running
./scripts/valor-service.sh restart  # Restart after changes
./scripts/valor-service.sh logs     # View logs
```

## Key Principles

1. **Always commit and push** - Never leave work uncommitted
2. **No legacy code** - Delete obsolete code completely
3. **Critical thinking** - Question assumptions, validate decisions
4. **Self-improving** - Valor can modify his own code and restart

## Thread Types (for complex work)

| Type | Use Case |
|------|----------|
| Base | Single task |
| P-Thread | Parallel independent work |
| C-Thread | Chained phases with checkpoints |
| L-Thread | Extended autonomous work |

## Quick Actions

**Check system status:**
```bash
./scripts/valor-service.sh status
tail -20 logs/bridge.error.log
```

**After making changes:**
```bash
git add . && git commit -m "Description" && git push
./scripts/valor-service.sh restart
```

---

*Run `/prime` at the start of any session to get oriented.*