vstack 0.0.0__py3-none-any.whl

vstack/_templates/skills/design/template.md

@@ -0,0 +1,231 @@
+{{SKILL_CONTEXT}}
+
+# design — API & Service Design
+
+Produce a complete service or API design document from minimal input. The output
+becomes the source of truth for implementation.
+
+## Out of scope
+
+- Reviewing existing DX/ergonomics (use `consult`)
+- Architecture review (use `architecture`)
+- Implementation (engineering role)
+- Contract compliance validation (use `verify` or `code-review`)
+
+______________________________________________________________________
+
+## Deliverable and artifact policy
+
+- Primary deliverable: `docs/design/design.md`
+- Additional deliverable when user-facing scope: `docs/design/ux.md`
+- Baseline-first default: write final design decisions directly to `docs/design/*.md` on the feature branch.
+- Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/DESIGN_DELTA.md`
+- Before merge: consolidate any delta draft into baseline design docs.
+
+______________________________________________________________________
+
+## Step 0: Understand the Domain
+
+> **Question:** What are we designing?
+> **Options:**
+> A) REST API for a new service
+> B) gRPC service / Protobuf schema
+> C) Event-driven API (AsyncAPI / Kafka topics)
+> D) Library / SDK public interface
+> E) Internal service interface (service-to-service)
+> **Default if no response:** A
+
+Gather context:
+
+```bash
+# Existing code/contracts
+find . -name 'openapi*' -o -name '*.proto' -o -name 'asyncapi*' 2>/dev/null | head -5
+```
+
+______________________________________________________________________
+
+## Step 1: Resource Design
+
+For each resource/entity in the domain:
+
+1. **Name:** Plural noun (`users`, `orders`, `payments`)
+1. **Ownership:** Which service owns this resource?
+1. **Lifecycle:** What states can it be in?
+1. **Relationships:** What resources does it reference?
+
+Produce an entity diagram. Prefer Mermaid when possible; use ASCII as a fallback
+only when Mermaid support is unavailable or would reduce clarity.
+
+```mermaid
+erDiagram
+  USER ||--o{ ORDER : places
+  USER {
+    string id
+    string email
+    string name
+  }
+  ORDER {
+    string id
+    string user_id
+    string status
+  }
+```
+
+______________________________________________________________________
+
+## Step 2: Endpoint Design
+
+For each resource, define CRUD + custom actions:
+
+```yaml
+# Example
+GET    /users          # List (paginated)
+POST   /users          # Create
+GET    /users/{id}     # Get by ID
+PATCH  /users/{id}     # Update (partial)
+DELETE /users/{id}     # Soft delete
+
+# Custom actions (use sub-resources or action paths)
+POST   /users/{id}/activate    # Non-CRUD action
+POST   /users/{id}/deactivate
+```
+
+______________________________________________________________________
+
+## Step 3: Request/Response Conventions
+
+Define the standard envelope:
+
+```yaml
+# Success response (single resource)
+{
+  "data": { ... },
+  "meta": { "request_id": "...", "version": "v1" }
+}
+# Success response (collection)
+{
+  "data": [ ... ],
+  "pagination": {
+    "cursor": "...",
+    "has_next": true,
+    "total": 1000
+  },
+  "meta": { "request_id": "...", "version": "v1" }
+}
+
+# Error response
+{
+  "error": {
+    "code": "VALIDATION_FAILED",
+    "message": "Request validation failed",
+    "details": [
+      { "field": "email", "issue": "Invalid email format" }
+    ]
+  },
+  "meta": { "request_id": "...", "version": "v1" }
+}
+```
+
+______________________________________________________________________
+
+## Step 4: Error Code Taxonomy
+
+Define a machine-readable error code taxonomy:
+
+```text
+# Auth errors
+UNAUTHENTICATED       — No valid credentials provided
+UNAUTHORIZED          — Credentials valid but permission denied
+TOKEN_EXPIRED         — JWT or session token has expired
+RATE_LIMITED          — Too many requests
+
+# Validation errors
+VALIDATION_FAILED     — Request body/params failed validation
+INVALID_FORMAT        — Field format invalid (e.g., not a valid UUID)
+MISSING_REQUIRED      — Required field absent
+CONSTRAINT_VIOLATED   — Business constraint violated
+
+# Resource errors
+NOT_FOUND             — Resource doesn't exist
+CONFLICT              — Resource state conflict (e.g., duplicate)
+GONE                  — Resource permanently deleted
+
+# System errors
+INTERNAL_ERROR        — Unexpected server error (don't expose details)
+DEPENDENCY_ERROR      — Upstream service failure
+UNAVAILABLE           — Service temporarily unavailable
+```
+
+______________________________________________________________________
+
+## Step 5: Versioning & Contract Discipline
+
+Define the versioning approach:
+
+```text
+Versioning: URL path prefix (/v1/, /v2/)
+Breaking change policy: 12-month minimum support after deprecation
+Deprecation process:
+  1. Add Deprecation header with sunset date
+  2. Add X-API-Warn header with migration path
+  3. Update docs with migration guide
+  4. Remove version only after sunset date
+```
+
+### API Contract Checklist
+
+- [ ] OpenAPI / AsyncAPI spec updated for any new or changed endpoints
+- [ ] Breaking changes flagged (field removal, type change, required→optional, enum value removal)
+- [ ] Backward-compatible changes documented (new optional fields, new enum values)
+- [ ] Error response envelopes consistent with existing API conventions
+- [ ] Pagination contract consistent (cursor vs offset, envelope shape)
+- [ ] Rate limiting headers documented if applicable
+- [ ] Authentication/authorization contracts documented
+- [ ] Semver bump reflects compatibility level:
+  - PATCH → bug fix, no contract change
+  - MINOR → new optional fields, backward compatible
+  - MAJOR → breaking change
+
+______________________________________________________________________
+
+## Step 6: Authentication & Authorization
+
+```text
+Auth mechanism: Bearer token (JWT)
+Token lifecycle: Access (15min) + Refresh (30 days)
+Token claims: user_id, roles[], tenant_id
+Authorization model: RBAC with per-resource checks
+```
+
+______________________________________________________________________
+
+## Step 7: Produce the Design Document
+
+Output a complete design document to `docs/design/design.md` or `openapi.yaml`:
+
+```markdown
+# API Design — [Service Name]
+
+## Overview
+[One paragraph purpose]
+
+## Resources
+[Entity diagram + table]
+
+## Endpoints
+[Endpoint table]
+
+## Conventions
+[Request/response envelope, error codes, pagination]
+
+## Versioning
+[Strategy and policy]
+
+## Authentication
+[Auth flow and token lifecycle]
+
+## Security
+[Input validation, rate limiting, CORS policy]
+```
+
+______________________________________________________________________

vstack/_templates/skills/docs/config.yaml

@@ -0,0 +1,17 @@
+name: docs
+version: 1.0.2
+description: |
+  Post-release documentation alignment. Updates README, API docs, migration
+  guides, and related docs to match shipped behavior. Does not own release-note
+  generation or CHANGELOG updates.
+  Use after release or deploy, or when asked to "update docs", "align
+  documentation", or "refresh README/API docs".
+argument-hint: '[release or change 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/docs/template.md

@@ -0,0 +1,128 @@
+{{SKILL_CONTEXT}}
+
+{{BASE_BRANCH}}
+
+# docs — Post-Release Documentation Update
+
+Update all documentation to match what was just shipped. Report and write; do not
+change source code.
+
+## Out of scope
+
+- Code changes or bug fixes (use `verify` or `debug`)
+- Creating the PR (use `pr`)
+- Generating release notes (use `release-notes`)
+- Updating `CHANGELOG.md` (owned by `release-notes`)
+
+## Deliverable and artifact policy
+
+- Primary deliverables: updated baseline documentation artifacts (for example `README.md`, API docs, migration guides)
+- Baseline-first default: write final documentation updates directly to baseline docs on the feature branch.
+- Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/DOCS_DELTA.md`
+- Before merge: consolidate any documentation delta notes into baseline docs.
+
+______________________________________________________________________
+
+## Step 0: Scope the Release
+
+```bash
+# What changed in this release?
+git log <base>..HEAD --oneline
+git diff <base> --stat | head -30
+
+# Current version
+cat VERSION 2>/dev/null \
+  || node -p "require('./package.json').version" 2>/dev/null \
+  || echo "unknown"
+```
+
+______________________________________________________________________
+
+## Step 1: README
+
+Review whether README needs updates:
+
+```bash
+cat README.md 2>/dev/null | head -60
+```
+
+Check:
+
+- [ ] Installation instructions still accurate?
+- [ ] "Getting started" example still works?
+- [ ] Feature list reflects new capabilities?
+- [ ] Any deprecated features removed from featured examples?
+- [ ] Badges (version, CI status) still accurate?
+
+______________________________________________________________________
+
+## Step 2: API Documentation
+
+If there's an OpenAPI / AsyncAPI spec:
+
+```bash
+cat openapi.yaml 2>/dev/null | head -40 || true
+```
+
+Check:
+
+- [ ] Spec version matches VERSION?
+- [ ] New endpoints documented?
+- [ ] Changed endpoints updated?
+- [ ] Deprecated endpoints marked with `deprecated: true`?
+- [ ] Response examples accurate?
+
+If there's generated API documentation (Swagger UI, Redoc, TypeDoc, Sphinx):
+
+```bash
+npm run docs 2>/dev/null || make docs 2>/dev/null || true
+```
+
+______________________________________________________________________
+
+## Step 3: MIGRATIONS Guide (if applicable)
+
+If this release contains breaking changes or migration steps:
+
+- Create or update `MIGRATIONS.md` or `docs/migrations/vX.md`
+- Document: why the change was made, what behavior changed, migration steps, code examples
+
+______________________________________________________________________
+
+## Step 4: Code Comments & ADRs
+
+For significant architectural changes:
+
+- Check if inline code comments reference outdated behavior
+
+- Add an Architecture Decision Record in `docs/architecture/adr/` if a significant decision was made
+
+  (use the `adr` skill for the full ADR writing procedure)
+
+______________________________________________________________________
+
+## Step 5: Commit Documentation Updates
+
+```bash
+git add README.md openapi.yaml docs/ 2>/dev/null || true
+git commit -m "docs: update documentation for v$(cat VERSION 2>/dev/null || echo 'unknown')"
+```
+
+______________________________________________________________________
+
+## Summary
+
+```text
+## Documentation Update — v[VERSION] — [date]
+
+Updated:
+- [ ] README.md
+- [ ] API spec (openapi.yaml)
+- [ ] Migration guide (if breaking changes)
+- [ ] ADR (if architectural decision)
+
+Skipped (n/a):
+- [ ] [reason]
+```
+
+______________________________________________________________________

vstack/_templates/skills/explore/config.yaml

@@ -0,0 +1,17 @@
+name: explore
+version: 1.0.2
+description: |
+  Repository and system discovery. Maps the architecture, understands the
+  codebase, identifies technical debt, and produces a structured onboarding
+  summary. Use at the start of any engagement with an unfamiliar codebase,
+  when asked to "understand this codebase", "map the architecture", "explore
+  the repo", or "what does this service do?".
+argument-hint: '[repository or system to explore]'
+
+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/explore/template.md

@@ -0,0 +1,188 @@
+{{SKILL_CONTEXT}}
+
+# explore — Codebase & Architecture Discovery
+
+Map an unfamiliar codebase and produce a structured onboarding summary.
+Report findings; do not change code.
+
+## Out of scope
+
+- Fixing issues found during exploration (use `debug` or `verify`)
+- Architecture recommendations (use `architecture`)
+- Performance analysis (use `performance` or `analyse`)
+
+______________________________________________________________________
+
+## Phase 1: Project Overview
+
+```bash
+# Identify project type and tech stack
+ls -la
+cat README.md 2>/dev/null | head -60 || cat README.rst 2>/dev/null | head -60 || true
+cat package.json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print('Name:', d.get('name'), '| Version:', d.get('version'), '| Main:', d.get('main',''))" 2>/dev/null || true
+cat pyproject.toml 2>/dev/null | head -20 || true
+cat go.mod 2>/dev/null | head -10 || true
+cat Cargo.toml 2>/dev/null | head -10 || true
+```
+
+Record:
+
+- **Project name and purpose**
+- **Tech stack** (language, framework, runtime)
+- **Project type** (API service, library, CLI, worker, monorepo)
+
+______________________________________________________________________
+
+## Phase 2: Directory Structure
+
+```bash
+# Top-level structure
+find . -maxdepth 3 -not -path '*/node_modules/*' -not -path '*/.git/*' \
+  -not -path '*/vendor/*' -not -path '*/__pycache__/*' -not -path '*/dist/*' \
+  -not -path '*/.venv/*' | sort | head -80
+```
+
+Identify:
+
+- Where source code lives (`src/`, `lib/`, `pkg/`, top-level)
+- Where tests live (`test/`, `tests/`, `spec/`, `__tests__/`)
+- Where configs live (`config/`, `.env*`, `*config.yaml`)
+- CI/CD configuration (`.github/workflows/`, `.gitlab-ci.yml`, etc.)
+- Infrastructure code (`k8s/`, `terraform/`, `docker-compose.yml`)
+
+______________________________________________________________________
+
+## Phase 3: Dependencies & External Services
+
+```bash
+# Dependency overview
+cat package.json 2>/dev/null | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+deps = {**d.get('dependencies',{}), **d.get('devDependencies',{})}
+print('Dependencies:', len(deps))
+for k,v in list(deps.items())[:20]: print(f'  {k}: {v}')
+" 2>/dev/null || true
+
+cat pyproject.toml 2>/dev/null | grep -A 20 '\[tool.poetry.dependencies\]' | head -25 || true
+cat go.mod 2>/dev/null | grep -E '^require|^\t' | head -20 || true
+
+# External services referenced
+grep -r -E 'postgres|mysql|redis|mongodb|kafka|rabbitmq|elasticsearch|dynamodb|s3' \
+  --include='*.ts' --include='*.py' --include='*.go' --include='*.yaml' --include='*.env*' \
+  --exclude-dir=node_modules --exclude-dir=vendor . 2>/dev/null | grep -v test | head -20
+```
+
+______________________________________________________________________
+
+## Phase 4: API & Service Contracts
+
+```bash
+# Check for API spec files
+find . -name 'openapi*.yaml' -o -name 'openapi*.json' -o -name 'swagger*.yaml' \
+  -o -name '*.proto' -o -name 'asyncapi*.yaml' 2>/dev/null | head -10
+
+# Check for route definitions
+grep -r -n '@app.route\|router\.\|@Get\|@Post\|path=' \
+  --include='*.ts' --include='*.py' --include='*.go' \
+  --exclude-dir=node_modules . 2>/dev/null | head -30
+```
+
+______________________________________________________________________
+
+## Phase 5: Test Infrastructure
+
+{{RUN_TESTS}}
+
+```bash
+# Test count and coverage setup
+find . -name '*.test.*' -o -name '*_test.*' -o -name '*spec.*' \
+  --exclude-dir=node_modules 2>/dev/null | wc -l
+
+# Coverage config
+cat .nycrc 2>/dev/null || cat vitest.config.* 2>/dev/null | head -20 || \
+  cat pytest.ini 2>/dev/null | head -20 || true
+```
+
+______________________________________________________________________
+
+## Phase 6: CI/CD Pipeline
+
+```bash
+# CI config
+ls .github/workflows/ 2>/dev/null | head -10
+cat .github/workflows/*.yml 2>/dev/null | head -80 || true
+cat .gitlab-ci.yml 2>/dev/null | head -60 || true
+```
+
+______________________________________________________________________
+
+## Phase 7: Technical Debt & Health
+
+```bash
+# Check for TODO/FIXME/HACK comments
+grep -r -n "TODO\|FIXME\|HACK\|XXX\|DEPRECATED\|BUG" \
+  --include='*.ts' --include='*.py' --include='*.go' \
+  --exclude-dir=node_modules . 2>/dev/null | head -30
+
+# Check for TODOS.md
+cat TODOS.md 2>/dev/null | head -40 || true
+```
+
+______________________________________________________________________
+
+## Discovery Report
+
+Produce a structured summary:
+
+```text
+## Discovery Report — [project name] — [date]
+
+### Overview
+Purpose: [one paragraph]
+Type:    [API service / library / CLI / worker / ...]
+Stack:   [language, framework, runtime versions]
+
+### Architecture
+[Mermaid diagram of service topology or module structure when possible; ASCII fallback if needed]
+
+### Data Stores
+
+- [Database]: [what it stores, ORM/driver used]
+- [Cache]: [what is cached, TTL strategy]
+
+### Key External Dependencies
+
+- [Service A]: [purpose, auth method]
+- [Service B]: [purpose]
+
+### API Surface
+
+[Summarize endpoints or exported functions]
+
+### Test Coverage
+
+- Unit tests: [Y/N, count, coverage %]
+- Integration tests: [Y/N]
+- Contract tests: [Y/N]
+
+### CI/CD
+
+- CI: [GitHub Actions/GitLab CI/etc]
+- Deploy target: [Fly.io/Render/K8s/etc]
+- Release process: [manual/automated]
+
+### Technical Debt
+
+- [Key items from TODOS.md or code comments]
+
+### Onboarding Notes
+
+- How to run locally: [command]
+- How to run tests: [command]
+- Key config: [env vars]
+- Gotchas: [anything that surprised me]
+
+```
+
+______________________________________________________________________

vstack/_templates/skills/guardrails/config.yaml

@@ -0,0 +1,16 @@
+name: guardrails
+version: 1.0.2
+description: |
+  Activate safety guardrails for the current session. Before any destructive
+  command (rm -rf, DROP TABLE, git push --force, git reset --hard, kubectl delete,
+  production config changes, database migrations) a confirmation is required.
+  Use when asked to "be careful", "enable guardrails", or "careful mode".
+disable-model-invocation: true
+
+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

vstack/_templates/skills/guardrails/template.md

@@ -0,0 +1,45 @@
+{{SKILL_CONTEXT}}
+
+# guardrails — Safety Mode
+
+Activate careful mode for this session. Two behaviors are now enabled.
+
+## Out of scope
+
+- Code review or security audit (use `code-review` or `security`)
+
+______________________________________________________________________
+
+## Behavior 1: Careful Mode (always active after invoking this skill)
+
+**Before executing any of the following commands, get explicit confirmation:**
+
+| Command                        | Risk                         | What to confirm             |
+| ------------------------------ | ---------------------------- | --------------------------- |
+| `rm -rf`                       | Permanent file deletion      | Files to delete             |
+| `DROP TABLE` / `DROP DATABASE` | Permanent data loss          | Table/database name         |
+| `git push --force`             | Overwrites remote history    | Branch and remote           |
+| `git reset --hard`             | Discards local changes       | What will be lost           |
+| `git clean -fd`                | Removes untracked files      | Files to remove             |
+| `kubectl delete`               | Removes Kubernetes resources | Resource name and namespace |
+| `fly destroy`                  | Destroys Fly.io app          | App name                    |
+| `docker rm -f`                 | Forcefully removes container | Container                   |
+| Any `--force` flag             | Bypasses safety check        | Why force is needed         |
+| Production config changes      | Affects live traffic         | Explicit approval           |
+| Database migrations            | May modify data schema       | Review migration SQL        |
+
+**Procedure for each dangerous command:**
+
+1. Stop.
+1. Explain exactly what the command does and what will be permanently lost.
+1. Ask for explicit confirmation.
+1. Only proceed if the user says yes.
+1. Never use workarounds to avoid this confirmation.
+
+______________________________________________________________________
+
+## How to Deactivate
+
+Explicitly ask to "disable guardrails".
+
+______________________________________________________________________

vstack/_templates/skills/incident/config.yaml

@@ -0,0 +1,17 @@
+name: incident
+version: 1.0.1
+description: |
+  Incident analysis and post-mortem writing. Guides a structured investigation
+  from timeline reconstruction through root cause identification to a blameless
+  post-mortem document with action items. Use when asked to "write a post-mortem",
+  "incident review", "root cause analysis for this outage", "what went wrong?",
+  or "blameless post-mortem". Produces a docs/postmortems/{date}-{slug}.md.
+argument-hint: '[incident or outage to analyse and 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