automatasaurus 0.1.0

package/template/skills/python-standards/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: python-standards
+description: Python coding standards, conventions, and best practices. Use when writing, reviewing, or testing Python code.
+---
+
+# Python Coding Standards
+
+## New Project Preferences
+
+When starting new Python projects, prefer:
+
+- **uv** for package/environment management (fast, modern alternative to pip/venv)
+- **FastAPI** for web APIs
+- **Pydantic** for data validation and serialization
+
+## Style Guide
+
+Follow PEP 8 with these project-specific additions:
+
+### Formatting
+- Line length: 88 characters (Black default)
+- Use Black for formatting, isort for imports
+- Use double quotes for strings (Black default)
+
+### Naming Conventions
+```python
+# Modules and packages: lowercase_with_underscores
+user_service.py
+
+# Classes: PascalCase
+class UserService:
+    pass
+
+# Functions and variables: snake_case
+def get_user_by_id(user_id: int) -> User:
+    active_users = []
+
+# Constants: SCREAMING_SNAKE_CASE
+MAX_RETRY_ATTEMPTS = 3
+DEFAULT_TIMEOUT_SECONDS = 30
+
+# Private: single leading underscore
+def _internal_helper():
+    pass
+
+# "Private" (name mangling): double leading underscore (rare)
+class Base:
+    def __private_method(self):
+        pass
+```
+
+### Imports
+```python
+# Order: stdlib, third-party, local (isort handles this)
+import os
+import sys
+from pathlib import Path
+
+import requests
+from pydantic import BaseModel
+
+from app.models import User
+from app.services import UserService
+```
+
+## Type Hints
+
+Always use type hints for function signatures:
+
+```python
+from typing import Optional, List, Dict, Any, Union
+from collections.abc import Sequence, Mapping
+
+def process_users(
+    users: List[User],
+    filter_active: bool = True,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> List[ProcessedUser]:
+    """Process a list of users with optional filtering."""
+    ...
+
+# Use | for unions (Python 3.10+)
+def get_value(key: str) -> str | None:
+    ...
+```
+
+## Docstrings
+
+Use Google-style docstrings:
+
+```python
+def fetch_user(user_id: int, include_deleted: bool = False) -> User:
+    """Fetch a user by their ID.
+
+    Args:
+        user_id: The unique identifier of the user.
+        include_deleted: Whether to include soft-deleted users.
+
+    Returns:
+        The User object if found.
+
+    Raises:
+        UserNotFoundError: If no user exists with the given ID.
+        DatabaseConnectionError: If the database is unavailable.
+    """
+    ...
+```
+
+## Error Handling
+
+```python
+# Be specific with exceptions
+try:
+    user = await fetch_user(user_id)
+except UserNotFoundError:
+    logger.warning(f"User {user_id} not found")
+    raise HTTPException(status_code=404, detail="User not found")
+except DatabaseConnectionError as e:
+    logger.error(f"Database error: {e}")
+    raise HTTPException(status_code=503, detail="Service unavailable")
+
+# Create custom exceptions for domain errors
+class UserNotFoundError(Exception):
+    """Raised when a user cannot be found."""
+    def __init__(self, user_id: int):
+        self.user_id = user_id
+        super().__init__(f"User with ID {user_id} not found")
+```
+
+## Classes and Data
+
+```python
+# Prefer dataclasses for simple data containers
+from dataclasses import dataclass, field
+from datetime import datetime
+
+@dataclass
+class User:
+    id: int
+    email: str
+    name: str
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    is_active: bool = True
+
+# Use Pydantic for validation and serialization
+from pydantic import BaseModel, EmailStr, validator
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    name: str
+
+    @validator('name')
+    def name_must_not_be_empty(cls, v):
+        if not v.strip():
+            raise ValueError('Name cannot be empty')
+        return v.strip()
+```
+
+## Async Code
+
+```python
+# Use async/await consistently
+async def get_user_with_posts(user_id: int) -> UserWithPosts:
+    async with get_db_session() as session:
+        user = await session.get(User, user_id)
+        posts = await session.execute(
+            select(Post).where(Post.user_id == user_id)
+        )
+        return UserWithPosts(user=user, posts=posts.scalars().all())
+
+# Use asyncio.gather for concurrent operations
+async def fetch_all_data(user_id: int) -> tuple[User, list[Post], Settings]:
+    user, posts, settings = await asyncio.gather(
+        fetch_user(user_id),
+        fetch_posts(user_id),
+        fetch_settings(user_id),
+    )
+    return user, posts, settings
+```
+
+## Testing
+
+```python
+# Use pytest with fixtures
+import pytest
+from unittest.mock import Mock, patch, AsyncMock
+
+@pytest.fixture
+def mock_user():
+    return User(id=1, email="test@example.com", name="Test User")
+
+@pytest.fixture
+def mock_db_session():
+    with patch('app.database.get_session') as mock:
+        yield mock
+
+# Async tests
+@pytest.mark.asyncio
+async def test_fetch_user(mock_db_session, mock_user):
+    mock_db_session.return_value.get = AsyncMock(return_value=mock_user)
+
+    result = await fetch_user(1)
+
+    assert result.id == 1
+    assert result.email == "test@example.com"
+
+# Parameterized tests
+@pytest.mark.parametrize("input,expected", [
+    ("hello", "HELLO"),
+    ("World", "WORLD"),
+    ("", ""),
+])
+def test_uppercase(input, expected):
+    assert uppercase(input) == expected
+```
+
+## Project Commands
+
+Check `.claude/commands.md` for project-specific commands. Common Python commands:
+
+```bash
+# Virtual environment
+python -m venv venv
+source venv/bin/activate  # or `venv\Scripts\activate` on Windows
+
+# Dependencies
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+
+# Formatting
+black .
+isort .
+
+# Linting
+ruff check .
+mypy .
+
+# Testing
+pytest
+pytest --cov=app --cov-report=html
+pytest -x -v  # stop on first failure, verbose
+```
+
+## Common Patterns
+
+### Context Managers
+```python
+from contextlib import contextmanager, asynccontextmanager
+
+@contextmanager
+def temporary_file(suffix: str = ".tmp"):
+    path = Path(tempfile.mktemp(suffix=suffix))
+    try:
+        yield path
+    finally:
+        path.unlink(missing_ok=True)
+
+@asynccontextmanager
+async def get_db_connection():
+    conn = await create_connection()
+    try:
+        yield conn
+    finally:
+        await conn.close()
+```
+
+### Logging
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+def process_order(order_id: int) -> None:
+    logger.info(f"Processing order {order_id}")
+    try:
+        # ... processing
+        logger.debug(f"Order {order_id} validated")
+    except ValidationError as e:
+        logger.warning(f"Order {order_id} validation failed: {e}")
+        raise
+    except Exception as e:
+        logger.exception(f"Unexpected error processing order {order_id}")
+        raise
+```

package/template/skills/requirements-gathering/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: requirements-gathering
+description: Discovery questions, checklists, and techniques for gathering requirements. Use during discovery to ensure thorough understanding before creating issues.
+---
+
+# Requirements Gathering Skill
+
+This skill provides guidance for thorough requirements gathering during discovery.
+
+## Core Principle
+
+**The more we nail down upfront, the better the results.** Don't assume - ASK.
+
+## Your Job During Discovery
+
+- Be thorough and inquisitive
+- Ask clarifying questions before creating any issues
+- Uncover hidden assumptions
+- Define the desired end state clearly
+- Identify edge cases early
+- Document what's in scope AND out of scope
+
+---
+
+## Questions to Ask for Every Feature
+
+### Goals & Success
+
+- What problem are we solving?
+- What does success look like? How will we measure it?
+- What's the priority relative to other work?
+
+### Users & Personas
+
+- Who are the users of this feature?
+- Are there different user types with different needs?
+- What permissions/roles are involved?
+
+### Core Functionality
+
+- What is the primary goal?
+- Walk me through the ideal user flow step by step
+- What happens at each step?
+
+### Data & State
+
+- What data needs to be captured/stored?
+- What are the required fields vs optional?
+- Are there validation rules? (formats, lengths, ranges)
+- What's the initial/default state?
+
+### Edge Cases & Errors
+
+- What happens if [X] fails?
+- What if the user enters invalid data?
+- What about empty states? (no data yet)
+- What about concurrent access?
+- Rate limiting needed?
+
+### UI/UX (if applicable)
+
+- Is there a specific design or layout in mind?
+- Mobile responsive?
+- Accessibility requirements?
+- Loading states? Progress indicators?
+- Success/error feedback to user?
+
+### Integration
+
+- Does this connect to external services?
+- Are there existing patterns to follow?
+- API format preferences?
+
+### Security & Privacy
+
+- Is this data sensitive?
+- Authentication required?
+- Who can see/edit this data?
+
+### Architecture & Technical
+
+- What's the existing tech stack?
+- Are there performance requirements? (latency, throughput, scale)
+- What's the deployment environment?
+- Are there budget constraints?
+- What external services or APIs are involved?
+
+### Scope Boundaries
+
+- What is explicitly NOT included?
+- Are there future phases we should plan for but not build now?
+- What's the MVP vs nice-to-have?
+- What can we cut if we run short?
+
+---
+
+## Red Flags to Probe
+
+When the user says something vague, dig deeper:
+
+| User Says | Ask About |
+|-----------|-----------|
+| "Simple login" | What's simple? OAuth? Email/password? Magic links? |
+| "Just like [X site]" | Which specific features? They have many |
+| "Standard CRUD" | What fields? Validation? Permissions? |
+| "Users can edit" | Edit what exactly? All fields? Their own only? |
+| "Normal validation" | What's normal? Email format? Required fields? |
+| "Handle errors" | Which errors? How? Messages? Retry? |
+| "Make it secure" | What threats? Auth? Encryption? Rate limiting? |
+| "Real-time updates" | WebSockets? SSE? Polling? How fresh? |
+| "Good performance" | What's good? <100ms? <1s? Specific benchmarks? |
+
+---
+
+## Discovery Readiness Checklist
+
+**Don't move to issue creation until:**
+
+- [ ] You understand the complete user flow
+- [ ] You've identified all user types involved
+- [ ] You know what data is captured and validated
+- [ ] Edge cases and error handling are defined
+- [ ] Security/permission requirements are clear
+- [ ] You know what's explicitly OUT of scope
+- [ ] The user has confirmed your understanding
+- [ ] Architecture approach is validated
+- [ ] UI/UX requirements are captured (if applicable)
+
+---
+
+## Example: Requirements Interview
+
+**User says:** "Add user authentication"
+
+**Good discovery response:**
+
+```
+Before we design this, let me make sure I understand the full scope:
+
+**Users:**
+1. Is this for end-users, admins, or both?
+2. Will there be different roles/permissions?
+
+**Registration:**
+3. What fields are required? (email, password, name, etc.)
+4. Email verification required?
+5. Password requirements? (length, complexity)
+6. Terms of service acceptance?
+
+**Login:**
+7. Remember me / stay logged in option?
+8. Session timeout duration?
+9. Multiple device login allowed?
+
+**Password:**
+10. Password reset flow - email link or security questions?
+11. Password change when logged in?
+12. Account lockout after failed attempts?
+
+**Security:**
+13. Two-factor authentication needed?
+14. OAuth/social login? (Google, GitHub, etc.)
+15. Rate limiting on login attempts?
+
+**Edge cases:**
+16. What happens to existing data/users (if any)?
+17. Account deletion/deactivation?
+
+**Out of scope (confirm):**
+18. User profile editing - separate feature?
+19. Admin user management - separate feature?
+```
+
+---
+
+## Capturing Discovery Output
+
+As you gather requirements, document findings in structured format:
+
+```markdown
+## Goals
+- [Primary goal]
+- [Success metrics]
+
+## Users
+- [User type 1]: [needs]
+- [User type 2]: [needs]
+
+## Requirements
+### Must Have (MVP)
+- [Requirement 1]
+- [Requirement 2]
+
+### Nice to Have
+- [Requirement 3]
+
+## Architecture Considerations
+- [Technical approach]
+- [Constraints]
+
+## UI/UX Requirements
+- [Design notes]
+
+## Out of Scope
+- [Explicitly excluded item 1]
+- [Explicitly excluded item 2]
+
+## Open Questions
+- [Any remaining unknowns]
+```
+
+This structured output becomes the `discovery.md` document.

package/template/skills/user-stories/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: user-stories
+description: Guidelines for writing effective user stories with clear acceptance criteria. Use when creating issues from discovery findings.
+---
+
+# User Stories Skill
+
+This skill provides guidance for writing well-formed user stories with clear acceptance criteria.
+
+## User Story Format
+
+```markdown
+As a [type of user],
+I want [goal/desire],
+So that [benefit/value].
+```
+
+### Examples
+
+**Good:**
+```
+As a registered user,
+I want to reset my password via email,
+So that I can regain access to my account if I forget my password.
+```
+
+**Bad:**
+```
+Add password reset feature.
+```
+
+The good example captures WHO needs it, WHAT they need, and WHY.
+
+---
+
+## INVEST Criteria
+
+Good user stories are:
+
+| Criteria | Description |
+|----------|-------------|
+| **I**ndependent | Can be developed separately from other stories |
+| **N**egotiable | Details can be discussed and refined |
+| **V**aluable | Delivers clear value to the user |
+| **E**stimable | Can be sized (fits in a single PR) |
+| **S**mall | Implementable in one PR, not weeks of work |
+| **T**estable | Has clear acceptance criteria to verify |
+
+### Checking Your Stories
+
+- **Independent**: Does this require other stories to be done first? If so, document the dependency.
+- **Negotiable**: Is there flexibility in HOW this is implemented?
+- **Valuable**: Can you explain the user benefit?
+- **Estimable**: Is it clear enough to implement?
+- **Small**: Could this be done in 1-3 days? If not, break it down.
+- **Testable**: Can you write acceptance criteria?
+
+---
+
+## Acceptance Criteria
+
+Acceptance criteria define WHEN a story is complete. They should be:
+
+- **Specific**: Clear, unambiguous conditions
+- **Measurable**: Can be verified as pass/fail
+- **Complete**: Cover the happy path AND edge cases
+
+### Format
+
+Use checkbox format for easy verification:
+
+```markdown
+## Acceptance Criteria
+- [ ] User can request password reset with their email
+- [ ] Reset link is sent to registered email only
+- [ ] Reset link expires after 1 hour
+- [ ] User sees error message for unregistered email
+- [ ] User can set new password via reset link
+- [ ] Old password no longer works after reset
+```
+
+### Writing Good Criteria
+
+**Good criteria:**
+- [ ] Login form shows error for incorrect password
+- [ ] Error message says "Invalid email or password" (not which is wrong)
+- [ ] Account locks after 5 failed attempts
+
+**Bad criteria:**
+- [ ] Login works correctly (too vague)
+- [ ] Errors are handled (not specific)
+- [ ] Good UX (not measurable)
+
+---
+
+## Breaking Down Large Features
+
+Large features should be broken into stories sized for a single PR.
+
+### Splitting Strategies
+
+1. **By User Flow Step**
+   - Registration → Login → Password Reset → Session Management
+
+2. **By Data Entity**
+   - User Model → User API → User UI
+
+3. **By User Type**
+   - End-user features → Admin features
+
+4. **By Complexity Layer**
+   - Backend API → Frontend UI → Integration
+
+### Example: "User Authentication" Feature
+
+Break into:
+
+| Issue | Story | Dependencies |
+|-------|-------|--------------|
+| #1 | Database schema for users | None |
+| #2 | User registration endpoint | #1 |
+| #3 | User login endpoint | #1 |
+| #4 | Session management | #3 |
+| #5 | Password reset flow | #2, #3 |
+
+Each issue is one PR's worth of work.
+
+---
+
+## Issue Template
+
+```markdown
+## User Story
+As a [type of user],
+I want [goal/desire],
+So that [benefit/value].
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Technical Notes
+[Architecture decisions, approach, or constraints]
+
+## UI/UX Requirements
+[Design specs, wireframes, or "None - backend only"]
+
+## Dependencies
+[List as "Depends on #X" or "None - can be worked independently"]
+
+## Out of Scope
+[Explicitly list what is NOT included to avoid scope creep]
+```
+
+---
+
+## Common Mistakes
+
+### Too Big
+**Bad:** "As a user, I want a complete authentication system"
+**Better:** Split into registration, login, password reset, etc.
+
+### No User Value
+**Bad:** "Refactor the database layer"
+**Better:** "As a developer, I want a normalized user schema so that queries are faster"
+
+### Vague Criteria
+**Bad:** "Login should work well"
+**Better:** "User is redirected to dashboard after successful login"
+
+### Missing Edge Cases
+**Bad:** Only happy path criteria
+**Better:** Include error states, empty states, boundary conditions
+
+### Hidden Dependencies
+**Bad:** No mention of required prior work
+**Better:** "Depends on #1 (User model must exist first)"
+
+---
+
+## Verification
+
+Before finalizing a story, verify:
+
+1. **Is the user clear?** Who specifically benefits?
+2. **Is the goal actionable?** What exactly will they do?
+3. **Is the value stated?** Why does this matter?
+4. **Are criteria testable?** Can each be verified pass/fail?
+5. **Is it sized right?** One PR, not a week of work?
+6. **Are dependencies explicit?** What must exist first?
+7. **Is scope bounded?** What's explicitly excluded?