Add repo-surveyor plugin: three staff-level survey lenses

.agents/plugins/marketplace.json

@@ -26,6 +26,17 @@
       },
       "category": "Productivity",
       "keywords": ["context-engineering", "constitution", "claude-md", "governance", "conventions", "behavioral-contract", "token-budget", "context-hygiene", "monorepo", "codebase-analysis"]
+    },
+    {
+      "name": "repo-surveyor",
+      "source": "./plugins/repo-surveyor",
+      "description": "Three staff-level survey lenses that scout a codebase and emit evidence-cited findings: debt-radar triages technical debt (smells, dead code, swallowed errors) with severity, LOE and do-vs-not trade-offs and verifies past findings; feature-gap maps the user-facing surface (UI, MCP tools, CLI, public API) for gaps, inconsistencies, discoverability and product metrics; signal-map recommends surgical log/metric/trace placement for debugging and feature performance. Read-only; invents nothing — every finding cites a path:line.",
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity",
+      "keywords": ["technical-debt", "code-smells", "dead-code", "observability", "instrumentation", "product-analytics", "feature-gaps", "code-review", "codebase-analysis", "severity", "loe", "metrics"]
     }
   ]
 }

.claude-plugin/marketplace.json

@@ -30,6 +30,18 @@
       },
       "license": "MIT",
       "keywords": ["context-engineering", "constitution", "claude-md", "governance", "conventions", "behavioral-contract", "token-budget", "context-hygiene", "monorepo", "codebase-analysis"]
+    },
+    {
+      "name": "repo-surveyor",
+      "displayName": "Repo Surveyor",
+      "source": "./plugins/repo-surveyor",
+      "description": "Three staff-level survey lenses that scout a codebase and emit evidence-cited findings: debt-radar triages technical debt (smells, dead code, swallowed errors) with severity, LOE and do-vs-not trade-offs and verifies past findings; feature-gap maps the user-facing surface (UI, MCP tools, CLI, public API) for gaps, inconsistencies, discoverability and product metrics; signal-map recommends surgical log/metric/trace placement for debugging and feature performance. Read-only; invents nothing — every finding cites a path:line.",
+      "author": {
+        "name": "David Castillo",
+        "email": "davcs86@gmail.com"
+      },
+      "license": "MIT",
+      "keywords": ["technical-debt", "code-smells", "dead-code", "observability", "instrumentation", "product-analytics", "feature-gaps", "code-review", "codebase-analysis", "severity", "loe", "metrics"]
     }
   ]
 }

.cursor-plugin/marketplace.json

@@ -32,6 +32,18 @@
       },
       "license": "MIT",
       "keywords": ["context-engineering", "constitution", "claude-md", "governance", "conventions", "behavioral-contract", "token-budget", "context-hygiene", "monorepo", "codebase-analysis"]
+    },
+    {
+      "name": "repo-surveyor",
+      "displayName": "Repo Surveyor",
+      "source": "./plugins/repo-surveyor",
+      "description": "Three staff-level survey lenses that scout a codebase and emit evidence-cited findings: debt-radar triages technical debt (smells, dead code, swallowed errors) with severity, LOE and do-vs-not trade-offs and verifies past findings; feature-gap maps the user-facing surface (UI, MCP tools, CLI, public API) for gaps, inconsistencies, discoverability and product metrics; signal-map recommends surgical log/metric/trace placement for debugging and feature performance. Read-only; invents nothing — every finding cites a path:line.",
+      "author": {
+        "name": "David Castillo",
+        "email": "davcs86@gmail.com"
+      },
+      "license": "MIT",
+      "keywords": ["technical-debt", "code-smells", "dead-code", "observability", "instrumentation", "product-analytics", "feature-gaps", "code-review", "codebase-analysis", "severity", "loe", "metrics"]
     }
   ]
 }

README.md

@@ -69,6 +69,24 @@ A three-stage pipeline you can enter at any stage.
 > quirks — so it belongs beside the code that can change them, where a breaking change and
 > the skill update it forces ship in the same pull request.
 
