Ramp

ramp

Adaptive, repo-grounded learning mode for Claude Code — it measures what you can do, not what you've clicked through.

Built by Bernie Green · Greenfield Labs

---

Why this exists

Claude Code adoption stalls for a predictable reason: the documentation is complete, but it doesn't adapt to you — your codebase, your current level, what you've already demonstrated. Most developers plateau at basic edits and multi-file changes. Hooks, worktrees, custom agents, MCP servers, and pipeline integration stay unexplored. The capability gap compounds.

/ramp:up solves this. Run it in any repo. It scans your environment — not just the codebase, but your Claude Code configuration, git history, session history, and prior progress. It asks at most 2–3 targeted questions about things that can't be detected. Then it delivers a personalized, repo-grounded learning path and stays engaged as your co-pilot for the rest of the session.

It's not a report. It's a mode.

> For teams, this is an onboarding engine. Companies deploy ramp as a project-level command so new engineers ramp up on Claude Code, the codebase, and the team's workflows from day one — starting from what each person already knows. Solo devs use it to level up. See [Company deployment](#company-deployment).

---

Quickstart

/plugin marketplace add gf-labs/gfl-marketplace
/plugin install ramp@gfl-marketplace

Then, in any repo:

/ramp:up

That's it. ramp detects your level, renders your personalized knowledge graph, and hands you your first mastery mission grounded in the actual files in front of you.

---

The commands

Nine commands, all namespaced /ramp:*. up is the engine; the rest read, reinforce, and maintain your graph.

| Command | What it does | |---------|--------------| | /ramp:up [topic] | Learning mode. Scans your environment, assesses your level, delivers a repo-grounded path, and co-pilots the session | | /ramp:list | Browse every topic and where you've started — read-only catalog | | /ramp:help | A 60-second orientation — what ramp is and the full command map | | /ramp:tree [topic\|all] | Read-only view of your knowledge graph — no inference, no writes | | /ramp:review [topic] | Spaced-repetition review of [✓] nodes due today — pass to advance, fail to reset | | /ramp:cheatsheet [topic]| A scannable personal reference built from your own evidence trails | | /ramp:pin [topic] | Mid-session checkpoint — status, save demonstrated nodes, optional MEMORY snapshot | | /ramp:wrap [topic] | End-of-session harvest — upgrade nodes, update the review schedule, optional snapshot | | /ramp:ingest [topic] [src] | Generate a new topic schema from an external source — a course curriculum, API docs, or a spec (PDF / URL / file) |

/ramp:up                                            # default topic: claude-code
/ramp:up I'm a new backend engineer joining the team
/ramp:up mcp-development I'm building a server
/ramp:up which skills apply to writing a good hook? # consultant mode, mid-session

---

Design principles

Detect before interrogating. Over 40 shell commands run at invocation — CLAUDE.md content, hook configs, MCP servers, worktree count, session history, headless invocations. By the time you see a question, /ramp:up has already determined your level and identified your gaps. You answer at most three questions, and they're specific.

Demonstrated over claimed. The graph distinguishes [✓] (demonstrated) from [~] (self-reported). A hook in settings.json is [✓|artifact]. Saying "yes, I've used hooks" is [~|reported]. A [✓] requires at least one verifiable detail — a flag, an observed behavior, a tradeoff navigated. The difference between "I've heard of hooks" and "I have a PostToolUse hook that fires my linter" is the entire gap between knowledge and practice.

Mastery missions, not checklists. Every node has a falsifiable mastery criterion and a repo-grounded exercise. Not "run your tests" — "run pytest tests/ on auth_service.py and interpret the failures."

Dependency-gated progression. You don't reach Agents until you've demonstrated Code Changes. The gates are the pedagogy.

Session-persistent, topic-namespaced. Graphs live at ~/.claude/knowledge-graphs/[topic].md and follow you across every repo. Returning users with a fresh graph (≤ 7 days) skip questions entirely. Progress is never lost.

Spaced repetition. [✓] nodes carry a | next: YYYY-MM-DD [LN] review schedule (1d → 3d → 7d → 21d → 60d → permanent). /ramp:review steps through due nodes one at a time. Pass = advance + XP. Fail = reset to L1.

Engine / curriculum separation. /ramp:up is topic-agnostic. The curriculum — nodes, detection signals, gap questions, mastery criteria, doc links — lives in schema files under topics/. Adding a topic means writing one file. The engine never changes.

---

Topics

| Topic | Command | Nodes | Focus | |-------|---------|-------|-------| | claude-code (default) | /ramp:up | 81 | Claude Code's feature surface — a meta-topic sourcing 5 sub-topics | | best-practices | /ramp:up best-practices | 15 | CLAUDE.md design, configuration patterns, session hygiene | | mcp-development | /ramp:up mcp-development | 29 | Building MCP servers: tools, resources, prompts, distribution | | anthropic-api | /ramp:up anthropic-api | 18 | Claude API: completions, tool use, agentic loops, production patterns | | claude-code-internals | /ramp:up claude-code-internals | 5 | Empirically-verified, undocumented Claude Code behaviors | | (your topic) | /ramp:up [topic] | any | Install a schema → it just works |

