index

What this skill does

<!-- Governing: ADR-0015 (Markdown-Native Configuration), ADR-0016 (Workspace Mode), ADR-0024 (qmd hard dependency), ADR-0025 (Tracker Issues as Fourth qmd Collection), ADR-0026 (Tiered Index Freshness), ADR-0031 (Embed-Session Retry Loop), ADR-0032 (qmd Version-Staleness Check), SPEC-0019 REQ "Issues Collection Layout", SPEC-0019 REQ "Issues Collection Sync via /sdd:index" -->

# Index Repository into QMD

Create per-repository [qmd](https://github.com/tobi/qmd) collections so agents and humans can run hybrid search across a repo's ADRs, OpenSpec specs, source code, and tracker issues from a single query plane. Each repository owns four collections (`{repo}-adrs`, `{repo}-specs`, `{repo}-code`, `{repo}-issues`) so searches can be filtered cleanly with `qmd query "..." -c {repo}-adrs`. The issues collection is populated by syncing the configured tracker into `.sdd/issues/{id}.md` files (per ADR-0025 and `references/tracker-sync.md`). Workspace projects (ADR-0016) get one set of collections per module: `{repo}-{module}-{kind}`.

## Process

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

0. **Resolve artifact paths**: Follow the **Artifact Path Resolution** pattern from `references/shared-patterns.md`. If `$ARGUMENTS` contains `--module <name>`, scope to that module; otherwise, in a workspace, iterate all modules. The resolved ADR directory is `{adr-dir}` and spec directory is `{spec-dir}`, both per-module in workspace mode.

### Step 1: Parse Subcommand

Read `$ARGUMENTS`. The first positional token (ignoring `--module <name>`) selects the operation:

| Token | Operation |
|-------|-----------|
| `add` | Create collections only — do not embed |
| `update` | Re-index existing collections (`qmd update`) |
| `embed` | Generate or refresh vector embeddings (`qmd embed --chunk-strategy auto`) |
| `status` | Show qmd status filtered to this repo's collections |
| `remove` | Drop this repo's collections (asks for confirmation) |
| _(none)_ | Default: add (or update if collections exist) → embed |

### Step 2: Preflight Checks

Before doing anything else, verify the environment. Each check has its own short-circuit message — do not chain them silently. Checks 4 and 5 are non-blocking diagnostics: they emit warnings rendered at the top of the final report (see **Report Banner** in Step 5) but do not stop the operation. Checks 1–3 are hard preconditions and stop the skill on failure.

1. **qmd installed**: Run `command -v qmd >/dev/null 2>&1`. If missing, output and stop:

   ```
   qmd CLI not found. Install it with `npm install -g @tobilu/qmd` (or `bun install -g @tobilu/qmd`), then re-run this skill. See https://github.com/tobi/qmd for details.
   ```

2. **Inside a git repository**: Run `git rev-parse --show-toplevel`. If it fails, output: "Not inside a git repository. `/sdd:index` derives the collection name from the repo root — `cd` into a checkout and try again." Then stop.

3. **CLAUDE.md exists with SDD references**: Read `CLAUDE.md` at the project root (or module root if `--module` is set). If it does not exist or lacks references to an ADR/spec directory, output:

   ```
   CLAUDE.md does not have SDD plugin references. Run `/sdd:init` first so this skill knows where to find ADRs and specs.
   ```

   Then stop. The skill needs CLAUDE.md to know the ADR/spec paths and to extract the per-collection context summary (Step 4).

4. **qmd version staleness check** (non-blocking; Governing: ADR-0032). Read the cache at `~/.cache/sdd-plugin/qmd-version.json`. Schema:

   ```json
   { "latest": "2.1.3", "checked_at": "2026-05-04T10:30:00Z" }
   ```

   - **Cache miss or stale (>7 days)**: refresh via `npm view @tobilu/qmd version 2>/dev/null`. Write the result back to the cache file (creating `~/.cache/sdd-plugin/` if absent). On any failure (offline, registry timeout, npm not in PATH), silently skip the warning — DO NOT block, DO NOT error. Network failures are common and should never gate indexing.
   - **Cache hit (≤7 days old)**: use the cached `latest` value as-is — no `npm view` call.
   - Read installed version: `qmd --version 2>&1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+'`.
   - If installed `<` latest (semver compare on major.minor.patch — pure numeric, no prerelease handling needed for qmd's release pattern), set the report banner:

     ```
     ⚠ qmd {installed} installed; {latest} available — `npm install -g @tobilu/qmd` (may include embed-session-timeout fixes)
     ```

   The banner renders at the top of every report template (see Step 5). If versions match, no banner.

5. **qmd hardware mode** (non-blocking; Governing: ADR-0026 embed policy, ADR-0031 retry loop). Determines GPU vs. CPU for embed scheduling. The previous detection technique — scanning `qmd status` for the "running on CPU" warning — is structurally wrong because the warning emits only when the embedding model loads (during `qmd embed`), never in `qmd status`. Replaced with a cached probe of qmd's own emitted output.

   Read the cache at `~/.cache/sdd-plugin/qmd-hardware.json`. Schema:

   ```json
   { "qmd_version": "2.1.0", "qmd_path": "/usr/bin/qmd", "hardware": "cpu", "detected_at": "2026-05-04T10:30:00Z" }
   ```

   - **Cache hit AND qmd_version matches `qmd --version` AND qmd_path matches `command -v qmd`**: use the cached `hardware` value (`gpu` or `cpu`). Skip the probe.
   - **Cache miss, version mismatch, path mismatch, or `--reprobe` flag in `$ARGUMENTS`**: defer detection to the first embed run — see **Operation: embed** Step 1 below. Until then, **assume CPU** (conservative default; worst case is a backgrounded fast embed for a GPU machine on first run).
   - The cache is keyed by `(qmd_version, qmd_path)` so an upgrade or relocation of qmd invalidates it automatically. The cache file is treated as untrusted input — if it fails to parse as JSON or is missing required fields, treat as a cache miss.

   Surface the resolved hardware as a one-line note in the report header (`Hardware: GPU (cached)` or `Hardware: CPU (cached)` or `Hardware: assumed CPU (probing on next embed)`).

6. **qmd install writability** (non-blocking; surfaces as report warning). When qmd was installed via `sudo npm install -g`, its `node-llama-cpp` GPU build artifacts cannot be written under `/usr/lib/node_modules/...` by a non-root user, which silently forces CPU mode even on GPU machines. Detect:

   ```bash
   qmd_root=$(npm root -g 2>/dev/null)/@tobilu/qmd/node_modules/node-llama-cpp/llama
   if [ -d "$qmd_root" ] && [ ! -w "$qmd_root" ]; then
     # surface warning
   fi
   ```

   If unwritable, surface the diagnosis in the report (DO NOT auto-fix — destructive ownership changes need user consent):

   ```
   ⚠ qmd installed at {npm-root-g}/@tobilu/qmd is not writable by $USER.
   node-llama-cpp cannot build GPU artifacts under it; embeds will fall back to CPU (~3.4s/chunk).
   Fix options:
     1. Reinstall under your home: npm config set prefix ~/.npm-global && npm install -g @tobilu/qmd
     2. Take ownership: sudo chown -R $USER {npm-root-g}/@tobilu/qmd/node_modules/node-llama-cpp
   ```

   If `npm root -g` fails or the path does not exist, skip silently — qmd may be installed via a different package manager (bun, manual build) that doesn't have this problem.

### Step 3: Derive Collection Names

1. Compute the repo slug:

   ```bash
   git rev-parse --show-toplevel | xargs basename | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g'
   ```

2. Build the collection name set (per ADR-0025 / SPEC-0019, the issues collection is the fourth per-repo collection alongside adrs, specs, and code):
   - **Single-module project** (no workspace, or `--module` provided): `{repo}-adrs`, `{repo}-specs`, `{repo}-code`, `{repo}-issues`. Where `{repo}` is the slug from step 3.1, plus the module name when `--module` is provided (e.g., `stumpcloud-infra-adrs`).
   - **Workspace aggregate mode** (no `--module`, multiple modules detected): one quadruple per module