squad-kit 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -7,6 +7,191 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] — 2026-11-05
+
+squad-kit 1.2 is about trust: squad-kit shows that it understands your project, says what the work really cost, and
+makes the squad's work harder to fake. It also takes a whole requirements document and builds it, story by story.
+Windows is less protected and not fully tested yet (see What's safer).
+
+### What's new
+
+#### From a BRD to a built product
+
+- **A new Requirements page** (after Overview). **Add a BRD**: a PDF, Word or Markdown file, or pasted text, with
+  mockups if you have them. The Analyst reads it live and asks only about what is **missing in the BRD** or where
+  **two parts clash**. Then it writes epics, features and stories, each with its checks (Given, When, Then), size,
+  needs and its place in the document.
+- **Review it as a tree or a map.** Rename, rewrite, move, add or remove any part, or ask the Analyst to redo one.
+  An estimate from this project's own tickets: "20 stories, about $140 and 6 hours, 2 at a time". Nothing is built
+  or sent before **Approve breakdown**.
+- **Send to Azure DevOps**: epics, features and stories with parent and dependency links, into the backlog. **Send
+  changes** updates only what changed. squad-kit never deletes there, and a cut-off send makes no doubles.
+- **Build continuously**: each story becomes a ticket on the new **Builds by itself** track, in the order its needs
+  allow, within the parallel limit and the budgets. No questions, the plan is approved by itself, small choices are
+  listed under **Decided for you** (press **Change** on any), and it merges by itself once the checks, the review
+  and the screenshots pass. It stops only for a gap, a clash or a failed check, and then only that story and the
+  ones that need it wait. Releases stay your button.
+- Terminal: `squad requirements add|show|answer|edit|move|approve|send|build|start|…`, `squad decided`. See
+  [From a BRD to a built product](docs/requirements.md).
+
+#### Proof you can read
+
+- **squad-kit takes the screenshots itself, with its own browser.** The Tester says which pages, steps and sizes.
+  squad-kit opens the story's own copy of the app, does the steps and takes the pictures.
+- **One or more pictures for each "done when"**: one per part or case, up to 6.
+- **Each "done when" gets a verdict**, from the Tester and squad-kit's own check of all its pictures together:
+  **Met**, **Not working yet** (a picture shows it does not work), **Not shown yet** (the pictures do not show it
+  clearly) or **Not on a screen** (it cannot be shown at all, like an email or what happens after a restart). Not
+  working yet goes back to the Builder once, then it is a plain stop. Not shown yet goes back to the Tester up to 2
+  more times, keeps the good pictures and never reaches the Builder. Not on a screen keeps its reason and does not
+  stop the story, unless every "done when" ends that way.
+- **Also changed, not in the plan**: what the change touches beyond its plan, in the Reviewer's words. It never
+  blocks. You see it at your check, on a stop, on the ticket and in the release notes.
+
+#### Your turn
+
+- **Where to look**: each page the proof names, with the "done when" it shows.
+- **Try it yourself**: runs the story's own copy of the app, with the change in it and nothing merged, so you can
+  click through it before **Looks right**. It stops by itself when the story moves on. Terminal: `squad try <ticket>`.
+- **Ask a question** on every story, in every state: working, in the queue, waiting for another story, stopped, at
+  review, taken over or released. Whoever knows the story best answers: the Analyst before the build, the Builder
+  during and after it, the Tester once there are screenshots. It answers questions only, and the story stays exactly
+  where it is. Terminal: `squad chat <ticket> --ask`.
+
+#### First run and Overview
+
+- **Add project says what it found** (code with or without git, an empty folder, several repos, an older
+  squad-kit) and what happens next, before you confirm.
+- **A setup page with live steps**: project memory, the AI tool, the Architect reading the code, how to test and run
+  it, trying the tests, opening the app once with a screenshot, and your overview. Each step has its time; a failure
+  has a way out and never stops the setup. **Notify me when it is ready**. Quality is asked once here.
+- **The Overview page**, first in the sidebar: what the project is, who uses it, what it can do today, how its parts
+  fit together, things worth knowing, the rules found, the proof, and three ideas for a first ticket. It stays up to
+  date after every merged ticket.
+- **The rules the Architect found are proposals until you approve them** with **Looks right, start working**. They
+  used to be saved as approved without being shown. **Something is wrong** opens a talk with the Architect.
+- **An empty project asks "What do you want to build?"**, in your own words, in English or Arabic. The Architect
+  writes down what you want with first stories for it, and picks the technology itself when your first story is
+  planned. Terminal: `squad overview --build "what you want"`.
+- **squad-kit finds the commands of a project that started empty.** After the first build it reads how to test and
+  run the project from its files, and saves that. Nobody is asked.
+- Terminal: `squad setup`, `squad overview`, `squad demo --first-run`.
+
+#### Conversation and Cost
+
+- **Conversation opens on "What happened"**: one card per step with its time, a one-line summary and what it handed
+  in, drawn as the real thing. **Full log** keeps the detail, in plain words, with **Open it in Claude Code**.
+- **Cost follows how you pay.** On a subscription: "Included in your Claude plan. No extra charge.", the size of the
+  work and where it went, with the API-price figure shown as a value, not a bill. With an API key: real dollars, a
+  budget per ticket and per month, a warning at 80% and a pause at 100%.
+- **Averages per Quality setting** (cost and squad time per accepted ticket) on the Squad and AI page.
+- Terminal: `squad cost`, `squad config set payment`, `squad config set budget`.
+
+#### Tickets that depend on each other
+
+- **The Analyst and the Architect see the other open tickets** and the files they change.
+- **A design can depend on another ticket.** The ticket then waits before building: **Build on its branch**, **Build
+  anyway**, or **Wait** (it starts by itself when the other one merges). Terminal: `squad depends`, `squad build`.
+- **Bring in latest main** is a button on a ticket being built (`squad bring-in`).
+
+#### Releases
+
+- **Take a ticket out of the next release** before you release it (`squad release --without`).
+- **Released tickets' branches are cleaned up** on this computer, and on the remote when you ask (`squad branches`).
+  A branch with unmerged work is never deleted.
+- **A release cut off by a restart finishes or rolls back** cleanly on the next start.
+
+#### Also
+
+- **The ticket can go full width** (the button next to Close; remembered in this browser). **Hand over** and
+  **Propose a change** moved to the ⋯ menu, and Propose a change is also on the ticket's bottom bar, so the header is
+  one row at any width.
+- **The Waiting for you banner is one slim, calm row**, and stays readable beside a docked chat.
+- **The update banner shows what is new in every release since your version**, and **Check for updates** reads the
+  notes again.
+- **Free the port and try again** on a stuck Tester step, for programs squad-kit itself started.
+
+### What's safer
+
+- **Agents get fixed tools, "the window"**: `take_screenshots`, `look_at_page`, `start_app`, `stop_app`, `app_status`,
+  `run_checks` and `i_am_stuck`. An agent fills in the fields, squad-kit checks them, does the job itself and hands
+  back the result. There is no free command: only this story's app on this computer, only the project's saved
+  commands, only what squad-kit started. A request outside that is refused and written in the activity, and three
+  refusals in one step stop the agent.
+- **`i_am_stuck`**: when something technical is in an agent's way, squad-kit tries its own fixes (its browser, a free
+  port, starting the app again) and writes one plain line. It is never a question to you.
+- **Technical questions never reach you.** squad-kit reads each question an agent asks, with its choices and
+  everything shown with it, and does not trust the agent's label. A question about ports, commands, files or settings
+  goes back to the agent to decide. An agent that keeps asking stops in plain words. When another program holds a
+  port and going around it did not work, you get one plain card with no port in it: **Stop it** (with a confirm) or
+  **Skip the browser tests**.
+- **Some asks are refused and logged.** Asking you to change squad-kit's settings or protected files, to hand over a
+  password or a key, or to change git history never reaches you. One plain line goes in the activity. A reply in a
+  chat that asks for any of these is left out too.
+- **A second guard for the project's own commands.** The tests, lint, build, setup, the app's start and the release
+  pipeline run in squad-kit's own guard on Mac and Linux. They work normally, browser tests too, and can reach the
+  network, but they can't read your keys, sign-ins, browser profiles, squad-kit's own folder or the `.env` files in
+  your project folder. If a project truly needs a file outside its copy, one plain sentence says so, and an engineer
+  can allow it in Settings or with `squad config set allow-read <path>` and `squad config set allow-write <path>`.
+  `squad doctor` shows whether the guard runs here.
+- **Windows is less protected and not fully tested yet.** There, the agents' own commands and the project's own
+  commands have no guard, so they can reach other files on the computer. Use it on projects you trust. Settings and
+  the Squad and AI page say "Windows: less protected".
+- **"Not checked" instead of a green pass** when a project has no tests. You are asked once per project, with the
+  Architect's suggested test command. A project without tests also checks that the app starts.
+- **Weakened tests stop the ticket**: deleted tests, fewer tests, a changed test setup, or new skip/only markers, in
+  the common languages. **Continue anyway** needs a reason that stays on the record.
+- **Proof is verified**: each screenshot must be a real image taken in this step, and "after" must differ from
+  "before", unless the "done when" says the screen stays as it was.
+- **The Reviewer sees the whole change and the check results** in every round, not only the fix. In its review it can
+  also look at a page of the app itself (`look_at_page`).
+- **A change to the test command is tried first.** squad-kit runs the new command and the current one in the ticket's
+  copy, and keeps the new one only when it passes and runs at least as many tests. You choose only when it cannot
+  tell. Terminal: `squad test-command <ticket> --use | --keep`.
+- **The Builder's and Tester's commands run in Claude Code's sandbox** where the computer allows it: they write only
+  in the ticket's copy, its proof folder and a private package cache, can't read your keys, sign-ins or `.env`
+  files, and reach only package registries and the websites you allow (Settings, `squad config set hosts`). A
+  blocked command says what and why. `squad doctor` shows whether the sandbox runs here.
+- **Turn and spend caps per step** from the Quality setting. Reaching one keeps the work and offers **Give it more**
+  or **Stop**.
+- **Every command squad-kit suggests you copy quotes your text safely**, on the board and in the terminal.
+- **zod 4, the AI SDK 5 and diff 8** for the 0.x planner commands. This closes the last high alert. The planner's
+  file-read tool on the Claude Agent SDK path now works with ranged reads.
+
+### What's fixed
+
+- **Plain stop messages.** A stop says what happened in squad-kit's own plain words, with **Try again**. A tool's raw
+  error never reaches you: the exact words are in the ticket's Developer tab and the app log.
+- **A failed check runs once more** before anyone is sent to fix it, so a flaky test costs no Builder run. If it passes
+  then, the activity and the Developer tab say "failed once, passed when run again". Not after a Stop, a command
+  squad-kit had to end, or a file the guard blocked.
+- **The Builder is told about old failures**: the checks that already failed on the first run, before any story
+  touched the code. It fixes what its story broke and leaves other screens alone. The checks must still pass.
+- **A clash no longer stops a story too soon on Builds by itself.** While main keeps moving, squad-kit brings it in
+  again by itself, up to 3 times, with the checks, the review and the proof each time. If main has not moved, or after
+  the third time, you get the clash card. Other tracks show the card at the first clash, as before.
+- **Apps move to a free port by themselves** when another program holds the usual one: Your apps, the story's own copy
+  and Try it yourself. In Your apps this works when the start command or the app's code takes a port setting; if not,
+  one plain sentence says what is in the way. `--next-port` on `squad app start` and `squad app restart` is still
+  accepted, and now does nothing.
+- **squad-kit installs its own screenshot browser.** No `npx playwright`, and nothing to install by hand. The first
+  time, one line says "Setting up squad-kit's screenshot browser. This happens only once."
+- **The step timer counts only running time.** It stands still while a ticket waits for you, for another story or for
+  a free place, so "Taking longer than usual" no longer shows on a step that was only waiting.
+- **A restart is not a failure.** Restarting the board, Stop or the computer sleeping no longer counts as a failed
+  try or raises the model's effort. The Builder carries on with the same step in the same conversation, instead of
+  starting the work again, and the step's clock keeps its time ("resumed after a restart").
+- **Nothing is left behind.** When a step ends, on Stop, and when the board restarts or quits, squad-kit stops every
+  program it started for the ticket, including test servers that left their process group. It finds them by where
+  they run: inside squad-kit's own copy of the code, never your folders or Your apps.
+- **squad-kit clears its own leftovers before the checks** and says so in one activity line. If an agent asks about a
+  busy port that squad-kit caused, squad-kit answers it and you never see the question.
+- **Desktop notices: Turn on always answers.** It says when the browser is asking, explains how to allow notices
+  when the browser stays silent (for example in Arc), and sends one test notice.
+- **A ticket a teammate deleted** shows "Deleted by <owner>" with **Remove from my board**.
+- **A chat message sent during Claude's usage limit waits** and is answered when the squad carries on.
+- **On a phone**, the banners fold into one slim row while a ticket is open, and the website's docs pages fit.
+
 ## [1.1.1] — 2026-11-03
 
 A security update. Nothing changes in how squad-kit works.