The claude-code meta-topic spans five sub-topics — Getting Started · Build · Configuration · Deployment · Administration — gated so you progress through them in order.

---

Three modes

/ramp:up adapts to what it finds when you run it.

| Context | What happens | |---------|-------------| | Existing repo | Scans codebase + env + history → renders the graph → delivers mastery missions → stays engaged as session co-pilot | | Empty / new repo | Asks what to build → builds it with you → narrates every Claude Code capability as it's used → renders the graph from what was demonstrated | | Directory of repos | Surveys all repos (name, stack, last activity) → you pick a focus → proceeds as single-repo mode |

---

The knowledge graph

81 nodes for claude-code, every one grounded in Claude Code's actual feature surface.

[Getting Started] Core Foundations
    [✓] What Claude Code does and when to use it
    [✓] How Claude Code uses computers (tool loop)
    [★] Memory types and scope hierarchy

[Build] Agents and Orchestration
    [✓] Subagent basics: spawning and tool access
    [~] Foreground vs. background subagents
    [★] Custom subagent definitions (.claude/agents/)

[Build] Hooks System
    [✓] PostToolUse hooks (linting, reactions)
    [★] PreToolUse hooks (validation, blocking)

[Build] Headless and MCP
    [~] Headless mode (-p flag, non-interactive)
    [ ] MCP: configure and use servers

[Configuration] Settings Fundamentals
    [✓] Settings scope hierarchy: global, project, local

[·] Deployment        (unlock: complete Configuration)
[·] Administration    (unlock: complete Deployment)

Your frontier: → Memory types [★]  → CLAUDE.md as living memory [★]  → PreToolUse hooks [★]
Level: Builder — hooks and commands demonstrated, moving into orchestration

Marker key: [✓] demonstrated · [~] self-reported · [ ] not yet · [★] mastery target · [·] locked

Each [★] becomes a mastery mission — a falsifiable criterion plus a repo-grounded exercise using your real file names and toolchain.

> View it any time with /ramp:tree (read-only), or build a personal reference from your evidence trails with /ramp:cheatsheet. See [docs/tree-format.md](docs/tree-format.md) for the annotated graph format.

Spaced-repetition review

/ramp:review runs a focused session over demonstrated [✓] nodes that are due today — no assessment, no new skills, just reinforcement.

• Finds all [✓] nodes where next: YYYY-MM-DD ≤ today
• Asks one targeted question per node
• Pass (specific detail) → advance one level, next date from the interval ladder
• Fail (vague or none) → reset to L1, review again tomorrow

Interval ladder: L1 = 1d · L2 = 3d · L3 = 7d · L4 = 21d · L5 = 60d · L6 = permanent.

---

Company deployment

ramp is built to onboard engineers. Two artifacts work together — one static, one active.

Two tools, two purposes

| | ONBOARDING.md | Custom topic schema | |--|---|---| | Format | Static markdown doc | Active knowledge-graph session | | When used | Day 1: "how do I run this?" | First week: guided onboarding with exercises | | Personalized? | No — same doc for everyone | Yes — starts from what the dev already knows | | Progress tracking | No | Yes — evidence trails, XP, spaced repetition | | Generated by | /ramp:up Phase 4 option b | /ramp:up [your-topic] | | Committed to repo? | Yes (optional) | Schema yes; knowledge graphs stay personal |

Use both: ONBOARDING.md as the quick-start reference, a custom topic for the active ramp-up.

Step 1 — Commit the commands

Copy the command files into your team repo's .claude/commands/ so engineers get them on clone:

cp commands/up.md     /your-team-repo/.claude/commands/ramp.md
cp commands/tree.md   /your-team-repo/.claude/commands/tree.md
cp commands/review.md /your-team-repo/.claude/commands/review.md

Knowledge graphs (~/.claude/knowledge-graphs/) stay personal — they live on each developer's machine, not in the repo.

Step 2 — Create a custom topic schema (recommended)

Add .claude/knowledge-graphs/schemas/[your-topic].md to the team repo. This is the curriculum for onboarding to this codebase — nodes, detection signals, gap questions, and mastery criteria specific to your project.

.claude/
└── knowledge-graphs/
    └── schemas/
        └── acme-onboarding.md   ← commit this

Example nodes: [ROOT] Environment setup (make setup, .env, local run), [A] Architecture (data flow, service ownership), [B] Dev workflow (PR process, test suite, deploy), [C] Team practices (escalation, monitoring). See [topics/claude-code.md](topics/claude-code.md) for the full schema format — once committed, engineers clone and run /ramp acme-onboarding.

