Cix Workspace

---
name: cix-workspace
description: Cross-project research workflow for cix workspaces in Claude Cowork. Use when a request spans multiple repositories — "wire feature X through the platform", "add Y across the services", "change Z in production/staging", "how does this work end-to-end across repos". Uses cix_workspace_search to find which repos are in scope, then cix_search to drill into one repo at a time. Talks to a cix server that may host many workspaces and repos, so name the workspace and project explicitly.
metadata:
  version: "0.1.0"
  surface: cowork
---

# `cix workspace` — Cross-Project Research Workflow

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

`cix_workspace_search` 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*. Don't jump to implementation before you can
answer all three with evidence.

There is no "current repo" here (Cowork has no opened working directory). A
workspace groups several indexed repos on a server; infer the task's **anchor
repo** from the request, and let the workspace supply the surrounding repos.

> **This skill only searches.** The `cix_*` MCP tools are read-only — there is
> no MCP tool to create a workspace or link/unlink repos. If the workspace you
> need doesn't exist yet, an operator sets it up with the `cix` CLI
> (`cix ws create` / `add`) or the dashboard; here you consume workspaces that
> already exist.

## First: which server hosts the workspace?

A cix connection may reach more than one **server** (a local box, a remote
corporate backend, …). Each server hosts its own workspaces and projects — a
workspace named `platform` on one server is unrelated to anything on another.

`cix_list_servers` lists the configured servers. **A workspace and all its repos
live on exactly one server.** Decide which server you're on, then be consistent:
pass the *same* `server` argument to every call in the flow
(`cix_list_workspaces`, `cix_workspace_search`, and the per-project `cix_search`
drill-downs). Mixing servers mid-workflow silently returns empty or wrong-repo
results, because the project doesn't exist on the other server.

**Rule:** use the default server (omit `server`) unless the user names one, or the
target workspace isn't on the default. Never guess a name — call
`cix_list_servers`. Once you know it, thread it through the whole workflow.

## When to reach for workspace search

| Signal in the user's request | What to do |
|---|---|
| Names a product / acronym you don't recognize | 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 — the 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 often a manifests/config/contract repo even when a code repo ranks higher (trust rule 7) |
| Plain change entirely inside one repo | **Don't** workspace search. Use the `cix` single-repo skill |
| User points at a specific symbol / file path | **Don't.** `cix_definitions` on the name, or Read the path |

If unsure, call `cix_list_workspaces` once to see whether a workspace covering
the task even exists. If not, this skill doesn't apply.

## The workflow

A goal-driven loop. Each step is fast — don't shortcut it.

### Step 0 — orient
- `cix_list_servers` — which servers exist? which is default?
- `cix_list_workspaces` — workspaces on the chosen server (id + name).
- `cix_list_workspace_projects(workspace)` — confirm the repos are indexed.

Lock in the server here, before searching. If a later response shows
`stale_fts_repos`, trust the dense ranking less (see references/troubleshooting.md).

### Step 1 — answer "which repos?"

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

- GOOD — short, term-rich: `cix_workspace_search(workspace, "rate-limit middleware")`
- BAD — a full sentence dilutes the literal-match signal with stopwords:
  `"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", "to", "a") match
everywhere and dilute that signal.

Read the response:
- **`projects[]` is the answer to Q1**, sorted by `project_score`. Each entry has
  `bm25_score` (literal overlap) and `dense_score` (semantic). Projects below the
  per-query threshold are already filtered out — you only see survivors.
- The top entry's `project_score` is your reference. 60–100% of top = core
  relevant; 40–60% = secondary.
- Include the **anchor repo** (the one the user's task is rooted in) even if it
  ranks low — infer it from the request. The other repos are its dependencies /
  consumers / providers.

Optional args: `top_projects` (default 5), `top_chunks` (default 10),
`min_score` (default 0.4 — pass `0` for intentional cross-cutting sweeps).

### Step 2 — answer "what code is relevant?" (sequential drill-down)

Workspace search is a **scoping** tool: it tells you which repos are in play and
shows a *capped teaser* of chunks (round-robin, ~few per repo). It is NOT where
you read the code.

**Drill into the relevant repos one at a time, in priority order** — do NOT fan
out, do NOT spawn sub-agents. For each repo from `projects[]`, starting with the
highest-ranked relevant one:

1. Take its `project_path` from the `projects[]` panel — that is the `host_path`.
2. Call `cix_search(project=<that host_path>, query="<focused query>", server=<same server>)`
   to get file-grouped, deeper results.
3. Read the results, decide whether this repo is actually in scope, then move to
   the next repo only if the task needs it.

For a natural-language drill-down query ("how does X work"), pass `min_score: 0`
— abstract queries can score in the 0.2–0.3 range the default rejects.

Workspace repos are external (server-cloned), so once `cix_search` points you at
a file, read the real source with `cix_file(project, file, [start], [end])`
instead of relying on the capped chunk teaser, and browse the layout with
`cix_tree(project, [dir])`. In Cowork (no local filesystem) these are the way to
see actual file contents.

Investigate the strongest-signal repo fully before opening the next. Most tasks
resolve after drilling into the top 1–2 repos; you rarely need all of them.

### Step 3 — answer "what changes?"

This is the deliverable. Your per-repo reads feed the plan; you write it. For
each relevant repo:
- What needs to change (specific file:line, or a new file).
- Why (which step of the data flow this implements).
- Order constraints (e.g. "shared-models migration must deploy before the backend
  reads the new field").
- Tests that prove it works.

Confirm with the user before any of this lands. The plan is the deliverable of
this skill; implementation is a separate step.

### Throughout — ask, don't guess
Trigger a clarifying question when:
- Top-2 projects are at near-equal `project_score` with different labels — ask
  which repo the user means.
- `bm25_score` is 0 across all projects → either the FTS index is stale (see
  troubleshooting) or the term doesn't appear literally anywhere. Ask for the term
  the code actually uses ("we call it `Order` in code, not `Trade`").
- Your drill-down into a repo finds no clear entry point — surface that
  uncertainty, don't paper over it.

Don't ask if the answer is obvious from the chunks. The bar is "I have two
plausible interpretations and the wrong one costs real time."

## Reading the projects panel

```
  - service-a  (/repo/service-a)  [score 0.50, 5 hit(s); bm25 0.42, dense 0.56]
  - service-b  (/repo/service-b)  [score 0.41, 5 hit(s); bm25 0.32, dense 0.50]
  - service-c  (/repo/service-c)  [score 0.29, 3 hit(s); bm25 0.16, dense 0.36]
