cfsa-antigravity 2.19.0 → 2.19.2

package/template/.claude/skills/technical-writer/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: Technical Writer
+description: Create clear, comprehensive technical documentation for any audience
+---
+
+# Technical Writer
+
+Create clear, comprehensive technical documentation for any audience.
+
+## When to Use This Skill
+- Write user documentation for a feature
+- Create a tutorial for setting up a development environment
+- Document system architecture
+- Write a troubleshooting guide
+- Create onboarding documentation for new developers
+- Write a README for a project
+
+## Instructions
+
+When a user needs technical documentation:
+
+1. **Identify Documentation Type**:
+   - User guide / end-user documentation
+   - Developer documentation / API docs
+   - System architecture documentation
+   - Tutorial / how-to guide
+   - Troubleshooting guide
+   - README file
+   - Release notes / changelog
+   - Onboarding documentation
+   - Knowledge base article
+   - Standard Operating Procedure (SOP)
+
+2. **Determine Audience**:
+   - Technical level (beginner, intermediate, expert)
+   - Role (end user, developer, admin, stakeholder)
+   - Prior knowledge assumptions
+   - Context (internal team, external customers, open source community)
+
+3. **Structure Documentation**:
+
+   **User Guide Format**:
+   ```markdown
+   # [Product/Feature Name]
+
+   ## Overview
+   [What it is, what it does, why use it - 2-3 sentences]
+
+   ## Prerequisites
+   - [Required knowledge]
+   - [Required tools/access]
+   - [System requirements]
+
+   ## Getting Started
+   [Quick start guide with minimal steps to first success]
+
+   ## Key Concepts
+   ### [Concept 1]
+   [Explanation with examples]
+
+   ## Common Tasks
+   ### How to [Task]
+   1. [Step]
+   2. [Step]
+   3. [Expected result]
+
+   ## Advanced Features
+   [Optional advanced functionality]
+
+   ## Troubleshooting
+   ### Problem: [Common issue]
+   **Symptoms**: [What users see]
+   **Solution**: [How to fix]
+
+   ## FAQ
+   **Q: [Question]**
+   A: [Answer]
+
+   ## Additional Resources
+   - [Link to related docs]
+   - [Support channels]
+   ```
+
+   **Tutorial Format**:
+   ```markdown
+   # How to [Accomplish Goal]
+
+   **Time required**: [X minutes]
+   **Difficulty**: [Beginner/Intermediate/Advanced]
+
+   ## What You'll Learn
+   - [Learning objective 1]
+   - [Learning objective 2]
+
+   ## Prerequisites
+   - [Required knowledge]
+   - [Tools needed]
+
+   ## Step-by-Step Instructions
+
+   ### 1. [First Major Step]
+   [Explanation of why this step matters]
+
+   ### 2. [Next Major Step]
+   [Continue pattern]
+
+   ## Verification
+   [How to confirm it worked]
+
+   ## Next Steps
+   [What to learn next]
+
+   ## Troubleshooting
+   [Common issues]
+   ```
+
+   **Architecture Documentation Format**:
+   ```markdown
+   # [System Name] Architecture
+
+   ## Overview
+   [High-level description, purpose, key characteristics]
+
+   ## Architecture Diagram
+   [ASCII diagram or description for diagram]
+
+   ## Components
+   ### [Component 1]
+   **Purpose**: [What it does]
+   **Technology**: [Stack/framework]
+   **Responsibilities**:
+   - [Responsibility 1]
+   - [Responsibility 2]
+
+   **Interfaces**:
+   - Input: [Data/requests it receives]
+   - Output: [Data/responses it produces]
+
+   ## Data Flow
+   1. [Step-by-step flow through system]
+
+   ## Technology Stack
+   - **Frontend**: [Technologies]
+   - **Backend**: [Technologies]
+   - **Database**: [Technologies]
+   - **Infrastructure**: [Technologies]
+
+   ## Design Decisions
+   ### Why [Technology/Pattern]?
+   [Rationale, alternatives considered, trade-offs]
+
+   ## Scalability Considerations
+   [How system scales, bottlenecks, mitigation strategies]
+
+   ## Security
+   [Authentication, authorization, data protection]
+
+   ## Monitoring & Observability
+   [Logging, metrics, alerting]
+   ```
+
+4. **Apply Technical Writing Best Practices**:
+
+   **Clarity**:
+   - Use short sentences (aim for 15-20 words)
+   - Avoid jargon or define it when first used
+   - Use active voice ("Click the button" not "The button should be clicked")
+   - Be specific ("Set timeout to 30 seconds" not "Set a reasonable timeout")
+
+   **Structure**:
+   - Use descriptive headings
+   - Break content into scannable sections
+   - Use numbered lists for sequences
+   - Use bullet points for unordered items
+   - Add table of contents for long docs
+
+   **Visuals**:
+   - Include screenshots with annotations
+   - Add code examples with syntax highlighting
+   - Use diagrams for complex concepts
+   - Show expected outputs
+   - Add tables for comparison or reference
+
+   **Code Examples**:
+   - Include language identifier
+   - Show both good and bad examples
+   - Add comments explaining complex parts
+   - Use realistic, runnable examples
+   - Include error handling
+
+   **User-Focused**:
+   - Start with most common use case
+   - Include "why" not just "how"
+   - Anticipate user questions
+   - Address common pitfalls
+   - Provide troubleshooting
+
+5. **Special Documentation Types**:
+
+   **README.md**:
+   - Project name and description
+   - Installation instructions
+   - Quick start example
+   - Features list
+   - Documentation links
+   - Contributing guidelines
+   - License
+
+   **Release Notes**:
+   - Version number and date
+   - New features
+   - Improvements
+   - Bug fixes
+   - Breaking changes
+   - Migration guide
+   - Deprecation notices
+
+   **Troubleshooting Guide**:
+   - Symptom-based organization
+   - Root cause analysis
+   - Step-by-step resolution
+   - Prevention tips
+   - When to escalate
+
+## Output Quality
+Ensure documentation:
+- Has clear, descriptive title
+- Starts with overview/context
+- Lists prerequisites upfront
+- Uses consistent formatting
+- Includes code examples where appropriate
+- Shows expected outputs
+- Has troubleshooting section
+- Uses appropriate technical level for audience
+- Is structured logically (simple to complex)
+- Includes visual aids (diagrams, screenshots)
+- Has table of contents for long docs
+- Links to related documentation
+- Is easy to scan
+- Uses active voice
+- Avoids ambiguity
+- Includes examples from user perspective

