Doccraft Update

---
name: doccraft-update
description: >-
  Update the installed doccraft skills and openspec instructions to the latest
  release. Reads the version stamp from doccraft.json, fetches the migration
  manifest via npx doccraft@latest llm, and either updates silently (dominant
  path — no migration entries) or summarises and gates on approval (assisted
  path — migration entries present). Never fabricates steps the manifest did
  not declare.
---

> Managed by **doccraft** — `doccraft update` regenerates this file. Local edits will be overwritten. See `doccraft.json` to override project-specific vocabulary and paths without touching this file.

# doccraft — update

## When to use

- Periodically to keep doccraft skills and openspec instructions current.
- After a teammate updates doccraft in a shared repo (check the version stamp
  in `doccraft.json` against the latest npm release).
- When `doccraft-config` or other skills mention features that don't seem to
  work — you may be running an older skill body.

## Steps

### 1. Read the local version

Read `"version"` from `doccraft.json` at the project root.
If the file does not exist, treat the local version as **unknown** and warn
the user — then proceed.

### 2. Fetch the manifest

Run exactly once:

```
npx doccraft@latest llm
```

Parse the JSON output. The relevant fields are:
- `version` — the latest doccraft version.
- `migrations` — array of `{ from, to, summary, steps[] }` entries.

If the invocation fails (no network, npx error), report the error and stop.
Do not guess at migration steps.

### 3. Filter migrations

Filter `migrations` to entries where the local version falls within the
`from` range and the latest version falls within the `to` range.

Treat `from` as a semver range (e.g. `"0.x"` covers `0.1.0`, `0.9.3`).
If you cannot parse the range, surface it as a step the user should review
manually rather than blocking the update.

### 4a. Dominant path — no matching entries

**If the filtered list is empty:**

1. Run: `npx doccraft@latest update`
2. Bump `"version"` in `doccraft.json` to the latest version (surgical edit
   of the `"version"` string and the version segment of `"$schema"` URL only).
3. Report what was installed (skills refreshed, openspec version).
4. No prompt before running — this is the expected steady-state path.

### 4b. Assisted path — migration entries present

**If the filtered list is non-empty:**

1. Summarise each matching migration entry:
   - `summary` — one sentence.
   - `steps[]` — numbered list.
2. Ask for user approval before proceeding.
3. On approval:
   a. Run: `npx doccraft@latest update`
   b. Bump the `"version"` stamp (same surgical edit as 4a).
   c. Report what was installed.
4. On rejection: stop. Do not run the update command.

## Constraints

- **Never fabricate migration steps** — only report what `migrations[]` in
  the manifest declares. If the array is empty, there are no user actions
  required.
- **Gate only when migration entries are present.** The dominant path (empty
  migrations) must run without prompting — that is the whole point.
- **Tolerate a missing `doccraft.json`** — continue with local version
  treated as unknown; warn the user and proceed.
- **One npx invocation for the manifest.** Do not call `npx doccraft@latest
  llm` more than once per update run.