prime git:20260705.5a5efb9A

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

---
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 oriented in the Valor AI system well enough to add 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 → Bridge (Telethon) → Redis AgentSession queue (bridge is I/O only)
Standalone Worker (python -m worker) → sole session execution engine → Claude Agent SDK / granite PTY
Reflection scheduler (python -m reflections) → own launchd subprocess; enqueues recurring work the worker executes
```

**Key components:**
- **Bridge** (`bridge/telegram_bridge.py`): Telegram user account via Telethon; enqueues sessions and routes output (nudge loop) — no SDLC awareness
- **Worker** (`worker/__main__.py`): executes AgentSessions via the Claude Agent SDK (`agent/sdk_client.py`)
- **MCP Servers** (`.mcp.json`): modular capabilities (memory, BYOB, Sentry, Notion); GitHub via `gh` CLI
- **Identity** (`config/identity.json` + `config/personas/segments/`): structured identity data and composable persona segments

## Directory Layout

```
ai/                          # This repo
├── .claude/skills/          # Project-only skills (/prime, /setup, /sdlc, /update, /do-deploy)
├── .claude/skills-global/   # Global skills — hardlinked to ~/.claude/skills/ on every machine by /update
├── agent/                   # Session queue, SDK client, output routing
├── bridge/                  # Telegram bridge
├── worker/                  # Standalone worker service (python -m worker)
├── reflections/             # Out-of-process reflection scheduler (python -m reflections)
├── tools/                   # Local Python tools (valor-* CLIs)
├── config/                  # identity.json, personas/segments/, reflections.yaml
├── scripts/valor-service.sh # Service management
├── docs/features/           # Feature index — how things actually work
└── 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
3. `docs/features/README.md` - feature index, when you need how-something-works detail

## How to Add Features

Create `.claude/skills-global/<name>/SKILL.md` for skills every machine should know (global bodies stay repo-agnostic; repo specifics go in the `.claude/skill-context/` seam), or `.claude/skills/<name>/SKILL.md` for project-only skills. See "Global vs. Project-Only Skills" in `CLAUDE.md`.

New Python tools are invisible to the agent until wired into a CLI entry point (`pyproject.toml [project.scripts]`) or imported by the bridge directly.

## Service Management

```bash
./scripts/valor-service.sh status   # Check if running
./scripts/valor-service.sh restart  # Restart bridge, watchdog, and worker 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
5. **Parallelize independent work** - spawn parallel subagents for independent tasks; never for sequential/dependent work

## Quick Actions

**Check system status:**
```bash
./scripts/valor-service.sh status
tail -20 logs/bridge.error.log
curl -s localhost:8500/dashboard.json   # full system state as JSON
```

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