/cix-workspace

name: cix-workspace
description: Cross-project research workflow for cix workspaces. Load the `cix-workspace` skill explicitly when a request spans multiple repos and you want the full workflow guidance (which repos? what code? what changes?) plus the trust rules for interpreting workspace search responses. Bundles the cix-workspace-investigator sub-agent for parallel per-repo fan-out. Do not auto-trigger.
user-invocable: true
allowed-tools: Bash(cix *), Agent

`cix workspace` — Cross-Project Research Workflow

You usually work inside one repo — your **primary project** — the directory the user opened you in. Most tasks are fully contained there and `cix search` / `cix definitions` / `cix references` are the right tools.

But some tasks are not contained. A request like "wire feature X through the platform" can touch a half-dozen repos in different languages, layers, and shapes — a service, a shared library, the infra manifests, an API spec. Reading the primary repo alone gives you 1/N of the picture. Worse, you don't know which N repos are actually involved until you look.

`cix workspace` is the tool for that. It searches every repo in a named workspace at once and tells you:

1. **Which repos are actually relevant to this request.** 2. **Which code in those repos is the entry point.** 3. **What changes need to land in each, and in what order.**

Those three questions are the *goal* of using this skill. Don't jump to implementation before you can answer all three with evidence.

> **Prerequisite: a populated workspace.** This skill assumes the > workspace already exists and its repos are indexed. If it doesn't, > create and populate one first (owner/admin): `cix ws create "<name>"`, > then `cix ws "<name>" add <project>` for each already-indexed repo — or > clone new GitHub repos in via the dashboard. `cix ws` lists what's > available; the main `cix` skill has the full management verb reference.

---

First: which server hosts the workspace?

The `cix` CLI can be configured with **several named servers** (a local box, a remote corporate backend, …). Each server hosts its **own** set of workspaces and projects — a workspace named `platform` on one server is unrelated to anything on another. Every `cix` command targets the **default** server unless you pass the global `--server <alias>` flag (or set `CIX_SERVER`).

cix config show     # lists configured servers; * marks the default

**A workspace and all its repos live on exactly one server.** So before you run the workflow, decide which server you're on, then be **consistent**: pass the *same* `--server <alias>` to *every* command in the flow — `cix ws`, workspace search, per-project drill-down, and the sub-agent fan-out. Mixing servers mid-workflow (orient on server A, drill down on the default) silently returns empty or wrong-repo results, because the project simply doesn't exist on the other server.

**Agent rule:** use the default server (no flag) unless the user names a specific server, or the primary project's workspace isn't on the default. Never guess an alias — run `cix config show` to see the configured names. Once you know the alias, thread it through the whole workflow. The examples below omit `--server` for readability; add it to **every** command when the target workspace is on a non-default server.

---

When to reach for workspace search

| Signal in the user's request | What to do | |---|---| | Names a product / acronym you don't fully recognize from primary repo | Workspace search the acronym, see where it lives | | "Add X to the Y flow", "wire Z into A" | Workspace search Y or Z — likely cross-cutting | | "Across services", "between repos", "end-to-end" | Workspace search the feature | | Talks about an event / topic / contract / API endpoint | Workspace search the event name | | References infra / deployment alongside code | Workspace search — infra repo is probably in the workspace too | | "How do I change X in production / staging" | Workspace search BUT look past top-1 — the answer is usually a manifests/config/contract repo even when a code repo ranks higher (rule 7 below) | | Plain bugfix entirely inside one file | **Don't** workspace search. `cix search` is enough | | User points at a specific symbol / file path | **Don't.** `cix definitions <name>` or just Read the path |

If you're not sure, run `cix ws` once to see whether the primary project is even part of a workspace. If it isn't, this skill doesn't apply.

---

The workflow

The goal-driven loop. Don't shortcut it. Each step is fast.

Step 0 — orient

cix config show              # which servers exist? which is default?
cix ws                       # list workspaces on the (default) server
cix ws <name>                # describe — confirm repos are indexed (✓ count)

If `cix ws` doesn't list the workspace your task is about, it may live on a different server — re-run with `--server <alias>` (the alias from `cix config show`) and keep that flag on every later command. Lock in the server here, before searching.

If the workspace shows `stale_fts_repos` in any search response later, trust the dense ranking less — see the troubleshooting section.

Step 1 — answer "which repos?"

Run workspace search with a **short, term-rich query**, not the full user sentence:

# GOOD — short, term-rich (a product acronym + an action verb)
cix ws platform search "rate-limit middleware"

# BAD — full sentence dilutes BM25 with stopwords ("add", "to", "a")
cix ws platform search "Add a rate limit to every API endpoint"

Why short: the hybrid algorithm fuses BM25 (literal token match) with dense (semantic). BM25 carries the project-gating signal — repos that share zero vocabulary with the query drop out. Common words ("add", "flow", "for") match everywhere and dilute that signal.

Read the response:

• **`projects[]` is the answer to Q1.** Sorted by `project_score`

(candidacy). Each entry has `bm25_score` (literal