@slope-dev/slope 1.36.0 → 1.37.1

package/templates/claude-code/commands/start-sprint.md

@@ -0,0 +1,79 @@
+# Start Sprint — Pre-Sprint Setup and Briefing
+
+Run the complete pre-sprint routine: verify prior sprint hygiene, get briefing, create branch, and initialize sprint state.
+
+## Arguments
+
+- `$ARGUMENTS` — optional: sprint number (auto-detected if omitted)
+
+## Steps
+
+### 1. Determine sprint number
+
+- If a number was provided as an argument, use it
+- Otherwise, run `slope next` to auto-detect the next sprint number
+
+### 2. Verify prior sprint scorecard
+
+Check that the previous sprint's scorecard exists at `docs/retros/sprint-{N-1}.json`:
+- If missing, **stop and create it first** using `/post-sprint`
+- If it exists, continue
+- Note: the sprint-completion guard also enforces this — PR creation is blocked without a scorecard
+
+### 3. Branch hygiene
+
+- Run `git branch` to check for stale branches from prior sprints
+- If stale branches exist, warn the user
+- Create a new feature branch: `feat/sprint-{N}-<theme-slug>`
+
+### 4. Run briefing
+
+Run `slope briefing` to get:
+- Handicap snapshot (rolling performance stats)
+- Hazard index (recent gotchas by area)
+- Filtered common issues relevant to this sprint's work area
+- Session continuity (any handoffs from prior sessions)
+
+If you know the sprint's work area, add filters:
+```
+slope briefing --categories=<area> --keywords=<topic>
+```
+
+### 5. Initialize sprint state
+
+Run `slope sprint start --number={N}` to create the sprint state file with gate tracking.
+
+### 6. Set par and slope
+
+Based on the sprint plan:
+- **Par**: 1-2 tickets = 3, 3-4 tickets = 4, 5+ tickets = 5
+- **Slope**: Count complexity factors:
+  - New infrastructure or architecture (+1)
+  - Multi-package changes (+1)
+  - Schema or API changes (+1)
+  - External API integration (+1)
+  - Learning curve / unfamiliar territory (+1)
+
+### 7. Prior art research
+
+Before implementation begins, search for existing solutions:
+- How have other projects solved this problem?
+- Are there standard algorithms or approaches?
+- Any relevant GDC talks, blog posts, or papers?
+
+Save findings to `docs/` for reference during implementation.
+
+### 8. Present sprint summary
+
+Show the user:
+- Sprint number and theme
+- Par and slope
+- Ticket list with planned clubs
+- Key hazards to watch for (from briefing)
+- Deferred findings targeting this sprint: `slope review deferred --sprint={N}`
+
+## Important
+
+- Never skip the prior scorecard verification — this prevents the "batch without reflection" problem
+- The briefing output contains critical context; read it carefully before starting
+- If the codebase map is stale, run `slope map` to refresh it

package/templates/claude-code/hooks/pre-merge-check.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# pre-merge-check.sh — Validates scorecard exists before PR merge
+#
+# Usage: Add as a pre-merge hook or run manually before merging.
+# Checks that the PR diff contains a scorecard JSON file.
+
+set -euo pipefail
+
+SCORECARD_DIR="${SLOPE_SCORECARD_DIR:-docs/retros}"
+SCORECARD_PATTERN="${SLOPE_SCORECARD_PATTERN:-sprint-*.json}"
+
+# Get the current branch's diff against main
+DIFF_FILES=$(git diff --name-only main...HEAD 2>/dev/null || git diff --name-only HEAD~1)
+
+# Check for scorecard in diff
+SCORECARD_FOUND=false
+for file in $DIFF_FILES; do
+  case "$file" in
+    ${SCORECARD_DIR}/${SCORECARD_PATTERN})
+      SCORECARD_FOUND=true
+      break
+      ;;
+  esac
+done
+
+if [ "$SCORECARD_FOUND" = false ]; then
+  echo ""
+  echo "ERROR: No scorecard found in PR diff."
+  echo "  Expected: ${SCORECARD_DIR}/${SCORECARD_PATTERN}"
+  echo ""
+  echo "  Create a scorecard before merging:"
+  echo "    slope validate <path-to-scorecard>"
+  echo ""
+  exit 1
+fi
+
+# Validate the scorecard if slope CLI is available
+if command -v slope &>/dev/null; then
+  for file in $DIFF_FILES; do
+    case "$file" in
+      ${SCORECARD_DIR}/${SCORECARD_PATTERN})
+        echo "Validating $file..."
+        slope validate "$file"
+        ;;
+    esac
+  done
+fi
+
+echo "Pre-merge check passed."

