Add /craftsman:discover requirements interview (0.10.0)

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "craftsman",
       "source": "./craftsman-plugin",
       "description": "Agent-discipline toolkit: portable agent set plus skills enforcing minimal-diff coding, root-cause debugging, recurring-bug detection via graphify, environment-quirk memory, and an ask-before-writing project scaffolder",
-      "version": "0.9.0",
+      "version": "0.10.0",
       "license": "MIT",
       "author": {
         "name": "bufferbrew",

.github/PULL_REQUEST_TEMPLATE.md

@@ -10,7 +10,7 @@
 
 <!-- What you ran and what you saw. Paste the relevant output — a claim without
      evidence is not a verification. Example:
-     `claude plugin validate --strict ./craftsman-plugin` → "Validation passed" (14 agents, 8 skills, 5 commands, 2 hook events)
+     `claude plugin validate --strict ./craftsman-plugin` → "Validation passed" (15 agents, 8 skills, 7 commands, 4 hook events)
      CI green on the linked commit. -->
 
 **Checklist**

CHANGELOG.md

@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Version numbers track `.claude-plugin/plugin.json` (kept in sync with the root
 `marketplace.json`).
 
+## [0.10.0] - 2026-07-26
+
+### Added
+- `/craftsman:discover <vague idea>`: a requirements-discovery interview that turns an
+  underspecified request into a numbered, testable spec. It exists because the shallow end of
+  `ideation-first` was the only option — 3–5 questions and a three-line brief, with no way to invoke
+  it deliberately, so a substantially open request ("build a notifications system") got the same
+  treatment as a merely fuzzy one.
+
+  The work is split across two surfaces because of a hard constraint: **a subagent cannot conduct an
+  interview.** It receives one cold prompt and returns one result, which is why `orchestrator` already
+  has to bounce underspecified features back to its caller. So the interview runs in the main thread
+  as a command, and only the half a subagent is genuinely good at — reading the codebase — is
+  delegated.
+- `requirements-analyst` agent (read-only: Read/Glob/Grep, Opus): drafts the clarifying questions a
+  request leaves unanswered, grounded in prior art and existing abstractions rather than a generic
+  checklist. Every question carries a `file:line` or an explicit "gap" label, plus an assumption
+  default so the interview never stalls on a declined question; questions the code already settles
+  come back as *constraints* instead. Capped at 10–20 questions — past that, it is asking things the
+  codebase already answers. It never asks the user anything itself and never writes files.
+
+### Changed
+- `ideation-first`: now runs at two depths. **Quick** is unchanged and still the default (3–5
+  questions, one per turn, Scope brief). **Deep** grounds 10–20 questions in the analyst's dossier and
+  asks them in **3–4 sequenced rounds of 2–4 questions** via `AskUserQuestion` — a deliberate
+  divergence from the one-question-per-turn rule, which is right for five questions and punishing for
+  fifteen. What the rule actually protects is that later questions adapt to earlier answers, and
+  sequenced *rounds* preserve that; batching all fifteen at once does not.
+
+  Deep mode ends by writing a numbered requirements spec (`R1`, `R2`, … each with an acceptance
+  criterion, so `tester` and `reviewer` can trace coverage back to a requirement) at
+  `docs/requirements/<slug>.md` — proposed, shown in full, and written only on confirmation, per the
+  same ask-before-writing rule `/craftsman:init` follows. The **Scope brief** is still emitted inline
+  at both depths and remains the machine handoff the planner and the orchestrator's ideation gate
+  consume; the spec file is additive, and the brief gained a `Spec:` line pointing at it.
+
+  New explicit rule: **expand the questions, bound the scope.** Deep mode raises error states, empty
+  states, migration, and offline behavior — then still recommends the smallest build that satisfies
+  the request, with everything surfaced but unagreed recorded under Out of scope. A deep interview
+  that ends with a *bigger* scope than a quick one has failed; it should end with the same scope, held
+  with more confidence and a longer out-of-scope list. Without this, deep mode would have quietly
+  contradicted `smallest-change-first`.
+- `orchestrator`: the ideation gate now accepts either an inline Scope brief or a path to a
+  requirements spec, and instructs the planner to read the spec when one is named. Availability table
+  gains `requirements-analyst`.
+- `/craftsman:orchestrate`: the ideation-gate step routes substantially open requests to deep mode
+  rather than a three-line brief.
+- `userpromptsubmit-task-router`: the feature-shaped nudge names `/craftsman:discover` for
+  substantially open requests. Still one nudge per prompt; no new `case` branch.
+
+### Fixed
+- `session-start` announced "Seven skills" and "Five commands" — both already wrong before this
+  release (8 and 6), and both invisible to CI: the count validator skips any line containing
+  "commands" when checking skills, and only matches the literal phrase "N slash commands" for
+  commands. The whole reminder is a single line, so both slipped through every check. The skill list
+  was also missing `ui-craft` and the command list was missing `/craftsman:orchestrate` — a session
+  therefore started without being told two components existed.
+
 ## [0.9.0] - 2026-07-25
 
 ### Added

README.md

@@ -13,7 +13,7 @@
 
 **craftsman** makes engineering discipline the default in [Claude Code](https://code.claude.com):
 the smallest correct change, no fix without a root cause, and an honest report of what was
-actually verified. It bundles fourteen agents, eight skills, six slash commands, and a cross-platform
+actually verified. It bundles fifteen agents, eight skills, seven slash commands, and a cross-platform
 hook system — installable in two commands.
 
 <p align="center">

craftsman-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "craftsman",
   "description": "Agent-discipline toolkit: a portable agent set plus skills enforcing minimal-diff coding, root-cause debugging, recurring-bug detection via graphify, environment-quirk memory, and an ask-before-writing project scaffolder",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "author": {
     "name": "bufferbrew",
     "email": "bufferbrew@gmail.com"

craftsman-plugin/README.md

@@ -12,8 +12,8 @@
 </p>
 
 A Claude Code plugin that makes engineering discipline the default: the smallest correct change,
-no fix without a root cause, and an honest report of what was actually verified. Fourteen agents, eight
-skills, six slash commands, and a cross-platform hook system.
+no fix without a root cause, and an honest report of what was actually verified. Fifteen agents, eight
+skills, seven slash commands, and a cross-platform hook system.
 
 ## Why craftsman
 
@@ -51,11 +51,12 @@ Worked examples in [docs/use-cases.md](../docs/use-cases.md); contributions welc
 ```
 craftsman-plugin/
 ├── .claude-plugin/plugin.json    Plugin manifest
-├── agents/                       Fourteen agents (see Agents reference)
+├── agents/                       Fifteen agents (see Agents reference)
 ├── skills/                       Eight skills (see Skills reference)
 ├── commands/
 │   ├── init.md                   /craftsman:init — project scaffolder
 │   ├── orchestrate.md            /craftsman:orchestrate — full pipeline, end to end
+│   ├── discover.md               /craftsman:discover — requirements interview → numbered spec
 │   ├── quick.md                  /craftsman:quick — small-change fast path
 │   ├── doctor.md                 /craftsman:doctor — install health check (--fix to remediate)
 │   ├── review.md                 /craftsman:review — direct reviewer routing
@@ -111,7 +112,7 @@ Or from inside a session: `/plugin marketplace add bufferBrew/craftsman` then
 `/plugin install craftsman@craftsman`.
 
 Restart Claude Code (or start a new session) after installing. Verify with `claude plugin list`
-and inspect the loaded components with `claude plugin details craftsman` — it should report 14 agents. Claude Code counts commands as skills in the plugin details output: 8 skill files + 6 command files = 14 under the skills heading, and 4 hook events
+and inspect the loaded components with `claude plugin details craftsman` — it should report 15 agents. Claude Code counts commands as skills in the plugin details output: 8 skill files + 7 command files = 15 under the skills heading, and 4 hook events
 (SessionStart, UserPromptSubmit, PreToolUse, Stop). Only SessionStart has an always-on cost (roughly 1.2k tokens per session); the other three are event-driven and inject a short nudge only when a real signal matches — no idle cost.
 
 ### Option C — install from a local marketplace checkout
@@ -181,6 +182,34 @@ and the ideation gate needs interactive Q&A, which the main thread can hold and
 `@craftsman:orchestrator <task>` still works and is the right choice when you want the pipeline run
 in its own context.
 
+### `/craftsman:discover <vague idea>`
+
+Turns an idea that isn't specified well enough to plan into a numbered, testable requirements spec.
+Runs the `ideation-first` skill's **deep mode**:
+
+1. Dispatches the read-only `requirements-analyst`, which reads the codebase and drafts the questions
+   the request leaves unanswered — each grounded in a `file:line` or labelled an explicit gap, with an
+   assumption default so the interview never stalls. Questions the code already answers come back as
+   *constraints*, not questions.
+2. Interviews you in the main thread: 3–4 sequenced rounds of 2–4 related questions, via
+   `AskUserQuestion` so each is a click rather than an essay. Rounds are sequenced — purpose and scope,
+   then behavior and integration, then acceptance criteria — so later questions adapt to earlier
+   answers.
+3. Proposes a spec at `docs/requirements/<slug>.md` (redirectable), shows the full content, and writes
+   only on confirmation. Every requirement is numbered `R1`, `R2`, … with an acceptance criterion, so
+   `tester` and `reviewer` can trace coverage back to a requirement.
+4. Emits the `ideation-first` **Scope brief** inline as well — that block, not the spec file, is what
+   `planner` and the orchestrator's ideation gate consume.
+
+The interview runs in the main thread by necessity: a subagent gets one cold prompt and returns one
+result, so it cannot hold a conversation. Only the question-drafting half is delegated. Use plain
+`ideation-first` (3–5 questions, scope brief, no file) when the request is merely fuzzy rather than
+substantially open — deep mode on a small feature is ceremony.
+
+**It expands the questions, not the scope.** The interview deliberately raises error states, empty
+states, migration, and offline behavior — then still recommends the smallest build that satisfies the
+request. Everything surfaced but not agreed lands under **Out of scope**, recorded rather than built.
+
 ### `/craftsman:quick <description of the small change>`
 
 Fast path for genuinely small, well-understood edits — typo fixes, one-line logic changes, small
@@ -205,6 +234,7 @@ Invoke any agent with `@craftsman:<name> <task>` — plugin agents are namespace
 | Agent | Model | Writes files? | Use for |
 |---|---|---|---|
 | `orchestrator` | Opus | No (delegates) | Any multi-step task; picks the smallest pipeline, enforces gates, max 2 repairs per gate, structured report |
+| `requirements-analyst` | Opus | No | Drafting the clarifying questions an underspecified request leaves open — grounded in prior art and `file:line` evidence, with an assumption default each. Returns a question dossier for a main-thread interviewer; asks the user nothing itself. Normally reached via `/craftsman:discover` |
 | `planner` | Haiku | No | Decomposing a feature/bug into ordered steps before coding |
 | `coder` | Opus | Yes | The implementation itself — minimal diff, runs the build, asks before adding anything extra |
 | `ui-designer` | Opus | Yes | UI-flavored implementation — detects the UI framework (Compose, Flutter, React, SwiftUI, web), applies design-system tokens, a11y, responsive layout per the `ui-craft` skill; minimal diff, runs the build |
@@ -223,7 +253,9 @@ Invoke any agent with `@craftsman:<name> <task>` — plugin agents are namespace
 
 - `quick` → `coder` alone
 - `feature` → *ideation gate* (if underspecified, main-thread `ideation-first` skill produces a
-  scope brief first) → `researcher?` → `planner` → `coder` → `tester` → `reviewer` → `docs-writer?`
+  scope brief first — or `/craftsman:discover` a full spec, via `requirements-analyst`, when the
+  request is substantially open) → `researcher?` → `planner` → `coder` → `tester` → `reviewer` →
+  `docs-writer?`
 - `bugfix` → `debugger` (read-only root-cause 4-phase method + quirks/KNOWN_ISSUES/graphify; hands
   off fix location + repro recipe) → `coder` → `tester` → `reviewer`
 - UI-flavored `feature`/`bugfix`/`quick` (screens, components, styling, layout) → same pipeline
@@ -242,7 +274,7 @@ directly.
 
 | Skill | When it applies |
 |---|---|
-| `ideation-first` | Before planning a new feature or greenfield refactor whose requirements aren't pinned down. Asks 3–5 clarifying questions one at a time, then emits a **Scope brief** (Goal / In scope / Out of scope / Key decisions / Open questions) the planner builds on. Skipped for well-specified requests, `quick`, and `bugfix`. Runs in the main thread (interactive). `/craftsman:orchestrate` runs it directly; the `@craftsman:orchestrator` subagent gates on the brief's presence rather than running it itself. |
+| `ideation-first` | Before planning a new feature or greenfield refactor whose requirements aren't pinned down. Two depths: **quick** (default) asks 3–5 questions one at a time and emits a **Scope brief** (Goal / In scope / Out of scope / Key decisions / Open questions); **deep** (`/craftsman:discover`) grounds 10–20 questions in a `requirements-analyst` dossier, asks them in 3–4 sequenced rounds, and writes a numbered requirements spec — still emitting the brief, which stays the machine handoff. Expands the *questions*, not the scope: extra findings land in Out of scope. Skipped for well-specified requests, `quick`, and `bugfix`. Runs in the main thread (interactive). `/craftsman:orchestrate` runs it directly; the `@craftsman:orchestrator` subagent gates on the brief's presence rather than running it itself. |
 | `smallest-change-first` | Before writing any new code/file/dependency. Seven-step ladder: needs to exist? → already in codebase? → stdlib? → platform feature? → existing dependency? → one line? → only then write the minimum. Source of the "ask before anything extra" rule. |
 | `logging-tradeoffs` | When taking a deliberate shortcut, investigating a possibly-logged bug, or resolving an entry. Defines the `KNOWN_ISSUES.md` format: what changed / ceiling / upgrade trigger / status. |
 | `environment-memory` | Before retrying anything that failed once; after discovering an OS/shell/tool quirk. Reads/appends `~/.claude/craftsman-memory/environment-quirks.md`. |

craftsman-plugin/agents/orchestrator.md

@@ -109,11 +109,13 @@ researcher (only if APIs, libraries, or MCP-server coverage are unknown)
   → docs-writer (only if public API surface changed)
 ```
 **Ideation gate (before planner):** if the request is underspecified — goal, boundaries, or
-success criteria open to interpretation — and no **Scope brief** was supplied in your invocation,
-**stop**. You are a subagent and cannot hold the interactive Q&A this needs. Instruct the caller to
-run the `ideation-first` skill in the main thread first, then re-invoke you with the resulting scope
-brief. Do **not** dispatch the planner against guesses. When a scope brief *is* present (or the
-request is already well-specified), proceed and pass the brief into the planner's prompt verbatim.
+success criteria open to interpretation — and neither a **Scope brief** nor a path to a requirements
+spec was supplied in your invocation, **stop**. You are a subagent and cannot hold the interactive
+Q&A this needs. Instruct the caller to run the `ideation-first` skill in the main thread first (or
+`/craftsman:discover` for a substantially open request, which produces a numbered spec), then
+re-invoke you with the resulting scope brief. Do **not** dispatch the planner against guesses. When a
+brief *is* present (or the request is already well-specified), proceed and pass the brief into the
+planner's prompt verbatim; if it names a spec file, tell the planner to read that path too.
 
 **bugfix**
 ```
@@ -232,7 +234,7 @@ ran did not verify anything. Never infer a passing build from an agent's confide
 
 | Agent | Gate — must pass before proceeding |
 |---|---|
-| `ideation-first` (feature/greenfield refactor) | A **Scope brief** is present — either supplied in your invocation or produced by the main-thread skill — before the planner runs. If the request is underspecified and no brief exists, do not proceed; bounce back per the ideation gate. Well-specified requests pass this trivially. |
+| `ideation-first` (feature/greenfield refactor) | A **Scope brief** is present — either supplied in your invocation or produced by the main-thread skill — before the planner runs, or the invocation names a requirements spec file the planner can read. If the request is underspecified and neither exists, do not proceed; bounce back per the ideation gate. Well-specified requests pass this trivially. |
 | `planner` | Output contains numbered steps and at least one "Files to change" entry. |
 | `debugger` | Root cause is stated in one sentence, the failure was reproduced (fresh output shown), and the hand-off names a fix location + failing-test spec. Read-only — it does not apply the fix. |
 | `coder` / `ui-designer` | Build passes — the project's declared build/verify command succeeds, AND the report shows fresh command output, not just a claim (verification-before-completion — no completion claim without evidence run in this session). |
@@ -325,6 +327,7 @@ Read this before building any pipeline. Do not use agents marked "unavailable".
 ### Available — have .md files in this plugin's `agents/` directory
 | Agent | Role | Read-only? |
 |---|---|---|
+| `requirements-analyst` | Drafts codebase-grounded clarifying questions for an underspecified request; returns a question dossier, asks the user nothing | Yes |
 | `planner` | Decomposes tasks into ordered steps | Yes |
 | `debugger` | Root-cause diagnosis: reproduce, trace, hand off fix location + repro recipe | Yes (+ Bash to reproduce) |
 | `coder` | Minimal-diff implementation, runs build | No |