Step 3 — Add team context to CLAUDE.md

/ramp:up reads an ## Onboarding section and folds it into every session and the generated ONBOARDING.md:

## Onboarding
- Run `make setup` before anything else
- Read `docs/architecture.md` for system design context
- Auth system owned by @alice, data pipeline by @bob
- Ask in #dev-help — 30-minute rule before escalating
- Deploy: PR → staging → 24h soak → prod

After a session, /ramp:up also offers to bootstrap the repo's Claude Code setup — create a CLAUDE.md, add starter hooks, write a custom command — if any are missing.

---

Install

From the GFL marketplace (recommended). ramp is published through the gf-labs/gfl-marketplace catalog, alongside tools:

/plugin marketplace add gf-labs/gfl-marketplace
/plugin install ramp@gfl-marketplace

From a local clone (dev / offline). ramp is also its own single-plugin marketplace, so you can add the clone directly — note the install name is ramp@ramp here, not @gfl-marketplace:

git clone https://github.com/gf-labs/ramp ~/path/to/ramp

/plugin marketplace add ~/path/to/ramp
/plugin install ramp@ramp

Hooks (the passive observer) and topic schemas are set up automatically on first session start. Update with /plugin marketplace update gfl-marketplace.

Add a community topic:

cp your-topic.md ~/.claude/knowledge-graphs/schemas/your-topic.md
/ramp:up your-topic

---

The passive observer

A hook watches every Claude Code session and upgrades ~/.claude/knowledge-graphs/claude-code.md whenever it detects skill evidence — no need to run /ramp:up. scripts/skill-observer.py listens on two events (PostToolUse, SessionStart) and detects, for example:

• git worktree add → Worktrees [✓|historical]
• claude -p → Headless mode [✓|historical]
• Writes to .claude/agents/*.md → Custom subagent definitions [✓|historical]
• Writes to settings.json with a hooks key → PostToolUse hooks [✓|historical]
• Writes to settings.json with an mcpServers key → MCP servers [✓|historical]

> What it can't see: built-in CLI commands (/help, /compact, /usage, /doctor) never enter the tool loop, so no hook fires. Those are captured through /ramp:up's assessment, which can promote a [~|reported] node to [✓].

The observer ships in the plugin and registers automatically on install. Verify it with cat ~/.claude/knowledge-graphs/claude-code.md after a session.

---

MCP server — knowledge-graph

mcp/server.py is an optional MCP server that gives /ramp:up structured read/write access to your graphs — atomic local saves, plus a client for cross-device sync and team/org layers when paired with a compatible backend (not included in this repo).

Why use it. Without the MCP, /ramp:up reads graphs via a bash cat and writes via the Write tool. With it, reads and writes go through structured tools — enabling swappable backends (local files → hosted API) without changing up.md.

| Tool | Description | |------|-------------| | read_graph(topic) | Read a knowledge graph — returns markdown | | save_graph(topic, content) | Atomic write + optional backend sync | | list_topics() | All topics with level and XP — returns JSON | | get_benchmarks(topic) | Personal stats; team/org when a backend is configured | | export_delta(topic, since_date) | Demonstrated nodes since a date — for team sharing |

Setup. Create the repo-local virtualenv (the system python3 ships a conflicting mcp stub, so the server must run from .venv):

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

> The MCP server is opt-in — it is not configured automatically, and ramp works fully without it. To enable it, run the venv setup above, then the registration block below. (Or, from the plugin's install directory, run python3 scripts/setup-mcp.py to provision the venv and register the server in one step.)

Add to ~/.claude.json (global user-scope MCP config) — point command at the venv python, or use ./mcp/start.sh, which resolves it for you:

{
  "mcpServers": {
    "knowledge-graph": {
      "type": "stdio",
      "command": "/absolute/path/to/ramp/.venv/bin/python3",
      "args": ["/absolute/path/to/ramp/mcp/server.py"]
    }
  }
}

Hosted backend (team / org). Set KNOWLEDGE_GRAPH_API_URL and the server proxies read_graph/save_graph to GET/PUT /graphs/{topic} and get_benchmarks to GET /benchmarks/{topic}. A compatible backend service would then unlock cross-device sync, team skill matrices, and org dashboards; without one, the server falls back to local files. This repo ships the client side only — the backend service is not included.

---

Schemas vs. knowledge graphs

Two different things live in ~/.claude/knowledge-graphs/:

| | Location | Contains | Created by | |--|----------|----------|------------| | Schema | …/schemas/[topic].md | Curriculum blueprint: nodes, detection signals, gap questions, mastery criteria, doc links | Plugin install (auto-symlinked from topics/ on first session start) | | Knowledge graph | …/[topic].md | Your progress: no

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gf-labs
• Source: gf-labs/ramp
• License: MIT

Install and usage instructions live in the source repository linked above.