# Taking tasks from the alterspec dispatcher: developer guide

Your team's work is handed out by the **alterspec dispatcher**. It reads the signed-off product spec (the **export**
repository), splits every change into tasks and gives them to you through Claude Code. It records who works on what,
how far along each task is and when it is done. You don't track any of this by hand.

You connect to it with the **alterspec client** (`@alterset/alterspec-client`, public on npm). Setting up takes about
15 minutes, once per machine and repository. Follow the steps in order.

## How it works, in six lines

- A **change** is one signed-off piece of the spec, e.g. `CHG-023`.
- A **track** is a stream of build work, usually built in one repository. `BE` is the backend (APIs included); every
  other track is a UI design, named by its channel code (`WEB`, `MOB`, …).
- A **task** is one change on one track, written `CHG-023/BE`. A UI task opens only once the `BE` task of the same
  change is done.
- A task's **checklist** lists what it must deliver: acceptance criteria (`CAP-CAT-001-AC-03`), screen actions
  (`SCR-PRC-01.A02`), experience states (`UX-SCR-PRC-01-WEB#error`). Progress counts the items your commits cover;
  nobody types percentages. Each item may carry a **weight** (`w 20`), 0 to 100: how much specified behaviour it
  is, reasoned when the change was signed off from the spec alone, never from your code (a wording change is a
  few, an acceptance criterion about 10, a new capability 40 to 60). The dispatcher's progress and ETA count
  weight, not items, so a task of twelve small parts is not twelve days; an item without a weight counts 10.
  The weight is your track's: an item marked `w 0, nothing to build on this track` is behaviour another track
  builds (a criterion only the other channel shows, a mockup file). You read it, build nothing for it and never
  name it in `Alterspec-Covers`; it counts in no progress, and a task whose items all weigh 0 is never handed out.
  The task itself may carry one **task weight**, 1 to 100 (`Task weight 35 of 100` at the top of the brief): the
  size of what your track builds in the change, on the same scale for every task (a wording fix a few, a new
  capability 30 to 50, an application's foundation 80 to 100). It is what the lists show next to the task; it is
  never the sum of the item weights, and progress keeps counting the items.
  Nobody types a weight either: the product side's sign-off gives it, and a developer never changes it.
- A task may carry a **title** and a **summary**, and each item a **label**: what a person calls them, written by
  the product side at the sign-off (or taken from the spec's own titles). The brief opens with the title and the
  summary and shows each item's label in bold before what the item is; the dispatcher's lists show the same words
  with the ID beside them. They are for reading. Build from the brief's spec text, never from a label.
- An acceptance criterion may have two outcomes: **Then**, what the system guarantees, and **Shown**, what the
  person sees on the screen. The backend builds and tests the Then, a UI track the Shown, and each task's checklist
  holds the criterion only for its own part; the brief shows you yours and says when the other part is another
  task's. A criterion without Shown is all the backend's.
- When the checklist is covered, Claude sends the dispatcher short **feedback** on the task: what in the spec was
  unclear and was not asked, what it had to read beyond the brief, and the `Q-<n>` of each assumption it built on.
  It never says a question again: the product side reads the task's questions beside it. Two objects of the spec
  that disagree are asked the moment Claude sees them, not kept for the feedback. It is never a grade of your work.
- When the spec doesn't decide something, Claude **asks** instead of stopping you or deciding itself. An answerer
  that reads only the spec replies: *from the spec*, with the IDs it rests on; *assumed*, when the spec is silent and
  one reading is the cautious one (work goes on, and the product side confirms or corrects it later); or *open*,
  when nobody may assume it (that checklist item waits, the others go on). An answer from the spec stays with you;
  the dispatcher keeps the assumptions and the open questions, a product person answers them, and the answer is in the task's brief the next time Claude reads it.
- When you take a task it is yours until you report it **done** or **release** it; nobody else can.
- A task is **done** when its work is pushed and you report it: the commit and the branch it is on. The merge into
  the track's main branch comes after; the dispatcher learns of it from the repository's pushes, and the tasks
  waiting for yours start from your branch in the meantime.

## Before you start

You need:

- macOS or Linux, `git`, **Node 20 or later** (`node -v`) and **Claude Code**.
- From your admin (the person who runs the dispatcher):
  - the **dispatcher URL**, e.g. `https://dispatcher.example.com`;
  - the **export repository** to clone;
  - your **track(s)** and the code repository each is built in;
  - the track's **main branch** (`main`, `master`, …) if it isn't the remote's default.
- Read access to the export repository and access to your code repository.

In the steps below, replace `<dispatcher-url>`, `<export-repo>`, `<code-repo>`, `<TRACK>` and `<branch>` with these
values.

## Step 1: An Ed25519 SSH key

The dispatcher has no passwords: you sign in with an SSH key that your admin adds for you. It must be **Ed25519**;
RSA keys (`id_rsa`) are not accepted. Check whether you have one:

```bash
ls ~/.ssh/id_ed25519.pub
```

If it says "No such file", create one (press Enter for the default location; a passphrase is recommended):

```bash
ssh-keygen -t ed25519 -C "you@example.com"
```

If the key has a passphrase, add it to ssh-agent so the client can sign without asking. On macOS:

```bash
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
```

On Linux:

```bash
ssh-add ~/.ssh/id_ed25519
```

## Step 2: Send your admin your public key

Print it with its fingerprint:

```bash
cat ~/.ssh/id_ed25519.pub
```

```bash
ssh-keygen -lf ~/.ssh/id_ed25519.pub
```

Send your admin:

1. your name and email,
2. the whole line starting with `ssh-ed25519 AAAA…`,
3. the fingerprint (`SHA256:…`), so they can check it arrived intact,
4. your track(s).

Send only the `.pub` line. **Never send `~/.ssh/id_ed25519`** (the file without `.pub`): that is your private key, and
it never leaves your machine.

Continue with steps 3 and 4 while you wait. Step 5 needs your admin's confirmation.

## Step 3: Clone the repositories side by side

Put your code repository and the export next to each other in one folder:

```bash
mkdir -p ~/Projects/<product> && cd ~/Projects/<product>
git clone <export-repo> <product>-export
git clone <code-repo>
```

The export is **read-only**: never edit, commit or switch branches in it. The client pulls it for you.

## Step 4: Set the client up in your code repository

In the root of your code repository:

```bash
cd ~/Projects/<product>/<code-repo>
npx @alterset/alterspec-client init --dispatcher <dispatcher-url> --export ../<product>-export --track <TRACK> --branch <branch>
```

Answer `y` if npx asks to install the package. Leave out `--branch` when the track's main branch is the remote's
default. A repository that builds several tracks takes them all: `--track BE WEB`. If you sign with another key than
`~/.ssh/id_ed25519`, add `--key <path-to-.pub>`.

If your project must run npx with flags of its own (for instance `--min-release-age=0`, where npm is set to refuse
a package published in the last days and you take the client on its release day), say so once:
`init --npx=--min-release-age=0` (several, comma-separated). `init` keeps them in `.alterspec-client.json` as
`"npx": { "args": ["--min-release-age=0"] }` and writes them into everything that runs the client: the server in
`.mcp.json`, the progress hook, the skills' permissions and the prompts. Every later `init` reads them from there,
so an update never takes them away; `--npx=` removes them. The registry is not a flag: pin it in the repository's
`.npmrc` (see "When something is off").

`init` writes:

| File                          | What it is                                                                 | Commit it?                             |
| ----------------------------- | -------------------------------------------------------------------------- | -------------------------------------- |
| `.alterspec-client.json`      | the dispatcher URL, the export path, your tracks, the main branch          | if the whole team shares these values  |
| `.mcp.json`                   | the `dispatcher` MCP server for Claude Code                                | yes                                    |
| `.claude/settings.json`       | a hook that reports progress after each `git commit`                       | yes                                    |
| `.claude/skills/alterspec-*`  | the skills                                                                 | yes                                    |
| `.alterspec-client/prompts/`  | the instructions behind the skills                                         | yes                                    |
| `.claude/settings.local.json` | your approval of the `dispatcher` server; `init` adds it to `.gitignore`   | **never**                              |

It ends by printing your public key and fingerprint: the same ones as in step 2. It is safe to run again, and running
it again with a newer client updates the skills.

If a teammate has already committed the setup, run `init` anyway: it reports the shared files as unchanged and writes
your approval.

### If your team keeps the Claude Code setup in another repository

Some teams don't commit `.claude`, `.mcp.json` or `.alterspec-client` in the code repository, but keep them in a
shared repository next to it and link them in with symlinks. That works:

- Keep the links out of git on your machine: add each one to `.git/info/exclude` (never committed), e.g.
  `echo "/.mcp.json" >> .git/info/exclude`. `git status` should not list them.
- Run `init` as above. Because `.claude` is a link, it may say it can't tell whether `.claude/settings.local.json` is
  ignored: make sure the shared repository ignores that file.
- If `init` reports skills or `.claude/settings.json` as created or updated, the shared repository is behind the
  client: tell whoever maintains it rather than committing there yourself.

A worktree you make holds only what git tracks: link these into it yourself when you want the skills there.

## Step 5: Check that you can sign in

Once your admin confirms your key is added:

```bash
npx @alterset/alterspec-client open dispatcher
```

It opens the dispatcher in your browser, signed in as you: the dashboard, the changes and tasks, the graph of what
waits for what. If it says the dispatcher refused your SSH key, send your admin the two lines it prints.

## Step 6: Working with Claude Code

**Start a new Claude Code session** in your code repository: a session that was already open doesn't see the new
server. Then talk to it in plain words; the skills do the rest.

| You say or type                                      | What happens                                                                                                                         |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| "give me work" / `/alterspec-task-next`              | takes the next available task on your track and shows the brief; it creates no branch or worktree, you work wherever you like      |
| "I want CHG-052/BE" / `/alterspec-task-next CHG-052/BE` | takes that one task when it is available to you (its predecessors done, on your track, no overlap with your other work); otherwise says the dispatcher's reason and stops |
| "let's work on my task" / `/alterspec-task-context`  | the task's brief from the spec: why, the checklist (each part of an object named by its section or line), the one-time data change if any, the objects it changes (before and after) and where the export uses them, every text as the task's change saw it (later changes to the same objects are listed apart, as their tasks' work), the reach of its rules and roles, the changed acceptance criteria, the rules, events, quality requirements, integrations, decisions and glossary terms they and the change name (the rest, and the entities with their lifecycles, as paths); for a UI track also the screens, their contracts, mockups and design system |
| "what am I on?" / `/alterspec-task-status`           | your tasks with progress and ETA, what's available on your tracks, what is blocked and by what                                       |
| "what does RULE-… say?" / `/alterspec-spec-ask`      | answers about the product from the spec, citing IDs; what the spec doesn't say is recorded as an assumption or an open question for the product side; Claude uses it by itself when a task's spec is undecided |
| "the price screen shows no margin" / `/alterspec-bug` | grooms the report against the spec first: where the product deviates from what the spec says, raises a bug with the dispatcher citing the items it violates, placed after the tasks that built them and offered like any task; where the spec is silent or reads two ways, asks instead; where the spec is wrong, says so |
| `/alterspec-task-done CHG-023/BE`                    | after your branch is pushed: reports the task done with its head commit and the branch (or, once merged, the commit on the main branch); refused while nothing is pushed |
| `/alterspec-task-release CHG-023/BE <reason>`        | gives the task back so someone else can take it; your code and branches stay as they are                                             |
| `/alterspec-task-eta CHG-023/BE <YYYY-MM-DD> <reason>` | sets your own date when the computed ETA is wrong; `clear` instead of the date removes it                                          |

**done**, **release** and **eta** happen only when you type them; Claude never does them on its own.

### A task, start to finish

1. "Give me work." Claude takes a task and shows the brief and its checklist. Work on it in the branch (or worktree) you
   choose, made the way you make them: the client creates no branch, no worktree and no commit in your repository.
2. Build it with Claude in your own technology. The spec says what, never how; a mockup shows the agreed look and
   behaviour, it is not code to copy. When the spec is silent or says two things, Claude asks through `/alterspec-spec-ask` and
   goes on with what the answer allows; when the spec and the code disagree, Claude asks you.
3. Claude ends every commit of the task with a trailer:

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

   `Alterspec-Covers` names the checklist items whose tests pass with that commit, never items that aren't tested yet.
   After each commit a hook reports them in the background, and the task's progress on the dashboard moves. An
   object named without its section (`RULE-002` where the checklist has `RULE-002#guards`) isn't counted: the hook
   tells Claude the form to use, and a later commit naming it that way settles it.

4. Push your branch and type `/alterspec-task-done CHG-023/BE`: the task is done at that commit on that branch, and
   the tasks waiting for it may start from it. Open the pull request into the main branch as usual; the dispatcher
   notices the merge by itself.

When the brief says "Start from `task/chg-012-be`", a task yours waited for was done on that branch and isn't merged
yet: fetch it and base your branch on it, not on main (`git fetch origin task/chg-012-be`, then branch from
`origin/task/chg-012-be`). The teams merge a change's branches together once every track is done.

### A brief that doesn't move under you

The spec keeps changing while you build: a rule your task names may be edited by three later changes before you are
done. Your brief doesn't follow them. It shows every object **as your task's change saw it when it was signed
off**, the same today and next week, however often the export is pulled. What later changes did to those objects is
at the brief's end, under "Changed since (other tasks' work)": each later change with its own task on your track,
and what it touched. That work is built in those tasks, when you or a colleague take them; a question about a
sentence a later change wrote is asked on that change's task.

- A path the brief prints under `.alterspec-client/pins/<chg>-<track>/` is the pinned copy of an object changed
  since (its file and its shards, a few small files); the export's own file is the spec as it is now. The folder
  ignores itself in git and is rewritten every time the brief is made; delete it whenever you like.
- When the brief is read again and something moved in between, it marks it **new** and shows once what the new
  changes did.
- One exception to "not your work": before building one of your task's own objects that later changes touched,
  Claude compares the two texts and doesn't build a line a later change removed or reversed; it builds that item
  as the later change says and says so in the commit.
- An object that was signed off only after your task's change (the brief says so) is shown as the export holds it
  now: the export never had its earlier text.

### One task of your choosing

Name it: `/alterspec-task-next CHG-052/BE` (or "take CHG-052/BE"). The dispatcher assigns it alone when it is
available to you: on a track you may take, in your export, the tasks it waits for done, under your limit on that
track and not overlapping a task you have in progress there. Otherwise you get its reason (blocked by which tasks,
taken by whom, at the limit, done already, pull the export first) and nothing is assigned; Claude never takes the
next task in order instead. The order is advice, not a rule: an available task has its dependencies done.

### Several tasks at once

Ask for more than one: `/alterspec-task-next BE 2`. Claude lists them and works on none; type
`/alterspec-task-context <task>` wherever you work on each, e.g. a session per worktree you made (`git worktree add
../<code-repo>-tasks/chg-023-be -b task/chg-023-be origin/main`). In a worktree the client reads the configuration
from your main checkout, and the first `export-head` or `context` run there approves the dispatcher server in that
worktree's git-ignored `.claude/settings.local.json`, since a worktree holds only what git tracks; start a new Claude
Code session there after that. The dispatcher never gives you two tasks on the same track that change the same
objects, so they don't conflict.

### Questions about the spec

You don't carry questions to the product owner by hand. When the spec leaves something undecided, Claude asks:

- **Answered from the spec.** The answer names the IDs it stands on (the client checks each exists in the export).
  Work goes on, and nothing is sent to the dispatcher: nothing was decided.
- **Assumed** (`Q-12`). The spec is silent; Claude builds on the cautious reading and names `Q-12` in those commits.
  A product person confirms or corrects it on the dispatcher's **Questions** page. A correction shows at the top of
  the task's brief, and Claude reworks what stood on the assumption before anything else.
- **Open** (`Q-13`). Nothing may be assumed. That checklist item stays uncovered and Claude works the others; when
  the answer is there, the brief shows it and the item goes on.

Claude asks not only when it is stuck. Every time it is about to decide how the product behaves where the brief
doesn't say (which refusal wins, a default, what happens to existing records, a message's wording), it asks first:
either the spec already says, or the choice is recorded at once as an assumption the product side sees the same
hour. Nothing about the product is decided silently and found out at the end of the task. How the code is built is
yours and is never asked.

A question is recorded with the task it concerns, and the checklist item when it concerns one, whether or not the
task is yours yet: ask about `CHG-028/BE` while it waits behind another task and it lands on that task's page and in
its next holder's brief, not among the questions about no task. Name the task, or Claude takes the one the work is
about.

One question per matter. A question carries every case of its matter as numbered parts (the moment a limit counts
from, what happens to a thing in flight when it ends, what is recorded then), and a follow-up to Claude's own open
question extends that question instead of adding a new one, so the product side answers the matter once. After
three open questions about one object on a task, Claude asks nothing more about it: it writes the cases still
undecided into one question and builds everything else on the assumptions already recorded. A wish about how the
product should behave or look, with nothing in the spec read two ways and no item waiting on it, is not a question:
bring it to the product side as a proposal.

How an answer is found: the client first looks whether the question was asked before, then computes where the spec
would answer it (`lookup`: what the question names, by ID, by the glossary's words and their synonyms, by title; the
sections to read first; the rules, decisions and "out of scope" lines about it) and gives that reading list to the
answerer. The answerer may call the spec silent only after it opened everything on the list, and the client checks
that it did. So "the spec doesn't say" means the places that would say it were read, not that a search found
nothing.

`npx @alterset/alterspec-client questions` prints your questions with their answers, `questions CHG-023/BE` a
task's; the brief shows the whole change's, so what the backend assumed is in front of the web task too.
`/alterspec-task-done` names the questions still open and doesn't refuse: whether to wait is yours to
decide. If the answer changes the product, the product side grooms it into the spec (several answers as one
change) and signs it off, and it reaches you as a task of its own in a later export. The dispatcher knows which
of that change's questions your track built already (your task finished after the answer), and the brief opens
with it under "Built already": such a task checks that the code says what the spec now says, adds the missing tests
and covers the items; it builds only what wasn't built here. Nothing is marked done for you, and nothing is rebuilt.

While the dispatcher has no questions yet (an older one), the answer is still given, and Claude says it was not
recorded: then an open question is yours to carry, as before.

### Bugs

A bug is the product doing something other than what the spec says; the spec never records one. Say what is
wrong ("the price screen shows no margin") or type `/alterspec-bug <what is wrong>`, you or a product person.
Claude grooms it against the spec before anything is sent, the way it answers a question: the reading list, the
answerer reading the export only. Then one of three:

- **The spec says it and the product does otherwise.** A bug. Claude names the items the product violates
  (acceptance criteria, screen actions, contract states, or an object that is an item of its own), checks each
  exists in the export, looks whether one was raised about them before, and raises it with the dispatcher: a title,
  what was expected, what happened and how to see it, in the reporter's words naming IDs, never spec text. The
  dispatcher gives it a number (`BUG-3`) and a task per track the items are on (`BUG-3/BE`, `BUG-3/BO`), each after
  the tasks that built those items: available at once when they are done, blocked while one is in progress. A bug
  task is taken, worked and reported done like any other; its brief opens with the bug's words and its checklist is
  the cites, covered again as each one's tests pass with the fix.
- **The spec is silent or reads two ways.** Nothing is a bug yet: Claude hands it to `/alterspec-spec-ask`, the
  product side decides, and the bug, if any, comes after.
- **The spec is wrong.** Neither a bug nor a question: a change, groomed and signed off in the spec project, which
  arrives as tasks.

The dispatcher refuses an item no task of the export holds (cite it as the tasks list it) and one nothing built
holds yet (the task that builds it is still to come, so the product can't deviate from it). A bug raised in error,
or twice, is dismissed by whoever raised it while nobody works on it, or by an admin: type
`/alterspec-bug dismiss BUG-3 <reason>`; its tasks are never offered again. `npx @alterset/alterspec-client bugs`
prints your bugs with their tasks, `bugs --about <ID...>` everyone's about some items; `/alterspec-task-status` says
when one of yours was fixed since you last looked.

### Good to know

- **The trailer names the task.** Progress is read from the `Alterspec-Task` trailer of your commits, on any branch;
  the hook takes the task from the last commit's trailer (or from a `task/<chg>-<track>` branch).
- **A UI task waits for its `BE` task.** "Nothing available" on a UI track usually means the backend part isn't done
  yet; `/alterspec-task-status` says what blocks what. On a track, a task waits only for the earlier tasks that
  changed an item of its checklist, wrote what it changes again, or added an object it names; the rest of the
  lineage runs beside it.
- **The scope is the spec's.** If something in the spec is undecided or looks wrong, it is a question (above); don't
  widen or narrow the task yourself.
- **Only you move your task on.** Going away for a while? Release it. An admin can force a release only when you are
  gone, and that is logged.
- **Keep the client current.** Run `init` again now and then (or when your admin says so); it updates the skills.
- **Tell Claude about the spec outside the skills too.** The skills explain the export only while they run. Copy the
  block in [`agent-instructions.md`](agent-instructions.md) (in this package) into your `CLAUDE.md` or wherever you
  keep your agent's instructions, with your export clone's path.

## When something goes wrong

| You see                                                     | Do                                                                                                                                                         |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "The dispatcher refused your SSH key"                       | your key isn't added yet, or you sign with another key: send your admin the two lines it prints (or `npx @alterset/alterspec-client key`)                 |
| "That is not a public key the dispatcher accepts"           | you used an RSA key: make an Ed25519 key (step 1) and send it                                                                                              |
| "No SSH key to sign with"                                   | create `~/.ssh/id_ed25519` (step 1), or point `--key` at your key and run `init` again                                                                     |
| "ssh-agent doesn't hold the key"                            | `ssh-add` your key (step 1)                                                                                                                                |
| `E401` or `E404` running `npx @alterset/...`                | npm is set to a private registry that doesn't have the client. The client is on the public registry: add `@alterset:registry=https://registry.npmjs.org/` (only this package's scope) or `registry=https://registry.npmjs.org/` to the repository's `.npmrc`, or fix your registry login |
| npm refuses the client as published too recently            | your npm keeps packages back for some days after their release: run `init --npx=--min-release-age=0` once, and every command, the hook and the dispatcher server run with the flag |
| Claude has no `dispatcher` tools                            | run `init` again (it approves the server), make sure git doesn't track `.claude/settings.local.json`, and start a new session. In a terminal `claude` session, `/mcp` shows and approves the server too |
| "No .alterspec-client.json here"                            | run `init` in this repository (step 4)                                                                                                                     |
| "The export is N commits behind the dispatcher"             | your export clone couldn't be pulled: `git -C ../<product>-export pull`, and check its remote if it keeps happening                                       |
| an item reported as unknown                                 | a commit's `Alterspec-Covers` named something the checklist lacks. A pushed commit can't be corrected; name the right item on a later commit                |
| `task-done` refused: not pushed                             | push the task's branch `task/<chg>-<track>` first, then run it again                                                                                       |
| anything else                                               | send your admin the message exactly as it appears                                                                                                          |
