docs(implementation): document TDD project-policy override

[kyle-sexton]

Closes #406

Summary

Documents the implementation plugin's existing project-level testing-cadence override without changing its advertised TDD-by-default identity. TDD remains the fallback when a consuming project is silent; an explicit testing policy in the project's CLAUDE.md or rules now clearly takes precedence in every execution mode.

This gives teams a discoverable, repository-scoped opt-out while keeping the plugin's zero-configuration default unchanged.

Fix

• Add a concrete tests-after override example to the implementation README's Configuration section.
• State in the central /implementation:implement cadence that project policy overrides both the fallback and mode-context guidance.
• Make the feature and bugfix contexts explicitly honor project testing policy before their test-first fallback instructions.
• Remove the contradictory bugfix phrase test-first, always.
• Bump the implementation plugin from 0.7.8 to 0.7.9 and add its changelog entry.
• Keep a user-global userConfig key deferred, matching the accepted operator decision.

Research

The implementation follows Anthropic's current official scope model:

• How Claude remembers your project identifies project CLAUDE.md as team-shared instruction space for build/test instructions, coding standards, and common workflows.
• Plugins reference documents userConfig as user/managed-scoped and states that project and local plugin-option entries are ignored.

Together, those sources support keeping testing cadence in project instructions rather than introducing a user-scoped plugin option.

Verification