package/templates/claude-code/rules/commit-discipline.md

@@ -0,0 +1,36 @@
+# Commit Discipline
+
+**Commit early, commit often.** Lost context from uncommitted work is the #1 risk.
+The last push is the recovery point — everything since the last push is lost on crash or context loss.
+
+## Commit triggers:
+
+Commit immediately after ANY of these:
+1. **Each new file** — route, migration, config, component, test. Don't batch file creations.
+2. **Each endpoint or feature** — one feature implemented = one commit.
+3. **Each migration** — commit each separately.
+4. **Each doc update** — spec change, README edit.
+5. **Each bug fix** — no matter how small.
+6. **Before switching context** — moving to a different area? Commit first.
+7. **Before risky operations** — large refactor, dependency upgrade.
+8. **Time check** — if ~15 minutes have passed since the last commit, commit what works.
+9. **Session end** — never leave uncommitted changes. Use a `wip:` prefix if incomplete.
+
+## Push triggers:
+
+Push immediately after ANY of these:
+1. **After each completed ticket (Post-Shot Routine)** — all commits pushed before merging. Score the shot.
+2. **Every 30 minutes** — never go longer without a push.
+3. **Before context compaction** — if context is running low, push first.
+4. **Before switching tickets** — push current branch before starting a new one.
+5. **Session end** — never leave unpushed commits.
+
+## Commit message format:
+
+```
+<type>(<ticket>): <short summary in imperative mood>
+
+<optional body explaining why, not what>
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `wip`

package/templates/claude-code/rules/review-loop.md

@@ -0,0 +1,39 @@
+# Sprint Plan Review Loop
+
+After creating a sprint plan, run a structured review to catch issues before implementation.
+
+## Review Tier Selection
+
+| Tier | Rounds | When to use |
+|------|--------|-------------|
+| **Skip** | 0 | Research, infra, or docs-only sprints |
+| **Light** | 1 | 1-2 tickets, familiar patterns, single-package |
+| **Standard** | 2 | 3-4 tickets, multi-package, or schema/API changes |
+| **Deep** | 3 | 5+ tickets, new infrastructure, architectural changes |
+
+## Review Process
+
+### Round 1 — Deep Review
+
+Check the plan against the codebase:
+- Does the plan duplicate existing infrastructure?
+- Are dependencies correct and ordering optimal?
+- Does the approach match codebase patterns?
+- Are there scope gaps or underscoped complexity?
+- Does it introduce unnecessary complexity?
+
+### Round 2 — Delta Review (Standard+)
+
+Review **only what changed** since Round 1:
+- Were Round 1 findings addressed correctly?
+- Did revisions introduce new issues?
+
+### Round 3 — Final Sign-off (Deep only)
+
+Delta review of Round 2 changes. Expected outcome: approval with minor notes.
+
+## Tool Priority
+
+1. **Search** to check function signatures, type definitions, patterns
+2. **Find** to verify file existence and related files
+3. **Read** only when search can't answer (complex multi-line logic)

package/templates/claude-code/rules/sprint-checklist.md

@@ -0,0 +1,62 @@
+# Sprint Checklists (SLOPE Routine Hierarchy)
+
+The SLOPE framework organizes sprint work into a hierarchy of routines, mirroring golf's structured approach to each shot, hole, and round.
+
+## Pre-Tournament Routine (Course Strategy)
+
+Before starting a new phase or project:
+
+1. **Define the vision** — What does the end state look like? Document in a vision doc
+2. **Build the roadmap** — Create `docs/backlog/roadmap.json` with sprints, dependencies, and phases
+3. **Run `slope roadmap validate`** — Check for structural issues, dependency cycles, numbering gaps
+4. **Run `slope roadmap review`** — Automated architect review: scope balance, critical path, bottlenecks
+5. **Identify the critical path** — Run `slope roadmap show` to see the dependency graph and parallel tracks
+6. **Plan parallel tracks** — If sprints can run concurrently, plan for multi-agent execution
+
+## Pre-Round Routine (Sprint Start)
+
+Before writing any code in a new sprint:
+
+1. **Run `slope briefing`** — Single command that outputs handicap snapshot, hazard index, nutrition alerts, filtered gotchas, and session continuity
+   - Use `--categories=testing,api` or `--keywords=migration` to filter for the sprint's work area
+2. **Verify previous scorecard exists** — If the last sprint's scorecard wasn't created, create it now
+3. **Branch hygiene check** — `git branch -a` to confirm no stale branches remain
+4. **Gap analysis** (if touching API or schema) — Read relevant docs and compare against implementation before writing code
+5. **Set par and slope** — Par from ticket count (1-2=3, 3-4=4, 5+=5), slope from complexity factors
+
+## Pre-Shot Routine (Per-Ticket, Before Code)
+
+Before starting each ticket:
+
+1. **Select your club** — Declare approach complexity: driver (risky/new), long_iron (multi-package), short_iron (standard), wedge (small), putter (trivial)
+2. **Check the yardage book** — Review relevant codebase sections for files you'll modify
+3. **Scan for hazards** — Check `bunker_locations` from recent scorecards and common issues for known gotchas
+4. **Commit the club selection** — Note it in your sprint tracking before writing code
+
+## Post-Shot Routine (Per-Ticket, After Completion)
+
+After completing each ticket:
+
+1. **Score the shot** — Determine result: fairway (clean start), green (landed correctly), in_the_hole (perfect), or miss direction (long/short/left/right)
+2. **Record hazards** — Note any gotchas encountered
+3. **Check for penalties** — Tests break? Reverts needed? Each penalty adds to the score
+4. **Update sprint tracking** — Mark ticket status
+5. **Push** — The last push is the recovery point
+
+## Post-Hole Routine (Sprint Completion)
+
+After all tickets are complete:
+
+1. **Score the hole** — Audit commits, compute final score vs par
+2. **Build the SLOPE scorecard** — Create scorecard JSON in your retros directory. Run `slope validate` to confirm no errors
+3. **Distill learnings** — Update common-issues with new recurring patterns
+4. **Create PR and merge** — All artifacts travel with the PR
+5. **Review** — Run `slope review` to generate the sprint review markdown
+
+## Post-Round Routine (Per-Phase)
+
+At the end of each development phase:
+
+1. **Compute handicap card** — Run `slope card` to see trending stats
+2. **Review miss patterns** — Identify systemic issues from the handicap card
+3. **Training program** — Based on trends, identify areas for focused practice sprints

package/templates/cursor/rules/slope-commit-discipline.mdc

@@ -0,0 +1,37 @@
+---
+description: Commit and push discipline for SLOPE-managed sprints
+globs:
+alwaysApply: true
+---
+
+# Commit Discipline
+
+**Commit early, commit often.** The last push is the recovery point.
+
+## Commit triggers:
+
+Commit immediately after ANY of these:
+1. Each new file — route, migration, config, component, test
+2. Each endpoint or feature implemented
+3. Each migration — commit separately
+4. Each bug fix — no matter how small
+5. Before switching context to a different area
+6. Before risky operations — large refactor, dependency upgrade
+7. Time check — if ~15 minutes since last commit, commit what works
+8. Session end — never leave uncommitted changes (use `wip:` prefix if incomplete)
+
+## Push triggers:
+
+Push immediately after ANY of these:
+1. After each completed ticket (Post-Shot Routine)
+2. Every 30 minutes
+3. Before switching tickets
+4. Session end — never leave unpushed commits
+
+## Commit message format:
+
+```
+<type>(<ticket>): <short summary in imperative mood>
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `wip`

