squad-kit 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,84 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-04-24
+
+### Why this release
+
+squad-kit 0.2.2 stabilised rate-limit handling with retries and a softer `squad doctor` warning.
+That made failures loud but didn't reduce the underlying token spend: every planning turn
+re-sent the cumulative transcript, so costs scaled roughly quadratically with the number of
+tool calls. On Anthropic Tier 1 with Opus, that made non-trivial plans structurally infeasible.
+
+0.3.0 adds **prompt caching end-to-end** across Anthropic, OpenAI, and Google. Expected savings
+on a typical 10-turn run: ~70% fewer billed input tokens, and — critically on Anthropic —
+cached reads don't count the same against your per-minute quota. Tier 1 Opus users should find
+moderate plans work where they previously hit 429 from turn 7 onward.
+
+### Added
+
+- Anthropic explicit prompt caching via `cache_control: { type: 'ephemeral' }` on the system
+  prompt and the most recent tool-result block each turn (cache TTL rolls forward).
+- OpenAI and Google implicit prefix caching (no config required; activated by the stable-prefix
+  refactor below).
+- `planner.cache.enabled` config knob (default `true`). Configure via `squad config set planner`.
+- Run-summary line: `cache hit 68% (22.4k read / 32.9k total)` every `squad new-plan --api` run.
+- `squad doctor` now checks `planner cache effectiveness`, reading `.squad/.last-run.json`.
+- `.squad/.last-run.json` persistence of planner run stats (git-ignored, per-user).
+- `Usage.cacheCreationTokens` and `Usage.cacheReadTokens` on every provider response.
+- Deterministic request-body builders (`buildAnthropicBody`, `buildOpenAIBody`, `buildGoogleBody`)
+  exposed for testing; dev-mode warning when a turn mutates the cacheable prefix.
+- Copy-paste mode (`squad new-plan --copy`) now writes the composed prompt to
+  `.squad/.last-copy-prompt.md` and prints a compact summary (mode · story · file · size · est
+  tokens · clipboard status) instead of dumping the full 5–10 KB prompt into the terminal.
+- Clipboard fallbacks for Linux (`xsel` in addition to `xclip`) and Termux
+  (`termux-clipboard-set`). Headless Linux / SSH sessions now surface an actionable reason in
+  the summary ("no display server detected — install xclip or xsel, or use the saved file")
+  instead of silently skipping.
+- `squad config set planner` and `squad config set tracker` print a "▸ Next:" block so users
+  know what to run next (`squad doctor` → `squad new-story` → `squad new-plan`).
+- `squad tracker link` and `squad migrate` also print "▸ Next:" guidance.
+- Managed `.gitignore` block now covers `.squad/.last-run.json` and `.squad/.last-copy-prompt.md`.
+
+### Changed
+
+- System prompt no longer embeds timestamps, random IDs, or absolute host paths (these
+  cache-busted the prefix on every turn).
+- `squad doctor` Anthropic Tier 1 Opus warning softened from "you will hit ITPM" to "tight but
+  viable with caching on."
+- `squad config set planner` no longer prompts for `planner.modelOverride`. The interactive
+  flow is shorter and less intimidating; power users can still set the override directly in
+  `.squad/config.yaml` (documented in `docs/customization.md`).
+- `copyToClipboard()` now returns a structured `{ ok, tool?, reason? }` result instead of a
+  bare boolean, so callers can explain failures to the user.
+
+### Known limitations
+
+- Google `cachedContents` explicit API not implemented (implicit caching is sufficient for
+  single-run CLI use).
+- No cross-run persistence of cache stats yet — doctor only reads the most recent run.
+- No automatic context compression when transcripts exceed ~50 KB. Caching helps but doesn't
+  solve the long-horizon case. 0.4.0 candidate.
+- Anthropic 1-hour cache TTL (`ttl: "1h"`) not used — default 5-minute TTL covers single-run.
+
+### Migration
+
+See `docs/migrating-from-0.1.md` §9 "Upgrading from 0.2.x to 0.3.0" for the full path. Short
+version: `squad upgrade` and you're done. Caching is on by default; no config edits required.
+
+## [0.2.2] - 2026-04-22
+
+### Fixed
+
+- **Rate-limit retry no longer burns a doomed request.** 0.2.1 capped the auto-retry wait at 30 s. When a provider asked for longer than that (common on Anthropic Tier 1, which regularly asks for 60–180 s), squad-kit would retry *inside the same throttle window* and fail a second time. 0.2.2:
+  - Raises the retry cap from 30 s to **90 s**, which comfortably covers the provider-suggested wait for most Tier 1 / free-tier 429s.
+  - **Skips the retry entirely** when `Retry-After` is longer than the 90 s cap, and surfaces a dedicated message explaining the decision (`squad-kit did not auto-retry: the provider's 132s wait is longer than our 90s cap, so retrying would just burn another request inside the same throttle window.`) instead of wasting a request and showing the "already retried" variant.
+
+### Added
+
+- **`squad doctor` now reports planner tier vs. model awareness** (check id `planner-tier`). When `planner.provider === 'anthropic'` and the resolved plan model id contains `opus`, the check emits a **warn** with a fix hint suggesting `squad config set planner` to pick Sonnet or Haiku, which live in separate per-model rate-limit buckets on Anthropic Tier 1 (10 k input tokens / minute). For non-Anthropic providers and non-Opus models, the check is `skip` or `ok` — no noise for users who aren't affected.
+- `rateLimitMessage` gained a `retrySkippedReason` + `maxRetrySec` field, so the error text can distinguish "we retried and got throttled again" (firm over-quota) from "we did not retry because your wait is longer than our cap" (retry would be pointless). Both cases still surface the same four recovery options.
+
 ## [0.2.1] - 2026-04-22
 
 ### Fixed
