@amrhas82/agentic-kit 1.5.0 → 1.7.5

package/packages/droid/commands/test-driven-development.md

@@ -1,10 +1,44 @@
 ---
-description: Write test first, watch it fail, write minimal code to pass - ensures tests actually verify behavior
-argument-hint: <feature-or-behavior-to-test>
+name: test-driven-development
+description: Use when implementing any feature or bugfix, before writing implementation code - write the test first, watch it fail, write minimal code to pass; ensures tests actually verify behavior by requiring failure first
 ---
 
+# Test-Driven Development (TDD)
+
+## Auto-Trigger
+
+**APPLIES WHEN:**
+- About to write new production code (function, method, class)
+- Implementing any feature or bug fix
+- Modifying behavior of existing code
+- Task metadata includes `tdd: yes`
+- User requests feature implementation
+
+**APPLIES TO:**
+- All production code changes
+- Feature implementations
+- Bug fixes
+- Refactoring that changes behavior
+- API endpoint creation
+- Model/class creation
+
+**DOES NOT APPLY TO:**
+- Documentation files
+- Configuration files (unless logic-bearing)
+- Throwaway prototypes (with explicit user permission)
+- Generated code (with explicit user permission)
+
+**ENFORCEMENT:**
+If you find yourself writing implementation code before tests, STOP immediately. Delete the implementation and start over with TDD.
+
+## Overview
+
+Write the test first. Watch it fail. Write minimal code to pass.
+
 **Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
 
+**Violating the letter of the rules is violating the spirit of the rules.**
+
 ## When to Use
 
 **Always:**
@@ -13,11 +47,13 @@ argument-hint: <feature-or-behavior-to-test>
 - Refactoring
 - Behavior changes
 
-**Exceptions:**
+**Exceptions (ask your human partner):**
 - Throwaway prototypes
 - Generated code
 - Configuration files
 
+Thinking "skip TDD just this once"? Stop. That's rationalization.
+
 ## The Iron Law
 
 ```
@@ -29,16 +65,41 @@ Write code before the 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
 
-## Red-Green-Refactor Cycle
+Implement fresh from tests. Period.
+
+## Red-Green-Refactor
+
+```dot
+digraph tdd_cycle {
+    rankdir=LR;
+    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
+    verify_red [label="Verify fails\ncorrectly", shape=diamond];
+    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
+    verify_green [label="Verify passes\nAll green", shape=diamond];
+    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
+    next [label="Next", shape=ellipse];
+
+    red -> verify_red;
+    verify_red -> green [label="yes"];
+    verify_red -> red [label="wrong\nfailure"];
+    green -> verify_green;
+    verify_green -> refactor [label="yes"];
+    verify_green -> green [label="no"];
+    refactor -> verify_green [label="stay\ngreen"];
+    verify_green -> next;
+    next -> red;
+}
+```
 
-### 1. RED - Write Failing Test
+### RED - Write Failing Test
 
-Write one minimal test showing what should happen:
+Write one minimal test showing what should happen.
 
+<Good>
 ```typescript