package/templates/cursor/rules/slope-review-loop.mdc

@@ -0,0 +1,33 @@
+---
+description: Sprint plan review tiers for catching issues before implementation
+globs:
+alwaysApply: false
+---
+
+# Sprint Plan Review Loop
+
+After creating a sprint plan, run a structured review.
+
+## Review Tier Selection
+
+| Tier | Rounds | When to use |
+|------|--------|-------------|
+| **Skip** | 0 | Research, infra, or docs-only sprints |
+| **Light** | 1 | 1-2 tickets, familiar patterns, single-package |
+| **Standard** | 2 | 3-4 tickets, multi-package, or schema/API changes |
+| **Deep** | 3 | 5+ tickets, new infrastructure, architectural changes |
+
+## Round 1 — Deep Review
+
+- Does the plan duplicate existing infrastructure?
+- Are dependencies correct and ordering optimal?
+- Does the approach match codebase patterns?
+- Are there scope gaps or underscoped complexity?
+
+## Round 2 — Delta Review (Standard+)
+
+Review **only what changed** since Round 1.
+
+## Round 3 — Final Sign-off (Deep only)
+
+Delta review of Round 2 changes. Expected outcome: approval with minor notes.

package/templates/cursor/rules/slope-sprint-checklist.mdc

@@ -0,0 +1,48 @@
+---
+description: SLOPE sprint lifecycle checklist — routines for pre-round, per-ticket, and post-round
+globs:
+alwaysApply: true
+---
+
+# Sprint Checklists (SLOPE Routine Hierarchy)
+
+The SLOPE framework organizes sprint work into a hierarchy of routines, mirroring golf's structured approach to each shot, hole, and round.
+
+## Pre-Tournament Routine (Course Strategy)
+
+Before starting a new phase or project:
+
+1. **Build the roadmap** — Create `docs/backlog/roadmap.json` with sprints, dependencies, and phases
+2. **Run `slope roadmap validate`** — Check for dependency cycles, numbering gaps
+3. **Run `slope roadmap review`** — Scope balance, critical path, bottlenecks
+4. **Run `slope roadmap show`** — Dependency graph and parallel tracks
+
+## Pre-Round Routine (Sprint Start)
+
+Before writing any code in a new sprint:
+
+1. **Run `slope briefing`** — Outputs handicap snapshot, hazard index, nutrition alerts, filtered gotchas, and session continuity
+   - Use `--categories=testing,api` or `--keywords=migration` to filter for the sprint's work area
+2. **Verify previous scorecard exists** — If the last sprint's scorecard wasn't created, create it now
+3. **Branch hygiene check** — `git branch -a` to confirm no stale branches remain
+4. **Set par and slope** — Par from ticket count (1-2=3, 3-4=4, 5+=5), slope from complexity factors
+
+## Pre-Shot Routine (Per-Ticket, Before Code)
+
+1. **Select your club** — driver (risky/new), long_iron (multi-package), short_iron (standard), wedge (small), putter (trivial)
+2. **Check the yardage book** — Review relevant codebase sections for files you'll modify
+3. **Scan for hazards** — Check `bunker_locations` from recent scorecards and common issues
+
+## Post-Shot Routine (Per-Ticket, After Completion)
+
+1. **Score the shot** — in_the_hole (perfect), green (landed), fairway (clean start), or miss direction
+2. **Record hazards** — Note any gotchas encountered
+3. **Check for penalties** — Tests break? Reverts needed?
+4. **Push** — The last push is the recovery point
+
+## Post-Hole Routine (Sprint Completion)
+
+1. **Build the SLOPE scorecard** — Create scorecard JSON. Run `slope validate`
+2. **Distill learnings** — Update common-issues with new recurring patterns
+3. **Review** — Run `slope review` to generate the sprint review markdown
+4. **Compute handicap** — Run `slope card` to see trending stats

