anvil-dev-framework 0.1.6

package/global/skills/skill-template/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: [Skill Name]
+description: [Brief description of what this skill provides]
+triggers:
+  - [keyword1]
+  - [keyword2]
+  - [keyword3]
+version: 1.0.0
+---
+
+# [Skill Name]
+
+## Overview
+[2-3 sentences describing what this skill covers and why it exists]
+
+## When to Use
+- [Situation 1 when this skill is relevant]
+- [Situation 2 when this skill is relevant]
+- [Situation 3 when this skill is relevant]
+
+## Key Concepts
+
+### [Concept 1]
+[Explanation of the concept]
+
+### [Concept 2]
+[Explanation of the concept]
+
+### [Concept 3]
+[Explanation of the concept]
+
+## Patterns
+
+### Pattern: [Pattern Name]
+**When**: [When to use this pattern]
+**Why**: [Why this pattern is preferred]
+
+```typescript
+// Example implementation
+[code example]
+```
+
+### Pattern: [Another Pattern]
+**When**: [When to use]
+**Why**: [Why preferred]
+
+```typescript
+[code example]
+```
+
+## Decision Framework
+
+Use this when deciding between approaches:
+
+| Situation | Recommended Approach | Reason |
+|-----------|---------------------|--------|
+| [Situation 1] | [Approach] | [Reason] |
+| [Situation 2] | [Approach] | [Reason] |
+| [Situation 3] | [Approach] | [Reason] |
+
+## Anti-Patterns
+
+### ❌ [Anti-Pattern Name]
+**Problem**: [Why this is bad]
+**Instead**: [What to do instead]
+
+```typescript
+// Bad
+[bad code]
+
+// Good
+[good code]
+```
+
+### ❌ [Another Anti-Pattern]
+**Problem**: [Why this is bad]
+**Instead**: [What to do instead]
+
+## Checklist
+
+Before completing work in this domain, verify:
+
+- [ ] [Checklist item 1]
+- [ ] [Checklist item 2]
+- [ ] [Checklist item 3]
+- [ ] [Checklist item 4]
+
+## Examples
+
+### Example 1: [Example Name]
+[Description of what this example shows]
+
+See: `examples/example-1.ts`
+
+### Example 2: [Example Name]
+[Description]
+
+See: `examples/example-2.ts`
+
+## References
+
+- [Link to official documentation]
+- [Link to relevant article]
+- [Link to internal documentation]
+
+## Changelog
+
+### v1.0.0
+- Initial version

