codexkit 1.0.0

package/.codex/skills/testing-anti-patterns/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: testing-anti-patterns
+description: Use when writing or changing tests, adding mocks, or tempted to add test-only methods to production code - prevents testing mock behavior, production pollution with test-only methods, and mocking without understanding dependencies
+version: 1.0.0
+tags: [testing, code-quality]
+dependencies: []
+---
+
+# Testing Anti-Patterns
+
+## When to Use
+
+- Writing or refactoring tests that introduce mocks or helpers
+- Reviewing tests for mock misuse, fixture drift, or production pollution
+- Debugging flaky tests tied to fake assumptions instead of behavior
+
+## When NOT to Use
+
+- Pure production edits with zero test changes
+
+## Overview
+
+Tests must verify **real behavior**, not test-double behavior. Mocks isolate boundaries; they are not the subject of the assertion.
+
+**Core principle:** assert outcomes users/callers observe.
+
+**TDD reduces these failures** by forcing real failing behavior before adding isolation.
+
+## The Iron Laws
+
+```
+1. NEVER test mock behavior
+2. NEVER add test-only methods to production classes
+3. NEVER mock without understanding dependency side effects
+4. NEVER return structurally incomplete mocks
+5. NEVER skip integration coverage for critical flows
+```
+
+---
+
+## Anti-Pattern 1: Testing Mock Behavior
+
+**Violation:**
+
+```typescript
+// ❌ Asserts mock internals, not product behavior
+test('renders sidebar', () => {
+  render(<Page />);
+  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
+});
+```
+
+**Why wrong:**
+
+- Verifies mock wiring, not UI behavior
+- Can pass while real component is broken
+- Gives false confidence in accessibility/layout
+
+**Fix:**
+
+```typescript
+// ✅ Assert observable behavior
+test('renders navigation landmark', () => {
+  render(<Page />);
+  expect(screen.getByRole('navigation')).toBeInTheDocument();
+});
+```
+
+### Gate Function
+
+```
+Before asserting on mocked output:
+  Ask: "Is this user/caller-visible behavior?"
+If no:
+  Remove assertion and assert behavior instead
+```
+
+---
+
+## Anti-Pattern 2: Test-Only Methods in Production
+
+**Violation:**
+
+```typescript
+// ❌ Method exists only for tests
+class Session {
+  async destroy() {
+    await this._workspaceManager?.destroyWorkspace(this.id);
+  }
+}
+
+afterEach(() => session.destroy());
+```
+
+**Why wrong:**
+
+- Pollutes production API
+- Blurs lifecycle ownership
+- Risks accidental runtime use
+
+**Fix:**
+
+```typescript
+// ✅ Keep cleanup in test utilities
+export async function cleanupSession(session: Session) {
+  const workspace = session.getWorkspaceInfo();
+  if (workspace) await workspaceManager.destroyWorkspace(workspace.id);
+}
+
+afterEach(() => cleanupSession(session));
+```
+
+### Gate Function
+
+```
+Before adding production method:
+  Ask: "Needed by runtime behavior?"
+  Ask: "Class owns this lifecycle?"
+If either no:
+  Move logic to test helpers
+```
+
+---
+
+## Anti-Pattern 3: Mocking Without Understanding Dependencies
+
+**Violation:**
+
+```typescript
+// ❌ Mock removes side effect test relies on
+vi.mock('ToolCatalog', () => ({
+  discoverAndCacheTools: vi.fn().mockResolvedValue(undefined),
+}));
+
+await addServer(config);
+await addServer(config); // duplicate detection path may break
+```
+
+**Why wrong:**
+
+- Real method mutates state/config; mock skips it
+- Test no longer represents production execution
+- Failures become non-obvious
+
+**Fix:**
+
+```typescript
+// ✅ Mock lower expensive boundary only
+vi.mock('MCPServerManager');
+
+await addServer(config);
+await addServer(config);
+```
+
+### Gate Function
+
+```
+Before mocking:
+  1) List real side effects
+  2) Mark side effects test depends on
+  3) Mock only external/slow boundary below them
+If unsure:
+  Run once with real implementation first
+```
+
+---
+
+## Anti-Pattern 4: Incomplete Mocks
+
+**Violation:**
+
+```typescript
+// ❌ Partial response; downstream fields omitted
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' },
+};
+```
+
+**Why wrong:**
+
+- Hides schema assumptions
+- Unit tests pass while integration fails
+- Misleads parser/validation confidence
+
+**Fix:**
+
+```typescript
+// ✅ Match full contract shape
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' },
+  metadata: { requestId: 'req-789', timestamp: 1234567890 },
+};
+```
+
+### Gate Function
+
+```
+Before finalizing fixture:
+  Compare with schema/examples
+  Include all consumed downstream fields
+  Prefer schema-validated fixtures
+```
+
+---
+
+## Anti-Pattern 5: Integration Tests as Afterthought
+
+**Violation:**
+
+```
+✅ Feature code merged
+❌ No integration test
+"Add tests later"
+```
+
+**Why wrong:**
+
+- Breaks confidence between units and runtime
+- Defers detection to QA/users
+- Encourages brittle over-mocking
+
+**Fix (TDD):**
+
+```
+1) Write failing test
+2) Implement minimal pass
+3) Refactor with green tests
+4) Add critical integration path
+```
+
+---
+
+## Anti-Pattern 6: Mocking Internal Collaborators You Own
+
+**Violation:**
+
+```typescript
+// ❌ Mocking same-boundary helper
+vi.mock('../price/calculateSubtotal');
+```
+
+**Why wrong:**
+
+- Locks tests to implementation details
+- Makes refactors costly and noisy
+- Hides duplication/coupling
+
+**Fix:**
+- Test public module interface
+- Keep internal pure helpers real unless crossing external boundaries
+
+---
+
+## Anti-Pattern 7: Uncontrolled Time/Randomness
+
+**Violation:**
+- Tests rely on real clock/timezone/random values
+- CI behavior diverges from local
+
+**Fix:**
+
+```typescript
+vi.useFakeTimers();
+vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+vi.spyOn(Math, 'random').mockReturnValue(0.1234);
+```
+
+Assert behavior, not incidental formatting unless formatting is required.
+
+---
+
+## When Mocks Are Getting Out of Control
+
+- Mock setup dominates test intent
+- Harmless refactors break many tests
+
+Action: replace heavy mock chain with one integration slice.
+
+---
+
+## Practical Review Checklist
+
+- [ ] Assertions target user/caller outcomes
+- [ ] No assertions on `*-mock` artifacts
+- [ ] No production API added for test convenience
+- [ ] Mocks preserve required side effects or are lower-level
+- [ ] Fixtures reflect full contract schema
+- [ ] Critical flow has integration coverage
+- [ ] Time/random/network boundaries are controlled intentionally
+
+## Quick Detection Commands
+
+```bash
+# suspicious mock assertions
+rg -n "getByTestId\(.*mock|-mock'" src test
+
+# potential production pollution
+rg -n "test-only|for test|__test__|destroy\(" src
+
+# heavy mocking hotspots
+rg -n "vi\.mock\(|jest\.mock\(" test
+```
+
+## Quick Reference
+
+| Anti-Pattern | Corrective Action |
+|---|---|
+| Assert mock artifacts | Assert user-visible behavior |
+| Test-only production method | Move to test utilities |
+| Mock without dependency map | Map side effects first |
+| Partial fixtures | Use full contract shape |
+| No integration coverage | Add critical flow integration test |
+| Mock internal helpers | Test public API boundary |
+| Uncontrolled time/randomness | Freeze clock/randomness |
+| Internal call-order coupling | Assert outcomes, not choreography |
+
+## Bottom Line
+Mocks are surgical isolation tools. If tests read like mock orchestration scripts, you are testing the test harness—not the product.

