feat(plugins/cix): bundle cix-workspace skill + investigator sub-agent (v0.2.0)

.claude-plugin/marketplace.json

@@ -10,16 +10,16 @@
     {
       "name": "cix",
       "source": "./plugins/cix",
-      "description": "Semantic code search and navigation. Bundles the cix CLI and nudges Claude to prefer cix over Grep for semantic queries.",
+      "description": "Semantic code search and navigation. Bundles the cix CLI, slash commands, behavioral hooks, and the experimental cix-workspace skill + cix-workspace-investigator sub-agent for cross-project research across cix workspaces.",
       "author": {
         "name": "dvcdsys"
       },
       "homepage": "https://github.com/dvcdsys/code-index",
       "repository": "https://github.com/dvcdsys/code-index",
       "license": "MIT",
-      "keywords": ["search", "code-search", "semantic", "navigation", "indexing", "embeddings"],
+      "keywords": ["search", "code-search", "semantic", "navigation", "indexing", "embeddings", "workspace", "cross-project", "sub-agent"],
       "category": "developer-tools",
-      "tags": ["search", "indexing", "ai", "embeddings"]
+      "tags": ["search", "indexing", "ai", "embeddings", "workspace", "cross-project"]
     }
   ]
 }

README.md

@@ -392,15 +392,28 @@ cp -r skills/cix ~/.claude/skills/cix
 For multi-repo work via the experimental **workspaces** feature, the
 `cix-workspace` skill teaches the agent the cross-project workflow and
 ships a dedicated `cix-workspace-investigator` sub-agent for parallel
-per-repo fan-out:
+per-repo fan-out. Both are bundled with the **`cix` Claude Code plugin**
+(v0.2.0+) — install it from the marketplace and the workspace pieces
+come with it automatically:
+
+```
+/plugin marketplace add dvcdsys/code-index
+/plugin install cix@code-index
+/reload-plugins
+```
+
+Or the legacy manual route:
 
 ```bash
 cp -r skills/cix-workspace ~/.claude/skills/cix-workspace
 mkdir -p ~/.claude/agents
 cp skills/cix-workspace/agents/cix-workspace-investigator.md ~/.claude/agents/
 ```
 
