@amrhas82/agentic-kit 1.5.0 → 1.7.5

package/packages/droid/commands/testing-anti-patterns.md

@@ -1,22 +1,34 @@
 ---
-description: Avoid testing anti-patterns - never test mock behavior, add test-only methods, or mock without understanding
-argument-hint: <test-anti-pattern-to-avoid>
+id: testing-anti-patterns
+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
+usage: /testing-anti-patterns <testing-scenario>
+auto_trigger: true
 ---
 
+# Testing Anti-Patterns
+
+## Overview
+
+Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
+
 **Core principle:** Test what the code does, not what the mocks do.
 
+**Following strict TDD prevents these anti-patterns.**
+
 ## The Iron Laws
 
 ```
 1. NEVER test mock behavior
-2. NEVER add test-only methods to production classes  
+2. NEVER add test-only methods to production classes
 3. NEVER mock without understanding dependencies
 ```
 
 ## Anti-Pattern 1: Testing Mock Behavior
 
-**❌ WRONG: Testing that the mock exists**
+**The violation:**
 ```typescript
+// ❌ BAD: Testing that the mock exists
 test('renders sidebar', () => {
   render(<Page />);
   expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
@@ -28,8 +40,11 @@ test('renders sidebar', () => {
 - Test passes when mock is present, fails when it's not
 - Tells you nothing about real behavior
 
-**✅ CORRECT: Test real component behavior**
+**your human partner's correction:** "Are we testing the behavior of a mock?"
+
+**The fix:**
 ```typescript
