Valor

An autonomous AI coworker. Not an assistant, not a chatbot — a colleague that owns its own machine and does real work.

Why Valor?

Works where you work. Receives tasks via Telegram or Email and replies in the same thread — no context switching, no dashboards to check.
Ships code end-to-end. Plans a feature, critiques the plan, writes the code, runs tests, opens a PR, and merges it — without being babysat through each step.
Remembers across sessions. A subconscious memory system injects relevant past decisions and corrections as <thought> blocks at exactly the right moment.
Fixes itself. A watchdog + self-healing pipeline restarts on crashes, hibernates on API failures, and escalates to you only when automation can't recover.
Extensible by design. Add a new skill in .claude/skills/, wire a tool in tools/ + MCP, or connect a new comms channel in bridge/ — the architecture absorbs extensions without surgery.

What Is This?

Valor wraps agent harnesses (like Claude Code) and bridges them to the comms channels humans actually use (Telegram, Email, LinkedIn, and more). The supervisor assigns work and provides direction. Valor executes autonomously on its own Mac, reaching out when necessary.

How It Works

Three layers:

Comms layer — bridges to the channels where work actually happens: Telegram, Email, LinkedIn, etc. Messages come in, replies go out, session context survives across conversations.
Harness layer — wraps agent harnesses like Claude Code, giving Valor tools, memory, skills, and a full SDLC workflow.
Execution layer — a standalone worker service runs sessions against the configured harness. Sessions come in three role flavors: PM (orchestrates work), Dev (writes code), and Teammate (conversational).

Architecture

See docs/features/bridge-worker-architecture.md for the full design.

📸 TODO: Add demo GIF or screenshot here — see docs/assets/ for placement instructions.

The SDLC Pipeline

Valor ships real features through a structured pipeline — a directed cyclic graph with failure cycles, not a straight line. Each stage is a skill the agent invokes, and each stage runs on the model best suited to its cognitive load: Opus for hard reasoning (Plan, Critique, Review) and Sonnet for plan execution and tool-heavy work (Build, Test, Patch, Docs).

Cycles are first-class. Critique loops back to Plan when concerns surface. Test→Patch→Test iterates until the fix holds. Review→Patch→Test→Review repeats until findings clear.
Hard patches resume the builder. When a Patch needs the original builder's accumulated context, PM resumes the Build session's Claude Code transcript instead of starting fresh — the dashed edge in the diagram.
PM orchestrates, Dev executes. A read-only PM session steers the pipeline stage-by-stage; each stage spawns a full-permission Dev session that runs one skill and reports back.

The pipeline graph is defined in agent/pipeline_graph.py. See .claude/skills/sdlc/SKILL.md for the ground truth on stage definitions and docs/features/pipeline-graph.md for the feature doc.

Subsystems

Subsystem	Purpose
Subconscious memory	Long-term memory with bloom-filter recall, intentional saves, and post-session extraction
Reflections	Daily autonomous maintenance pipeline (log review, audits, cleanup, reporting)
Autoexperiment	Nightly prompt optimization for observer/summarizer targets
Self-healing	Watchdog service with crash tracking and automatic recovery
Session steering	Inject guidance into running sessions from any process
Worktree isolation	Per-feature git worktrees for parallel work without collisions
Dashboard	Web UI showing sessions, health, reflections, and machine state

Quick Start

# 1. Install dependencies
pip install -e .

# 2. Configure environment (symlink to vault)
ln -sf ~/Desktop/Valor/.env ~/src/ai/.env
# All secrets live in ~/Desktop/Valor/.env (iCloud-synced vault)

# 3. Start the bridge and worker
./scripts/start_bridge.sh
./scripts/valor-service.sh worker-start

Service Management

./scripts/valor-service.sh status          # Bridge status
./scripts/valor-service.sh restart         # Restart bridge after code changes
./scripts/valor-service.sh worker-status   # Worker status
./scripts/valor-service.sh worker-restart  # Restart worker
tail -f logs/bridge.log                    # Stream logs

Repository Layout

ai/
├── agent/               # Session queue, SDK client, output routing
├── bridge/              # Comms bridges (Telegram, etc.) and nudge loop
├── worker/              # Standalone worker service (python -m worker)
├── tools/               # Local Python tools
├── ui/                  # Dashboard web UI
├── monitoring/          # Watchdog, crash tracker, health checks
├── .claude/
│   ├── skills/          # SDLC and utility skills
│   ├── commands/        # Slash commands
│   └── agents/          # Subagent definitions
├── config/              # identity.json, persona segments, projects.json
├── scripts/             # Service management, setup, deployment
├── docs/features/       # Feature-level documentation
└── tests/               # Unit, integration, e2e

Development

pytest tests/unit/ -n auto     # Fast unit tests in parallel
pytest tests/                  # Full suite
python -m ruff format .        # Format

Name	make-plan
Description	Create or update feature plan documents using Shape Up principles. Use when the user wants to plan a new feature, flesh out a plan, update an existing plan, or needs a structured approach to scoping work. Outputs to docs/plans/{slug}.md with problem statement, appetite, solution, risks, and boundaries.

Resource	Purpose
CLAUDE.md	Development principles and working guide
docs/features/README.md	Feature index — how things work
config/identity.json	Structured identity data
config/personas/segments/	Composable persona segments
tests/README.md	Test suite index and contribution guide

make-plan

SKILL.md