feat: add discovery plugin (explore + research skills)

.claude-plugin/marketplace.json

@@ -144,6 +144,12 @@
       "source": "./plugins/work-items",
       "category": "productivity",
       "tags": ["work-items", "issues", "github", "tracker", "triage", "orchestration", "skill"]
+    },
+    {
+      "name": "discovery",
+      "source": "./plugins/discovery",
+      "category": "development",
+      "tags": ["discovery", "explore", "research", "codebase", "investigation", "sources", "skill"]
     }
   ]
 }

README.md

@@ -43,6 +43,7 @@ Browse and manage with `/plugin`. To refresh after updates: `/plugin marketplace
 | [`firecrawl`](plugins/firecrawl) | Skill | Web scraping, search, crawling, URL discovery, browser interaction, and local file parsing through the `firecrawl-cli` binary — results written to disk and read back selectively to keep large pages out of context, plus a gated maintainer update flow tracking the upstream CLI and skill source. |
 | [`claude-config-audit`](plugins/claude-config-audit) | Skills | Keeps a repo's Claude Code configuration healthy via three report-first audit skills: `settings-audit` (config files vs upstream truth, with live plugin-drift detection), `memory-health` (CLAUDE.md / rules / auto-memory against official-doc criteria), and `automation-deep-dive` (evidence-gated verdicts on automation gaps). |
 | [`work-items`](plugins/work-items) | Skill | Manages GitHub Issues as a development work-item tracker: dashboard, taxonomy-labeled creation, a concurrent-safe hold→verify→claim protocol for multi-agent pickup, recurring-schedule checks, TODO scanning, stale-claim auditing, plan decomposition into vertical slices, and structured triage. |
+| [`discovery`](plugins/discovery) | Skills | Structured discovery before changes. Ships four skills: `/discovery:explore` and `/discovery:explore-deep` (six-dimension codebase exploration, inline or in a forked subagent) plus `/discovery:research` and `/discovery:research-deep` (three-phase multi-source external research with source tiers, falsification, and recency gates). |
 
 Install one: `/plugin install <plugin-name>@melodic-software`.
 

plugins/discovery/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "discovery",
+  "version": "0.1.0",
+  "description": "Structured discovery before changes: explore the local codebase (inline or in an isolated forked subagent) and run disciplined multi-source external research with source tiers, falsification, and recency gates — persisting EXPLORE.md / RESEARCH.md handoff artifacts.",
+  "author": {
+    "name": "Melodic Software",
+    "email": "info@melodicsoftware.com"
+  },
+  "license": "MIT",
+  "keywords": ["discovery", "explore", "research", "codebase", "investigation", "sources", "skill"],
+  "userConfig": {
+    "notes_dir": {
+      "type": "string",
+      "title": "Notes directory",
+      "description": "Project-relative directory where discovery artifacts (EXPLORE.md, RESEARCH.md) are written. A working-notes convention declared in your own project's CLAUDE.md or rules takes precedence.",
+      "default": ".claude/notes"
+    }
+  }
+}

plugins/discovery/README.md

@@ -0,0 +1,49 @@
+# discovery
+
+A Claude Code plugin for **structured discovery before changes** — understand what
+IS (the local codebase) and what SHOULD BE (current external sources) before any
+code is written. Four skills, two axes: local vs external, inline vs isolated.
+
+| Skill | Axis | What it does |
+|---|---|---|
+| `/discovery:explore` | Local, inline | Six-dimension codebase exploration — code reading, git history, project structure, test discovery, build config, environment — plus a `blindspot` mode that surfaces the USER's unknown-unknowns and coaches a better prompt. |
+| `/discovery:explore-deep` | Local, isolated | The same explore workflow in a forked subagent: verbose reads and search output stay in the fork; only a short summary returns, with findings persisted to `EXPLORE.md`. Requires `CLAUDE_CODE_FORK_SUBAGENT=1`. |
+| `/discovery:research` | External, inline | Three chained research phases (broad → targeted + falsification → preferred sources) with per-claim source tiers, independent-corroborator ratios, a recency gate, and a binary outcome gate before presenting. |
+| `/discovery:research-deep` | External, isolated | Dispatcher that routes deep research to the heaviest isolated tier available — a deep-research workflow engine, a forked subagent, or inline as last resort — with a multi-topic check that fans out one agent per separable topic. |
+
+Both inline skills persist handoff artifacts (`EXPLORE.md` / `RESEARCH.md`) so a
+fresh session can resume planning from the artifact alone.
+
+## Works in any repo
+
+- **Self-contained.** The research discipline file (source tiers, recency gates,
+  falsification recipes, failure patterns) and the per-ecosystem discovery
+  reference ship inside the plugin and are referenced via `${CLAUDE_PLUGIN_ROOT}`.
+- **Reads your conventions, assumes none.** Project rules, preferred-source
+  rosters, per-ecosystem source mappings, and any stated direction come from your
+  own project's `CLAUDE.md` and rules; where none exist, the skills self-discover
+  (llms.txt / sitemap probing, canonical-home identification).
+- **Graceful degrade.** Adjacent capabilities — a workflow engine, forked
+  subagents, synthesis MCP servers, documentation agents — are used when present
+  and substituted when absent; no phase blocks on a missing tool, and substitutions
+  are documented as gaps rather than silently lowering the bar.
+
+## Install
+
+```shell
+/plugin marketplace add melodic-software/claude-code-plugins
+/plugin install discovery@melodic-software
+```
+
+## Configuration
+
+One option, prompted at enable time:
+
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `notes_dir` | string | `.claude/notes` | Project-relative directory where discovery artifacts (`EXPLORE.md`, `RESEARCH.md`) are written, one subdirectory per topic. A working-notes convention declared in your own project's `CLAUDE.md` or rules takes precedence. |
+
+## License
+
+MIT (SPDX-License-Identifier: MIT). See the `LICENSE` file at the root of the
+melodic-software/claude-code-plugins repository.

plugins/discovery/skills/explore-deep/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: explore-deep
+description: "Run the full explore workflow in an isolated forked subagent so verbose file reads and search output stay out of the main conversation; only a short summary returns, with findings persisted to an EXPLORE.md artifact. Use for thorough or large-scope investigation (10+ file reads or broad search sweeps); requires CLAUDE_CODE_FORK_SUBAGENT=1 — when unset, fall back to inline /explore or a built-in Explore subagent."
+argument-hint: "[scope] (e.g., /discovery:explore-deep payments module dependencies, /discovery:explore-deep tests, /discovery:explore-deep git)"
+user-invocable: true
+disable-model-invocation: false
+context: fork
+agent: general-purpose
+---
+
+## Pre-computed context
+
+Current branch: !`git branch --show-current 2>/dev/null || echo "unknown"`
+Working tree status: !`git status --porcelain 2>/dev/null | head -20 || echo "clean"`
+Project root: !`git rev-parse --show-toplevel 2>/dev/null || echo "unknown"`
+
+## Purpose
+
+You are a forked **general-purpose** subagent running the canonical explore workflow (the sibling `/explore` skill) on behalf of the main session. Your investigation runs in an isolated context — you do NOT see the parent conversation, and the main session does NOT see your file reads, Glob results, or Grep output; only your final summary returns.
+
+You inherit the parent's full toolset, but this is the **read-only exploration phase**: do NOT Edit source files and do NOT run mutating Bash (no writes/moves/deletes/installs, no git-state changes). The ONLY file you Write is the `EXPLORE.md` artifact in Step 3. Read-only Bash (e.g. `git log`, `git diff`) for the git-history dimension is fine. This read-only boundary is by instruction, not tool-enforced — honor it deliberately.
+
+This is a forked-execution variant of `/explore`: same investigation discipline, cleaner main-session context.
+
+## Step 1 — Load the consuming project's conventions
+
+As a fork you auto-load the project's memory (`CLAUDE.md`), but path-scoped project rules do NOT auto-load in subagent contexts. Before doing scope-relevant work, explicitly Read the consuming project's rule files relevant to `$ARGUMENTS` (its `.claude/rules/` or equivalent — architecture rules, the ecosystem conventions for the file types in scope, testing conventions when scope involves tests). Skip any that don't exist; never invent paths.
+
+**Scope comes exclusively from `$ARGUMENTS`** — a forked skill does not see the parent conversation, so the caller must pass explicit scope in the invocation. If `$ARGUMENTS` is empty, run a general repository-orientation pass (project structure, build configuration, test layout) and state in both the artifact and your return summary that no scope was provided.
+
+## Step 2 — Execute the explore workflow
+
+Follow the sibling `/explore` skill exactly:
+
+- Cover the relevant subset of its 6 exploration dimensions (codebase reading, git history, project structure, test discovery, configuration, environment)
+- Use Glob/Grep/Read aggressively — that's the whole point of running in a fork (the verbose tool calls don't pollute main context)
+- Produce its 7-section output report (summary, current state, existing patterns, test coverage, constraints, planned-direction alignment, open questions)
+
+**Scope**: $ARGUMENTS
+
+## Step 3 — Persist the artifact
+
+**Before writing, run the Outcome gate** the `/explore` workflow defines — the binary artifact self-check, not a "did I explore enough?" recap; any FAIL → fix first.
+
+Write findings to `${user_config.notes_dir}/<topic-slug>/EXPLORE.md` — derive `<topic-slug>` from the exploration scope or current branch name (kebab-case, ≤40 chars). If the consuming project declares its own working-notes convention, that wins over the default location.
+
+**If EXPLORE.md already exists** there for an unrelated task, write a sidecar `explore-<scope-slug>.md` in the same directory instead (kebab-case scope, ≤40 chars) and surface the filename choice in your return summary — the sidecar avoids clobbering prior work.
+
+## Step 4 — Return summary to main session
+
+Your conversation history stays in the fork. Return:
+
+1. A one-paragraph summary (3–5 sentences) of the highest-signal findings
+2. The artifact path
+3. Any blocking open questions the main session must answer before proceeding
+
+Do NOT include the full 7-section report in your return — that's what the artifact is for.