squad-kit 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-04-22
+
+### Fixed
+
+- **`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:
+  - Detects 429s across Anthropic, OpenAI, and Google (new `errorKind: 'rate_limit'` on `ProviderResponse`).
+  - Parses `Retry-After` (seconds or HTTP-date) and Google's body-level `retryDelay` field.
+  - 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.
+  - 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).
+- 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.
+
+### Added
+
+- `detectRateLimit()` and `rateLimitMessage()` in `src/planner/provider-errors.ts`. Both cover all three supported providers and are unit-tested with real-shaped 429 fixtures.
+
+## [0.2.0] - 2026-04-22
+
+### tracker-intake-fetch
+
+**Added**
+
+- `squad new-story --id <ID>` auto-fetches title, description, labels, and attachments (≤ 10 MB each) from the configured tracker. Supported: Jira Cloud, Azure DevOps Services.
+- `.squad/secrets.yaml` as a second credential source (after environment variables) for planner keys and tracker tokens. Created with mode `0600` on POSIX; auto-added to `.gitignore`.
+- `squad init` now prompts for tracker credentials when a supported tracker is chosen, and offers to save the planner key inline as an alternative to exporting an env var.
+- `squad status` shows tracker type, workspace, and credential source (`env` / `secrets.yaml` / `missing`).
+- `squad new-story` flags: `--no-fetch`, `--no-attachments`, `--attachment-mb <n>`.
+- `squad new-story --no-tracker` — skip tracker id and fetch for a single story in a workspace that normally requires tracker ids. Interactive mode now offers "skip tracker for this story" alongside "enter id" when required.
+
+**Changed**
+
+- `squad new-story` accepts the feature slug as an optional positional; prompts when it is omitted in a TTY (including a picker for existing feature folders). Passing `-y` / `--yes` keeps fail-fast behaviour when the slug is missing. `CI=1` forces non-interactive mode even in a TTY.
+- `squad tracker link` accepts both the story path and the tracker id as optional positionals; prompts with a story picker and id input when omitted. `-y` / `--yes` and `CI=1` force non-interactive fail-fast.
+- CLI-wide: commands treat missing required input as promptable in a TTY; `-y` / `--yes` and `CI=1` opt out.
+- Credential resolution order documented: env var → `.squad/secrets.yaml` → prompt → fail. Applies to both planner and tracker credentials.
+
+**Security**
+
+- `.squad/config.yaml` continues to reject secret-shaped keys (`apiKey`, `token`, …). Secrets live in `.squad/secrets.yaml` only.
+- Auto-managed `.gitignore` block covers `.squad/secrets.yaml`, `.squad/stories/**/attachments/`, and `.squad/.trash/`.
+
+### Added
+
+- `squad config` command group with `show`, `set planner`, `set tracker`, `unset planner`, `unset tracker`, and `remove-credential <section>` subcommands. Every field in `.squad/config.yaml` and `.squad/secrets.yaml` can now be edited interactively without opening a text editor.
+- `squad init` on an existing workspace now offers **Reconfigure planner / Reconfigure tracker / Overwrite / Cancel** instead of silently bailing. `--force` keeps the old overwrite behaviour for scripts.
+
+- `squad upgrade` self-update command. Detects the package manager used to install squad-kit, fetches the latest version from npm, and runs the appropriate global-install command after confirmation. Refuses dev installs and major version bumps (print-manual-guide instead).
+- `squad migrate` command applies one-shot 0.1.x → 0.2.0 structural migrations (delete legacy prompts, gitignore, secrets perms, planner budget defaults, config normalisation). Idempotent; destructive by design; gated behind a confirmation prompt unless `--yes` is passed.
+- `squad doctor` command: a full health check covering planner config, tracker credentials, model list probes (no completion calls), `.gitignore` managed block, `secrets.yaml` permissions, legacy `.squad/prompts/`, and `.squad/` layout. `--fix` applies non-destructive repairs only; destructive fixes belong in `squad migrate`.
+- `planner.modelOverride` (per-provider) lets you pin a different plan-phase model id without editing squad-kit source.
+- `pnpm verify:models` (`scripts/verify-models.ts`) probes provider model list APIs before publish so pinned ids cannot drift unnoticed.
+- Clear, actionable error when the planner model returns 404 (upgrade, config override, or `squad doctor`).
+- `squad status` marks the planner row with `(override)` when `modelOverride` is active for the current provider.
+- Direct planner API (optional): Anthropic, OpenAI, Google. Squad calls the planner for you and writes the plan file.
+- Demand-driven context: planner reads files on request via a bounded budget (file count, bytes, wall-clock).
+- Interactive picker in `squad new-plan` over un-planned intakes.
+- Already-planned guard with `--yes` override.
+- `--api`, `--copy`, `--feature`, `--all` flags on `new-plan`.
+- `squad init` asks about planner setup; `--planner <provider>` for non-interactive.
+- `squad status` shows planner provider, model, and env-var presence.
+- `squad list` shows which plans were generated by the API vs copy-paste.
+- Visual identity: mint-green brand, custom spinner frames, banner, summary boxes, consistent prefixes across all commands.
+- `squad rm` command group: `rm story`, `rm plan`, `rm feature`, each with `--dry-run`, `--trash`, `-y`, and interactive pickers. Deleting a story cascades to the matching plan file and overview row. `.squad/.trash/<timestamp>/` is now git-ignored automatically.
+
+### Changed
+
+- Every user-facing error now ends with a recommended next command (for example, `Run \`squad doctor\` to diagnose`). Failures no longer dead-end users at an error string.
+- `ensureGitignore` now includes `.squad/.trash/` in the managed block. Existing users will see the line appended on the next `squad doctor --fix` or any command that calls `ensureGitignore`.
+- Anthropic plan model pinned to the versioned Claude API id `claude-opus-4-7` (replacing the prior alias default) and execute remains dated `claude-haiku-4-5-20251001`, per Anthropic’s model overview — run `pnpm verify:models` after changes.
+- `new-plan <intake>` is now optional; omit to pick interactively.
+- `--no-copy` renamed to `--no-clipboard` (old flag removed). `--copy` now forces copy-paste mode.
+- Prompts (`generate-plan.md`, `intake.md`, `story-skeleton.md`) now ship entirely within the squad-kit package. Fresh installs no longer create a `.squad/prompts/` directory. Stale `.squad/prompts/` from 0.1.x installs is ignored at runtime and cleaned up by `squad migrate`.
+
+### Breaking changes for 0.1.x users
+
+- 0.1.x users who upgrade should run `squad migrate` once per repo. A `.squad/prompts/` folder left from 0.1.x is deleted outright (prompts are now bundled in the squad-kit package).
+- If you customised `.squad/prompts/*.md`, those customisations are no longer used. The canonical prompts are in the installed squad-kit package. To customise, fork squad-kit and patch `templates/prompts/`. (This is intentional: behaviour was inconsistent before — some commands ignored the user copy — and silent version drift was breaking workflows.)
+
+### Security
+
+- Config loader rejects any YAML entry whose key looks like `apiKey`, `token`, `secret`, or `credential`.
+
+### Known limitations
+
+- OpenAI and Google planner model ids in squad-kit remain provider “latest”-style names for 0.2.0; dated snapshots for those providers are planned for 0.2.1 once verified.
+
+### Non-goals (still deferred)
+
+- OpenAI-compatible generic endpoint (OpenRouter, Ollama, local). Targeted for 0.3.
+- `squad implement` command. Targeted for 0.3.
+- MCP server, telemetry.
+
+## [0.1.0] - 2026-04-21
+
+First public release.
+
+### Added
+
+- `squad init` — scaffolds `.squad/` with `config.yaml`, prompt templates, and agent slash commands.
+- `squad new-story <feature-slug>` — creates `.squad/stories/<feature>/<id>/intake.md` with `attachments/`.
+- `squad new-plan <intake-path>` — composes the plan-generation meta-prompt inline with the intake, prints to stdout, and copies to clipboard.
+- `squad status` — reports story / plan counts and next global `NN`.
+- `squad list [--feature <slug>]` — table of stories and their plan state.
+- `squad tracker link <story> <id>` — upserts a tracker id on an existing intake.
+- Agent slash-command templates for **Claude Code**, **Cursor**, **GitHub Copilot**, and **Gemini CLI**.
+- Tracker id validators for **GitHub**, **Linear**, **Jira**, and **Azure DevOps** (no API calls; format validation only).
+- 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
+[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,131 +1,164 @@
 # squad-kit
 
-**Plan once, execute cheap.** A 3-step SDD-style workflow CLI for AI-assisted coding: **raw story → good plan → implementation**.
+[![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)
 
-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.
+**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).
 
 ```
 .squad/
-├── prompts/                # meta-prompts you can edit
-├── stories/<feature>/<id>/ # intake + attachments (one per story)
-└── plans/<feature>/        # NN-story-<slug>.md (one per executable plan)
+├── stories/<feature>/<id>/  # intake + attachments (one per story)
+└── plans/<feature>/         # NN-story-<slug>.md (one per executable plan)
 ```
 
----
+## What's new in 0.2.0
 
-## Why not Spec-Kit?
+- **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.
+- **Tracker auto-fetch.** `squad new-story --id <ID>` pulls title, description, labels, and attachments (≤ 10 MB each) from Jira Cloud or Azure DevOps Services.
+- **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.
+- **Interactive-first UX.** Missing input prompts in a TTY; `-y` / `--yes` or `CI=1` opts out and fails fast.
+- **`squad doctor`.** Full read-only health check; `--fix` for non-destructive repairs, `--json` for scripting.
+- **`squad migrate`.** One-shot 0.1.x → 0.2.0 structural migrations (delete legacy `.squad/prompts/`, permissions, config normalisation). Destructive; use `--dry-run` first.
+- **`squad upgrade`.** Safe npm-backed self-update (`--check` to verify only).
+- **`squad config`.** `show`, `set planner` / `set tracker`, `unset …`, `remove-credential …` — edit config and secrets without hand-editing YAML.
+- **`squad rm`.** `rm story` / `rm plan` / `rm feature` with `--dry-run`, `--trash`, and cascading overview updates.
+- **Bundled prompts.** `generate-plan.md`, `intake.md`, and `story-skeleton.md` ship inside the npm package; upgrade the CLI to update them.
 
-Both aim at spec-driven development. They make different bets.
+Full list in [`CHANGELOG.md`](CHANGELOG.md).
 
-| | squad-kit | Spec-Kit |
-|---|---|---|
-| Commands | `init`, `new-story`, `new-plan`, `status`, `list`, `tracker link` | `constitution`, `specify`, `clarify`, `plan`, `tasks`, `analyze`, `checklist`, `implement` |
-| `/implement` turn starts with | one plan file (~5–15 KB) | 5–7 command templates + cross-artifact reads (~15–25 KB) |
-| Model-tier awareness | Built into the philosophy (planner ≠ executor) | Not prescribed |
-| 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` |
-| Customization | Prompts live in your repo as plain Markdown. Edit freely. | Template override stack with presets/extensions |
-| Runtime | Node + TypeScript, npm-distributable | Python + `uv` |
-| Scope | Intentionally small | Broad, with safety nets (`clarify`, `analyze`) |
+## Upgrading from 0.1.x
 
-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.
+Existing squad-kit users should run two commands, once per repo:
 
-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.
+```bash
+pnpm add -g squad-kit@0.2.0       # or: npm install -g squad-kit@0.2.0 — or: squad upgrade
+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).
 
 ## Install
 
 ```bash
-npm install -g squad-kit
+npm install -g squad-kit@0.2.0
 # or
-pnpm add -g squad-kit
+pnpm add -g squad-kit@0.2.0
 ```
 
 Requires Node 18+.
 
