From 715cdeb485deaea3dae481d4dc97a25a7e319bf1 Mon Sep 17 00:00:00 2001 From: Daniel Bushman Date: Fri, 10 Jul 2026 01:08:15 +0000 Subject: [PATCH 1/2] docs(maproom): replace INTERIM multi-repo guidance with native 0.3.0 cross-repo flags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the section in maproom-researcher.md with native --all-repos / repeatable --repo guidance (maproom 0.3.0). Update version floor 0.2.0 → 0.3.0. Add Native Cross-Repo Search section to multi-repo-guide.md with per-repo loop demoted to pre-0.3.0 fallback note. Update SKILL.md Cross-Repo Search Workflow with single-invocation examples. Bump plugin.json 0.10.2 → 0.10.3. Verified live: --all-repos and repeatable --repo confirmed working; vector-search exits 2 on multi-repo scope as documented. verify-docs.sh 11/11. Co-Authored-By: Claude Fable 5 --- plugins/maproom/.claude-plugin/plugin.json | 2 +- plugins/maproom/agents/maproom-researcher.md | 29 ++++++------ .../maproom/skills/maproom-search/SKILL.md | 15 ++++++- .../references/multi-repo-guide.md | 44 +++++++++++++++++++ 4 files changed, 75 insertions(+), 15 deletions(-) diff --git a/plugins/maproom/.claude-plugin/plugin.json b/plugins/maproom/.claude-plugin/plugin.json index b8e100c..caf59a2 100644 --- a/plugins/maproom/.claude-plugin/plugin.json +++ b/plugins/maproom/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "maproom", - "version": "0.10.2", + "version": "0.10.3", "description": "Semantic code search using the maproom CLI. Find code by concept, understand architecture, and explore relationships between code elements.", "author": { "name": "Daniel Bushman", diff --git a/plugins/maproom/agents/maproom-researcher.md b/plugins/maproom/agents/maproom-researcher.md index c7954b1..6fead93 100644 --- a/plugins/maproom/agents/maproom-researcher.md +++ b/plugins/maproom/agents/maproom-researcher.md @@ -47,30 +47,33 @@ maproom status Then select the most relevant repo for the research question. - ### Multi-repo tasks -When a task spans multiple repositories, enumerate available repos first, then search each one individually: +Maproom 0.3.0 supports native cross-repo search — use `--all-repos` or repeatable `--repo` flags instead of a per-repo loop. +**Sweep all indexed repos in one call:** ```bash -# Step 1: list all indexed repos (shared-Postgres environments return the full inventory) -maproom status --json +QUERY="" +maproom search --all-repos --query "$QUERY" --k 10 --format agent ``` -Parse the `repos[].name` values from the JSON output to build your repo list. Then issue a separate search per repo: +`--k` is a **per-repo cap**: with `--all-repos` and `--k 10`, you receive up to 10 results per repo, grouped by repo. Results use `repo:file:line` format in `--format agent` output so the source repo is always visible. +**Target specific repos only:** ```bash -# Step 2: search each repo in turn QUERY="" -maproom search --repo --query "$QUERY" --k 10 --format agent +maproom search --repo manifoldlogic/crewchief --repo specs --query "$QUERY" --k 10 --format agent ``` -A local convenience wrapper (`maproom-all`) may be present in some environments; use it if available, but do not assume it exists — the per-repo loop above is portable. +`--repo` is repeatable. Use it when you know which repos are relevant and want to avoid sweeping the full index. + +**Scope rules:** +- `--all-repos`, `--repo` (one or more), and the legacy single-repo `--repo` form are mutually exclusive — pass exactly one scope. +- `vector-search` and `hybrid` modes do **not** support multi-repo scope; they exit with code 2 if `--all-repos` or multiple `--repo` flags are passed. Use FTS (`search`) for cross-repo sweeps. -**`--repo specs` is available in shared-Postgres environments** and covers indexed specification documents. Include it explicitly when the task involves specs. +**Search budget:** One `--all-repos` call counts as **one search** against your session cap (soft=5, hard=10). Prefer a single `--all-repos` call over N single-repo calls — it is equivalent in cost but 10× faster. -**No server-side cross-repo search yet.** There is no `--all-repos` flag. Each search targets exactly one repo. Cross-repo synthesis is done by the agent after collecting results from each repo in sequence. - +**`--repo specs`** covers indexed specification documents in shared-Postgres environments. It is a valid target for both single-repo and multi-repo invocations. ## Critical Rules @@ -105,7 +108,7 @@ maproom search --repo --query --format agent Before beginning the 4-phase workflow: -1. **CLI Version Check:** Run `maproom --version` and verify version 0.2.0 or higher. If version check fails, report error and halt execution. +1. **CLI Version Check:** Run `maproom --version` and verify version 0.3.0 or higher. If version check fails, report error and halt execution. 2. **Query Validation:** Reject null, empty, or whitespace-only queries. Valid query pattern: at least one non-whitespace character. ## Query Classification (Before Phase 1) @@ -347,4 +350,4 @@ Instead: **Security:** Do not include actual credentials, access tokens, or project IDs in your findings output. Use placeholders like `YOUR_PROJECT_ID`. ### CLI and Query Validation -See Pre-Workflow Checks section above. Version 0.2.0 or higher required; null/empty queries rejected. +See Pre-Workflow Checks section above. Version 0.3.0 or higher required; null/empty queries rejected. diff --git a/plugins/maproom/skills/maproom-search/SKILL.md b/plugins/maproom/skills/maproom-search/SKILL.md index 12db7dc..12bf0f4 100644 --- a/plugins/maproom/skills/maproom-search/SKILL.md +++ b/plugins/maproom/skills/maproom-search/SKILL.md @@ -250,7 +250,20 @@ This lists all repos that have been scanned and are available for search. ### Cross-Repo Search Workflow -When a question spans both design and implementation, search across repos sequentially. +**Native multi-repo search (maproom 0.3.0+):** Use `--all-repos` or repeatable `--repo` flags to query multiple repos in a single call. One invocation counts as **one search** against your session cap. + +```bash +# Sweep all indexed repos +QUERY="authentication middleware" +maproom search --all-repos --query "$QUERY" --k 10 --format agent + +# Target specific repos only +maproom search --repo manifoldlogic/crewchief --repo specs --query "$QUERY" --k 10 --format agent +``` + +Note: `vector-search` does not support multi-repo scope — use FTS (`search`) for cross-repo sweeps. + +**Sequential search (specs → code):** When a question spans design rationale and implementation, search specs for *why*, then code for *how*. **Example: Understanding why and how authentication works** diff --git a/plugins/maproom/skills/maproom-search/references/multi-repo-guide.md b/plugins/maproom/skills/maproom-search/references/multi-repo-guide.md index 3f7f057..6b417ad 100644 --- a/plugins/maproom/skills/maproom-search/references/multi-repo-guide.md +++ b/plugins/maproom/skills/maproom-search/references/multi-repo-guide.md @@ -162,6 +162,50 @@ maproom search --repo specs --query "decision rationale" --format agent Results from docs repos include `heading_1`, `heading_2`, `heading_3`, and `heading_4` chunks that reveal the document hierarchy. Use the `file_relpath` and line numbers to navigate to specific sections. +## Native Cross-Repo Search (maproom 0.3.0+) + +Maproom 0.3.0 adds server-side cross-repo search — a single CLI invocation queries multiple repos in one round-trip, returning results grouped by repo with `repo:file:line` coordinates. + +### `--all-repos`: sweep the full index + +```bash +QUERY="authentication middleware" +maproom search --all-repos --query "$QUERY" --k 10 --format agent +``` + +`--k` is a **per-repo cap**: `--k 10` returns up to 10 hits per repo. Results are grouped by repo so you can see which repos contain relevant code at a glance. + +**Search budget:** One `--all-repos` call counts as **one search** against the session cap (soft=5, hard=10). Prefer it over N single-repo calls — it is equivalent in cost but substantially faster. + +### `--repo` (repeatable): target specific repos + +```bash +QUERY="embedding pipeline" +maproom search --repo manifoldlogic/crewchief --repo specs --query "$QUERY" --k 10 --format agent +``` + +Pass `--repo` more than once to search a named subset of repos in a single call. Use this when you know which repos are relevant. + +### Scope rules + +- `--all-repos`, multiple `--repo` flags, and the legacy single-`--repo` form are mutually exclusive — pass exactly one scope type. +- `vector-search` and `hybrid` modes do **not** support multi-repo scope. They exit with code 2 if `--all-repos` or multiple `--repo` flags are passed. Use FTS (`search`) for cross-repo sweeps. +- `--repo specs` covers indexed specification documents in shared-Postgres environments and is a valid target for both single-repo and multi-repo calls. + +### Pre-0.3.0 fallback + +If you are on an environment running maproom older than 0.3.0, native cross-repo flags are unavailable. Fall back to the per-repo loop: + +```bash +# Pre-0.3.0 fallback only — superseded by --all-repos / repeatable --repo in 0.3.0 +QUERY="authentication middleware" +for repo in manifoldlogic/crewchief manifoldlogic/claude-code-plugins specs; do + maproom search --repo "$repo" --query "$QUERY" --k 10 --format agent +done +``` + +A local convenience wrapper (`maproom-all`) performs the same loop in some environments. Both approaches are superseded by native flags once 0.3.0 is installed. + ## Cross-Repo Patterns These patterns combine searches across code and docs repos to answer questions that neither repo can answer alone. Each pattern starts in one repo type and follows up in the other. From 3fd2c69df0b09753316ffcad35995da41ae626ea Mon Sep 17 00:00:00 2001 From: Daniel Bushman Date: Fri, 10 Jul 2026 01:16:58 +0000 Subject: [PATCH 2/2] =?UTF-8?q?fix(maproom):=20address=20review=20findings?= =?UTF-8?q?=20=E2=80=94=20accuracy,=20scope=20rules,=20and=20regression=20?= =?UTF-8?q?coverage?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove fabricated '10× faster' claim; replace with 'substantially faster' (matching multi-repo-guide.md) - Clarify scope rules: --all-repos and --repo are two-way mutually exclusive; --repo is one repeatable flag, not two separate scope types - Fix terminology: 'vector-search' is a subcommand, 'hybrid'/'vector' are --mode values on search; document both paths that exit 2 on multi-repo scope - Apply same scope-rules and mode-terminology fixes to multi-repo-guide.md for consistency - Add 4 new checks to verify-docs.sh (checks 12-15): INTERIM absence, 0.3.0 version floor, --all-repos presence, search-budget note — closes TEST ADEQUACY gap flagged in review - verify-docs.sh now passes 15/15 Co-Authored-By: Claude Fable 5 --- plugins/maproom/agents/maproom-researcher.md | 6 +- plugins/maproom/scripts/verify-docs.sh | 59 ++++++++++++++++++- .../references/multi-repo-guide.md | 4 +- 3 files changed, 63 insertions(+), 6 deletions(-) diff --git a/plugins/maproom/agents/maproom-researcher.md b/plugins/maproom/agents/maproom-researcher.md index 6fead93..ee93647 100644 --- a/plugins/maproom/agents/maproom-researcher.md +++ b/plugins/maproom/agents/maproom-researcher.md @@ -68,10 +68,10 @@ maproom search --repo manifoldlogic/crewchief --repo specs --query "$QUERY" --k `--repo` is repeatable. Use it when you know which repos are relevant and want to avoid sweeping the full index. **Scope rules:** -- `--all-repos`, `--repo` (one or more), and the legacy single-repo `--repo` form are mutually exclusive — pass exactly one scope. -- `vector-search` and `hybrid` modes do **not** support multi-repo scope; they exit with code 2 if `--all-repos` or multiple `--repo` flags are passed. Use FTS (`search`) for cross-repo sweeps. +- `--all-repos` and `--repo` are mutually exclusive — pass one or the other. `--repo` is repeatable; single and multiple uses are the same flag, not different scope types. +- The `vector-search` subcommand and `search --mode hybrid` / `search --mode vector` do **not** support multi-repo scope; they exit with code 2 if `--all-repos` or multiple `--repo` flags are passed. Use `search` (FTS / default mode) for cross-repo sweeps. -**Search budget:** One `--all-repos` call counts as **one search** against your session cap (soft=5, hard=10). Prefer a single `--all-repos` call over N single-repo calls — it is equivalent in cost but 10× faster. +**Search budget:** One `--all-repos` call counts as **one search** against your session cap (soft=5, hard=10). Prefer a single `--all-repos` call over N single-repo calls — it is equivalent in cost but substantially faster. **`--repo specs`** covers indexed specification documents in shared-Postgres environments. It is a valid target for both single-repo and multi-repo invocations. diff --git a/plugins/maproom/scripts/verify-docs.sh b/plugins/maproom/scripts/verify-docs.sh index 26e340f..6b04067 100755 --- a/plugins/maproom/scripts/verify-docs.sh +++ b/plugins/maproom/scripts/verify-docs.sh @@ -39,6 +39,10 @@ CHECKS: 9. New flags (--kind/--lang/--preview/--preview-length/--threshold) in SKILL.md (>= 5) 10. --format agent in troubleshooting.md (informational) 11. Cross-reference integrity (./references/*.md and ./templates/* links in SKILL.md) + 12. No INTERIM markers in plugins/maproom/ (zero hits) + 13. 0.3.0 version floor in maproom-researcher.md (>= 1) + 14. --all-repos flag documented in maproom-researcher.md (>= 1) + 15. Search-budget note (--all-repos = one search) in maproom-researcher.md (>= 1) EXIT CODES: 0 All checks passed @@ -97,7 +101,7 @@ fi # --------------------------------------------------------------------------- PASS_COUNT=0 FAIL_COUNT=0 -TOTAL_CHECKS=11 +TOTAL_CHECKS=15 # --------------------------------------------------------------------------- # JSON accumulation @@ -404,6 +408,59 @@ else json_add_result 11 "Cross-reference integrity" "fail" "$broken" 0 "$broken of $total_refs cross-references are broken" fi +# =========================================================================== +# Check 12: No INTERIM markers in plugins/maproom/ (zero hits) +# =========================================================================== +AGENT_MD="$PLUGIN_DIR/agents/maproom-researcher.md" +human_echo "Check 12: No INTERIM markers in plugins/maproom/" +interim_count=$(grep -rn "INTERIM" "$PLUGIN_DIR" | grep -v "verify-docs.sh" | grep -c "INTERIM" || true) +if [ "$interim_count" -eq 0 ]; then + report_pass "No INTERIM markers found" + json_add_result 12 "No INTERIM markers in plugins/maproom/" "pass" 0 0 "No INTERIM markers found" +else + report_fail "$interim_count INTERIM marker(s) found — remove before shipping" + json_add_result 12 "No INTERIM markers in plugins/maproom/" "fail" "$interim_count" 0 "$interim_count INTERIM marker(s) found" +fi + +# =========================================================================== +# Check 13: 0.3.0 version floor in maproom-researcher.md (>= 1) +# =========================================================================== +human_echo "Check 13: 0.3.0 version floor in maproom-researcher.md" +count=$(grep -c "0\.3\.0" "$AGENT_MD" || true) +if [ "$count" -ge 1 ]; then + report_pass "$count occurrences (>= 1 required)" + json_add_result 13 "0.3.0 version floor in maproom-researcher.md" "pass" "$count" 1 "$count occurrences (>= 1 required)" +else + report_fail "$count occurrences (>= 1 required)" + json_add_result 13 "0.3.0 version floor in maproom-researcher.md" "fail" "$count" 1 "$count occurrences (>= 1 required)" +fi + +# =========================================================================== +# Check 14: --all-repos documented in maproom-researcher.md (>= 1) +# =========================================================================== +human_echo "Check 14: --all-repos flag documented in maproom-researcher.md" +count=$(grep -c "\-\-all-repos" "$AGENT_MD" || true) +if [ "$count" -ge 1 ]; then + report_pass "$count occurrences (>= 1 required)" + json_add_result 14 "--all-repos documented in maproom-researcher.md" "pass" "$count" 1 "$count occurrences (>= 1 required)" +else + report_fail "$count occurrences (>= 1 required)" + json_add_result 14 "--all-repos documented in maproom-researcher.md" "fail" "$count" 1 "$count occurrences (>= 1 required)" +fi + +# =========================================================================== +# Check 15: Search-budget note in maproom-researcher.md (>= 1) +# =========================================================================== +human_echo "Check 15: Search-budget note (--all-repos = one search) in maproom-researcher.md" +count=$(grep -c "one search\|one.*--all-repos\|--all-repos.*one" "$AGENT_MD" || true) +if [ "$count" -ge 1 ]; then + report_pass "$count occurrences (>= 1 required)" + json_add_result 15 "Search-budget note in maproom-researcher.md" "pass" "$count" 1 "$count occurrences (>= 1 required)" +else + report_fail "$count occurrences (>= 1 required)" + json_add_result 15 "Search-budget note in maproom-researcher.md" "fail" "$count" 1 "$count occurrences (>= 1 required)" +fi + # =========================================================================== # Output # =========================================================================== diff --git a/plugins/maproom/skills/maproom-search/references/multi-repo-guide.md b/plugins/maproom/skills/maproom-search/references/multi-repo-guide.md index 6b417ad..ba59e27 100644 --- a/plugins/maproom/skills/maproom-search/references/multi-repo-guide.md +++ b/plugins/maproom/skills/maproom-search/references/multi-repo-guide.md @@ -188,8 +188,8 @@ Pass `--repo` more than once to search a named subset of repos in a single call. ### Scope rules -- `--all-repos`, multiple `--repo` flags, and the legacy single-`--repo` form are mutually exclusive — pass exactly one scope type. -- `vector-search` and `hybrid` modes do **not** support multi-repo scope. They exit with code 2 if `--all-repos` or multiple `--repo` flags are passed. Use FTS (`search`) for cross-repo sweeps. +- `--all-repos` and `--repo` are mutually exclusive — pass one or the other. `--repo` is repeatable; single and multiple uses are the same flag, not different scope types. +- The `vector-search` subcommand and `search --mode hybrid` / `search --mode vector` do **not** support multi-repo scope. They exit with code 2 if `--all-repos` or multiple `--repo` flags are passed. Use `search` (FTS / default mode) for cross-repo sweeps. - `--repo specs` covers indexed specification documents in shared-Postgres environments and is a valid target for both single-repo and multi-repo calls. ### Pre-0.3.0 fallback