Customization

How to add project-specific agents, skills, commands, and gate overrides to Propel.

Automatic Project Profiling

Propel can auto-detect your project's coding conventions, domain context, and development patterns, creating a persistent profile that Claude references on every session start. The profile lives in .propel/ (gitignored).

How It Works

Run /intro and accept the Part 3 offer, or say "customize Propel" at any time. Propel runs six phases:

1. Scan project structure — language, framework, dependencies, directory layout, build tools
2. Analyze code style — naming conventions, import patterns, formatting, type hints, docstrings (from 5–10 source files)
3. Detect domain — classify from imports; optionally delegate to env-researcher or deep-research agents for detailed context
4. Analyze git history — commit style, branch naming, active areas, team size
5. Read existing conventions — CLAUDE.md, CONTRIBUTING.md, CI configs, linter configs, editor configs
6. Present profile for confirmation — you review and approve before anything is written

Output Files

All output goes to .propel/ (gitignored):

What Gets Detected

The analysis covers the following categories in detail:

Delta Updates

On subsequent runs, Propel hashes key project files and compares against the stored hash. If nothing changed, it confirms the profile is current. If files changed, it re-analyzes only the affected categories and shows you a diff before updating.

Adding Custom Agents

Propel's agents are defaults. You can add project-specific agents in your own .claude/agents/ directory — they take precedence over Propel's built-in agents.

Example: PyTorch Logic Auditor

If your project uses PyTorch instead of JAX, create .claude/agents/torch-logic-auditor.md:

---
name: torch-logic-auditor
description: "PyTorch-specific logic auditor. Replaces jax-logic-auditor."
tools: Read, Grep, Glob
---

You are a PyTorch logic auditor...
[Your PyTorch-specific checks here]

Example: Domain-Specific Auditor

For robotics projects, you might add .claude/agents/sim-real-gap-auditor.md:

---
name: sim-real-gap-auditor
description: "Checks for sim-to-real transfer issues..."
tools: Read, Grep, Glob
---

[Auditor content]

Agent Design Principles

1. One-shot context — Agents have no conversation history. Their prompt must be self-contained.
2. Read-only by default — Auditors should only read code, not modify it.
3. Structured output — Use the output format template from existing agents.
4. Specific trigger conditions — The description field determines when the agent gets dispatched.

Adding Custom Skills

Add skills to .claude/skills/ in your project. They integrate with Propel's existing workflow. Each skill has a SKILL.md file with YAML frontmatter (name, description) and markdown body.

Example: Hardware Deployment Skill

Create .claude/skills/hardware-deployment/SKILL.md:

---
name: hardware-deployment
description: >
  Guides the deployment of trained policies to physical hardware.
  Use when the user says "deploy to robot", "run on hardware",
  "sim to real".
---

# Hardware Deployment

## Pre-Deployment Checklist
- [ ] Policy verified in simulation
- [ ] Action scaling verified (sim units -> hardware units)
- [ ] Safety limits configured
- [ ] Fallback behavior defined

Adding Custom Commands

Add slash commands to .claude/commands/ in your project. Use $ARGUMENTS for parameterization.

Example: Run Training

Create .claude/commands/train.md:

Run a training experiment with the configuration in $ARGUMENTS.

## Process
1. Verify the config exists and is valid
2. Run a 100-step smoke test first
3. If smoke test passes, launch full training
4. Monitor the first 1000 steps for NaN/explosion

Then invoke it with /train configs/rvq-base.yaml.

Customizing Gate Behavior

You can adjust gate behavior by adding instructions to your project's CLAUDE.md. Gates can be expanded (stricter) or abbreviated (lighter) depending on context.

Example: Gate Overrides

## Propel Overrides

### Gate 0 (Intake)
- For routine experiments (hyperparameter sweeps), Gate 0 can
  be abbreviated to a single scope confirmation.
- For novel implementations, full Gate 0 is mandatory.

### Gate 3 (Mid-Implementation)
- For this project, always include the sim-real-gap-auditor
  in the audit dispatch.

Mode-Specific Overrides

Propel's four modes (Researcher, Engineer, Debugger, Trainer) have default skill/gate assignments, but you can override these per-project:

## Propel Mode Overrides

### Trainer Mode
- Allow Trainer Mode to adjust hyperparameters in config files
- Architecture, loss, and data pipeline changes still require
  /switch engineer

### Default Mode
- Default to trainer mode — this project is in the training phase

Customizing Auditor Dispatch

The subagent-driven-research/auditor-dispatch.md file contains the dispatch rules. To add your project-specific auditor to the dispatch:

1. Add the agent file to your .claude/agents/ directory
2. Add a dispatch rule in your CLAUDE.md:

## Auditor Dispatch Override
After modifying any file in `envs/` or `controllers/`,
also dispatch sim-real-gap-auditor.

Project CLAUDE.md Integration

Reference Propel in your project's CLAUDE.md to tie everything together:

## Workflow
This project uses the Propel research workflow.
Skills, agents, and commands are in .claude/ (installed via `propel init`).
See propel docs for the investigation -> design -> implement -> validate pipeline.

## Project-Specific Notes
- Our configs are in `configs/` — existing configs must not change behavior
- Paper references are in `docs/papers/` — use /read-paper to extract them
- Training scripts expect wandb to be configured