vstack 0.0.0__py3-none-any.whl

vstack/_templates/skills/openapi/template.md

@@ -0,0 +1,382 @@
+{{SKILL_CONTEXT}}
+
+# openapi — OpenAPI 3.1 Specification
+
+Write or review OpenAPI 3.1 specifications. The spec is the contract — it must
+be precise, complete, and implementable without ambiguity.
+
+## Out of scope
+
+- Service architecture decisions (use `architecture`)
+- Full API design from scratch (use `design`)
+- Security audit of the implementation (use `security`)
+- Contract compliance of the implementation (use `verify`)
+
+**Golden rule: The spec is the source of truth. Code must conform to the spec,
+not the other way around.**
+
+______________________________________________________________________
+
+## Step 0: Understand the Task
+
+> **Question:** What needs to be done?
+>
+> **Options:**
+> A) Write a new OpenAPI spec from scratch
+> B) Review and improve an existing spec
+> C) Add endpoints to an existing spec
+> D) Validate spec for correctness and completeness
+> **Default:** B — review existing spec
+
+```bash
+# Locate existing spec files
+find . -name 'openapi*.yaml' -o -name 'openapi*.json' \
+  -o -name 'swagger*.yaml' -o -name 'swagger*.json' \
+  2>/dev/null | grep -v node_modules | grep -v .venv | head -10
+
+# Validate spec if tooling is available
+[ -f openapi.yaml ] && npx @redocly/cli lint openapi.yaml 2>/dev/null || true
+[ -f openapi.yaml ] && npx swagger-cli validate openapi.yaml 2>/dev/null || true
+```
+
+______________________________________________________________________
+
+## Part 1: Spec Structure
+
+Every OpenAPI 3.1 spec must have:
+
+```yaml
+openapi: "3.1.0"
+
+info:
+  title: Service Name API
+  version: "1.0.0"
+  description: |
+    One paragraph describing the service purpose.
+  contact:
+    name: Team Name
+    email: team@example.com
+
+servers:
+  - url: https://api.example.com/v1
+    description: Production
+  - url: https://api.staging.example.com/v1
+    description: Staging
+
+tags:
+  - name: users
+    description: User management
+
+paths: {}
+
+components:
+  schemas: {}
+  securitySchemes: {}
+
+security: []
+```
+
+Check:
+
+- [ ] `openapi` field is `"3.1.0"` (not 3.0.x or 2.x)
+- [ ] `info.version` follows semver
+- [ ] At least one server defined
+- [ ] Tags defined at root level and used consistently on operations
+- [ ] `components` section exists for reusable schemas
+
+______________________________________________________________________
+
+## Part 2: Resource & Path Design
+
+### Naming conventions
+
+| Correct                    | Incorrect            | Rule                        |
+| -------------------------- | -------------------- | --------------------------- |
+| `/users`                   | `/getUsers`, `/user` | Plural nouns, no verbs      |
+| `/users/{userId}`          | `/users/{id}`        | Descriptive path parameters |
+| `/users/{userId}/orders`   | `/userOrders`        | Nested for ownership        |
+| `/orders/{orderId}/cancel` | `/cancelOrder/{id}`  | Sub-resource for actions    |
+
+### HTTP method semantics
+
+| Method   | Semantics                       | Idempotent | Body |
+| -------- | ------------------------------- | ---------- | ---- |
+| `GET`    | Read, no side effects           | Yes        | No   |
+| `POST`   | Create or non-idempotent action | No         | Yes  |
+| `PUT`    | Full replace                    | Yes        | Yes  |
+| `PATCH`  | Partial update                  | No         | Yes  |
+| `DELETE` | Remove                          | Yes        | No   |
+
+Check each path:
+
+- [ ] Path uses plural noun, no verbs
+- [ ] Path parameters are descriptive (`userId` not `id`)
+- [ ] HTTP method matches semantics above
+- [ ] `GET` operations have no request body
+- [ ] `DELETE` operations return `204 No Content` or `200` with body, never `201`
+- [ ] Every operation has a unique `operationId` (camelCase, e.g. `listUsers`, `createOrder`)
+- [ ] Every operation has a `summary` (short title, ≤ 80 chars) and `tags`
+
+______________________________________________________________________
+
+## Part 3: Status Codes
+
+Use exactly these status codes — no others unless justified:
+
+| Code                        | Meaning                       | When to use                           |
+| --------------------------- | ----------------------------- | ------------------------------------- |
+| `200 OK`                    | Success with body             | `GET`, `PUT`, `PATCH` success         |
+| `201 Created`               | Resource created              | `POST` creating a resource            |
+| `202 Accepted`              | Accepted for async processing | Background jobs                       |
+| `204 No Content`            | Success, no body              | `DELETE`, `POST` with no return       |
+| `400 Bad Request`           | Validation error              | Invalid input                         |
+| `401 Unauthorized`          | Not authenticated             | Missing/invalid token                 |
+| `403 Forbidden`             | Not authorized                | Valid token, insufficient permissions |
+| `404 Not Found`             | Resource missing              | ID doesn't exist                      |
+| `409 Conflict`              | State conflict                | Duplicate create, optimistic lock     |
+| `422 Unprocessable Entity`  | Semantic validation           | Business rule violation               |
+| `429 Too Many Requests`     | Rate limited                  | Include `Retry-After` header          |
+| `500 Internal Server Error` | Unexpected error              | Never expose internals                |
+
+Check:
+
+- [ ] Every operation documents all realistic status codes
+- [ ] `200` vs `201` vs `204` used correctly
+- [ ] `401` and `403` are distinct and documented
+- [ ] `500` is documented but never includes stack traces
+
+______________________________________________________________________
+
+## Part 4: Error Response Schema
+
+Every error response must use a consistent schema:
+
+```yaml
+components:
+  schemas:
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          description: Machine-readable error code
+          example: "VALIDATION_ERROR"
+        message:
+          type: string
+          description: Human-readable description
+          example: "email must be a valid email address"
+        details:
+          type: array
+          description: Field-level validation errors
+          items:
+            type: object
+            required: [field, message]
+            properties:
+              field:
+                type: string
+                example: "email"
+              message:
+                type: string
+                example: "must be a valid email address"
+        request_id:
+          type: string
+          description: Correlation ID for tracing
+          example: "req_01HZ..."
+```
+
+Check:
+
+- [ ] All `4xx` and `5xx` responses reference `$ref: '#/components/schemas/Error'`
+- [ ] Error schema has a machine-readable `code` field
+- [ ] `request_id` for correlation is present
+- [ ] Field-level errors included for `400`/`422`
+
+______________________________________________________________________
+
+## Part 5: Pagination
+
+Standard cursor-based pagination (preferred for large datasets):
+
+```yaml
+# Query parameters
+parameters:
+  - name: cursor
+    in: query
+    schema:
+      type: string
+    description: Opaque cursor from previous response
+  - name: limit
+    in: query
+    schema:
+      type: integer
+      minimum: 1
+      maximum: 100
+      default: 20
+
+# Response envelope
+components:
+  schemas:
+    PaginatedUsers:
+      type: object
+      required: [data, pagination]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/User'
+        pagination:
+          type: object
+          required: [has_more]
+          properties:
+            has_more:
+              type: boolean
+            next_cursor:
+              type: string
+              nullable: true
+            total:
+              type: integer
+              description: Total count (expensive — omit if not needed)
+```
+
+Check:
+
+- [ ] Pagination is cursor-based (not offset for large collections)
+- [ ] `limit` has a maximum and default
+- [ ] Response includes `has_more` and `next_cursor`
+- [ ] `total` is optional (expensive query — only include if needed)
+
+______________________________________________________________________
+
+## Part 6: Schema Quality
+
+For each schema in `components/schemas`:
+
+```yaml
+components:
+  schemas:
+    User:
+      type: object
+      required: [id, email, created_at]    # ← explicit required list
+      properties:
+        id:
+          type: string
+          format: uuid
+          readOnly: true                   # ← readOnly for server-generated fields
+          example: "01HZ..."
+        email:
+          type: string
+          format: email
+          example: "user@example.com"
+        name:
+          type: string
+          minLength: 1
+          maxLength: 255
+          example: "Alice"
+        created_at:
+          type: string
+          format: date-time
+          readOnly: true
+          example: "2026-01-01T00:00:00Z"
+```
+
+Check:
+
+- [ ] All schemas have a `required` list (no implicit optionals)
+- [ ] `id`, `created_at`, `updated_at` are `readOnly: true`
+- [ ] All string fields have `minLength`/`maxLength` where appropriate
+- [ ] All fields have an `example`
+- [ ] `format` used for `uuid`, `email`, `date-time`, `uri`
+- [ ] No `type: object` without properties (use `additionalProperties` explicitly)
+- [ ] No circular `$ref` without a nullable break
+
+______________________________________________________________________
+
+## Part 7: Security Schemes
+
+```yaml
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+    apiKey:
+      type: apiKey
+      in: header
+      name: X-API-Key
+
+security:
+  - bearerAuth: []   # Global default
+```
+
+Override at operation level where needed:
+
+```yaml
+paths:
+  /health:
+    get:
+      security: []   # Public endpoint — no auth required
+```
+
+Check:
+
+- [ ] Security scheme is defined in `components.securitySchemes`
+- [ ] Global `security` set at root level
+- [ ] Public endpoints explicitly override with `security: []`
+- [ ] OAuth2 scopes are defined if using OAuth
+- [ ] No API keys in query parameters (use headers)
+
+______________________________________________________________________
+
+## Part 8: Versioning
+
+URI versioning is the recommended approach:
+
+```yaml
+servers:
+  - url: https://api.example.com/v1
+```
+
+Check:
+
+- [ ] Version in server URL (`/v1`, `/v2`)
+- [ ] No minor versions in URL (`/v1.1` is wrong — use headers for minor)
+- [ ] Deprecated operations tagged with `deprecated: true`
+- [ ] Deprecated operations have a `x-sunset` date
+
+```yaml
+/users/{userId}:
+  get:
+    deprecated: true
+    x-sunset: "2027-01-01"
+    description: "Deprecated. Use /v2/users/{userId} instead."
+```
+
+______________________________________________________________________
+
+## Output
+
+Produce a review report or the corrected spec:
+
+**Review report format:**
+
+```text
+OpenAPI Spec Review
+═══════════════════
+
+Spec:    [filename]
+Version: [openapi version]
+Paths:   [count]
+Schemas: [count]
+
+Issues:
+  🔴 CRITICAL: [issue] — [path/operation]
+  🟡 WARNING:  [issue] — [path/operation]
+  🟢 INFO:     [suggestion]
+
+Summary: [N critical, N warnings, N info]
+```
+
+**If writing or correcting the spec:** produce the complete corrected YAML, using
+`$ref` for all reusable schemas, and validate it passes linting.