----
-
 ## Quickstart
 
-In your project root:
-
 ```bash
-squad init                        # interactive: tracker, agents, name
-squad new-story auth --title "SSO support"
-# → edit .squad/stories/auth/sso-support/intake.md (paste title, description, criteria)
+cd your-project
+squad init                                              # interactive: tracker, planner, agents, name
+squad new-story auth --title "SSO support"              # or: squad new-story auth --id ENG-42 to auto-fetch
+# → edit .squad/stories/auth/ENG-42/intake.md
 
-# then, in your agent (Claude Code / Cursor / Copilot / Gemini):
-/squad-plan .squad/stories/auth/sso-support/intake.md
+/squad-plan .squad/stories/auth/ENG-42/intake.md        # in your agent (Claude / Cursor / Copilot / Gemini)
+# → .squad/plans/auth/01-story-sso-support.md
 
-# → produces .squad/plans/auth/01-story-sso-support.md
-
-# implementation: new agent chat, attach ONLY the plan file.
-# a cheap model can execute it end-to-end.
+# new agent chat · attach ONLY the plan file · a cheap model ships it
 ```
 
-No slash commands in your agent? Pipe the prompt directly:
+No slash commands in your agent? Skip the meta-prompt copy-paste entirely:
 
 ```bash
-squad new-plan .squad/stories/auth/sso-support/intake.md   # prints to stdout, copies to clipboard
+squad new-plan --api   # interactive picker, direct provider call, writes the plan file
 ```
 
