prime · diff

git:20260411.5712c0d to git:20260626.d9fb956

3 added, 2 removed. Audit A to A.

---

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/ # Claude Code skills (/prime, /pthread, /sdlc)

+ ├── .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/<name>/SKILL.md` with instructions for Claude Code to follow.

+ 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.*