The SLOPE Framework

SLOPE writes everything to disk — JSON scorecards, config files, hazard maps. Any agent that can read files and run commands can use it. There's no API key, no cloud service, no vendor lock-in.

Hooks are the deepest integration but not required — they just automate enforcement. Without hooks, the agent follows the same routines manually via rules files and CLI commands. The output is identical.

This means SLOPE works with future tools too, not just today's editors. If a new AI coding environment launches tomorrow and it can run shell commands, SLOPE works on day one.

AI coding agents lose context. They crash, compact, and restart. Without a fixed lifecycle, every session starts from zero — the agent has no idea what happened in the last 50 sprints.

SLOPE's lifecycle is designed around this constraint. The workflow engine enforces this lifecycle automatically — sprint-standard is the default workflow. Every artifact is written to disk at specific checkpoints: the plan file after plan review, the scorecard after post-hole, the handicap after the 19th hole. When context compacts, the agent reads these artifacts and picks up exactly where it left off.

The "plan review" gate ensures you have a reviewed approach before implementation starts. The "for each ticket" loop is where most work happens. But the pre-round and post-hole routines are what make the data compound. Without them, you just have a git log. With them, you have a trajectory.

The five levels aren't arbitrary — they map to different feedback loop frequencies. A stroke (commit) gives you immediate feedback: does it compile? A shot (ticket) gives you end-of-task feedback: does the feature work? A hole (sprint) gives you multi-task feedback: did the team improve?

The round (phase) and tournament (project) levels are where strategic patterns emerge. "We always struggle at the mobile-orchestrator boundary" is a round-level insight. "Our scoping gets better every phase" is a tournament-level trend.

Most dev frameworks only operate at one or two levels. SLOPE gives you vocabulary and measurement at all five, so you can reason about performance at the right granularity.

A Par 4, Slope 3 sprint is meaningfully harder than a Par 4, Slope 0. Both have 3-4 tickets, but the slope factors compound difficulty in ways that ticket count alone doesn't capture.

The handicap system accounts for this: handicap = avg(score - par) over a rolling window. A bogey on a Slope 3 sprint is more forgivable than a bogey on Slope 0. The framework doesn't penalize you for taking on hard work.

Example: Sprint 22 — Par 4, Slope 2 (cross-package + new area)
Score: 4 (Par) — clean execution despite the slope factors.
The handicap computation weights slope difficulty appropriately.

Sprint type affects how you interpret the score. A research sprint that scores bogey isn't a failure — exploration takes more strokes by nature. A bugfix sprint that scores bogey might indicate deeper issues, since bug fixes should be precise.

The handicap system tracks sprint types to normalize scoring. If your handicap improves but you're only doing feedback and bugfix sprints, the improvement is less meaningful than if you're consistently improving on feature sprints.

Sprint type also drives the training recommendation engine: "long" misses on feature sprints recommend research training. "Right" misses on infra sprints recommend feedback training.

Workflows are defined as YAML files in .slope/workflows/. A workflow has phases, each containing steps:

name: sprint-standard
phases:
  - name: pre_hole
    steps:
      - name: briefing
        type: command
        command: slope briefing
  - name: plan_review
    steps:
      - name: write_plan
        type: agent_work
        completion_conditions:
          files_exist: ["docs/plans/S*.md"]
      - name: review_plan
        type: agent_input
        required_fields: [review_tier, review_complete]
  - name: per_ticket
    repeat_for: tickets
    steps:
      - name: implement
        type: agent_work
      - name: validate
        type: validation
  - name: post_hole
    steps:
      - name: scorecard
        type: command
        command: slope review

The repeat_for: tickets directive runs the phase once per claimed ticket. Completion conditions enforce that required files exist before advancing. Set defaultWorkflow: 'sprint-standard' in your config to use workflows by default.

Club selection isn't just metadata. It's a forcing function that makes you think about complexity before writing code. When you pick up a driver, you're saying: "this is risky, this is new, I'm swinging hard." When you pick up a putter, you're saying: "this is close to done, precision matters more than power."

Over time, club selection data reveals patterns: "We always reach for drivers on OAuth work, but irons would be safer." This is exactly how experienced players optimize — they know which clubs they hit consistently and which ones introduce variance.

The provisional is particularly powerful for AI agents. When an agent declares a provisional ("if this approach fails in 2 commits, switch to X"), it prevents the common failure mode of sinking 45 minutes into a dead-end approach.

