Feature/query orchestrator

.github/workflows/build-docs-map.yml

@@ -0,0 +1,44 @@
+name: Build Docs Map
+
+on:
+  workflow_run:
+    workflows: ["Update Claude Code Documentation"]
+    types: [completed]
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'scripts/build_docs_map.py'
+      - 'docs/**/*.md'
+
+permissions:
+  contents: write
+
+jobs:
+  build-map:
+    if: github.event.workflow_run.conclusion == 'success' || github.event_name != 'workflow_run'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ref: main
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Build docs map
+        run: python scripts/build_docs_map.py
+
+      - name: Commit if changed
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          if [[ -n "$(git status --porcelain docs/DOCS_MAP.md)" ]]; then
+            git add docs/DOCS_MAP.md
+            git commit -m "Update DOCS_MAP.md - $(date +'%Y-%m-%d')"
+            git push
+          else
+            echo "No changes to DOCS_MAP.md"
+          fi

.gitignore

@@ -27,6 +27,9 @@ Thumbs.db
 .last_check
 claude-docs-helper.sh
 
+# User-generated query outputs (created by /query feature)
+/query/
+
 # Test files
 test_*.txt
 test_*.md

CLAUDE.md

@@ -11,6 +11,14 @@ When responding to /docs commands:
 2. Read documentation files from the docs/ directory only
 3. Use the manifest to know available topics
 
+## For /query Command
+
+When responding to /query commands:
+1. Invoke the `query-orchestrator` skill via the Skill tool
+2. Follow the skill's 7-step procedure (parse → task ID → folder → template → batch dispatch → assemble → summary)
+3. Subagents read from docs/ folder via DOCS_MAP.md
+4. Outputs accumulate in ~/.claude-code-docs/query/
+
 ## Files to ultrathink about
 
 @install.sh
@@ -20,3 +28,5 @@ When responding to /docs commands:
 @claude-docs-helper.md
 @scripts/
 @.github/workflows/
+@docs/DOCS_MAP.md
+@claude-files/

README.md

