From 2c1ce601b1a6a2885ed4e33bb36c84e72d88db95 Mon Sep 17 00:00:00 2001 From: Laith Al-Saadoon <9553966+theagenticguy@users.noreply.github.com> Date: Fri, 5 Jun 2026 16:23:04 -0500 Subject: [PATCH] fix(ci): point license gate at packages/cli and align plugin tool namespace to codehub Two independent fixes for gates that were green but checking nothing. License gate (vacuous post package-collapse): After the 17->1 package collapse, the root package.json is private with no runtime dependencies, so license-checker-rseidelsohn --production --excludePrivatePackages run from the repo root traversed zero packages and passed vacuously. The real third-party runtime deps (including lru-cache, which is BlueOak-1.0.0) live in packages/cli. All four callers (scripts/acceptance.sh, mise.toml, .github/workflows/ci.yml, and .github/workflows/pre-release-gate.yml) now pass --start packages/cli so the checker traverses the cli production deps, and all four share one unified allowlist superset: Apache-2.0;MIT;BSD-2-Clause;BSD-3-Clause;ISC;CC0-1.0;BlueOak-1.0.0;0BSD (acceptance.sh previously omitted BlueOak-1.0.0 and 0BSD). Verified the corrected command now lists 25 cli production packages and exits 0, and a deliberately-narrow allowlist correctly fails on lru-cache, proving the scan is no longer vacuous. Plugin tool namespace (broken at runtime): The MCP server registers under the key codehub, so the live tools are mcp__codehub__*. The plugin's code-analyst agent tool grants and the skill files referenced tools as mcp__opencodehub__*, which matched zero real tools. Rewrote mcp__opencodehub__ -> mcp__codehub__ across the plugins/ runtime tree and the committed .claude/ install mirror (agent frontmatter grants + skill invocation/reference text). Server key, CLI bin name, and setup.ts are unchanged. --- .claude/agents/code-analyst.md | 2 +- .claude/skills/codehub-contract-map/SKILL.md | 18 ++--- .claude/skills/codehub-document/SKILL.md | 38 +++++------ .../references/cross-reference-spec.md | 2 +- .../agents/doc-analysis-dead-code.md | 6 +- .../agents/doc-analysis-ownership.md | 12 ++-- .../agents/doc-analysis-risk-hotspots.md | 24 +++---- .../agents/doc-architecture-data-flow.md | 10 +-- .../agents/doc-architecture-module-map.md | 6 +- .../doc-architecture-system-overview.md | 8 +-- .../agents/doc-behavior-processes.md | 14 ++-- .../agents/doc-behavior-state-machines.md | 12 ++-- .../agents/doc-cross-repo-contracts-matrix.md | 4 +- .../agents/doc-cross-repo-dependency-flow.md | 4 +- .../agents/doc-cross-repo-portfolio-map.md | 2 +- .../agents/doc-diagrams-components.md | 10 +-- .../agents/doc-diagrams-dependency-graph.md | 10 +-- .../agents/doc-diagrams-sequences.md | 10 +-- .../templates/agents/doc-reference-cli.md | 8 +-- .../agents/doc-reference-mcp-tools.md | 10 +-- .../agents/doc-reference-public-api.md | 14 ++-- .claude/skills/codehub-onboarding/SKILL.md | 16 ++--- .../skills/codehub-pr-description/SKILL.md | 16 ++--- .claude/skills/opencodehub-debugging/SKILL.md | 42 ++++++------ .claude/skills/opencodehub-exploring/SKILL.md | 40 +++++------ .claude/skills/opencodehub-guide/SKILL.md | 58 ++++++++-------- .../opencodehub-impact-analysis/SKILL.md | 42 ++++++------ .claude/skills/opencodehub-pr-review/SKILL.md | 68 +++++++++---------- .../skills/opencodehub-refactoring/SKILL.md | 50 +++++++------- .github/workflows/ci.yml | 3 + .github/workflows/pre-release-gate.yml | 3 + mise.toml | 6 +- plugins/opencodehub/agents/code-analyst.md | 2 +- .../skills/codehub-contract-map/SKILL.md | 18 ++--- .../skills/codehub-document/SKILL.md | 40 +++++------ .../references/cross-reference-spec.md | 2 +- .../agents/doc-analysis-dead-code.md | 6 +- .../agents/doc-analysis-ownership.md | 12 ++-- .../agents/doc-analysis-risk-hotspots.md | 24 +++---- .../agents/doc-architecture-data-flow.md | 10 +-- .../agents/doc-architecture-module-map.md | 6 +- .../doc-architecture-system-overview.md | 8 +-- .../agents/doc-behavior-processes.md | 14 ++-- .../agents/doc-behavior-state-machines.md | 12 ++-- .../agents/doc-cross-repo-contracts-matrix.md | 4 +- .../agents/doc-cross-repo-dependency-flow.md | 4 +- .../agents/doc-cross-repo-portfolio-map.md | 2 +- .../agents/doc-diagrams-components.md | 10 +-- .../agents/doc-diagrams-dependency-graph.md | 10 +-- .../agents/doc-diagrams-sequences.md | 10 +-- .../templates/agents/doc-reference-cli.md | 8 +-- .../agents/doc-reference-mcp-tools.md | 10 +-- .../agents/doc-reference-public-api.md | 14 ++-- .../skills/codehub-onboarding/SKILL.md | 16 ++--- .../skills/codehub-pr-description/SKILL.md | 16 ++--- .../skills/opencodehub-debugging/SKILL.md | 42 ++++++------ .../skills/opencodehub-exploring/SKILL.md | 40 +++++------ .../skills/opencodehub-guide/SKILL.md | 58 ++++++++-------- .../opencodehub-impact-analysis/SKILL.md | 42 ++++++------ .../skills/opencodehub-pr-review/SKILL.md | 68 +++++++++---------- .../skills/opencodehub-refactoring/SKILL.md | 50 +++++++------- scripts/acceptance.sh | 8 ++- 62 files changed, 574 insertions(+), 560 deletions(-) diff --git a/.claude/agents/code-analyst.md b/.claude/agents/code-analyst.md index b4402d18..6a788c99 100644 --- a/.claude/agents/code-analyst.md +++ b/.claude/agents/code-analyst.md @@ -1,7 +1,7 @@ --- name: code-analyst description: Use when the user asks to understand code structure, impact of changes, find owners, audit dependencies, or navigate the codebase graph. Specializes in the OpenCodeHub MCP toolkit and always grounds claims in graph queries rather than text search. -tools: mcp__opencodehub__query, mcp__opencodehub__context, mcp__opencodehub__impact, mcp__opencodehub__route_map, mcp__opencodehub__api_impact, mcp__opencodehub__shape_check, mcp__opencodehub__tool_map, mcp__opencodehub__verdict, mcp__opencodehub__owners, mcp__opencodehub__license_audit, mcp__opencodehub__list_findings, mcp__opencodehub__list_findings_delta, mcp__opencodehub__list_dead_code, mcp__opencodehub__signature, mcp__opencodehub__detect_changes, Read, Grep, Glob +tools: mcp__codehub__query, mcp__codehub__context, mcp__codehub__impact, mcp__codehub__route_map, mcp__codehub__api_impact, mcp__codehub__shape_check, mcp__codehub__tool_map, mcp__codehub__verdict, mcp__codehub__owners, mcp__codehub__license_audit, mcp__codehub__list_findings, mcp__codehub__list_findings_delta, mcp__codehub__list_dead_code, mcp__codehub__signature, mcp__codehub__detect_changes, Read, Grep, Glob model: sonnet --- diff --git a/.claude/skills/codehub-contract-map/SKILL.md b/.claude/skills/codehub-contract-map/SKILL.md index bc1f0f3a..a7fc60f0 100644 --- a/.claude/skills/codehub-contract-map/SKILL.md +++ b/.claude/skills/codehub-contract-map/SKILL.md @@ -1,7 +1,7 @@ --- name: codehub-contract-map -description: "Use when the user asks for a cross-repo contract map, an API-consumer matrix, or a service-interaction diagram across a repo group. Examples: \"map the HTTP contracts between services\", \"which services call the billing API\", \"show the contract matrix for the platform group\". GROUP MODE ONLY — requires a named group. DO NOT use on a single repo (use `codehub-document` with `reference/public-api.md`). DO NOT use if `mcp__opencodehub__group_list` does not include the group." -allowed-tools: "Read, Write, mcp__opencodehub__group_list, mcp__opencodehub__group_status, mcp__opencodehub__group_contracts, mcp__opencodehub__group_query, mcp__opencodehub__route_map, mcp__opencodehub__list_repos" +description: "Use when the user asks for a cross-repo contract map, an API-consumer matrix, or a service-interaction diagram across a repo group. Examples: \"map the HTTP contracts between services\", \"which services call the billing API\", \"show the contract matrix for the platform group\". GROUP MODE ONLY — requires a named group. DO NOT use on a single repo (use `codehub-document` with `reference/public-api.md`). DO NOT use if `mcp__codehub__group_list` does not include the group." +allowed-tools: "Read, Write, mcp__codehub__group_list, mcp__codehub__group_status, mcp__codehub__group_contracts, mcp__codehub__group_query, mcp__codehub__route_map, mcp__codehub__list_repos" argument-hint: " [--output ] [--committed]" color: magenta model: sonnet @@ -13,9 +13,9 @@ Standalone group-only skill. Renders `group_contracts` into a Markdown + Mermaid ## Preconditions -1. A `` positional argument is required. If missing or if `mcp__opencodehub__group_list` does not return the name, refuse with: +1. A `` positional argument is required. If missing or if `mcp__codehub__group_list` does not return the name, refuse with: `Contract map requires a named group — run 'codehub group list' to see registered groups.` (Spec 001 AC-3-4.) -2. `mcp__opencodehub__group_status({group})` must return `fresh: true` for every member. If any member is stale, abort and name each stale repo. +2. `mcp__codehub__group_status({group})` must return `fresh: true` for every member. If any member is stale, abort and name each stale repo. ## Arguments @@ -30,12 +30,12 @@ Default output path: ## Process 1. Run the preconditions. Refuse on missing/unknown group. -2. `mcp__opencodehub__group_list` — confirm `` exists; read member list. -3. `mcp__opencodehub__group_status({group})` — confirm freshness per member. Abort with named stale repos otherwise. -4. `mcp__opencodehub__group_contracts({group})` — the spine. Returns `{producer_repo, consumer_repo, path, method, shape}`. +2. `mcp__codehub__group_list` — confirm `` exists; read member list. +3. `mcp__codehub__group_status({group})` — confirm freshness per member. Abort with named stale repos otherwise. +4. `mcp__codehub__group_contracts({group})` — the spine. Returns `{producer_repo, consumer_repo, path, method, shape}`. 5. If `group_contracts` returns `[]` (zero inter-repo contracts): still write the artifact with a `No inter-repo contracts detected` banner and an empty matrix. Do not error. (Spec 001 AC-5-5.) -6. `mcp__opencodehub__group_query({group, text: "api handlers"})` — disambiguate producer-side locations. -7. For each member repo: `mcp__opencodehub__route_map({repo})` for handler-path citations. +6. `mcp__codehub__group_query({group, text: "api handlers"})` — disambiguate producer-side locations. +7. For each member repo: `mcp__codehub__route_map({repo})` for handler-path citations. 8. Build the consumer/producer matrix: rows = producers, columns = consumers, cell = contract count. 9. Build the Mermaid `flowchart LR` showing inter-repo edges, labeled with contract counts. 10. Assemble the output using the template below. diff --git a/.claude/skills/codehub-document/SKILL.md b/.claude/skills/codehub-document/SKILL.md index cec81f65..d72316d3 100644 --- a/.claude/skills/codehub-document/SKILL.md +++ b/.claude/skills/codehub-document/SKILL.md @@ -1,7 +1,7 @@ --- name: codehub-document -description: "Use when the user asks to generate, regenerate, or refresh long-form codebase documentation, an architecture book, a module map, or a per-repo reference — especially after `codehub analyze` finishes or after a large merge. Examples: \"document this repo\", \"regenerate the architecture docs\", \"write a module map for the monorepo\", \"produce a group-wide portfolio doc\". DO NOT use if the repo is not indexed — run `codehub analyze` first and confirm `mcp__opencodehub__list_repos` returns the repo. DO NOT use for PR descriptions (use `codehub-pr-description`), onboarding docs (use `codehub-onboarding`), or cross-repo contract maps alone (use `codehub-contract-map`)." -allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(codehub:*), mcp__opencodehub__list_repos, mcp__opencodehub__project_profile, mcp__opencodehub__query, mcp__opencodehub__context, mcp__opencodehub__impact, mcp__opencodehub__dependencies, mcp__opencodehub__owners, mcp__opencodehub__risk_trends, mcp__opencodehub__route_map, mcp__opencodehub__tool_map, mcp__opencodehub__list_dead_code, mcp__opencodehub__list_findings, mcp__opencodehub__verdict, mcp__opencodehub__group_list, mcp__opencodehub__group_query, mcp__opencodehub__group_status, mcp__opencodehub__group_contracts, mcp__opencodehub__sql, Task" +description: "Use when the user asks to generate, regenerate, or refresh long-form codebase documentation, an architecture book, a module map, or a per-repo reference — especially after `codehub analyze` finishes or after a large merge. Examples: \"document this repo\", \"regenerate the architecture docs\", \"write a module map for the monorepo\", \"produce a group-wide portfolio doc\". DO NOT use if the repo is not indexed — run `codehub analyze` first and confirm `mcp__codehub__list_repos` returns the repo. DO NOT use for PR descriptions (use `codehub-pr-description`), onboarding docs (use `codehub-onboarding`), or cross-repo contract maps alone (use `codehub-contract-map`)." +allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(codehub:*), mcp__codehub__list_repos, mcp__codehub__project_profile, mcp__codehub__query, mcp__codehub__context, mcp__codehub__impact, mcp__codehub__dependencies, mcp__codehub__owners, mcp__codehub__risk_trends, mcp__codehub__route_map, mcp__codehub__tool_map, mcp__codehub__list_dead_code, mcp__codehub__list_findings, mcp__codehub__verdict, mcp__codehub__group_list, mcp__codehub__group_query, mcp__codehub__group_status, mcp__codehub__group_contracts, mcp__codehub__sql, Task" argument-hint: "[output-dir] [--group ] [--committed] [--refresh] [--section ]" color: indigo model: sonnet @@ -18,9 +18,9 @@ Primary artifact generator. Produces a tree of cross-linked Markdown under `.cod ## Preconditions (check before Phase 0) -1. `mcp__opencodehub__list_repos` returns the target. If not, emit `Run codehub analyze first — repo is not indexed.` and stop. +1. `mcp__codehub__list_repos` returns the target. If not, emit `Run codehub analyze first — repo is not indexed.` and stop. 2. `codehub status` reports fresh. If stale, emit `Run 'codehub analyze' first — index is stale` and stop. -3. Group mode only: `mcp__opencodehub__group_status({group})` must return `fresh: true` for every member. If any member is stale, abort and name each stale repo. +3. Group mode only: `mcp__codehub__group_status({group})` must return `fresh: true` for every member. If any member is stale, abort and name each stale repo. ## Arguments @@ -38,24 +38,24 @@ Phase 0 writes `/.context.md` and `/.prefetch.md` so Phase **Wave 0a — independent precompute (one message, parallel)**. Issue all of these in a single tool-use batch: -- `mcp__opencodehub__list_repos` -- `mcp__opencodehub__project_profile` -- `mcp__opencodehub__sql` — schema probe: `SELECT table_name, column_name FROM information_schema.columns WHERE table_name IN ('nodes','relations') ORDER BY table_name, column_name` -- `mcp__opencodehub__route_map` -- `mcp__opencodehub__tool_map` -- `mcp__opencodehub__dependencies` -- `mcp__opencodehub__risk_trends` -- `mcp__opencodehub__list_dead_code` -- `mcp__opencodehub__list_findings` -- Group mode only: `mcp__opencodehub__group_list`, `mcp__opencodehub__group_status`, `mcp__opencodehub__group_contracts` +- `mcp__codehub__list_repos` +- `mcp__codehub__project_profile` +- `mcp__codehub__sql` — schema probe: `SELECT table_name, column_name FROM information_schema.columns WHERE table_name IN ('nodes','relations') ORDER BY table_name, column_name` +- `mcp__codehub__route_map` +- `mcp__codehub__tool_map` +- `mcp__codehub__dependencies` +- `mcp__codehub__risk_trends` +- `mcp__codehub__list_dead_code` +- `mcp__codehub__list_findings` +- Group mode only: `mcp__codehub__group_list`, `mcp__codehub__group_status`, `mcp__codehub__group_contracts` **Wave 0b — depends on 0a (one message, parallel)**. Needs schema column names + profile entry points from 0a, so it is a second batch. Issue in one message: -- `mcp__opencodehub__sql` — top communities (`SELECT … FROM nodes WHERE kind='Community' ORDER BY cohesion DESC LIMIT 10`) -- `mcp__opencodehub__sql` — top processes (`SELECT … FROM nodes WHERE kind='Process' ORDER BY step_count DESC LIMIT 10`) -- `mcp__opencodehub__sql` — relations slice for diagrams (filtered per the schema probe) -- `mcp__opencodehub__owners` × top-5 folders (derived from `project_profile` entry points + file-count heuristic) -- Group mode only: `mcp__opencodehub__group_query` for any canonical cross-repo search terms +- `mcp__codehub__sql` — top communities (`SELECT … FROM nodes WHERE kind='Community' ORDER BY cohesion DESC LIMIT 10`) +- `mcp__codehub__sql` — top processes (`SELECT … FROM nodes WHERE kind='Process' ORDER BY step_count DESC LIMIT 10`) +- `mcp__codehub__sql` — relations slice for diagrams (filtered per the schema probe) +- `mcp__codehub__owners` × top-5 folders (derived from `project_profile` entry points + file-count heuristic) +- Group mode only: `mcp__codehub__group_query` for any canonical cross-repo search terms **Wave 0c — inline Write (no tool batch)**. Deterministic post-processing; no MCP calls: diff --git a/.claude/skills/codehub-document/references/cross-reference-spec.md b/.claude/skills/codehub-document/references/cross-reference-spec.md index 20ecb1e0..b783f687 100644 --- a/.claude/skills/codehub-document/references/cross-reference-spec.md +++ b/.claude/skills/codehub-document/references/cross-reference-spec.md @@ -79,7 +79,7 @@ Group mode populates `cross_repo_refs[]`: ## `--refresh` algorithm 1. Load `.docmeta.json` from the existing output tree. -2. Fetch the current `codehub_graph_hash` from `mcp__opencodehub__list_repos`. If it matches the manifest's hash exactly, skip to step 5. +2. Fetch the current `codehub_graph_hash` from `mcp__codehub__list_repos`. If it matches the manifest's hash exactly, skip to step 5. 3. For each `section` in the manifest: - Compute `max(mtime(source))` across `sections[i].sources[]` via `stat`. - If `max(source_mtime) > sections[i].mtime`: mark the section stale. diff --git a/.claude/skills/codehub-document/templates/agents/doc-analysis-dead-code.md b/.claude/skills/codehub-document/templates/agents/doc-analysis-dead-code.md index 67ccdef3..e447df5a 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-analysis-dead-code.md +++ b/.claude/skills/codehub-document/templates/agents/doc-analysis-dead-code.md @@ -25,14 +25,14 @@ Produce `{{ docs_root }}/analysis/dead-code.md`: three tables enumerating unrefe |---|---|---| | Shared context | `Read {{ context_path }}` | always first | | Prefetch ledger | `Read {{ prefetch_path }}` | always first | -| Dead-code inventory | `mcp__opencodehub__list_dead_code({repo: "{{ repo }}"})` | mid-run (rarely cached; the tool is cheap) | +| Dead-code inventory | `mcp__codehub__list_dead_code({repo: "{{ repo }}"})` | mid-run (rarely cached; the tool is cheap) | | Last-modified per path | from `list_dead_code` response fields when present, else `git log -1 --format=%cs -- ` via shell | mid-run | | Graph hash | `{{ graph_hash }}` for the empty-state banner timestamp anchor | cached | ## 4. Process 1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm graph hash and any cached dead-code digest. -2. Call `mcp__opencodehub__list_dead_code({repo: "{{ repo }}"})`. Partition the response into three buckets: `Unreferenced exports`, `Unreferenced files`, `Dead imports`. +2. Call `mcp__codehub__list_dead_code({repo: "{{ repo }}"})`. Partition the response into three buckets: `Unreferenced exports`, `Unreferenced files`, `Dead imports`. 3. If all three buckets are empty: skip to step 7 (empty-state banner). 4. For `Unreferenced exports`: draft a table with columns `Symbol | Path | Last modified`. Path is a backtick `path:LOC`. Last modified is an ISO date. 5. For `Unreferenced files`: draft a table with columns `File | Lines | Last modified`. File is a backtick `path`. Lines is an integer LOC count. @@ -57,7 +57,7 @@ Produce `{{ docs_root }}/analysis/dead-code.md`: three tables enumerating unrefe | Need | Tool | Why | |---|---|---| -| Unreferenced symbols + files | `mcp__opencodehub__list_dead_code` | graph-aware; deletes are safe | +| Unreferenced symbols + files | `mcp__codehub__list_dead_code` | graph-aware; deletes are safe | | Last-modified per path | `list_dead_code` fields, else `git log -1` shell | graph does not always carry mtime | | LOC per unreferenced file | `Read` then line count | graph stores node spans, not file LOC | | Cross-check at import site | `Read` at `path:LOC` | verify import survives before listing as dead | diff --git a/.claude/skills/codehub-document/templates/agents/doc-analysis-ownership.md b/.claude/skills/codehub-document/templates/agents/doc-analysis-ownership.md index da8dbddf..3fa09153 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-analysis-ownership.md +++ b/.claude/skills/codehub-document/templates/agents/doc-analysis-ownership.md @@ -26,15 +26,15 @@ Produce `{{ docs_root }}/analysis/ownership.md`: a ranked table of folders in `{ | Shared context | `Read {{ context_path }}` | always first | | Prefetch ledger | `Read {{ prefetch_path }}` | always first | | Owners summary | `{{ context_path }} § Owners summary` | cached | -| Owners per folder | `{{ prefetch_path }} § owners` or `mcp__opencodehub__owners({path: })` | cached when present | -| Folder roster | `mcp__opencodehub__sql({query: "SELECT DISTINCT file_path FROM nodes WHERE kind='File'"})` + folder-prefix grouping | mid-run, only if `.context.md` roster is truncated | +| Owners per folder | `{{ prefetch_path }} § owners` or `mcp__codehub__owners({path: })` | cached when present | +| Folder roster | `mcp__codehub__sql({query: "SELECT DISTINCT file_path FROM nodes WHERE kind='File'"})` + folder-prefix grouping | mid-run, only if `.context.md` roster is truncated | | Top-contributor share | `owners` response field `share` | cached or mid-run | ## 4. Process 1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm Owners summary and cached owners digest. 2. Build the folder roster: use `.context.md § Owners summary` when it enumerates folders; otherwise group `File` nodes by top-level folder prefix (`packages//src`, `src/`, etc.). -3. For each folder (top 15 by file count): resolve top owner and share from `{{ prefetch_path }} § owners` when present, else call `mcp__opencodehub__owners({path: })`. Capture top owner, share %, total contributors. +3. For each folder (top 15 by file count): resolve top owner and share from `{{ prefetch_path }} § owners` when present, else call `mcp__codehub__owners({path: })`. Capture top owner, share %, total contributors. 4. Rank folders by top-owner share, descending. Draft the ranking table with columns `Folder | Top owner | Share | Total contributors`. Every Folder cell is a backtick path. 5. Identify Single Points of Failure: folders or files where the top owner's share is > 70%. For each SPOF: draft a bullet under the `## Single points of failure` H2 stating the path, the owner's share percentage, and a one-sentence mitigation (pair reviewer, knowledge-transfer session, cross-training target, etc.). 6. Draft the intro (1-2 paragraphs): what "share" means (commit share, not line share), the window, and what a > 70% share signals for bus factor. @@ -54,14 +54,14 @@ Produce `{{ docs_root }}/analysis/ownership.md`: a ranked table of folders in `{ | Need | Tool | Why | |---|---|---| -| Contributor share per folder | `mcp__opencodehub__owners` | authoritative over git-blame | +| Contributor share per folder | `mcp__codehub__owners` | authoritative over git-blame | | Cached owners digest | `{{ prefetch_path }} § owners` | precomputed; do not re-call for cached paths | | Folder roster | `{{ context_path }} § Owners summary` | precomputed | -| Folder roster (fallback) | `mcp__opencodehub__sql` over `File` nodes | only when `.context.md` slice is truncated | +| Folder roster (fallback) | `mcp__codehub__sql` over `File` nodes | only when `.context.md` slice is truncated | ## 7. Fallback paths -- If `mcp__opencodehub__owners` fails for a path: cite the top-3 authors from a manual git-log walk and mark the row `*git-log fallback*` in the Top owner cell. +- If `mcp__codehub__owners` fails for a path: cite the top-3 authors from a manual git-log walk and mark the row `*git-log fallback*` in the Top owner cell. - If `.context.md § Owners summary` is absent: use the `sql` folder roster and call `owners` per folder. Cite the fallback in the Work log. - If no folder crosses the > 70% threshold: still emit the `## Single points of failure` H2 with a single line `No folders exceed the 70% bus-factor threshold.` — the H2 must exist for Phase E cross-references. - If owners data is completely missing (new repo, shallow clone): write the gap to the Work log, skip the Write step, and do not emit an empty file with a single-row table. diff --git a/.claude/skills/codehub-document/templates/agents/doc-analysis-risk-hotspots.md b/.claude/skills/codehub-document/templates/agents/doc-analysis-risk-hotspots.md index a0c36612..51fbc18f 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-analysis-risk-hotspots.md +++ b/.claude/skills/codehub-document/templates/agents/doc-analysis-risk-hotspots.md @@ -26,18 +26,18 @@ Produce `{{ docs_root }}/analysis/risk-hotspots.md`: a ranked table of the top 1 | Shared context | `Read {{ context_path }}` | always first | | Prefetch ledger | `Read {{ prefetch_path }}` | always first | | Owners summary | `{{ context_path }} § Owners summary` | cached | -| Risk trends | `mcp__opencodehub__risk_trends({repo: "{{ repo }}", window_days: 30})` | mid-run | -| Current findings | `mcp__opencodehub__list_findings({repo: "{{ repo }}", severity: ">=warn"})` | mid-run | -| Owners per hotspot | `mcp__opencodehub__owners({path: })` or `{{ prefetch_path }} § owners` | cached when present | -| Verdict context (optional) | `mcp__opencodehub__verdict({repo: "{{ repo }}"})` | mid-run, optional | +| Risk trends | `mcp__codehub__risk_trends({repo: "{{ repo }}", window_days: 30})` | mid-run | +| Current findings | `mcp__codehub__list_findings({repo: "{{ repo }}", severity: ">=warn"})` | mid-run | +| Owners per hotspot | `mcp__codehub__owners({path: })` or `{{ prefetch_path }} § owners` | cached when present | +| Verdict context (optional) | `mcp__codehub__verdict({repo: "{{ repo }}"})` | mid-run, optional | ## 4. Process 1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm the Owners summary and any cached findings/trend digests. -2. Call `mcp__opencodehub__risk_trends({repo: "{{ repo }}", window_days: 30})`. Record the per-community / per-file trend slope (`↑ rising`, `→ flat`, `↓ falling`). -3. Call `mcp__opencodehub__list_findings({repo: "{{ repo }}", severity: ">=warn"})`. Group findings by `file_path`; compute `N warn, M error` counts per file. +2. Call `mcp__codehub__risk_trends({repo: "{{ repo }}", window_days: 30})`. Record the per-community / per-file trend slope (`↑ rising`, `→ flat`, `↓ falling`). +3. Call `mcp__codehub__list_findings({repo: "{{ repo }}", severity: ">=warn"})`. Group findings by `file_path`; compute `N warn, M error` counts per file. 4. Combine trend slope + severity into a risk score and rank files. Pick the top 12 for the ranking table; the top 5 feed the drill-down. -5. For each top-12 file: resolve the top owner from `{{ prefetch_path }} § owners` when present, else `mcp__opencodehub__owners({path: })`. Capture percentage share. +5. For each top-12 file: resolve the top owner from `{{ prefetch_path }} § owners` when present, else `mcp__codehub__owners({path: })`. Capture percentage share. 6. Draft the ranked table with columns `File | Trend | Open findings | Top owner | Citation`. Every row cites the file as a backtick `path` with an optional `(N LOC)` suffix; every `Open findings` cell derives from `list_findings` output only. 7. Draft the intro (2 paragraphs): what "risk" means here, how the scoring is composed, the window. If `risk_trends` returned `status: "insufficient_history"`, note the limitation in the intro and drop the Trend column. 8. Draft the `## Per-file drill-down` section. One H3 per top-5 hotspot. Each H3 covers: What's there (2-sentence summary from `context`/`Read`), Recent activity (from `risk_trends`), Owners (top 1-2 with percentage share), Findings (counts by severity, each cited to `list_findings`). @@ -58,11 +58,11 @@ Produce `{{ docs_root }}/analysis/risk-hotspots.md`: a ranked table of the top 1 | Need | Tool | Why | |---|---|---| -| Risk over time | `mcp__opencodehub__risk_trends` | slope + severity, pre-computed | -| Open findings per file | `mcp__opencodehub__list_findings` | grouped by path; merges scanners | -| Contributor share per path | `mcp__opencodehub__owners` | authoritative over git-blame | -| Hotspot context / summary | `mcp__opencodehub__context` | inbound/outbound for the 2-sentence summary | -| Severity framing (optional) | `mcp__opencodehub__verdict` | optional — frames the intro severity | +| Risk over time | `mcp__codehub__risk_trends` | slope + severity, pre-computed | +| Open findings per file | `mcp__codehub__list_findings` | grouped by path; merges scanners | +| Contributor share per path | `mcp__codehub__owners` | authoritative over git-blame | +| Hotspot context / summary | `mcp__codehub__context` | inbound/outbound for the 2-sentence summary | +| Severity framing (optional) | `mcp__codehub__verdict` | optional — frames the intro severity | ## 7. Fallback paths diff --git a/.claude/skills/codehub-document/templates/agents/doc-architecture-data-flow.md b/.claude/skills/codehub-document/templates/agents/doc-architecture-data-flow.md index 23358d5f..4a265795 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-architecture-data-flow.md +++ b/.claude/skills/codehub-document/templates/agents/doc-architecture-data-flow.md @@ -26,9 +26,9 @@ Produce `{{ docs_root }}/architecture/data-flow.md`: a walk of the top 3 process | Shared context | `Read {{ context_path }}` | always first | | Prefetch ledger | `Read {{ prefetch_path }}` | always first | | Top processes | `{{ context_path }} § Top processes` | cached | -| Process entry points | `{{ prefetch_path }} § entry points` or `mcp__opencodehub__sql({query: "SELECT p.name, n.name AS entry_name, n.file_path, n.start_line FROM nodes p JOIN nodes n ON p.entry_point_id = n.id WHERE p.kind='Process'"})` | cached if digest present | -| Symbol neighborhoods along each flow | `mcp__opencodehub__context({symbol: })` | mid-run (only if cache miss) | -| Query grounding for ambiguous steps | `mcp__opencodehub__query({text: "", limit: 10})` | mid-run (only if cache miss) | +| Process entry points | `{{ prefetch_path }} § entry points` or `mcp__codehub__sql({query: "SELECT p.name, n.name AS entry_name, n.file_path, n.start_line FROM nodes p JOIN nodes n ON p.entry_point_id = n.id WHERE p.kind='Process'"})` | cached if digest present | +| Symbol neighborhoods along each flow | `mcp__codehub__context({symbol: })` | mid-run (only if cache miss) | +| Query grounding for ambiguous steps | `mcp__codehub__query({text: "", limit: 10})` | mid-run (only if cache miss) | | Source spans for step citations | `Read ` over `start_line..start_line+20` | mid-run | ## 4. Process @@ -56,8 +56,8 @@ Produce `{{ docs_root }}/architecture/data-flow.md`: a walk of the top 3 process | Need | Tool | Why | |---|---|---| | Process list + entry points | `{{ context_path }} § Top processes` + `{{ prefetch_path }}` | precomputed; do not re-call `sql` | -| Symbol neighborhood for call chain | `mcp__opencodehub__context` | inbound/outbound relations grounded in the graph | -| Concept grounding when a step is ambiguous | `mcp__opencodehub__query` | hybrid BM25+vector, process-grouped | +| Symbol neighborhood for call chain | `mcp__codehub__context` | inbound/outbound relations grounded in the graph | +| Concept grounding when a step is ambiguous | `mcp__codehub__query` | hybrid BM25+vector, process-grouped | | Verifying step text | `Read` at `path:start_line-start_line+20` | avoid paraphrase drift | ## 7. Fallback paths diff --git a/.claude/skills/codehub-document/templates/agents/doc-architecture-module-map.md b/.claude/skills/codehub-document/templates/agents/doc-architecture-module-map.md index 4d6aeffb..066aa698 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-architecture-module-map.md +++ b/.claude/skills/codehub-document/templates/agents/doc-architecture-module-map.md @@ -26,8 +26,8 @@ Produce `{{ docs_root }}/architecture/module-map.md`: one H2 per top module, eac | Shared context | `Read {{ context_path }}` | always first | | Prefetch ledger | `Read {{ prefetch_path }}` | always first | | Top communities | `{{ context_path }} § Top communities` | cached | -| Community member files | `{{ prefetch_path }} § community members` or `mcp__opencodehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='File' AND community_id = ORDER BY file_path"})` | cached if digest present | -| Community relations | `mcp__opencodehub__context({symbol: })` per module | mid-run (only if cache miss) | +| Community member files | `{{ prefetch_path }} § community members` or `mcp__codehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='File' AND community_id = ORDER BY file_path"})` | cached if digest present | +| Community relations | `mcp__codehub__context({symbol: })` per module | mid-run (only if cache miss) | | File LOC | `Read ` then count lines | mid-run | ## 4. Process @@ -56,7 +56,7 @@ Produce `{{ docs_root }}/architecture/module-map.md`: one H2 per top module, eac |---|---|---| | Module list | `{{ context_path }} § Top communities` | precomputed; do not re-call `sql` | | Community member files | `{{ prefetch_path }}` or `sql` over `nodes WHERE kind='File' AND community_id=...` | authoritative member set | -| Module relation counts | `mcp__opencodehub__context` | already cached for top-6 by system-overview packet; reuse digest | +| Module relation counts | `mcp__codehub__context` | already cached for top-6 by system-overview packet; reuse digest | | File LOC | `Read` then line count | graph does not store LOC | ## 7. Fallback paths diff --git a/.claude/skills/codehub-document/templates/agents/doc-architecture-system-overview.md b/.claude/skills/codehub-document/templates/agents/doc-architecture-system-overview.md index 5e6ae069..211d09a2 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-architecture-system-overview.md +++ b/.claude/skills/codehub-document/templates/agents/doc-architecture-system-overview.md @@ -28,13 +28,13 @@ Produce `{{ docs_root }}/architecture/system-overview.md`: a 400–600-word narr | Project profile | `{{ context_path }} § Repo profile` | cached | | Top communities | `{{ context_path }} § Top communities` | cached | | Top processes | `{{ context_path }} § Top processes` | cached | -| External deps | `{{ context_path }} § Stack` or `mcp__opencodehub__dependencies({repo: "{{ repo }}"})` | cached if digest present | -| Module relations | `mcp__opencodehub__context({symbol: })` per top 6 modules | mid-run | +| External deps | `{{ context_path }} § Stack` or `mcp__codehub__dependencies({repo: "{{ repo }}"})` | cached if digest present | +| Module relations | `mcp__codehub__context({symbol: })` per top 6 modules | mid-run | ## 4. Process 1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm `{{ repo }}` profile, top-6 community names, top processes. -2. For each of the top 6 communities (from `.context.md § Top communities`): call `mcp__opencodehub__context({symbol: })` to pull inbound/outbound relation counts. Cache the summary in this packet's Work log. +2. For each of the top 6 communities (from `.context.md § Top communities`): call `mcp__codehub__context({symbol: })` to pull inbound/outbound relation counts. Cache the summary in this packet's Work log. 3. Pull the external dependencies list from `.context.md § Stack` (or call `dependencies` if not cached). Keep the top 15 by usage. 4. Resolve the stack layers by inspecting `project_profile.entry_points` and cross-referencing the top communities with their `file_path` prefixes. 5. Draft the narrative (400–600 words). Structure: paragraph 1 = what the repo does, paragraph 2 = how the pieces fit. @@ -56,7 +56,7 @@ Produce `{{ docs_root }}/architecture/system-overview.md`: a 400–600-word narr | Need | Tool | Why | |---|---|---| | Module list + cohesion | `{{ context_path }} § Top communities` | precomputed; do not re-call `sql` | -| Symbol neighborhood | `mcp__opencodehub__context` | inbound/outbound + cochange counts | +| Symbol neighborhood | `mcp__codehub__context` | inbound/outbound + cochange counts | | External dependency list | `{{ context_path }} § Stack` or `dependencies` | authoritative over grepping manifests | | File line count for `(N LOC)` | `Read` then line count | graph does not store LOC | diff --git a/.claude/skills/codehub-document/templates/agents/doc-behavior-processes.md b/.claude/skills/codehub-document/templates/agents/doc-behavior-processes.md index 38761d52..b7a37082 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-behavior-processes.md +++ b/.claude/skills/codehub-document/templates/agents/doc-behavior-processes.md @@ -28,14 +28,14 @@ Produce `{{ docs_root }}/behavior/processes.md`: one H2 per top process in `{{ r | Top processes | `{{ context_path }} § Top processes` | cached | | Route inventory | `{{ prefetch_path }} § route_map` | cached | | MCP tool inventory | `{{ prefetch_path }} § tool_map` | cached | -| Step sequence per process | `mcp__opencodehub__context({symbol: })` | mid-run | -| Disambiguation lookup | `mcp__opencodehub__query({text: ""})` | mid-run, only on collision | +| Step sequence per process | `mcp__codehub__context({symbol: })` | mid-run | +| Disambiguation lookup | `mcp__codehub__query({text: ""})` | mid-run, only on collision | ## 4. Process 1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm the Top processes list is present; if empty, follow Fallback paths. 2. Select the top 8 processes from `.context.md § Top processes` (ranked by `step_count`). -3. For each of the 8: call `mcp__opencodehub__context({symbol: })` to pull entry point, ordered outbound calls, and handler files. Cache the per-process digest in this packet's Work log. +3. For each of the 8: call `mcp__codehub__context({symbol: })` to pull entry point, ordered outbound calls, and handler files. Cache the per-process digest in this packet's Work log. 4. Group each process by its initiator using the cached `route_map` / `tool_map` digest: HTTP route, MCP tool, CLI command, scheduled job, or internal. 5. Draft `processes.md` with H1 = `{{ repo }} · Processes`. One H2 per process (max 8). Under each H2: a single-line `Entry point: `, a numbered step list where every step cites `path:LOC`, then a `### Related` subsection listing the top 3-6 handler/helper files as backtick citations. 6. Processes with fewer than 3 concrete steps collapse into a trailing `## Minor flows` H2 (one bullet per flow, not an H2 section of their own). @@ -56,16 +56,16 @@ Produce `{{ docs_root }}/behavior/processes.md`: one H2 per top process in `{{ r | Need | Tool | Why | |---|---|---| | Process roster + step counts | `{{ context_path }} § Top processes` | precomputed; do not re-call `sql` | -| Ordered steps per process | `mcp__opencodehub__context` | outbound edges + ordering hints | +| Ordered steps per process | `mcp__codehub__context` | outbound edges + ordering hints | | Initiator attribution | `{{ prefetch_path }} § route_map` / `§ tool_map` | cached inventories | -| Disambiguate colliding names | `mcp__opencodehub__query` | only when two symbols share a name | +| Disambiguate colliding names | `mcp__codehub__query` | only when two symbols share a name | | Recover stale graph | `Grep` the repo | fallback when `context` returns nothing | ## 7. Fallback paths - If a process has fewer than 3 steps in `context`: collapse it into the trailing `## Minor flows` H2 rather than giving it its own section. Cite the collapse in the Work log. -- If `.context.md § Top processes` is empty: fall back to `mcp__opencodehub__sql({query: "SELECT name, file_path, step_count FROM nodes WHERE kind='Process' ORDER BY step_count DESC LIMIT 8"})`. Cite the fallback in the Work log. -- If `mcp__opencodehub__query` for a process name returns nothing (graph out of sync): `Grep` the repo for the name and cite the Grep hits with an inline `*graph stale for this process*` note. +- If `.context.md § Top processes` is empty: fall back to `mcp__codehub__sql({query: "SELECT name, file_path, step_count FROM nodes WHERE kind='Process' ORDER BY step_count DESC LIMIT 8"})`. Cite the fallback in the Work log. +- If `mcp__codehub__query` for a process name returns nothing (graph out of sync): `Grep` the repo for the name and cite the Grep hits with an inline `*graph stale for this process*` note. - If `context` errors on a named process: omit the process's step list, keep the H2 as a stub with `*context unavailable — see Grep fallback*`, and enumerate its handler files from `Grep` hits. ## 8. Success criteria diff --git a/.claude/skills/codehub-document/templates/agents/doc-behavior-state-machines.md b/.claude/skills/codehub-document/templates/agents/doc-behavior-state-machines.md index c31649f1..98510f80 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-behavior-state-machines.md +++ b/.claude/skills/codehub-document/templates/agents/doc-behavior-state-machines.md @@ -27,14 +27,14 @@ Produce `{{ docs_root }}/behavior/state-machines.md`: one H2 per state machine i | Shared context | `Read {{ context_path }}` | always first | | Prefetch ledger | `Read {{ prefetch_path }}` | always first | | State-machine inventory | `{{ context_path }} § State machines` (count + names + paths) | cached | -| State-machine nodes (detail) | `mcp__opencodehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='StateMachine'"})` | mid-run, only if `.context.md` slice is truncated | -| States + transitions per machine | `mcp__opencodehub__context({symbol: })` | mid-run | +| State-machine nodes (detail) | `mcp__codehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='StateMachine'"})` | mid-run, only if `.context.md` slice is truncated | +| States + transitions per machine | `mcp__codehub__context({symbol: })` | mid-run | | Verbatim state/transition text | `Read :` | mid-run | ## 4. Process 1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm `.context.md § State machines` lists ≥ 2 machines. If the slice is truncated, call the `sql` fallback in Section 3. -2. For each state machine: call `mcp__opencodehub__context({symbol: })` to pull states, entry state, transitions, and terminal states. +2. For each state machine: call `mcp__codehub__context({symbol: })` to pull states, entry state, transitions, and terminal states. 3. For each machine: `Read` the definition file at `start_line..start_line+60` to verify state names and transition labels before drawing. Do not invent transitions. 4. Draft `state-machines.md` with H1 = `{{ repo }} · State machines`. One H2 per machine, in alphabetical order by machine name. Under each H2: exactly one fenced Mermaid `stateDiagram-v2` block, then a single-line `Defined at: ` citation. 5. Transitions use the source-level event name as the Mermaid edge label (e.g., `start()`, `complete()`). Do not paraphrase event names. @@ -55,13 +55,13 @@ Produce `{{ docs_root }}/behavior/state-machines.md`: one H2 per state machine i | Need | Tool | Why | |---|---|---| | State-machine roster | `{{ context_path }} § State machines` | precomputed; do not re-call `sql` | -| States + transitions | `mcp__opencodehub__context` | outbound edges encode transitions | +| States + transitions | `mcp__codehub__context` | outbound edges encode transitions | | Verbatim state / event names | `Read` at `file_path:start_line` | graph stores the structure, not the literal text | -| Disambiguate machine names | `mcp__opencodehub__query` | only when two machines share a name | +| Disambiguate machine names | `mcp__codehub__query` | only when two machines share a name | ## 7. Fallback paths -- If `.context.md § State machines` is truncated or absent: call `mcp__opencodehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='StateMachine'"})`. Cite the fallback in the Work log. +- If `.context.md § State machines` is truncated or absent: call `mcp__codehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='StateMachine'"})`. Cite the fallback in the Work log. - If the sql roster returns < 2 machines (the conditional precondition was wrong): write the gap to the Work log, stop, and do not emit an empty or 1-machine file — the orchestrator will prune this packet from the README. - If `context` returns no transitions for a machine: `Read` the definition file at `start_line..start_line+60` and parse the states/transitions manually; mark the machine H2 with `*transitions derived by direct read*` in the Work log. - If a machine has no terminal state in source: draw the diagram without a `--> [*]` edge and note the absence in the Work log (do not invent a terminal state). diff --git a/.claude/skills/codehub-document/templates/agents/doc-cross-repo-contracts-matrix.md b/.claude/skills/codehub-document/templates/agents/doc-cross-repo-contracts-matrix.md index a9285943..63f0c5fb 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-cross-repo-contracts-matrix.md +++ b/.claude/skills/codehub-document/templates/agents/doc-cross-repo-contracts-matrix.md @@ -30,7 +30,7 @@ Produce `{{ group_docs_root }}/cross-repo/contracts-matrix.md`: the N×N produce | Member list + freshness | `{{ group_context_path }} § Members` / `{{ group_prefetch_path }} § group_list,group_status` | cached | | Group contracts (the spine) | `{{ group_prefetch_path }} § group_contracts` | cached | | Per-member route inventory | `{{ group_prefetch_path }} § route_map()` per `{{ member_repos }}` | cached | -| Concept → symbol disambiguation | `mcp__opencodehub__group_query({group: "{{ group }}", text: })` | mid-run, on demand | +| Concept → symbol disambiguation | `mcp__codehub__group_query({group: "{{ group }}", text: })` | mid-run, on demand | ## 4. Process @@ -58,7 +58,7 @@ Produce `{{ group_docs_root }}/cross-repo/contracts-matrix.md`: the N×N produce | Member list + freshness | `{{ group_prefetch_path }} § group_list,group_status` | precondition gate; precomputed | | Contract inventory | `{{ group_prefetch_path }} § group_contracts` | authoritative spine; do not re-call | | Producer file resolution | `{{ group_prefetch_path }} § route_map()` | maps contract `path` → handler `file:LOC` | -| Concept disambiguation | `mcp__opencodehub__group_query` | when a contract's target symbol has multiple matches across the group | +| Concept disambiguation | `mcp__codehub__group_query` | when a contract's target symbol has multiple matches across the group | ## 7. Fallback paths diff --git a/.claude/skills/codehub-document/templates/agents/doc-cross-repo-dependency-flow.md b/.claude/skills/codehub-document/templates/agents/doc-cross-repo-dependency-flow.md index 0dc30a59..e0c56e2e 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-cross-repo-dependency-flow.md +++ b/.claude/skills/codehub-document/templates/agents/doc-cross-repo-dependency-flow.md @@ -30,7 +30,7 @@ Produce `{{ group_docs_root }}/cross-repo/dependency-flow.md`: a single Mermaid | Member list + freshness | `{{ group_context_path }} § Members` / `{{ group_prefetch_path }} § group_list,group_status` | cached | | Group contracts | `{{ group_prefetch_path }} § group_contracts` | cached | | Per-member route inventory | `{{ group_prefetch_path }} § route_map()` per `{{ member_repos }}` | cached | -| Async / event topics | `mcp__opencodehub__group_query({group: "{{ group }}", text: "message consumer"})` or `"publishes"` | mid-run, only if stream edges are suspected | +| Async / event topics | `mcp__codehub__group_query({group: "{{ group }}", text: "message consumer"})` or `"publishes"` | mid-run, only if stream edges are suspected | ## 4. Process @@ -62,7 +62,7 @@ Produce `{{ group_docs_root }}/cross-repo/dependency-flow.md`: a single Mermaid | Member list + freshness | `{{ group_prefetch_path }} § group_list,group_status` | precondition gate; precomputed | | Contract inventory | `{{ group_prefetch_path }} § group_contracts` | authoritative spine; source for every edge | | Producer file resolution | `{{ group_prefetch_path }} § route_map()` | maps contract `path` → handler `file:LOC` for citations | -| Async/stream discovery | `mcp__opencodehub__group_query` with `"message consumer"` / `"publishes"` | only if stream edges are suspected and not cached | +| Async/stream discovery | `mcp__codehub__group_query` with `"message consumer"` / `"publishes"` | only if stream edges are suspected and not cached | | Diagram idioms | `references/mermaid-patterns.md § Cross-repo dependency flow` | canonical `flowchart TB` shape + solid/dashed edge rules | ## 7. Fallback paths diff --git a/.claude/skills/codehub-document/templates/agents/doc-cross-repo-portfolio-map.md b/.claude/skills/codehub-document/templates/agents/doc-cross-repo-portfolio-map.md index 821d2d4b..c5a578c0 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-cross-repo-portfolio-map.md +++ b/.claude/skills/codehub-document/templates/agents/doc-cross-repo-portfolio-map.md @@ -67,7 +67,7 @@ Produce `{{ group_docs_root }}/cross-repo/portfolio-map.md`: a 2-paragraph narra - If `group_contracts` returned zero contracts: keep the diagram with isolated (edge-less) nodes; narrative paragraph 2 becomes a 1-sentence note that the group graph does not currently encode cross-repo edges. Record the fallback in the Work log. - If any member is stale despite Phase 0 checks: abort — do not write `portfolio-map.md`. Instead, write `{{ group_docs_root }}/cross-repo/_stale.md` explaining which repo blocked generation, and stop. -- If `{{ group_context_path }} § Member profiles` lacks a one-liner for a member: call `mcp__opencodehub__project_profile({repo: })` once, extract the summary, cache the digest in Work log, and use it. Do not invent a description. +- If `{{ group_context_path }} § Member profiles` lacks a one-liner for a member: call `mcp__codehub__project_profile({repo: })` once, extract the summary, cache the digest in Work log, and use it. Do not invent a description. ## 8. Success criteria diff --git a/.claude/skills/codehub-document/templates/agents/doc-diagrams-components.md b/.claude/skills/codehub-document/templates/agents/doc-diagrams-components.md index a6d1d8ad..517c3959 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-diagrams-components.md +++ b/.claude/skills/codehub-document/templates/agents/doc-diagrams-components.md @@ -26,15 +26,15 @@ Produce `{{ docs_root }}/diagrams/architecture/components.md`: a single Mermaid | Shared context | `Read {{ context_path }}` | always first | | Prefetch ledger | `Read {{ prefetch_path }}` | always first | | Top communities | `{{ context_path }} § Top communities` | cached | -| Community relations | `{{ prefetch_path }} § sql relations` or `mcp__opencodehub__sql({query: "SELECT source, target, kind FROM relations WHERE kind IN ('CONTAINS','CALLS','IMPORTS') LIMIT 500"})` | cached if digest present; mid-run otherwise | -| Component method list | `mcp__opencodehub__context({symbol: })` per top 8 | mid-run | +| Community relations | `{{ prefetch_path }} § sql relations` or `mcp__codehub__sql({query: "SELECT source, target, kind FROM relations WHERE kind IN ('CONTAINS','CALLS','IMPORTS') LIMIT 500"})` | cached if digest present; mid-run otherwise | +| Component method list | `mcp__codehub__context({symbol: })` per top 8 | mid-run | ## 4. Process 1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm top-8 community names and their file-path roots. -2. Pull the raw edge set from `.prefetch.md § sql relations` (kinds `CONTAINS`, `CALLS`, `IMPORTS`). If not cached, call `mcp__opencodehub__sql` with the query above and cache the digest in this packet's Work log. +2. Pull the raw edge set from `.prefetch.md § sql relations` (kinds `CONTAINS`, `CALLS`, `IMPORTS`). If not cached, call `mcp__codehub__sql` with the query above and cache the digest in this packet's Work log. 3. Project file-level edges down to the community level: collapse every `(source_community, target_community, kind)` triple into a single edge, labeled with a one-word verb (`contains`, `invokes`, `imports`, `depends`). -4. For each of the top 8 communities, call `mcp__opencodehub__context({symbol: })` and select the top 3-5 outbound method names by call count. These populate the `classDiagram` method list for that class. +4. For each of the top 8 communities, call `mcp__codehub__context({symbol: })` and select the top 3-5 outbound method names by call count. These populate the `classDiagram` method list for that class. 5. If the projected graph has > 20 nodes, keep the top-20 by edge count and move the overflow into a `## Legend (overflow)` table with columns `Node | Edges | Reason for elision`. 6. Draft the Mermaid `classDiagram`. Max 8 classes; each class has 3-5 methods; relationships labeled with one-word verbs. 7. `Write {{ docs_root }}/diagrams/architecture/components.md` with H1 = `{{ repo }} · Component view`. @@ -55,7 +55,7 @@ Produce `{{ docs_root }}/diagrams/architecture/components.md`: a single Mermaid |---|---|---| | Community list | `{{ context_path }} § Top communities` | precomputed; do not re-call `sql` | | Edge set | `{{ prefetch_path }} § sql relations` | authoritative; filter to `CONTAINS`/`CALLS`/`IMPORTS` | -| Class method list | `mcp__opencodehub__context` | picks methods by call count | +| Class method list | `mcp__codehub__context` | picks methods by call count | | Diagram idioms | `references/mermaid-patterns.md § Component view` | canonical `classDiagram` shape + rules | ## 7. Fallback paths diff --git a/.claude/skills/codehub-document/templates/agents/doc-diagrams-dependency-graph.md b/.claude/skills/codehub-document/templates/agents/doc-diagrams-dependency-graph.md index 57c62af6..2b629074 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-diagrams-dependency-graph.md +++ b/.claude/skills/codehub-document/templates/agents/doc-diagrams-dependency-graph.md @@ -26,14 +26,14 @@ Produce `{{ docs_root }}/diagrams/structural/dependency-graph.md`: a single Merm | Shared context | `Read {{ context_path }}` | always first | | Prefetch ledger | `Read {{ prefetch_path }}` | always first | | Top communities | `{{ context_path }} § Top communities` | cached | -| Internal edges | `{{ prefetch_path }} § sql relations` or `mcp__opencodehub__sql({query: "SELECT source, target, kind FROM relations WHERE kind IN ('CONTAINS','CALLS','IMPORTS') LIMIT 500"})` | cached if digest present; mid-run otherwise | -| External dependencies | `{{ context_path }} § Stack` or `mcp__opencodehub__dependencies({repo: "{{ repo }}"})` | cached if digest present; mid-run otherwise | +| Internal edges | `{{ prefetch_path }} § sql relations` or `mcp__codehub__sql({query: "SELECT source, target, kind FROM relations WHERE kind IN ('CONTAINS','CALLS','IMPORTS') LIMIT 500"})` | cached if digest present; mid-run otherwise | +| External dependencies | `{{ context_path }} § Stack` or `mcp__codehub__dependencies({repo: "{{ repo }}"})` | cached if digest present; mid-run otherwise | ## 4. Process 1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm the internal community list and the external-dep list. -2. Pull the internal edge set from `.prefetch.md § sql relations`. If not cached, call `mcp__opencodehub__sql` and cache the digest in this packet's Work log. -3. Pull the external-dep list from `.context.md § Stack`. If absent, call `mcp__opencodehub__dependencies({repo: "{{ repo }}"})` and keep the top 15 by usage. +2. Pull the internal edge set from `.prefetch.md § sql relations`. If not cached, call `mcp__codehub__sql` and cache the digest in this packet's Work log. +3. Pull the external-dep list from `.context.md § Stack`. If absent, call `mcp__codehub__dependencies({repo: "{{ repo }}"})` and keep the top 15 by usage. 4. Compose the node set: internal communities (as `name[Label]` plain rectangles) plus the external deps (as `name[(Label)]:::external` parenthesized nodes with a dashed stroke class). Reserve the full 20-node budget; drop lowest-usage externals first when pruning. 5. Compose the edge set: internal→internal edges from the `sql` result collapsed to community level; internal→external edges from the dependency list, sourced at the internal community that imports the dep most often. 6. If node count > 20 after composition: keep the top-20 by edge count, then add a `## Legend (overflow)` table with columns `Node | Edges | Reason for elision`. @@ -58,7 +58,7 @@ Produce `{{ docs_root }}/diagrams/structural/dependency-graph.md`: a single Merm |---|---|---| | Internal node list | `{{ context_path }} § Top communities` | precomputed; do not re-call `sql` for it | | Internal edge set | `{{ prefetch_path }} § sql relations` | authoritative; filter to `CONTAINS`/`CALLS`/`IMPORTS` | -| External leaf nodes | `{{ context_path }} § Stack` or `mcp__opencodehub__dependencies` | do not grep manifests | +| External leaf nodes | `{{ context_path }} § Stack` or `mcp__codehub__dependencies` | do not grep manifests | | Diagram idioms | `references/mermaid-patterns.md § Dependency graph` | canonical `flowchart LR` shape + external-node styling | ## 7. Fallback paths diff --git a/.claude/skills/codehub-document/templates/agents/doc-diagrams-sequences.md b/.claude/skills/codehub-document/templates/agents/doc-diagrams-sequences.md index d2dfd5e3..a80a6041 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-diagrams-sequences.md +++ b/.claude/skills/codehub-document/templates/agents/doc-diagrams-sequences.md @@ -28,14 +28,14 @@ Produce `{{ docs_root }}/diagrams/behavioral/sequences.md`: up to three Mermaid | Shared context | `Read {{ context_path }}` | always first | | Prefetch ledger | `Read {{ prefetch_path }}` | always first | | Top processes (with step counts) | `{{ context_path }} § Top processes` | cached | -| Process step order | `mcp__opencodehub__context({symbol: })` per top 3 processes | mid-run | -| Participant labels | `mcp__opencodehub__query({text: })` when a step's symbol is ambiguous | mid-run, on demand | +| Process step order | `mcp__codehub__context({symbol: })` per top 3 processes | mid-run | +| Participant labels | `mcp__codehub__query({text: })` when a step's symbol is ambiguous | mid-run, on demand | ## 4. Process 1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm which processes in `§ Top processes` have ≥ 3 steps — those are candidates. 2. Pick the top 3 candidates by step count (ties broken by entry-point centrality from `.context.md`). If fewer than 3 qualify, emit only the qualifying count (1 or 2 diagrams). -3. For each chosen process, call `mcp__opencodehub__context({symbol: })` and extract the outbound call sequence in dispatch order. Cache the digest in this packet's Work log. +3. For each chosen process, call `mcp__codehub__context({symbol: })` and extract the outbound call sequence in dispatch order. Cache the digest in this packet's Work log. 4. Derive 4-8 participant lifelines per process by grouping step targets into community / module bands. Lifelines are listed in dispatch order at the top of each `sequenceDiagram`. 5. Draft each `sequenceDiagram`: solid arrows (`->>`) for synchronous calls, dashed (`-->>`) for returns. Short labels (≤ 15 chars on edges, ≤ 20 chars on participant names). 6. If any single diagram exceeds 20 nodes (participants + step-labeled messages), keep the top-20 and move overflow into a `## Legend (overflow)` table below that block. @@ -56,8 +56,8 @@ Produce `{{ docs_root }}/diagrams/behavioral/sequences.md`: up to three Mermaid | Need | Tool | Why | |---|---|---| | Process list + step counts | `{{ context_path }} § Top processes` | precomputed; gates the conditional | -| Outbound call order | `mcp__opencodehub__context` | dispatch sequence for lifelines | -| Actor label disambiguation | `mcp__opencodehub__query` | when a step target has multiple matches | +| Outbound call order | `mcp__codehub__context` | dispatch sequence for lifelines | +| Actor label disambiguation | `mcp__codehub__query` | when a step target has multiple matches | | Diagram idioms | `references/mermaid-patterns.md § Top process` | canonical `sequenceDiagram` shape + rules | ## 7. Fallback paths diff --git a/.claude/skills/codehub-document/templates/agents/doc-reference-cli.md b/.claude/skills/codehub-document/templates/agents/doc-reference-cli.md index 5e5b0da8..03fc3ce6 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-reference-cli.md +++ b/.claude/skills/codehub-document/templates/agents/doc-reference-cli.md @@ -28,8 +28,8 @@ Produce `{{ docs_root }}/reference/cli.md`: one H2 per CLI subcommand (derived f | Shared context | `Read {{ context_path }}` | always first | | Prefetch ledger | `Read {{ prefetch_path }}` | always first | | Project profile (entry points) | `{{ context_path }} § Repo profile` | cached | -| CLI subcommand inventory | `{{ prefetch_path }} § route_map` or `mcp__opencodehub__route_map({repo: "{{ repo }}"})` | cached if digest present | -| Per-command signatures / flags | `mcp__opencodehub__signature({symbol: })` per handler | mid-run (only if cache miss) | +| CLI subcommand inventory | `{{ prefetch_path }} § route_map` or `mcp__codehub__route_map({repo: "{{ repo }}"})` | cached if digest present | +| Per-command signatures / flags | `mcp__codehub__signature({symbol: })` per handler | mid-run (only if cache miss) | | Handler source for flag extraction | `Read ` at `start_line..start_line+40` | mid-run | ## 4. Process @@ -60,8 +60,8 @@ Produce `{{ docs_root }}/reference/cli.md`: one H2 per CLI subcommand (derived f | Need | Tool | Why | |---|---|---| | CLI presence signal | `{{ context_path }} § Repo profile` (`project_profile.entry_points`) | precondition for this packet | -| Subcommand inventory | `mcp__opencodehub__route_map` (cached in `.prefetch.md`) | pre-parsed CLI tree; authoritative over handler grepping | -| Handler signature / flag parser | `mcp__opencodehub__signature` | captures the parameter shape without paraphrase | +| Subcommand inventory | `mcp__codehub__route_map` (cached in `.prefetch.md`) | pre-parsed CLI tree; authoritative over handler grepping | +| Handler signature / flag parser | `mcp__codehub__signature` | captures the parameter shape without paraphrase | | Flag source lines | `Read` at `path:start_line-start_line+40` | graph does not record per-flag line numbers | ## 7. Fallback paths diff --git a/.claude/skills/codehub-document/templates/agents/doc-reference-mcp-tools.md b/.claude/skills/codehub-document/templates/agents/doc-reference-mcp-tools.md index 2db7730a..d1dc3fec 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-reference-mcp-tools.md +++ b/.claude/skills/codehub-document/templates/agents/doc-reference-mcp-tools.md @@ -27,9 +27,9 @@ Produce `{{ docs_root }}/reference/mcp-tools.md`: the authoritative reference fo | Shared context | `Read {{ context_path }}` | always first | | Prefetch ledger | `Read {{ prefetch_path }}` | always first | | MCP tool inventory | `{{ prefetch_path }} § tool_map` | cached | -| Tool handler nodes | `mcp__opencodehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='Function' AND file_path LIKE '%mcp%'"})` | mid-run, only if `tool_map` slice is truncated | +| Tool handler nodes | `mcp__codehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='Function' AND file_path LIKE '%mcp%'"})` | mid-run, only if `tool_map` slice is truncated | | Verbatim signatures | `Read :` (signatures are not stored in the graph) | mid-run | -| Usage count per tool | `mcp__opencodehub__context({symbol: })` | mid-run | +| Usage count per tool | `mcp__codehub__context({symbol: })` | mid-run | ## 4. Process @@ -55,12 +55,12 @@ Produce `{{ docs_root }}/reference/mcp-tools.md`: the authoritative reference fo |---|---|---| | Full tool inventory | `{{ prefetch_path }} § tool_map` | precomputed; do not re-call `tool_map` | | Verbatim signature text | `Read` at `file_path:start_line` | graph stores names/locs, not signature text | -| Handler usage count | `mcp__opencodehub__context` | inbound count; signals which tools are load-bearing | -| Tools not in `tool_map` | `mcp__opencodehub__sql` filtered to MCP files | fallback only when `tool_map` is stale | +| Handler usage count | `mcp__codehub__context` | inbound count; signals which tools are load-bearing | +| Tools not in `tool_map` | `mcp__codehub__sql` filtered to MCP files | fallback only when `tool_map` is stale | ## 7. Fallback paths -- If `{{ prefetch_path }} § tool_map` is empty but `project_profile.stacks` includes `"MCP"`: call `mcp__opencodehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='Function' AND (file_path LIKE '%mcp%' OR file_path LIKE '%tools%') ORDER BY file_path"})`, filter to registered handlers by grepping for tool-registration decorators, and cite the fallback in the Work log. +- If `{{ prefetch_path }} § tool_map` is empty but `project_profile.stacks` includes `"MCP"`: call `mcp__codehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='Function' AND (file_path LIKE '%mcp%' OR file_path LIKE '%tools%') ORDER BY file_path"})`, filter to registered handlers by grepping for tool-registration decorators, and cite the fallback in the Work log. - If `tool_map` returns `[]` and `project_profile.stacks` does not contain `"MCP"`: do not emit an empty file. Write the gap to the Work log, mark `status: COMPLETE` with a note, and skip the Write step — the orchestrator will prune this packet from the README. - If a handler `Read` fails (file moved since the last `codehub analyze`): flag the row with `*graph stale — verify with codehub analyze*` and cite the graph-recorded path. - If a tool registration has no description string: infer from the handler's top-level docstring; mark the H2 body `*description inferred from docstring*` in-line. diff --git a/.claude/skills/codehub-document/templates/agents/doc-reference-public-api.md b/.claude/skills/codehub-document/templates/agents/doc-reference-public-api.md index 0c80b22e..925c24f2 100644 --- a/.claude/skills/codehub-document/templates/agents/doc-reference-public-api.md +++ b/.claude/skills/codehub-document/templates/agents/doc-reference-public-api.md @@ -26,10 +26,10 @@ Produce `{{ docs_root }}/reference/public-api.md`: one H3 per exported symbol fo | Shared context | `Read {{ context_path }}` | always first | | Prefetch ledger | `Read {{ prefetch_path }}` | always first | | Project profile | `{{ context_path }} § Repo profile` | cached | -| Exported symbols (public surface) | `{{ prefetch_path }} § exports` or `mcp__opencodehub__sql({query: "SELECT name, kind, file_path, start_line FROM nodes WHERE kind IN ('Function','Class','Method') AND name NOT LIKE '\\_%' ORDER BY file_path LIMIT 500"})` | cached if digest present | -| Per-symbol signatures | `mcp__opencodehub__signature({symbol: })` | mid-run (only if cache miss) | -| Per-symbol usage count | `mcp__opencodehub__context({symbol: })` | mid-run (only if cache miss) | -| HTTP route inventory | `{{ prefetch_path }} § route_map` or `mcp__opencodehub__route_map({repo: "{{ repo }}"})` | cached if digest present | +| Exported symbols (public surface) | `{{ prefetch_path }} § exports` or `mcp__codehub__sql({query: "SELECT name, kind, file_path, start_line FROM nodes WHERE kind IN ('Function','Class','Method') AND name NOT LIKE '\\_%' ORDER BY file_path LIMIT 500"})` | cached if digest present | +| Per-symbol signatures | `mcp__codehub__signature({symbol: })` | mid-run (only if cache miss) | +| Per-symbol usage count | `mcp__codehub__context({symbol: })` | mid-run (only if cache miss) | +| HTTP route inventory | `{{ prefetch_path }} § route_map` or `mcp__codehub__route_map({repo: "{{ repo }}"})` | cached if digest present | | Source fallback for missing signatures | `Read ` at `start_line..start_line+20` | mid-run | ## 4. Process @@ -60,9 +60,9 @@ Produce `{{ docs_root }}/reference/public-api.md`: one H3 per exported symbol fo | Need | Tool | Why | |---|---|---| | Public-ish symbol surface | `sql` (cached in `.prefetch.md`) | Filter to non-underscore names grouped by barrel | -| Verbatim signatures | `mcp__opencodehub__signature` | authoritative signature text; never paraphrase | -| Usage count / publicness signal | `mcp__opencodehub__context` | inbound count orders the top-30 shortlist | -| HTTP route inventory | `mcp__opencodehub__route_map` | pre-parsed routes; avoids handler-file grepping | +| Verbatim signatures | `mcp__codehub__signature` | authoritative signature text; never paraphrase | +| Usage count / publicness signal | `mcp__codehub__context` | inbound count orders the top-30 shortlist | +| HTTP route inventory | `mcp__codehub__route_map` | pre-parsed routes; avoids handler-file grepping | | Signature fallback | `Read` at `path:start_line-start_line+20` | paste declaration verbatim when `signature` is empty | ## 7. Fallback paths diff --git a/.claude/skills/codehub-onboarding/SKILL.md b/.claude/skills/codehub-onboarding/SKILL.md index bceb9390..8296905a 100644 --- a/.claude/skills/codehub-onboarding/SKILL.md +++ b/.claude/skills/codehub-onboarding/SKILL.md @@ -1,7 +1,7 @@ --- name: codehub-onboarding description: "Use when the user asks for an ONBOARDING, getting-started, or new-engineer guide for the current repo or group. Examples: \"write ONBOARDING.md\", \"generate an onboarding doc for new hires\", \"what should a new engineer read first\". Produces a ranked reading order from `project_profile` + top processes + entry points + owners + centrality. DO NOT use for full architecture books (use `codehub-document`) or PR summaries (use `codehub-pr-description`)." -allowed-tools: "Read, Write, Glob, mcp__opencodehub__project_profile, mcp__opencodehub__query, mcp__opencodehub__context, mcp__opencodehub__route_map, mcp__opencodehub__tool_map, mcp__opencodehub__owners, mcp__opencodehub__sql, mcp__opencodehub__list_repos, Task" +allowed-tools: "Read, Write, Glob, mcp__codehub__project_profile, mcp__codehub__query, mcp__codehub__context, mcp__codehub__route_map, mcp__codehub__tool_map, mcp__codehub__owners, mcp__codehub__sql, mcp__codehub__list_repos, Task" argument-hint: "[output-path] [--committed]" color: green model: sonnet @@ -13,7 +13,7 @@ Produces a single ONBOARDING.md with a ranked reading order drawn from graph cen ## Preconditions -1. `mcp__opencodehub__list_repos` returns the target. If not, emit `Run codehub analyze first — repo is not indexed.` and stop. +1. `mcp__codehub__list_repos` returns the target. If not, emit `Run codehub analyze first — repo is not indexed.` and stop. 2. `codehub status` is fresh. If stale, emit `Run 'codehub analyze' first — index is stale` and stop. (Spec 001 AC-3-1.) ## Arguments @@ -26,12 +26,12 @@ Produces a single ONBOARDING.md with a ranked reading order drawn from graph cen ## Process 1. Run the preconditions. -2. `mcp__opencodehub__project_profile({repo})` — languages, stacks, entry points, 2-sentence summary. -3. `mcp__opencodehub__route_map({repo})` — HTTP surface (if present). -4. `mcp__opencodehub__tool_map({repo})` — MCP/CLI surface (if present). -5. `mcp__opencodehub__sql({query: "SELECT name, file_path, in_degree + out_degree AS centrality FROM nodes WHERE kind IN ('File','Module','Class') ORDER BY centrality DESC LIMIT 15"})` — top-centrality nodes, the "read these first" candidates. -6. For the top 8 of those: `mcp__opencodehub__context({symbol: })` to pull a one-line summary + owners. -7. `mcp__opencodehub__owners({path})` on the top-3 folders by file count — gives the "ask these humans" list. +2. `mcp__codehub__project_profile({repo})` — languages, stacks, entry points, 2-sentence summary. +3. `mcp__codehub__route_map({repo})` — HTTP surface (if present). +4. `mcp__codehub__tool_map({repo})` — MCP/CLI surface (if present). +5. `mcp__codehub__sql({query: "SELECT name, file_path, in_degree + out_degree AS centrality FROM nodes WHERE kind IN ('File','Module','Class') ORDER BY centrality DESC LIMIT 15"})` — top-centrality nodes, the "read these first" candidates. +6. For the top 8 of those: `mcp__codehub__context({symbol: })` to pull a one-line summary + owners. +7. `mcp__codehub__owners({path})` on the top-3 folders by file count — gives the "ask these humans" list. 8. Dispatch a single `Task` with the `doc-onboarding` specialty role (inline in this skill — see `references/onboarding-template.md`). 9. Assemble the output using the template below. 10. `Write` to the resolved output path. diff --git a/.claude/skills/codehub-pr-description/SKILL.md b/.claude/skills/codehub-pr-description/SKILL.md index 118dc930..946cdec4 100644 --- a/.claude/skills/codehub-pr-description/SKILL.md +++ b/.claude/skills/codehub-pr-description/SKILL.md @@ -1,7 +1,7 @@ --- name: codehub-pr-description description: "Use when the user asks for a PR description, a pull request summary, a merge write-up, or a release note for a branch or diff. Examples: \"write the PR description\", \"summarize this branch for review\", \"draft release notes for HEAD\". Calls `detect_changes` + `verdict` + `owners` + `list_findings_delta` and writes Markdown. DO NOT use for open-ended architecture docs (use `codehub-document`) or onboarding guides (use `codehub-onboarding`). DO NOT use when no diff exists — the skill refuses on a clean tree." -allowed-tools: "Read, Write, Bash(git diff:*), Bash(git log:*), Bash(git rev-parse:*), mcp__opencodehub__detect_changes, mcp__opencodehub__verdict, mcp__opencodehub__owners, mcp__opencodehub__impact, mcp__opencodehub__signature, mcp__opencodehub__list_findings_delta, mcp__opencodehub__api_impact" +allowed-tools: "Read, Write, Bash(git diff:*), Bash(git log:*), Bash(git rev-parse:*), mcp__codehub__detect_changes, mcp__codehub__verdict, mcp__codehub__owners, mcp__codehub__impact, mcp__codehub__signature, mcp__codehub__list_findings_delta, mcp__codehub__api_impact" argument-hint: "[--base ] [--head ] [--out ]" color: teal model: sonnet @@ -25,12 +25,12 @@ Generates a Markdown PR body from graph primitives. Linear (no subagents). Sonne ## Process 1. Run the preconditions. On clean tree, refuse and stop. -2. `mcp__opencodehub__detect_changes({base, head})` — map the diff to affected symbols + processes. -3. `mcp__opencodehub__verdict({base, head})` — 5-tier merge recommendation with reasons. -4. `mcp__opencodehub__owners({paths: })` — required reviewers per path. -5. `mcp__opencodehub__list_findings_delta({base, head})` — new/resolved scanner findings in the diff range. -6. For any symbol flagged as tier ≥ 3 by verdict: `mcp__opencodehub__impact({symbol, direction: "downstream", depth: 2})` — spell out who breaks. -7. For public API changes: `mcp__opencodehub__api_impact({route})` when the diff touches a handler. +2. `mcp__codehub__detect_changes({base, head})` — map the diff to affected symbols + processes. +3. `mcp__codehub__verdict({base, head})` — 5-tier merge recommendation with reasons. +4. `mcp__codehub__owners({paths: })` — required reviewers per path. +5. `mcp__codehub__list_findings_delta({base, head})` — new/resolved scanner findings in the diff range. +6. For any symbol flagged as tier ≥ 3 by verdict: `mcp__codehub__impact({symbol, direction: "downstream", depth: 2})` — spell out who breaks. +7. For public API changes: `mcp__codehub__api_impact({route})` when the diff touches a handler. 8. Assemble the Markdown body using the template below. 9. `Write` to ``. @@ -46,7 +46,7 @@ commit messages + the highest-impact change detected. ## Verdict -**Tier —