scip-query 0.10.3 → 0.10.4

package/skills/scip-doc-reconcile/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: scip-doc-reconcile
 description: Reconcile standards docs and living documentation with the current code using scip-query doc-drift evidence. Updates descriptive claims, repairs broken file references, and escalates normative violations instead of silently blessing them. Ends with staleness driven to zero.
-allowed-tools: [Bash, Read, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
-keywords: [docs, standards, reconcile, doc-drift, stale-docs, agent-os, spec, documentation, drift, sync]
 ---
 
 # Doc Reconciliation with scip-query
@@ -76,7 +74,7 @@ Then edit the doc:
 
 ```bash
 scip-query doc-drift <doc>     # staleness must drop to 0, broken refs to none
-scip-query diff-gate           # your own doc edits gate clean before commit
+scip-query diff-gate --json    # your own doc edits gate clean before commit
 ```
 
 A doc still showing staleness after your edit means a subject changed in

package/skills/scip-doc-reconcile/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Doc Reconcile"
+  short_description: "Repair docs that drift from code"
+  default_prompt: "Use $scip-doc-reconcile to reconcile this documentation with current SCIP-backed code evidence."

package/skills/scip-explore/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: scip-explore
 description: Deep codebase exploration using scip-query. Trace how any system works end-to-end — call graphs, data flow, dependencies, blast radius — using compiler-resolved analysis. Use when you need to understand how something works before answering questions or making changes.
-allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
-keywords: [explore, understand, trace, investigate, how-does, explain, architecture, flow, debug, navigate, codebase]
 ---
 
 # Codebase Exploration with scip-query
@@ -90,8 +88,10 @@ Start with the high-level map. Run these first:
 
 ```bash
 scip-query stats                      # How big is this codebase?
+scip-query kind-counts                # What symbol kinds dominate?
 scip-query system <module>            # Full module map: files, symbols, deps
 scip-query outline <entry-file>       # What's in the entry point?
+scip-query by-kind function --scope <module>  # Inventory one kind in scope
 ```
 
 **Output:** List all files in the module, the key symbols, what it depends on, and what depends on it. This is your map.
@@ -115,6 +115,7 @@ Understand what the system depends on and who depends on it:
 ```bash
 scip-query deps <file>                # Forward: what does this file need?
 scip-query rdeps <file>               # Reverse: who breaks if this changes?
+scip-query fan-out <file>             # External symbols this file reaches for
 scip-query surface <module>           # True public API (what consumers use)
 scip-query affected <symbol>          # Full transitive blast radius
 ```
@@ -158,6 +159,7 @@ scip-query coupling <file1> <file2>   # How tightly coupled are two files?
 
 ```bash
 scip-query code X                     # Read the source
+scip-query hierarchy X                # Symbol ancestry: method -> class -> module
 scip-query call-graph X               # What it calls, who calls it
 scip-query dataflow X                 # What data flows through it
 scip-query complexity X               # How complex is it
@@ -222,13 +224,17 @@ Every file path, line number, and behavioral claim includes the scip-query comma
 | Read source code | `scip-query code <symbol> [-C N]` |
 | All symbols in a file | `scip-query outline <file>` |
 | Find files | `scip-query files <pattern>` |
+| Symbol kind histogram | `scip-query kind-counts` |
+| Symbols by kind | `scip-query by-kind <kind>` |
 | Full module map | `scip-query system <module>` |
 | True public API | `scip-query surface <module>` |
+| Symbol ancestry | `scip-query hierarchy <symbol>` |
 | Callers + callees | `scip-query call-graph <symbol>` |
 | Every reference | `scip-query refs <symbol>` |
 | Definition + references | `scip-query trace <symbol>` |
 | Forward dependencies | `scip-query deps <file>` |
 | Reverse dependencies | `scip-query rdeps <file>` |
+| External symbol reach | `scip-query fan-out [file]` |
 | Transitive blast radius | `scip-query affected <symbol>` |
 | Pre-change risk briefing | `scip-query change-surface <file>` |
 | Dataflow analysis | `scip-query dataflow <symbol>` |

package/skills/scip-explore/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Explore"
+  short_description: "Trace systems with SCIP evidence"
+  default_prompt: "Use $scip-explore to understand this system end to end with SCIP-backed code evidence."

package/skills/scip-health-audit/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: scip-health-audit
+description: Confirm and prioritize scip-query health signals before cleanup. Use after `scip-query setup`, when reviewing `docs/scip-query/health-dossier.*`, when a user asks for a health audit, issue cleanup, perfect-code pass, setup follow-through, or confirmation of raw scip-query findings before an agent starts fixing them.
+---
+
+# SCIP Health Audit
+
+Use this skill to turn raw scip-query health output into a confirmed cleanup queue.
+
+A health signal is a scip-query reported fact about source code, references, docs, or capability coverage that may indicate maintenance risk. A confirmed issue is a health signal the agent has checked against the current code and SCIP evidence, then classified as a real fix target, an intentional design choice, a false positive, or a blocked investigation.
+
+For autonomous score improvement after this confirmation pass, invoke
+`scip-health-improve`. This skill is the confirmation and ranking pass; the
+improvement skill owns the keep-working cleanup loop.
+
+## Non-Negotiables
+
+1. Start from current evidence. Run `scip-query reindex` when the index is stale, missing, or uncertain.
+2. Do not start cleanup before telling the user the health score and listing the confirmed items that need attention.
+3. Do not call raw analyzer output an issue until you inspect the code or graph evidence that makes it real.
+4. Do not defer confirmed fix targets into vague future work. If the active user request asks for cleanup, start the safest confirmed batch after the visible health report.
+5. Do not use `scip-query setup-ci` in this workflow. CI setup is intentionally outside first-run setup and health cleanup for now.
+
+## Evidence Collection
+
+If setup just ran, read the dossier first:
+
+```bash
+scip-query setup --json
+```
+
+Then collect the current state:
+
+```bash
+scip-query doctor
+scip-query status --capabilities
+scip-query reindex
+scip-query health --json --full
+scip-query diff-gate --json
+scip-query capability-matrix --json
+scip-query config-validate --json
+```
+
+If `doctor`, `status`, or `capability-matrix` reports unavailable capabilities, record them as unavailable checks. Unavailable is not clean; it means this signal class was not proven in this repository.
+
+## Signal Sweep
+
+Run the relevant commands for the repository and scope. Prefer `--json` where supported so the dossier can be updated without scraping prose.
+
+```bash
+scip-query cleanup-plan --verify --json
+scip-query recent-duplicates --json --full
+scip-query incomplete-migration --json --full
+scip-query unused-params --json --full
+scip-query stale-abstractions --json --full
+scip-query wrapper-candidates --json --full
+scip-query passthrough-candidates --json --full
+scip-query dead --json --full
+scip-query isolated --json --full
+scip-query cycles
+scip-query co-change --json --full
+scip-query doc-drift --json --full
+```
+
+For React projects, add:
+
+```bash
+scip-query react-component-duplicates --json --full
+scip-query react-hook-candidates --json --full
+scip-query react-large-component-pressure --json --full
+```
+
+For Vue projects, add:
+
+```bash
+scip-query vue-component-duplicates --json --full
+scip-query vue-composable-candidates --json --full
+scip-query vue-large-view-pressure --json --full
+```
+
+## Confirm Findings
+
+For every candidate that could become a fix target, inspect the relevant code and graph evidence.
+
+Use these probes as needed:
+
+```bash
+scip-query code <symbol-or-file>
+scip-query refs <symbol>
+scip-query fan-in <symbol>
+scip-query fan-out <symbol>
+scip-query affected <symbol> --json
+scip-query change-surface <file> --json --full
+scip-query convergence <symbolA> <symbolB>
+scip-query co-change <file> --json --full
+```
+
+Classify each candidate:
+
+- `confirmed fix target`: the code evidence shows unnecessary code, broken migration, stale docs, accidental duplication, hidden coupling, or another real maintenance burden.
+- `intentional design`: the finding is real but the current shape exists for a documented product, compatibility, performance, API, or ownership reason.
+- `false positive`: the analyzer report contradicts inspected code or graph evidence. Record the analyzer improvement needed.
+- `blocked`: confirmation needs a missing toolchain, missing test command, missing product decision, or unavailable capability.
+
+Use `scip-query suppress <id> --reason "<specific reason>"` only for accepted findings that have stable finding IDs and a durable reason. A suppression is an explicit design record, not a way to hide uncertainty.
+
+## User Handoff Before Cleanup
+
+Before editing application code, send the user a compact report in this order:
+
+```markdown
+Health score: N/100
+
+Confirmed items to address:
+- [priority] <finding> - <evidence command> - <first safe action>
+
+Unconfirmed signals:
+- <signal> - <what evidence is still needed>
+
+Unavailable or blocked checks:
+- <check> - <why it could not be proven>
+
+Recommended first cleanup batch:
+- <batch> - <why this is safe to start now>
+```
+
+If there are no confirmed fix targets, say that clearly and list remaining unconfirmed or unavailable signals.
+
+## Cleanup Order
+
+When the user has asked for cleanup or the current workflow is post-setup cleanup, start after the handoff with the safest confirmed batch:
+
+1. Compiler-verified deletion batches from `scip-query cleanup-plan --verify --json`, applied with `scip-query cleanup-apply --verified --batch <n>`.
+2. Broken or stale docs from `scip-query doc-drift --json --full`.
+3. Incomplete migrations and recent duplicate echoes from `scip-query incomplete-migration --json --full` and `scip-query recent-duplicates --json --full`.
+4. Unused trailing parameters from `scip-query unused-params --json --full`.
+5. Thin wrappers, passthroughs, stale abstractions, and hidden co-change couplings after confirming behavior.
+
+After every batch:
+
+```bash
+scip-query reindex
+scip-query diff-gate --json
+scip-query health --json --full
+```
+
+Update `docs/scip-query/health-dossier.md` and `docs/scip-query/health-dossier.json` when they exist. Preserve raw signals, confirmation status, evidence commands, fixes applied, and remaining blockers.
+
+## Finish Criteria
+
+The audit is complete only when every collected signal is one of:
+
+- fixed and verified;
+- confirmed intentional with a durable reason;
+- recorded as a false positive with analyzer-improvement notes;
+- blocked by a named external constraint or user decision.
+
+End with the final health score, the verification commands run, and the remaining blocked or intentionally accepted items.

package/skills/scip-health-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Health Audit"
+  short_description: "Confirm scip-query health signals before cleanup"
+  default_prompt: "Run a scip-query health audit, show the score and confirmed items first, then begin the safest cleanup batch."

package/skills/scip-health-improve/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: scip-health-improve
+description: Autonomously raise a scip-query repository's health score with verified, bounded cleanup. Use when the user asks to improve, raise, or maximize the health score; clean up as much as reasonable; continue after setup; pursue perfect code; or keep working with minimal interaction until no safe confirmed work remains.
+---
+
+# SCIP Health Improve
+
+Use this skill for an autonomous health-improvement campaign. The target is not
+score chasing: fix confirmed issues that make the codebase harder to understand,
+verify, or change, then stop when the remaining score movement is unsafe,
+unproven, blocked, or not worth the risk.
+
+A confirmed issue is a raw scip-query signal that the agent has checked against
+current code, graph evidence, or repository checks and classified as real,
+intentional, false positive, or blocked.
+
+## Non-Negotiables
+
+1. If the environment supports durable goals and the user asked for autonomous
+   health improvement, create or continue a concrete goal: raise the scip-query
+   health score as high as reasonably possible by fixing confirmed actionable
+   findings while preserving behavior.
+2. Start from current evidence. Run setup first only if the repository has not
+   been bootstrapped; otherwise refresh the index and collect current signals.
+3. Before editing code, tell the user the current health score and the first
+   confirmed batch you will address.
+4. Do not treat raw health output as actionable until you inspect the relevant
+   code, graph, or verification evidence.
+5. Prioritize worst confirmed offenders first: high risk, high confidence, low
+   blast radius, strong expected score movement, and clear verification path.
+6. Keep working batch by batch until no safe confirmed improvement remains, the
+   score stabilizes, or a real external decision blocks progress.
+7. Do not run `scip-query setup-ci` in this workflow. CI setup is intentionally
+   separate until that path is mature.
+
+## Evidence Baseline
+
+Collect the baseline before ranking:
+
+```bash
+scip-query doctor
+scip-query status --capabilities
+scip-query reindex
+scip-query health --json --full
+scip-query diff-gate --json
+scip-query capability-matrix --json
+```
+
+Unavailable capabilities are not clean results. Record them as unproven signal
+classes and fix missing local prerequisites when that is in scope.
+
+## Priority Ladder
+
+Work from the safest, highest-confidence improvements toward broader design
+work:
+
+1. Compiler-verified cleanup-plan deletion batches.
+2. Incomplete migrations and recent duplicate echoes.
+3. Unused params, unused imports, dead symbols, and isolated symbols.
+4. Broken or stale docs, config validation issues, and missing co-change
+   partners.
+5. Thin wrappers, passthrough layers, stale abstractions, and speculative
+   generality.
+6. React or Vue duplicate components, hooks, composables, and large
+   component/view pressure.
+7. Directory architecture and maintainability repairs only when the evidence is
+   strong and the blast radius is bounded.
+
+## Confirmation Sweep
+
+Run the relevant commands for the current repository and scope:
+
+```bash
+scip-query cleanup-plan --verify --json
+scip-query recent-duplicates --json --full
+scip-query incomplete-migration --json --full
+scip-query unused-params --json --full
+scip-query stale-abstractions --json --full
+scip-query wrapper-candidates --json --full
+scip-query passthrough-candidates --json --full
+scip-query doc-drift --json --full
+scip-query co-change --json --full
+```
+
+For frontend projects, add the relevant React or Vue maintainability commands.
+
+Confirm candidates with targeted probes before editing:
+
+```bash
+scip-query code <symbol-or-file>
+scip-query refs <symbol>
+scip-query fan-in <symbol>
+scip-query fan-out <symbol>
+scip-query affected <symbol> --json
+scip-query change-surface <file> --json --full
+scip-query co-change <file> --json --full
+```
+
+## Autonomous Loop
+
+Before the first edit, report:
+
+```markdown
+Health score: N/100
+
+First confirmed batch:
+- <finding> - <evidence> - <planned fix> - <verification>
+
+Remaining notable signals:
+- <signal> - <status: unconfirmed, intentional, false positive, blocked>
+```
+
+Then repeat:
+
+1. Apply one verified deletion batch or one small targeted refactor.
+2. Run the project check that proves the touched behavior.
+3. Run:
+   ```bash
+   scip-query reindex
+   scip-query diff-gate --json
+   scip-query health --json --full
+   ```
+4. Fix new diff-gate findings immediately unless they are documented,
+   intentional, or blocked.
+5. Update `docs/scip-query/health-dossier.md` and
+   `docs/scip-query/health-dossier.json` when they exist.
+6. Pick the next highest-priority confirmed item.
+
+Use `scip-query cleanup-apply --verified --batch <n>` for verified deletion
+batches. Use `--all` only with explicit human approval. Use `--force-dirty`
+only after inspecting the touched files and confirming existing edits are
+unrelated to the cleanup batch.
+
+## Stop Criteria
+
+Stop the campaign when one of these is true:
+
+- the health score stabilizes after a verified batch;
+- only intentional, false-positive, blocked, or unconfirmed items remain;
+- the next improvement requires a product, API, compatibility, or ownership
+  decision from the user;
+- a missing toolchain or unavailable capability prevents trustworthy
+  verification;
+- further work would be broad architectural redesign rather than bounded health
+  improvement.
+
+## Closeout
+
+End with the starting and final health scores, batches applied, important files
+changed, verification commands run, remaining accepted or blocked items, and the
+next highest-value follow-up if one exists.

package/skills/scip-health-improve/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Health Improve"
+  short_description: "Autonomous verified health cleanup"
+  default_prompt: "Use $scip-health-improve to raise this repo health score as high as reasonably possible with verified cleanup."

package/skills/scip-language-playbook/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: scip-language-playbook
 description: Pick the highest-signal scip-query commands for the language in front of you so you can understand a system granularly and find DRY or de-bloat opportunities without wandering through low-signal queries first.
-allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
-keywords: [language, playbook, commands, cheat-sheet, understand, granular, flow, dry, debloat, consolidate, similarity, ts, typescript, python, java, scala, kotlin, rust, cpp, c, ruby, csharp, vb, dart, php]
 ---
 
 # Best scip-query Commands by Language
@@ -26,9 +24,12 @@ Run these in almost every codebase, regardless of language:
 
 ```bash
 scip-query stats
+scip-query kind-counts
 scip-query files <feature-or-module-name>
 scip-query outline <file>
+scip-query by-kind function --scope <feature-or-module-name>
 scip-query trace <symbol>
+scip-query hierarchy <symbol>
 scip-query code <symbol>
 ```
 
@@ -69,7 +70,7 @@ Vue note: `.vue` single-file components are handled by the same path. scip-query
 Use first:
 ```bash
 scip-query outline <file>
-scip-query outline <file>
+scip-query kind-counts --scope <module-or-file>
 scip-query system <module-or-file>
 scip-query imports <file>
 scip-query imported-by <symbol>
@@ -210,7 +211,7 @@ scip-query trace <symbol>
 scip-query call-graph <symbol>
 scip-query refs <symbol>
 scip-query outline <file>
-scip-query outline <file>
+scip-query fan-out <file>
 ```
 
 Skip:
@@ -348,6 +349,8 @@ scip-query extract-candidates
 ```bash
 scip-query files <feature>
 scip-query outline <file>
+scip-query kind-counts --scope <feature>
+scip-query fan-out <file>
 scip-query trace <entry-symbol>
 scip-query call-graph <entry-symbol>
 scip-query code <entry-symbol>

package/skills/scip-language-playbook/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Language Playbook"
+  short_description: "Pick high-signal SCIP commands by language"
+  default_prompt: "Use $scip-language-playbook to choose the best scip-query commands for this language and task."

package/skills/scip-maintainability/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: scip-maintainability
 description: Principled maintainability review using scip-query. Finds hidden policies, scattered concepts, accidental variation, weak boundaries, and system-compression opportunities, then proposes or executes structural improvements and verifies post-change wiring without chasing health scores.
-allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
 ---
 
 # SCIP Maintainability Review
@@ -41,6 +40,11 @@ System compression belongs inside this review. A system compression is a maintai
 
 6. **Prefer small named mechanisms.** Delete, inline, merge, generate, or enforce before adding broad frameworks.
 
+7. **Treat suppressions as accepted design records.** Prefer fixing findings.
+   Use `scip-query suppress <id> --reason "<specific reason>"` only for
+   intentional design, compatibility shims, framework entry points, or accepted
+   false positives. Run `scip-query config-validate` afterward.
+
 ---
 
 ## Core Concepts
@@ -259,8 +263,8 @@ Then run the post-change checks that match what the fix actually did:
 Always finish implemented maintainability work with:
 
 ```bash
-scip-query diff-impact
-scip-query reindex && scip-query diff-gate
+scip-query diff-impact --json
+scip-query reindex && scip-query diff-gate --json
 ```
 
 Treat `diff-gate` findings as unfinished work. Fix them or state a concrete acceptance reason; do not silently report success.

package/skills/scip-maintainability/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Maintainability"
+  short_description: "Review hidden policy and boundaries"
+  default_prompt: "Use $scip-maintainability to find maintainability risks, hidden policies, and weak boundaries with SCIP evidence."

package/skills/scip-query/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: scip-query
 description: Router for codebase work in scip-query-indexed projects. Use whenever exploring, planning, implementing, refactoring, extracting helpers, verifying changes, hunting duplication or bloat, fixing stale docs, or cleaning up after an AI coding session — or when unsure which scip-* skill applies. Picks the right specialist skill and the commands that must run for each phase of work.
-allowed-tools: [Bash, Skill]
 ---
 
 # scip-query Router
@@ -21,26 +20,59 @@ When the user asks you to build, change, or fix something non-trivial:
 1. **Plan first** — invoke `concrete-plan` (every claim in the plan must come
    from a scip-query command, anchored by `scip-query plan-context <target>`).
 2. **Implement** the plan.
-3. **Run the post-checks that match what you did** (table below) — don't wait
-   to be asked.
-4. **Gate before done** — `scip-query reindex && scip-query diff-gate`; fix
-   findings or state explicitly why each is accepted.
+3. **Verify** — invoke `scip-verify`, then run the post-checks that match what
+   you changed (table below).
+4. **Gate before done** — run `scip-query reindex`, then
+   `scip-query diff-gate --json`; fix findings or state explicitly why each is
+   accepted.
 
 ## Route by phase of work
 
-| You are about to... | Invoke | Anchor commands |
-|---|---|---|
-| Understand how something works, trace a system end-to-end | `scip-explore` | `scip-query system <module>`, `scip-query trace <symbol>` |
-| Plan a feature, fix, or refactor | `concrete-plan` | `scip-query plan-context <target>` |
-| Pick high-signal commands for an unfamiliar language | `scip-language-playbook` | — |
-| Verify work you just finished (any implementation, refactor, or extraction) | `scip-verify` | `scip-query reindex && scip-query diff-gate` |
-| Find dead code, duplication, or structural bloat | `scip-debloat` | `scip-query health` |
-| Clean up after AI-assisted coding sessions | `scip-ai-cleanup` | `scip-query recent-duplicates`, `scip-query incomplete-migration` |
-| Reconcile docs/standards that drifted from the code | `scip-doc-reconcile` | `scip-query doc-drift <doc>` |
-| Review or redesign source folder structure and ownership boundaries | `scip-directory-architecture` | `scip-query locality-candidates --json --full`, `scip-query similar-files --full` |
-| Review architecture, hidden policies, weak boundaries beyond folder structure | `scip-maintainability` | `scip-query bottlenecks`, `scip-query coupling` |
-| Review React frontend reuse, components, hooks, or TSX/JSX maintainability | `scip-react-maintainability` | `scip-query react-component-duplicates --full`, `scip-query react-hook-candidates --full` |
-| Review Vue frontend reuse, SFCs, templates, or composables | `scip-vue-maintainability` | `scip-query vue-component-duplicates --full`, `scip-query vue-composable-candidates --full` |
+| You are about to...                                                                                                | Invoke                        | Anchor commands                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Understand how something works, trace a system end-to-end                                                          | `scip-explore`                | `scip-query system <module>`, `scip-query trace <symbol>`                                                   |
+| Debug a bug, regression, failing behavior, or wrong data flow                                                      | `scip-debug`                  | `scip-query trace <symbol>`, `scip-query dataflow <symbol>`, `scip-query change-surface <file>`             |
+| Triage a bug report or issue into evidence and a fix plan                                                          | `scip-triage-issue`           | `scip-query files <term>`, `scip-query trace <symbol>`, `scip-query affected <symbol>`                      |
+| Create a visual explanation, flow map, dependency map, or HTML diagram                                             | `scip-diagram`                | `scip-query call-graph <symbol>`, `scip-query dataflow <symbol>`, `scip-query affected <symbol>`            |
+| Plan a feature, fix, or refactor                                                                                   | `concrete-plan`               | `scip-query plan-context <target>`                                                                          |
+| Assess a public API, route, CLI, config, schema, or boundary change                                                | `scip-api-impact`             | `scip-query surface <module>`, `scip-query affected <symbol>`, `scip-query co-change <file>`                |
+| Pick high-signal commands for an unfamiliar language                                                               | `scip-language-playbook`      | —                                                                                                           |
+| Adopt or bootstrap scip-query in a repository                                                                      | `scip-adoption`               | `scip-query setup --json`, `scip-query check-deps`, `scip-query capability-matrix --json`                   |
+| Verify work you just finished (any implementation, refactor, or extraction)                                        | `scip-verify`                 | `scip-query reindex`, `scip-query diff-gate --json`                                                         |
+| Confirm post-setup health signals before cleanup                                                                   | `scip-health-audit`           | `scip-query health --json --full`, `scip-query diff-gate --json`                                            |
+| Raise the health score as high as reasonably possible with autonomous verified cleanup                             | `scip-health-improve`         | `scip-query health --json --full`, `scip-query cleanup-plan --verify --json`, `scip-query diff-gate --json` |
+| Audit dead code, duplication, unnecessary abstractions, or structural bloat and produce a prioritized cleanup plan | `scip-debloat`                | `scip-query health`                                                                                         |
+| Clean up recent AI-assisted coding rot, copied echoes, incomplete migrations, speculative params, or doc drift     | `scip-ai-cleanup`             | `scip-query recent-duplicates`, `scip-query incomplete-migration`                                           |
+| Reconcile docs/standards that drifted from the code                                                                | `scip-doc-reconcile`          | `scip-query doc-drift <doc>`                                                                                |
+| Review or redesign source folder structure and ownership boundaries                                                | `scip-directory-architecture` | `scip-query locality-candidates --json --full`, `scip-query similar-files --full`                           |
+| Review architecture, hidden policies, weak boundaries beyond folder structure                                      | `scip-maintainability`        | `scip-query bottlenecks`, `scip-query coupling`                                                             |
+| Review React frontend reuse, components, hooks, or TSX/JSX maintainability                                         | `scip-react-maintainability`  | `scip-query react-component-duplicates --full`, `scip-query react-hook-candidates --full`                   |
+| Review Vue frontend reuse, SFCs, templates, or composables                                                         | `scip-vue-maintainability`    | `scip-query vue-component-duplicates --full`, `scip-query vue-composable-candidates --full`                 |
+
+## Tie-break close calls
+
+Use these boundaries before loading a specialist skill:
+
+- `scip-health-audit` confirms, ranks, and reports health signals before code
+  changes. It is the right first step when the user asks "what needs fixing?"
+  or when setup produced a health dossier.
+- `scip-health-improve` is the autonomous campaign. Use it when the user asks
+  to raise/maximize the health score, keep working with minimal interaction, or
+  get the repo as clean as reasonably possible.
+- `scip-debloat` is a bloat audit and cleanup plan. Use it when the user wants
+  dead code, duplication, unnecessary abstractions, wrappers, or structural
+  waste found and prioritized, but has not asked for a score-maxing campaign.
+- `scip-ai-cleanup` is for AI-session residue: recent re-implementations of
+  established code, incomplete helper migrations, speculative parameters,
+  stale docs caused by generated changes, and echo code introduced in the
+  current or recent work.
+- `scip-maintainability` is for deeper design pressure: hidden policies,
+  scattered concepts, weak boundaries, accidental variation, and system
+  compression. Use it when the problem is not just "delete waste" but "make the
+  codebase easier to reason about."
+- `scip-directory-architecture` is only for folder ownership and migration
+  questions. Use it when the user asks where code should live, whether
+  boundaries are mature, or how to reorganize source directories.
 
 Invoke skills by name (Skill tool or slash command). If skill invocation is
 unavailable in this harness, read `~/.agents/skills/<name>/SKILL.md` and
@@ -51,16 +83,16 @@ follow it directly.
 After implementing, run the checks for what the change actually did — every
 row, every time it applies:
 
-| You just... | Run |
-|---|---|
-| Extracted a helper / created an abstraction | `scip-query incomplete-migration` — lists call sites that still hold the logic inline; migrate them or state why they differ |
-| Wrote a brand-new helper or module | `scip-query similar <it>` and `scip-query recent-duplicates` — reuse beats re-implementation; delete the echo |
-| Added parameters, options, or config flags | `scip-query unused-params` — speculative "for later" params must go |
-| Added a forwarding or wrapper layer | `scip-query wrapper-candidates` and `scip-query passthrough-candidates` — indirection must earn its keep |
-| Added an interface, base class, or type alias | `scip-query stale-abstractions` — one real consumer is not an abstraction |
-| Changed a schema, contract, config, or generated file | `scip-query co-change <file>` — update the historical partners or confirm the coupling broke |
-| Changed code that docs describe | `scip-query doc-drift` — update the docs that now lie |
-| Deleted code | `scip-query cleanup-plan --verify` — take the whole cascade with compiler proof |
+| You just...                                           | Run                                                                                                                          |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Extracted a helper / created an abstraction           | `scip-query incomplete-migration` — lists call sites that still hold the logic inline; migrate them or state why they differ |
+| Wrote a brand-new helper or module                    | `scip-query similar <it>` and `scip-query recent-duplicates` — reuse beats re-implementation; delete the echo                |
+| Added parameters, options, or config flags            | `scip-query unused-params` — speculative "for later" params must go                                                          |
+| Added a forwarding or wrapper layer                   | `scip-query wrapper-candidates` and `scip-query passthrough-candidates` — indirection must earn its keep                     |
+| Added an interface, base class, or type alias         | `scip-query stale-abstractions` — one real consumer is not an abstraction                                                    |
+| Changed a schema, contract, config, or generated file | `scip-query co-change <file>` — update the historical partners or confirm the coupling broke                                 |
+| Changed code that docs describe                       | `scip-query doc-drift` — update the docs that now lie                                                                        |
+| Deleted code                                          | `scip-query cleanup-plan --verify` — take the whole cascade with compiler proof                                              |
 
 Confusable detectors (full guide: docs/DETECTOR_GUIDE.md): `unused-params` is
 parameter-level; `passthrough-candidates` = one **callee** (only forwards);
@@ -69,13 +101,22 @@ type-level. `recent-duplicates` = similarity + git age (which copy is the
 echo); `incomplete-migration` = the inverse (the new helper is canonical, the
 old inline copies must go).
 
-**Before declaring any change done** — run `scip-query diff-gate`. Exit 1
+**Before declaring any change done** — run `scip-query diff-gate --json`. Exit 1
 means findings, each with a remediation. Fix them or knowingly accept them
 with a stated reason; never ignore them silently.
 
 ## One-time project setup
 
-If this project has no agent guidance yet, offer to run
-`scip-query setup-agent` — it seeds the AGENTS.md block (every agent reads
-it) and, with `--git-hook`, installs a pre-commit diff gate that fires no
-matter which agent or human wrote the change.
+If this project has not been bootstrapped yet, run `scip-query setup`. It
+installs bundled skills, checks indexer readiness, refreshes the index, runs
+capability and health checks, writes the health dossier, and seeds agent
+guidance. Use `scip-query setup-agent` only when you specifically need to
+refresh AGENTS.md/CLAUDE.md guidance without the full setup pass.
+Use `scip-query setup-hooks --json` to repair the current repository's
+project-local Codex/Claude Code lifecycle hooks.
+After setup, use `scip-health-audit` to confirm and rank raw health signals, or
+`scip-health-improve` when the user wants the agent to raise the score as high
+as reasonably possible with minimal interaction.
+
+Do not use `scip-query setup-ci` as part of first-run setup. The CI workflow is
+intentionally separate until its validation story is mature.

package/skills/scip-query/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Query Router"
+  short_description: "Route codebase work to SCIP skills"
+  default_prompt: "Use $scip-query to choose the right SCIP-backed workflow for this codebase task."