Skip to content

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

Closed

Description

@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.

Activity

  1. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.
    and removed
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Jul 19, 2026
  2. kyle-sexton commented on Jul 19, 2026

    @kyle-sexton
    MemberAuthor

    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.

  3. added
    wayfind: designWayfind decision item: design-space or domain-model decision; human in the loop.
    on Jul 19, 2026
  4. kyle-sexton commented on Jul 19, 2026

    @kyle-sexton
    MemberAuthor

    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.

  5. kyle-sexton commented on Jul 19, 2026

    @kyle-sexton
    MemberAuthor

    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.

  6. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    and removed
    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Jul 19, 2026
  7. kyle-sexton commented on Jul 19, 2026

    @kyle-sexton
    MemberAuthor

    This was generated by AI during triage.

    Umbrella-fold: member of #531 (portability lint lane — 19-issue coupling class). Routed blocked-by-carrier, not standalone: native blocked by #531 dependency recorded, priority: needs-triage removed, wayfind: design applied uniformly. Decision lands on #531; this issue rides along.

  8. kyle-sexton commented on Jul 21, 2026

    @kyle-sexton
    MemberAuthor

    Decided — operator accepted 2026-07-19 (batch 1, RECOMMENDED option verbatim); carried by #531's staged decomposition child #714. The wayfind: design label predates the fold and is a stale routing artifact, not an open-proposal request.

    This was generated by AI (tower overnight design drafter, Opus). Proposal only — no convention locked; operator/design-session decides.

  9. kyle-sexton commented on Jul 22, 2026

    @kyle-sexton
    MemberAuthor

    Operator ruling (ratification interview, 2026-07-22 ~03:05Z): RE-ACTIVATED. Accepted option 1 stands: TDD stays the default; fix is documentation-only — name the existing CLAUDE.md off-switch in README Configuration + a SKILL.md one-liner. The userConfig key stays deferred with trigger. Cheap pre-freeze win. Flipping to status: ready.

  10. added
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    on Jul 22, 2026
  11. self-assigned this
    on Jul 22, 2026
  12. kyle-sexton commented on Jul 22, 2026

    @kyle-sexton
    MemberAuthor
    No description provided.
  13. added
    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.
    on Jul 23, 2026
  14. added 2 commits that reference this issue on Jul 25, 2026
    12ec6ff
    d7551dc
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.status: readyTriaged, unblocked, and fully specified; eligible to pick up.wayfind: designWayfind decision item: design-space or domain-model decision; human in the loop.

Type

Fields

No fields configured for Task.

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions