tspl-cli 0.1.1 → 0.1.3

package/README.md

@@ -1,128 +1,488 @@
 # tspl
 
-`tspl` is the command-line tool for the TSPL AI feature-development tool. It reads your repositories (no AI, nothing leaves your machine), turns a task into a clear brief, plans the change with you, enforces the approved plan while an AI tool builds it, runs the tests and opens the pull request.
+`tspl` is the command-line tool for the TSPL AI feature-development tool. It takes a task, finds the code it touches, plans the change with you, has people approve the plan, then lets an AI tool build it, runs the tests, gets a separate AI review and opens the pull request.
+
+- **Your code stays on your machine.** tspl reads your repositories locally, with no AI and no tokens. The server keeps only tasks, plans, approvals, reports and AI usage, never code.
+- **People stay in control.** Nothing is built until the developer, and then the PM, approve the plan. While a build runs, git hooks refuse commits and pushes that touch files outside the approved plan.
+- **Done means tested.** A task is ready only when every required check passed on the exact commits of the pull request, and the server decides that, not the AI.
 
 ```text
 npm i -g tspl-cli → tspl setup → tspl init → tspl task new "…" → tspl t-xxxx → tspl plan approve t-xxxx → tspl task run t-xxxx
 ```
 
+## Contents
+
+1. [Requirements](#requirements)
+2. [Install](#1-install)
+3. [Configure your computer](#2-configure-your-computer)
+4. [Accounts and organizations](#3-accounts-and-organizations)
+5. [Set up a project](#4-set-up-a-project)
+6. [Work on a task, step by step](#5-work-on-a-task-step-by-step)
+7. [Use tspl from your AI tool](#6-use-tspl-from-your-ai-tool)
+8. [Team, roles and projects](#7-team-roles-and-projects)
+9. [AI engines](#8-ai-engines)
+10. [Command reference](#9-command-reference)
+11. [Files and settings](#10-files-and-settings)
+12. [Troubleshooting](#11-troubleshooting)
+13. [Update and uninstall](#12-update-and-uninstall)
+
 ## Requirements
 
-- Node 22 or newer
-- git
-- A TSPL account and the address of your TSPL API (ask your team)
-- An AI tool such as Claude Code, Codex, Cursor or Gemini, using your own subscription
+- **Node 22 or newer** (`node --version`)
+- **git**
+- **A TSPL account.** Ask your organization's owner or admin to add you. You get a temporary password and choose your own at the first login.
+- **An AI tool** you are signed in to with your own subscription: Claude Code, Codex CLI, Gemini CLI, Antigravity, Cursor or VS Code Copilot
+- **GitHub CLI** (`gh`), for automatic draft pull requests on GitHub. Optional.
+
+The TSPL API address is:
 
-## 1. Install (once per computer)
+```text
+https://aitool-api.techivies.com
+```
+
+## 1. Install
+
+Do this once per computer.
 
 ```bash
 npm install -g tspl-cli
 tspl --version
 ```
 
-Update later with `npm install -g tspl-cli@latest`.
+This installs the `tspl` command for your whole computer.
+
+## 2. Configure your computer
+
+Do this once per computer. You can rerun it at any time, and nothing is lost.
+
+```bash
+tspl setup --api https://aitool-api.techivies.com --connect claude
+```
+
+`tspl setup` goes through these steps and ends with a list of what is ready and what still needs you:
+
+1. **Checks Node and git.**
+2. **Logs you in** to the TSPL API with your email and password. The API address is remembered, so you never type it again.
+3. **Chooses your AI engines,** the AI tool tspl uses for each step (see [AI engines](#8-ai-engines)). It finds Claude, Codex, Gemini and Ollama if they are installed.
+4. **Tests the engines** (optional). It sends one tiny prompt to check that each engine is signed in.
+5. **Connects your AI tool,** so you can type `/tspl` inside it. Use `--connect` with one or more of: `claude`, `codex`, `gemini`, `antigravity`, `cursor`, `vscode`.
+
+`tspl setup` options:
+
+| Option | What it does |
+| --- | --- |
+| `--api <url>` | TSPL API address |
+| `--email <email>` | your email, so you are not asked |
+| `--org <slug>` | the organization, if you belong to several |
+| `--connect <tools...>` | the AI tools to connect |
+| `-y, --yes` | keep existing choices and ask nothing |
+
+**Restart your AI tool after setup** so it loads tspl.
 
-## 2. Configure (once per computer)
+**For GitHub pull requests,** sign the GitHub CLI in once:
 
 ```bash
-tspl setup --api https://<your-tspl-api> --connect claude
-tspl whoami
+gh auth login
+gh auth status
 ```
 
-`tspl setup` walks you through:
+**Check that everything works:**
 
-- logging in to the TSPL API with your email and password
-- choosing which AI engine does each step
-- connecting your AI tool: the `/tspl` command, the edit lock and the MCP plug-in
+```bash
+tspl whoami          # you, your organization, your role and the API address
+tspl engines test    # each AI engine answers
+```
 
-Connect other tools with `--connect codex cursor gemini antigravity vscode`, or later with `tspl connect <tool>`. Restart your AI tool after connecting it.
+## 3. Accounts and organizations
 
-Several organizations:
+```bash
+tspl login                                   # log in (uses the saved API address)
+tspl login --api https://aitool-api.techivies.com --email you@company.com
+tspl login --org <slug>                      # log in to a specific organization
+tspl whoami                                  # who is logged in, which organization and API
+tspl password                                # change your password
+tspl forgot-password --email you@company.com # get a temporary password (no email is sent)
+tspl logout                                  # log out the account in use
+tspl logout --all                            # log out every account on this computer
+```
+
+One person can belong to several organizations, or have several accounts:
 
 ```bash
-tspl login --org <slug>   # log in to a specific organization
-tspl org use <slug>       # switch to one you are already logged in to
+tspl org list              # organizations you are logged in to; * is the one in use
+tspl org use <slug>        # switch organization
+tspl account               # menu: switch, add another login, or log out
+tspl account list          # saved logins
+tspl account use <email-or-organization>
 ```
 
-## 3. Set up a project (once per project folder)
+## 4. Set up a project
 
-Run inside the project folder:
+Do this once per project folder. Run it inside the folder of your project: one repository, or a folder that contains several repositories.
 
 ```bash
 cd path/to/your/project
+git status --short     # commit or stash your work first
 tspl init
 ```
 
-This links the folder to a TSPL project, finds its test and lint checks, and saves `.tspl/project.json`. Commit that file so the whole team shares the same rules. tspl then reads the code into a local map (no AI, nothing uploaded).
+`tspl init` does the following:
+
+1. **Links the folder to a TSPL project.** It recognizes your repositories by their git history, so folder names and git hosts don't matter. If the project doesn't exist yet, it offers to create it (owner, admin or PM only). If it finds new repositories, it offers to add them.
+2. **Finds your checks.** It reads your package scripts, without running them, and asks you to confirm which ones are the real **test**, **lint**, **typecheck** and **build** commands, and which are required.
+3. **Asks about pull requests:** the GitHub repository, the target branch and the CI policy.
+4. **Offers browser tests.** For web apps without browser tests, it offers to set up Playwright. Skip this with `--no-e2e`.
+5. **Saves the shared project files** in `.tspl/`.
+6. **Tells you** whether a tested pull request is possible for this project.
+
+Then commit the shared files, so everyone on the team uses the same rules:
+
+```bash
+git add .tspl
+git commit -m "Configure TSPL workflow"
+```
+
+`tspl init` options:
+
+| Option | What it does |
+| --- | --- |
+| `[folder]` | the project folder, if not the current folder |
+| `--org <slug>` | the organization, if you are logged in to several |
+| `--project <slug>` | add this folder to an existing project |
+| `--name <name>` | the project name, if a new project is created |
+| `--manifest-home <repo>` | for a folder of several repos: the repo that holds `.tspl/` |
+| `--no-e2e` | don't set up browser tests |
+| `-y, --yes` | accept supported suggestions without asking |
+
+Running `tspl` with no arguments in a project folder sets the folder up if needed, or lists its open tasks with the next command for each.
+
+**Teammates** don't run `tspl init` again. They install tspl, run `tspl setup`, open the same folder and run `tspl`. The project and the `.tspl/` files are already there.
+
+## 5. Work on a task, step by step
+
+A task goes through these statuses:
+
+```text
+draft → plan-review → pm-review → approved → building → done
+               ↘ changes-requested (from either review) ↙
+```
+
+Replace `t-xxxx` below with your task id.
+
+### Step 1: Create the task (developer or PM)
+
+```bash
+tspl task new "Add a forgot password link to the login page"
+```
+
+Other ways to create one:
+
+```bash
+tspl task new --ticket TEST-1 "Add About page"     # with a ticket id
+tspl task new TEST-1 --file ticket.md              # ticket text from a file
+tspl task new "..." --yes                          # save without the review menu (scripts)
+```
+
+What happens:
+
+1. tspl guesses the **type** (feature, change or bug) and asks only for what is missing: what should change, who it's for, where it is, and for bugs, the steps and the expected result. The answer options come from your code.
+2. You write the **done-when checks**, the acceptance criteria. Each becomes a test case (`TC1`, `TC2`, …) that has to pass later.
+3. tspl **finds the code** the task touches across all repositories, using no AI, and shows the files and how sure it is.
+4. A menu lets you **save**, **edit a field**, **add words and search again**, or **ask the AI once** for better keywords and checks.
+5. It saves the task and prints its **id**, for example `t-mfx2a1-9c3e`.
+
+Manage tasks:
+
+```bash
+tspl task list               # tasks on this computer
+tspl task show t-xxxx        # brief: card, done-when checks, files found
+tspl task edit t-xxxx        # change the task and save it again
+tspl find "forgot password"  # just search the code, without making a task (no AI)
+```
+
+### Step 2: Confirm the scope (PM)
+
+If your project uses scope confirmation, a PM, admin or owner checks that the task is clear and in scope:
+
+```bash
+tspl task scope t-xxxx                                       # confirm
+tspl task scope t-xxxx --back --note "Missing the mobile view" # send it back
+```
+
+This can also be done in the web console.
+
+### Step 3: Plan (developer and AI)
+
+```bash
+tspl t-xxxx
+```
+
+You can also type `/tspl t-xxxx` in your AI tool. The plan is made in three parts:
+
+1. **The AI reads the brief and compares 2–3 approaches,** with one recommendation.
+2. **You choose an approach.** The AI never chooses for you. To pick one from a terminal:
+   ```bash
+   tspl task choose t-xxxx <option-id> --version <n>
+   ```
+3. **The AI writes the plan:** the files to edit, create and remove in each repo, and a test for every done-when check, with the command that runs it. tspl checks the plan against the code: the files exist, new files sit with files of the same kind, names follow the project's style, and every done-when check has a test.
+
+Look at the plan:
+
+```bash
+tspl plan show t-xxxx          # in the terminal
+tspl plan show t-xxxx --page   # as a page in your browser
+```
+
+### Step 4: Approve the plan (developer, then PM)
+
+```bash
+tspl plan approve t-xxxx                                  # approve
+tspl plan approve t-xxxx --note "Looks good"
+tspl plan reject t-xxxx --note "Also update the reset page" # send it back
+tspl plan list                                            # plans waiting for your decision
+```
+
+The approval rules:
+
+- **The developer approves first, then the PM.** The PM must be a different person from the developer who approved. An owner or admin may approve their own plan, and it is recorded as self-approved.
+- **Approvals are made by people,** in a terminal or the web console. `tspl plan approve` refuses to run inside an AI tool.
+- **An approval counts only for that plan version.** If the plan changes, it has to be approved again.
+- A project can turn off PM approval: `tspl project set-approval <project> off`.
+
+While a plan waits for approval, Claude Code is not allowed to edit files in the project's repositories.
+
+### Step 5: Build, test, review and open the pull request
+
+```bash
+tspl task run t-xxxx
+```
+
+Before writing any code, tspl asks:
+
+1. **Which branch each repository starts from.** Pick it from the list, or type to filter.
+2. **The name of the new branch,** for example `feature/forgot-password`.
+
+Skip the questions with:
+
+```bash
+tspl task run t-xxxx --base main --branch feature/forgot-password
+```
+
+Then it goes through these stages by itself:
+
+| Stage | What happens |
+| --- | --- |
+| `implementing` | The AI writes the code, touching only the files in the approved plan |
+| `testing` | tspl runs the project's required checks and the plan's tests |
+| `repairing` | If something fails, the AI fixes it. There are at most 2 repair rounds in total |
+| `reviewing` | A separate, fresh AI session reviews the changes |
+| `awaiting-delivery` | tspl asks you to confirm the push: repository, branch, target and title |
+| `creating-pr` | Pushes the branch and opens a draft pull request |
+| `awaiting-ci` | Waits for the required CI checks on GitHub |
+| `ready` | Everything passed on the same commits, and the server marks the task done |
+
+Options for `tspl task run`:
+
+| Option | What it does |
+| --- | --- |
+| `--base <branch>` | branch every repo starts from |
+| `--branch <name>` | name of the new branch |
+| `--confirm-delivery` | confirm the push and pull request in advance, without being asked |
+| `-w, --wait` | when it stops for an approval, a manual check or CI, wait and continue by itself |
+| `--stage <stage>` | retry one stage: `implementing`, `testing`, `reviewing`, `awaiting-delivery`, `creating-pr` or `awaiting-ci` |
+
+If it stops, run the same command again. It continues where it stopped and does not ask for the branch again.
+
+```bash
+tspl task run t-xxxx                    # resume
+tspl task watch t-xxxx                  # same as run --wait
+tspl task status t-xxxx                 # stage, checks, review, pull requests and the next command
+tspl task run t-xxxx --stage testing    # rerun the checks, then continue
+tspl task run t-xxxx --stage reviewing  # rerun the review, then continue
+```
+
+### Step 6: Check by hand what no test can prove
+
+Some done-when checks can't be proven by an automatic test. Check them yourself on the tested commits, then record it with proof:
+
+```bash
+tspl task verify t-xxxx --check 2 --note "Checked on Safari" --file screenshot.png
+```
+
+`--file` accepts png, jpg, webp, webm and mp4 files.
+
+### Step 7: Review and merge
+
+The pull request stays a **draft** until the required CI passes, and then it is marked ready. Review it and merge it on GitHub as usual. tspl never merges, deploys or changes branch protection.
 
-Running `tspl` with no arguments sets the folder up if needed, or shows its open tasks.
+For a git host other than GitHub, tspl gives you a compare link instead:
 
-## 4. Work on a task
+```bash
+tspl build push t-xxxx    # push the branch of every repo on the plan
+```
+
+### Stop, change or delete a task
 
 ```bash
-tspl task new "Add a Contact page at /contact"   # answer a few questions; prints the task id, e.g. t-xxxx
-tspl t-xxxx                                      # compare approaches, pick one, write the plan
-tspl plan show t-xxxx                            # files to edit, create and remove, and tests
-tspl plan approve t-xxxx                         # developer approves, then the PM approves
-tspl task run t-xxxx                             # code, run checks, repair, review, draft pull requests, CI
+tspl build stop t-xxxx                  # stop and lift the edit lock (branches are kept)
+tspl plan amend t-xxxx                  # cancel the stopped run so a new plan version can be made
+tspl task delete t-xxxx --reason "duplicate"
 ```
 
-Other ways to start a task:
+Use `stop` and `amend` only when the plan really has to change, not for every failure. A new plan version needs new approvals.
+
+### Build by hand instead of `task run`
 
 ```bash
-tspl task new --ticket TEST-1 "Add About page"   # with a ticket id
-tspl task new --file ticket.txt                  # ticket text from a file
+tspl build start t-xxxx --branch feature/x   # create the branch in every repo on the plan
+tspl build start t-xxxx --open               # same, then open a fresh AI session with only the build brief
+tspl build check t-xxxx                      # compare the commits with the approved plan (also for CI)
+tspl build status                            # builds in progress on this computer
 ```
 
-`tspl task run` asks which branch each repo starts from and the name of the new branch. Skip the questions with:
+`build start` first stops if any repository has uncommitted changes. Add `--from-current` to start from the branch each repo has checked out instead of the base branch.
+
+## 6. Use tspl from your AI tool
+
+After `tspl connect <tool>` and a restart of the tool, open it in your project folder and type:
+
+```text
+/tspl Add a forgot password link to the login page
+/tspl t-xxxx
+```
+
+The AI uses tspl's tools to read the brief, compare approaches, submit the plan and build. It cannot approve plans; you do that in a terminal or the web console, then tell the AI "approved".
 
 ```bash
-tspl task run t-xxxx --base main --branch feature/contact-page
+tspl connect claude            # Claude Code: /tspl, edit lock and AI usage tracking
+tspl connect codex             # Codex CLI
+tspl connect gemini            # Gemini CLI
+tspl connect antigravity       # Antigravity CLI
+tspl connect cursor            # Cursor
+tspl connect vscode            # VS Code Copilot agent
+tspl connect claude --remove   # take tspl out again
 ```
 
-Run `tspl task run t-xxxx` again to resume after a stop. To retry one stage, add `--stage testing` or `--stage reviewing`.
+The edit lock and the AI usage record work only in Claude Code. The git hooks that enforce the plan work with every tool.
 
-From your AI tool, type `/tspl <what should change>` to do the same steps there.
+## 7. Team, roles and projects
 
-## Everyday commands
+**Roles:**
 
-| What | Command |
+| Role | Can do |
 | --- | --- |
-| Where a task is and the next command | `tspl task status t-xxxx` |
-| Tasks on this computer | `tspl task list` |
-| Show a task brief | `tspl task show t-xxxx` |
-| Change a task | `tspl task edit t-xxxx` |
-| Plans waiting for a decision | `tspl plan list` |
-| Send a plan back | `tspl plan reject t-xxxx --note "..."` |
-| PM confirms scope / sends it back | `tspl task scope t-xxxx` / `tspl task scope t-xxxx --back --note "..."` |
-| Keep going through approvals and CI | `tspl task watch t-xxxx` |
-| Builds in progress | `tspl build status` |
-| Stop a build and lift its edit lock | `tspl build stop t-xxxx` |
-| Allow a new plan after a stop | `tspl plan amend t-xxxx` |
-| Delete a task | `tspl task delete t-xxxx --reason "..."` |
-| Who is logged in | `tspl whoami` |
-| AI engine per step | `tspl engines` |
-
-## Team and projects
-
-```bash
-tspl project list                                # projects you can see
-tspl member list                                 # people and their roles
-tspl member add <email>                          # owner or admin
-tspl member role <email> <role>
-tspl project add-member <project> <email>
+| `owner` | everything; add owners and admins; delete projects |
+| `admin` | see all projects, manage the team, delete projects |
+| `pm` | in their projects: confirm scope, give the PM approval, add project members |
+| `developer` | in their projects: create tasks, plan, approve as developer, build |
+| `viewer` | read only |
+
+**People** (owner or admin):
+
+```bash
+tspl member list
+tspl member add dev@company.com --name "Dev Name" --role developer   # gets a temporary password
+tspl member role dev@company.com pm
+tspl member remove dev@company.com
+```
+
+New accounts get a temporary password. Pass it on privately; the person chooses their own at the first login.
+
+**Projects:**
+
+```bash
+tspl project list                                   # projects you can see
+tspl project show <project>                         # repos and where they are on this computer
+tspl project add-member <project> <email>           # owner, admin or PM
 tspl project remove-member <project> <email>
+tspl project set-branch <project> <repo> <branch>   # which branch is read and built on
+tspl project set-approval <project> on|off          # whether plans need PM approval (default on)
+tspl project remove-repo <project> <repo>           # archived, not deleted
+tspl project rm <project>                           # delete for everyone (owner or admin)
+tspl unlink [project]                               # forget repo locations on this computer only
 ```
 
-## Where tspl keeps data
+## 8. AI engines
+
+tspl uses your own AI subscription. Choose which engine does each step:
+
+```bash
+tspl engines                                   # see the current choice
+tspl engines set plan claude                   # engine for planning help
+tspl engines set build claude --model opus     # engine for building, with a model
+tspl engines test                              # check every engine is signed in
+```
 
-- `~/.tspl`: your login, settings and the local code map of each repo. The map is built from git and never uploaded.
-- `.tspl/project.json` in your project: the project's checks and settings, meant to be committed.
-- The TSPL server stores tasks, plans, approvals, reports and AI usage, never your code.
+The steps are `plan`, `build`, `verify` and `bulk`. The engines are `claude`, `codex`, `gemini` and `ollama`.
 
-## Help
+## 9. Command reference
+
+| Command | What it does |
+| --- | --- |
+| `tspl` | set up this folder, or list its open tasks |
+| `tspl t-xxxx` | continue a task from wherever it is |
+| `tspl setup` | configure this computer |
+| `tspl init` | set up a project folder |
+| `tspl login` / `logout` / `whoami` | log in, log out, show who is logged in |
+| `tspl account` / `org` | switch accounts or organizations |
+| `tspl password` / `forgot-password` | change or reset your password |
+| `tspl connect <tool>` | add tspl to an AI tool |
+| `tspl engines` | choose and test AI engines |
+| `tspl find "<text>"` | find the code a task is about (no AI) |
+| `tspl analyze` | re-read the code of this project (no AI; usually automatic) |
+| `tspl task new` / `list` / `show` / `edit` / `delete` | manage tasks |
+| `tspl task scope` | PM confirms or sends back the scope |
+| `tspl task choose` | choose an approach before planning |
+| `tspl task run` / `watch` / `status` | build a task, follow it, see where it is |
+| `tspl task verify` | record a check you did by hand |
+| `tspl plan list` / `show` / `approve` / `reject` / `amend` | review and decide on plans |
+| `tspl build start` / `status` / `check` / `push` / `stop` | manual build commands |
+| `tspl member ...` | people and roles |
+| `tspl project ...` | projects, repos, branches and members |
+| `tspl unlink` | forget repo locations on this computer |
+
+Every command has its own help:
 
 ```bash
 tspl --help
-tspl <command> --help
+tspl task run --help
 ```
+
+## 10. Files and settings
+
+| Where | What | Shared? |
+| --- | --- | --- |
+| `~/.tspl/` | your login, settings, engine choice, where your repos are, and the local code map | No, this computer only |
+| `.tspl/project.json` | the project's repos, checks (test, lint, typecheck, build), repair limits and pull request settings | Yes, commit it |
+| `.tspl/instructions.md` | the project's rules for the AI; existing `CLAUDE.md` or `AGENTS.md` files are referenced, never rewritten | Yes, commit it |
+| TSPL server | tasks, plans, approvals, reports, evidence and AI usage, never code | Your organization |
+
+- To keep tspl's settings somewhere else, set `TSPL_HOME=/path`.
+- The code map is built from git on your computer and refreshed in the background, reading only changed files. It is never uploaded.
+- `.tspl/project.json` contains no tokens and no paths from your computer.
+
+## 11. Troubleshooting
+
+| Problem | Fix |
+| --- | --- |
+| `Cannot reach the TSPL API` | check your internet connection, then `tspl whoami`; the address should be `https://aitool-api.techivies.com` |
+| `You are logged in to …, not …` | run `tspl login --api https://aitool-api.techivies.com` |
+| Login expired | run `tspl login` |
+| Forgot your password | run `tspl forgot-password --email you@company.com` |
+| `tspl needs Node 22 or newer` | install Node 22+ from https://nodejs.org, then reinstall tspl |
+| `/tspl` doesn't show in your AI tool | run `tspl connect <tool>` and restart the tool |
+| `plan approve` refuses to run | run it in a normal terminal, not inside an AI tool |
+| Build won't start: uncommitted changes | commit or stash your work, then run again |
+| Commit or push refused by a tspl hook | the file isn't in the approved plan; change the plan with `tspl plan amend`, or stop with `tspl build stop` |
+| No pull request is opened | run `gh auth login`; for other git hosts use the compare link |
+| The task stopped | run `tspl task status t-xxxx`; it prints the exact next command |
+| An engine doesn't answer | run `tspl engines test`, then sign in to that AI tool |
+
+## 12. Update and uninstall
+
+```bash
+npm install -g tspl-cli@latest   # update
+npm uninstall -g tspl-cli        # uninstall
+```
+
+Uninstalling keeps `~/.tspl` (your login and settings). Delete that folder to remove everything.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tspl-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "TSPL command-line tool: learns your code, plans changes with you, builds, tests and opens pull requests",
   "keywords": [
     "tspl",