This repository was archived by the owner on Sep 15, 2026. It is now read-only.
feat: guided-use coach — session-start digest + Next: footers (v1.8.0-rc.1, d074) - #76
Merged
Merged
Conversation
…ne-shot stamps, footer helper (d074) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…sumers (C36/C43/C44/C47) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…registration (d074) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…human output (d074) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…dash survives any console codepage Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… 1.8.0-rc.1 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a new “guided-use coach” subsystem to Baton to surface context-aware command suggestions (without model calls) via a SessionStart digest hook and “Next:” footers on select CLIs.
Changes:
- Introduce
scripts/coach-lib.ps1rules engine to derive suggestions from local Baton state (projects, runs, prompt pool, usage/budget) with one-shot dedup via$BATON_HOME/coach/seen.json. - Add SessionStart hook (
scripts/hooks/baton-coach.ps1) and wire it inhooks/hooks.jsonto emit a short orientation digest (or one-shot onboarding line). - Add “Next:” footer wiring in fleet CLIs, plus new hermetic test suites and documentation updates; bump plugin version to
1.8.0-rc.1.
Reviewed changes
Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/coach-lib.ps1 | New coach rules/context engine + footer printer + seen-store. |
| scripts/hooks/baton-coach.ps1 | New SessionStart hook to print digest/onboard line (fail-open). |
| hooks/hooks.json | Registers the new SessionStart hook command. |
| scripts/fleet-usage.ps1 | Sources coach lib and prints a footer (currently only on status). |
| scripts/fleet-gate.ps1 | Sources coach lib and prints footer on non-JSON gate output. |
| scripts/fleet-go.ps1 | Sources coach lib and prints footer on non-JSON go output. |
| scripts/fleet-optimize-prompt.ps1 | Sources coach lib and prints footer on non-JSON pool/evolution output; excludes self-suggestion rules. |
| scripts/test-coach-lib.ps1 | New hermetic unit tests for coach engine + footer behavior. |
| scripts/test-coach-footers.ps1 | New end-to-end footer tests via fleet-usage CLI + wiring parity checks. |
| scripts/test-baton-coach-hook.ps1 | New hermetic tests for SessionStart hook digest/onboard behavior. |
| docs/COMMANDS.md | Documents the guided-use coach feature, rules, and configuration. |
| commands/usage.md | Documents coach footer behavior for /baton:usage. |
| commands/gate.md | Documents coach footer behavior for /baton:gate. |
| commands/go.md | Documents coach footer behavior for /baton:go. |
| commands/optimize-prompt.md | Documents coach footer behavior for /baton:optimize-prompt. |
| commands/start.md | Documents the SessionStart coach digest. |
| .claude-plugin/plugin.json | Version bump to 1.8.0-rc.1. |
Comment on lines
+169
to
+182
| # Usage governor. | ||
| try { | ||
| $usagePath = Join-Path $BatonHome 'usage-journal.jsonl' | ||
| $rows = @(Read-UsageJournal -Path $usagePath) | ||
| $ctx.conserve = [bool](Get-ConserveMode -Rows $rows) | ||
| $atRisk = $false | ||
| $workers = @($rows | Where-Object { $_.event -eq 'tick' } | ForEach-Object { [string]$_.worker } | Sort-Object -Unique) | ||
| foreach ($w in $workers) { | ||
| $f = Get-UsageForecast -Worker $w -UsagePath $usagePath -FleetPath (Join-Path $BatonHome 'fleet.yaml') | ||
| if (($f.status -eq 'ok') -and ($null -ne $f.days_to_exhaustion) -and ([double]$f.days_to_exhaustion -le 2)) { | ||
| $atRisk = $true; break | ||
| } | ||
| } | ||
| $ctx.budget_at_risk = ($ctx.conserve -or $atRisk) |
Comment on lines
+102
to
+106
| $acc = Get-Content -Raw -LiteralPath $accPath -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop | ||
| if ("$($acc.verdict)" -match 'reject|polish') { | ||
| [void]$found.Add(@{ run_id = $run.Name; verdict = [string]$acc.verdict }) | ||
| if ($found.Count -ge $MaxRuns) { break } | ||
| } |
Comment on lines
+63
to
66
| if (-not $Json) { | ||
| if (Get-Command Write-CoachFooter -ErrorAction SilentlyContinue) { Write-CoachFooter -ExcludeIds @('budget') } | ||
| } | ||
| return |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Guided-use coach (v1.8.0-rc.1) — d074
Baton now suggests its own commands so features aren't hidden behind command names. One rules engine, two surfaces, zero model cost:
scripts/coach-lib.ps1— declarative signal→suggestion rules over local state (last-run status, gate polish/reject, promote nudge, live A/B verdict, budget posture, unregistered repo), fail-open context readers, one-shot dedup stamps in$BATON_HOME/coach/seen.json,off/quiet/teachknob (default quiet).scripts/hooks/baton-coach.ps1) — registered project → 3–5 orientation lines + one suggested command; unregistered git repo → one-shot onboard line; elsewhere silent. Always exits 0; UTF-8 stdout forced.Next:footers on/baton:usage,gate,go,optimize-prompt— at most one line, one-shot per triggering state, never in--jsonoutput, never on error paths, self-suggestion excluded.Tests
Three new hermetic suites (C1–C48 engine, H1–H7 hook, F1–F6 footers); full 14-suite sweep green.
Review
Opus whole-branch final review: READY TO MERGE, 0 Critical / 0 Important / 6 Minor (
.superpowers/sdd/final-review-coach.md). Notable minors deferred as follow-ups: seen.json pruning + atomic writes.Spec:
docs/superpowers/specs/2026-07-03-guided-use-coach-design.md· Plan:docs/superpowers/plans/2026-07-03-guided-use-coach.md🤖 Generated with Claude Code