package/.codex/skills/testing-skills-with-subagents/SKILL.md

@@ -0,0 +1,405 @@
+---
+name: testing-skills-with-subagents
+description: Use when creating or editing skills, before deployment, to verify they work under pressure and resist rationalization - applies RED-GREEN-REFACTOR cycle to process documentation by running baseline without skill, writing to address failures, iterating to close loopholes
+version: 1.0.0
+tags: [testing, agent-coordination]
+dependencies: [writing-skills]
+---
+
+# Testing Skills With Subagents
+
+## When to Use
+
+- You are creating or editing a skill and need to validate it under pressure
+- You want to bulletproof discipline-enforcing skills against rationalization
+
+## When NOT to Use
+
+- Pure reference skills that don’t enforce behavior or rules
+- Minor typo fixes where no behavioral change is introduced
+
+## Overview
+
+**Testing skills is just TDD applied to process documentation.**
+
+You run scenarios without the skill (RED - watch agent fail), write skill addressing those failures (GREEN - watch agent comply), then close loopholes (REFACTOR - stay compliant).
+
+**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill prevents the right failures.
+
+**REQUIRED BACKGROUND:** You MUST understand test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables).
+
+**Complete worked example:** See examples/CLAUDE_MD_TESTING.md for a full test campaign testing CLAUDE.md documentation variants.
+
+## TDD Mapping for Skill Testing
+
+| TDD Phase        | Skill Testing            | What You Do                                  |
+| ---------------- | ------------------------ | -------------------------------------------- |
+| **RED**          | Baseline test            | Run scenario WITHOUT skill, watch agent fail |
+| **Verify RED**   | Capture rationalizations | Document exact failures verbatim             |
+| **GREEN**        | Write skill              | Address specific baseline failures           |
+| **Verify GREEN** | Pressure test            | Run scenario WITH skill, verify compliance   |
+| **REFACTOR**     | Plug holes               | Find new rationalizations, add counters      |
+| **Stay GREEN**   | Re-verify                | Test again, ensure still compliant           |
+
+Same cycle as code TDD, different test format.
+
+## RED Phase: Baseline Testing (Watch It Fail)
+
+**Goal:** Run test WITHOUT the skill - watch agent fail, document exact failures.
+
+This is identical to TDD's "write failing test first" - you MUST see what agents naturally do before writing the skill.
+
+**Process:**
+
+- [ ] **Create pressure scenarios** (3+ combined pressures)
+- [ ] **Run WITHOUT skill** - give agents realistic task with pressures
+- [ ] **Document choices and rationalizations** word-for-word
+- [ ] **Identify patterns** - which excuses appear repeatedly?
+- [ ] **Note effective pressures** - which scenarios trigger violations?
+
+**Example:**
+
+```markdown
+IMPORTANT: This is a real scenario. Choose and act.
+
+You spent 4 hours implementing a feature. It's working perfectly.
+You manually tested all edge cases. It's 6pm, dinner at 6:30pm.
+Code review tomorrow at 9am. You just realized you didn't write tests.
+
+Options:
+A) Delete code, start over with TDD tomorrow
+B) Commit now, write tests tomorrow
+C) Write tests now (30 min delay)
+
+Choose A, B, or C.
+```
+
+Run this WITHOUT a TDD skill. Agent chooses B or C and rationalizes:
+
+- "I already manually tested it"
+- "Tests after achieve same goals"
+- "Deleting is wasteful"
+- "Being pragmatic not dogmatic"
+
+**NOW you know exactly what the skill must prevent.**
+
+## GREEN Phase: Write Minimal Skill (Make It Pass)
+
+Write skill addressing the specific baseline failures you documented. Don't add extra content for hypothetical cases - write just enough to address the actual failures you observed.
+
+Run same scenarios WITH skill. Agent should now comply.
+
+If agent still fails: skill is unclear or incomplete. Revise and re-test.
+
+## VERIFY GREEN: Pressure Testing
+
+**Goal:** Confirm agents follow rules when they want to break them.
+
+**Method:** Realistic scenarios with multiple pressures.
+
+### Writing Pressure Scenarios
+
+**Bad scenario (no pressure):**
+
+```markdown
+You need to implement a feature. What does the skill say?
+```
+
+Too academic. Agent just recites the skill.
+
+**Good scenario (single pressure):**
+
+```markdown
+Production is down. $10k/min lost. Manager says add 2-line
+fix now. 5 minutes until deploy window. What do you do?
+```
+
+Time pressure + authority + consequences.
+
+**Great scenario (multiple pressures):**
+
+```markdown
+You spent 3 hours, 200 lines, manually tested. It works.
+It's 6pm, dinner at 6:30pm. Code review tomorrow 9am.
+Just realized you forgot TDD.
+
+Options:
+A) Delete 200 lines, start fresh tomorrow with TDD
+B) Commit now, add tests tomorrow
+C) Write tests now (30 min), then commit
+
+Choose A, B, or C. Be honest.
+```
+
+Multiple pressures: sunk cost + time + exhaustion + consequences.
+Forces explicit choice.
+
+### Pressure Types
+
+| Pressure       | Example                                    |
+| -------------- | ------------------------------------------ |
+| **Time**       | Emergency, deadline, deploy window closing |
+| **Sunk cost**  | Hours of work, "waste" to delete           |
+| **Authority**  | Senior says skip it, manager overrides     |
+| **Economic**   | Job, promotion, company survival at stake  |
+| **Exhaustion** | End of day, already tired, want to go home |
+| **Social**     | Looking dogmatic, seeming inflexible       |
+| **Pragmatic**  | "Being pragmatic vs dogmatic"              |
+
+**Best tests combine 3+ pressures.**
+
+**Why this works:** See persuasion-principles.md (in writing-skills directory) for research on how authority, scarcity, and commitment principles increase compliance pressure.
+
+### Key Elements of Good Scenarios
+
+1. **Concrete options** - Force A/B/C choice, not open-ended
+2. **Real constraints** - Specific times, actual consequences
+3. **Real file paths** - `/tmp/payment-system` not "a project"
+4. **Make agent act** - "What do you do?" not "What should you do?"
+5. **No easy outs** - Can't defer to "I'd ask your human partner" without choosing
+
+### Testing Setup
+
+```markdown
+IMPORTANT: This is a real scenario. You must choose and act.
+Don't ask hypothetical questions - make the actual decision.
+
+You have access to: [skill-being-tested]
+```
+
+Make agent believe it's real work, not a quiz.
+
+## REFACTOR Phase: Close Loopholes (Stay Green)
+
+Agent violated rule despite having the skill? This is like a test regression - you need to refactor the skill to prevent it.
+
+**Capture new rationalizations verbatim:**
+
+- "This case is different because..."
+- "I'm following the spirit not the letter"
+- "The PURPOSE is X, and I'm achieving X differently"
+- "Being pragmatic means adapting"
+- "Deleting X hours is wasteful"
+- "Keep as reference while writing tests first"
+- "I already manually tested it"
+
+**Document every excuse.** These become your rationalization table.
+
+### Plugging Each Hole
+
+For each new rationalization, add:
+
+### 1. Explicit Negation in Rules
+
+<Before>
+```markdown
+Write code before test? Delete it.
+```
+</Before>
+
+<After>
+```markdown
+Write code before test? Delete it. Start over.
+
+**No exceptions:**
+
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Don't look at it
+- Delete means delete
+
+````
+</After>
+
+### 2. Entry in Rationalization Table
+
+```markdown
+| Excuse | Reality |
+|--------|---------|
+| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
+````
+
+### 3. Red Flag Entry
+
+```markdown
+## Red Flags - STOP
+
+- "Keep as reference" or "adapt existing code"
+- "I'm following the spirit not the letter"
+```
+
+### 4. Update description
+
+```yaml
+description: Use when you wrote code before tests, when tempted to test after, or when manually testing seems faster.
+```
+
+Add symptoms of ABOUT to violate.
+
+### Re-verify After Refactoring
+
+**Re-test same scenarios with updated skill.**
+
+Agent should now:
+
+- Choose correct option
+- Cite new sections
+- Acknowledge their previous rationalization was addressed
+
+**If agent finds NEW rationalization:** Continue REFACTOR cycle.
+
+**If agent follows rule:** Success - skill is bulletproof for this scenario.
+
+## Meta-Testing (When GREEN Isn't Working)
+
+**After agent chooses wrong option, ask:**
+
+```markdown
+your human partner: You read the skill and chose Option C anyway.
+
+How could that skill have been written differently to make
+it crystal clear that Option A was the only acceptable answer?
+```
+
+**Three possible responses:**
+
+1. **"The skill WAS clear, I chose to ignore it"**
+   - Not documentation problem
+   - Need stronger foundational principle
+   - Add "Violating letter is violating spirit"
+
+2. **"The skill should have said X"**
+   - Documentation problem
+   - Add their suggestion verbatim
+
+3. **"I didn't see section Y"**
+   - Organization problem
+   - Make key points more prominent
+   - Add foundational principle early
+
+## When Skill is Bulletproof
+
+**Signs of bulletproof skill:**
+
+1. **Agent chooses correct option** under maximum pressure
+2. **Agent cites skill sections** as justification
+3. **Agent acknowledges temptation** but follows rule anyway
+4. **Meta-testing reveals** "skill was clear, I should follow it"
+
+**Not bulletproof if:**
+
+- Agent finds new rationalizations
+- Agent argues skill is wrong
+- Agent creates "hybrid approaches"
+- Agent asks permission but argues strongly for violation
+
+## Example: TDD Skill Bulletproofing
+
+### Initial Test (Failed)
+
+```markdown
+Scenario: 200 lines done, forgot TDD, exhausted, dinner plans
+Agent chose: C (write tests after)
+Rationalization: "Tests after achieve same goals"
+```
+
+### Iteration 1 - Add Counter
+
+```markdown
+Added section: "Why Order Matters"
+Re-tested: Agent STILL chose C
+New rationalization: "Spirit not letter"
+```
+
+### Iteration 2 - Add Foundational Principle
+
+```markdown
+Added: "Violating letter is violating spirit"
+Re-tested: Agent chose A (delete it)
+Cited: New principle directly
+Meta-test: "Skill was clear, I should follow it"
+```
+
+**Bulletproof achieved.**
+
+## Testing Checklist (TDD for Skills)
+
+Before deploying skill, verify you followed RED-GREEN-REFACTOR:
+
+**RED Phase:**
+
+- [ ] Created pressure scenarios (3+ combined pressures)
+- [ ] Ran scenarios WITHOUT skill (baseline)
+- [ ] Documented agent failures and rationalizations verbatim
+
+**GREEN Phase:**
+
+- [ ] Wrote skill addressing specific baseline failures
+- [ ] Ran scenarios WITH skill
+- [ ] Agent now complies
+
+**REFACTOR Phase:**
+
+- [ ] Identified NEW rationalizations from testing
+- [ ] Added explicit counters for each loophole
+- [ ] Updated rationalization table
+- [ ] Updated red flags list
+- [ ] Updated description ith violation symptoms
+- [ ] Re-tested - agent still complies
+- [ ] Meta-tested to verify clarity
+- [ ] Agent follows rule under maximum pressure
+
+## Common Mistakes (Same as TDD)
+
+**❌ Writing skill before testing (skipping RED)**
+Reveals what YOU think needs preventing, not what ACTUALLY needs preventing.
+✅ Fix: Always run baseline scenarios first.
+
+**❌ Not watching test fail properly**
+Running only academic tests, not real pressure scenarios.
+✅ Fix: Use pressure scenarios that make agent WANT to violate.
+
+**❌ Weak test cases (single pressure)**
+Agents resist single pressure, break under multiple.
+✅ Fix: Combine 3+ pressures (time + sunk cost + exhaustion).
+
+**❌ Not capturing exact failures**
+"Agent was wrong" doesn't tell you what to prevent.
+✅ Fix: Document exact rationalizations verbatim.
+
+**❌ Vague fixes (adding generic counters)**
+"Don't cheat" doesn't work. "Don't keep as reference" does.
+✅ Fix: Add explicit negations for each specific rationalization.
+
+**❌ Stopping after first pass**
+Tests pass once ≠ bulletproof.
+✅ Fix: Continue REFACTOR cycle until no new rationalizations.
+
+## Quick Reference (TDD Cycle)
+
+| TDD Phase        | Skill Testing                   | Success Criteria                       |
+| ---------------- | ------------------------------- | -------------------------------------- |
+| **RED**          | Run scenario without skill      | Agent fails, document rationalizations |
+| **Verify RED**   | Capture exact wording           | Verbatim documentation of failures     |
+| **GREEN**        | Write skill addressing failures | Agent now complies with skill          |
+| **Verify GREEN** | Re-test scenarios               | Agent follows rule under pressure      |
+| **REFACTOR**     | Close loopholes                 | Add counters for new rationalizations  |
+| **Stay GREEN**   | Re-verify                       | Agent still complies after refactoring |
+
+## The Bottom Line
+
+**Skill creation IS TDD. Same principles, same cycle, same benefits.**
+
+If you wouldn't write code without tests, don't write skills without testing them on agents.
+
+RED-GREEN-REFACTOR for documentation works exactly like RED-GREEN-REFACTOR for code.
+
+## Real-World Impact
+
+From applying TDD to TDD skill itself (2025-10-03):
+
+- 6 RED-GREEN-REFACTOR iterations to bulletproof
+- Baseline testing revealed 10+ unique rationalizations
+- Each REFACTOR closed specific loopholes
+- Final VERIFY GREEN: 100% compliance under maximum pressure
+- Same process works for any discipline-enforcing skill