@amrhas82/agentic-kit 1.2.1 → 1.5.0

package/packages/opencode/command/test-driven-development.md

@@ -0,0 +1,231 @@
+---
+description: Write test first, watch it fail, write minimal code to pass - ensures tests actually verify behavior
+argument-hint: <feature-or-behavior-to-test>
+---
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+## When to Use
+
+**Always:**
+- New features
+- Bug fixes
+- Refactoring
+- Behavior changes
+
+**Exceptions:**
+- Throwaway prototypes
+- Generated code
+- Configuration files
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? Delete it. Start over.
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Delete means delete
+
+## Red-Green-Refactor Cycle
+
+### 1. RED - Write Failing Test
+
+Write one minimal test showing what should happen:
+
+```typescript
+// ✅ GOOD: Clear name, tests real behavior
+test('retries failed operations 3 times', async () => {
+  let attempts = 0;
+  const operation = () => {
+    attempts++;
+    if (attempts < 3) throw new Error('fail');
+    return 'success';
+  };
+
+  const result = await retryOperation(operation);
+
+  expect(result).toBe('success');
+  expect(attempts).toBe(3);
+});
+
+// ❌ BAD: Vague name, tests mock not code
+test('retry works', async () => {
+  const mock = jest.fn()
+    .mockRejectedValueOnce(new Error())
+    .mockRejectedValueOnce(new Error())
+    .mockResolvedValueOnce('success');
+  await retryOperation(mock);
+  expect(mock).toHaveBeenCalledTimes(3);
+});
+```
+
+**Requirements:**
+- One behavior per test
+- Clear name describing behavior
+- Real code (no mocks unless unavoidable)
+
+### 2. Verify RED - Watch It Fail
+
+**MANDATORY. Never skip.**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+Confirm:
+- Test fails (not errors)
+- Failure message is expected
+- Fails because feature missing (not typos)
+
+**Test passes?** You're testing existing behavior. Fix test.
+
+**Test errors?** Fix error, re-run until it fails correctly.
+
+### 3. GREEN - Minimal Code
+
+Write simplest code to pass the test:
+
+```typescript
+// ✅ GOOD: Just enough to pass
+async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
+  for (let i = 0; i < 3; i++) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (i === 2) throw e;
+    }
+  }
+  throw new Error('unreachable');
+}
+
+// ❌ BAD: Over-engineered
+async function retryOperation<T>(
+  fn: () => Promise<T>,
+  options?: {
+    maxRetries?: number;
+    backoff?: 'linear' | 'exponential';
+    onRetry?: (attempt: number) => void;
+  }
+): Promise<T> {
+  // YAGNI - not needed for this test
+}
+```
+
+Don't add features, refactor other code, or "improve" beyond the test.
+
+### 4. Verify GREEN - Watch It Pass
+
+**MANDATORY.**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+Confirm:
+- Test passes
+- Other tests still pass
+- Output pristine (no errors, warnings)
+
+**Test fails?** Fix code, not test.
+
+**Other tests fail?** Fix now.
+
+### 5. REFACTOR - Clean Up
+
+After green only:
+- Remove duplication
+- Improve names
+- Extract helpers
+- Maintain clear intent
+
+Keep tests green. Don't add behavior.
+
+### 6. Repeat
+
+Next failing test for next feature.
+
+## Good vs Bad 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 |
+
+## Test Structure
+
+```typescript
+// Arrange - Set up test data
+const input = { id: '123', name: 'Test' };
+
+// Act - Execute the behavior
+const result = await processUser(input);
+
+// Assert - Verify the outcome
+expect(result.id).toBe('123');
+expect(result.processed).toBe(true);
+expect(result.timestamp).toBeInstanceOf(Date);
+```
+
+## Common Patterns
+
+### Testing Error Cases
+```typescript
+test('throws error for invalid input', async () => {
+  const invalidInput = null;
+  
+  await expect(processUser(invalidInput))
+    .rejects
+    .toThrow('Invalid user data');
+});
+```
+
+### 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);
+});
+```
+
+### Testing Edge Cases
+```typescript
+test('handles empty array', () => {
+  const result = processItems([]);
+  
+  expect(result).toEqual([]);
+});
+
+test('handles single item', () => {
+  const result = processItems(['item']);
+  
+  expect(result).toHaveEqual(['processed-item']);
+});
+```
+
+## Usage Examples
+
+**Start new feature:**
+`/test-driven-development "user authentication"`
+
+**Fix existing bug:**
+`/test-driven-development "database connection error handling"`
+
+**Refactor code:**
+`/test-driven-development "legacy auth module"`
+
+**Behavior change:**
+`/test-driven-development "password reset flow"`
+
+Remember: TDD is a discipline. Every shortcut undermines the process.

package/packages/opencode/command/testing-anti-patterns.md

@@ -0,0 +1,248 @@
+---
+description: Avoid testing anti-patterns - never test mock behavior, add test-only methods, or mock without understanding
+argument-hint: <test-anti-pattern-to-avoid>
+---
+
+**Core principle:** Test what the code does, not what the mocks do.
+
+## The Iron Laws
+
+```
+1. NEVER test mock behavior
+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**
+```typescript
+test('renders sidebar', () => {
+  render(<Page />);
+  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
+});
+```
+
+**Why this is wrong:**
+- You're verifying the mock works, not that the component works
+- Test passes when mock is present, fails when it's not
+- Tells you nothing about real behavior
+
+**✅ CORRECT: Test real component behavior**
+```typescript
+test('renders sidebar', () => {
+  render(<Page />);  // Don't mock sidebar
+  expect(screen.getByRole('navigation')).toBeInTheDocument();
+});
+
+// OR if sidebar must be mocked for isolation:
+// Don't assert on the mock - test Page's behavior with sidebar present
+```
+
+### Gate Function
+```
+BEFORE asserting on any mock element:
+  Ask: "Am I testing real component behavior or just mock existence?"
+
+  IF testing mock existence:
+    STOP - Delete the assertion or unmock the component
+
+  Test real behavior instead
+```
+
+## Anti-Pattern 2: Test-Only Methods in Production
+
+**❌ WRONG: Production class polluted with test-only code**
+```typescript
+class Session {
+  async destroy() {  // Only used in tests
+    await this._workspaceManager?.destroyWorkspace(this.id);
+  }
+}
+
+// In tests
+afterEach(() => session.destroy());
+```
+
+**Why this is wrong:**
+- Production class polluted with test-only code
+- Dangerous if accidentally called in production
+- Violates YAGNI and separation of concerns
+- Confuses object lifecycle with entity lifecycle
+
+**✅ CORRECT: Test utilities handle test cleanup**
+```typescript
+// Session has no destroy() - it's stateless in production
+
+// In test-utils/
+export async function cleanupSession(session: Session) {
+  const workspace = session.getWorkspaceInfo();
+  if (workspace) {
+    await workspaceManager.destroyWorkspace(workspace.id);
+  }
+}
+
+// In tests
+afterEach(() => cleanupSession(session));
+```
+
+### Gate Function
+```
+BEFORE adding any method to production class:
+  Ask: "Is this only used by tests?"
+
+  IF yes:
+    STOP - Don't add it
+    Put it in test utilities instead
+```
+
+## Anti-Pattern 3: Mocking Without Understanding
+
+**❌ WRONG: Mock breaks test logic**
+```typescript
+test('detects duplicate server', () => {
+  vi.mock('ToolCatalog', () => ({
+    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
+  }));
+
+  await addServer(config);
+  await addServer(config);  // Should throw - but won't!
+});
+```
+
+**Why this is wrong:**
+- Mocked method had side effect test depended on (writing config)
+- Over-mocking to "be safe" breaks actual behavior
+- Test passes for wrong reason or fails mysteriously
+
+**✅ CORRECT: Mock at correct level**
+```typescript
+test('detects duplicate server', () => {
+  // Mock the slow part, preserve behavior test needs
+  vi.mock('MCPServerManager'); // Just mock slow server startup
+
+  await addServer(config);  // Config written
+  await addServer(config);  // Duplicate detected ✓
+});
+```
+
+### Gate Function
+```
+BEFORE mocking any method:
+  STOP - Don't mock yet
+
+  1. Ask: "What side effects does the real method have?"
+  2. Ask: "Does this test depend on any of those side effects?"
+  3. Ask: "Do I fully understand what this test needs?"
+
+  IF depends on side effects:
+    Mock at lower level (the actual slow/external operation)
+    OR use test doubles that preserve necessary behavior
+    NOT the high-level method the test depends on
+
+  Red flags:
+    - "I'll mock this to be safe"
+    - "This might be slow, better mock it"
+    - Mocking without understanding the dependency chain
+```
+
+## Anti-Pattern 4: Incomplete Mocks
+
+**❌ WRONG: Partial mock structure**
+```typescript
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' }
+  // Missing: metadata that downstream code uses
+};
+
+// Later: breaks when code accesses response.metadata.requestId
+```
+
+**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
+
+**✅ CORRECT: Mock complete data structures**
+```typescript
+// Mock the COMPLETE data structure as it exists in reality
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' },
+  metadata: { requestId: 'req-456', timestamp: '2024-01-01' },
+  headers: { 'content-type': 'application/json' }
+};
+```
+
+## Anti-Pattern 5: Over-Mocking
+
+**❌ 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);
+});
+```
+
+**Why this is wrong:**
+- Testing mock behavior, not real behavior
+- No integration verification
+- Easy to pass incorrect implementation
+
+**✅ 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
+});
+```
+
+## Prevention Guidelines
+
+**When writing tests:**
+- Test behavior, not implementation
+- Mock at the right level
+- Understand dependencies before mocking
+- Use real implementations where possible
+
+**When adding test utilities:**
+- Keep test-only code in test utilities
+- Don't pollute production classes
+- Separate test concerns from production logic
+
+**When mocking:**
+- Understand what the mock does in reality
+- Preserve necessary side effects
+- Mock complete data structures
+- Mock at the lowest level possible
+
+## Usage Examples
+
+**Before writing test:**
+`/testing-anti-patterns "writing integration test for user service"`
+
+**Before adding mock:**
+`/testing-anti-patterns "mocking external API call"`
+
+**Before adding test utility:**
+`/testing-anti-patterns "creating test cleanup helper"`
+
+**When refactoring tests:**
+`/testing-anti-patterns "refactoring mock-heavy test suite"`
+
+Remember: Following strict TDD prevents these anti-patterns naturally.