+// ✅ GOOD: Test real component or don't mock it
 test('renders sidebar', () => {
   render(<Page />);  // Don't mock sidebar
   expect(screen.getByRole('navigation')).toBeInTheDocument();
@@ -40,6 +55,7 @@ test('renders sidebar', () => {
 ```
 
 ### Gate Function
+
 ```
 BEFORE asserting on any mock element:
   Ask: "Am I testing real component behavior or just mock existence?"
@@ -52,11 +68,13 @@ BEFORE asserting on any mock element:
 
 ## Anti-Pattern 2: Test-Only Methods in Production
 
-**❌ WRONG: Production class polluted with test-only code**
+**The violation:**
 ```typescript
+// ❌ BAD: destroy() only used in tests
 class Session {
-  async destroy() {  // Only used in tests
+  async destroy() {  // Looks like production API!
     await this._workspaceManager?.destroyWorkspace(this.id);
+    // ... cleanup
   }
 }
 
@@ -70,8 +88,9 @@ afterEach(() => session.destroy());
 - Violates YAGNI and separation of concerns
 - Confuses object lifecycle with entity lifecycle
 
-**✅ CORRECT: Test utilities handle test cleanup**
+**The fix:**
 ```typescript
+// ✅ GOOD: Test utilities handle test cleanup
 // Session has no destroy() - it's stateless in production
 
 // In test-utils/
@@ -87,6 +106,7 @@ afterEach(() => cleanupSession(session));
 ```
 
 ### Gate Function
+
 ```
 BEFORE adding any method to production class:
   Ask: "Is this only used by tests?"
@@ -94,13 +114,20 @@ BEFORE adding any method to production class:
   IF yes:
     STOP - Don't add it
     Put it in test utilities instead
+
+  Ask: "Does this class own this resource's lifecycle?"
+
+  IF no:
+    STOP - Wrong class for this method
 ```
 
 ## Anti-Pattern 3: Mocking Without Understanding
 
-**❌ WRONG: Mock breaks test logic**
+**The violation:**
 ```typescript
+// ❌ BAD: Mock breaks test logic
 test('detects duplicate server', () => {
+  // Mock prevents config write that test depends on!
   vi.mock('ToolCatalog', () => ({
     discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
   }));
@@ -115,8 +142,9 @@ test('detects duplicate server', () => {
 - Over-mocking to "be safe" breaks actual behavior
 - Test passes for wrong reason or fails mysteriously
 
-**✅ CORRECT: Mock at correct level**
+**The fix:**
 ```typescript
+// ✅ GOOD: Mock at correct level
 test('detects duplicate server', () => {
   // Mock the slow part, preserve behavior test needs
   vi.mock('MCPServerManager'); // Just mock slow server startup
@@ -127,6 +155,7 @@ test('detects duplicate server', () => {
 ```
 
 ### Gate Function
+
 ```
 BEFORE mocking any method:
   STOP - Don't mock yet
@@ -140,6 +169,11 @@ BEFORE mocking any method:
     OR use test doubles that preserve necessary behavior
     NOT the high-level method the test depends on
 
+  IF unsure what test depends on:
+    Run test with real implementation FIRST
+    Observe what actually needs to happen
+    THEN add minimal mocking at the right level
+
   Red flags:
     - "I'll mock this to be safe"
     - "This might be slow, better mock it"
@@ -148,8 +182,9 @@ BEFORE mocking any method:
 
 ## Anti-Pattern 4: Incomplete Mocks
 
-**❌ WRONG: Partial mock structure**
+**The violation:**
 ```typescript
+// ❌ BAD: Partial mock - only fields you think you need
 const mockResponse = {
   status: 'success',
   data: { userId: '123', name: 'Alice' }
@@ -160,89 +195,111 @@ const mockResponse = {
 ```
 
 **Why this is wrong:**
-- Partial mocks hide structural assumptions
-- Downstream code may depend on fields you didn't include
-- Tests pass but integration fails
-- False confidence about real behavior
+- **Partial mocks hide structural assumptions** - You only mocked fields you know about
+- **Downstream code may depend on fields you didn't include** - Silent failures
+- **Tests pass but integration fails** - Mock incomplete, real API complete
+- **False confidence** - Test proves nothing about real behavior
+
+**The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
 
-**✅ CORRECT: Mock complete data structures**
+**The fix:**
 ```typescript
-// Mock the COMPLETE data structure as it exists in reality
+// ✅ GOOD: Mirror real API completeness
 const mockResponse = {
   status: 'success',
   data: { userId: '123', name: 'Alice' },
-  metadata: { requestId: 'req-456', timestamp: '2024-01-01' },
-  headers: { 'content-type': 'application/json' }
+  metadata: { requestId: 'req-789', timestamp: 1234567890 }
+  // All fields real API returns
 };
 ```
 
-## Anti-Pattern 5: Over-Mocking
+### Gate Function
 
-**❌ WRONG: Everything is mocked**
-```typescript
-test('saves user', () => {
-  const mockUser = { id: '1', name: 'John' };
-  const mockDb = { save: vi.fn().mockResolvedValue(mockUser) };
-  
-  vi.mocked(userService.save).mockResolvedValue(mockUser);
-  vi.mocked(db.save).mockResolvedValue(mockUser);
-  vi.mocked(cache.set).mockResolvedValue();
-  
-  const result = await saveUser(mockUser);
-  expect(result).toBe(mockUser);
-});
+```
+BEFORE creating mock responses:
+  Check: "What fields does the real API response contain?"
+
+  Actions:
+    1. Examine actual API response from docs/examples
+    2. Include ALL fields system might consume downstream
+    3. Verify mock matches real response schema completely
+
+  Critical:
+    If you're creating a mock, you must understand the ENTIRE structure
+    Partial mocks fail silently when code depends on omitted fields
+
+  If uncertain: Include all documented fields
+```
+
+## Anti-Pattern 5: Integration Tests as Afterthought
+
+**The violation:**
+```
+✅ Implementation complete
+❌ No tests written
+"Ready for testing"
 ```
 
 **Why this is wrong:**
-- Testing mock behavior, not real behavior
-- No integration verification
-- Easy to pass incorrect implementation
+- Testing is part of implementation, not optional follow-up
+- TDD would have caught this
+- Can't claim complete without tests
 
-**✅ CORRECT: Mock only what you must**
-```typescript
-test('saves user', async () => {
-  const mockUser = { id: '1', name: 'John' };
-  
-  // Only mock the external dependency (database)
-  vi.mocked(db.save).mockResolvedValue(mockUser);
-  
-  const result = await saveUser(mockUser);
-  expect(result).toEqual(mockUser);
-  // Real business logic tested, only DB isolated
-});
+**The fix:**
+```
+TDD cycle:
+1. Write failing test
+2. Implement to pass
+3. Refactor
+4. THEN claim complete
 ```
 
-## Prevention Guidelines
+## When Mocks Become Too Complex
+
+**Warning signs:**
+- Mock setup longer than test logic
+- Mocking everything to make test pass
+- Mocks missing methods real components have
+- Test breaks when mock changes
+
+**your human partner's question:** "Do we need to be using a mock here?"
+
+**Consider:** Integration tests with real components often simpler than complex mocks
+
+## TDD Prevents These Anti-Patterns
+
+**Why TDD helps:**
+1. **Write test first** → Forces you to think about what you're actually testing
+2. **Watch it fail** → Confirms test tests real behavior, not mocks
+3. **Minimal implementation** → No test-only methods creep in
+4. **Real dependencies** → You see what the test actually needs before mocking
 
-**When writing tests:**
-- Test behavior, not implementation
-- Mock at the right level
-- Understand dependencies before mocking
-- Use real implementations where possible
+**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
 
-**When adding test utilities:**
-- Keep test-only code in test utilities
-- Don't pollute production classes
-- Separate test concerns from production logic
+## Quick Reference
 
-**When mocking:**
-- Understand what the mock does in reality
-- Preserve necessary side effects
-- Mock complete data structures
-- Mock at the lowest level possible
+| Anti-Pattern | Fix |
+|--------------|-----|
+| Assert on mock elements | Test real component or unmock it |
+| Test-only methods in production | Move to test utilities |
+| Mock without understanding | Understand dependencies first, mock minimally |
+| Incomplete mocks | Mirror real API completely |
+| Tests as afterthought | TDD - tests first |
+| Over-complex mocks | Consider integration tests |
 
-## Usage Examples
+## Red Flags
 
-**Before writing test:**
-`/testing-anti-patterns "writing integration test for user service"`
+- Assertion checks for `*-mock` test IDs
+- Methods only called in test files
+- Mock setup is >50% of test
+- Test fails when you remove mock
+- Can't explain why mock is needed
+- Mocking "just to be safe"
 
-**Before adding mock:**
-`/testing-anti-patterns "mocking external API call"`
+## The Bottom Line
 
-**Before adding test utility:**
-`/testing-anti-patterns "creating test cleanup helper"`
+**Mocks are tools to isolate, not things to test.**
 
-**When refactoring tests:**
-`/testing-anti-patterns "refactoring mock-heavy test suite"`
+If TDD reveals you're testing mock behavior, you've gone wrong.
 
-Remember: Following strict TDD prevents these anti-patterns naturally.
+Fix: Test real behavior or question why you're mocking at all.

package/packages/droid/commands/verification-before-completion.md

@@ -1,10 +1,32 @@
 ---
-description: Evidence before claims - verify work completion with fresh verification commands
-argument-hint: <work-claiming-to-complete>
+id: verification-before-completion
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+usage: /verification-before-completion <work-to-verify>
+auto_trigger: true
 ---
 
+# Verification Before Completion
+
+## Auto-Trigger
+
+**APPLIES WHEN:**
+- About to say: done, fixed, complete, passing, success
+- About to commit, push, create PR
+- About to mark task [x]
+
+**APPLIES TO:** All agents, all invocation paths
+
+**NEVER SKIP:** Even for "obvious" tasks
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
 **Core principle:** Evidence before claims, always.
 
+**Violating the letter of this rule is violating the spirit of this rule.**
+
 ## The Iron Law
 
 ```
@@ -29,89 +51,28 @@ BEFORE claiming any status or expressing satisfaction:
 Skip any step = lying, not verifying
 ```
 
-## Common Claims & Verification
-
-| Claim | Requires Verification | Not Sufficient |
-|-------|----------------------|----------------|
-| Tests pass | `npm test` output: 0 failures | "Previously passed" |
-| Linter clean | ESLint output: 0 errors | "Should be clean" |
-| Build succeeds | Build command: exit 0 | "Linter passed" |
-| Bug fixed | Test original symptom: passes | "Code changed" |
-| Regression test works | Red-green cycle verified | "Test passes" |
-| Requirements met | Line-by-line checklist completion | "Tests pass" |
-
-## Key Verification Patterns
-
-### Test Verification
-```bash
-# ✅ CORRECT
-npm test
-# See: "34/34 tests passing"
-"All tests pass"
-
-# ❌ WRONG  
-"Should pass now"
-"Looks correct"
-```
+## Common Failures
 
-### Build Verification
-```bash
-# ✅ CORRECT  
-npm run build
-# See: exit code 0
-"Build succeeds"
-
-# ❌ WRONG
-"Looks good"  
-"Linter was clean"
-```
-
-### Bug Fix Verification
-```bash
-# ✅ CORRECT
-# Re-create original bug scenario
-# See: bug no longer occurs
-"Bug fixed: original error no longer reproduces"
-
-# ❌ WRONG
-"Made the changes"
-"Code looks right"
-```
-
-### Regression Test (TDD Red-Green)
-```bash
-# ✅ CORRECT
-# Step 1: Write failing test
-# Step 2: Run test (must fail)
-# Step 3: Write minimal fix
-# Step 4: Run test (must pass) 
-# Step 5: Revert fix → Run (must fail)
-# Step 6: Restore fix → Run (must pass)
-"Red-green cycle verified"
-```
-
-### Requirements Verification
-```bash
-# ✅ CORRECT
-# Re-read requirements
-# Create verification checklist
-# Check each requirement against implementation
-# Report completion or gaps
-
-"Requirements verification complete:"
-"✅ Feature A implemented"
-"✅ Feature B implemented"  
-"❌ Feature C incomplete"
-```
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
 
 ## Red Flags - STOP
 
 - Using "should", "probably", "seems to"
-- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
 - About to commit/push/PR without verification
 - Trusting agent success reports
 - Relying on partial verification
-- **ANY wording implying success without verification**
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
 
 ## Rationalization Prevention
 
@@ -124,23 +85,64 @@ npm run build
 | "Agent said success" | Verify independently |
 | "I'm tired" | Exhaustion ≠ excuse |
 | "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
 
-## Usage Examples
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
 
-**Before claiming tests pass:**
-`/verification-before-completion "all unit tests passing"`
+## Why This Matters
 
-**Before claiming build succeeds:**
-`/verification-before-completion "production build working"`
+From 24 failure memories:
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
 
-**Before claiming bug fixed:**
-`/verification-before-completion "original error resolved"`
+## When To Apply
 
-**Before claiming requirements met:**
-`/verification-before-completion "feature specification fulfilled"`
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
 
-**Before committing code:**
-`/verification-before-completion "ready for commit"`
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
 
 ## The Bottom Line
 
@@ -148,4 +150,4 @@ npm run build
 
 Run the command. Read the output. THEN claim the result.
 
-This prevents false completion claims and maintains trust through evidence-based reporting.
+This is non-negotiable.