@@ -115,6 +193,9 @@ First public release.
 - Plan-generation meta-prompt (`generate-plan.md`), intake template (`intake.md`), and plan skeleton reference (`story-skeleton.md`).
 - Documentation: `docs/philosophy.md`, `docs/getting-started.md`, `docs/customization.md`, `docs/vs-spec-kit.md`.
 
-[Unreleased]: https://github.com/AzmSquad/squad-kit/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/AzmSquad/squad-kit/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/AzmSquad/Squad-Kit/releases/tag/v0.3.0
+[0.2.2]: https://github.com/AzmSquad/squad-kit/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/AzmSquad/squad-kit/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/AzmSquad/squad-kit/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/AzmSquad/squad-kit/releases/tag/v0.1.0

package/README.md

@@ -1,11 +1,17 @@
-# squad-kit
+<p align="center">
+  <a href="https://squad-kit.com">
+    <img src="https://squad-kit.com/logo-wordmark.svg?v=2" alt="squad-kit logo" width="360">
+  </a>
+</p>
 
-[![npm version](https://img.shields.io/npm/v/squad-kit.svg)](https://www.npmjs.com/package/squad-kit)
-[![CI](https://github.com/AzmSquad/Squad-Kit/actions/workflows/ci.yml/badge.svg)](https://github.com/AzmSquad/Squad-Kit/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Website](https://img.shields.io/badge/site-squad--kit.netlify.app-7cffa0?labelColor=0a0a0c)](https://squad-kit.netlify.app)
+<p align="center">
+  <a href="https://www.npmjs.com/package/squad-kit"><img src="https://img.shields.io/npm/v/squad-kit.svg" alt="npm version"></a>
+  <a href="https://github.com/AzmSquad/Squad-Kit/actions/workflows/ci.yml"><img src="https://github.com/AzmSquad/Squad-Kit/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://squad-kit.com"><img src="https://img.shields.io/badge/site-squad--kit.com-7cffa0?labelColor=0a0a0c" alt="Website"></a>
+</p>
 
-**Plan once, execute cheap.** A 3-step SDD-style workflow CLI for AI-assisted coding: **raw story → good plan → implementation**. Your expensive model plans once. A cheap model executes many times. Squad-kit owns the folder conventions, the plan meta-prompt, and the agent slash-commands so the token cost goes where it pays off. Deeper product notes live on **[squad-kit.netlify.app](https://squad-kit.netlify.app)** and in [`docs/`](docs/philosophy.md).
+**Plan once, execute cheap.** A 3-step SDD-style workflow CLI for AI-assisted coding: **raw story → good plan → implementation**. Your expensive model plans once. A cheap model executes many times. Squad-kit owns the folder conventions, the plan meta-prompt, and the agent slash-commands so the token cost goes where it pays off. Deeper product notes live on **[squad-kit.com](https://squad-kit.com)** and in [`docs/`](docs/philosophy.md).
 
 ```
 .squad/
@@ -13,6 +19,11 @@
 └── plans/<feature>/         # NN-story-<slug>.md (one per executable plan)
 ```
 
+## What's new in 0.3.0
+
+- **Prompt caching** across Anthropic, OpenAI, and Google — ~70% fewer billed input tokens on
+  a typical planning run, and Anthropic Tier 1 ITPM pressure roughly 5× lower.
+
 ## What's new in 0.2.0
 
 - **Direct planner.** `squad new-plan --api` runs Anthropic, OpenAI, or Google from your terminal and writes the plan file. Demand-driven context keeps tokens bounded.
@@ -39,7 +50,7 @@ cd your-project && squad migrate
 
 `squad migrate` deletes the now-unused `.squad/prompts/` directory, appends the managed `.gitignore` block, tightens `.squad/secrets.yaml` permissions to `0600`, and normalises `.squad/config.yaml`. It is idempotent but destructive — run it with `--dry-run` first if you forked the prompt files.
 
-Full upgrade walkthrough, including what-if scenarios and how to recover customised prompts: [migration guide (repo)](docs/migrating-from-0.1.md) · [migration guide (site)](https://squad-kit.netlify.app/docs/migrating-from-0.1).
+Full upgrade walkthrough, including what-if scenarios and how to recover customised prompts: [migration guide (repo)](docs/migrating-from-0.1.md) · [migration guide (site)](https://squad-kit.com/docs/migrating-from-0.1).
 
 ## Install
 
@@ -108,6 +119,8 @@ Override the default plan-phase model without editing squad-kit:
 planner:
   enabled: true
   provider: anthropic
+  cache:
+    enabled: true   # default; turn off via squad config set planner
   modelOverride:
     anthropic: claude-opus-5-0      # riding a newer provider release early
 ```
@@ -165,6 +178,7 @@ See [`docs/philosophy.md`](docs/philosophy.md) for the token math and [`docs/vs-
 - **Quality depends on the planning model.** squad-kit has no safety-net commands. Use a strong model for `new-plan`.
 - **Plans are project-coupled.** They reference real file paths. That is the point — do not expect portability between projects.
 - **Global `NN` can collide on parallel branches.** Rebase-and-renumber is the resolution. Documented in [`docs/customization.md`](docs/customization.md).
+- **Anthropic Tier 1 + Opus** shares a tight input-token-per-minute bucket. **0.3.0** enables prompt caching by default so typical multi-turn plans stay viable; see [Prompt caching](docs/customization.md#prompt-caching) in the customization docs.
 
 ## Non-goals for 0.2