# alterspec client

`@alterset/alterspec-client` brings the work of an [alterspec](https://github.com/altersetigor/alterspec) product
spec into the repositories that build the product. With it, a developer working in Claude Code takes a task from the
alterspec dispatcher, reads only the part of the spec that task needs, builds it, and reports progress and completion
back. The client never edits the spec.

It also carries the format of the export's `work.json` (`@alterset/alterspec-client/work`) for the dispatcher.

New to the dispatcher? Start with the step-by-step [developer guide](developer-guide.md) (`developer-guide.md` in
this package): the SSH key, setting a repository up, signing in, and a task from start to finish. This README is the
reference.

## What you need

- Node.js 20 or later, git, and [Claude Code](https://code.claude.com).
- The dispatcher's URL from your admin.
- A clone of the **export** repository: the signed-off product spec your team builds from. The client pulls it.
  Never edit it by hand.
- An `ssh-ed25519` key: in ssh-agent, or at `~/.ssh/id_ed25519`. Signing in to the dispatcher uses it. There is no
  password or token to manage.

## Words

- **Task**: one signed-off change on one track, written `CHG-012/BE`.
- **Track**: a stream of build work. It is not a channel. `BE` is the backend (every API channel included). Every
  other track is one design, named by the code of the channel that owns it (`BO`, `MOB`). A channel that shares
  another's design is built in that channel's track.
- **Checklist**: a task's items, such as acceptance criteria (`CAP-CAT-001-AC-03`), screen actions (`SCR-PRC-01.A02`),
  experience states (`UX-SCR-PRC-01-WEB#error`) and, of an object changed as a whole, the parts of its text that
  changed (`ENT-USER#lifecycle`, `NFR-019#sign-in-succeeded`, `RULE-056#front-matter`). Progress counts the items
  your commits cover.
- **Then and Shown**: a criterion's `Then` is what the system guarantees (the backend's), its `Shown` what the screen
  shows (a UI track's). A task's checklist holds a criterion for its own part only; one without `Shown` is all the
  backend's.
- **Feedback**: when a task's checklist is covered, the agent tells the dispatcher what in the spec was unclear, what
  it had to open beyond the brief and what it decided itself, naming IDs, so the product side can fix the spec.
- **Question**: when the spec doesn't decide something, the agent asks with `/alterspec-spec-ask`. The answer is
  from the spec (citing IDs the export holds), an assumption to work on until the product side confirms or corrects
  it, or open (that item waits). The dispatcher keeps the assumptions and the open ones (an answer from the spec is
  not sent); a product person answers there and marks each reconciled with the spec once the spec says it.
- **Bug**: the product does something other than what the spec says. Anyone raises one with `/alterspec-bug`,
  which grooms the report against the export first; the dispatcher keeps it (`BUG-3`), never the spec, with the
  items it violates as cites, and makes a task per track those items are on (`BUG-3/BE`), after the tasks that
  built them. A bug task is taken and worked like any other; its checklist is the cites.

## Set up a repository

In the root of the repository that builds one or more tracks:

```bash
npx @alterset/alterspec-client init --dispatcher https://<dispatcher> --export ../<export-clone> --track BE
```

| Option               | Meaning                                                                     |
| -------------------- | --------------------------------------------------------------------------- |
| `--dispatcher <url>` | The dispatcher's URL.                                                       |
| `--export <path>`    | Your clone of the export repository, relative to this repository or absolute. |
| `--track <code...>`  | The tracks this repository builds (`BE`, `BO`, …). Several are allowed: `--track BE BO`. |
| `--key <key>`        | The public key to sign with, as a `.pub` path or the key line. Default: the first `ssh-ed25519` key in ssh-agent, then `~/.ssh/id_ed25519.pub`. |
| `--branch <name>`    | The track's main branch. Default: the remote's `HEAD`, else `main`.         |
| `--force`            | Replace skills you modified.                                                |

`init` writes:

- `.alterspec-client.json`: the configuration above.
- `.mcp.json`: the `dispatcher` MCP server (`npx @alterset/alterspec-client mcp`).
- `.claude/settings.json`: a hook that reports progress after each `git commit`.
- `.claude/settings.local.json`: your approval of the `dispatcher` server (`"enabledMcpjsonServers": ["dispatcher"]`),
  merged with whatever else the file holds. Claude Code loads a server from a project's `.mcp.json` only once it is
  approved, and honours this approval only while git doesn't track the file, so `init` adds the file to `.gitignore`
  when git doesn't ignore it yet.
- `.claude/skills/alterspec-*`: the skills, which are thin wrappers.
- `.alterspec-client/prompts/`: the full instructions behind the skills.

It is safe to run again. Running it again also updates the client: it adds the skills of the new version, removes
the ones it dropped, and keeps any skill you edited unless you pass `--force`. Commit everything it writes except
`.claude/settings.local.json`, so a worktree you make has it too. The client never makes a branch, a worktree or a
commit in your repository; in a worktree of yours, the first `export-head` or `context` run writes the approval
into that worktree's `.claude/settings.local.json` (where `.mcp.json` is present and `.claude` is not a link that
points nowhere), and nothing else. If you keep the setup out of git, as top-level symlinks into another repository
(`.claude`, `.mcp.json`, `.alterspec-client`), link them into each worktree yourself.

When `.claude` is a symlink to another repository, git can't tell whether the file is ignored there: `init` says so,
and you add `.claude/settings.local.json` to that repository's `.gitignore`.

At the end it prints your public key and fingerprint. **Send both to the dispatcher's admin.** Nothing works until
the admin adds your key. To print them again:

```bash
npx @alterset/alterspec-client key
```

The dispatcher's tools appear in the next Claude Code session started in the repository.

`init` doesn't touch your `CLAUDE.md`. So that Claude knows where the export is and how to treat it outside the
skills too, copy the block in [`agent-instructions.md`](agent-instructions.md) (in this package) into your agent's
instructions, wherever you keep them.

## Working day

You talk to Claude Code; the skills call the dispatcher and the CLI for you.

1. **Take work.** `/alterspec-task-next`, or just "give me the next task". Name a track or ask for several at once:
   `/alterspec-task-next BE 2`. It only assigns: with one task it continues with the brief, with several it lists
   them; type `/alterspec-task-context <task>` wherever you work on each. It creates no branch or worktree; where
   and how you work is yours.
2. **Build from the brief.** `/alterspec-task-context [task]` reads the task's brief from the export:
   - the checklist, with the items the dispatcher already holds covered and what changed in each;
   - why the change was made;
   - the before and after of each object, and what moved since the sign-off: the later changes that touched it and
     whether the export's current text is still this delta's after (when not, build to the current file);
   - for `BE`: the changed acceptance criteria on the checklist and the operations, whole; the rules, events,
     quality requirements and integrations the checklist's criteria or the change's text name, whole; the others
     the capabilities name, as paths;
   - for `BE`: the entities the capabilities work with, as paths, each with its lifecycle in one line;
   - the reach of the rules it carries whole and the roles it touches: which capabilities enforce or hold them,
     which criteria cover them, which screens they are on;
   - the decisions and glossary terms the change's text names, whole; the other decisions its objects name, as
     paths;
   - for a UI track: the screens, their experience contracts, the mockup pages and the design system.

   You build it in your own technology. When the spec is silent or disagrees with the code, Claude asks you; it does
   not invent business rules. A mockup page shows the agreed look and behaviour. It is not code to copy.
3. **Commit with trailers.** Every commit of the task ends with:

   ```
   Alterspec-Task: CHG-012/BE
   Alterspec-Covers: CAP-CAT-001-AC-03, CAP-CAT-002
   ```

   `Alterspec-Task` goes on every commit. `Alterspec-Covers` goes only on the commit that makes an item's tests pass,
   naming items exactly as the checklist writes them. Name each item once; a commit that covers nothing has no
   `Alterspec-Covers` line. After each commit the hook reports the covered items to the dispatcher. It works in the
   background and never blocks you. It skips the report when nothing changed or the last report is under 15 minutes
   old.
4. **Push, then report done.** Once the task's branch is pushed, type `/alterspec-task-done CHG-012/BE`. It sends
   the last progress and reports the task done with the branch's head commit and the branch (or, once merged, with
   the commit on the main branch that brought it in). It refuses while nothing is pushed. The tasks waiting for yours
   start from your branch; the dispatcher learns of the merge from the repository's pushes. When the brief says
   "Start from `task/…`", fetch that branch and base yours on `origin/<branch>`, not on main.