The real power isn't in logging individual hazards — it's in the bunker location map that accumulates over time. After 50 sprints, you know exactly where the bunkers are: "the OAuth module always has nvm sourcing issues," "mobile-orchestrator boundary misses right on integration."

This map gets baked into the pre-shot routine. Before starting a ticket, the agent checks: "are there known bunkers in this area?" If yes, it budgets an extra shot and selects a safer club. This is how the best players play — they don't just swing and hope. They study the course.

In SLOPE, this is implemented as common-issues.json — a growing database of gotchas indexed by code area, severity, and recurrence. The pre-round briefing surfaces the top hazards for the sprint's work area automatically.

Conditions aren't excuses — they're context. A bogey in wind (context compaction) is different from a bogey on a calm day. The scorecard captures both the score and the conditions, so when you review your handicap trend, you can separate "bad play" from "hard conditions."

Pin position is especially useful for AI agents. A ticket with loose acceptance criteria ("make the UI better") is a center pin — easy to land near. A ticket with precise requirements ("the animation must be exactly 200ms with this easing curve") is a tucked pin — requires surgical precision. Knowing the pin position before you swing changes your club selection.

The #1 insight from dozens of sprints: routine beats talent. An agent that follows the pre-shot routine every time will outperform an agent that's "smarter" but inconsistent. The best players know this — they don't skip their routine even when they're playing well.

The 19th Hole is the most underrated part. It captures what metrics can't: momentum, energy, intuition. After many sprints of 19th Hole notes, patterns emerge that no stat can show: "infrastructure sprints are energizing," "cross-package work is draining."

For AI agents specifically, the routines solve the context compaction problem. When an agent's context window fills up and old messages get compressed, the routine artifacts on disk preserve everything. The next session reads the sprint file and the scorecard, and it's as if no context was lost.

The handicap isn't a judgment — it's a prediction. A handicap of 1.2 means "this system averages 1.2 strokes over par." That's not bad or good in isolation — it's useful because it tells you what to expect from the next sprint.

The three windows (last 5, last 10, all-time) show different things:

• Last 5 — Are you in form right now? Recent momentum.
• Last 10 — Is this a trend or a fluke? Smooths out variance.
• All-time — Your baseline. Where you started vs where you are.

When last-5 is significantly better than all-time, you're improving. When it's worse, something changed — check conditions, check hazards, check if you're tackling harder sprints (higher slope).

The miss pattern is arguably more actionable than the handicap itself. "We consistently miss long" means the team over-engineers. "We miss right" means the approach is correct but execution/integration fails. This directly maps to training drills: research sprints for "long" misses, feedback sprints for "right" misses.

The analysis layer is what turns SLOPE from a logging tool into a coaching system. Raw scorecards give you numbers; the advisor gives you actionable recommendations.

recommendClub() looks at your history with similar tickets — same par, same area, same conditions — and suggests the approach most likely to land on the green. Confidence drops when you haven't faced this combination before.

Auto-scoring via classifyShotFromSignals() means agents don't need to self-assess. CI pass/fail, PR size, review comments, and time-to-merge all feed into an objective result classification. This removes the biggest bias in self-scored systems.

Training is what turns scorecard data into improvement. Without it, you're just tracking stats. With it, each sprint's learnings feed back into specific practice areas.

The nutrition checklist is deceptively important for AI agents. "Hydration" maps to keeping context fresh, "diet" to clean inputs, "recovery" to proper session boundaries. An agent running without these checks is like an athlete who never stretches — performance degrades silently.

slope report generates a Markdown file you can commit alongside your scorecards — perfect for PR descriptions or team reviews. It's a snapshot: handicap trend, top hazards, area breakdown.

slope dashboard launches a local web UI for exploratory analysis. Click into any sprint to see individual shots, filter by club or hazard type, and spot patterns that static reports miss.

Roles aren't just labels — they change the briefing content. A backend agent gets hazards about database migrations surfaced prominently; a frontend agent gets accessibility gotchas. The same pre-round briefing is filtered through the role's lens.

In a multi-agent sprint, the team handicap is more useful than individual handicaps. It tells you: "when these agents work together on this kind of sprint, they average X over par." This predicts team performance better than any individual metric.

A tournament groups related sprints — like "auth system rewrite" or "v2 migration" — into a single narrative. Individual scorecards show per-sprint performance; the tournament shows the initiative-level trajectory.

The hazard index is especially useful here. A hazard that appears once is a fluke. A hazard that appears in 4 of 6 sprints is a systemic issue that needs a dedicated fix — and SLOPE surfaces it automatically.