package/template/.claude/skills/testing-strategist/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: Testing Strategist
+description: Design and implement comprehensive testing strategies. Use when setting up tests, choosing test types, implementing TDD, or improving code quality. Covers unit tests, integration tests, E2E tests, test-driven development, and testing best practices.
+version: 1.0.0
+---
+
+# Testing Strategist
+
+Test the right things at the right level — write tests that give you confidence to ship.
+
+## Stack-Specific References
+
+After reading the methodology below, read the reference matching your surface's Languages column in the surface stack map (`.agent/instructions/tech-stack.md`):
+
+| Language | Reference |
+|----------|-----------|
+| TypeScript / JavaScript | `references/typescript.md` |
+| Python | `references/python.md` |
+| Go | `references/go.md` |
+| Rust | `references/rust.md` |
+
+## Core Principle
+
+**The Testing Pyramid:** 70% unit tests, 20% integration tests, 10% E2E tests.
+
+Tests should be:
+
+- **Fast** — Run in milliseconds (unit) to seconds (integration) to minutes (E2E)
+- **Isolated** — Test one thing at a time
+- **Repeatable** — Same input = same output
+- **Self-checking** — Pass/fail automatically, no manual verification
+- **Timely** — Written alongside code (or before, with TDD)
+
+---
+
+## The Testing Pyramid
+
+```
+           /\
+          /  \         E2E Tests (10%)
+         /----\        - Slow, brittle, expensive
+        /      \       - Test critical user journeys
+       /--------\      - Example: "User can complete checkout"
+      /          \
+     /------------\    Integration Tests (20%)
+    /              \   - Medium speed, test components together
+   /----------------\  - Example: "API endpoint returns correct data"
+  /                  \
+ /--------------------\ Unit Tests (70%)
+/______________________\ - Fast, isolated, test functions/components
+                        - Example: "calculateTotal returns sum"
+```
+
+### Why This Ratio?
+
+- **Unit tests:** Fast feedback, pinpoint bugs precisely, easy to maintain
+- **Integration tests:** Ensure components work together, catch interface issues
+- **E2E tests:** Verify actual user flows, catch UI bugs, but slow and brittle
+
+---
+
+## Level 1: Unit Tests (70%)
+
+### What to Test
+
+Test individual functions, components, or classes in isolation.
+
+**Good candidates:**
+
+- ✅ Business logic functions (calculations, validation, transformations)
+- ✅ Utility functions (formatting, parsing, etc.)
+- ✅ UI components (rendering, props, state)
+- ✅ Pure functions (same input = same output)
+
+**Skip:**
+
+- ❌ Third-party libraries (assume they work)
+- ❌ Framework internals
+- ❌ Simple getters/setters with no logic
+
+### Unit Test Best Practices
+
+✅ **Do:**
+
+- Test behavior, not implementation
+- Use descriptive test names
+- Follow AAA pattern: Arrange, Act, Assert
+- Test edge cases (empty, null, negative, boundary values)
+- Keep tests simple and readable
+
+❌ **Don't:**
+
+- Test private methods directly
+- Over-mock (makes tests brittle)
+- Test framework internals
+- Write tests that depend on other tests
+
+---
+
+## Level 2: Integration Tests (20%)
+
+### What to Test
+
+Test multiple units working together — typically API routes, database operations, or service integrations.
+
+**Good candidates:**
+
+- ✅ API endpoints (request → handler → database → response)
+- ✅ Database operations (queries, transactions)
+- ✅ Third-party integrations (payment, email, etc.)
+- ✅ Authentication flows
+- ✅ File upload/download
+
+### Integration Test Best Practices
+
+✅ **Do:**
+
+- Use test database (separate from development/production)
+- Clean up test data before/after each test
+- Test happy path + error cases
+- Test authentication/authorization
+- Use factories/fixtures for test data
+
+❌ **Don't:**
+
+- Test against production database
+- Leave test data behind
+- Mock database (defeats purpose of integration test)
+- Depend on external services (mock external APIs)
+
+---
+
+## Level 3: E2E Tests (10%)
+
+### What to Test
+
+Test complete user journeys through the actual UI.
+
+**Good candidates:**
+
+- ✅ Critical user flows (signup, login, checkout)
+- ✅ Core business processes
+- ✅ Multi-step workflows
+
+**Skip:**
+
+- ❌ Every possible UI interaction (too slow/brittle)
+- ❌ Edge cases (cover with unit/integration tests)
+
+### E2E Test Best Practices
+
+✅ **Do:**
+
+- Test critical paths only (< 20 tests)
+- Use stable selectors (test IDs, roles, labels — not CSS classes)
+- Run in CI/CD pipeline
+- Test across browsers if web surface
+- Take screenshots on failure
+
+❌ **Don't:**
+
+- Test every UI variation
+- Use fragile selectors (nth-child, CSS classes)
+- Run E2E tests on every commit (too slow)
+- Ignore flaky tests (fix or remove them)
+
+---
+
+## Test-Driven Development (TDD)
+
+### The Red-Green-Refactor Cycle
+
+1. **Red:** Write a failing test that defines expected behavior
+2. **Green:** Write minimal code to make it pass
+3. **Refactor:** Improve code while keeping tests green
+
+### When to Use TDD
+
+**Good for:**
+
+- ✅ Complex business logic
+- ✅ Bug fixes (write test that reproduces bug first)
+- ✅ Well-defined requirements
+- ✅ Critical algorithms
+
+**Skip for:**
+
+- ❌ Exploratory coding (don't know requirements yet)
+- ❌ Throwaway prototypes
+- ❌ Simple CRUD operations
+
+---
+
+## Mocking Strategies
+
+### When to Mock
+
+- ✅ External APIs (slow, unreliable, cost money)
+- ✅ Time/randomness (make tests deterministic)
+- ✅ File system operations
+- ✅ Database (in unit tests only — NEVER in integration tests)
+
+### Anti-Mock-Abuse Rules
+
+1. **Never mock what you own** — if you wrote the module, test it directly
+2. **One mock = one boundary** — only mock at the boundary between your code and external systems
+3. **Verify mock interactions** — assert that mocked deps were called with correct arguments
+4. **Mock return values, not internals** — mock the return value, not the internal implementation
+
+### Mocking Best Practices
+
+✅ **Do:**
+
+- Mock at boundaries (APIs, file system, network)
+- Restore mocks after tests
+- Make mocks realistic (same shape as real data)
+
+❌ **Don't:**
+
+- Over-mock (makes tests brittle and meaningless)
+- Mock your own code (test real behavior)
+- Leave mocks unreset between tests
+
+---
+
+## Assertion Depth Rules
+
+### ❌ Shallow Assertions (BANNED)
+
+Assertions that prove nothing about correctness:
+- "Result is defined" — undefined would also be defined
+- "Result is truthy" — empty arrays and objects are truthy
+- "Status is 200" alone — doesn't verify response body
+
+### ✅ Deep Assertions (REQUIRED)
+
+Every test must assert:
+1. **The correct output** — specific values, not just types
+2. **The correct side effects** — what changed in the system
+3. **The correct error behavior** — specific error type and message
+
+---
+
+## Code Coverage
+
+### Coverage Targets
+
+- **70% minimum** — Below this, you're missing important tests
+- **80% good** — Solid coverage of critical paths
+- **90%+ diminishing returns** — Chasing 100% often not worth it
+
+### What to Focus On
+
+**High priority (90%+ coverage):**
+
+- Business logic
+- Authentication/authorization
+- Payment processing
+- Data validation
+
+**Medium priority (70%+):**
+
+- API routes
+- Database queries
+- Utility functions
+
+**Low priority (okay to skip):**
+
+- UI components (test behavior, not rendering)
+- Configuration files
+- Type definitions
+
+---
+
+## Common Testing Patterns
+
+### Testing Async Code
+Write tests that properly wait for async operations to complete before asserting. Use your framework's async test utilities.
+
+### Testing Error Handling
+Mock dependencies to throw errors, then assert your code handles them correctly — shows the right error message, returns the right status code, logs appropriately.
+
+### Testing Forms
+Fill form fields programmatically, submit, and assert both the submission data and any validation errors.
+
+---
+
+## Test Organization
+
+### File Structure
+
+Tests co-locate with source files:
+
+```
+source-file.ext      → source-file.test.ext     (unit tests)
+route-handler.ext    → route-handler.test.ext   (integration tests)
+e2e/                 → feature-name.e2e.ext     (E2E tests)
+```
+
+### Naming Conventions
+
+- Unit/Integration: `*.test.*` or `*.spec.*`
+- E2E: `*.e2e.*` or `*.spec.*` (in tests/e2e/)
+- Test names should describe behavior: "returns X when Y" or "throws error for invalid input"
+
+---
+
+## When to Use This Skill
+
+- ✅ Setting up testing for new project
+- ✅ Choosing test frameworks
+- ✅ Deciding what to test and at what level
+- ✅ Implementing TDD
+- ✅ Improving code coverage
+- ✅ Fixing flaky tests
+
+---
+
+**Good tests give you confidence to ship.** ✅