@@ -886,7 +1071,8 @@ 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/v1.1.1...HEAD
+[Unreleased]: https://github.com/AzmSquad/squad-kit/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/AzmSquad/squad-kit/releases/tag/v1.2.0
 [1.1.1]: https://github.com/AzmSquad/squad-kit/releases/tag/v1.1.1
 [1.1.0]: https://github.com/AzmSquad/squad-kit/releases/tag/v1.1.0
 [1.0.1]: https://github.com/AzmSquad/squad-kit/releases/tag/v1.0.1

package/README.md

@@ -1,6 +1,10 @@
 <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">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://squad-kit.com/readme/header-dark.png">
+      <source media="(prefers-color-scheme: light)" srcset="https://squad-kit.com/readme/header-light.png">
+      <img src="https://squad-kit.com/readme/header-light.png" alt="squad-kit: Your AI Engineering Squad. One Unified Harness." width="800">
+    </picture>
   </a>
 </p>
 
@@ -11,8 +15,6 @@
   <a href="https://squad-kit.com"><img src="https://img.shields.io/badge/site-squad--kit.com-7cffa0?labelColor=0a0a0c" alt="Website"></a>
 </p>
 
-**Your AI Engineering Squad. One Unified Harness.**
-
 squad-kit is an agent harness for the whole software cycle. You describe what you need in plain words. A
 squad of AI agents takes it from that ask to a release: the Analyst, the Architect, the Builder, the Tester
 and the Reviewer. You stay in control. The squad asks you when it needs you, and nothing important moves on
