vstack 0.0.0__py3-none-any.whl

vstack/_templates/skills/code-review/template.md

@@ -0,0 +1,180 @@
+{{SKILL_CONTEXT}}
+
+{{BASE_BRANCH}}
+
+# code-review — Pre-Landing Code Review
+
+Review code before merging. Find bugs that pass CI but break in production.
+Report findings; do not change code unless explicitly asked.
+
+## Out of scope
+
+- Full security audit (use `security`)
+- Performance benchmarking (use `performance`)
+- Architecture design decisions (use `architecture`)
+- Running the test suite (use `verify`)
+
+Find bugs that will pass CI but break in production. Be specific — name files, lines, and
+scenarios. Be opinionated — give a recommendation, not just observations.
+
+## Review Principles
+
+- **API contracts are public promises.** Breaking changes must be flagged and versioned.
+- **Silent failures are catastrophic.** Every error path must be visible.
+- **Systems over heroes.** Code that requires intimate knowledge to debug safely is a liability.
+- **Observability is scope.** New codepaths without logs/metrics/traces are incomplete.
+- **Security is non-negotiable.** Authentication bypass, injection vulnerabilities, and secrets in code are blocking issues.
+
+## Step 0: Branch & Diff Setup
+
+```bash
+# Confirm we're on a feature branch, not base
+CURRENT=$(git branch --show-current)
+echo "Current branch: $CURRENT"
+echo "Base branch: <base>"
+
+# Show what this PR changes
+git diff <base> --stat | head -40
+git log <base>..HEAD --oneline
+```
+
+If on the base branch, STOP:
+
+> You appear to be on the base branch ($CURRENT). Review is most useful on a feature branch. Are you sure you want to continue reviewing uncommitted changes?
+
+## Step 1: Context Read
+
+Before reviewing diffs, read:
+
+1. The PR description / task description (if provided)
+1. Any design docs referenced
+1. Relevant existing code that the diff builds upon
+
+```bash
+# Read TODOS.md for context on deferred work
+cat TODOS.md 2>/dev/null | head -30 || true
+# Check for API spec
+cat openapi.yaml 2>/dev/null | head -50 || cat openapi.json 2>/dev/null | head -50 || true
+```
+
+## Step 2: Diff Review
+
+```bash
+git diff <base> -- $(git diff <base> --name-only | grep -v node_modules | grep -v vendor | head -30)
+```
+
+Review each changed file for:
+
+### 2.1 API Contract
+
+- [ ] Any new or changed endpoints listed in OpenAPI/spec?
+- [ ] Breaking changes? (field removal, type change, status code change)
+- [ ] Error responses consistent with API conventions?
+- [ ] Pagination/filtering contracts consistent?
+
+### 2.2 Error Handling
+
+- [ ] Every exception has a name, a handler, and a user-visible representation?
+- [ ] No bare `catch (e) {}` or `except Exception: pass`?
+- [ ] HTTP 5xx vs 4xx used correctly?
+- [ ] Timeouts set on all external calls?
+- [ ] Retry logic present where needed? Are operations idempotent?
+
+### 2.3 Data Integrity
+
+- [ ] Database migrations backward-compatible? (expand-contract pattern)
+- [ ] No raw SQL vulnerable to injection?
+- [ ] Transactions used where multiple writes must be atomic?
+- [ ] Optimistic locking where concurrent writes are possible?
+- [ ] No unbounded queries (missing LIMIT, full table scan)?
+
+### 2.4 Distributed Systems
+
+- [ ] All state-mutating external calls are idempotent?
+- [ ] Circuit breakers / bulkheads present for critical dependencies?
+- [ ] No synchronous cascade — single slow dependency can't block the whole request?
+- [ ] Eventual consistency acknowledged where applicable?
+- [ ] Message deduplication strategy for async consumers?
+
+### 2.5 Security
+
+- [ ] Authentication checked at every new endpoint?
+- [ ] Authorization checked — not just "is logged in" but "has permission for THIS resource"?
+- [ ] All user-controlled input validated and sanitized?
+- [ ] No secrets, credentials, or PII in logs?
+- [ ] Secrets in secure storage, not hardcoded or in env files?
+- [ ] CSRF protection for state-mutating endpoints?
+
+### 2.6 Observability
+
+- [ ] New codepaths emit structured logs with correlation IDs?
+- [ ] Error paths logged at ERROR level with stack traces?
+- [ ] New metrics/counters/histograms added for new operations?
+- [ ] Distributed trace spans for cross-service calls?
+- [ ] New failure modes visible in existing dashboards / alerts?
+
+### 2.7 Testing
+
+- [ ] Tests cover happy path AND error paths?
+- [ ] Test coverage adequate for risk level?
+- [ ] Tests don't rely on implementation details (test behavior, not internals)?
+- [ ] No flaky tests introduced (timing-dependent, order-dependent)?
+- [ ] Contract tests added or updated for API changes?
+
+### 2.8 Performance
+
+- [ ] No N+1 database queries?
+- [ ] Expensive operations cached where appropriate?
+- [ ] No unbounded data loads (always paginated)?
+- [ ] Sync operations that should be async?
+
+### 2.9 Code Quality
+
+- [ ] DRY — no copy-pasted logic?
+- [ ] Functions/methods do one thing?
+- [ ] Naming is clear and consistent with codebase conventions?
+- [ ] No magic numbers/strings without named constants?
+- [ ] Comments explain WHY, not WHAT?
+
+## Step 3: Checklist Enforcement
+
+Check for a project-specific review checklist:
+
+```bash
+cat .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null || true
+cat docs/review-checklist.md 2>/dev/null || true
+```
+
+If a project-specific checklist exists, verify each item.
+
+## Step 4: Final Report
+
+For each issue found, classify:
+
+- **BLOCKING:** Must be fixed before merge. (Security, data integrity, silent failures, broken API contracts)
+- **IMPORTANT:** Should be fixed in this PR. (Missing tests, error handling gaps, observability)
+- **SUGGESTION:** Consider for this PR or defer. (Refactoring, style, non-blocking improvements)
+
+Format:
+
+```text
+## Code Review — [branch name] — [date]
+
+### BLOCKING Issues (must fix before merge)
+1. **[Category]** `path/to/file.ts:42` — [Issue description]
+   Evidence: [specific code or behavior]
+   Fix: [recommended change]
+
+### IMPORTANT Issues (should fix in this PR)
+...
+
+### SUGGESTIONS (optional improvements)
+...
+
+### Overall Assessment
+[APPROVED / APPROVED WITH SUGGESTIONS / REQUEST CHANGES]
+
+Confidence: [HIGH/MEDIUM/LOW — explain if not HIGH]
+```
+
+______________________________________________________________________

