|
| 1 | +# DSO NextJS Starter: Plugin Install Consent Design |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This document investigates whether placing `extraKnownMarketplaces` and `enabledPlugins` in a |
| 6 | +project's `.claude/settings.json` will trigger a consent/install dialog when a developer first |
| 7 | +opens the project in Claude Code — enabling the DSO plugin to be auto-installed without any |
| 8 | +manual `claude plugin install` step. |
| 9 | + |
| 10 | +The use case is the **DSO NextJS Starter template**: a scaffolded project that ships with a |
| 11 | +pre-populated `.claude/settings.json` pointing to the DSO plugin marketplace. The question is |
| 12 | +whether a first-time user who clones the template and runs `claude` will be automatically |
| 13 | +prompted to install the DSO plugin. |
| 14 | + |
| 15 | +--- |
| 16 | + |
| 17 | +## Research Findings |
| 18 | + |
| 19 | +### Official Documentation (code.claude.com/docs/en/settings — April 2026) |
| 20 | + |
| 21 | +The authoritative Claude Code settings reference describes `extraKnownMarketplaces` behavior |
| 22 | +under **Plugin settings**: |
| 23 | + |
| 24 | +> **When a repository includes `extraKnownMarketplaces`**: |
| 25 | +> 1. Team members are prompted to install the marketplace when they trust the folder |
| 26 | +> 2. Team members are then prompted to install plugins from that marketplace |
| 27 | +> 3. Users can skip unwanted marketplaces or plugins (stored in user settings) |
| 28 | +> 4. Installation respects trust boundaries and requires explicit consent |
| 29 | +
|
| 30 | +This is a two-step flow: marketplace registration consent, then plugin install consent. Both are |
| 31 | +interactive prompts that appear at the workspace trust moment. |
| 32 | + |
| 33 | +### GitHub Issue #13097: Interactive-Only Constraint |
| 34 | + |
| 35 | +Issue [#13097](https://github.com/anthropics/claude-code/issues/13097) ("Clarify that |
| 36 | +extraKnownMarketplaces requires interactive trust dialog") documents that: |
| 37 | + |
| 38 | +- The `extraKnownMarketplaces` feature **only activates during interactive mode** |
| 39 | +- In headless/print mode (`-p` flag), the trust dialog is skipped entirely and |
| 40 | + `extraKnownMarketplaces` is not processed |
| 41 | +- This is intentional: consent requires a human at the keyboard |
| 42 | + |
| 43 | +An independent investigation (gist linked in the issue) confirmed: |
| 44 | + |
| 45 | +> "Two separate systems exist: project-level `extraKnownMarketplaces` (ignored by plugin |
| 46 | +> commands) and user-level `known_marketplaces.json` (actually consulted). The auto-installation |
| 47 | +> bridge between them only engages during the interactive trust moment." |
| 48 | +
|
| 49 | +This means the mechanism works in the exact scenario we care about — a developer running |
| 50 | +`claude` interactively in a newly cloned repo — and does not apply to CI or headless runs. |
| 51 | + |
| 52 | +### GitHub Issue #32607: Silent Failure for Uninstalled Enabled Plugins |
| 53 | + |
| 54 | +Issue [#32607](https://github.com/anthropics/claude-code/issues/32607) ("No warning when |
| 55 | +enabledPlugins references a plugin that is not installed") identifies a current gap: |
| 56 | + |
| 57 | +- If `enabledPlugins` lists a plugin but the user skips installation or the marketplace prompt |
| 58 | + doesn't fire, Claude Code **silently does nothing** — no error, no warning |
| 59 | +- Users see `Unknown skill: dso:sprint` with no diagnostic path |
| 60 | + |
| 61 | +This does not affect the primary consent flow (which does present a prompt), but it matters |
| 62 | +for the degraded-path experience documented below. |
| 63 | + |
| 64 | +### GitHub Issue #23737: Auto-Install Feature Request |
| 65 | + |
| 66 | +Issue [#23737](https://github.com/anthropics/claude-code/issues/23737) ("Auto-install plugins |
| 67 | +from enabledPlugins in shared settings.json") was filed requesting fully automatic installation |
| 68 | +without a consent prompt. It was **closed as a duplicate** of an existing open feature request. |
| 69 | + |
| 70 | +Key implication: as of April 2026, fully silent auto-install (no dialog at all) is **not |
| 71 | +implemented**. The consent prompt approach documented in the official docs is the current |
| 72 | +mechanism. |
| 73 | + |
| 74 | +### Platform Consistency Note |
| 75 | + |
| 76 | +Issue [#32268](https://github.com/anthropics/claude-code/issues/32268) documents that the |
| 77 | +official Anthropic marketplace (`claude-plugins-official`) is pre-registered on macOS but |
| 78 | +**not** on Windows. For a custom DSO marketplace, `extraKnownMarketplaces` registration is |
| 79 | +required on all platforms, making the `.claude/settings.json` approach consistently necessary |
| 80 | +regardless of OS. |
| 81 | + |
| 82 | +--- |
| 83 | + |
| 84 | +## Success Path |
| 85 | + |
| 86 | +**When `extraKnownMarketplaces` + `enabledPlugins` is used in project settings:** |
| 87 | + |
| 88 | +A developer clones the DSO NextJS Starter and runs `claude` in interactive mode: |
| 89 | + |
| 90 | +1. Claude Code detects a new (untrusted) project directory and presents the workspace trust dialog |
| 91 | +2. Developer selects "Yes, proceed" (trust the folder) |
| 92 | +3. Claude Code reads `.claude/settings.json`, finds `extraKnownMarketplaces` pointing to the |
| 93 | + DSO plugin marketplace |
| 94 | +4. A second prompt appears: "This project recommends the [DSO] marketplace — install it?" |
| 95 | +5. Developer confirms; the marketplace catalog is fetched |
| 96 | +6. A third prompt (or sequential continuation) appears for each plugin listed in |
| 97 | + `enabledPlugins`: "Install [digital-service-orchestra]?" |
| 98 | +7. Developer confirms; the DSO plugin installs and is available immediately |
| 99 | + |
| 100 | +The user experience is a guided sequence of two or three consent dialogs, not a manual |
| 101 | +`claude plugin install` invocation. From the developer's perspective, opening a new project |
| 102 | +*just works* after clicking through the prompts. |
| 103 | + |
| 104 | +**Limitations of this path:** |
| 105 | + |
| 106 | +- Requires interactive mode — the prompts do not appear in `claude -p` (headless) runs |
| 107 | +- Users can skip each prompt (stored as "dismissed" in their local settings) |
| 108 | +- If skipped, the plugin is silently absent with no follow-up warning (see Issue #32607) |
| 109 | +- Does not apply in CI/CD pipelines — the template's README should document the manual |
| 110 | + `claude plugin marketplace add` + `claude plugin install` commands for CI contexts |
| 111 | + |
| 112 | +--- |
| 113 | + |
| 114 | +## Failure Path |
| 115 | + |
| 116 | +**Conditions under which the consent flow does not trigger:** |
| 117 | + |
| 118 | +1. **Headless/CI mode** (`claude -p`): Trust dialog is skipped; `extraKnownMarketplaces` is |
| 119 | + never processed. This is intentional, not a bug. |
| 120 | +2. **Already-trusted directory**: If the developer has previously trusted the directory (e.g., |
| 121 | + ran `claude` before the template's `.claude/settings.json` was committed), the trust dialog |
| 122 | + may not re-appear. The marketplace prompt fires only on the first trust event. |
| 123 | +3. **User dismisses the prompt**: Dismissed marketplaces and plugins are recorded in the user's |
| 124 | + `~/.claude/settings.json` and will not prompt again on subsequent runs. |
| 125 | +4. **Plugin listed in `enabledPlugins` is not yet installed**: If the marketplace prompt fires |
| 126 | + but the user skips the plugin install step, subsequent skill invocations fail silently |
| 127 | + (Issue #32607 — no warning is shown). |
| 128 | + |
| 129 | +The failure path does not mean the configuration is wrong; it means the feature has clear |
| 130 | +interactive-only scope and a silent-degradation gap that operators should anticipate. |
| 131 | + |
| 132 | +--- |
| 133 | + |
| 134 | +## Recommendation |
| 135 | + |
| 136 | +This document declares the **Success Path** as **authoritative**. |
| 137 | + |
| 138 | +The `extraKnownMarketplaces` field **does** trigger a consent/install prompt sequence when a |
| 139 | +developer opens a project for the first time in interactive Claude Code. This behavior is |
| 140 | +documented in the official settings reference and confirmed by community investigation. |
| 141 | + |
| 142 | +**Template fork recommendation: include `.claude/settings.json` with these fields.** |
| 143 | + |
| 144 | +The DSO NextJS Starter template should ship with a `.claude/settings.json` that declares: |
| 145 | + |
| 146 | +```json |
| 147 | +{ |
| 148 | + "extraKnownMarketplaces": { |
| 149 | + "digital-service-orchestra": { |
| 150 | + "source": { |
| 151 | + "source": "github", |
| 152 | + "repo": "navapbc/digital-service-orchestra" |
| 153 | + } |
| 154 | + } |
| 155 | + }, |
| 156 | + "enabledPlugins": { |
| 157 | + "digital-service-orchestra@digital-service-orchestra": true |
| 158 | + } |
| 159 | +} |
| 160 | +``` |
| 161 | + |
| 162 | +This delivers the onboarding goal: first-time users are guided through plugin installation |
| 163 | +without needing to know about the installer script `create-dso-app.sh` or the plugin system |
| 164 | +internals. |
| 165 | + |
| 166 | +**Additional steps for a complete experience:** |
| 167 | + |
| 168 | +1. **README callout**: Document that Claude Code will prompt to install the DSO marketplace on |
| 169 | + first launch; explain what to do if the prompt was skipped (run |
| 170 | + `/plugin marketplace add navapbc/digital-service-orchestra` then |
| 171 | + `/plugin install digital-service-orchestra@digital-service-orchestra`) |
| 172 | +2. **CI guidance**: For teams running `claude -p` in CI, document the explicit install commands |
| 173 | + since the consent flow does not run in headless mode |
| 174 | +3. **Trust re-trigger caveat**: If a developer has run `claude` in the project directory |
| 175 | + before the settings file was added, they may need to run the manual install; the trust event |
| 176 | + only fires once per directory |
| 177 | + |
| 178 | +The recommendation does **not** depend on the silent auto-install feature requested in |
| 179 | +Issue #23737 (not yet implemented). The consent-dialog path is sufficient for interactive |
| 180 | +developer onboarding. |
0 commit comments