-Invoke with `/cix-workspace <task>`. See [`workspaces.md`](workspaces.md#agent-integration) for the agent contract and behavior rules.
+The skill is **manual-only by design** — it doesn't auto-trigger on
+cross-cutting prompts. Invoke it explicitly with `/cix-workspace <task>`
+when you genuinely need the multi-repo workflow. See [`workspaces.md`](workspaces.md#agent-integration)
+for the agent contract and behavior rules.
 
 Then in any Claude Code session, invoke the skill **paired with the actual engineering task** — not a search query. The pattern is `/cix <fix / implement / investigate / refactor …>`:
 

plugins/cix/.claude-plugin/plugin.json

@@ -1,14 +1,26 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "cix",
-  "version": "0.1.0",
-  "description": "Semantic code search and navigation for Claude Code via the cix index. Bundles the cix CLI (auto-installs if missing) and nudges Claude to prefer cix over Grep for semantic queries.",
+  "version": "0.2.0",
+  "description": "Semantic code search and navigation for Claude Code via the cix index. Single-repo cix skill + commands, plus the experimental cix-workspace skill and cix-workspace-investigator sub-agent for cross-project research across cix workspaces.",
   "author": {
     "name": "dvcdsys",
     "email": "dvcdsys@gmail.com"
   },
   "homepage": "https://github.com/dvcdsys/code-index",
   "repository": "https://github.com/dvcdsys/code-index",
   "license": "MIT",
-  "keywords": ["search", "code-search", "semantic", "navigation", "indexing", "embeddings", "ai"]
+  "keywords": [
+    "search",
+    "code-search",
+    "semantic",
+    "navigation",
+    "indexing",
+    "embeddings",
+    "ai",
+    "workspace",
+    "cross-project",
+    "monorepo",
+    "sub-agent"
+  ]
 }

plugins/cix/README.md

@@ -18,6 +18,21 @@ Semantic code search and navigation for Claude Code, powered by the
   invoke it (`/cix:search`, `/cix-skill`, or auto-trigger on a relevant
   prompt). Stays in context for the rest of the session — never
   duplicated.
+- **`cix-workspace` skill (SKILL.md)** *(experimental, **manual-only**)* —
+  companion workflow for tasks that span more than one repo. **Does
+  not auto-trigger** — invoke it explicitly with `/cix-workspace <task>`
+  when you want the full cross-project workflow guidance: which repos
+  are in scope, what code is relevant, what changes need to land.
+  Includes ten trust rules for interpreting `projects[]` vs `chunks[]`,
+  a four-part fan-out prompt template, and an anti-patterns list.
+- **`cix-workspace-investigator` sub-agent** *(experimental)* — thin
+  read-only shell around `cix search`/`cix def`/`cix refs` for parallel
+  per-repo fan-out from the workspace skill. Hard rules baked in: one
+  repo per spawn, no edits, no recursion. Methodology and output
+  format are the main agent's call per spawn; the sub-agent follows
+  instructions. Lives at `agents/cix-workspace-investigator.md` —
+  available as `subagent_type="cix-workspace-investigator"` in `Agent`
+  tool calls.
 - **Behavioral nudges (5 hooks):**
   - **SessionStart** — calls `cix status` (2 s timeout). Caches the
     yes/no verdict in `$CLAUDE_PLUGIN_DATA/cix-aware-$SESSION_ID-$DIR_HASH`,
@@ -135,14 +150,63 @@ in two tiers:
 | Path | Purpose |
 |---|---|
 | `.claude-plugin/plugin.json` | Plugin manifest |
-| `skills/cix/SKILL.md` | Lazy-loaded usage skill (~7 KB) |
+| `skills/cix/SKILL.md` | Lazy-loaded single-repo usage skill (~7 KB) |
+| `skills/cix-workspace/SKILL.md` | Cross-project workflow skill *(experimental)* |
+| `agents/cix-workspace-investigator.md` | Read-only per-repo investigator sub-agent *(experimental)* |
 | `commands/*.md` | Six slash commands |
 | `hooks/hooks.json` | SessionStart + PreToolUse(Grep\|Glob\|Bash) registration |
 | `scripts/cix-wrapper.sh` | "Use system or auto-install" CLI wrapper |
 | `scripts/session-start.sh` | One-time session reminder |
 | `scripts/grep-nudge.sh` | Exponential-backoff Grep nudge |
 | `bin/cix` | Symlink to wrapper, exposed on `$PATH` while plugin enabled |
 
+## Cross-project workflow (experimental, manual-only)
+
+For tasks that touch more than the repo you're cd'd into, the plugin
+ships a second skill — **`cix-workspace`** — plus a dedicated
+**`cix-workspace-investigator`** sub-agent for parallel per-repo
+fan-out. **Neither auto-triggers.** You invoke them explicitly when
+you actually need them — typically with `/cix-workspace <task>`.
+
+> *Why manual-only?* The workspace flow is heavier than single-repo
+> `cix search` (multi-repo fan-out, server-side clones, sub-agent
+> spawns) and only pays off when the task genuinely spans repos. We
+> don't want it firing on every request that vaguely mentions
+> "services". Load it deliberately, when you've decided cross-project
+> research is the right shape of work. This policy may change once
+> the heuristics around "is this really cross-project?" are more
+> reliable.
+
+The flow once you've invoked it:
+
+1. `cix-workspace` skill loads, structures the request around three
+   questions (which repos? what code? what changes?).
+2. Main agent runs a short, term-rich workspace search and reads the
+   `projects[]` panel.
+3. For each relevant repo, main agent spawns a `cix-workspace-investigator`
+   sub-agent with the task verbatim, the project_path, seed chunks
+   plus its own interpretive commentary on them, and an explicit
+   deliverable.
+4. Sub-agents run in parallel with isolated context. Main agent
+   synthesizes their reports.
+
+Requirements:
+
+- Configured cix server with **workspaces enabled**
+  (`CIX_WORKSPACES_ENABLED=true`).
+- At least one workspace containing the repos you're working across.
+
+See [`workspaces.md`](https://github.com/dvcdsys/code-index/blob/main/workspaces.md)
+in the parent project for setup details and the full search-algorithm
+reference.
+
+The skill body documents ten "trust rules" derived from internal
+calibration testing — how to read `chunk.score=0` (BM25-only literal
+match), when to drop down to per-project search, when adding a
+disambiguating token helps vs hurts, and so on. Load it via
+`/cix-workspace` when you need the full reference; it stays in
+context for the rest of the session.
+
 ## Troubleshooting
 
 - **"cix: command not found" inside Claude Code Bash tool** — the

plugins/cix/agents/cix-workspace-investigator.md

@@ -0,0 +1,63 @@
+---
+name: cix-workspace-investigator
+description: Read-only deep-dive of ONE repository inside a workspace fan-out task. Receives the user task + project_path + seed chunks (with the main agent's commentary on what to trust and what to question) + an explicit deliverable. Returns whatever the main agent asked for, in the format they asked for. Use only when the main session is running the cix-workspace skill workflow and has identified one or more cross-project repos to investigate in parallel. Do not use for: single-repo questions (use cix search directly), tasks not framed by the cix-workspace skill, anything that requires editing or running code.
+tools: Bash, Read, Grep
+---
+
+# `cix-workspace-investigator`
+
+You investigate ONE repository as part of a larger cross-project workspace task.
+The main agent has full context about the user's goal; you only see what they
+passed to you in this single prompt.
+
+## Your tools
+
+You have a read-only toolkit for code investigation inside the assigned project:
+
+- **`cix search "<term>"`** — semantic / hybrid lookups inside the assigned
+  project. Default tool for "find code that means X".
+- **`cix def <symbol>`** — go-to-definition.
+- **`cix refs <symbol>`** — find every usage.
+- **Read** — open specific files when chunk inspection isn't enough.
+- **Grep** — exact literal strings only (error messages, config keys, import
+  paths). Not for semantic search.
+- **Bash** — for running the `cix` CLI and small read-only shell commands
+  (`ls`, `wc`, `head`, `cat` short files). Never mutate state.
+
+The cix index already covers this project — you don't need to (and can't)
+re-index.
+
+## Hard rules — non-negotiable
+
+1. **Stay inside the assigned `project_path`.** Don't read or query other
+   workspace repos. If you discover a finding that requires looking elsewhere,
+   surface it as an uncertainty for the main agent to fan out further.
+2. **Read-only.** No `Write`, no `Edit`, no `git` mutations, no shell side
+   effects. If you see a bug, describe it — don't fix it.
+3. **No recursion.** Don't spawn further sub-agents. You are one level of
+   fan-out; the main agent handles synthesis.
+4. **Follow the main agent's instructions exactly.** Output format, depth,
+   word budget, and what to look for are the main agent's call — not yours.
+   If they ask for three bullets, give three bullets. If they ask for a
+   five-step trace, give that. Don't volunteer extra structure.
+5. **Report what you can't do.** If a file is missing, if `cix` returns
+   empty for a term that should exist, if a seed chunk doesn't match what
+   the main agent suggested — say so explicitly. Don't fabricate findings
+   to fill a template.
+
+## Output contract
+
+Return exactly what the main agent asked for, in exactly the format they
+asked for. The main agent already knows how to parse the response they
+requested. Don't add a preamble, don't add a meta-summary unless asked,
+don't restate the task back at them.
+
+If the request is ambiguous, pick the most-likely interpretation, execute it,
+and flag the ambiguity in one short line at the end.
+
+## What you are NOT
+
+You are not a generic code-explorer. You are not a planner. You are not a
+reviewer. You are a focused, read-only investigator for one repo, working
+under explicit per-call instructions from a main agent that already knows
+the workspace and the user.