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

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-token overlap) and dense_score (semantic similarity).
• Projects below the per-query relative threshold are already filtered out — you only see the survivors.
• Top entry's project_score is your reference. Entries at 60-100% of top are core relevant. Entries at 40-60% are secondary. Below 40% would have been dropped server-side.

Always include the primary project even if workspace search ranks it low — the user's task is rooted there. The workspace's other repos are dependencies / consumers / providers / counter-parties.

Step 2 — answer "what code is relevant?"

Now switch from workspace search to per-project search. Workspace search is a scoping tool: it tells you which repos are in play and shows a teaser of chunks, but that teaser is capped (round-robin, ~5 chunks per repo) and is NOT where you read the code. Once you know the target repos, drill into each one with single-project search (cix search -n <project_path>) or a cix-workspace-investigator sub-agent — that is where the real, file-grouped depth comes from. Don't try to answer the task from the workspace chunk panel alone.

For each repo from step 1, look at the chunks panel. The chunk list is interleaved by rank across surviving projects so each repo's top hit appears early. Use these chunks as starting points for a deeper read, not as the full answer.

For repos other than the primary, you have two options:

A. Quick scan (≤ 2 repos to investigate): use single-project search directly via the CLI, scoped with -n to the project. Pass the project_path from the workspace-search projects[] panel verbatim:

# Search inside one specific project (-n = exact project ID from cix list /
# the workspace projects[] panel). --server keeps it on the same backend
# the workspace lives on — REQUIRED when that's not the default server.
cix search "rate limit middleware handler" -n <project_path> --min-score 0
cix search "rate limit middleware handler" -n <project_path> --server corporate --min-score 0

The per-project default min_score is 0.2 — light floor that keeps abstract NL queries non-empty. For drill-down on a natural- language question ("how does X work end-to-end"), pass --min-score 0 explicitly to be safe. For strict code-symbol matching, pass 0.4+.

Workspace repos are external (server-cloned), so once search points you at a file you can read the actual source — not just the capped chunk teaser — straight