scip-query 0.10.12 → 0.11.0

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

@@ -0,0 +1,105 @@
+---
+name: scip-claim-audit
+description: Audit output-facing status claims for evidence with scip-query. Use to classify whether an "available", "verified", "safe", "PASS", or "complete" status word is derived from a real check, hedged as a candidate, or merely asserted without being probed.
+commands:
+  - template: "scip-query files <pattern>"
+    when: "Inventory: locate the renderer or status-producing module for a claim."
+  - template: "scip-query refs <symbol>"
+    when: "Classify: find every producer and consumer of a status-bearing function."
+  - template: "scip-query code <symbol>"
+    when: "Classify: read the producing function to see whether it computes or asserts."
+  - template: "scip-query trace <symbol>"
+    when: "Classify: definition plus every reference for a status field or constant."
+  - template: "scip-query capabilities --matrix --json"
+    when: "Spot-check: an already-known example of a fixed derived-status surface."
+---
+
+# scip-claim-audit
+
+Use this skill to find agent-facing claims that sound verified but are not. A status word is **derived** when its producer computes it from a real probe, scan, or computation (a compiler run, a runtime capability probe, a graph traversal). It is **hedged** when the code or its label already says it is a candidate, heuristic, or unverified. It is **asserted** when the value is a constant, a hardcoded table entry, or a string literal presented with the same confidence as a derived value but backed by nothing the code actually checked at that call site. Asserted status words that are agent-facing and trust-bearing (an agent would route a decision — "use this evidence", "skip this check", "delete this" — based on the word) are the highest-severity class this skill exists to find.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query files <pattern>` | Find files matching a pattern | Inventory: locate the renderer or status-producing module for a claim. |
+| `scip-query refs <symbol>` | Find all files referencing a symbol | Classify: find every producer and consumer of a status-bearing function. |
+| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Classify: read the producing function to see whether it computes or asserts. |
+| `scip-query trace <symbol>` | Trace a symbol: definition + all references | Classify: definition plus every reference for a status field or constant. |
+| `scip-query capabilities --matrix --json` | Report which evidence and verification capabilities are available in this project | Spot-check: an already-known example of a fixed derived-status surface. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Rules
+
+1. Ground every claim in the producing function's source, not its label or variable name alone — a variable named `verified` that is never checked against a real result is still asserted.
+2. Classify status, don't just list it: every status word in scope gets exactly one of derived / hedged / asserted.
+3. Severity follows the rubric: asserted + agent-facing + trust-bearing = high; asserted + internal-only or low-consequence = low; hedged is not a finding (the label already discloses uncertainty).
+4. A status that used to be asserted and now calls a real probe is fixed — say so and move on; do not re-report it.
+5. File findings as a table, not prose; a claim → producer → classification → fix format is the deliverable.
+
+## Workflow
+
+### 1. Inventory the status vocabulary
+
+Grep the target scope (a file, module, or command family) for user-visible or JSON-facing status words: `available`, `unavailable`, `partial`, `verified`, `safe`, `PASS`, `FAIL`, `complete`, `derived`, `asserted`. For each hit, note the file:line and the renderer or JSON field that surfaces it to an agent or user.
+
+```bash
+scip-query files <target-file-or-pattern>
+```
+
+This step is complete only when every status-bearing string or field in scope is listed with its surface (human output, `--json` field, or both).
+
+### 2. Classify each producer
+
+For each status word's producing function:
+
+```bash
+scip-query refs <producing-function>
+scip-query code <producing-function>
+scip-query trace <status-field-or-constant>
+```
+
+Read the function body. Classify:
+
+- **Derived**: the status is computed from a probe, scan, spawn result, file check, or graph query performed at or near that call site.
+- **Hedged**: the label, descriptor evidence tier, or surrounding text already marks the value as heuristic, candidate, or unverified.
+- **Asserted**: the value is a literal, a static table lookup, or a branch that returns a fixed status without invoking any check for that specific branch.
+
+This step is complete only when every producer has one of these three labels with the one line of source evidence that justifies it.
+
+### 3. File findings for every asserted status
+
+For each **asserted** status, apply the severity rubric (rule 3) and write:
+
+```markdown
+Claim: <status word and where it appears>
+Producer: <file:line function name>
+Classification: asserted
+Severity: high/low
+Fix: probe it (name the real check to add), generate it (derive from a registry/config that is itself kept honest), or soften the language (hedge the label to match what is actually known)
+```
+
+This step is complete only when every asserted status in scope has a filed finding with a fix direction, and every derived/hedged status is confirmed correct (not silently asserted behind a computed-looking name).
+
+### 4. Report
+
+Write the report under `docs/scip-query/` unless the user asked only for a conversational answer.
+
+```markdown
+Scope:
+Status words inventoried: N
+
+Claim table:
+| Claim | Producer | Classification | Fix |
+| --- | --- | --- | --- |
+
+Fixed since last audit:
+- <claim> — now derived via <probe>, no longer a finding.
+```
+
+The audit is complete only when every status word in scope is classified and every asserted, trust-bearing claim has a filed finding.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Claim Audit"
+  short_description: "Classify output-facing status claims as derived, hedged, or asserted"
+  default_prompt: "Use scip-query to inventory output-facing status words in the target scope, classify each producer as derived, hedged, or asserted, and file findings for asserted trust-bearing claims."

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

@@ -0,0 +1,122 @@
+---
+name: scip-cleanup-audit
+description: Audit and rank scip-query cleanup signals without editing code. Use for health reports, de-bloat reports, recent AI residue audits, score-framed cleanup queues, confirming raw findings, or preparing a cleanup plan.
+commands:
+  - template: "scip-query health --json"
+    when: "Establish evidence: composite score and prioritized action list."
+  - template: "scip-query cleanup-plan --verify --json"
+    when: "Sweep signals: compiler-verified deletion plan, batched."
+  - template: "scip-query duplicate-bodies --json --full"
+    when: "Sweep signals: exact duplicate small-body candidates."
+  - template: "scip-query recent-duplicates --json --full"
+    when: "Sweep signals: recent code that re-implements established code."
+  - template: "scip-query incomplete-migration --json --full"
+    when: "Sweep signals: partially-completed extractions."
+  - template: "scip-query doc-drift --json --full"
+    when: "Sweep signals: stale docs referencing changed code."
+---
+
+# scip-cleanup-audit
+
+Use this skill to turn raw scip-query signals into a confirmed cleanup queue. Do not edit application code in this skill.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query health --json` | Composite codebase health report with prioritized action list | Establish evidence: composite score and prioritized action list. |
+| `scip-query cleanup-plan --verify --json` | Ordered, batched deletion plan: graph-fact dead code plus the cascade candidates it unlocks | Sweep signals: compiler-verified deletion plan, batched. |
+| `scip-query duplicate-bodies --json --full` | Find exact duplicate small-body candidates across files | Sweep signals: exact duplicate small-body candidates. |
+| `scip-query recent-duplicates --json --full` | Directional duplicate candidates: recent code that re-implements established callable, React, or Vue code | Sweep signals: recent code that re-implements established code. |
+| `scip-query incomplete-migration --json --full` | Partially-completed extraction candidates: new helpers in the diff wired into some sites while similar un-migrated sites remain | Sweep signals: partially-completed extractions. |
+| `scip-query doc-drift --json --full` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | Sweep signals: stale docs referencing changed code. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Modes
+
+- Whole-repo audit: rank all cleanup signals.
+- Recent AI residue: focus on echoes, twins, incomplete migrations, speculative params, stale agent-facing docs, and hidden couplings.
+- Score-framed audit: explain health score deductions and the safest first batch.
+
+## Workflow
+
+### 1. Establish evidence
+
+```bash
+scip-query doctor
+scip-query status --capabilities
+scip-query health --json
+scip-query capabilities --json
+scip-query config-validate --json
+```
+
+This step is complete only when unavailable capabilities are recorded as unavailable.
+
+### 2. Sweep signals
+
+Run every relevant class, or record why it is unavailable:
+
+```bash
+scip-query cleanup-plan --verify --json
+scip-query duplicate-bodies --json --full
+scip-query recent-duplicates --json --full
+scip-query incomplete-migration --json --full
+scip-query unused-params --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 frontend repos, add the React or Vue duplicate, hook/composable, and large-component/view commands.
+
+Optional deep-dive (near-zero precision on codebases with intentional layering/ambient types — run only when the sweep above is exhausted, and treat every hit as a lead to confirm, not a finding):
+
+```bash
+scip-query stale-abstractions --json --full
+scip-query wrapper-candidates --json --full
+```
+
+### 3. Confirm candidates
+
+For each high-priority candidate, inspect source and graph evidence:
+
+```bash
+scip-query code <symbol-or-file>
+scip-query refs <symbol>
+scip-query fan-in <symbol>
+scip-query fan-out <symbol-or-file>
+scip-query affected <symbol> --json
+scip-query change-surface <file> --json --full
+scip-query similar <symbolA> <symbolB> --plan
+scip-query co-change <file> --json --full
+```
+
+Classify every candidate as `confirmed fix target`, `intentional design`, `false positive`, or `blocked`.
+
+### 4. Report
+
+```markdown
+Health score: N/100
+
+Confirmed items:
+- [priority] finding - evidence - first safe action
+
+Unconfirmed signals:
+- signal - evidence still needed
+
+Unavailable or blocked checks:
+- check - reason
+
+Recommended first cleanup batch:
+- batch - why safe now
+```
+
+The audit is complete only when each collected signal is classified and the next action is visible.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Cleanup Audit"
+  short_description: "Confirm and rank cleanup, de-bloat, and recent AI residue signals without editing"
+  default_prompt: "Audit scip-query cleanup signals, classify findings with evidence, and report the safest next cleanup batch."

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

@@ -0,0 +1,84 @@
+---
+name: scip-cleanup-improve
+description: Improve scip-query health autonomously with verified cleanup. Use when the user asks to fix cleanup findings, raise health, keep cleaning, continue after setup, or work until no safe confirmed cleanup remains.
+commands:
+  - template: "scip-query health --json"
+    when: "Before editing: report current score and remaining signals."
+  - template: "scip-query cleanup-plan --verify --json"
+    when: "Loop: confirm the next compiler-verified deletion batch."
+  - template: "scip-query cleanup-apply --verified --batch <n>"
+    when: "Loop: apply one verified deletion batch."
+  - template: "scip-query duplicate-bodies --json --full"
+    when: "Priority: exact duplicate small-body echoes to consolidate."
+  - template: "scip-query incomplete-migration --json --full"
+    when: "Priority: un-migrated call sites left behind by a new helper."
+---
+
+# scip-cleanup-improve
+
+Use this skill for bounded autonomous cleanup. The target is not score chasing; the target is fixing confirmed issues that make the codebase harder to understand, verify, or change.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query health --json` | Composite codebase health report with prioritized action list | Before editing: report current score and remaining signals. |
+| `scip-query cleanup-plan --verify --json` | Ordered, batched deletion plan: graph-fact dead code plus the cascade candidates it unlocks | Loop: confirm the next compiler-verified deletion batch. |
+| `scip-query cleanup-apply --verified --batch <n>` | Apply a compiler-verified cleanup-plan batch to the working tree | Loop: apply one verified deletion batch. |
+| `scip-query duplicate-bodies --json --full` | Find exact duplicate small-body candidates across files | Priority: exact duplicate small-body echoes to consolidate. |
+| `scip-query incomplete-migration --json --full` | Partially-completed extraction candidates: new helpers in the diff wired into some sites while similar un-migrated sites remain | Priority: un-migrated call sites left behind by a new helper. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Rules
+
+1. Start with `scip-cleanup-audit` evidence or run the audit sweep yourself.
+2. Report current health and the first confirmed batch before editing.
+3. Prioritize high-confidence, low-blast-radius, clearly verifiable fixes.
+4. Apply one small batch at a time.
+5. After a cleanup pass, run `scip-query health --write-baseline` to snapshot finding identities, then compare with `scip-query health --baseline` at the start of the next pass.
+
+## Priority
+
+1. Compiler-verified 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, passthroughs, stale abstractions, and speculative generality.
+6. Frontend component/hook/composable duplication and large-view pressure.
+7. Directory architecture and maintainability repairs only when evidence is strong and the blast radius is bounded.
+
+## Loop
+
+Before editing:
+
+```markdown
+Health score: N/100
+First confirmed batch:
+- finding - evidence - planned fix - verification
+Remaining signals:
+- signal - status
+```
+
+Then repeat:
+
+1. Apply one verified deletion batch or one small targeted refactor.
+2. Run the narrow project check for touched behavior.
+3. Run `scip-query health --json`.
+4. Invoke `scip-verify`.
+5. If `docs/scip-query/health-dossier.md` exists (or a custom `--dossier-dir` was used), refresh it by rerunning `scip-query setup --json` (add the same `--dossier-dir` if one was used).
+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 user approval.
+
+## Stop
+
+Stop when only intentional, false-positive, blocked, or unconfirmed items remain; when the next improvement needs a product/API/ownership decision; when a missing toolchain prevents trustworthy verification; or when further work would be broad redesign rather than bounded cleanup.
+
+## Closeout
+
+Report starting and final health scores, batches applied, important files changed, verification commands, remaining accepted or blocked items, and highest-value follow-up.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Cleanup Improve"
+  short_description: "Fix confirmed cleanup findings batch by batch with verification"
+  default_prompt: "Improve scip-query health by fixing confirmed cleanup findings one verified batch at a time."

