vstack 0.0.0__py3-none-any.whl

vstack/_templates/skills/migrate/template.md

@@ -0,0 +1,298 @@
+{{SKILL_CONTEXT}}
+
+{{BASE_BRANCH}}
+
+# migrate — Database Migration Review & Authoring
+
+Review or write database migrations for safety, correctness, and zero-downtime
+deployability. No migration ships without a rollback plan.
+
+## Out of scope
+
+- ORM model design (use `design`)
+- Performance benchmarking of queries (use `performance`)
+- Full security audit (use `security`)
+- Architecture decisions (use `architecture` + `adr`)
+
+**Golden rule: Every migration must be reversible or explicitly documented as
+irreversible with a data-recovery plan.**
+
+______________________________________________________________________
+
+## Step 0: Understand the Change
+
+Before reviewing or writing anything, gather context:
+
+> **Question:** What schema change is needed and why?
+>
+> - What table(s) / collection(s) are affected?
+> - Approximate row count and data size?
+> - Is this service actively serving production traffic?
+> - What deployment strategy is used (blue/green, rolling, big-bang)?
+>   **Default:** Assume rolling deployment, production traffic, safety-first.
+
+```bash
+# Find existing migration files
+find . -type f \( -name '*.sql' -o -name '*migration*' -o -name '*migrate*' \) \
+  --exclude-dir=.venv --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=build \
+  2>/dev/null | sort | tail -20
+
+# Show migration files changed in this branch
+git diff <base> --stat -- '*.sql' '**migration**' '**migrate**' 2>/dev/null | head -20
+
+# Check migration framework in use
+[ -f alembic.ini ] && echo "alembic" || true
+[ -f flyway.conf ] && echo "flyway" || true
+grep -r "migrate\|liquibase\|goose\|dbmate" pyproject.toml package.json go.mod 2>/dev/null | head -5
+```
+
+Document:
+
+```text
+Framework:     [alembic | flyway | goose | dbmate | raw SQL | other]
+Table:         [affected table(s)]
+Row estimate:  [< 1k | 10k | 100k | 1M | 10M+ ]
+Deployment:    [rolling | blue-green | big-bang | maintenance window]
+Direction:     [new migration | review existing | both]
+```
+
+______________________________________________________________________
+
+## Step 1: Classify the Migration
+
+Classify every DDL operation by risk level:
+
+| Operation                                | Risk            | Notes                              |
+| ---------------------------------------- | --------------- | ---------------------------------- |
+| `CREATE TABLE`                           | Low             | Safe at any time                   |
+| `ADD COLUMN` nullable, no default        | Low             | Safe in rolling deploy             |
+| `ADD COLUMN` with default (non-volatile) | Medium          | May lock on large tables           |
+| `ADD COLUMN NOT NULL` without default    | **High**        | Breaks old app version             |
+| `DROP COLUMN`                            | **High**        | Must remove all references first   |
+| `RENAME COLUMN`                          | **High**        | Breaks old app version immediately |
+| `ALTER COLUMN` type change               | **High**        | May require data rewrite           |
+| `CREATE INDEX CONCURRENTLY`              | Low             | Safe, non-blocking                 |
+| `CREATE INDEX` (without CONCURRENTLY)    | **High**        | Full table lock                    |
+| `DROP INDEX`                             | Low             | Safe                               |
+| `ADD CONSTRAINT`                         | **High**        | Validates all existing rows        |
+| `TRUNCATE` / `DROP TABLE`                | **Destructive** | Requires explicit confirmation     |
+
+Assign risk to each operation in the migration:
+
+```text
+Operations:
+  1. [operation] — [Low | Medium | High | Destructive]
+  2. ...
+Overall risk: [Low | Medium | High | Destructive]
+```
+
+______________________________________________________________________
+
+## Step 2: Zero-Downtime Analysis
+
+**Rolling deployments require that the schema be compatible with BOTH the old and
+new version of the application simultaneously.**
+
+Check each operation:
+
+- [ ] Old app version can read/write with the new schema
+- [ ] New app version can read/write with the old schema (before migration runs)
+- [ ] No `NOT NULL` columns added without a default or backfill step
+- [ ] No column renames (use add → backfill → switch → drop in separate deploys)
+- [ ] No type changes that are incompatible with existing data
+
+**Expand/Contract pattern (required for breaking changes):**
+
+```text
+Phase 1 — Expand:   Add new column/table alongside old one
+Phase 2 — Migrate:  Backfill data; dual-write in application
+Phase 3 — Switch:   Application reads from new column
+Phase 4 — Contract: Drop old column in a separate deploy
+```
+
+If the migration violates zero-downtime, flag it:
+
+```text
+⚠ ZERO-DOWNTIME VIOLATION
+  Operation: [operation]
+  Problem:   [what breaks]
+  Fix:       [expand/contract steps or maintenance window required]
+```
+
+______________________________________________________________________
+
+## Step 3: Rollback Plan
+
+Every migration must have a defined rollback:
+
+```sql
+-- Forward migration
+ALTER TABLE orders ADD COLUMN discount_cents INTEGER;
+
+-- Rollback
+ALTER TABLE orders DROP COLUMN discount_cents;
+```
+
+For destructive operations (DROP, TRUNCATE), rollback is not possible — document this explicitly:
+
+```text
+⚠ IRREVERSIBLE OPERATION
+  Operation: DROP TABLE legacy_sessions
+  Pre-condition: Confirm legacy_sessions is unused (grep all references)
+  Backup required: Yes — take a snapshot before deploying
+  Recovery: Restore from snapshot (RTO: [estimate])
+```
+
+______________________________________________________________________
+
+## Step 4: Data Integrity
+
+Check:
+
+- [ ] Foreign key constraints are correct and indexed
+- [ ] `NOT NULL` columns have sensible defaults for existing rows
+- [ ] `UNIQUE` constraints won't fail on existing duplicates
+- [ ] `CHECK` constraints won't reject existing data
+- [ ] Enum additions are safe (additions OK; removals break existing data)
+- [ ] Cascade behavior is intentional (`ON DELETE CASCADE` vs `RESTRICT`)
+
+```sql
+-- Before adding a NOT NULL column: verify no NULLs exist
+SELECT COUNT(*) FROM table WHERE column IS NULL;
+
+-- Before adding UNIQUE constraint: verify no duplicates
+SELECT column, COUNT(*) FROM table GROUP BY column HAVING COUNT(*) > 1;
+
+-- Before adding CHECK constraint: verify no violations
+SELECT COUNT(*) FROM table WHERE NOT (constraint_expression);
+```
+
+______________________________________________________________________
+
+## Step 5: Index Safety
+
+**Never create an index without `CONCURRENTLY` on a live table.**
+
+```sql
+-- BAD: acquires ACCESS EXCLUSIVE lock
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+
+-- GOOD: non-blocking, runs in background
+CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders(user_id);
+```
+
+Caveats for `CONCURRENTLY`:
+
+- Cannot run inside a transaction block
+- Takes longer to build
+- May fail if the table is modified heavily during build
+
+Check:
+
+- [ ] All new indexes use `CONCURRENTLY` (unless in a migration transaction that can afford a lock)
+- [ ] Composite index column order matches query patterns
+- [ ] No redundant indexes (subset of existing composite index)
+- [ ] Partial indexes considered for filtered queries
+
+______________________________________________________________________
+
+## Step 6: Performance on Large Tables
+
+For tables with > 100k rows:
+
+```bash
+# Estimate table size
+# PostgreSQL:
+psql -c "SELECT pg_size_pretty(pg_total_relation_size('table_name'));" 2>/dev/null || true
+# MySQL:
+# SELECT table_name, ROUND(((data_length + index_length) / 1024 / 1024), 2) AS 'Size (MB)'
+# FROM information_schema.TABLES WHERE table_schema = DATABASE();
+```
+
+For large tables, prefer:
+
+- **Online DDL** (MySQL 8+, PostgreSQL with `CONCURRENTLY`)
+- **Batched backfills** instead of single `UPDATE` statements
+- **Maintenance window** for operations that cannot be made non-blocking
+
+Batched backfill pattern:
+
+```sql
+-- Backfill in batches to avoid long-running locks
+DO $$
+DECLARE
+  batch_size INT := 10000;
+  offset_val INT := 0;
+  rows_updated INT;
+BEGIN
+  LOOP
+    UPDATE table SET new_col = <expr>
+    WHERE id IN (
+      SELECT id FROM table WHERE new_col IS NULL LIMIT batch_size
+    );
+    GET DIAGNOSTICS rows_updated = ROW_COUNT;
+    EXIT WHEN rows_updated = 0;
+    PERFORM pg_sleep(0.1); -- brief pause between batches
+  END LOOP;
+END $$;
+```
+
+______________________________________________________________________
+
+## Step 7: Testing
+
+```bash
+# Run migration tests
+# Framework-specific:
+alembic upgrade head && alembic downgrade -1 2>/dev/null || true
+flyway migrate && flyway undo 2>/dev/null || true
+
+# Verify the schema matches models
+# (adjust for your ORM)
+python -c "from app.models import Base; Base.metadata.create_all(engine)" 2>/dev/null || true
+```
+
+Check:
+
+- [ ] Migration applies cleanly on a fresh database
+- [ ] Migration applies cleanly on a database with production-representative data
+- [ ] Rollback/downgrade works cleanly
+- [ ] Application tests pass with the new schema
+- [ ] No model/schema drift detected
+
+______________________________________________________________________
+
+## Output
+
+Produce a structured migration review:
+
+```text
+Migration Review
+════════════════
+
+File:          [migration filename]
+Framework:     [framework]
+Risk level:    [Low | Medium | High | Destructive]
+
+Operations:
+  1. [operation] — [risk] — [safe / unsafe for rolling deploy]
+  2. ...
+
+Zero-downtime: [SAFE | UNSAFE — reason]
+Rollback:      [SQL rollback statement | IRREVERSIBLE — reason]
+
+Issues found:
+  🔴 CRITICAL: [issue + fix]
+  🟡 WARNING:  [issue + recommendation]
+  🟢 OK:       [what is correct]
+
+Recommended migration:
+  [corrected or approved SQL]
+
+Pre-deploy checklist:
+  [ ] Backup taken
+  [ ] Migration tested on staging with production data volume
+  [ ] Rollback script validated
+  [ ] Feature flag in place (if needed for expand/contract)
+  [ ] Monitoring alert set for migration duration
+```

