# 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.

## 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`)
  and experience states (`UX-SCR-PRC-01-WEB#error`). Progress counts the items your commits cover.

## 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`. |
| `--worktrees <path>` | Where task worktrees go. Default: `../<repo>-tasks`.                        |
| `--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 task worktrees have it too. `worktree` writes the approval into each new task
worktree itself.

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.

## 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`. With one task, the client makes its branch `task/<chg>-<track>` in this checkout and
   continues with the brief. With several, it makes a worktree for each. Start a Claude Code session in each folder
   and type `/alterspec-task-context <task>` there.
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;
   - why the change was made;
   - the before and after of each object;
   - for `BE`: the acceptance criteria, rules, events and operations;
   - 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. **Merge, then report done.** Once the task's work is on the track's main branch on the remote, type
   `/alterspec-task-done CHG-012/BE`. It sends the last progress, finds the commit that brought the task in, and
   reports it done. It refuses while the work is not merged.

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. Its branch and worktree stay.                              |
| `/alterspec-spec-ask <question>`          | Answer a question about the product from the export, citing IDs. Read-only. |

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 task worktree. In a task
worktree, the configuration is read from the main checkout.

| 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]`                 | Print the task's brief from the export, starting with its checklist.          |
| `worktree <task> [--here]`                | Create the branch `task/<chg>-<track>` from `origin/<main>` in its own worktree. `--here` uses this checkout instead. |
| `progress [task] [--json]`                | Report the items your commits cover. Default: the task of the current branch. |
| `merged <task>`                           | Print 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 merged**: merge the task's branch into the main branch, or push the commits that
  carry its `Alterspec-Task` trailer, 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.