vstack/_templates/skills/performance/config.yaml

@@ -0,0 +1,15 @@
+name: performance
+version: 1.0.2
+description: |
+  Performance profiling and regression detection. Establishes baselines, detects
+  regressions, profiles bottlenecks, and recommends optimizations. Use when asked
+  to "profile", "benchmark", "performance test", or "is this faster?".
+argument-hint: '[endpoint or function to profile]'
+
+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/performance/template.md

@@ -0,0 +1,198 @@
+{{SKILL_CONTEXT}}
+
+{{BASE_BRANCH}}
+
+# performance — Profile, Benchmark & Regression Detection
+
+Profile backend services, detect performance regressions, and recommend
+optimizations. Measure first; never optimize without evidence.
+
+## Out of scope
+
+- Full code review (use `code-review`)
+- Security analysis (use `security`)
+- Architecture design (use `architecture`)
+- Non-performance bug fixing (use `debug`)
+
+## Deliverable and artifact policy
+
+- Primary deliverable: `docs/performance-baseline.md`
+- Baseline-first default: write benchmark outcomes and regression verdicts directly to `docs/performance-baseline.md` on the feature branch.
+- Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/PERFORMANCE_DELTA.md`
+- Before merge: consolidate thresholds, measurements, and recommendations into the baseline performance report.
+
+______________________________________________________________________
+
+## Setup
+
+**Parse the user's request:**
+
+| Parameter | Default                     | Override                                 |
+| --------- | --------------------------- | ---------------------------------------- |
+| Target    | Whole service / entry point | `Focus on the /search endpoint`          |
+| Mode      | Comparison (vs base branch) | `--baseline`, `--profile`, `--load-test` |
+| Threshold | 5% regression               | `--threshold 0.10` (10%)                 |
+
+______________________________________________________________________
+
+## Phase 1: Establish Baseline
+
+If on a feature branch, record performance metrics before and after the change:
+
+```bash
+# Record current branch metrics
+CURRENT=$(git branch --show-current)
+
+# Run benchmarks
+echo "=== Benchmarks on $CURRENT ==="
+{{RUN_TESTS}}
+
+# Language-specific benchmark runners:
+# Node/Bun
+[ -f package.json ] && npm run bench 2>/dev/null \
+  || npx vitest bench 2>/dev/null \
+  || npx jest --config jest.bench.config.js 2>/dev/null || true
+
+# Python
+[ -f pyproject.toml ] && python -m pytest --benchmark-only -v 2>/dev/null || true
+
+# Go
+[ -f go.mod ] && go test -bench=. -benchmem ./... 2>/dev/null || true
+
+# Rust
+[ -f Cargo.toml ] && cargo bench 2>/dev/null || true
+```
+
+______________________________________________________________________
+
+## Phase 2: Comparison vs Base Branch
+
+```bash
+# Stash current changes and benchmark base
+git stash
+git checkout <base>
+
+echo "=== Benchmarks on <base> ==="
+# [run same benchmark commands as Phase 1]
+
+# Restore feature branch
+git checkout "$CURRENT"
+git stash pop
+```
+
+Compare results:
+
+- p50 latency change
+- p95/p99 latency change
+- Throughput (ops/second) change
+- Memory allocation change
+- CPU usage change
+
+**Regression threshold:** Flag if any metric degrades by more than 5% (or configured threshold).
+
+______________________________________________________________________
+
+## Phase 3: Load Testing (if applicable)
+
+```bash
+# Check for load test tools
+which k6 2>/dev/null && echo "k6 available"
+which hey 2>/dev/null && echo "hey available"
+which wrk 2>/dev/null && echo "wrk available"
+which ab 2>/dev/null && echo "ab available"
+
+# Example k6 run (adapt to your endpoint)
+# k6 run --vus 50 --duration 30s script.js
+```
+
+For API endpoints, run a basic load test:
+
+```bash
+# Using hey (install: go install github.com/rakyll/hey@latest)
+hey -n 1000 -c 50 "${SERVICE_URL}/health" 2>/dev/null || true
+
+# Using wrk (if available)
+wrk -t4 -c100 -d30s "${SERVICE_URL}/health" 2>/dev/null || true
+```
+
+______________________________________________________________________
+
+## Phase 4: Profiling (if regression found)
+
+If a regression is detected, profile to identify the bottleneck:
+
+```bash
+# Node.js profiling
+node --prof app.js &
+# ...run workload...
+node --prof-process isolate-*.log > profile.txt
+
+# Python profiling
+python -m cProfile -o profile.prof app.py
+python -m pstats profile.prof
+
+# Go pprof
+go tool pprof cpu.prof
+```
+
+Common bottleneck categories:
+
+- **N+1 queries:** Multiple DB calls where one would suffice
+- **Serialization:** JSON marshal/unmarshal overhead
+- **Lock contention:** Mutex/lock held too long
+- **Memory allocation:** GC pressure from excessive allocations
+- **Missing cache:** Repeated computation of the same result
+- **Sync where async:** Blocking I/O on hot path
+- **Regex compilation:** Regex compiled inside hot loop
+
+______________________________________________________________________
+
+## Phase 5: Optimization Loop
+
+For each bottleneck identified:
+
+1. Propose the optimization with rationale
+1. Implement
+1. Re-benchmark
+1. Confirm improvement
+
+**Optimization principles:**
+
+- Measure first, optimize second. Never guess what's slow.
+- Profile the real workload, not synthetic microbenchmarks.
+- Big-O matters more than constant factors.
+- Cache invalidation is a correctness problem, not just a performance trick.
+- Async I/O > sync I/O for I/O-bound work.
+- Batch > N individual calls.
+
+______________________________________________________________________
+
+## Performance Report
+
+```text
+## Performance Report — [service/endpoint] — [date]
+
+### Benchmark Results
+
+| Metric | Base | Current | Change | Status |
+|--------|------|---------|--------|--------|
+| p50 latency | Xms | Xms | +N% | ✓/✗ |
+| p95 latency | Xms | Xms | +N% | ✓/✗ |
+| p99 latency | Xms | Xms | +N% | ✓/✗ |
+| Throughput (rps) | X | X | +N% | ✓/✗ |
+| Memory (MB) | X | X | +N% | ✓/✗ |
+
+### Regressions Found
+[NONE / List regressions]
+
+### Bottlenecks Identified
+1. [Bottleneck] — [Evidence] — [Recommended fix]
+
+### Optimizations Applied
+1. [Change] — [Before: Xms → After: Xms] — [Commit SHA]
+
+### Verdict
+[NO REGRESSION / REGRESSION FIXED / REGRESSION NEEDS ATTENTION]
+```
+
+______________________________________________________________________

vstack/_templates/skills/pr/config.yaml

@@ -0,0 +1,15 @@
+name: pr
+version: 1.0.2
+description: |
+  Commit, push, and open a pull request from the current branch to main.
+  Uses the release notes from docs/releases/{date}.md as the PR body.
+  Use when asked to "open a PR", "push and create PR", or "submit for review".
+
+license: MIT
+compatibility: Requires a skills-compatible agent with repository file access and terminal command execution when needed.
+metadata:
+  owner: vstack
+  maturity: stable
+argument-hint: '[task]'
+user-invocable: true
+disable-model-invocation: false