opencode-agile-agent 1.0.1

package/templates/.opencode/skills/plan-writing/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: plan-writing
+description: Structured planning and task breakdown techniques.
+version: 1.0.0
+---
+
+# Plan Writing
+
+Structured approaches to creating plans, breaking down tasks, and defining success criteria.
+
+## Plan Structure
+
+### Minimal Plan Template
+
+```markdown
+# PLAN: [Feature Name]
+
+## What
+Brief description of what we're building.
+
+## Why
+Business justification and user value.
+
+## How
+High-level technical approach.
+
+## Tasks
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Task 3
+
+## Success Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+```
+
+### Comprehensive Plan Template
+
+```markdown
+# PLAN: [Feature Name]
+
+## Executive Summary
+One paragraph overview.
+
+## Problem Statement
+What problem are we solving?
+
+## Proposed Solution
+How will we solve it?
+
+## User Stories
+1. As a [user], I want [goal] so that [benefit]
+2. ...
+
+## Technical Design
+### Architecture
+[Diagram or description]
+
+### API Design
+[Endpoints/contracts]
+
+### Data Model
+[Schema/ERD]
+
+## Implementation Plan
+### Phase 1: Foundation
+- [ ] Task 1.1
+- [ ] Task 1.2
+
+### Phase 2: Core Features
+- [ ] Task 2.1
+- [ ] Task 2.2
+
+### Phase 3: Polish
+- [ ] Task 3.1
+- [ ] Task 3.2
+
+## Dependencies
+- Dependency 1
+- Dependency 2
+
+## Risks & Mitigations
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| ... | ... | ... | ... |
+
+## Success Metrics
+| Metric | Target | How Measured |
+|--------|--------|--------------|
+| ... | ... | ... |
+
+## Timeline
+- Phase 1: [dates]
+- Phase 2: [dates]
+- Phase 3: [dates]
+
+## Open Questions
+1. [Question] - Owner: [name]
+2. [Question] - Owner: [name]
+
+## Appendix
+- [Supporting documents]
+- [Research notes]
+```
+
+## Task Breakdown
+
+### WBS (Work Breakdown Structure)
+
+```
+Feature: User Authentication
+├── 1. Registration
+│   ├── 1.1 Registration form UI
+│   ├── 1.2 Form validation
+│   ├── 1.3 API endpoint
+│   ├── 1.4 Email verification
+│   └── 1.5 Password hashing
+├── 2. Login
+│   ├── 2.1 Login form UI
+│   ├── 2.2 JWT generation
+│   ├── 2.3 Session management
+│   └── 2.4 Logout flow
+└── 3. Password Reset
+    ├── 3.1 Forgot password form
+    ├── 3.2 Reset token generation
+    └── 3.3 Reset password form
+```
+
+### Task Sizing
+
+| Size | Duration | Characteristics |
+|------|----------|-----------------|
+| **XS** | < 1 hour | Typo fix, config change |
+| **S** | 1-4 hours | Simple component, small fix |
+| **M** | 4-8 hours | Feature with multiple parts |
+| **L** | 1-2 days | Complex feature, multiple files |
+| **XL** | 2-5 days | Major feature, needs breakdown |
+
+### Dependency Mapping
+
+```markdown
+Task Dependencies:
+
+A ─────► B ─────► D
+         │
+         └───────► C ─────► E
+
+Execution Order:
+1. A (no dependencies)
+2. B (depends on A)
+3. C (depends on B)
+4. D (depends on B)
+5. E (depends on C)
+```
+
+## Success Criteria
+
+### SMART Criteria
+
+| Letter | Meaning | Example |
+|--------|---------|---------|
+| **S**pecific | Clear and precise | "Reduce load time" → "Reduce LCP to < 2.5s" |
+| **M**easurable | Quantifiable | "Improve UX" → "Increase conversion by 10%" |
+| **A**chievable | Realistic | Based on resources and constraints |
+| **R**elevant | Aligned with goals | Supports business objectives |
+| **T**ime-bound | Has deadline | "Complete by Q2" |
+
+### Acceptance Criteria Template
+
+```markdown
+## User Story
+As a [user type], I want [goal] so that [benefit]
+
+## Acceptance Criteria
+- [ ] Given [context], when [action], then [outcome]
+- [ ] Given [context], when [action], then [outcome]
+- [ ] Given [context], when [action], then [outcome]
+
+## Edge Cases
+- [ ] Handle [edge case]
+- [ ] Handle [edge case]
+
+## Non-Functional
+- [ ] Performance: [requirement]
+- [ ] Security: [requirement]
+- [ ] Accessibility: [requirement]
+```
+
+## Risk Assessment
+
+### Risk Matrix
+
+```
+              IMPACT
+           Low    Med    High
+         ┌──────┬──────┬──────┐
+    High │Monitor│Plan  │Act   │
+LIK      ├──────┼──────┼──────┤
+    Med  │Accept │Monitor│Plan │
+         ├──────┼──────┼──────┤
+    Low  │Accept │Accept │Monitor│
+         └──────┴──────┴──────┘
+```
+
+### Risk Register Template
+
+```markdown
+| ID | Risk | Likelihood | Impact | Score | Mitigation | Owner |
+|----|------|------------|--------|-------|------------|-------|
+| R1 | API changes | Medium | High | 6 | Version lock | Dev |
+| R2 | Staff change | Low | High | 3 | Documentation | PM |
+```
+
+## Estimation Techniques
+
+### Planning Poker
+
+```
+Team members estimate:
+- Developer A: 5
+- Developer B: 8
+- Developer C: 5
+- Developer D: 13
+
+Discuss high/low outliers, reach consensus.
+```
+
+### Three-Point Estimation
+
+```
+Optimistic (O): 2 days
+Most Likely (M): 4 days
+Pessimistic (P): 8 days
+
+Expected = (O + 4M + P) / 6 = (2 + 16 + 8) / 6 = 4.33 days
+```
+
+## Plan Review Checklist
+
+- [ ] **Clear Objective**: What and why are clear
+- [ ] **Complete Breakdown**: All tasks identified
+- [ ] **Dependencies Mapped**: Order is logical
+- [ ] **Sized Appropriately**: Tasks are achievable
+- [ ] **Success Criteria**: Measurable outcomes defined
+- [ ] **Risks Identified**: Major risks documented
+- [ ] **Timeline Realistic**: Based on estimates
+- [ ] **Stakeholders Aligned**: Key people approve
+
+---
+
+**A good plan eliminates ambiguity and enables execution.**