Other skills:

| Skill                                     | What it does                                                                 |
| ----------------------------------------- | ---------------------------------------------------------------------------- |
| `/alterspec-task-status [track]`          | Your tasks with progress and ETA, what is available, what is blocked and by what, and the open changes per level. |
| `/alterspec-task-eta <task> <YYYY-MM-DD\|clear> <reason>` | Set your own date for a task, or `clear` it so the dispatcher's computed ETA applies again. |
| `/alterspec-task-release <task> [reason]` | Give a task back. Your code and branches stay as they are.                   |
| `/alterspec-spec-ask <question>`          | Answer a question about the product from the export, citing IDs. Read-only. |
| `/alterspec-bug <what is wrong>`          | Groom a report against the export and, when the product deviates from what the spec says, raise a bug with the dispatcher citing the items it violates. A silent or ambiguous spec becomes a question instead; a wrong spec is a change in the spec project. `dismiss BUG-3 <reason>`, typed, dismisses one you raised. |

You only ever type `task-done`, `task-eta` and `task-release` yourself, because each is your word. Claude starts
the others from plain language as well.

## Commands

The skills run these; you rarely need them yourself. Run them in the repository or in a worktree of it; there the
configuration is read from the main checkout. None of them writes to your repository's git: no branch, worktree,
switch or commit (`merged` fetches `origin/<main>` and the task branch, to read them).