vstack/_templates/skills/concise/config.yaml

@@ -0,0 +1,16 @@
+name: concise
+version: 1.0.1
+description: |
+  Runtime response-style controller for concise communication. Switches between
+  normal, compact, and ultra output density without regenerating agents. Use
+  when asked for shorter responses, token efficiency, or to check active style
+  mode.
+argument-hint: '[normal|compact|ultra|status|on|off]'
+
+license: MIT
+compatibility: Requires a skills-compatible agent with session memory and repository context.
+metadata:
+  owner: vstack
+  maturity: stable
+user-invocable: true
+disable-model-invocation: false

vstack/_templates/skills/concise/template.md

@@ -0,0 +1,128 @@
+{{SKILL_CONTEXT}}
+
+# concise — Runtime Response Style Mode
+
+Control response brevity at runtime without regenerating any agent artifacts.
+
+## Out of scope
+
+- Rewriting or mutating source code, scripts, commands, or API contracts
+- Persisting style mode across independent chat sessions
+- Overriding safety-critical clarity requirements
+
+______________________________________________________________________
+
+## Commands
+
+Supported commands:
+
+- `concise normal`
+- `concise compact`
+- `concise ultra`
+- `concise status`
+
+Compatibility aliases:
+
+- `concise on` -> `concise compact`
+- `concise off` -> `concise normal`
+
+Unknown arguments:
+
+- If argument is unknown, do not guess. Return usage and keep current mode unchanged.
+
+______________________________________________________________________
+
+## Mode Semantics
+
+- `normal`: full, explicit explanation depth.
+- `compact`: default concise mode; shorter prose, unchanged technical accuracy.
+- `ultra`: maximal brevity; remove narrative filler, keep technical correctness.
+
+Hard invariants for all concise modes:
+
+- Keep code blocks, commands, paths, and symbols exact.
+- Do not remove required warnings, constraints, or irreversible-action cautions.
+- Never trade correctness for brevity.
+
+______________________________________________________________________
+
+## Priority and Resolution
+
+Resolve active mode with this precedence:
+
+1. Explicit user command in current turn (`concise ...`)
+1. Session override (last accepted concise mode command)
+1. Agent default mode
+1. Global default mode (`normal`)
+
+`concise status` must show:
+
+- active mode
+- session override value (or none)
+- agent default mode
+- global default mode
+- whether auto-clarity override is currently active
+
+______________________________________________________________________
+
+## Suggested Agent Defaults
+
+When no session override exists, use these defaults:
+
+- `product`: `compact`
+- `architect`: `normal`
+- `designer`: `compact`
+- `engineer`: `compact`
+- `tester`: `ultra`
+- `release`: `compact`
+
+______________________________________________________________________
+
+## Auto-Clarity Override (Mandatory)
+
+Temporarily force `normal` regardless of active concise mode for:
+
+- security warnings
+- destructive or irreversible actions
+- multi-step sequences where truncation can cause ordering mistakes
+- user confusion or repeated clarification requests
+
+After the high-clarity segment ends, return to previously active concise mode.
+
+______________________________________________________________________
+
+## Expected Responses
+
+On successful mode switch:
+
+```text
+Concise mode set to <mode>.
+```
+
+On status request:
+
+```text
+concise status
+active: <mode>
+session override: <value|none>
+agent default: <mode>
+global default: normal
+auto-clarity override: <active|inactive>
+```
+
+On invalid argument:
+
+```text
+Unknown concise mode: <value>
+Usage: concise normal|compact|ultra|status|on|off
+Current mode unchanged: <mode>
+```
+
+______________________________________________________________________
+
+## Completion Checklist
+
+- [ ] Command parsed and validated
+- [ ] Mode switched or preserved according to rules
+- [ ] Safety/clarity override honored where required
+- [ ] User confirmation/status returned in deterministic format

