prime

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

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

./scripts/valor-service.sh status
tail -20 logs/bridge.error.log

After making changes:

git add . && git commit -m "Description" && git push
./scripts/valor-service.sh restart

---

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