@slope-dev/slope

SLOPE

Sprint Lifecycle & Operational Performance Engine

Quantified sprint metrics for AI-assisted development. Scorecards, handicap tracking, and real-time agent guidance for Claude Code, Cursor, Windsurf, Cline, OB1, and OpenCode.

Setup

Install SLOPE as a dev dependency in your project:

npm install --save-dev @slope-dev/slope

Then initialize from inside your AI coding tool. Pick your platform below and paste the prompt.

---

Claude Code

The most fully-featured integration — context injection, guard hooks, slash commands, and MCP.

Paste this prompt into Claude Code:

Install and initialize SLOPE for this project. Run:

1. npx slope init --claude-code --interactive --smart
2. npx slope hook add --level=full
3. npx slope map

This will create .claude/rules/, .claude/hooks/, .claude/commands/, .mcp.json, and CLAUDE.md.
After init, verify the MCP server works by running the `search` MCP tool with an empty query.

What you get:

Component	Location	Purpose
Rules	.claude/rules/*.md	Sprint checklist, commit discipline, review loop, codebase context
Guard hooks	.claude/hooks/slope-guard.sh	22 real-time guards configured in .claude/settings.json
Slash commands	.claude/commands/*.md	/start-sprint, /post-sprint, /review-pr workflow automation
MCP server	.mcp.json	search() to discover API, execute() to run SLOPE commands
Project context	CLAUDE.md	Project-wide context with SLOPE workflow summary
Codebase map	CODEBASE.md	Auto-generated index for agent navigation

Slash commands (Claude Code exclusive):

• /start-sprint — pre-sprint setup: briefing, branch creation, sprint state, prior scorecard verification
• /post-sprint — scorecard creation, validation, review, common-issues distillation
• /review-pr — structured PR review with finding tracking and scorecard amendment

---

Cursor

Full guard support with context injection and MCP.

Paste this prompt into Cursor:

Install and initialize SLOPE for this project. Run these commands in the terminal:

1. npx slope init --cursor --interactive --smart
2. npx slope hook add --level=full --harness=cursor
3. npx slope map

This will create .cursor/rules/, .cursor/hooks/, .cursor/mcp.json, .cursorrules, and CODEBASE.md.

What you get:

Component	Location	Purpose
Rules	.cursor/rules/*.mdc	Sprint checklist, commit discipline, review loop, codebase context
Guard hooks	.cursor/hooks/slope-guard.sh	Guards configured in .cursor/hooks.json
MCP server	.cursor/mcp.json	API search and command execution
Project context	.cursorrules	Project-wide context

---

Windsurf

Guard support with blocking (no context injection).

Paste this prompt into Windsurf:

Install and initialize SLOPE for this project. Run these commands in the terminal:

1. npx slope init --windsurf --interactive --smart
2. npx slope hook add --level=full --harness=windsurf
3. npx slope map

This will create .windsurf/rules/, .windsurf/hooks/, .windsurf/mcp.json, .windsurfrules, and CODEBASE.md.

What you get:

Component	Location	Purpose
Rules	.windsurf/rules/*.mdc	Sprint checklist, commit discipline, review loop, codebase context
Guard hooks	.windsurf/hooks/slope-guard.sh	Exit-code based guards in .windsurf/hooks.json
MCP server	.windsurf/mcp.json	API search and command execution
Project context	.windsurfrules	Project-wide context

Note: Guards can block/allow actions but cannot inject guidance text into agent context.

---

Cline

Full guard support with per-event hook scripts. MCP requires manual setup.

Paste this prompt into Cline:

Install and initialize SLOPE for this project. Run these commands in the terminal:

1. npx slope init --cline --interactive --smart
2. npx slope hook add --level=full --harness=cline
3. npx slope map

This will create .clinerules/, .clinerules/hooks/, and CODEBASE.md.

After init, I need to manually add the MCP server through the Cline VS Code extension.
Read .clinerules/slope-context.md for the MCP configuration instructions.

What you get:

Component	Location	Purpose
Rules	.clinerules/*.md	Sprint checklist, commit discipline, review loop, codebase context
Guard hooks	.clinerules/hooks/	Per-event scripts (PreToolUse, PostToolUse, TaskCancel, PreCompact)
MCP instructions	.clinerules/slope-context.md	Setup guide for manual MCP configuration

Note: MCP server must be configured manually through the Cline VS Code extension UI.

---

OB1

Guard support with per-event hook scripts and MCP.

Paste this prompt into OB1:

Install and initialize SLOPE for this project. Run these commands:

1. npx slope init --ob1
2. npx slope hook add --level=full --harness=ob1
3. npx slope map

This will create .ob1/hooks/, .ob1/mcp.json, and CODEBASE.md.

What you get:

Component	Location	Purpose
Guard hooks	.ob1/hooks/	Per-event scripts (pre_tool, post_tool, post_agent)
MCP server	.ob1/mcp.json	API search and command execution

---

OpenCode

Plugin-based integration with MCP.

Paste this prompt into OpenCode:

Install and initialize SLOPE for this project. Run these commands:

1. npx slope init --opencode
2. npx slope map

This will create opencode.json, .opencode/plugins/, AGENTS.md, and CODEBASE.md.
For roadmap planning intake, run `npx slope roadmap interview --agent` or ask the MCP server for `search({ module: "init" })`.

What you get:

Component	Location	Purpose
Plugin	.opencode/plugins/slope-plugin.ts	Session lifecycle hooks
MCP server	opencode.json	API search and command execution
Project context	AGENTS.md	Project-wide context

---

Platform Capabilities

	Claude Code	Cursor	Windsurf	Cline	OB1	OpenCode
Context injection	Yes	Yes	--	Yes	Yes	--
PreToolUse guards	Yes	Yes	Yes	Yes	Yes	--
PostToolUse guards	Yes	Yes	Yes	Yes	Yes	--
Stop/session-end	Yes	Yes	--	Yes	Yes	Yes
PreCompact	Yes	--	--	Yes	--	--
Slash commands	Yes	--	--	--	--	--
MCP auto-install	Yes	Yes	Yes	Manual	Yes	Yes
Rules/context files	Yes	Yes	Yes	Yes	--	Yes

What SLOPE Does

SLOPE replaces subjective retrospectives with quantified sprint metrics. Every sprint gets a scorecard that tracks each ticket's approach complexity, outcome, and hazards encountered. Over time, your handicap card reveals patterns — do you consistently over-engineer? Under-scope? Pick the wrong approach?

For AI-assisted development, SLOPE also provides real-time agent guidance: 22 guard hooks that inject context, warnings, and blocks into your coding agent's workflow as you work.

Core Concepts

Concept	What it measures
Par	Expected sprint baseline (1-2 tickets = 3, 3-4 = 4, 5+ = 5)
Slope	Difficulty modifier (cross-package changes, migrations, new infra)
Club	Approach complexity (driver = risky/new, putter = trivial)
Result	Outcome (in_the_hole = perfect, missed_long = over-engineered)
Hazard	Gotchas encountered (rough = code quality, water = security, bunker = architecture)
Handicap	Rolling performance trend across sprints

Don't like golf terms? SLOPE supports 7 pluggable metaphors — same math, your vocabulary.

Guard Hooks

Guards are the real-time guidance system. They fire on specific tool calls and inject context, warnings, or blocks into your agent's workflow. They're installed automatically by slope hook add --level=full.

Guard	Fires on	What it does
explore	Read/Glob/Grep/Edit/Write	Suggests checking codebase map; blocks edits when map is 31+ commits stale
hazard	Edit/Write	Warns about known issues in areas being edited
sprint-completion	gh pr create / session end	Blocks PR without scorecard; blocks session end with incomplete gates
commit-nudge	Edit/Write	Nudges to commit after prolonged editing
push-nudge	Bash (git commit)	Nudges to push when unpushed commits pile up
scope-drift	Edit/Write	Warns when editing files outside claimed ticket scope
subagent-gate	Agent	Enforces model selection on Explore/Plan subagents
branch-before-commit	Bash (git commit)	Blocks commits directly on main/master
workflow-gate	ExitPlanMode	Blocks plan exit until review rounds complete
version-check	Bash (git push)	Blocks push when package versions haven't been bumped
stop-check	Session end	Warns about uncommitted/unpushed work
next-action	Session end	Suggests next actions before session ends

Plus 10 more for review workflows, transcript recording, worktree safety, and flow staleness detection. Run npx slope guard list to see all available guards.

MCP Server

The SLOPE MCP server gives your agent direct access to the scoring engine. It's auto-configured during slope init for all platforms except Cline.

# Discover all available API functions
search({})

# Search for specific functionality
search({ query: 'handicap' })
search({ module: 'map' })          # Get the codebase map

# Execute SLOPE code in a sandbox
execute({ code: 'return computeHandicapCard(loadScorecards())' })

CLI Reference

All commands use npx slope when installed locally.

Default help is intentionally small:

Command	Description
npx slope now	Compact current-state cockpit: current sprint, state, claims, next action
npx slope start [--ticket=KEY]	Start or begin work without exposing sprint/claim plumbing
npx slope help	Human command surface for daily work, setup, and direction
npx slope help <command>	Detailed usage for one command
npx slope help --all	Full command registry with audience labels

Commands are classified as human, agent, advanced, or internal. Humans should usually start with the default help surface; skills and agents orchestrate the rest of the CLI as execution primitives.

Setup

Command	Description
npx slope init	Initialize SLOPE (auto-detects platform)
npx slope init --interactive --smart	Guided setup with repo analysis
npx slope hook add --level=full	Install all guidance hooks
npx slope map	Generate/update codebase map

Scoring

Command	Description
npx slope card	Display handicap card
npx slope validate [path]	Validate scorecard(s)
npx slope review [path]	Generate sprint review markdown
npx slope auto-card --sprint=N	Generate scorecard from git + CI signals
npx slope report --html	Generate HTML performance report
npx slope dashboard	Live local performance dashboard

Planning

Command	Description
npx slope now	Compact current-state cockpit
npx slope start [--ticket=KEY]	Start sprint state or begin a ticket with briefing, claim, prep, and next gates
npx slope briefing	Pre-sprint hazard index, nutrition alerts, filtered gotchas
npx slope plan --complexity=<level>	Club recommendation + training plan
npx slope next	Show next sprint number
npx slope roadmap interview	Run the project interview when planning input is needed
npx slope roadmap status [--sprint=N]	Compact current roadmap state: active work, blockers, next ready, upcoming
npx slope roadmap status --full	Full historical roadmap status
npx slope roadmap validate	Validate roadmap dependencies and sprint status
npx slope vision create + npx slope roadmap generate	Create vision-backed roadmap plans from concrete backlog signals

Review & Findings

Command	Description
npx slope review recommend	Which review types to run based on sprint characteristics
npx slope review findings add	Record a review finding
npx slope review amend	Inject findings as hazards into scorecard
npx slope review defer --from=N --to=M	Defer a finding to a future sprint
npx slope review deferred --sprint=N	List deferred findings targeting a sprint
npx slope review resolve --id=<uuid>	Mark a deferred finding as resolved

Sessions

Command	Description
npx slope session start|end|list	Manage live sessions
npx slope claim --target=<t>	Claim a ticket or area
npx slope status	Sprint status + conflicts
npx slope sprint start --number=N	Initialize sprint state with gate tracking

Maintenance

Command	Description
npx slope extract --file=<path>	Extract events into store
npx slope distill	Promote patterns to common issues
npx slope store health|backup|restore	Store diagnostics and management
npx slope flows init|list|check	Manage user flow definitions

Metaphors

7 built-in metaphors — same scoring math, different vocabulary:

Metaphor	Sprint	Ticket	Perfect	On Target
Golf (default)	Sprint	Shot	Hole-in-One	Par
Tennis	Set	Point	Ace	Deuce
Baseball	Inning	At-Bat	Home Run	Single
Gaming	Level	Quest	S-Rank	B-Rank
D&D	Quest	Encounter	Natural 20	DC Met
Matrix	Simulation	Anomaly	The One	Stable
Agile	Sprint	Story	Shipped	Accepted

npx slope init --metaphor=gaming          # Set during init
npx slope card --metaphor=tennis          # Override per-command

Core API

import {
  buildScorecard,
  validateScorecard,
  computeHandicapCard,
  computeDispersion,
  formatSprintReview,
  loadScorecards,
  getMetaphor,
  createDeferred,
  listDeferred,
} from '@slope-dev/slope';

Published as @slope-dev/slope.

Documentation

• Getting Started — installation, setup, core concepts
• Tutorial: First Sprint — end-to-end walkthrough
• Framework Reference — full scoring system specification
• Dashboard Guide — live performance dashboard
• Multi-Developer Guide — team handicap and leaderboard
• Cline Setup — Cline-specific MCP configuration
• Scorecard Template — field-by-field reference

Contributing

1. Fork and clone
2. pnpm install && pnpm build
3. pnpm test — runs all tests
4. pnpm typecheck — type checking
5. Create a feature branch, make changes, submit a PR

License

MIT