package/templates/.opencode/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: systematic-debugging
+description: Methodical approach to identifying and fixing bugs.
+version: 1.0.0
+---
+
+# Systematic Debugging
+
+A methodical approach to finding and fixing bugs efficiently.
+
+## Debugging Methodology
+
+### The Scientific Method
+
+1. **Observe** - What's the symptom?
+2. **Hypothesize** - What could cause this?
+3. **Test** - Verify or disprove hypothesis
+4. **Repeat** - Until root cause found
+5. **Fix** - Address the root cause
+6. **Verify** - Confirm fix works
+7. **Document** - Record for future
+
+## Step-by-Step Process
+
+### Step 1: Reproduce
+
+```markdown
+Document exact steps:
+1. Open browser
+2. Navigate to /dashboard
+3. Click "Export" button
+4. Error appears
+
+Environment:
+- Browser: Chrome 120
+- OS: macOS 14
+- Node: v20.10.0
+```
+
+### Step 2: Gather Information
+
+```bash
+# Check logs
+tail -f /var/log/app.log
+
+# Check recent changes
+git log --oneline -10
+
+# Check error stack trace
+Error: Cannot read property 'map' of undefined
+    at exportData (src/utils/export.ts:45)
+    at handleClick (src/components/ExportButton.tsx:23)
+```
+
+### Step 3: Hypothesize
+
+```markdown
+Possible causes (ranked by likelihood):
+1. data is null/undefined when exportData is called
+2. data structure changed but exportData not updated
+3. Race condition in data loading
+4. API returning unexpected format
+```
+
+### Step 4: Test Hypotheses
+
+```typescript
+// Add defensive logging
+console.log('exportData called with:', { data, type: typeof data });
+
+// Add type guard
+if (!data || !Array.isArray(data)) {
+  console.error('Invalid data for export:', data);
+  return;
+}
+```
+
+### Step 5: Fix Root Cause
+
+```typescript
+// ❌ Fix symptom only
+const items = data?.items || []; // Hides the real problem
+
+// ✅ Fix root cause
+// Investigate WHY data is undefined and fix upstream
+async function loadData() {
+  const response = await fetch('/api/data');
+  if (!response.ok) {
+    throw new Error(`Failed to load data: ${response.status}`);
+  }
+  return response.json();
+}
+```
+
+## Common Bug Patterns
+
+### Null/Undefined Errors
+
+```typescript
+// ❌ Crashes on null
+const name = user.profile.name;
+
+// ✅ Safe access
+const name = user?.profile?.name ?? 'Unknown';
+```
+
+### Race Conditions
+
+```typescript
+// ❌ Race condition
+let data;
+fetchData().then(result => { data = result; });
+console.log(data); // undefined!
+
+// ✅ Proper async handling
+const data = await fetchData();
+console.log(data);
+```
+
+### State Sync Issues
+
+```typescript
+// ❌ Stale closure
+const [count, setCount] = useState(0);
+useEffect(() => {
+  const interval = setInterval(() => {
+    console.log(count); // Always 0!
+  }, 1000);
+  return () => clearInterval(interval);
+}, []);
+
+// ✅ Use ref or dependency
+const countRef = useRef(count);
+countRef.current = count;
+// Or add count to dependencies
+```
+
+## Debugging Tools
+
+### Console Debugging
+
+```typescript
+// Strategic logging
+console.log('1. Before fetch');
+const data = await fetch(url);
+console.log('2. After fetch:', data);
+const processed = processData(data);
+console.log('3. After process:', processed);
+
+// Performance timing
+console.time('operation');
+doSomething();
+console.timeEnd('operation');
+```
+
+### Browser DevTools
+
+```
+1. Sources panel - Set breakpoints
+2. Network panel - Check API calls
+3. Console - Run expressions
+4. React DevTools - Component tree
+5. Performance - Record profile
+```
+
+### Node.js Debugging
+
+```bash
+# Inspector mode
+node --inspect app.js
+
+# Then open chrome://inspect
+```
+
+## Debugging Checklist
+
+- [ ] **Reproduced**: Can consistently reproduce
+- [ ] **Isolated**: Narrowed to specific area
+- [ ] **Root cause**: Understand WHY
+- [ ] **Fix implemented**: Addresses cause, not symptom
+- [ ] **Verified**: Fix resolves the issue
+- [ ] **No regressions**: Other functionality intact
+- [ ] **Tests added**: Prevents future occurrences
+
+## Anti-Patterns to Avoid
+
+### Shotgun Debugging
+
+```
+❌ Change random things hoping it works
+✅ Change one thing at a time, verify each
+```
+
+### Console.log Everything
+
+```
+❌ console.log everywhere
+✅ Strategic, minimal logging with context
+```
+
+### Fix Symptom, Not Cause
+
+```
+❌ Add null check to hide error
+✅ Find why null occurs and fix upstream
+```
+
+---
+
+**Systematic debugging finds root causes faster.**