----
+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).
 
 ## Commands
 
 | Command | What it does |
-|---|---|
-| `squad init` | Bootstrap `.squad/` with prompts, config, and agent slash-commands |
-| `squad new-story <feature> [--id ID] [--title ...]` | Scaffold a story intake folder |
-| `squad new-plan <intake-path>` | Compose the plan-generation meta-prompt with the intake inlined; print to stdout + copy to clipboard |
-| `squad status` | Count stories/plans, show next global `NN`, warn on duplicates |
-| `squad list [--feature <slug>]` | Table of stories + their plan state |
-| `squad tracker link <story> <id>` | Attach or update a tracker id on an intake |
-
----
-
-## Agent integration
+| --- | --- |
+| `squad init` | Scaffold `.squad/` with config, bundled prompts reference, and agent slash-commands. See [`docs/getting-started.md`](docs/getting-started.md). |
+| `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. |
+| `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). |
+| `squad status` | Counts, next `NN`, planner and tracker rows (including credential source). |
+| `squad list [--feature <slug>]` | Table of stories and plan state. |
+| `squad tracker link [story] [id]` | Attach or update a tracker id on an intake. |
+| `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). |
+| `squad rm <story\|plan\|feature> [target] [--dry-run] [--trash] [-y]` | Safely delete with cascading overview updates. |
+| `squad doctor [--fix] [--json]` | Full health check; `--fix` applies non-destructive repairs. |
+| `squad migrate [--dry-run] [-y]` | One-shot 0.1.x → 0.2.0 structural migrations. Destructive. |
+| `squad upgrade [--check] [-y]` | Check npm and install a newer squad-kit release. |
 
-At `squad init` you pick which agents get native slash commands. Supported:
+Deeper option lists: `squad <command> --help` and the `docs/` pages above.
 
-- **Claude Code** → `.claude/commands/squad-plan.md`, `.claude/commands/squad-new-story.md`
-- **Cursor** → `.cursor/commands/squad-*.md`
-- **GitHub Copilot** → `.github/prompts/squad-plan.prompt.md`
-- **Gemini CLI** → `.gemini/commands/squad-plan.toml`
+## Direct planner (optional)
 
-Unsupported agents work fine too — `squad new-plan` prints the composed prompt on stdout.
+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.
 
----
+Credential resolution order:
 
-## Trackers
+1. Provider env var (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`).
+2. `.squad/secrets.yaml` under `planner.<provider>.apiKey` (or cross-provider `SQUAD_PLANNER_API_KEY`).
+3. Interactive prompt (TTY only).
+4. Fail with a recovery hint.
 