package/skills/scip-concrete-plan/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: scip-concrete-plan
+description: Plan code changes with scip-query evidence and testable design. Use for non-trivial implementation, refactor, migration, API, or bug-fix plans before editing code; require source citations, reuse audit, test seams, side-effect boundaries, contracts, and verification.
+commands:
+  - template: "scip-query status --capabilities"
+    when: "Discover: confirm the index is fresh before citing graph facts."
+  - template: "scip-query plan-context <target>"
+    when: "Discover: anchor the plan with pre-edit context for the target."
+  - template: "scip-query refs <symbol>"
+    when: "Reuse audit: find existing consumers before proposing a new unit."
+  - template: "scip-query code <symbol>"
+    when: "Reuse audit: read source before citing a behavior claim."
+  - template: "scip-query trace <symbol>"
+    when: "Verify the plan: rerun source-producing context for cited targets."
+---
+
+# Concrete Plan
+
+Use this skill to write an implementation plan that another agent can execute without guessing. A concrete plan is a dated Markdown checklist whose code claims come from scip-query evidence and whose design makes the intended behavior easy to test before it is easy to ship.
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you need lookup tips, command families, postchecks, or subagent rules.
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query status --capabilities` | Show index status for this project | Discover: confirm the index is fresh before citing graph facts. |
+| `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | Discover: anchor the plan with pre-edit context for the target. |
+| `scip-query refs <symbol>` | Find all files referencing a symbol | Reuse audit: find existing consumers before proposing a new unit. |
+| `scip-query code <symbol>` | Read the source code for a symbol (bounded to its definition range) | Reuse audit: read source before citing a behavior claim. |
+| `scip-query trace <symbol>` | Trace a symbol: definition + all references | Verify the plan: rerun source-producing context for cited targets. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## Rules
+
+1. Start with `scip-query status --capabilities`; reindex only when freshness is `stale`, `missing`, or `unknown`.
+2. Anchor the plan with `scip-query plan-context <target>`. If the target is not indexed, record that fact and use scip-query for every code-adjacent claim it can answer.
+3. Put the plan in `docs/plans/YYYY-MM-DD-<short-name>.md`.
+4. Every code step includes a `Source` field naming the scip-query command that produced the path, line range, and behavior claim.
+5. Every behavior-changing step includes a testability design: test seam, injected dependencies, pure core, side-effect boundary, and validation.
+6. Do not propose a new helper, wrapper, type, parameter, config flag, component, hook, or module until the reuse audit proves reuse or extension is not the better move.
+
+## Planning Terms
+
+A reuse audit is the part of a plan that proves a proposed new symbol, file, option, wrapper, or contract is needed; what makes it useful is that it ties the new shape to existing definitions, consumers, and rejected extension points.
+
+A test seam is the entry point a test can call to prove a behavior without replaying the whole product path; what makes it valuable in a plan is that it names the exact unit or boundary where correctness will be observed.
+
+A side-effect boundary is the edge where deterministic program decisions meet files, processes, clocks, networks, databases, or other external capabilities; what makes it important is that failures and fakes can be isolated there while core decisions stay easy to test.
+
+A contract is the stable promise one code unit exposes to another, including accepted inputs, returned outputs, errors, timing expectations, and side effects that callers may rely on.
+
+## Workflow
+
+### 1. Discover
+
+Run:
+
+```bash
+scip-query status --capabilities
+scip-query plan-context <target>
+```
+
+Use the shared reference for follow-up commands. Fill three gates before designing:
+
+```markdown
+## Goal
+What the user is trying to accomplish and what done looks like for them.
+
+## Current State
+The affected end-to-end flow, with scip-query citations for entry points, callers, data flow, dependencies, downstream impact, and non-obvious invariants.
+
+## Reuse Audit
+For every new symbol or file being considered: reuse target, extension target, or evidence-backed reason new code is justified.
+```
+
+This step is complete only when the plan can explain the current flow, its consumers, and every proposed new unit's reuse decision with citations.
+
+### 2. Shape for Tests
+
+Before writing implementation phases, add:
+
+```markdown
+## Testability Design
+
+| Behavior | Test seam | Dependencies to inject | Pure core | Side-effect shell | Contract |
+| --- | --- | --- | --- | --- | --- |
+| <behavior> | <test entry point> | <clock/db/http/logger/etc.> | <calculation/decision function> | <I/O wrapper> | <small interface or call shape> |
+```
+
+Plan the code so tests can call the pure core directly and exercise the side-effect shell with injected replacements. Prefer this shape:
+
+1. Parse and validate at the boundary.
+2. Pass domain data and injected dependencies into a small orchestrator.
+3. Put calculations, filtering, selection, formatting decisions, and state transitions in pure functions.
+4. Keep database, network, filesystem, clock, randomness, logging, email, and payment calls in thin side-effect shells.
+5. Depend on small contracts at boundaries; avoid broad option objects, booleans that hide behavior, and wrappers that merely forward.
+
+This step is complete only when every changed behavior has a named test seam and the plan makes clear which logic can be tested without real external services.
+
+### 3. Design the Checklist
+
+Write phases in execution order. Keep each phase deployable or explicitly mark why it is not. Use this step format:
+
+```markdown
+### N.M - Imperative title
+
+- [ ] **File**: `path/to/file.ts:LINE-LINE`
+- **Source**: `scip-query <command>`
+- **What**: Current behavior verified from source.
+- **Change**: Exact edit to make.
+- **Testability**:
+  - Test seam:
+  - Injected dependencies:
+  - Pure core:
+  - Side-effect shell:
+  - Contract:
+- **Validation**: Targeted test, smoke command, or manual check that proves the behavior.
+- **Why**: Why this step is needed and why this order is safe.
+```
+
+This step is complete only when no checklist item says "update this file" without exact current behavior, target behavior, and validation.
+
+### 4. Stress-Test
+
+Apply these lenses to every phase. Add or change steps until each answer is concrete:
+
+| Lens | Plan must answer |
+| --- | --- |
+| Purpose | Why does the current code exist, and what invariant must survive? |
+| Blast radius | Which direct and transitive consumers move with this change? |
+| Valid intermediate state | Would the project still work after only this phase? |
+| Reversibility | Is this a one-way or two-way door, and what rollback exists? |
+| Failure | What happens when I/O, external APIs, malformed data, retries, or crashes occur? |
+| Concurrency | What shared state can be touched twice or out of order? |
+| Boundaries | Who can call this entry point, and where is input validated? |
+| Data integrity | What existing data, generated artifacts, or persisted contracts are affected? |
+| Observability | Can a maintainer diagnose failures from logs/errors without rereading the source? |
+| Human experience | What would surprise, confuse, or block a real user? |
+| Reuse | Does existing code already solve this problem or most of it? |
+| Testability | Are dependencies injectable, logic pure where practical, concerns separated, and contracts small? |
+
+This step is complete only when every discovered gap has either a new plan step or a written reason it is accepted.
+
+### 5. Verify the Plan
+
+Run or delegate phase-by-phase reference checks. Each verifier confirms:
+
+- every path exists;
+- every line range is still within about five lines;
+- every behavior claim matches source;
+- every new unit has reuse evidence;
+- every behavior-changing step has a validation command and testability design.
+
+Then rerun the source-producing context for the cited targets:
+
+```bash
+scip-query plan-context <target>
+```
+
+Use the shared reference for subagent briefing text when delegating.
+
+This step is complete only when stale references are fixed and every phase has a validation path.
+
+## Output Shape
+
+The plan file contains:
+
+1. Title and date.
+2. Goal.
+3. Current State.
+4. Reuse Audit.
+5. Testability Design.
+6. Design Phases.
+7. Stress-Test Findings.
+8. Execution Order and deployable phase notes.
+9. Ship Order with one-way doors flagged.
+10. Summary of files to create, edit, delete, and verify.