@@ -34,8 +36,10 @@ without your approval.
 4. The Architect writes the **design**: the decision and the steps. You, or a developer, approve it.
 5. The Builder writes the code in its own copy of the project. Your own folder stays as it is.
 6. squad-kit runs the tests, lint and build itself. The Reviewer checks the work with fresh eyes. The Tester
-   takes a screenshot for each "done when".
-7. You check this **proof** and press **Looks right**.
+   shows each "done when" in one or more screenshots, one per part or case, taken with squad-kit's own browser.
+7. You check this **proof**: each "done when" says **Met**, **Not working yet**, **Not shown yet** or **Not on a
+   screen**. **Where to look** names the pages, and **Try it yourself** runs the ticket's own copy of the app, with
+   nothing merged. Then press **Looks right**.
 8. You press **Release**. squad-kit writes the changelog, sets the version and adds the git tag.
 
 When the squad needs you, a banner shows on every page with the button to press, the browser tab shows how many
@@ -50,6 +54,10 @@ terminal command, so developers can do the same from the terminal.
   AI tool the squad runs on. squad-kit uses your existing sign-in, so there is nothing new to buy. squad-kit
   also finds Codex, but cannot run it yet.
 
+There is nothing else to install. squad-kit installs its own browser for the screenshots the first time it needs
+one, so there is no `npx playwright` to run. **Windows** works, but it is less protected and not fully tested yet:
+use it on projects you trust.
+
 ## Install
 
 ```bash
@@ -84,14 +92,16 @@ Any folder works:
 
 | The folder | What squad-kit does |
 | --- | --- |
-| An empty folder | Makes a new git repo. The Architect picks the stack with you on your first ticket. |
+| An empty folder | Makes a new git repo and asks "What do you want to build?". The Architect picks the technology when your first ticket is planned, and squad-kit finds how to test and run it after the first build. |
 | Code with git | Keeps your repo and its history as they are. |
 | Code without git | Makes a repo, with your files in its first commit. Generated folders like `node_modules` and `dist`, and `.env` files, stay out. |
 | A folder with several code repos | Works across them. Each ticket works in one repo. |
 | A squad-kit 0.x project | Keeps your stories, plans and tracker settings. Moves your sign-ins to this computer. |
 
-Then the Architect reads the project, which takes a few minutes. It maps the code and finds how to install,
-test, build and run it. You can follow it on the board.
+Then a setup page shows each step live while the Architect reads the project, finds how to test and run it, and
+squad-kit tries the tests and opens the app once. It takes a few minutes, and you can leave the page. Then the
+**Overview** opens: what the project is, who uses it, how its parts fit, the rules found, and ideas for a first
+ticket. Approve it with **Looks right, start working**, and the squad follows those rules.
 
 ## Your first ticket
 
@@ -112,10 +122,26 @@ The step-by-step guide is in [Getting started](docs/getting-started.md).
 - **A slow step says so**, with what it is doing and three ways out: **Give it 10 more minutes**, **Stop and try
   again**, or **Stop**. A step that makes no progress says what squad-kit checked.
 - **Run your app** from **Your apps** in the sidebar: Start, Open, Restart and Stop, from squad-kit's own copy of
-  `main`. After **Looks right**, **Run the new version** shows the change. Terminal: `squad app start`.
+  `main`. If another program holds its port, it moves to a free one by itself. After **Looks right**, **Run the new
+  version** shows the change. Terminal: `squad app start`.
+- **Tickets that need each other**: when a design depends on a ticket that is not merged yet, it waits with
+  **Build on its branch**, **Build anyway** or **Wait**.
 - **Remove a ticket** you no longer want with **Delete**, and take finished ones off the board with **Archive**.
   The dialog lists what goes and what stays; the cost stays in Usage. Terminal: `squad delete`, `squad archive`.
 
+## Checks you can trust
+
+- **Not checked, never a fake pass**: a project with no tests shows "Not checked" in orange.
+- **Weakened tests stop the ticket**: deleted or skipped tests, fewer tests, or a changed test setup.
+- **Proof is checked**: each screenshot must be a real, new picture, and squad-kit's own check looks at all the
+  pictures of each "done when" together before it says **Met**.
+- **The Builder works in a sandbox** where the computer allows it: its copy only, no keys or `.env` files, and only
+  the package registries and websites you allow.
+- **The project's own commands run in a guard** on Mac and Linux: the tests, the setup and the app work normally, but
+  can't read your keys, your sign-ins or squad-kit's own files.
+- **Agents get fixed tools, no free commands**, for screenshots, the app and the checks. squad-kit checks each
+  request and does the job itself.
+
 ## When something goes wrong
 
 - **Every stop says what happened, what is safe, and the ways out**, as buttons: Try again, Fix it yourself,
@@ -165,19 +191,29 @@ Hand over and clones work for a project whose `.squad/` sits in its one code rep
 
 ## Talk to the squad
 
-Open a chat with any agent on a ticket. **Asking never stops the work**: the squad keeps working while you
-talk. To change what gets built, press **Propose a change**. The Analyst writes the change into the spec, old
+**Ask a question** is at the top of every ticket, in every state: working, in the queue, waiting for another ticket,
+stopped, at review, taken over or released. Whoever knows the ticket best answers: the Analyst before the build, the
+Builder during and after it, the Tester once there are screenshots. It answers questions only, like "how do I test
+this?" or "where is the new page?", and the ticket stays exactly where it is. Terminal: `squad chat <ticket> --ask`.
+
+You can also open a chat with any agent on a ticket. **Asking never stops the work**: the squad keeps working while
+you talk. To change what gets built, press **Propose a change**. The Analyst writes the change into the spec, old
 and new side by side, and you approve it. A released ticket answers questions only. A change to it becomes a new
 linked ticket or a bug report.
 
+**The squad asks you only about the business.** Technical questions stay with the agent and squad-kit. Nobody may ask
+you for a password or a key, to change squad-kit's settings, or to change git history: squad-kit refuses it and
+writes one line in the ticket's activity.
+
 ## Cost and models
 
 - squad-kit picks a **model level** for each role and step from the project's **Quality** setting: **Best**
   (the default) builds and reviews on the strongest model, **Balanced** builds on it at medium effort, and
   **Thrifty** builds on a lighter one. **Fast** stays for screenshots and small helpers. The team or each person
   can change single steps on the **Squad and AI** page.
-- The board shows **what each ticket and each role used**, in tokens and in money at the AI company's API
-  prices. Your own AI subscription pays for it. This shows where the cost goes.
+- The board shows **what each ticket and each role used**, the way you pay. On a Claude subscription it says the
+  work is included in your plan, and shows its size and its value at API prices (a value, not a bill). With an API
+  key it shows real dollars, against a budget per ticket and per month.
 - One **limit of tickets at once** (2 by default, up to 5) is shared by all your projects, because they use the
   same AI account.
 
@@ -186,6 +222,8 @@ linked ticket or a bug report.
 - [Getting started](docs/getting-started.md): your first hour, from install to a release.
 - [Moving to 1.0](docs/migrating-to-1.0.md): from squad-kit 0.x, and from early 1.0 boards.
 - [The app](docs/console.md): Home, the board, the ticket drawer, Squad and AI, and Settings.
+- [From a BRD to a built product](docs/requirements.md): upload a requirements document, approve the breakdown,
+  send it to Azure DevOps and let the squad build it.
 - [CHANGELOG](CHANGELOG.md): what changed in each version.
 
 The 0.x planner commands (`squad new-story`, `squad new-plan`, `squad auth` and others) still ship. Their docs

package/SECURITY.md

@@ -7,8 +7,8 @@ or `squad upgrade`.
 
 | Version | Supported |
 | ------- | --------- |
-| 1.1.x   | ✅        |
-| < 1.1   | ❌        |
+| 1.2.x   | ✅        |
+| < 1.2   | ❌        |
 
 ## Reporting a vulnerability
 
@@ -44,6 +44,13 @@ Credit will be given in the release notes unless you prefer to remain anonymous.
   own copy of the code, the Tester cannot change code, and no agent may change the instruction files the next session
   would follow, squad-kit's own `.squad/` folder, or git history. squad-kit checks after each step and puts back what
   an agent changed outside its lane. Text from trackers and pasted messages reaches agents as data, never as orders.
+- **Agents get fixed tools, no free commands.** For screenshots, the app and the checks, an agent presses one of
+  squad-kit's tools. squad-kit checks every field, does the job itself, and refuses and logs what breaks a check.
+- **The project's own commands run in a guard** on Mac and Linux: the tests, setup, the app and the release pipeline
+  can't read your keys, sign-ins, browser profiles, squad-kit's own folder or the `.env` files in your project folder.
+- **Windows is less protected and not fully tested yet.** There, the agents' own commands and the project's own
+  commands have no guard, so they can reach other files on the computer, squad-kit's own too. Use it on projects you
+  trust. Settings says so.
 - **The engine owns git and the release.** Agents never merge, push or grade their own work.
 - **The npm package is built and published by GitHub Actions** from a release tag, with npm trusted publishing (no
   npm token exists) and a signed provenance statement you can check on npmjs.com.