package/templates/.opencode/skills/testing-patterns/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: testing-patterns
+description: Testing strategies, patterns, and best practices for unit, integration, and E2E tests.
+version: 1.0.0
+---
+
+# Testing Patterns
+
+Comprehensive testing strategies and best practices.
+
+## Testing Pyramid
+
+```
+        /\
+       /E2E\      Few, slow, critical paths
+      /------\    
+     /  API   \   Some, integration tests
+    /----------\
+   /   Unit     \  Many, fast, isolated
+  /--------------\
+```
+
+## Unit Testing
+
+### AAA Pattern
+
+```typescript
+describe('calculateTotal', () => {
+  it('should sum item prices', () => {
+    // Arrange
+    const items = [{ price: 10 }, { price: 20 }];
+    
+    // Act
+    const result = calculateTotal(items);
+    
+    // Assert
+    expect(result).toBe(30);
+  });
+});
+```
+
+### Test Edge Cases
+
+```typescript
+describe('calculateTotal', () => {
+  it('should handle empty array', () => {
+    expect(calculateTotal([])).toBe(0);
+  });
+  
+  it('should handle null', () => {
+    expect(calculateTotal(null)).toBe(0);
+  });
+  
+  it('should handle negative prices', () => {
+    expect(calculateTotal([{ price: -5 }])).toBe(-5);
+  });
+});
+```
+
+### Mocking
+
+```typescript
+// Mock external dependency
+jest.mock('./api');
+api.fetchUser.mockResolvedValue({ id: 1, name: 'Test' });
+
+// Mock function
+const mockCallback = jest.fn();
+mockCallback.mockReturnValue(true);
+mockCallback.mockImplementation(x => x * 2);
+```
+
+## Integration Testing
+
+### API Testing
+
+```typescript
+describe('POST /api/users', () => {
+  it('should create user with valid data', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ name: 'Test', email: 'test@example.com' });
+    
+    expect(response.status).toBe(201);
+    expect(response.body.data.name).toBe('Test');
+  });
+  
+  it('should reject invalid email', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ name: 'Test', email: 'invalid' });
+    
+    expect(response.status).toBe(400);
+  });
+});
+```
+
+### Database Testing
+
+```typescript
+describe('UserService', () => {
+  beforeAll(async () => {
+    await setupTestDatabase();
+  });
+  
+  afterAll(async () => {
+    await teardownTestDatabase();
+  });
+  
+  beforeEach(async () => {
+    await clearDatabase();
+  });
+  
+  it('should create user', async () => {
+    const user = await UserService.create({ name: 'Test' });
+    expect(user.id).toBeDefined();
+  });
+});
+```
+
+## E2E Testing
+
+### Page Object Model
+
+```typescript
+// pages/LoginPage.ts
+export class LoginPage {
+  constructor(private page: Page) {}
+  
+  async goto() {
+    await this.page.goto('/login');
+  }
+  
+  async login(email: string, password: string) {
+    await this.page.fill('[data-testid="email"]', email);
+    await this.page.fill('[data-testid="password"]', password);
+    await this.page.click('[data-testid="login-btn"]');
+  }
+}
+
+// tests/auth.spec.ts
+test('should login successfully', async ({ page }) => {
+  const loginPage = new LoginPage(page);
+  await loginPage.goto();
+  await loginPage.login('user@example.com', 'password');
+  
+  await expect(page).toHaveURL('/dashboard');
+});
+```
+
+### Test Selectors
+
+```typescript
+// ❌ Brittle
+await page.locator('.card > .title').click();
+
+// ✅ Resilient
+await page.locator('[data-testid="product-title"]').click();
+```
+
+## Test Organization
+
+```
+tests/
+├── unit/
+│   ├── utils/
+│   │   └── calculate.test.ts
+│   └── components/
+│       └── Button.test.tsx
+├── integration/
+│   ├── api/
+│   │   └── users.test.ts
+│   └── services/
+│       └── auth.test.ts
+└── e2e/
+    ├── auth.spec.ts
+    └── checkout.spec.ts
+```
+
+## Coverage Guidelines
+
+| Type | Target |
+|------|--------|
+| Statements | 80% |
+| Branches | 75% |
+| Functions | 85% |
+| Lines | 80% |
+
+## Best Practices
+
+### Descriptive Names
+
+```typescript
+// ❌ Vague
+test('user', () => {});
+
+// ✅ Descriptive
+test('should create user with valid email', () => {});
+```
+
+### One Concept Per Test
+
+```typescript
+// ❌ Multiple concepts
+test('user operations', () => {
+  // Test create
+  // Test update
+  // Test delete
+});
+
+// ✅ One concept
+test('should create user', () => {});
+test('should update user', () => {});
+test('should delete user', () => {});
+```
+
+### Test Behavior, Not Implementation
+
+```typescript
+// ❌ Tests implementation
+expect(component.state.count).toBe(1);
+
+// ✅ Tests behavior
+expect(screen.getByText('Count: 1')).toBeInTheDocument();
+```
+
+## Anti-Patterns
+
+### Testing Implementation
+
+```
+❌ Test that function calls internal helper
+✅ Test the output/behavior
+```
+
+### Shared State
+
+```
+❌ Tests that depend on each other
+✅ Each test is independent
+```
+
+### Overspecifying
+
+```
+❌ Assert every property
+✅ Assert essential behavior
+```
+
+---
+
+**Good tests enable confident refactoring.**