-// ✅ GOOD: Clear name, tests real behavior
 test('retries failed operations 3 times', async () => {
   let attempts = 0;
   const operation = () => {
@@ -52,8 +113,12 @@ test('retries failed operations 3 times', async () => {
   expect(result).toBe('success');
   expect(attempts).toBe(3);
 });
+```
+Clear name, tests real behavior, one thing
+</Good>
 
-// ❌ BAD: Vague name, tests mock not code
+<Bad>
+```typescript
 test('retry works', async () => {
   const mock = jest.fn()
     .mockRejectedValueOnce(new Error())
@@ -63,13 +128,15 @@ test('retry works', async () => {
   expect(mock).toHaveBeenCalledTimes(3);
 });
 ```
+Vague name, tests mock not code
+</Bad>
 
 **Requirements:**
-- One behavior per test
-- Clear name describing behavior
+- One behavior
+- Clear name
 - Real code (no mocks unless unavoidable)
 
-### 2. Verify RED - Watch It Fail
+### Verify RED - Watch It Fail
 
 **MANDATORY. Never skip.**
 
@@ -86,12 +153,12 @@ Confirm:
 
 **Test errors?** Fix error, re-run until it fails correctly.
 
-### 3. GREEN - Minimal Code
+### GREEN - Minimal Code
 
-Write simplest code to pass the test:
+Write simplest code to pass the test.
 
+<Good>
 ```typescript
-// ✅ GOOD: Just enough to pass
 async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
   for (let i = 0; i < 3; i++) {
     try {
@@ -102,8 +169,12 @@ async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
   }
   throw new Error('unreachable');
 }
+```
+Just enough to pass
+</Good>
 
-// ❌ BAD: Over-engineered
+<Bad>
+```typescript
 async function retryOperation<T>(
   fn: () => Promise<T>,
   options?: {
@@ -112,13 +183,15 @@ async function retryOperation<T>(
     onRetry?: (attempt: number) => void;
   }
 ): Promise<T> {
-  // YAGNI - not needed for this test
+  // YAGNI
 }
 ```
+Over-engineered
+</Bad>
 
 Don't add features, refactor other code, or "improve" beyond the test.
 
-### 4. Verify GREEN - Watch It Pass
+### Verify GREEN - Watch It Pass
 
 **MANDATORY.**
 
@@ -135,97 +208,183 @@ Confirm:
 
 **Other tests fail?** Fix now.
 
-### 5. REFACTOR - Clean Up
+### REFACTOR - Clean Up
 
 After green only:
 - Remove duplication
 - Improve names
 - Extract helpers
-- Maintain clear intent
 
 Keep tests green. Don't add behavior.
 
-### 6. Repeat
+### Repeat
 
 Next failing test for next feature.
 
-## Good vs Bad Tests
+## Good Tests
 
-| Aspect | Good Tests | Bad Tests |
-|--------|------------|-----------|
-| **Focus** | Behavior | Implementation |
-| **Names** | Describe what happens | Describe what it does |
-| **Structure** | Arrange-Act-Assert | Random order |
-| **Isolation** | Independent, no shared state | Shared fixtures |
-| **Speed** | Fast (<100ms) | Slow, flaky |
+| Quality | Good | Bad |
+|---------|------|-----|
+| **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
+| **Clear** | Name describes behavior | `test('test1')` |
+| **Shows intent** | Demonstrates desired API | Obscures what code should do |
 
-## Test Structure
+## Why Order Matters
 
-```typescript
-// Arrange - Set up test data
-const input = { id: '123', name: 'Test' };
+**"I'll write tests after to verify it works"**
 
-// Act - Execute the behavior
-const result = await processUser(input);
+Tests written after code pass immediately. Passing immediately proves nothing:
+- Might test wrong thing
+- Might test implementation, not behavior
+- Might miss edge cases you forgot
+- You never saw it catch the bug
 
-// Assert - Verify the outcome
-expect(result.id).toBe('123');
-expect(result.processed).toBe(true);
-expect(result.timestamp).toBeInstanceOf(Date);
-```
+Test-first forces you to see the test fail, proving it actually tests something.
+
+**"I already manually tested all the edge cases"**
+
+Manual testing is ad-hoc. You think you tested everything but:
+- No record of what you tested
+- Can't re-run when code changes
+- Easy to forget cases under pressure
+- "It worked when I tried it" ≠ comprehensive
+
+Automated tests are systematic. They run the same way every time.
+
+**"Deleting X hours of work is wasteful"**
+
+Sunk cost fallacy. The time is already gone. Your choice now:
+- Delete and rewrite with TDD (X more hours, high confidence)
+- Keep it and add tests after (30 min, low confidence, likely bugs)
+
+The "waste" is keeping code you can't trust. Working code without real tests is technical debt.
+
+**"TDD is dogmatic, being pragmatic means adapting"**
+
+TDD IS pragmatic:
+- Finds bugs before commit (faster than debugging after)
+- Prevents regressions (tests catch breaks immediately)
+- Documents behavior (tests show how to use code)
+- Enables refactoring (change freely, tests catch breaks)
+
+"Pragmatic" shortcuts = debugging in production = slower.
+
+**"Tests after achieve the same goals - it's spirit not ritual"**
 
-## Common Patterns
+No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"
 
-### Testing Error Cases
+Tests-after are biased by your implementation. You test what you built, not what's required. You verify remembered edge cases, not discovered ones.
+
+Tests-first force edge case discovery before implementing. Tests-after verify you remembered everything (you didn't).
+
+30 minutes of tests after ≠ TDD. You get coverage, lose proof tests work.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing. |
+| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
+| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
+| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
+| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
+| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
+| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
+| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
+| "Existing code has no tests" | You're improving it. Add tests for existing code. |
+
+## Red Flags - STOP and Start Over
+
+- Code before test
+- Test after implementation
+- Test passes immediately
+- Can't explain why test failed
+- Tests added "later"
+- Rationalizing "just this once"
+- "I already manually tested it"
+- "Tests after achieve the same purpose"
+- "It's about spirit not ritual"
+- "Keep as reference" or "adapt existing code"
+- "Already spent X hours, deleting is wasteful"
+- "TDD is dogmatic, I'm being pragmatic"
+- "This is different because..."
+
+**All of these mean: Delete code. Start over with TDD.**
+
+## Example: Bug Fix
+
+**Bug:** Empty email accepted
+
+**RED**
 ```typescript
-test('throws error for invalid input', async () => {
-  const invalidInput = null;
-  
-  await expect(processUser(invalidInput))
-    .rejects
-    .toThrow('Invalid user data');
+test('rejects empty email', async () => {
+  const result = await submitForm({ email: '' });
+  expect(result.error).toBe('Email required');
 });
 ```
 
-### Testing Async Operations
-```typescript
-test('saves user asynchronously', async () => {
-  const user = { name: 'John' };
-  
-  const result = await saveUser(user);
-  
-  expect(result.id).toBeDefined();
-  expect(database.save).toHaveBeenCalledWith(user);
-});
+**Verify RED**
+```bash
+$ npm test
+FAIL: expected 'Email required', got undefined
 ```
 
-### Testing Edge Cases
+**GREEN**
 ```typescript
-test('handles empty array', () => {
-  const result = processItems([]);
-  
-  expect(result).toEqual([]);
-});
+function submitForm(data: FormData) {
+  if (!data.email?.trim()) {
+    return { error: 'Email required' };
+  }
+  // ...
+}
+```
 
-test('handles single item', () => {
-  const result = processItems(['item']);
-  
-  expect(result).toHaveEqual(['processed-item']);
-});
+**Verify GREEN**
+```bash
+$ npm test
+PASS
 ```
 
-## Usage Examples
+**REFACTOR**
+Extract validation for multiple fields if needed.
+
+## Verification Checklist
+
+Before marking work complete:
 
-**Start new feature:**
-`/test-driven-development "user authentication"`
+- [ ] Every new function/method has a test
+- [ ] Watched each test fail before implementing
+- [ ] Each test failed for expected reason (feature missing, not typo)
+- [ ] Wrote minimal code to pass each test
+- [ ] All tests pass
+- [ ] Output pristine (no errors, warnings)
+- [ ] Tests use real code (mocks only if unavoidable)
+- [ ] Edge cases and errors covered
 
-**Fix existing bug:**
-`/test-driven-development "database connection error handling"`
+Can't check all boxes? You skipped TDD. Start over.
 
-**Refactor code:**
-`/test-driven-development "legacy auth module"`
+## When Stuck
 
-**Behavior change:**
-`/test-driven-development "password reset flow"`
+| Problem | Solution |
+|---------|----------|
+| Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. |
+| Test too complicated | Design too complicated. Simplify interface. |
+| Must mock everything | Code too coupled. Use dependency injection. |
+| Test setup huge | Extract helpers. Still complex? Simplify design. |
+
+## Debugging Integration
+
+Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
+
+Never fix bugs without a test.
+
+## Final Rule
+
+```
+Production code → test exists and failed first
+Otherwise → not TDD
+```
 
-Remember: TDD is a discipline. Every shortcut undermines the process.
+No exceptions without your human partner's permission.

package/packages/droid/commands/test-generate.md

@@ -0,0 +1,19 @@
+---
+id: test-generate
+name: test-generate
+description: Generate tests [file]
+usage: /test-generate <code-section>
+argument-hint: [file-to-test]
+---
+Generate tests for $ARGUMENTS.
+
+## Include
+- Happy path (expected usage)
+- Edge cases (empty, null, boundaries)
+- Error scenarios (invalid input, failures)
+- Integration points (mocks for external deps)
+
+## Requirements
+- Match existing test patterns in this project
+- Use the testing framework already in use
+- Clear test names: "should [expected] when [condition]"