vstack/_templates/skills/onboard/config.yaml

@@ -0,0 +1,18 @@
+name: onboard
+version: 1.0.1
+description: |
+  Generate a contributor onboarding guide for a repository. Covers project
+  purpose, architecture overview, local dev setup, test commands, contribution
+  workflow, and first-task suggestions. Use when asked to "write an onboarding
+  guide", "create a contributor guide", "help new devs get started", or
+  "document how to contribute". Produces or updates CONTRIBUTING.md and
+  supplements README with a dev setup section.
+argument-hint: '[repository or service to document]'
+
+license: MIT
+compatibility: Requires a skills-compatible agent with repository file access and terminal command execution when needed.
+metadata:
+  owner: vstack
+  maturity: stable
+user-invocable: true
+disable-model-invocation: false

vstack/_templates/skills/onboard/template.md

@@ -0,0 +1,289 @@
+{{SKILL_CONTEXT}}
+
+# onboard — Contributor Onboarding Guide
+
+Generate or update onboarding documentation so a new contributor can go from
+clone to first PR with zero tribal knowledge required.
+
+## Out of scope
+
+- API design documentation (use `design` or `openapi`)
+- Architecture documentation (use `architecture`)
+- Release notes (use `release-notes`)
+- Test execution (use `verify`)
+
+**Golden rule: If a new contributor needs to ask a question that isn't answered
+by the docs, that is a documentation gap — not a knowledge problem.**
+
+______________________________________________________________________
+
+## Step 0: Audit Existing Documentation
+
+```bash
+# Find existing contributor docs
+ls -la README.md CONTRIBUTING.md DEVELOPMENT.md docs/ 2>/dev/null
+
+# Check for setup scripts
+ls -la Makefile scripts/ bin/ 2>/dev/null
+
+# Check what tooling is defined
+cat Makefile 2>/dev/null | grep -E '^[a-z].*:' | head -20
+
+# Detect tech stack
+ls pyproject.toml package.json go.mod Cargo.toml pom.xml 2>/dev/null
+cat pyproject.toml 2>/dev/null | head -30
+cat package.json 2>/dev/null | grep -E '"scripts"' -A 20 | head -25
+```
+
+Document gaps:
+
+```text
+Existing docs:   [list of files found]
+Missing:         [what's absent — setup steps, test commands, etc.]
+Tech stack:      [Python | Node | Go | other]
+Build tool:      [Poetry | npm | make | other]
+```
+
+______________________________________________________________________
+
+## Step 1: Understand the Project
+
+Read the codebase to extract onboarding-relevant facts:
+
+```bash
+# Project purpose
+head -50 README.md 2>/dev/null
+
+# Project structure
+find . -maxdepth 3 -type d \
+  | grep -v node_modules | grep -v .venv | grep -v __pycache__ \
+  | grep -v .git | grep -v dist | grep -v build \
+  | sort | head -40
+
+# Dependencies and Python version
+cat pyproject.toml 2>/dev/null | grep -E 'python|requires|dependencies' | head -20
+cat .python-version 2>/dev/null
+cat .nvmrc 2>/dev/null
+cat .node-version 2>/dev/null
+
+# CI configuration — what does CI run?
+cat .github/workflows/*.yml 2>/dev/null | grep -E 'run:|uses:' | head -30
+```
+
+______________________________________________________________________
+
+## Step 2: Verify the Setup Steps Work
+
+Before documenting setup steps, verify they actually work:
+
+```bash
+# Attempt setup from scratch perspective
+# (Do not actually destroy the current environment — read and verify commands)
+
+# Check prerequisites are documented
+which python3 || which python && python --version
+which poetry && poetry --version
+which node && node --version
+which make && make --version
+```
+
+For each setup step, confirm:
+
+- [ ] The command exists and works
+- [ ] Dependencies are version-pinned or constrained
+- [ ] Environment variables are documented (use `.env.example` if present)
+- [ ] The setup completes in < 5 minutes on a fresh machine
+
+______________________________________________________________________
+
+## Step 3: Extract Test Commands
+
+```bash
+# Find all test commands
+cat Makefile 2>/dev/null | grep -E 'test|lint|check|verify' | head -20
+cat pyproject.toml 2>/dev/null | grep -E '\[tool\.' -A 5 | head -40
+cat package.json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); [print(k,':',v) for k,v in d.get('scripts',{}).items()]" 2>/dev/null
+```
+
+Document the minimal set a contributor needs:
+
+```text
+Quick check (before every commit):  [command]
+Full test suite:                     [command]
+Lint only:                           [command]
+Type check only:                     [command]
+Single test:                         [command pattern]
+```
+
+______________________________________________________________________
+
+## Step 4: Identify "Good First Issues"
+
+```bash
+# Find TODOs and FIXMEs
+grep -r -n "TODO\|FIXME\|HACK\|good.first" \
+  --include='*.py' --include='*.ts' --include='*.go' --include='*.md' \
+  --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=.git \
+  . 2>/dev/null | head -20
+
+# Check GitHub issues if available
+# (manual step — list any open "good first issue" labels)
+```
+
+______________________________________________________________________
+
+## Step 5: Write the Onboarding Guide
+
+Produce or update `CONTRIBUTING.md` with the following sections:
+
+______________________________________________________________________
+
+````markdown
+# Contributing to [Project Name]
+
+Welcome. This guide gets you from zero to a merged PR.
+
+## Prerequisites
+
+| Tool | Version | Install |
+|------|---------|---------|
+| Python | >= X.Y | [pyenv](https://github.com/pyenv/pyenv) |
+| Poetry | >= X.Y | `pip install poetry` |
+| make | any | system package manager |
+
+## Setup
+
+```bash
+git clone https://github.com/org/repo
+cd repo
+[setup command — e.g. make bootstrap or poetry install]
+```
+
+Verify setup:
+
+```bash
+[verify command — e.g. make check or poetry run pytest]
+```
+
+Expected output: `[N tests passed]`
+
+## Project Structure
+
+```
+[directory tree — top 2 levels with brief descriptions]
+```
+
+## Development Workflow
+
+### Making changes
+
+1. Create a branch: `git checkout -b [type]/[short-description]`
+   - `feat/` — new feature
+   - `fix/` — bug fix
+   - `chore/` — maintenance
+1. Make your change
+1. Run checks: `[check command]`
+1. Commit: `git commit -m "[type]: [description]"`
+1. Push and open a PR
+
+### Before every commit
+
+```bash
+[pre-commit or check command]
+```
+
+This runs: [lint, type check, tests — describe what is checked]
+
+## Testing
+
+```bash
+# Run all tests
+[full test command]
+
+# Run a single test file
+[single test command]
+
+# Run with coverage
+[coverage command]
+```
+
+Tests live in `tests/`. Mirror the source structure: `src/foo/bar.py` → `tests/foo/test_bar.py`.
+
+## Environment Variables
+
+Copy `.env.example` to `.env` and fill in values:
+
+```bash
+cp .env.example .env
+```
+
+| Variable   | Required | Description   |
+| ---------- | -------- | ------------- |
+| `VAR_NAME` | Yes      | [description] |
+
+## Architecture Overview
+
+\[2–4 sentences describing the main components and how they interact.
+Link to docs/architecture/architecture.md for details.\]
+
+## Good First Issues
+
+\[List 3–5 concrete starting points:
+
+- A TODO in the code
+- A missing test
+- A documentation gap
+- A small enhancement\]
+
+## Getting Help
+
+[Slack channel / GitHub Discussions / email — whatever is appropriate]
+
+````
+
+______________________________________________________________________
+
+______________________________________________________________________
+
+## Step 6: Supplement README (if needed)
+
+If README lacks a dev setup section, add a minimal one linking to CONTRIBUTING.md:
+
+````markdown
+## development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, and contribution guidelines.
+
+Quick start:
+
+```bash
+[one-liner setup command]
+[one-liner test command]
+```
+
+````
+
+______________________________________________________________________
+
+## Output
+
+```text
+Onboarding Guide Summary
+════════════════════════
+
+Files produced/updated:
+  ✅ CONTRIBUTING.md  — [new | updated]
+  ✅ README.md        — [updated dev section | no change needed]
+
+Coverage:
+  [ ] Prerequisites documented
+  [ ] Setup steps verified
+  [ ] Test commands documented
+  [ ] Environment variables documented
+  [ ] Project structure explained
+  [ ] Contribution workflow explained
+  [ ] Good first issues listed
+
+Gaps remaining (if any):
+  [anything that could not be determined automatically]
+```

vstack/_templates/skills/openapi/config.yaml

@@ -0,0 +1,17 @@
+name: openapi
+version: 1.0.1
+description: |
+  Write and review OpenAPI 3.1 specifications. Covers resource naming, HTTP
+  method semantics, status codes, error conventions, pagination, versioning,
+  security schemes, and schema validation. Use when asked to "write an OpenAPI
+  spec", "review this API spec", "add an endpoint to the spec", or "validate
+  this OpenAPI file".
+argument-hint: '[API or spec file to write or review]'
+
+license: MIT
+compatibility: Requires a skills-compatible agent with repository file access and terminal command execution when needed.
+metadata:
+  owner: vstack
+  maturity: stable
+user-invocable: true
+disable-model-invocation: false