-Optional. Configure in `.squad/config.yaml`:
+Override the default plan-phase model without editing squad-kit:
 
 ```yaml
-tracker:
-  type: linear     # none | github | linear | jira | azure
-naming:
-  includeTrackerId: true
-  globalSequence: true
+planner:
+  enabled: true
+  provider: anthropic
+  modelOverride:
+    anthropic: claude-opus-5-0      # riding a newer provider release early
 ```
 
-`--id` on `new-story` is validated against the tracker's id format (e.g. `ENG-42` for Linear, `843806` for Azure). No API calls in v0.1.
+`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.
 
----
+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).
 
-## What's *not* in v0.1
+## Tracker auto-fetch
 
-We ship lean on purpose. Current non-goals:
+`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**.
 
-- Direct Anthropic/OpenAI API invocation (cost stays with your agent subscription)
-- MCP server
-- `/clarify`, `/analyze`, constitution-equivalent
-- Tracker API calls (id validation only)
-- Telemetry
+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.
+
+Flags:
+
+- `--no-fetch` — scaffold an empty intake; never call the tracker.
+- `--no-attachments` — fetch metadata only.
+- `--attachment-mb <n>` — override the 10 MB per-file cap.
+- `--no-tracker` — skip the tracker id requirement for this story even when `naming.includeTrackerId: true`.
 
-Open to revisiting these for v0.2 based on usage.
+Full example with Azure DevOps: [`docs/getting-started.md`](docs/getting-started.md).
 