• Independent verification caught two contradictory mode-context instructions before publication; both were corrected and the resulting six-file change was re-verified before publish.
• Focused contract assertion: README, central skill, feature context, and bugfix context agree that project policy takes precedence while TDD remains the silent-project fallback.
• Regression assertion: bugfix context no longer contains test-first, always.
• claude plugin validate plugins/implementation — passed before and after rebasing.
• git diff --check origin/main...HEAD — passed after rebasing.
• Direct changelog assertion — verified 0.7.8 → 0.7.9 and a newly added ## [0.7.9] entry.
• Direct changed-skill assertion — frontmatter/routing description preserved; skill remains below the 500-line cap.
• Live collision audit — no open PR files or other registered worktrees touch plugins/implementation/**.
• Rebased cleanly onto current origin/main at b123108ed745c51478d77737a2a01480623fd2ae.

Local disclosure: the repository's canonical Bash changed-skill/changelog wrappers and markdownlint were not completed locally. The default bash command resolves to an unconfigured WSL environment, direct Git Bash wrapper attempts exceeded the strict local timebox, and no standalone markdownlint binary is installed. The focused direct equivalents above passed; canonical wrappers and markdownlint are left to required CI.

Related

• Refs verification: consumer override seams gestured ("when the project documents…") but no declared location exists #423 — trigger for revisiting a fleet-wide consumer-override seam.
• Refs ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531 — portability/configuration audit umbrella that originally carried this finding.

[claude]

Claude finished @kyle-sexton's task in 1m 32s —— View job

---

Code Review

• Gather context and understand request
• Read changed files
• Verify consistency across all changed files
• Check alignment with CLAUDE.md guidelines
• Post review findings

---

This is a well-scoped, well-executed documentation PR. The core objective — making the existing project-policy override explicitly discoverable across all execution surfaces without changing the TDD-by-default identity — is accomplished cleanly. Here are my findings, most significant first.

---

Minor issue: bugfix.md "Common pitfalls" contradicts the updated step 1

The step 1 heading was correctly updated to qualify test-first with "when project policy is silent," but the Common pitfalls section retains an unqualified imperative:

- **Fixing without a test** — "I can see the bug, the fix is obvious" leads to regressions. Write the test first

plugins/implementation/skills/implement/context/bugfix.md line 20

This creates a quiet contradiction: a consumer with Use tests-after in their CLAUDE.md would see step 1 correctly defer to their policy, but then encounter a pitfall entry telling them "Write the test first" with no qualification. Suggesting a small addition like "Write the test first (unless project policy specifies otherwise)" or "Under the test-first fallback, write the test first" to keep the pitfall section honest. Fix this →

---

Observation: SKILL.md frontmatter and plugin.json description still say "TDD by default"

The skill frontmatter description and plugin.json description both still read "TDD by default" / "TDD-by-default cadence" without the "when project policy is silent" qualifier:

• SKILL.md line 3: TDD by default
• plugin.json line 5: TDD-by-default cadence

These are one-line summary fields where brevity is appropriate, so "TDD by default" reads as acceptable shorthand. The PR description explicitly notes it wants to preserve the plugin's "TDD-by-default identity," so this is likely intentional. Not blocking — just confirming the trade-off was deliberate.

---

Positive observations

Consistency across the four updated surfaces. README, SKILL.md (step 3), feature.md (step 5), and bugfix.md (step 1) all use the same priority model — project policy first, TDD as the fallback — and the SKILL.md step 3 even embeds the exact opt-out sentence shown in the README (Use tests-after for implementation work; do not use test-first TDD.), which is a nice touch that makes the documentation self-reinforcing.

refactor.md left untouched correctly. It contains no test-first instructions, so there was nothing to qualify there.

Semver is appropriate. A 0.7.8 → 0.7.9 patch bump is the right call for a documentation/clarification-only change with no behavior change and no breaking API surface.

CHANGELOG is accurate and well-structured. The ## [0.7.9] entry under ### Changed correctly scopes the change and cross-references the closing issue.

The phrase "test-first, always" is gone. The old bugfix.md heading absolute was the sharpest contradiction; its removal is correct.

---

Summary

One minor fix is worth making before merge: the bugfix.md Common pitfalls entry needs its own project-policy qualifier to match the updated step 1. Everything else is clean.

[claude]

Claude finished @kyle-sexton's task in 30s —— View job

---

Security Review — PR #1054

• Read the PR diff
• Review changed files for security issues
• Post findings

---

Findings

No security issues found.

All six changed files are pure documentation and metadata:

File	Change
plugin.json	Semver bump 0.7.8 → 0.7.9 — no schema or permission changes
CHANGELOG.md	Prose changelog entry — no executable content
README.md	Adds a Markdown code block example for a project instruction — static text only
SKILL.md	Rewrites step 3 prose — no new tool invocations, permissions, or external references
context/bugfix.md	Rewrites step 1 prose — same scope as above
context/feature.md	Rewrites step 5 prose — same scope as above

None of the changes introduce code execution paths, new permissions, external URLs, credential handling, injection surfaces, supply-chain dependencies, or GitHub Actions modifications. The diff presents no attack surface beyond the existing plugin runtime that loads these files.

[claude]

Claude finished @kyle-sexton's task in 1m 17s —— View job

---

Code Review — PR #1054 (re-review after 9925c11)

• Gather context
• Read changed files
• Verify the new commit addresses previous findings
• Check consistency across all surfaces
• Post review findings

---

The second commit (9925c11 docs(implementation): qualify bugfix testing pitfall) directly and cleanly resolves the one minor issue flagged in the prior review. Here is the full picture.

---

Previous finding resolved ✓

bugfix.md Common pitfalls — now correctly qualified.

The unqualified "Write the test first" in the pitfall entry has been replaced with:

Under the test-first fallback, write the test first; otherwise follow the project's declared CLAUDE.md / rules testing cadence

plugins/implementation/skills/implement/context/bugfix.md line 20

The fix is precise — it scopes the imperative to the fallback cadence and points to the same authority (project CLAUDE.md / rules) used throughout the other updated surfaces. The vocabulary is consistent with step 1.

---

Consistency check across all four updated surfaces

All surfaces now agree: project policy wins; TDD is the fallback when the project is silent.

Surface	Verdict
README Configuration section	✅ "TDD remains the fallback when the consuming project's CLAUDE.md or rules do not declare another cadence."
SKILL.md step 2 item 3	✅ "TDD is the fallback when the consuming project does not declare another testing cadence … A consumer can opt out in its CLAUDE.md / rules"
feature.md step 5	✅ "first honor the consuming project's testing cadence … that project policy overrides the test-first instructions in this step"
bugfix.md step 1 + pitfalls	✅ Both now qualified; "test-first, always" is gone

---

Unchanged items confirmed intentional

• SKILL.md frontmatter: still "TDD by default" in the one-line description. Brevity is appropriate for a summary field; the full qualifier lives in step 2. The PR description explicitly states this preserves the plugin's "TDD-by-default identity" — the trade-off is deliberate.
• plugin.json description: still "TDD-by-default cadence" for the same reason.
• refactor.md: left untouched. It carries no test-first instructions, so there is nothing to qualify.

---

Semver and changelog

• 0.7.8 → 0.7.9 patch bump is appropriate for a documentation-only, no-behavior-change PR.
• CHANGELOG.md ## [0.7.9] entry is well-structured, scoped correctly, and cross-references issue implementation: TDD-by-default fires when consumer CLAUDE.md is silent — no userConfig toggle #406.

---

Verdict

Both commits are clean. No outstanding issues. This PR is ready to merge.

[claude]

Claude finished @kyle-sexton's task in 1m 51s —— View job

---

Security Review — PR #1054

• Read PR diff
• Review changed files for security issues
• Post findings

---

Findings

No security issues found.

All six changed files are pure documentation and metadata:

File	Change
plugin.json	Semver bump 0.7.8 → 0.7.9 — no schema, permission, or keyword changes
CHANGELOG.md	Prose changelog entry — no executable content
README.md	Adds a Markdown code-block example (Use tests-after for implementation work…) — static text only; rendered as a quoted code block, not injected into any execution context
SKILL.md	Rewrites step 3 prose to add project-policy precedence language — no new shell commands, tool invocations, external URLs, or permission grants
context/bugfix.md	Rewrites step 1 and common pitfalls with the same project-policy qualifier — same scope as above
context/feature.md	Rewrites step 5 prose — same scope as above

Pre-computed shell context (!git branch --show-current, !git status --porcelain, etc.) in SKILL.md is unchanged from the pre-PR version — no new shell execution surfaces were introduced.

Prompt-injection surface: the skill .md files are instructions loaded into Claude's context at invocation. The new prose directs the model to honor consumer CLAUDE.md instructions — this is the documented, intentional trust model for Claude Code plugins (project CLAUDE.md overrides plugin defaults). No adversarially-constructed instruction is embedded; the example opt-out string is enclosed in a fenced code block in the README and in a plain-English sentence in the skill files, neither of which creates a novel injection path beyond what already exists in the plugin system design.

None of the changes introduce code execution paths, new permissions, external URLs, credential handling, injection surfaces, supply-chain dependencies, or GitHub Actions modifications.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9925c11724

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kyle-sexton]

🔒 babysit-prs lane claiming this PR for on-branch fix work this cycle (amendment-round: 16, safe tier). Will fix clear branch-owned findings and push; will not resolve threads or merge (safe tier).

[claude]

Claude finished @kyle-sexton's task in 1m 30s —— View job

---

Code Review — PR #1054 (re-review after rebase onto 9172d53)

• Gather context and read changed files
• Verify all previous findings are addressed
• Check consistency across all surfaces
• Post review findings

---

All prior findings from the previous review rounds — including the Codex-flagged internal inconsistency in bugfix.md — have been addressed. Here is the full current state.

---

Previous findings resolved ✓

Finding	Source	Commit	Status
bugfix.md pitfall "Write the test first" unqualified	Prior Claude review	9925c11	✅ Resolved — now scoped to the test-first fallback
bugfix.md step 4 and first checkpoint reference step-1 failing test without conditionality	Codex review	bd92091	✅ Resolved — both now defer to project's declared cadence

---

Consistency check across all four updated surfaces

All surfaces now agree: project policy overrides the fallback; TDD is the fallback when the project is silent.

Surface	Key text	Verdict
README.md lines 80–90	"TDD remains the fallback when the consuming project's CLAUDE.md or rules do not declare another cadence."	✅
SKILL.md step 3, line 68	"TDD is the fallback … That project policy overrides this fallback and the mode context guidance"	✅
feature.md step 5, line 11	"first honor the consuming project's testing cadence … that project policy overrides the test-first instructions in this step"	✅
bugfix.md step 1 + step 4 + checkpoint + pitfalls	All four locations now carry the "under the test-first fallback … otherwise follow the project's declared cadence" qualifier	✅

---

Version number in PR description is stale (informational only)

The PR body references "0.7.8 → 0.7.9" — written before the branch was rebased. The actual diff shows 0.9.0 → 0.9.1, which is correct: a patch bump for a documentation-only, no-behavior-change PR. Not a code issue; the description was authored prior to the rebase. Code is correct.

---

Unchanged items confirmed intentional

• SKILL.md frontmatter / plugin.json description: both still read "TDD by default" / "TDD-by-default cadence." Brevity is appropriate for one-line summary fields; the full qualifier lives in step 3. Deliberate.
• context/refactor.md: untouched. It contains no test-first instructions. Correct.
• feature.md checkpoints: "tests green" is cadence-agnostic (tests must pass at commit time regardless of when they were written) — no qualification needed.

---

Verdict

All commits are clean. No outstanding issues. This PR is ready to merge.

[claude]

Claude finished @kyle-sexton's task in 49s —— View job

---

Security Review — PR #1054

• Read the PR diff
• Review changed files for security issues
• Post findings

---

Findings

No security issues found.

All six changed files are pure documentation and metadata:

File	Change
plugin.json	Semver bump 0.9.0 → 0.9.1 — no schema, permission, or keyword changes
CHANGELOG.md	Prose changelog entry — no executable content
README.md	Adds a Markdown fenced-code-block example for a project instruction — static text only; rendered as a quoted code block, not injected into any execution context
SKILL.md	Rewrites step 3 to add project-policy precedence language and an inline example opt-out string — no new shell commands, tool invocations, external URLs, or permission grants
context/bugfix.md	Rewrites step 1, step 4, the first checkpoint, and the Common pitfalls entry with project-policy qualifiers — same scope as above
context/feature.md	Rewrites step 5 with the same project-policy qualifier — same scope

Trust-delegation surface (confirmed intentional, no new risk): The updated skill prose now explicitly directs the implementation plugin to honor CLAUDE.md / rules from the consumer project for testing cadence. This is the documented Claude Code trust model — consumer CLAUDE.md files are already authoritative over plugin behavior by design. This PR makes that existing trust relationship visible in the prose; it does not widen or alter it. No new injection surface is created.

Pre-computed shell context (!git branch --show-current, !git status --porcelain, etc.) in SKILL.md is unchanged from the pre-PR state — no new shell execution surfaces were introduced.

None of the changes introduce code execution paths, new permissions, external URLs, credential handling, injection surfaces, supply-chain dependencies, or GitHub Actions modifications.

---

Note: The PR description references a version bump from 0.7.8 → 0.7.9, but the actual diff shows 0.9.0 → 0.9.1. This is a prose inaccuracy in the PR description only — the committed plugin.json and CHANGELOG.md are internally consistent with each other at 0.9.1. No security implication.