+### [`repo-surveyor`](plugins/repo-surveyor/) — survey the codebase, cite everything
+
+Three staff-level lenses that scout a repo and emit evidence-cited findings reports — read-only
+by default, and never a vague "you should refactor": always a `path:line`, a severity, and a
+labeled estimate.
+
+| Skill | Use it when |
+|---|---|
+| **`debt-radar`** | You want the real technical debt found and *triaged* — code smells, dead code, swallowed/silenced errors, brittle patterns — each confirmed with a `path:line`, a severity, a benefit, a T-shirt LOE, and an explicit **do-vs-not-do** trade-off. A `verify` mode re-checks whether a past finding (or a pasted issue) is now resolved against current code — repo-local, no tracker required. |
+| **`feature-gap`** | You want the **user-facing surface** — UI routes, MCP tool schemas, CLI commands, public/exported API — mapped for feature gaps, cross-surface inconsistencies, low-discoverability features, additive feature ideas, and the **product metrics** worth tracking. Static and recommendation-only: it reads the surface, it doesn't measure live traffic. |
+| **`signal-map`** | You want **surgical** observability guidance — the minimum logs/metrics/traces at the maximum-leverage points (error branches, hot paths, feature boundaries) so failures are visible and feature performance is measurable. Each gap cites the `path:line`, the signal type, and the question it answers. |
+
+The two metric-touching lenses split by audience: `feature-gap` recommends *product* metrics (what
+to measure and why), `signal-map` recommends *instrumentation placement* (where in code) — they
+cross-reference rather than overlap. Severity uses the repo's own priority system when one is
+detected, else an Eisenhower → P0–P3 fallback. Ships a runnable [`plugin eval`](plugins/repo-surveyor/evals/)
+regression suite so skill changes can be tested against fixed cases.
+
 ## What you get, concretely
 
 Both context-forge skills were run against this repository, and the results are

plugins/repo-surveyor/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "repo-surveyor",
+  "displayName": "Repo Surveyor",
+  "version": "0.1.0",
+  "description": "A repo-agnostic survey plugin: three staff-level lenses that scout a codebase and emit evidence-cited findings reports, inventing nothing. debt-radar digs technical debt (code smells, dead code, swallowed/silenced errors) with a severity, a T-shirt LOE, benefit, and an explicit do-vs-not trade-off per finding, and can verify whether a past finding is now resolved. feature-gap maps the reachable user-facing surface (UI routes, MCP tool schemas, CLI, public/exported API) for gaps, inconsistencies, low discoverability, recommended features, and the product metrics worth tracking. signal-map recommends surgical log/metric/trace placement at hot paths and error branches for debugging and feature-performance. Read-only by default; every finding cites a path:line, symbol, or commit.",
+  "author": {
+    "name": "David Castillo",
+    "email": "davcs86@gmail.com"
+  },
+  "license": "MIT",
+  "keywords": ["technical-debt", "code-smells", "dead-code", "observability", "instrumentation", "product-analytics", "feature-gaps", "code-review", "codebase-analysis", "severity", "loe", "metrics"]
+}

plugins/repo-surveyor/.codex-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "repo-surveyor",
+  "version": "0.1.0",
+  "description": "A repo-agnostic survey plugin: three staff-level lenses that scout a codebase and emit evidence-cited findings reports, inventing nothing. debt-radar digs technical debt (code smells, dead code, swallowed/silenced errors) with a severity, a T-shirt LOE, benefit, and an explicit do-vs-not trade-off per finding, and can verify whether a past finding is now resolved. feature-gap maps the reachable user-facing surface (UI routes, MCP tool schemas, CLI, public/exported API) for gaps, inconsistencies, low discoverability, recommended features, and the product metrics worth tracking. signal-map recommends surgical log/metric/trace placement at hot paths and error branches for debugging and feature-performance. Read-only by default; every finding cites a path:line, symbol, or commit.",
+  "author": {
+    "name": "David Castillo",
+    "email": "davcs86@gmail.com"
+  },
+  "license": "MIT",
+  "keywords": ["technical-debt", "code-smells", "dead-code", "observability", "instrumentation", "product-analytics", "feature-gaps", "code-review", "codebase-analysis", "severity", "loe", "metrics"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Repo Surveyor",
+    "shortDescription": "Survey a repo across three staff lenses — debt, product gaps, observability — with cited findings.",
+    "category": "Productivity"
+  }
+}

plugins/repo-surveyor/.cursor-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "repo-surveyor",
+  "displayName": "Repo Surveyor",
+  "version": "0.1.0",
+  "description": "A repo-agnostic survey plugin: three staff-level lenses that scout a codebase and emit evidence-cited findings reports, inventing nothing. debt-radar digs technical debt (code smells, dead code, swallowed/silenced errors) with a severity, a T-shirt LOE, benefit, and an explicit do-vs-not trade-off per finding, and can verify whether a past finding is now resolved. feature-gap maps the reachable user-facing surface (UI routes, MCP tool schemas, CLI, public/exported API) for gaps, inconsistencies, low discoverability, recommended features, and the product metrics worth tracking. signal-map recommends surgical log/metric/trace placement at hot paths and error branches for debugging and feature-performance. Read-only by default; every finding cites a path:line, symbol, or commit.",
+  "author": {
+    "name": "David Castillo",
+    "email": "davcs86@gmail.com"
+  },
+  "license": "MIT",
+  "keywords": ["technical-debt", "code-smells", "dead-code", "observability", "instrumentation", "product-analytics", "feature-gaps", "code-review", "codebase-analysis", "severity", "loe", "metrics"]
+}

plugins/repo-surveyor/.gitignore

@@ -0,0 +1,2 @@
+# claude plugin eval writes run artifacts here
+evals/results/

plugins/repo-surveyor/README.md

@@ -0,0 +1,59 @@
+# repo-surveyor
+
+Three staff-level **survey** lenses that scout a codebase and emit **evidence-cited findings
+reports** — never a vague "you should refactor," always a `path:line` + severity + a labeled
+estimate. Read-only by default; each skill writes only its own findings artifact. Published to
+**Claude Code**, **Cursor**, and **Codex** from one shared component tree.
+
+```shell
+/plugin marketplace add davcs86/agent-plugins
+/plugin install repo-surveyor@davcs86-agent-plugins
+```
+
+## The three lenses
+
+| Skill | Persona | Use it when |
+|---|---|---|
+| **`debt-radar`** | Staff software architect | You want the real technical debt found and *triaged* — code smells, dead code, swallowed/silenced errors, brittle patterns — each confirmed with a `path:line`, a severity, a benefit, a T-shirt LOE, and an explicit **do-vs-not-do** trade-off. A `verify` mode re-checks whether a past finding (or a free-text issue) is now resolved against the current code. |
+| **`feature-gap`** | Product-manager × engineer hybrid | You want the **user-facing surface** (UI routes, MCP tool schemas, CLI commands, public/exported API) analyzed for feature gaps, cross-surface inconsistencies, low-discoverability features, additive feature ideas, and the **product metrics** worth tracking per feature. Static and recommendation-only — it maps the surface, it does not measure live traffic. |
+| **`signal-map`** | Observability × data-science hybrid | You want **surgical** instrumentation guidance — the minimum logs/metrics/traces at the maximum-leverage points (error branches, hot paths, feature boundaries) so failures are visible and feature performance is measurable. Cites the exact `path:line`, the signal type, and the question each signal answers. |
+
+## What every finding guarantees
+
+Every report is governed by a shared **Floor / Norms** discipline (`RS-*` / `RS-N*`):
+
+- **Nothing is invented (RS-1).** The *existence* of a defect, gap, or blind spot cites concrete
+  evidence — a `path:line`, a symbol, a config key, or a commit. An ungrounded suspicion lands
+  under `## Needs confirmation`, phrased as a question, never asserted.
+- **Estimates are labeled, not disguised (RS-4).** LOE, benefit, and impact are ordinal T-shirt
+  estimates with stated assumptions — the defect is cited, the estimate is flagged as a
+  projection.
+- **Trade-offs run both ways (RS-N3).** Every recommendation states the cost of doing it *and* the
+  cost of not doing it.
+- **Ranked by leverage (RS-N2).** Within a severity, findings sort by impact ÷ LOE, so you act
+  top-down.
+- **Read-only by default (RS-2).** A survey writes only its findings artifact under the configured
+  output dir; it never mutates your source.
+
+## Severity
+
+Each finding carries a severity. On the first run in a repo the skill **detects the repo's own
+priority system** (issue-template labels, `CONTRIBUTING`, existing `P0`/`S1`/`sev*` conventions)
+and uses it. Absent one, it falls back to an **Eisenhower (urgent × important) → P0–P3** mapping —
+see `skills/*/reference/severity-rubric.md`.
+
+## Config
+
+All three skills share one committable config, `.agents/repo-surveyor.json` at the repo root.
+On the first run (when it is absent) the skill asks where findings should be written —
+`.repo-surveyor/`, `./docs/repo-surveyor/`, or an existing docs directory it detects — and stores
+the choice. `outputDir: null` is scratch mode: findings are presented inline and nothing is
+written.
+
+## Development
+
+```shell
+# structural integrity of this plugin (manifests, frontmatter, shared-copy parity, subagents)
+python3 plugins/repo-surveyor/scripts/validate.py
+python3 plugins/repo-surveyor/scripts/validate.py --self-test
+```

plugins/repo-surveyor/agents/debt-scout.md

@@ -0,0 +1,104 @@
+---
+name: debt-scout
+description: Read-only technical-debt scout for the debt-radar (repo-surveyor) skill. Given a scoped set of source paths and the detected stack, it classifies code into debt-radar's seven categories — swallowed/silenced errors, dead code, code smells/anti-patterns, brittle/over-specified logic, duplication, contradiction-with-intent, and latent risk — grounding every suspected item in content-anchored evidence (path:line plus the quoted snippet or symbol), and proposing a severity. It reports leads for the orchestrator to confirm; it never asserts a verdict it cannot ground, never reads beyond its scope's relevance, and never writes. Advisory only — the orchestrator re-verifies and is the sole writer.
+tools: Glob, Grep, Read
+model: inherit
+readonly: true
+---
+
+You are the **debt scout** for the `/debt-radar` (repo-surveyor) skill. You read *source code* and
+return a compact, evidence-cited digest of suspected technical debt for the orchestrator to
+confirm. You are advisory: you locate and quote; you never write, and you never get the last word
+— every lead you return is re-verified by the orchestrator before it becomes a finding. The
+orchestrator's context window is the resource you protect: **distill, do not dump.**
+
+## Scope (hard boundaries)
+
+- **Read only the paths you are given** (plus whatever you must grep across the tree to test a
+  reference). Never write. You have `Glob, Grep, Read` only.
+- **Return leads, not conclusions.** Your job is to surface grounded suspicions with their
+  evidence; the orchestrator confirms dead-code refs, reads handlers, and assigns final verdicts.
+- **Never paste file bodies.** One line per lead. Prefer a dozen sharp leads over a hundred shallow
+  ones (**RS-N8**).
+
+## The seven categories (what to look for, and the evidence each needs)
+
+A lead is worth returning only when you can cite what makes it one (**RS-1**):
+
+1. **Swallowed / silenced errors** *(highest signal)* — an empty or comment-only catch/except; a
+   discarded error return (`_ = err`, unawaited/ignored promise rejection, `except: pass`); an
+   unjustified suppression on real logic (`# noqa`, `// eslint-disable-next-line`, `@ts-ignore`,
+   `# type: ignore`, `#[allow(...)]`). Cite the handler/line. A handler that logs or re-raises, or
+   a documented deliberate ignore, is **not** a lead.
+2. **Dead code** — an export/function/branch/file/flag that *looks* unreferenced. Grep the symbol
+   in your scope; if you find no use, return it as a lead **and say so** ("grep in scope: 0 refs")
+   — but flag if it is exported/public or reachable by dynamic dispatch, because the orchestrator
+   must grep the whole tree and rule those out. Never assert dead yourself.
+3. **Code smells / anti-patterns** — god function/file (give the measured line count), deep nesting
+   (give the depth), long parameter lists, copy-paste blocks, primitive obsession, leaky
+   abstraction, wrong-way boundary crossing. Cite the span and the measured shape.
+4. **Brittle / over-specified logic** — a long if-else / hard-coded enumeration a heuristic or
+   data-driven form would replace; quote enough to show the enumeration.
+5. **Duplication** — the same logic in ≥2 places; cite every site so the orchestrator can confirm
+   they match and must change together.
+6. **Contradiction with intent** — code that disagrees with an adjacent comment/docstring/type.
+   Cite both the code line and the asserting line. Mark ⚠ security if it touches
+   authz/authn/secret/tenant.
+7. **Latent risk** — TODO/FIXME/HACK on a load-bearing path, `sleep`-based synchronization,
+   unbounded resource/loop, swallowed timeout. Cite the site.
+
+Anything you suspect but cannot ground → `## Needs confirmation`, phrased as the check that would
+confirm it. Never inflate a lead into a verdict.
+
+## Method
+
+1. **Map the scope.** Glob the paths; note the languages so you recognize each language's
+   swallow/suppress idioms and its dispatch conventions.
+2. **Grep the high-signal patterns first.** Error-swallowing and suppression directives are
+   greppable across the scope — start there; they pay the most.
+3. **Read the dense/central files** the smells cluster in; measure shapes (line counts, nesting)
+   rather than asserting them.
+4. **Test references in scope** for dead-code leads; always mark exported/dynamic candidates for
+   the orchestrator's whole-tree check.
+5. **Propose a severity** per lead from `severity-rubric.md`'s scale (the orchestrator finalizes
+   it), and note anything security-adjacent with ⚠.
+6. **Distill.** One line per lead: `path:line` · category · quoted/anchored evidence · proposed
+   severity. No file bodies.
+
+## Output format (always)
+
+```
+## Scope surveyed
+- `<path glob(s)>` — <languages/frameworks noted> — <N files read>
+
+## Swallowed / silenced errors
+- `path:NN` — "<quoted handler/suppression>" (`<symbol>`) — proposed <severity> [⚠ security?]
+- (or "none")
+
+## Dead code (leads — orchestrator must confirm across whole tree)
+- `path:NN` — `<symbol>` — grep in scope: 0 refs; [exported/public? | dynamic-dispatch possible?] — proposed <severity>
+- (or "none")
+
+## Code smells / anti-patterns
+- `path:NN–MM` — <measured shape, e.g. 1,900-line file / nesting depth 7> — proposed <severity>
+- (or "none")
+
+## Brittle / over-specified logic
+- `path:NN–MM` — "<enumeration/hard-coded branches>" — proposed <severity>
+- (or "none")
+
+## Duplication
+- `pathA:NN`, `pathB:MM` <(+ more)> — same logic — proposed <severity>
+- (or "none")
+
+## Contradiction with intent
+- [⚠ security?] `path:NN` code does "<Y>"; `path:MM` <comment/type> asserts "<X>" — proposed <severity>
+- (or "none")
+
+## Latent risk
+- `path:NN` — "<TODO on load-bearing path / sleep-sync / unbounded resource>" — proposed <severity>
+- (or "none")
+
+## Needs confirmation
+- `path:NN` — suspected <category>; would confirm: <the check> | "none"
+```