skill.md & Custom Commands

---
name: test-generator
description: Generate pytest tests for a TaskFlow router file
arguments:
  - name: file
    description: Router file path relative to project root (e.g. routers/tasks.py)
    required: true
---

You are writing pytest tests for the TaskFlow FastAPI application.

Target file: @{{file}}

Context files to read first:
- @sample-project/taskflow/schemas.py       — Pydantic models for request/response
- @sample-project/taskflow/models.py        — SQLAlchemy ORM models
- @sample-project/taskflow/auth.py          — get_current_user dependency

Requirements:
1. Use pytest with httpx.AsyncClient (already in requirements.txt)
2. Include a `test_client` fixture that creates a real in-memory SQLite DB
3. Include a `auth_headers` fixture that registers + logs in a test user
4. Test every endpoint in the file:
   - Happy path (201/200)
   - Auth required (401 when no token)
   - Not found (404 for missing IDs)
   - Validation error (422 for bad input)
5. Use descriptive test names: test_create_task_returns_201_with_valid_data
6. Add a docstring to each test explaining WHAT it validates and WHY it matters

Output: a complete, runnable test file. No pseudocode. No placeholders.

---
name: pr-summary
description: Generate a structured PR description from a branch diff
arguments:
  - name: branch
    description: The feature branch name (source of the PR)
    required: true
  - name: base
    description: The base branch to diff against
    required: false
    default: main
---

You are generating a GitHub Pull Request description for the TaskFlow project.

Context:
- Project: FastAPI + SQLite task management API
- Key files: @sample-project/taskflow/main.py, @sample-project/taskflow/routers/tasks.py

Diff target: branch `{{branch}}` against `{{base}}`
Run this shell command first to get the diff: `git diff {{base}}...{{branch}}`

Then produce a PR description with these exact sections:

## Summary
(2-3 bullet points: what changed and why)

## Changed Endpoints
(list each API endpoint modified, with before/after behavior if applicable)

## Models / Schema Changes
(any SQLAlchemy model or Pydantic schema changes — none if unchanged)

## Test Coverage
(list test files affected or created; note any coverage gaps)

## Breaking Changes
(none, or list with migration instructions)

Keep it factual. Do not invent changes that aren't in the diff.

---
name: release-notes
description: Generate CHANGELOG entries from git commits between two tags
arguments:
  - name: version
    description: The new version being released (e.g. v1.2.0)
    required: true
  - name: since_tag
    description: The previous release tag to diff from (e.g. v1.1.0)
    required: true
---

Generate CHANGELOG-style release notes for TaskFlow version {{version}}.

First, fetch the commit history since the last release:
`git log {{since_tag}}..HEAD --oneline --no-merges`

Then read @sample-project/taskflow/main.py to understand the project structure.

Output the notes in Keep a Changelog format:

## [{{version}}] - {{today}}

### Added
(new features, new endpoints, new query params)

### Changed
(modified behavior in existing endpoints)

### Fixed
(bug fixes — include the commit hash in parentheses)

### Removed
(deprecated features removed in this release)

Rules:
- Group commits by type (feat/fix/chore/docs prefix)
- Skip pure chore/ci/docs commits in the output
- Use present tense ("Add filter", not "Added filter")
- If a commit message is ambiguous, note it as "(needs clarification)"

arguments:
  # Required — Gemini CLI will error if not provided
  - name: file
    description: Router file path relative to project root
    required: true

  # Optional with default — uses "main" if caller omits it
  - name: base
    description: Base branch for diff
    required: false
    default: main

  # Optional with no default — omitting leaves {{base}} unreplaced
  # (usually a bug — always provide a default for optional args)
  - name: since_tag
    description: Previous git tag
    required: false

# Plain text substitution
Analyze the module: {{file}}
# → Analyze the module: routers/tasks.py

# File read via @ prefix
Read and analyze: @{{file}}
# → Gemini reads routers/tasks.py contents

# In shell commands
`git diff {{base}}...{{branch}}`
# → git diff main...feat/add-filter

# In headings
## Review for version {{version}}
# → ## Review for version v1.2.0

---
name: schema-validator
description: Check that all SQLAlchemy model fields have matching Pydantic schemas
arguments: []
---

Compare the SQLAlchemy models and Pydantic schemas in TaskFlow.

Read these files:
- @sample-project/taskflow/models.py
- @sample-project/taskflow/schemas.py

For each SQLAlchemy model (User, Task, Tag), list:

1. **Fields in the model but missing from ALL schemas** — these are likely
   accidentally exposed or forgotten. Flag as WARNING.

2. **Fields in schemas but not in the model** — these are likely typos or
   removed fields still in the schema. Flag as ERROR.

3. **Type mismatches** — e.g., model uses DateTime but schema uses str.
   Flag as WARNING.

Output format per model:
### ModelName
- [OK] field_name: type matches
- [WARN] field_name: in model, missing from schema
- [ERROR] field_name: in schema, not in model

Finish with a summary: "X errors, Y warnings found."

---
name: endpoint-docs
description: Generate a FastAPI docstring for a TaskFlow endpoint function
arguments:
  - name: endpoint
    description: The Python function name (e.g. list_tasks, create_task)
    required: true
  - name: file
    description: Router file containing the endpoint
    required: false
    default: routers/tasks.py
---

Generate a complete FastAPI docstring for the `{{endpoint}}` function in:
@{{file}}

Also read:
- @sample-project/taskflow/schemas.py  — for request/response types
- @sample-project/taskflow/auth.py     — to document auth requirements

The docstring must include:
- One-sentence summary (imperative mood: "List all tasks for the current user")
- Parameters section (path params, query params, request body fields)
- Returns section (HTTP status code + response schema)
- Raises section (401, 403, 404, 422 as applicable)
- Example section with a realistic curl command

Format as a Google-style Python docstring. Output only the docstring, ready to paste.

---
name: migration-helper
description: Draft an Alembic migration for a TaskFlow model change
arguments:
  - name: change
    description: Plain-English description of the model change
    required: true
---

Generate an Alembic migration script for TaskFlow.

Change description: {{change}}

Read the current models first:
@sample-project/taskflow/models.py

Then produce a complete Alembic migration file with:
1. Correct `upgrade()` function using `op.add_column`, `op.drop_column`, etc.
2. Correct `downgrade()` function that reverses the upgrade
3. Realistic `revision`, `down_revision`, and `branch_labels` values
4. A comment explaining why this migration is needed

Constraints:
- Use SQLAlchemy column types from `sqlalchemy` (Integer, String, DateTime, Boolean)
- For nullable additions, use `nullable=True` and `server_default` if appropriate
- For index changes, use `op.create_index` / `op.drop_index`
- Do not import models directly — Alembic scripts use op.* only

Output only the Python migration file. No explanation text.