vstack/_templates/skills/consult/config.yaml

@@ -0,0 +1,18 @@
+name: consult
+version: 1.0.2
+description: |
+  DX triage and focused review. First classifies whether the request is API DX,
+  CLI/tool DX, or developer workflow DX, then runs exactly one review path with
+  0-10 scoring and ROI-ranked improvements. Routes non-DX requests to the right
+  specialized skill (analyse/debug/security/performance/design/verify/code-review).
+  Use when asked to "review DX", "review API usability", "review CLI experience",
+  or "review developer workflow friction".
+argument-hint: '[API, tool, or workflow to consult]'
+
+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/consult/template.md

@@ -0,0 +1,195 @@
+{{SKILL_CONTEXT}}
+
+# consult — DX Triage and Focused Review
+
+Classify the request first, then run exactly one focused DX review path.
+If the request is not DX-focused, route to the correct specialized skill.
+Read only — do not change any code.
+
+## Out of scope
+
+- Building or redesigning APIs from scratch (use `design`)
+- Implementation of improvements (engineering role)
+- Full verification or contract testing (use `verify`)
+- Architecture decisions (use `architecture`)
+- Root-cause debugging (use `debug`)
+- Security audits (use `security`)
+- Performance profiling/regression analysis (use `performance`)
+- Tradeoff/impact/feasibility analysis (use `analyse`)
+
+______________________________________________________________________
+
+## Step 0: Classify and Route
+
+Determine the user's real intent before reviewing anything.
+
+```bash
+# Quick context snapshot
+ls openapi.yaml openapi.json asyncapi.yaml 2>/dev/null | head -5 || true
+cat README.md 2>/dev/null | head -25 || true
+```
+
+> **Question:** Which path matches the request best?
+> **Options:**
+> A) API DX review
+> B) CLI/tool DX review
+> C) Developer workflow DX review (onboarding/CI/tooling)
+> D) Not DX (route to another skill)
+> **Default if no response:** A
+
+If D, stop and return this routing recommendation:
+
+- API/service design from scratch -> `design`
+- Technical impact/tradeoff analysis -> `analyse`
+- Root-cause investigation -> `debug`
+- Pre-merge risk review -> `code-review`
+- Security audit -> `security`
+- Performance profiling/regression check -> `performance`
+- Verification/fix loop -> `verify`
+
+Do not continue with DX scoring when routing to another skill.
+
+______________________________________________________________________
+
+## Step 1: Run Exactly One Path
+
+Run only the selected path (A, B, or C). Skip all others.
+
+### Path A — API DX Review
+
+Rate each dimension 0-10. Explain the current score and what a 10 looks like.
+
+#### A1. Naming and Consistency
+
+- Are resource names plural nouns? (`/users`, not `/user`, `/getUser`)
+- Are action names consistent? (REST verbs via HTTP method, not in path)
+- Are field names consistently cased? (camelCase or snake_case — not mixed)
+- Are boolean flags named clearly? (`is_active`, not `active`)
+- Are error codes human-readable? (`INVALID_EMAIL`, not `ERR_400_02`)
+
+#### A2. Error UX
+
+- Does every error response include a human-readable `message`?
+- Does every error include a machine-readable `code` for programmatic handling?
+- Does every validation error identify the specific field that failed?
+- Are errors actionable? ("Email already in use" not "Conflict")
+- Are error codes documented?
+
+#### A3. Contract and Envelope Consistency
+
+- Is the response envelope consistent across all endpoints?
+- Are pagination responses consistent? (same cursor/offset shape)
+- Is there a `data` wrapper vs direct object — consistent?
+- Is the `null` contract clear? (field absent vs `null` vs empty array)
+
+#### A4. Auth Integrator Experience
+
+- Is the auth flow simple to implement for a new integrator?
+- Are auth errors clear? (401 vs 403, explained)
+- Are token expiry and refresh mechanisms obvious?
+- Is there a "getting started" auth example?
+
+#### A5. Versioning and Documentation
+
+- Is the versioning strategy documented? (`/v1/`, `Accept` header, custom header)
+- Are breaking change policies documented?
+- Is there a deprecation timeline?
+- Are deprecated fields/endpoints marked in the API spec?
+- Does every endpoint have a description and examples?
+
+#### A6. SDK Ergonomics (if applicable)
+
+- If an SDK is provided: is it idiomatic for the target language?
+- Does the SDK handle pagination, retries, and auth automatically?
+- Is the SDK versioned and published to the target package registry?
+- Are there typed responses?
+
+### Path B — CLI/Tool DX Review
+
+#### B1. Onboarding Speed
+
+- How many commands to get to "hello world"?
+- Is there a `--help` at every level?
+- Does the tool guide you when required args are missing?
+
+#### B2. Error Messages and Feedback
+
+- Are error messages actionable? (not "command failed")
+- Do errors include the remediation step?
+- Is progress shown for long operations?
+
+#### B3. Discoverability
+
+- Can you discover all commands via `--help`?
+- Are subcommands logical and grouped?
+- Is there autocomplete?
+
+### Path C — Developer Workflow DX Review
+
+#### C1. Local Setup Friction
+
+```bash
+cat README.md 2>/dev/null | grep -A 20 "Getting Started\|Installation\|Setup" | head -25
+ls docker-compose.yml Makefile .devcontainer/ 2>/dev/null || true
+```
+
+- Can a new developer be productive within 30 minutes?
+- Is local dev environment reproducible?
+- Are environment variables documented?
+
+#### C2. CI Feedback Speed
+
+```bash
+cat .github/workflows/*.yml 2>/dev/null | grep -E 'timeout|runs-on|steps' | head -20
+```
+
+- How long does CI take?
+- Are fast checks (lint, type) run before slow checks (tests)?
+- Is CI feedback specific about what failed and where?
+
+#### C3. Quality Tooling Loop
+
+- Is there a formatter configured?
+- Is there a linter with a clear rule set?
+- Is there type checking?
+- Are these run on commit (pre-commit hooks) or in CI?
+
+______________________________________________________________________
+
+## Step 2: Improvement Plan (ROI-first)
+
+For each weak area (typically score < 7), provide:
+
+1. **Quick win (< 2 hours):** Highest immediate impact.
+1. **Medium investment (1-2 days):** Most likely path to 9/10.
+1. **Long-term:** Structural change to reach 10/10.
+
+______________________________________________________________________
+
+## Output Contract
+
+```text
+## Consult Report — [project/API/tool] — [date]
+
+selected_path: [A API DX | B CLI DX | C Workflow DX | D Routed]
+overall_score: [N/10 or N/A when routed]
+
+### Scores
+| Dimension | Score | Quick Win |
+|-----------|-------|-----------|
+| [Dimension 1] | N/10 | [Quick win] |
+| [Dimension 2] | N/10 | [Quick win] |
+| [Dimension 3] | N/10 | [Quick win] |
+| **Overall** | **N/10** | |
+
+### Top 3 Improvements (by ROI)
+1. [Highest leverage change]
+2. [Second highest]
+3. [Third]
+
+### Routing (only when selected_path = D)
+recommended_skill: [design|analyse|debug|code-review|security|performance|verify]
+reason: [one sentence]
+```
+
+______________________________________________________________________

