squad-kit 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/README.md +94 -183
  3. package/dist/cli.js +196 -28
  4. package/dist/cli.js.map +1 -1
  5. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.2.2] - 2026-04-22
11
+
12
+ ### Fixed
13
+
14
+ - **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:
15
+ - Raises the retry cap from 30 s to **90 s**, which comfortably covers the provider-suggested wait for most Tier 1 / free-tier 429s.
16
+ - **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.
17
+
18
+ ### Added
19
+
20
+ - **`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.
21
+ - `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.
22
+
23
+ ## [0.2.1] - 2026-04-22
24
+
25
+ ### Fixed
26
+
27
+ - **`squad new-plan --api` now handles provider rate limits (HTTP 429) properly.** Previously a 429 surfaced the generic `Run \`squad doctor\` to verify models and credentials.` hint, which is misleading — the credentials are fine, the org is just over its per-minute quota. `runPlanner` now:
28
+ - Detects 429s across Anthropic, OpenAI, and Google (new `errorKind: 'rate_limit'` on `ProviderResponse`).
29
+ - Parses `Retry-After` (seconds or HTTP-date) and Google's body-level `retryDelay` field.
30
+ - Retries **once** automatically, waiting the provider-requested time capped at 30 seconds. A new `onRateLimit(waitSec)` callback lets the UI show a "retrying in Ns" notice.
31
+ - When the retry also fails, throws a dedicated error that names the provider, summarises the wait time, and lists four concrete recovery paths: wait and retry, switch planner model (`squad config set planner`), tighten `planner.budget`, or upgrade tier (with a deep-link to each provider's limits page).
32
+ - The generic (non-429) provider-error hint now reads `Run \`squad doctor\` to diagnose, or retry — most 5xx errors are transient.`, which is accurate for the actual 5xx / network cases it covers.
33
+
34
+ ### Added
35
+
36
+ - `detectRateLimit()` and `rateLimitMessage()` in `src/planner/provider-errors.ts`. Both cover all three supported providers and are unit-tested with real-shaped 429 fixtures.
37
+
10
38
  ## [0.2.0] - 2026-04-22
11
39
 
12
40
  ### tracker-intake-fetch
package/README.md CHANGED
@@ -5,52 +5,41 @@
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
6
6
  [![Website](https://img.shields.io/badge/site-squad--kit.netlify.app-7cffa0?labelColor=0a0a0c)](https://squad-kit.netlify.app)
7
7
 
8
- **Plan once, execute cheap.** A 3-step SDD-style workflow CLI for AI-assisted coding: **raw story → good plan → implementation**.
9
-
10
- Website & docs: **[squad-kit.netlify.app](https://squad-kit.netlify.app)**
11
-
12
-
13
- 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.
8
+ **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).
14
9
 
15
10
  ```
16
11
  .squad/
17
- ├── stories/<feature>/<id>/ # intake + attachments (one per story)
18
- └── plans/<feature>/ # NN-story-<slug>.md (one per executable plan)
12
+ ├── stories/<feature>/<id>/ # intake + attachments (one per story)
13
+ └── plans/<feature>/ # NN-story-<slug>.md (one per executable plan)
19
14
  ```
20
15
 
21
- Plan meta-prompts (`generate-plan.md`, `story-skeleton.md`, intake template) are **bundled inside the squad-kit npm package**, not copied into your repo. Upgrade the CLI to change them; to fork and customise, patch `templates/prompts/` in a fork of squad-kit.
22
-
23
- ---
24
-
25
- ## Why not Spec-Kit?
26
-
27
- Both aim at spec-driven development. They make different bets.
28
-
29
- | | squad-kit | Spec-Kit |
30
- |---|---|---|
31
- | Commands | `init`, `new-story`, `new-plan`, `status`, `doctor`, `migrate`, `upgrade`, `list`, `rm`, `tracker link` | `constitution`, `specify`, `clarify`, `plan`, `tasks`, `analyze`, `checklist`, `implement` |
32
- | `/implement` turn starts with | one plan file (~5–15 KB) | 5–7 command templates + cross-artifact reads (~15–25 KB) |
33
- | Model-tier awareness | Built into the philosophy (planner ≠ executor) | Not prescribed |
34
- | Generated artifacts per story | `intake.md`, `NN-story-<slug>.md`, overview row | `spec.md`, `plan.md`, `data-model.md`, `contracts/`, `research.md`, `quickstart.md`, `tasks.md` |
35
- | Customization | Prompts ship with the CLI (fork squad-kit to change them). | Template override stack with presets/extensions |
36
- | Runtime | Node + TypeScript, npm-distributable | Python + `uv` |
37
- | Scope | Intentionally small | Broad, with safety nets (`clarify`, `analyze`) |
38
-
39
- Spec-Kit ships safety rails. Squad-kit ships the cheap path and gets out of the way. Pick squad-kit when your planner already produces trustworthy plans; pick Spec-Kit when you want the process to catch planning mistakes for you.
16
+ ## What's new in 0.2.0
40
17
 
41
- See [`docs/philosophy.md`](docs/philosophy.md) for the token math and [`docs/vs-spec-kit.md`](docs/vs-spec-kit.md) for the full comparison.
18
+ - **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.
19
+ - **Tracker auto-fetch.** `squad new-story --id <ID>` pulls title, description, labels, and attachments (≤ 10 MB each) from Jira Cloud or Azure DevOps Services.
20
+ - **Secrets split.** API tokens live in `.squad/secrets.yaml` (git-ignored, `0600` on POSIX). `.squad/config.yaml` never holds secrets; the loader rejects secret-shaped keys.
21
+ - **Interactive-first UX.** Missing input prompts in a TTY; `-y` / `--yes` or `CI=1` opts out and fails fast.
22
+ - **`squad doctor`.** Full read-only health check; `--fix` for non-destructive repairs, `--json` for scripting.
23
+ - **`squad migrate`.** One-shot 0.1.x → 0.2.0 structural migrations (delete legacy `.squad/prompts/`, permissions, config normalisation). Destructive; use `--dry-run` first.
24
+ - **`squad upgrade`.** Safe npm-backed self-update (`--check` to verify only).
25
+ - **`squad config`.** `show`, `set planner` / `set tracker`, `unset …`, `remove-credential …` — edit config and secrets without hand-editing YAML.
26
+ - **`squad rm`.** `rm story` / `rm plan` / `rm feature` with `--dry-run`, `--trash`, and cascading overview updates.
27
+ - **Bundled prompts.** `generate-plan.md`, `intake.md`, and `story-skeleton.md` ship inside the npm package; upgrade the CLI to update them.
42
28
 
43
- ### Tracker auto-fetch (new in 0.2.0)
29
+ Full list in [`CHANGELOG.md`](CHANGELOG.md).
44
30
 
45
- When a supported tracker is configured, `squad new-story <feature> --id <ID>` pulls the work item's title, description, labels, and attachments (≤ 10 MB each) directly into the intake. No more manual copy-paste.
31
+ ## Upgrading from 0.1.x
46
32
 
47
- Supported trackers in 0.2.0: **Jira Cloud**, **Azure DevOps Services**.
33
+ Existing squad-kit users should run two commands, once per repo:
48
34
 
49
- Credentials are prompted during `squad init` and stored in `.squad/secrets.yaml`, which squad-kit auto-adds to your `.gitignore`. Environment variables (`JIRA_API_TOKEN`, `AZURE_DEVOPS_PAT`, or the cross-provider `SQUAD_TRACKER_API_KEY`) also work if you prefer them.
35
+ ```bash
36
+ pnpm add -g squad-kit@0.2.0 # or: npm install -g squad-kit@0.2.0 — or: squad upgrade
37
+ cd your-project && squad migrate
38
+ ```
50
39
 
51
- Pass `--no-fetch` to skip the call and scaffold an empty intake; `--no-attachments` to fetch metadata only.
40
+ `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.
52
41
 
53
- ---
42
+ 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).
54
43
 
55
44
  ## Install
56
45
 
@@ -62,200 +51,114 @@ pnpm add -g squad-kit@0.2.0
62
51
 
63
52
  Requires Node 18+.
64
53
 
65
- ---
66
-
67
54
  ## Quickstart
68
55
 
69
- In your project root:
70
-
71
- ```bash
72
- squad init # interactive: tracker, agents, name
73
- squad new-story auth --title "SSO support"
74
- # → edit .squad/stories/auth/sso-support/intake.md (paste title, description, criteria)
75
-
76
- # Write an intake without a tracker id (even when naming.includeTrackerId would normally require one):
77
- squad new-story feature-slug --no-tracker --title "quick exploration"
78
- # Per-invocation only — .squad/config.yaml is not modified.
79
- ```
80
-
81
- ### Managing configuration
82
-
83
- squad-kit stores settings in two files:
84
-
85
- - `.squad/config.yaml` — project name, tracker type, naming rules, planner provider.
86
- - `.squad/secrets.yaml` — API keys and tokens, `.gitignore`-d and chmod 0600.
87
-
88
- Never edit these by hand. Use:
89
-
90
- | Command | What it does |
91
- | --- | --- |
92
- | `squad config show` | Detailed view of both files (secrets masked). |
93
- | `squad config set planner` | Interactively change provider, model, and key. |
94
- | `squad config set tracker` | Interactively change tracker type, host, token. |
95
- | `squad config unset planner` | Disable the direct planner; keeps credentials. |
96
- | `squad config unset tracker` | Set tracker to `none`; keeps credentials. |
97
- | `squad config remove-credential planner` | Delete planner keys without touching config. |
98
- | `squad config remove-credential tracker` | Delete tracker keys without touching config. |
99
- | `squad status` | Quick operational summary (stories, plans). |
100
- | `squad doctor` | Full health check. |
101
-
102
56
  ```bash
103
- # then, in your agent (Claude Code / Cursor / Copilot / Gemini):
104
- /squad-plan .squad/stories/auth/sso-support/intake.md
57
+ cd your-project
58
+ squad init # interactive: tracker, planner, agents, name
59
+ squad new-story auth --title "SSO support" # or: squad new-story auth --id ENG-42 to auto-fetch
60
+ # → edit .squad/stories/auth/ENG-42/intake.md
105
61
 
106
- # → produces .squad/plans/auth/01-story-sso-support.md
62
+ /squad-plan .squad/stories/auth/ENG-42/intake.md # in your agent (Claude / Cursor / Copilot / Gemini)
63
+ # → .squad/plans/auth/01-story-sso-support.md
107
64
 
108
- # implementation: new agent chat, attach ONLY the plan file.
109
- # a cheap model can execute it end-to-end.
65
+ # new agent chat · attach ONLY the plan file · a cheap model ships it
110
66
  ```
111
67
 
112
- No slash commands in your agent? Pipe the prompt directly:
68
+ No slash commands in your agent? Skip the meta-prompt copy-paste entirely:
113
69
 
114
70
  ```bash
115
- squad new-plan .squad/stories/auth/sso-support/intake.md # prints to stdout, copies to clipboard
71
+ squad new-plan --api # interactive picker, direct provider call, writes the plan file
116
72
  ```
117
73
 
118
- ---
74
+ Configuration, credential edits, and non-interactive flags: see [`docs/customization.md`](docs/customization.md) and `squad config show`. Full walkthrough: [`docs/getting-started.md`](docs/getting-started.md).
119
75
 
120
76
  ## Commands
121
77
 
122
- | Command | What it does |
123
- |---|---|
124
- | `squad init` | Bootstrap `.squad/` with config and agent slash-commands (prompts are bundled in the package) |
125
- | `squad new-story [feature] [--id ID] [--title ...]` | Scaffold a story intake folder (optional feature prompts in a TTY) |
126
- | `squad new-plan <intake-path>` | Compose the plan-generation meta-prompt with the intake inlined; print to stdout + copy to clipboard |
127
- | `squad status` | Count stories/plans, show next global `NN`, tracker/planner credential hints, warn on duplicates |
128
- | `squad doctor` | Run a health check on your `.squad/` workspace |
129
- | `squad doctor --fix` | Apply non-destructive repairs (`.gitignore` block, `secrets.yaml` mode `0600`, missing dirs) |
130
- | `squad doctor --json` | Emit results as JSON on stdout (for scripting) |
131
- | `squad list [--feature <slug>]` | Table of stories + their plan state |
132
- | `squad rm` | Delete stories, plans, or whole features (`rm story` / `rm plan` / `rm feature`) with `--dry-run`, `--trash`, `-y` |
133
- | `squad tracker link [story] [id]` | Attach or update a tracker id on an intake (optional args prompt in a TTY) |
134
- | `squad migrate` | One-shot structural migrations from 0.1.x to 0.2.0 |
135
- | `squad migrate --dry-run` | Show what would change without applying |
136
- | `squad migrate --yes` | Skip the confirmation prompt |
137
- | `squad upgrade` | Check npm for a newer squad-kit release and install it |
138
- | `squad upgrade --check` | Only check; do not install |
139
- | `squad upgrade --yes` | Skip the confirmation prompt |
140
-
141
- ### Removing things safely
142
-
143
- squad-kit never asks you to `rm -rf` by hand. Use:
144
-
145
78
  | Command | What it does |
146
79
  | --- | --- |
147
- | `squad rm story` | Interactive picker; deletes intake + plan + overview row. |
148
- | `squad rm story <path\|id>` | Same, targeted. |
149
- | `squad rm plan` | Interactive picker; deletes the plan file only. |
150
- | `squad rm feature` | Interactive picker; deletes every story + plan + overview. |
151
- | `... --dry-run` | Preview without changing anything. |
152
- | `... --trash` | Move into `.squad/.trash/<ts>/` instead of deleting. |
153
- | `... -y` | Skip the confirmation prompt (non-interactive). |
154
-
155
- `.squad/.trash/` is git-ignored automatically. Recover with `mv .squad/.trash/<ts>/<item> .squad/...`. Empty it when you are sure: `rm -rf .squad/.trash`.
156
-
157
- ### `squad upgrade`
158
-
159
- `squad upgrade` queries `registry.npmjs.org` for the latest squad-kit release, detects your package manager (pnpm, npm, yarn, bun), and runs the appropriate global-install command with your confirmation. After upgrading, run `squad migrate` in each project to update the `.squad/` structure if needed.
160
-
161
- ### `squad doctor`
162
-
163
- Use this when something feels misconfigured. By default it is read-only: it loads `.squad/config.yaml` and `.squad/secrets.yaml`, checks directory layout, warns if a legacy `.squad/prompts/` directory is still present (removed in 0.2.0), validates planner settings and API keys (including a lightweight `/v1/models` probe — never a paid completion), checks Jira/Azure tracker config and credentials, and optionally hits a small REST endpoint to verify connectivity.
164
-
165
- `--fix` only performs safe, idempotent fixes: creating missing `.squad/stories` or `.squad/plans`, appending the managed `.gitignore` block (including `.squad/.trash/` when missing), and tightening `secrets.yaml` permissions on POSIX. It does not delete files or rewrite config; for legacy prompts cleanup and other migrations, use `squad migrate`.
166
-
167
- ### Upgrading from 0.1.x
168
-
169
- After upgrading the squad-kit package (`pnpm add -g squad-kit@latest`), run `squad migrate` once in each repo that uses squad-kit. This deletes the now-unused `.squad/prompts/` directory, ensures your `.gitignore` has the squad-kit block, tightens permissions on `.squad/secrets.yaml`, and normalises `.squad/config.yaml` formatting. Comments inside `config.yaml` will be dropped.
170
-
171
- ---
172
-
173
- ## CLI conventions
174
-
175
- ### Interactive-first
176
-
177
- Every squad-kit command prompts for missing required input when run in a TTY. Use `-y` or `--yes` to opt out — missing input then fails fast instead of prompting. Useful in scripts and CI, e.g. `CI=1 squad new-story user-auth --id ENG-42 --yes`.
178
-
179
- Set `CI=1` to force non-interactive behaviour even in a TTY (matches how other tools behave in CI environments).
80
+ | `squad init` | Scaffold `.squad/` with config, bundled prompts reference, and agent slash-commands. See [`docs/getting-started.md`](docs/getting-started.md). |
81
+ | `squad new-story [feature] [--id ID] [--title …] [--no-tracker] [--no-fetch] [--no-attachments] [--attachment-mb n]` | Create a story intake. Auto-fetches from the configured tracker when `--id` is given. |
82
+ | `squad new-plan [intake] [--api] [--copy] [--feature <slug>] [--all]` | Generate a plan from an intake. `--api` calls the configured planner; without `--api`, copy-paste mode prints the prompt to stdout and clipboard (`--no-clipboard` to skip the clipboard). |
83
+ | `squad status` | Counts, next `NN`, planner and tracker rows (including credential source). |
84
+ | `squad list [--feature <slug>]` | Table of stories and plan state. |
85
+ | `squad tracker link [story] [id]` | Attach or update a tracker id on an intake. |
86
+ | `squad config <show\|set\|unset\|remove-credential> …` | View and edit `.squad/config.yaml` and `.squad/secrets.yaml` interactively. See [`docs/customization.md`](docs/customization.md). |
87
+ | `squad rm <story\|plan\|feature> [target] [--dry-run] [--trash] [-y]` | Safely delete with cascading overview updates. |
88
+ | `squad doctor [--fix] [--json]` | Full health check; `--fix` applies non-destructive repairs. |
89
+ | `squad migrate [--dry-run] [-y]` | One-shot 0.1.x → 0.2.0 structural migrations. Destructive. |
90
+ | `squad upgrade [--check] [-y]` | Check npm and install a newer squad-kit release. |
91
+
92
+ Deeper option lists: `squad <command> --help` and the `docs/` pages above.
180
93
 
181
94
  ## Direct planner (optional)
182
95
 
183
- Squad can call a strong planning model for you from the terminal so you do not have to paste the prompt into your agent. Off by default.
96
+ Off by default. Enable during `squad init` (answer **yes** to *Enable automatic plan generation?*) or later with `squad config set planner`. Supported providers: Anthropic, OpenAI, Google.
184
97
 
185
- 1. `squad init --force` and answer **yes** to *Enable automatic plan generation?* (or re-run `squad init -y --planner anthropic`). Use `--skip-secrets-prompt` (or `--no-prompt-secrets`) if you want to skip all secret prompts in a TTY session.
186
- 2. Export the provider's API key:
98
+ Credential resolution order:
187
99
 
188
- ```bash
189
- export ANTHROPIC_API_KEY=... # or OPENAI_API_KEY / GOOGLE_API_KEY
190
- ```
100
+ 1. Provider env var (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`).
101
+ 2. `.squad/secrets.yaml` under `planner.<provider>.apiKey` (or cross-provider `SQUAD_PLANNER_API_KEY`).
102
+ 3. Interactive prompt (TTY only).
103
+ 4. Fail with a recovery hint.
191
104
 
192
- 3. `squad new-plan` — pick an un-planned intake; squad reads only the files the planner asks for (bounded by `planner.budget`), writes the plan to `.squad/plans/<feature>/NN-story-<slug>.md`, and prints a summary.
193
-
194
- Optional: override the default plan-phase model id (per provider) without changing squad-kit:
105
+ Override the default plan-phase model without editing squad-kit:
195
106
 
196
107
  ```yaml
197
108
  planner:
198
109
  enabled: true
199
110
  provider: anthropic
200
- # Optional: pin a specific model for the plan phase, overriding the squad-kit default.
201
- # Useful when riding a newer provider release ahead of a squad-kit update, or when the
202
- # default has been deprecated.
203
111
  modelOverride:
204
- anthropic: claude-opus-5-0
112
+ anthropic: claude-opus-5-0 # riding a newer provider release early
205
113
  ```
206
114
 
207
- Slash commands inside your agent (`/squad-plan`) continue to work unchanged — the agent already has your repo in scope.
208
-
209
- Squad-kit never reads API keys from `.squad/config.yaml`. You can set keys via environment variables, save them in `.squad/secrets.yaml` (prompted by `squad init` when the planner is enabled), or a mix. See [Secrets](#secrets) below.
210
-
211
- #### Secrets
115
+ `squad status` marks the planner row `(override)` when a `modelOverride` is active. `squad doctor` probes the provider's `/v1/models` endpoint (no paid completion) and tells you what to do if the id is no longer served.
212
116
 
213
- - `.squad/config.yaml` — shape and non-sensitive settings. Safe to commit.
214
- - `.squad/secrets.yaml` — API tokens for the planner and tracker. **Always git-ignored** (managed by squad-kit).
215
- - Environment variables override `.squad/secrets.yaml`.
216
- - Priority: env var → `.squad/secrets.yaml` → prompt (interactive) → fail.
117
+ Slash commands inside your agent (`/squad-plan`) continue to work unchanged — the agent already has your repo in scope. The direct planner is an alternative path, not a replacement. For where keys live, see [Secrets](#secrets) below and [`docs/customization.md`](docs/customization.md).
217
118
 
218
- ---
119
+ ## Tracker auto-fetch
219
120
 
220
- ## Agent integration
121
+ `squad new-story <feature> --id <ID>` pulls the work item's title, description, labels, and attachments (≤ 10 MB each) straight into the intake. Supported trackers in 0.2.0: **Jira Cloud**, **Azure DevOps Services**.
221
122
 
222
- At `squad init` you pick which agents get native slash commands. Supported:
123
+ Credentials follow the same resolution order as the planner (env → `.squad/secrets.yaml` → prompt → fail). `squad init` prompts for them when a supported tracker is selected.
223
124
 
224
- - **Claude Code** → `.claude/commands/squad-plan.md`, `.claude/commands/squad-new-story.md`
225
- - **Cursor** → `.cursor/commands/squad-*.md`
226
- - **GitHub Copilot** → `.github/prompts/squad-plan.prompt.md`
227
- - **Gemini CLI** → `.gemini/commands/squad-plan.toml`
125
+ Flags:
228
126
 
229
- Unsupported agents work fine too — `squad new-plan` prints the composed prompt on stdout.
127
+ - `--no-fetch` — scaffold an empty intake; never call the tracker.
128
+ - `--no-attachments` — fetch metadata only.
129
+ - `--attachment-mb <n>` — override the 10 MB per-file cap.
130
+ - `--no-tracker` — skip the tracker id requirement for this story even when `naming.includeTrackerId: true`.
230
131
 
231
- ---
132
+ Full example with Azure DevOps: [`docs/getting-started.md`](docs/getting-started.md).
232
133
 
233
- ## Trackers
134
+ ## Secrets
234
135
 
235
- Optional. Configure in `.squad/config.yaml`:
136
+ squad-kit stores settings in two files:
236
137
 
237
- ```yaml
238
- tracker:
239
- type: linear # none | github | linear | jira | azure
240
- naming:
241
- includeTrackerId: true
242
- globalSequence: true
243
- ```
138
+ | File | Purpose | Git-tracked? | Editable by hand? |
139
+ | --- | --- | --- | --- |
140
+ | `.squad/config.yaml` | Project name, tracker, naming, agents, planner shape. | yes — commit it | yes, but `squad config set` is safer |
141
+ | `.squad/secrets.yaml` | Planner + tracker API tokens. | **no** — auto-ignored, `0600` on POSIX | no — use `squad config set` / `squad init` |
244
142
 
245
- `--id` on `new-story` is validated against the tracker's id format. For **Jira** and **Azure DevOps**, with credentials configured, the CLI can [auto-fetch](#tracker-auto-fetch-new-in-020) issue metadata and attachments. Other trackers (GitHub, Linear) use id format validation only in v0.2.
143
+ `config.yaml` rejects any key matching `apiKey`, `token`, `secret`, or `credential` at load time, so accidental commits fail loud. Rotate a credential with `squad config set planner` or `squad config set tracker`; remove one with `squad config remove-credential <section>`.
246
144
 
247
- ---
145
+ ## Why not Spec-Kit?
248
146
 
249
- ## What's *not* in v0.2
147
+ Both aim at spec-driven development. They make different bets.
250
148
 
251
- We ship lean on purpose. Current non-goals:
149
+ | | squad-kit | Spec-Kit |
150
+ | --- | --- | --- |
151
+ | Commands | `init`, `new-story`, `new-plan`, `status`, `doctor`, `migrate`, `upgrade`, `list`, `rm`, `tracker link`, `config` | `constitution`, `specify`, `clarify`, `plan`, `tasks`, `analyze`, `checklist`, `implement` |
152
+ | `/implement` turn starts with | one plan file (~5–15 KB) | 5–7 command templates + cross-artifact reads (~15–25 KB) |
153
+ | Model-tier awareness | Built into the philosophy (planner ≠ executor) | Not prescribed |
154
+ | Generated artifacts per story | `intake.md`, `NN-story-<slug>.md`, overview row | `spec.md`, `plan.md`, `data-model.md`, `contracts/`, `research.md`, `quickstart.md`, `tasks.md` |
155
+ | Customization | Prompts ship with the CLI (fork squad-kit to change them). | Template override stack with presets/extensions |
156
+ | Runtime | Node + TypeScript, npm-distributable | Python + `uv` |
157
+ | Scope | Intentionally small | Broad, with safety nets (`clarify`, `analyze`) |
252
158
 
253
- - OpenAI-compatible generic endpoint (local models, OpenRouter, etc.); [Direct planner (optional)](#direct-planner-optional) covers hosted Anthropic, OpenAI, and Google
254
- - MCP server
255
- - `/clarify`, `/analyze`, constitution-equivalent
256
- - Telemetry
159
+ Spec-Kit ships safety rails. Squad-kit ships the cheap path and gets out of the way. Pick squad-kit when your planner already produces trustworthy plans; pick Spec-Kit when you want the process to catch planning mistakes for you.
257
160
 
258
- ---
161
+ See [`docs/philosophy.md`](docs/philosophy.md) for the token math and [`docs/vs-spec-kit.md`](docs/vs-spec-kit.md) for the full comparison.
259
162
 
260
163
  ## Tradeoffs to know
261
164
 
@@ -263,7 +166,15 @@ We ship lean on purpose. Current non-goals:
263
166
  - **Plans are project-coupled.** They reference real file paths. That is the point — do not expect portability between projects.
264
167
  - **Global `NN` can collide on parallel branches.** Rebase-and-renumber is the resolution. Documented in [`docs/customization.md`](docs/customization.md).
265
168
 
266
- ---
169
+ ## Non-goals for 0.2
170
+
171
+ We ship lean on purpose. Current non-goals:
172
+
173
+ - OpenAI-compatible generic endpoint (local models, OpenRouter, etc.); [Direct planner (optional)](#direct-planner-optional) covers hosted Anthropic, OpenAI, and Google
174
+ - MCP server
175
+ - `squad implement` (targeted for 0.3)
176
+ - `/clarify`, `/analyze`, constitution-equivalent
177
+ - Telemetry
267
178
 
268
179
  ## License
269
180