package/packages/opencode/command/theme-factory.md

@@ -0,0 +1,146 @@
+---
+description: Apply professional themes to artifacts - 10 curated themes with color palettes and font pairings
+argument-hint: <artifact-type> <theme-choice>
+---
+
+Apply consistent, professional styling to presentations, documents, reports, and HTML pages with curated themes.
+
+## Available Themes
+
+The following 10 professionally designed themes are available:
+
+1. **Ocean Depths** - Professional and calming maritime theme
+2. **Sunset Boulevard** - Warm and vibrant sunset colors  
+3. **Forest Canopy** - Natural and grounded earth tones
+4. **Modern Minimalist** - Clean and contemporary grayscale
+5. **Golden Hour** - Rich and warm autumnal palette
+6. **Arctic Frost** - Cool and crisp winter-inspired theme
+7. **Desert Rose** - Soft and sophisticated dusty tones
+8. **Tech Innovation** - Bold and modern tech aesthetic
+9. **Botanical Garden** - Fresh and organic garden colors
+10. **Midnight Galaxy** - Dramatic and cosmic deep tones
+
+## Application Process
+
+### Step 1: Show Theme Showcase
+Display the `theme-showcase.pdf` file to allow users to see all available themes visually.
+
+### Step 2: Ask for Theme Selection
+Ask which theme to apply to the artifact.
+
+### Step 3: Wait for Confirmation
+Get explicit confirmation about the chosen theme.
+
+### Step 4: Apply the Theme
+Apply the selected theme's colors and fonts consistently throughout the artifact.
+
+## Theme Structure
+
+Each theme includes:
+- **Cohesive color palette** with hex codes
+- **Complementary font pairings** for headers and body text  
+- **Distinct visual identity** suitable for different contexts and audiences
+
+## Usage Guidelines
+
+### Theme Selection
+- Consider the artifact's purpose and audience
+- Match theme personality to content tone
+- Ensure proper contrast and readability
+- Maintain visual consistency across all elements
+
+### Application Standards
+- Apply colors consistently throughout
+- Use specified fonts for headers and body text
+- Ensure proper contrast ratios
+- Maintain the theme's visual identity
+
+## Custom Theme Creation
+
+When existing themes don't fit the artifact:
+
+### Generate Custom Theme
+Based on provided inputs:
+1. Create a new theme similar to existing ones
+2. Choose appropriate colors and fonts based on description
+3. Give the theme a descriptive name
+4. Apply the same structure as existing themes
+
+### Theme Specification Format
+```markdown
+# Theme Name
+
+## Color Palette
+- Primary: #hexcode
+- Secondary: #hexcode
+- Accent: #hexcode
+- Background: #hexcode
+- Text: #hexcode
+
+## Typography
+- Headers: Font Name
+- Body: Font Name
+
+## Usage Guidelines
+- When to use this theme
+- Best practices for application
+```
+
+## Artifact Types
+
+### Presentations
+- Apply theme to slide backgrounds
+- Use theme colors for charts and graphics
+- Apply fonts to titles and content
+- Maintain consistency across all slides
+
+### Documents
+- Apply theme colors to headings and accents
+- Use theme fonts for typography
+- Apply to charts, graphs, and visual elements
+- Maintain professional appearance
+
+### HTML Pages
+- Apply theme colors to CSS variables
+- Use theme fonts via web font imports
+- Apply to buttons, links, and UI elements
+- Ensure responsive design compatibility
+
+### Reports
+- Apply theme to headers and sections
+- Use colors for data visualization
+- Apply fonts for readability
+- Maintain data clarity
+
+## Quality Standards
+
+### Visual Consistency
+- Apply theme uniformly across all elements
+- Maintain proper spacing and alignment
+- Ensure color contrast meets accessibility standards
+- Use fonts consistently according to guidelines
+
+### Professional Appearance
+- Choose appropriate theme for audience
+- Maintain visual hierarchy
+- Ensure readability and accessibility
+- Create cohesive visual experience
+
+## Usage Examples
+
+**Style presentation slides:**
+`/theme-factory "presentation slides" "modern-minimalist"`
+
+**Apply theme to report:**
+`/theme-factory "quarterly report" "ocean-depths"`
+
+**Create themed HTML page:**
+`/theme-factory "landing page" "tech-innovation"`
+
+**Style document template:**
+`/theme-factory "proposal document" "golden-hour"`
+
+**Generate custom theme:**
+`/theme-factory "custom theme" "create-from-description: fintech blue and white"`
+
+Remember: Theme selection should enhance the content's message and suit the intended audience.