```

- `project_score`: the blended candidacy in [0,1]. Top = strongest signal.
- `bm25_score` >> `dense_score`: relevant by literal token overlap (the term
  appears in code). Trust the surface area, verify semantic relevance.
- `dense_score` >> `bm25_score`: relevant by semantic similarity but the literal
  term isn't there (common when the user's word is a nickname not used in code).
- Both near zero: you're seeing it because nothing else cleared the gate either.
  Treat with skepticism.

## Trust rules (summary — full version in references)

Empirically calibrated. Apply before acting on a panel:

1. **`chunk.score >= 0.4`** is the trust threshold; below that is ~75% noise.
2. **`chunk.score == 0`** is a BM25-only (literal) hit — valuable for unique
   identifiers, noise for generic English words.
3. **Top-1 of `projects[]` is right ~70%** of the time on real tasks — **scan
   ranks 2–5 before reformulating.**
4. **"Change X in production"** usually lives in a manifests/config/contract repo,
   not the code repo that ranks #1 (look for `*-platform`, `*-manifests`,
   `*-config`, `openapi*` at ranks 3–5).
5. **Words ≠ change location.** Search ranks where the *words* live; your task is
   about where the *change* happens. They coincide ~70%, not always.

Read **references/trust-rules.md** before acting on a borderline panel — it has
all ten rules with examples, plus when to add a disambiguating token and when to
sweep with `min_score: 0`.

## Worked example — why this skill exists

The failure mode this guards against: running workspace search with a full
natural-language sentence. A pure-dense search returns the N nearest vectors
regardless of how far "nearest" is, so every repo surfaces — including repos with
zero literal mention of the feature. The hybrid + short-query approach fixes it:

1. Query with the **high-precision term** first (the acronym, the feature name,
   the unique symbol) — everything else is noise.
2. Trust the project gate: if a repo dropped out, it dropped out for a reason.
3. Never treat "this repo surfaced in search" as "this repo is in scope" —
   verify by drilling in (Step 2) and confirm with the user.

## Quick tool reference

- `cix_list_servers` — list servers; omit `server` for the default.
- `cix_list_workspaces` — workspaces on a server.
- `cix_list_workspace_projects(workspace)` — repos in a workspace, with status.
- `cix_workspace_search(workspace, query, [top_projects], [top_chunks], [min_score], [server])`
  — cross-repo search. Use a short, term-rich query.
- `cix_search(project, query, [min_score], [server], …)` — per-repo drill-down;
  `project` is a `host_path` from the `projects[]` panel.

## TL;DR

When the task plausibly spans more than one repo:

0. `cix_list_servers` → if more than one, pick the one hosting the workspace and
   thread the same `server` through every call.
1. `cix_list_workspaces` → find it, then `cix_list_workspace_projects` to confirm
   repos are indexed.
2. `cix_workspace_search` with a **short, term-rich** query.
3. Read `projects[]` → that's your scope (Q1).
4. For each repo in scope, drill in **sequentially** with `cix_search`
   (`project` = the host_path), one repo at a time. No fan-out, no sub-agents.
5. Synthesize the reads → a per-repo change plan with order constraints (Q2 + Q3).
6. Confirm scope and plan with the user before implementing.

If `bm25_score` is 0 across the board, the FTS index is stale — see
references/troubleshooting.md before trusting the result.