| Command                                   | What it does                                                                  |
| ----------------------------------------- | ----------------------------------------------------------------------------- |
| `init [options]`                          | Set the repository up (see above).                                            |
| `key`                                     | Print the public key and fingerprint you sign with.                           |
| `open dispatcher`                         | Sign in and open the dispatcher's pages in the browser. The link works once, for a minute. |
| `context <task> [--json] [--stats]`       | Print the task's brief from the export, starting with its questions and its checklist; for a bug's task (`BUG-3/BE`), the bug's words, its cites as the checklist and the objects as they are now. |
| `progress [task] [--json]`                | Report the items your commits cover. Default: the task of the branch `task/<chg>-<track>`, else of the last commit's `Alterspec-Task` trailer. |
| `lookup [ref...] [--question <text>] [--task <task>] [--item <item>]` | Where in the export a question is answered: what to read first, what to open before calling the export silent, the neighbours. `--unread <path...>` says what of that was not opened. |
| `cites <ref...>`                          | Check that every ID or path is in the export; what an answer "from the spec" must pass. |
| `questions [task] [--about <ID...>] [--open] [--json]` | Print a task's questions with the product side's answers, the ones naming some IDs, or without either your own. |
| `bugs [--about <ID...>] [--status open\|done\|dismissed] [--track <code>] [--json]` | Print the bugs naming some IDs (to find one raised before), or without `--about` your own, each with its tasks' statuses and branches. |
| `merged <task> [--json]`                  | Print the commit and branch to report `done` with: the pushed task branch's head, or the commit on `origin/<main>` that brought the task in. |
| `export-head [--latest <sha>]`            | Pull the export clone and print the commit to send to the dispatcher.         |
| `mcp`                                     | The MCP server Claude Code starts from `.mcp.json`. It forwards to the dispatcher. |

Each runs as `npx @alterset/alterspec-client <command>`.

## Troubleshooting

- **"The dispatcher refused your SSH key"**: the admin hasn't added your key yet, or you are signing with a
  different key. Send the two lines it prints (or the output of `key`) to the admin.
- **"No SSH key to sign with"**: add an `ssh-ed25519` key to ssh-agent, create `~/.ssh/id_ed25519`, or set `key` in
  `.alterspec-client.json`.
- **"ssh-agent doesn't hold the key"**: run `ssh-add` for the configured key.
- **No dispatcher tools in Claude Code**: the `dispatcher` server isn't approved or loaded. Run `init` again (it
  approves it in `.claude/settings.local.json`), make sure git doesn't track that file (`git rm --cached` it if
  `init` says it is committed), then start a new session. In an interactive `claude` terminal, `/mcp` shows the
  server's state and approves it too.
- **"No .alterspec-client.json here"**: run `init` in this repository, or commit the configuration so worktrees
  find it.
- **"The export is N commits behind"**: the clone couldn't catch up. The task's change is already in it, so work
  goes on. Check the clone's remote if it keeps happening.
- **An item reported as unknown**: an `Alterspec-Covers` line named something the checklist lacks. A pushed commit
  can't be corrected; name the right item on a later commit.
- **`task-done` says the work isn't pushed**: push the task's branch `task/<chg>-<track>`, then run it again.

## For the dispatcher: the `work.json` format

```ts
import { parseWork, WorkSchema, AnyWorkSchema, WorkError } from '@alterset/alterspec-client/work';
```

`parseWork(text)` reads a `work.json` in format 1 or 2 and throws `WorkError` when it isn't one. The JSON Schema is
at `@alterset/alterspec-client/work.schema.json`.

## License

MIT, Alterset d.o.o.