----
+## Secrets
+
+squad-kit stores settings in two files:
+
+| File | Purpose | Git-tracked? | Editable by hand? |
+| --- | --- | --- | --- |
+| `.squad/config.yaml` | Project name, tracker, naming, agents, planner shape. | yes — commit it | yes, but `squad config set` is safer |
+| `.squad/secrets.yaml` | Planner + tracker API tokens. | **no** — auto-ignored, `0600` on POSIX | no — use `squad config set` / `squad init` |
+
+`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>`.
+
+## Why not Spec-Kit?
+
+Both aim at spec-driven development. They make different bets.
+
+| | squad-kit | Spec-Kit |
+| --- | --- | --- |
+| Commands | `init`, `new-story`, `new-plan`, `status`, `doctor`, `migrate`, `upgrade`, `list`, `rm`, `tracker link`, `config` | `constitution`, `specify`, `clarify`, `plan`, `tasks`, `analyze`, `checklist`, `implement` |
+| `/implement` turn starts with | one plan file (~5–15 KB) | 5–7 command templates + cross-artifact reads (~15–25 KB) |
+| Model-tier awareness | Built into the philosophy (planner ≠ executor) | Not prescribed |
+| 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` |
+| Customization | Prompts ship with the CLI (fork squad-kit to change them). | Template override stack with presets/extensions |
+| Runtime | Node + TypeScript, npm-distributable | Python + `uv` |
+| Scope | Intentionally small | Broad, with safety nets (`clarify`, `analyze`) |
+
+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.
+
+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.
 
 ## Tradeoffs to know
 
@@ -133,7 +166,15 @@ Open to revisiting these for v0.2 based on usage.
 - **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).
 
----
+## Non-goals for 0.2
+
+We ship lean on purpose. Current non-goals:
+
+- OpenAI-compatible generic endpoint (local models, OpenRouter, etc.); [Direct planner (optional)](#direct-planner-optional) covers hosted Anthropic, OpenAI, and Google
+- MCP server
+- `squad implement` (targeted for 0.3)
+- `/clarify`, `/analyze`, constitution-equivalent
+- Telemetry
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,57 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest minor release of squad-kit receives security fixes.
+
+| Version | Supported |
+| ------- | --------- |
+| 0.2.x   | ✅        |
+| 0.1.x   | ❌        |
+| < 0.1   | ❌        |
+
+## Reporting a vulnerability
+
+**Please do not open a public GitHub issue for security reports.**
+
+Email the maintainer privately at **momenysr@gmail.com** with:
+
+- A description of the issue and its impact.
+- Steps to reproduce (proof-of-concept preferred).
+- Affected version(s) and environment (OS, Node version).
+- Any suggested mitigation, if you have one.
+
+You can expect:
+
+1. **Acknowledgement** within 72 hours.
+2. **Initial assessment** within 7 days.
+3. **Fix + coordinated disclosure** as quickly as the severity warrants — typically a patch release within 14 days for high-severity issues.
+
+Credit will be given in the release notes unless you prefer to remain anonymous.
+
+## Handling credentials
+
+squad-kit reads API tokens from (in order):
+
+1. **Environment variables** — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, `SQUAD_PLANNER_API_KEY` for planner; `JIRA_API_TOKEN`, `AZURE_DEVOPS_PAT`, `SQUAD_TRACKER_API_KEY` for trackers.
+2. **`.squad/secrets.yaml`** — created with mode `0600` on POSIX; always included in `.gitignore` by `squad init`.
+3. **Interactive prompt** — when the terminal is a TTY and the command needs a credential that is missing.
+
+### Non-goals
+
+- `.squad/config.yaml` must never contain secrets. Loading it with a key matching `apiKey`, `api_key`, `token`, `secret`, `credential`, or `credentials` raises a loud error.
+- squad-kit does not integrate with OS keychains in 0.2.0. The secrets file model is intentional: it is inspectable, excluded by ignore rules, and portable.
+- Credentials are never logged. Tracker error messages redact tokens; planner provider errors do the same.
+
+## Scope
+
+squad-kit is a local-only CLI. It can call **optional** network APIs (tracker fetch, direct planner) when the user enables those flows and provides credentials. It does not execute user code. Reports in scope include:
+
+- Arbitrary file read/write outside the workspace caused by malformed input (e.g. path-traversal via feature slugs or intake paths).
+- Command injection via clipboard helpers or spawned processes.
+- Supply-chain concerns in shipped dependencies (`@inquirer/prompts`, `commander`, `fs-extra`, `js-yaml`, `kleur`).
+
+Out of scope:
+
+- Content of user-authored intakes and plans under `.squad/stories/` and `.squad/plans/` (treat as trusted project input to your agents).
+- Vulnerabilities in the AI agents that consume squad-kit output (Claude Code, Cursor, Copilot, Gemini). Report those upstream.