@@ -97,6 +97,19 @@ The changelog feature fetches the latest release notes directly from the officia
 /docs uninstall    # Get commnd to remove claude-code-docs completely
 ```
 
+### Multi-question research with /query
+
+`/query` parses your input into sub-questions, dispatches research subagents in batches of 3 in parallel, and assembles a structured answer file.
+
+```bash
+/query What is a hook?                          # single question
+/query Explain hooks and MCP, then compare them # multi-part
+/query 1. ... 2. ... 3. ...                     # explicit numbering
+```
+
+Each query produces a folder under `~/.claude-code-docs/query/QUERY-TASK-<keyword>-<id>/`
+containing the full structured answer with citations. Useful for non-trivial questions that span multiple docs.
+
 ### Customize command name
 
 If you prefer a different command name (e.g., `/claude-docs` instead of `/docs`), you can easily customize it:

claude-files/agents/query-researcher.md

@@ -0,0 +1,90 @@
+---
+name: query-researcher
+description: Research a single sub-question by reading Claude Code documentation files and producing a structured answer file
+tools: Read, Grep, Glob, Write, Bash
+---
+
+# Query Researcher
+
+You research ONE sub-question. You read the docs map, pick 2-5 relevant files, read them, then write a structured answer to a specific file path.
+
+## Input (provided in your prompt)
+
+The orchestrator gives you these fields:
+
+- `Task: <TASK_ID>` — the parent task identifier
+- `Query ID: [QUERY-N]` — your specific query slot
+- `Question:` — the actual question text
+- `Output file:` — exact path where you write the answer
+- `Docs map:` — path to DOCS_MAP.md
+- `Docs folder:` — path to the docs directory
+
+## Procedure
+
+### Step 1 — Pick relevant docs (max 5)
+
+Read the docs map with the Read tool. Match the question against entries via:
+
+- Title overlap
+- Summary overlap
+- Keyword overlap (each entry lists TF-IDF keywords)
+
+Prefer specific files over general ones (e.g., `hooks.md` over `overview.md` for a hooks question). If the question is broad with no specific match, pick 1 general + 2 specific.
+
+You may use Grep to find term-specific matches:
+
+```bash
+grep -l "specific-term" ~/.claude-code-docs/docs/*.md | head -5
+```
+
+### Step 2 — Read selected docs
+
+Use the Read tool on each selected file. **Hard cap: 5 files.** If a file you're reading references another that's clearly more relevant, swap rather than add.
+
+### Step 3 — Synthesize an answer
+
+Build an answer that:
+
+- Directly answers the question
+- Cites which docs you used
+- Quotes short relevant excerpts
+- Is 200-500 words typical (longer only if necessary)
+- Notes gaps or ambiguities when docs don't fully cover the question
+
+### Step 4 — Write the output file
+
+Use the Write tool to create the output file at the path provided in your input. Use this EXACT structure:
+
+```markdown
+# Answer to [QUERY-N]
+
+**Question:** <restate the question>
+**Task:** <TASK_ID>
+
+## Researched files
+
+- `docs/file1.md` — why relevant
+- `docs/file2.md` — why relevant
+
+## Answer
+
+<synthesized answer with markdown formatting>
+
+## Source excerpts
+
+> Short relevant quote from `file1.md`
+
+> Short relevant quote from `file2.md`
+
+## Notes
+
+<gaps, ambiguities, or "none">
+```
+
+## Constraints
+
+- Read AT MOST 5 docs
+- Write EXACTLY ONE output file (path given in input)
+- Do NOT call other subagents (no Task tool)
+- Do NOT fetch from the web (use only the local docs folder)
+- If no docs match the question, write the output file with `## Answer\n_No matching documentation found for this question. Suggested related topics: ..._`

claude-files/commands/query.md

@@ -0,0 +1,10 @@
+---
+description: Research Claude Code documentation by batching multi-question queries to specialized subagents
+argument-hint: <your question(s) — single or multi-part>
+---
+
+The user has invoked /query with the following input:
+
+$ARGUMENTS
+
+Use the Skill tool to invoke the `query-orchestrator` skill. Pass the user query above as the skill's argument. Follow the skill's instructions exactly.

claude-files/skills/query-orchestrator/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: query-orchestrator
+description: Use when handling /query slash command — parses multi-part questions, dispatches batched subagents to research docs, and assembles final answer
+---
+
+# Query Orchestrator
+
+You orchestrate research on Claude Code documentation when the user invokes `/query`. You decompose the user's input into sub-questions, dispatch a `query-researcher` subagent for each in batches of 3 parallel, and assemble all answers into a single output file.
+
+## Inputs
+
+The slash command passes the user's raw query as your argument. Examples:
+
+- "What are hooks?" (single question, N=1)
+- "Explain hooks and MCP, and how to integrate them" (3 sub-questions)
+- "1. ... 2. ... 3. ..." (explicit numbering)
+
+## Step-by-step procedure
+
+### Step 1 — Parse into sub-questions
+
+Identify each independent factual sub-question in the user's input. A sub-question is something a researcher could answer alone by reading docs.
+
+Rules:
+
+- One cohesive question → N = 1
+- Explicit numbering (1./2./3. or bullets) → follow numbering
+- Independent parts joined by a coordinating conjunction (e.g., `and`, `or`) → split, but only if each part is independently answerable from docs
+- Trim and normalize each sub-question to a clear standalone form
+
+Output internally:
+
+SUB_QUESTIONS = [
+  "What are hooks?",
+  "What is MCP?",
+  "How to integrate hooks with MCP?"
+]
+N = 3
+
+### Step 2 — Generate task ID
+
+- Take the first sub-question's most discriminative content word, skipping stopwords (`the`, `a`, `what`, `how`, `is`, `does`).
+- Lowercase, ASCII-normalize, slugify.
+- If no content word can be identified (e.g., "How does it work?"), use the literal keyword `query`.
+- Append current epoch milliseconds via Bash: `date +%s%3N`.
+- Format: `QUERY-TASK-<keyword>-<epoch_ms>`.
+- Example: `QUERY-TASK-hooks-1715432100123`.
+
+### Step 3 — Create task folder
+
+Use the Bash tool:
+
+    mkdir -p ~/.claude-code-docs/query/<TASK_ID>
+
+### Step 4 — Write initial query.md
+
+Use the Write tool to create `~/.claude-code-docs/query/<TASK_ID>/query.md` from this template (substitute placeholders):
+
+    # Query Task: <TASK_ID>
+
+    **Original user query:**
+    > <ORIGINAL_USER_INPUT>
+
+    **Created at:** <ISO_TIMESTAMP>
+    **Number of sub-questions:** <N>
+    **Status:** in-progress
+
+    ---
+
+    ## [QUERY-1] — <SHORT_TITLE_1>
+
+    **Question:** <SUB_QUESTION_1>
+
+    **Answer:**
+    <!-- ANSWER-1-START -->
+    _pending — researcher dispatched_
+    <!-- ANSWER-1-END -->
+
+    ---
+
+    ## [QUERY-2] — <SHORT_TITLE_2>
+
+    **Question:** <SUB_QUESTION_2>
+
+    **Answer:**
+    <!-- ANSWER-2-START -->
+    _pending — researcher dispatched_
+    <!-- ANSWER-2-END -->
+
+    ---
+
+    <!-- repeat the [QUERY-N] block for every sub-question -->
+
+`SHORT_TITLE_n` is a 3-5 word descriptor you derive from the sub-question (e.g., "What are hooks?" → "Hooks definition").
+
+### Step 5 — Dispatch subagents in batches of 3
+
+**CRITICAL:** All Task tool calls in one batch MUST be sent in a SINGLE message to execute in parallel. If you send them in separate messages they will execute sequentially.
+
+Batching table:
+
+| N  | Batches      |
+|----|--------------|
+| 1  | [1]          |
+| 2  | [2]          |
+| 3  | [3]          |
+| 4  | [3, 1]       |
+| 5  | [3, 2]       |
+| 6  | [3, 3]       |
+| 7  | [3, 3, 1]    |
+| 15 | [3, 3, 3, 3, 3] |
+
+General rule: `ceil(N/3)` batches; first floor(N/3) batches have 3 calls each; final batch has N mod 3 calls (or 3 if N is a multiple of 3).
+
+For each batch of up to 3 consecutive sub-questions:
+
+1. In a SINGLE message, issue up to 3 parallel Task tool calls.
+2. Each Task call uses `subagent_type: query-researcher`.
+3. Wait for ALL calls in the batch to return before starting the next batch.
+
+Each Task call prompt MUST contain these exact fields:
+
+    Task: <TASK_ID>
+    Query ID: [QUERY-N]
+    Question: <sub-question text>
+    Output file: ~/.claude-code-docs/query/<TASK_ID>/QUERY-<N>.md
+    Docs map: ~/.claude-code-docs/docs/DOCS_MAP.md
+    Docs folder: ~/.claude-code-docs/docs/
+
+### Step 6 — Assemble answers into final query.md
+
+After ALL batches complete:
+
+1. Issue parallel Read calls for every `QUERY-N.md` (single message, N Read tool calls).
+2. For each file, extract everything below the H1 header (`# Answer to [QUERY-N]`) — this is the answer body.
+3. Build the complete final `query.md` in memory: header (TASK_ID, original query, timestamp, N, `Status: complete`), then for each [QUERY-N] the question text plus the extracted body (replacing the `_pending_` placeholder).
+4. Single Write call overwrites `query.md` with the complete assembled content.
+
+If a `QUERY-N.md` is missing (subagent failed):
+
+- Insert: `_⚠️ Researcher did not complete this query. Re-run `/query` for just this question._` in place of the answer body.
+
+### Step 7 — Chat summary
+
+Output to chat:
+
+    ✓ Query complete: <TASK_ID> (<N> questions)
+
+    • [QUERY-1] <one-line synthesis of answer 1>
+    • [QUERY-2] <one-line synthesis of answer 2>
+    • ...
+
+    Full details: ~/.claude-code-docs/query/<TASK_ID>/query.md
+
+Keep each bullet to one line. Do not paste the full answers in chat.
+
+## Failure handling
+
+| Failure | Handling |
+|---------|----------|
+| `mkdir` fails | Abort with error message; do not dispatch subagents |
+| DOCS_MAP.md missing | Tell user to re-run `~/.claude-code-docs/install.sh` |
+| Subagent returns no file | Insert warning placeholder for that query; continue with others |
+| Parsing yields N=0 | Ask user to rephrase the query |