implementation: TDD-by-default fires when consumer CLAUDE.md is silent — no userConfig toggle

[kyle-sexton]

Plugin: implementation · Categories: hardcoded opinion (1), missing externalization (2) — designed default, low severity
Source: work-readiness sweep (read-only audit vs docs/PLUGIN-PHILOSOPHY.md + docs/MIGRATION-PLAYBOOK.md)

Findings

• plugins/implementation/skills/implement/SKILL.md:3 (description), SKILL.md:67 — "TDD is the default — skip only when genuinely impractical"
• plugins/implementation/skills/implement/context/feature.md:11
• plugins/implementation/skills/implement/context/bugfix.md:7 — "Reproduce first (test-first, always)"

Why flagged

Strong methodology opinion applied as the default-when-silent. Mitigations exist: TDD-by-default is the plugin's advertised identity (plugin.json description), and SKILL.md:67 defers to the consuming project's own testing conventions (CLAUDE.md/rules) — so seam-3 externalization is present. Gap: when the consumer CLAUDE.md is silent the opinionated default fires, and there is no userConfig toggle (README:76: plugin "declares no userConfig options"). Under PLUGIN-PHILOSOPHY this is a defensible rung-4 safe default — filed for triage visibility because it is the plugin's most load-bearing baked opinion.

Fix direction

If a consumer must disable the TDD default without editing prose, the sanctioned surface is a userConfig boolean (e.g. tdd_default) read into the cadence, alongside the existing seam-3 consumer CLAUDE.md deferral. Not a hardcode swap.

[kyle-sexton]

This was generated by AI during triage.

Triage → needs-human, priority: high. Config-seam gap on a priority plugin (implementation): TDD-by-default fires when consumer CLAUDE.md is silent and there is no userConfig toggle to disable it without editing prose. High per directive (setup/config-seam gap). Human decision: whether to add a userConfig boolean (e.g. tdd_default) — it changes the plugin's advertised identity, so it is a design call rather than a delegable fix.

[kyle-sexton]

Decision brief (2-minute read)

Problem. The implementation plugin applies TDD as the default cadence whenever the consuming project's CLAUDE.md says nothing about testing, and there is no userConfig toggle to turn it off without editing prose. The decision is whether to add a config key, and if so which seam owns it.

Today. Verified against origin/main:

• The TDD default is asserted in plugins/implementation/skills/implement/SKILL.md (frontmatter description; Step 2 cadence item 3: "TDD is the default — skip only when genuinely impractical"), context/feature.md (step 5, "Test first (TDD by default)"), and context/bugfix.md (step 1, "Reproduce first (test-first, always)").
• The consumer seam already exists at the repo-policy layer: SKILL.md Step 2 item 3 ends "Honor the consuming project's own testing conventions (its CLAUDE.md / rules)" — a one-line consumer CLAUDE.md instruction disables TDD today. But the plugin README's Configuration section only says "This plugin declares no userConfig options" and never names this off-switch, so a consumer can't discover it without reading skill internals.
• The userConfig mechanism is real and fleet-standard (e.g. boolean toggles with defaults in plugins/guardrails/.claude-plugin/plugin.json, plugins/desktop-notification/.claude-plugin/plugin.json), so adding a key is mechanically easy — the question is ownership, not feasibility.
• docs/PLUGIN-PHILOSOPHY.md ("Configuration ownership and scope") assigns each value one owner: personal/administrator scalar → manifest userConfig; tracked repository convention or team policy → a documented consumer-project file. It states explicitly that userConfig is not repository configuration — Claude Code reads it only from user/managed settings and ignores project settings.

Options.

1. RECOMMENDED — Keep the default; promote the existing CLAUDE.md seam to a documented off-switch; defer a config key with a trigger. Test methodology is team/repo policy, so per the philosophy doc's ownership table its correct owner is the consumer-project file — and that seam already works; what's missing is discoverability. Fix: name the off-switch in the plugin README Configuration section and SKILL.md (one-line consumer example, e.g. a CLAUDE.md testing-conventions instruction), keeping "declares no userConfig" true. The residual gap — a user-global "never TDD for me" preference — is a genuine personal scalar with no seam today; record it as deferred with triggers: (a) a demonstrated per-user/headless need, or (b) verification: consumer override seams gestured ("when the project documents…") but no declared location exists #423 landing a fleet-wide consumer-override seam convention this should then follow. Fully reversible: adding a key later is additive and non-breaking; shipping one now and removing it later is not. Preserves the plugin's advertised TDD-by-default identity (plugin.json description).
2. Add a userConfig key now. If chosen, follow the source-control: no read/consume-only posture — "safe" babysit tier and pull-request monitor write to GitHub autonomously #440-decided conventions: enum rather than boolean (e.g. test_discipline: tdd | tests-after | none), single canonical name, default tdd to preserve zero-config behavior. Gives a prose-free, --config-scriptable toggle for headless installs. Costs: it puts a user-scoped key in charge of repo-scoped policy, so a personal none silently overrides a repo whose CLAUDE.md mandates TDD unless the skill also ships precedence rules; it enlarges the config surface enough to trigger the philosophy doc's setup-skill requirement; and a shipped key is hard to retract. Weakly reversible.
3. Tracked consumer concern-file key. A machine-readable repo-level key (e.g. .claude/implementation.md test_discipline:, mirroring the trailer_policy precedent in plugins/source-control/skills/commit/SKILL.md). Right scope and diffable, but it duplicates what one line of consumer CLAUDE.md prose already achieves, and verification: consumer override seams gestured ("when the project documents…") but no declared location exists #423 is the open decision on where exactly such override seams live — deciding the shape here first risks fleet divergence. Best treated as the follow-on if verification: consumer override seams gestured ("when the project documents…") but no declared location exists #423 standardizes this seam shape, not decided independently.

Confidence note: options 1–3 rest on verified file contents; the claim that no user-global seam exists today is an absence claim (no userConfig, no user-scoped key found) and could be superseded by harness-level user memory behavior, which is outside this plugin's contract.

Related.

• source-control: no read/consume-only posture — "safe" babysit tier and pull-request monitor write to GitHub autonomously #440 — decided: canonical outward_write_mode: report-only | write userConfig enum, fail-safe default; establishes enum-over-boolean and one-canonical-key conventions for any option-2 key, but note the scope difference — write posture is a per-install administrator scalar (userConfig's proper owner), TDD is repo policy.
• verification: consumer override seams gestured ("when the project documents…") but no declared location exists #423 — open: where verification's consumer-override seams live (tracked .claude/ key vs concern-file); option 3's shape should follow that decision.
• toolchain: dotnet.md references dotnet-msbuild:* plugin skills that do not exist in this marketplace #412 — decided disposition: forward references stay, presence-gated, generic path first-class; not binding here, but shows the maintainer's preference for deferral-with-trigger over deletion.

[kyle-sexton]

Operator decision (2026-07-19, decision-session batch 1; relayed).

ACCEPTED — the brief's RECOMMENDED option verbatim: keep the TDD default; promote the existing consumer-CLAUDE.md seam to a documented off-switch (README Configuration section + SKILL.md one-line consumer example); defer a user-global config key, recorded with triggers (demonstrated per-user/headless need, or #423 landing a fleet-wide consumer-override seam convention this should then follow).

Note the operator's #415 batch-1 ruling also applies to this class: defaults must be non-conflicting good-practice defaults, with repo conventions discovered/configured via setup rather than pre-prescribed.

Re-intake: removing needs-human, adding priority: needs-triage for routing.