package/global/skills/testing-strategies/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: Testing Strategies
+description: Comprehensive testing patterns including unit, integration, and E2E testing
+triggers:
+  - testing
+  - unit test
+  - integration test
+  - e2e test
+  - test coverage
+  - test review
+version: 1.0.0
+---
+
+# Testing Strategies
+
+Comprehensive testing patterns for AI-assisted development.
+
+---
+
+## Testing Pyramid
+
+```
+        ┌─────┐
+        │ E2E │        Few, slow, high confidence
+       ─┴─────┴─
+      │Integration│    Some, medium speed
+     ─┴───────────┴─
+    │    Unit Tests   │  Many, fast, isolated
+   ─┴─────────────────┴─
+```
+
+| Layer | Count | Speed | Scope |
+|-------|-------|-------|-------|
+| Unit | Many (70-80%) | Fast (<10ms) | Single function/component |
+| Integration | Some (15-20%) | Medium (<1s) | Module boundaries |
+| E2E | Few (5-10%) | Slow (seconds) | Full user flows |
+
+---
+
+## Unit Testing
+
+### When to Write Unit Tests
+
+- Pure functions with logic
+- Utility functions
+- Data transformations
+- Business rules
+- Components with conditional rendering
+
+### Unit Test Structure (AAA Pattern)
+
+```typescript
+describe('calculateTotal', () => {
+  it('should apply discount when quantity > 10', () => {
+    // Arrange
+    const items = [{ price: 100, quantity: 15 }];
+    
+    // Act
+    const result = calculateTotal(items);
+    
+    // Assert
+    expect(result).toBe(1425); // 15 * 100 * 0.95
+  });
+});
+```
+
+### What to Test
+
+- ✅ Happy path (expected inputs → expected outputs)
+- ✅ Edge cases (empty, null, boundary values)
+- ✅ Error cases (invalid inputs → appropriate errors)
+- ✅ State transitions
+
+### What NOT to Unit Test
+
+- ❌ Third-party libraries (they have their own tests)
+- ❌ Simple getters/setters (no logic)
+- ❌ Implementation details (test behavior, not internals)
+- ❌ Framework code (React, Express, etc.)
+
+---
+
+## Integration Testing
+
+### When to Write Integration Tests
+
+- API route handlers
+- Database operations
+- Service-to-service communication
+- Authentication flows
+- Data flow across module boundaries
+
+### Integration Test Process
+
+**Step 1: Identify Integration Points**
+```
+Component A ←→ API ←→ Database
+     │
+     └──→ External Service
+```
+
+**Step 2: Test Each Boundary**
+
+```typescript
+describe('POST /api/reservations', () => {
+  it('should create reservation and return confirmation', async () => {
+    // Setup test database state
+    await db.items.create({ id: 'item-1', available: true });
+    
+    // Make request
+    const response = await request(app)
+      .post('/api/reservations')
+      .send({ itemId: 'item-1', guestEmail: 'test@example.com' });
+    
+    // Verify response
+    expect(response.status).toBe(201);
+    expect(response.body.reservationId).toBeDefined();
+    
+    // Verify database state
+    const reservation = await db.reservations.findFirst({
+      where: { itemId: 'item-1' }
+    });
+    expect(reservation).toBeDefined();
+  });
+});
+```
+
+**Step 3: Test Error Paths**
+
+```typescript
+it('should return 409 when item already reserved', async () => {
+  // Setup: item already reserved
+  await db.reservations.create({ 
+    itemId: 'item-1', 
+    status: 'confirmed' 
+  });
+  
+  const response = await request(app)
+    .post('/api/reservations')
+    .send({ itemId: 'item-1', guestEmail: 'test@example.com' });
+  
+  expect(response.status).toBe(409);
+  expect(response.body.error).toContain('already reserved');
+});
+```
+
+### Integration Test Checklist
+
+Before PR, verify integration tests cover:
+
+- [ ] Happy path (valid inputs → success)
+- [ ] Authentication required (401 without token)
+- [ ] Authorization (403 for wrong user)
+- [ ] Validation errors (400 for bad input)
+- [ ] Not found (404 for missing resources)
+- [ ] Conflict states (409 for duplicates)
+- [ ] Database state changes verified
+
+---
+
+## E2E Testing
+
+### When to Write E2E Tests
+
+- Critical user journeys
+- Payment flows
+- Authentication flows
+- Multi-step processes
+- Anything that breaks = serious business impact
+
+### E2E Test Structure
+
+```typescript
+test('user can complete checkout flow', async ({ page }) => {
+  // Setup: logged in user with items in cart
+  await loginAsTestUser(page);
+  await addItemToCart(page, 'product-123');
+  
+  // Navigate to checkout
+  await page.click('[data-testid="checkout-button"]');
+  
+  // Fill payment info
+  await page.fill('[data-testid="card-number"]', '4242424242424242');
+  await page.fill('[data-testid="expiry"]', '12/25');
+  await page.fill('[data-testid="cvc"]', '123');
+  
+  // Submit
+  await page.click('[data-testid="pay-button"]');
+  
+  // Verify success
+  await expect(page.locator('[data-testid="success-message"]'))
+    .toBeVisible();
+  await expect(page.locator('[data-testid="order-id"]'))
+    .toHaveText(/ORD-\d+/);
+});
+```
+
+### E2E Best Practices
+
+- Use data-testid attributes (not CSS classes)
+- Setup known test state before each test
+- Clean up after tests
+- Don't test what unit/integration tests cover
+- Run in CI, not just locally
+
+---
+
+## Test Review Checklist
+
+When reviewing tests (your own or others'):
+
+### Coverage
+- [ ] All new code has tests
+- [ ] Edge cases covered
+- [ ] Error paths tested
+- [ ] No dead test code
+
+### Quality
+- [ ] Tests are readable (clear names, AAA pattern)
+- [ ] Tests are isolated (don't depend on each other)
+- [ ] Tests are deterministic (no flaky tests)
+- [ ] Tests are fast (unit <10ms, integration <1s)
+
+### Anti-Patterns to Catch
+- [ ] No testing implementation details
+- [ ] No excessive mocking
+- [ ] No testing third-party code
+- [ ] No duplicate test coverage
+- [ ] No commented-out tests
+
+### Red Flags
+- 🚩 Test name doesn't describe behavior
+- 🚩 Multiple asserts testing unrelated things
+- 🚩 Test setup is longer than test itself
+- 🚩 Mock verifies implementation, not behavior
+- 🚩 Test passes when code is clearly broken
+
+---
+
+## Shared Code Testing (Hooks/Utilities)
+
+### Testing Hooks
+
+```typescript
+import { renderHook, act } from '@testing-library/react';
+import { useCounter } from './useCounter';
+
+describe('useCounter', () => {
+  it('should increment counter', () => {
+    const { result } = renderHook(() => useCounter());
+    
+    act(() => {
+      result.current.increment();
+    });
+    
+    expect(result.current.count).toBe(1);
+  });
+});
+```
+
+### Testing Utilities
+
+```typescript
+describe('formatCurrency', () => {
+  it.each([
+    [100, '$1.00'],
+    [1000, '$10.00'],
+    [1050, '$10.50'],
+    [0, '$0.00'],
+  ])('formats %i cents as %s', (cents, expected) => {
+    expect(formatCurrency(cents)).toBe(expected);
+  });
+});
+```
+
+### Rule of Three for Shared Code
+
+Before abstracting shared code:
+1. First use: Just write it
+2. Second use: Note the duplication
+3. Third use: NOW abstract and test thoroughly
+
+Thoroughly tested shared code prevents bugs that cascade across the codebase.
+
+---
+
+## Test Organization
+
+```
+src/
+├── components/
+│   └── Button/
+│       ├── Button.tsx
+│       └── Button.test.tsx      # Unit tests
+├── services/
+│   └── auth/
+│       ├── authService.ts
+│       └── authService.test.ts  # Unit tests
+├── app/
+│   └── api/
+│       └── reservations/
+│           ├── route.ts
+│           └── route.test.ts    # Integration tests
+└── e2e/
+    └── checkout.test.ts         # E2E tests
+```
+
+---
+
+## AI-Specific Testing Guidance
+
+### When Generating Tests with AI
+
+1. **Start with behavior description** — Tell AI what the code SHOULD do
+2. **Review generated tests** — AI may miss edge cases or test implementation details
+3. **Run tests immediately** — Verify they actually pass/fail correctly
+4. **Check for flakiness** — Run multiple times
+
+### Common AI Testing Mistakes
+
+- Testing implementation instead of behavior
+- Over-mocking (mocking the thing being tested)
+- Missing error cases
+- Hardcoded test data that doesn't cover edge cases
+- Tests that always pass (not actually testing anything)
+
+### Test-First with AI
+
+When asking AI to implement features:
+
+1. Write test first (or have AI write test)
+2. Verify test FAILS (confirms test is working)
+3. Implement feature
+4. Verify test PASSES
+5. Refactor if needed
+
+This ensures tests actually validate behavior.

package/global/templates/CHANGE-template.md

@@ -0,0 +1,105 @@
+---
+change_id: CHANGE-[NUMBER]
+title: [Change Description]
+status: draft
+created: YYYY-MM-DD
+linear_issue: [Issue Key]
+risk_level: low | medium | high
+---
+
+# Change Proposal: [Title]
+
+## Summary
+[1-2 sentence description of the change]
+
+## Motivation
+[Why is this change needed? What problem does it solve?]
+
+## Current State
+[Description of how things work now]
+
+### Affected Files (Current)
+| File | Purpose | Lines |
+|------|---------|-------|
+| src/components/X.tsx | [Current purpose] | ~150 |
+
+## Proposed Changes
+
+### File: src/[path]/[file].tsx
+
+#### MODIFIED: [Function/Component Name]
+```typescript
+// BEFORE (lines XX-YY)
+[current code]
+
+// AFTER
+[new code with ADDED/MODIFIED/REMOVED comments]
+```
+
+#### ADDED: [New element]
+```typescript
+// ADDED at line XX
+[new code]
+```
+
+#### REMOVED: [Removed element]
+```typescript
+// REMOVED from [location]
+[removed code]
+```
+
+---
+
+### File: src/[path]/[another-file].ts
+
+#### MODIFIED: [What changed]
+```typescript
+// BEFORE
+[old code]
+
+// AFTER
+[new code]
+```
+
+## New Files
+| File | Purpose |
+|------|---------|
+| | |
+
+## Deleted Files
+| File | Reason |
+|------|--------|
+| | |
+
+## Impact Analysis
+
+### Breaking Changes
+- [ ] API contract changes: [Yes/No - details]
+- [ ] Database schema changes: [Yes/No - details]
+- [ ] Environment variable changes: [Yes/No - details]
+
+### Affected Consumers
+| Consumer | Impact | Migration Needed |
+|----------|--------|------------------|
+| [Component/Service] | [Impact] | [Yes/No] |
+
+### Test Impact
+- [ ] Existing tests need updates: [List tests]
+- [ ] New tests needed: [List new tests]
+
+## Migration Plan
+[If breaking changes, how will migration happen?]
+
+1. [Step 1]
+2. [Step 2]
+
+## Rollback Plan
+[How to revert if something goes wrong]
+
+## Risk Assessment
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| [Risk] | Low/Med/High | Low/Med/High | [Mitigation] |
+
+## Open Questions
+- [ ] [Question]

package/global/templates/HANDOFF-template.md

@@ -0,0 +1,63 @@
+---
+session_date: YYYY-MM-DD
+session_time: HH:MM
+branch: [current branch]
+linear_issues: [comma-separated issue keys]
+---
+
+# Session Handoff: [Brief Description]
+
+## Session Summary
+[1-2 sentence summary of what this session was about]
+
+## Completed This Session
+- [x] [Issue key]: [What was done]
+- [x] [Description of completed work]
+- [x] [Another completed item]
+
+## In Progress (Not Complete)
+
+### [Issue Key]: [Title]
+- **Current state**: [Where we left off - be specific]
+- **Next steps**: [What needs to happen next]
+- **Files touched**: 
+  - `src/path/to/file.tsx` - [what was done/needs doing]
+  - `src/path/to/another.ts` - [what was done/needs doing]
+- **Blockers**: [Any blockers, or "None"]
+
+### [Another Issue Key]: [Title]
+- **Current state**: [Where we left off]
+- **Next steps**: [What needs to happen next]
+- **Files touched**: [List files]
+- **Blockers**: [Any blockers]
+
+## Discovered Work
+- [ ] [Description] → Filed as [Issue key]
+- [ ] [Description] → Not yet filed (needs: [what's needed])
+
+## Environment State
+- **Branch**: [branch name]
+- **Uncommitted changes**: [Yes/No - if yes, describe briefly]
+- **Last commit**: [hash] [message]
+- **Tests passing**: [Yes/No]
+- **Build status**: [Clean/Errors]
+
+## Recommended Next Task
+[What should be tackled first next session and why]
+
+**Issue**: [Issue key]
+**Reason**: [Why this should be next - priority, dependencies resolved, etc.]
+
+## Critical Context for Next Session
+[Important context that might be lost - decisions made, constraints discovered, gotchas]
+
+1. **[Topic]**: [Important detail]
+2. **[Topic]**: [Important detail]
+3. **[Topic]**: [Important detail]
+
+## Notes
+[Any other relevant notes, links, or context]
+
+---
+*Handoff created: [timestamp]*
+*Next session: Start with `/orient` to pick up context*

package/global/templates/PLAN-template.md

@@ -0,0 +1,111 @@
+---
+plan_id: PLAN-[SPEC-ID]
+spec_ref: SPEC-[NUMBER]
+status: draft
+created: YYYY-MM-DD
+estimated_hours: [X-Y]
+---
+
+# Implementation Plan: [Feature Name]
+
+## Specification Reference
+- **Spec**: SPEC-[number]
+- **Linear Issue**: [Issue key]
+
+## Implementation Strategy
+[High-level approach to implementing this feature]
+
+## Phases
+
+### Phase 1: [Phase Name]
+**Estimated**: X hours
+**Goal**: [What this phase accomplishes]
+
+**Tasks**:
+1. [ ] [Task description]
+2. [ ] [Task description]
+3. [ ] [Task description]
+
+**Files to Create/Modify**:
+| File | Action | Purpose |
+|------|--------|---------|
+| src/components/X.tsx | Create | [Purpose] |
+| src/services/y.ts | Modify | [Purpose] |
+
+**Acceptance**: [How to verify phase is complete]
+
+---
+
+### Phase 2: [Phase Name]
+**Estimated**: X hours
+**Goal**: [What this phase accomplishes]
+**Depends on**: Phase 1
+
+**Tasks**:
+1. [ ] [Task description]
+2. [ ] [Task description]
+
+**Files to Create/Modify**:
+| File | Action | Purpose |
+|------|--------|---------|
+
+**Acceptance**: [How to verify phase is complete]
+
+---
+
+### Phase 3: Testing & Polish
+**Estimated**: X hours
+**Goal**: Verify all acceptance criteria, fix edge cases
+
+**Tasks**:
+1. [ ] Write unit tests for [component]
+2. [ ] Write integration tests for [flow]
+3. [ ] Manual testing of acceptance scenarios
+4. [ ] Address any edge cases found
+
+**Acceptance**: All tests pass, all Gherkin scenarios verified
+
+## File Change Summary
+
+### New Files
+| Path | Purpose |
+|------|---------|
+| | |
+
+### Modified Files
+| Path | Changes |
+|------|---------|
+| | |
+
+### Deleted Files
+| Path | Reason |
+|------|--------|
+| [none expected] | |
+
+## Testing Strategy
+
+### Unit Tests
+- [ ] [Component/function to test]
+
+### Integration Tests
+- [ ] [Flow to test]
+
+### Manual Testing
+- [ ] [Scenario to manually verify]
+
+## Risks and Rollback
+
+### Known Risks
+| Risk | Mitigation |
+|------|------------|
+| [Risk] | [Mitigation] |
+
+### Rollback Plan
+[How to rollback if something goes wrong]
+
+## Definition of Done
+- [ ] All tasks complete
+- [ ] All tests passing
+- [ ] Code reviewed
+- [ ] Acceptance criteria verified
+- [ ] Documentation updated (if needed)