vstack/_templates/skills/container/config.yaml

@@ -0,0 +1,17 @@
+name: container
+version: 1.0.2
+description: |
+  Write and review Dockerfile, docker-compose, and container configuration.
+  Covers multi-stage builds, image hardening, non-root users, minimal base images,
+  layer optimisation, and local development compose setup.
+  Use when asked to "containerise", "write a Dockerfile", "add docker-compose",
+  or "harden the container image".
+argument-hint: '[service to containerise]'
+
+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/container/template.md

@@ -0,0 +1,122 @@
+{{SKILL_CONTEXT}}
+
+# container — Dockerfile & Compose
+
+Write production-grade container configuration for the service.
+
+## Out of scope
+
+- CI/CD pipeline configuration (use `cicd`)
+- Kubernetes manifests (use `cicd`)
+- Application code changes (engineering role)
+
+______________________________________________________________________
+
+## Step 1: Detect context
+
+```bash
+# Detect runtime
+ls pyproject.toml requirements.txt package.json go.mod Cargo.toml pom.xml 2>/dev/null | head -5
+
+# Detect existing container config
+ls Dockerfile* docker-compose* .dockerignore 2>/dev/null || echo "No container config found"
+```
+
+______________________________________________________________________
+
+## Step 2: Dockerfile
+
+Write a multi-stage `Dockerfile` following these rules:
+
+**Base image:**
+
+- Use an official, minimal image: `python:3.12-slim`, `node:22-alpine`, `golang:1.22-alpine`, etc.
+- Never use `latest` — pin to a specific version tag
+- Prefer `alpine` or `slim` variants for production stage
+
+**Multi-stage build:**
+
+```dockerfile
+# Stage 1: build / install dependencies
+FROM <runtime>:<version> AS builder
+WORKDIR /app
+COPY <dependency files> .
+RUN <install deps>
+
+# Stage 2: production image
+FROM <runtime>:<version>-slim AS runtime
+WORKDIR /app
+COPY --from=builder /app /app
+```
+
+**Security hardening:**
+
+- Run as non-root user:
+
+  ```dockerfile
+  RUN addgroup --system app && adduser --system --ingroup app app
+  USER app
+  ```
+
+- Drop capabilities where applicable
+
+- No secrets in image layers — use environment variables or mounted secrets at runtime
+
+- Set `HEALTHCHECK` instruction
+
+**Layer optimisation:**
+
+- Copy dependency files first, then source (cache busting only on source change)
+- Combine `RUN` steps with `&&` to minimise layers
+- Add `.dockerignore` excluding: `.git`, `node_modules`, `__pycache__`, `*.pyc`, `dist`, `build`, local env files
+
+**Port and entrypoint:**
+
+```dockerfile
+EXPOSE <port>
+ENTRYPOINT ["<executable>"]
+CMD ["<default args>"]
+```
+
+______________________________________________________________________
+
+## Step 3: docker-compose.yml (local dev)
+
+Write `docker-compose.yml` for local development:
+
+```yaml
+services:
+  app:
+    build: .
+    ports:
+      - "<host>:<container>"
+    environment:
+      - <ENV_VAR>=<value>
+    depends_on:
+      - <dependency>
+    volumes:
+      - .:/app          # hot-reload in dev only — remove for prod
+
+  # Add dependencies: database, cache, broker
+  # db:
+  #   image: postgres:16-alpine
+  # cache:
+  #   image: redis:7-alpine
+```
+
+For production-like local testing, write a separate `docker-compose.prod.yml` without volume mounts.
+
+______________________________________________________________________
+
+## Step 4: Review checklist
+
+- [ ] No `latest` tags
+- [ ] Multi-stage build — production image contains no build tools
+- [ ] Non-root user
+- [ ] `.dockerignore` present and complete
+- [ ] No secrets baked into image
+- [ ] `HEALTHCHECK` defined
+- [ ] Image builds successfully: `docker build -t app:local .`
+- [ ] Container starts and responds: `docker run --rm -p <port>:<port> app:local`
+
+______________________________________________________________________

vstack/_templates/skills/debug/config.yaml

@@ -0,0 +1,16 @@
+name: debug
+version: 1.0.2
+description: |
+  Systematic root-cause debugging for backend services, APIs, and libraries.
+  No fixes without investigation. Follows the scientific method: observe →
+  hypothesize → test → conclude → fix → prevent. Use when asked to "debug",
+  "investigate", "find the root cause", or "why is this broken?".
+argument-hint: '[issue or error to debug]'
+
+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