package/templates/generic/SLOPE-CHECKLIST.md

@@ -0,0 +1,27 @@
+# SLOPE Sprint Checklist
+
+## Pre-Tournament (Course Strategy)
+1. Build roadmap in `docs/backlog/roadmap.json`
+2. Run `slope roadmap validate` — check dependencies and structure
+3. Run `slope roadmap review` — scope balance, critical path, bottlenecks
+4. Run `slope roadmap show` — view dependency graph
+
+## Pre-Round (Sprint Start)
+1. Run `slope briefing` — handicap, hazards, gotchas, session continuity
+2. Verify previous scorecard exists
+3. Set par (1-2 tickets=3, 3-4=4, 5+=5) and slope factors
+
+## Per-Ticket
+- **Before:** Select club (driver/long_iron/short_iron/wedge/putter), scan hazards
+- **After:** Score shot, record hazards, check penalties, commit + push
+
+## Post-Hole (Sprint End)
+1. Build scorecard JSON, run `slope validate`
+2. Update common-issues with new patterns
+3. Run `slope review` for markdown output
+4. Run `slope card` for handicap trends
+
+## Commit Discipline
+- Commit after each file, feature, migration, or bug fix
+- Push after each ticket and every 30 minutes
+- Format: `<type>(<ticket>): <summary>` (feat/fix/refactor/docs/test/chore)