Getting Started

Install Propel, initialize your project, and run your first session in under 5 minutes.

1. Install Propel

Clone the repository and install in editable mode:

git clone https://github.com/KevinBian107/propel.git
cd propel && pip install -e .

2. Initialize in Your Project

Navigate to the project where you want to use Propel and run the init command:

cd /path/to/your/project
propel init

This does several things automatically:

• Copies all skills, agents, commands, and hooks into .claude/
• Configures the session-start hook in settings.local.json
• Adds scratch/, sessions/, .propel/, .claude/, and propel/ to .gitignore

3. Start Claude and Run /intro

Launch Claude Code in your terminal:

claude

Then inside Claude, run:

/intro

This does four things:

Mode Selection

Choose how you want to work. Each mode activates a different set of gates, skills, and agents:

• Researcher — literature review and investigation
• Engineer — full pipeline with all gates (default)
• Debugger — root-cause analysis with evidence-backed diagnosis
• Trainer — launch training runs and fix runtime errors

You can switch modes anytime with /switch.

Introduces Propel

Shows all available commands, skills, and agents along with their triggers.

Drafts Your CLAUDE.md

If you have an existing codebase, Propel scans it and generates a project-specific .claude/CLAUDE.md with code style, conventions, and structure already filled in. If you're starting from an empty repo, it seeds a minimal CLAUDE.md that grows progressively as you work — Gate 0 answers fill in research context, first code written fills in conventions, investigations fill in domain pitfalls.

Project Customization (Optional)

Analyzes your codebase to build a persistent profile in .propel/ that captures naming conventions, domain context, commit patterns, and more. Claude references this silently on every session start, so you don't have to re-explain your conventions. Takes ~2–3 minutes; you can also run it anytime by saying "customize Propel".

What Happens Next

Once your CLAUDE.md is set up, describe what you want to do. Propel will walk you through the gate pipeline:

1. Ask scoping questions (Gate 0) — before investigating
2. Scaffold an investigation — in scratch/{date}-{name}/README.md
3. Present findings (Gate 1) — before design
4. Propose a plan (Gate 2) — before implementation
5. Audit each component (Gate 3) — during implementation
6. Present diagnosis (Gate 4) — before any bug fix

Example First Session

You:  /intro
Claude: How do you want to work today?
        1. Researcher  2. Engineer  3. Debugger  4. Trainer

You:  2
Claude: Engineer Mode active. Full pipeline available.
        [explains Propel, lists all commands, skills, and agents]

You:  I want to implement residual vector quantization from this paper [link]

Claude: [Gate 0 fires — asks scoping questions one at a time]
        "Are you replacing the existing VQ entirely, or adding RVQ as
         an alternative?"
        "What depth? Is 2 a hard choice or should it support arbitrary
         depth?"
        ...

You:  [answer questions]

Claude: [writes scope statement, gets confirmation]
        [investigates codebase, creates scratch/2026-02-16-rvq/README.md]
        [Gate 1 — presents findings, asks design direction questions]

You:  [make design decisions]

Claude: [research-design produces paper-to-code mapping]
        [writing-plans breaks into micro-tasks]
        [Gate 2 — presents plan, asks about uncertainties]

You:  go

Claude: [implements component 1, runs auditors]
        [Gate 3 — presents audit results]
        ...

Key Slash Commands

All Propel commands are marked with [Propel] in their description.

What to Do After /clear

When you clear context mid-session, follow these steps to resume cleanly:

1. Run /primer to reload project context
2. Read your investigation README: scratch/{investigation}/README.md
3. Check the plan for where you left off: scratch/{investigation}/plan.md
4. Continue from the "Next Steps" section