package/skills/scip-concrete-plan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Concrete Plan"
+  short_description: "SCIP-grounded implementation plans"
+  default_prompt: "Use $scip-concrete-plan to create a SCIP-grounded implementation plan for this change."

package/skills/scip-conductor/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: scip-conductor
+description: Plan and conduct multi-step engineering programs like a skeptical principal engineer. Use for writing executable multi-phase plans, delegating implementation, reviewing another agent's work, or carrying a large change end to end with verification at every handoff.
+commands:
+  - template: "scip-query plan-context <target>"
+    when: "Anchor each phase's step before delegating it."
+  - template: "scip-query diff-gate --json"
+    when: "Verify a handoff before accepting it and before closing the program."
+  - template: "scip-query health --json"
+    when: "Pre-register or check a program-level health benchmark."
+---
+
+# scip-conductor
+
+This skill is how to run a *program* of work — planning, delegation, review,
+and closure — not how to write one change plan (use a dedicated planning
+skill such as `scip-concrete-plan` for individual changes when one is available).
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+
+<!-- BEGIN GENERATED SKILL COMMANDS -->
+## Commands for this skill
+
+| Command | Purpose | When |
+| --- | --- | --- |
+| `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | Anchor each phase's step before delegating it. |
+| `scip-query diff-gate --json` | Gate the current diff: echo candidates, incomplete migrations, missing co-change partners, unedited twin partners (advisory), uncited doc updates, unused params, new dead symbols; exit 1 on blocking findings | Verify a handoff before accepting it and before closing the program. |
+| `scip-query health --json` | Composite codebase health report with prioritized action list | Pre-register or check a program-level health benchmark. |
+
+Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
+<!-- END GENERATED SKILL COMMANDS -->
+
+## The Three Laws
+
+1. **A green result you have never seen fail is unverified.** Applies to
+   tests, gates, reports from other agents, and your own checks. (Where
+   available, `scip-integrity-audit` is the same law aimed at code.)
+2. **A plan is a contract for a less-capable executor, not a note to self.**
+   If a competent-but-uninspired agent could not execute a step without
+   guessing, the step is not finished being written.
+3. **Nothing is silent.** Every finding, deviation, and shortcut is either
+   fixed or written down with a reason someone else would accept. 0%
+   silent is the invariant; "fixed everything" is not.
+
+## Writing the Plan
+
+- **Goal states what DONE MEANS falsifiably** — a command someone can run
+  and a result they can check, not an aspiration.
+- **Pre-register acceptance benchmarks.** Before any work: measure the
+  current number (test count, timing, finding count, proof line), write it
+  in the plan, and state the target number. Work that cannot move a
+  pre-registered number is scope to question.
+- **Every step carries five fields**: file anchor with verified current
+  behavior (cite how you know); the exact change; the validation command
+  with expected output; testability design (pure core, injected effects);
+  why this step is safe *in this order*. "Update X" with no current/target
+  behavior is a wish, not a step.
+- **Order phases by information gain and risk**: blockers and
+  evidence-integrity first; cheap discriminating probes before expensive
+  builds; measurement before optimization; anything not yet decided by the
+  human is a GATED phase the executor must not start. Infrastructure the
+  later steps inherit (a labeling choke point, a shared helper layer)
+  lands before the features that need it.
+- **Flag one-way doors** with their migration path, and keep an explicit
+  DEFER list so cut scope is visible instead of forgotten.
+- **Include the working agreement**: ONE COMMIT PER STEP (bisectability is
+  non-negotiable; phase-level commits hide which step broke), the exact
+  gate commands — the FULL gate set the repo defines per phase: tests,
+  typecheck, lint/format, and build, not just focused tests (focused tests
+  hide cross-phase regressions; omitting the linter is how red mains ship),
+  regeneration duties,
+  and the deviation protocol —
+  "if source contradicts an anchor, BLOCKED-note it and continue; never
+  improvise silently."
+
+## Conducting the Work
+
+- **Delegate breadth, keep judgment.** Fan out mechanical/scoped work;
+  personally own anything requiring taste, cross-cutting context, or the
+  final word on "is this real."
+- **Concurrent agents get disjoint write scopes**, named in their briefs.
+  If a collision happens anyway: stop racing, apply-verify-commit
+  atomically in one action, and re-sequence to a single writer.
+- **Never accept a report — reproduce its evidence.** On every handoff,
+  choose the *minimal discriminating probe*: the one command most likely to
+  expose the report being wrong (a mutation input, a hand count, the
+  benchmark number), and run it yourself. A report verified by reading it
+  is not verified.
+- **Loop until the gate is quiet**: fix → re-run the discriminating probe →
+  re-run the gate → only then move on. After the program: fold what was
+  learned back into the durable layer (docs, skills, followups) — insight
+  that lives only in the conversation is lost.
+- **Escalate only genuine decision points** — one-way doors, scope changes,
+  taste, spending. Everything else: decide, act, disclose.
+
+## Scar Rules (each bought with a real failure)
+
+- **Verify your verifier.** A gate check that cannot fail is no gate: a
+  lint grep that only matches one linter's output, a diff-gate run on a
+  clean tree, a test suite that skips the new path. Prove the check catches
+  a planted failure once before trusting its green.
+- **Never `git checkout`/`restore`/`stash` on a tree with uncommitted
+  work** — yours or anyone's. Revert probe edits by targeted deletion.
+  If source is lost, check `dist/*.map` sourcesContent before panicking.
+- **Commit working states early and surgically** (explicit paths, never
+  `add -A` on a shared tree); an unbisectable pile of work is a liability.
+- **Make the commit cadence mechanical, not aspirational.** At every step
+  boundary run the arithmetic check: steps completed == commits made. If
+  they differ, stop and commit before touching anything new. "I'll commit
+  when it's all done" is the signature decay of a long or low-effort run —
+  two real executions finished an entire plan with zero or one commit, and
+  both times the deviation was rationalized mid-run, not decided. A
+  self-check that is a count cannot be rationalized.
+- **Watch for your own gate holes**: after any "all green," ask what that
+  check does NOT cover (eslint vs prettier; unit vs integration; clean-tree
+  vacuity).
+
+## Self-Report (required output)
+
+End every conducted program — and every plan written under this skill —
+with a checklist mapping each section above to concrete evidence:
+the pre-registered benchmarks and their before/after values; each handoff's
+discriminating probe and its OBSERVED result (a probe listed but not run
+counts as not run); the deviation ledger; the DEFER list;
+which learnings were folded back and where. A reviewer must be able to
+audit the *conduct*, not just the artifact.
+
+## Completion
+
+The program is complete only when: every pre-registered benchmark met or
+its miss explained; every handoff probe run and recorded; the gate quiet on
+the final state; nothing silent — every finding fixed or ledgered; and the
+self-report written.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Conductor"
+  short_description: "Conduct multi-phase engineering programs"
+  default_prompt: "Use $scip-conductor to plan and conduct this multi-phase program end to end with verified handoffs."