vstack 0.0.0__py3-none-any.whl

vstack/_templates/skills/debug/template.md

@@ -0,0 +1,247 @@
+{{SKILL_CONTEXT}}
+
+# debug — Systematic Root-Cause Investigation
+
+Investigate and fix bugs using the scientific method. No patches without understanding
+the root cause first.
+
+## Out of scope
+
+- Full code review (use `code-review`)
+- Performance benchmarking (use `performance`)
+- Architecture design (use `architecture`)
+- Security audit (use `security`)
+
+**Golden rule: No fixes without root cause. A patch without understanding creates two bugs.**
+
+Follow the scientific method:
+
+1. **Observe** — Gather all available evidence
+1. **Hypothesize** — Form ranked hypotheses
+1. **Test** — Write a reproducer, then eliminate hypotheses
+1. **Conclude** — Identify root cause with evidence
+1. **Fix** — Minimal change that addresses root cause
+1. **Prevent** — Add a test that would have caught this
+
+______________________________________________________________________
+
+## Step 0: Understand the Problem
+
+Before touching any code, gather complete context:
+
+**What exactly is failing?**
+
+> **Question:** Describe the problem completely.
+>
+> - What is the expected behavior?
+> - What is the actual behavior?
+> - When did it start failing? (sudden vs gradual)
+> - What was the last change before it started failing?
+> - Is it reproducible? Always, or intermittent?
+>   **Options:** A) Answer inline | B) I'll share logs/errors in the next message
+
+**Gather evidence:**
+
+```bash
+# Recent git history
+git log --oneline -20
+
+# Recent changes to the relevant area
+git log --oneline --follow -- path/to/suspect/file 2>/dev/null | head -10
+
+# Check for stashed work
+git stash list
+
+# Check for recent dependency changes
+git diff HEAD~10 -- package.json package-lock.json go.mod go.sum pyproject.toml 2>/dev/null | head -40
+```
+
+______________________________________________________________________
+
+## Step 1: Reproduce
+
+**First, reproduce the bug reliably before attempting any fix.**
+
+```bash
+# Attempt to reproduce with minimal case
+# Run the specific failing test or command
+```
+
+If intermittent:
+
+- Run N times: `for i in $(seq 1 10); do [command]; done`
+- Check for: time-dependent behavior, race conditions, external dependency flakiness
+
+Document the reproducer:
+
+```text
+Reproducer:
+  Command: [exact command to run]
+  Expected: [what should happen]
+  Actual: [what actually happens]
+  Frequency: [always / N% of the time]
+  Environment: [local / CI / staging / prod]
+```
+
+______________________________________________________________________
+
+## Step 2: Gather Evidence
+
+**Read all available logs and error output:**
+
+```bash
+# Application logs (recent)
+# Adjust for your platform:
+journalctl -u service-name --since "1 hour ago" 2>/dev/null | tail -100 || true
+docker logs container-name 2>/dev/null | tail -100 || true
+kubectl logs deployment/service-name --tail=100 2>/dev/null || true
+cat /var/log/app.log 2>/dev/null | tail -100 || true
+
+# Check for correlated errors at the same timestamp
+# Check for system-level issues (disk full, OOM, network)
+```
+
+**Read the failing code:**
+
+```bash
+# Read the relevant source files
+# Read the test that's failing (if applicable)
+# Read recent changes: git show HEAD
+git diff HEAD~3 -- relevant-files
+```
+
+______________________________________________________________________
+
+## Step 3: Form Hypotheses
+
+Based on evidence, list hypotheses in order of likelihood:
+
+```text
+Hypotheses (most likely first):
+1. [Hypothesis] — Evidence for: [X] — Evidence against: [Y]
+2. [Hypothesis] — Evidence for: [X] — Evidence against: [Y]
+3. [Hypothesis] — Evidence for: [X] — Evidence against: [Y]
+```
+
+**Common backend bug categories to consider:**
+
+- **Race condition / concurrency:** Multiple goroutines/threads/processes modifying shared state
+- **Nil/null dereference:** Unhandled nil case in a code path
+- **Off-by-one:** Boundary condition in loop, pagination, or slice
+- **Type coercion:** Implicit type conversion causing unexpected behavior
+- **State mutation:** Object modified unexpectedly (shared reference, closure)
+- **Async/await:** Missing await, unhandled promise rejection
+- **Database:** N+1 query, missing index, transaction isolation, stale connection
+- **Network:** Timeout, connection pool exhaustion, DNS resolution failure
+- **Configuration:** Wrong env var, missing config key, schema mismatch after migration
+- **Dependency version:** Introduced by a dependency upgrade (check lockfile changes)
+- **Memory:** Leak, fragmentation, GC pressure
+- **Timing:** TTL expiry, clock skew, eventual consistency window
+
+______________________________________________________________________
+
+## Step 4: Test Each Hypothesis
+
+For each hypothesis in rank order:
+
+1. Design a test that would prove or disprove it
+1. Run the test
+1. Update the hypothesis ranking based on results
+
+```bash
+# Example: test for race condition
+go test -race ./... 2>/dev/null || true
+
+# Example: test for nil path
+# Add temporary logging at the suspected nil path
+
+# Example: test for database issue
+# Examine query plans, check for missing indexes
+```
+
+Eliminate hypotheses one by one until only one remains.
+
+______________________________________________________________________
+
+## Step 5: Root Cause Identification
+
+State the root cause with precision:
+
+```text
+Root Cause:
+  Location:  path/to/file.ts:line
+  Mechanism: [exact description of what is happening]
+  Trigger:   [exact conditions that trigger the bug]
+  Timeline:  [when was this introduced? git log shows...]
+  Scope:     [Which environments? Which users? How often?]
+```
+
+______________________________________________________________________
+
+## Step 6: Fix
+
+Design the minimal fix:
+
+1. Identify the smallest change that correctly fixes the root cause
+1. Consider side effects
+1. Consider whether the fix introduces new edge cases
+1. Implement
+
+```bash
+# Apply the fix
+# Run the reproducer to confirm it's fixed
+```
+
+______________________________________________________________________
+
+## Step 7: Regression Test
+
+Add a test that would have caught this bug:
+
+```bash
+# Write the test
+# Run it on the broken state to confirm it catches the bug
+git stash  # temporarily revert fix
+[run test] # should fail
+git stash pop  # restore fix
+[run test] # should pass
+```
+
+Commit test + fix atomically:
+
+```bash
+git add -A
+git commit -m "fix: [description of what was wrong]
+
+Root cause: [one sentence]
+Reproducer: [if non-obvious]
+Test: [test file added/updated]"
+```
+
+______________________________________________________________________
+
+## Step 8: Prevent Recurrence
+
+Consider:
+
+1. Is this a systemic pattern that could occur elsewhere?
+1. Should there be a linting rule or code review checklist item?
+1. Should a runbook be updated?
+1. Should an alert be added to catch this class of failure in production?
+1. Should TODOS.md be updated with related improvements?
+
+______________________________________________________________________
+
+## Debug Summary
+
+```text
+## Debug Report — [bug description] — [date]
+
+Reproducer: [command or steps]
+Root cause: [one paragraph explanation]
+Fix: [change made in commit SHA]
+Regression test: [test file:function]
+Prevention: [any follow-up items]
+```
+
+______________________________________________________________________

vstack/_templates/skills/dependency/config.yaml

@@ -0,0 +1,18 @@
+name: dependency
+version: 1.0.1
+description: |
+  Dependency health audit. Covers vulnerability scanning, outdated packages,
+  licence compliance, transitive risk, pinning policy, and supply chain hygiene.
+  Goes beyond the vulnerability gate in `security` — covers upgrade strategy,
+  licence obligations, and long-term dependency health. Use when asked to
+  "audit dependencies", "check for outdated packages", "licence compliance",
+  "pin versions", or "dependency health check".
+argument-hint: '[project or package manifest to audit]'
+
+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/dependency/template.md

@@ -0,0 +1,293 @@
+{{SKILL_CONTEXT}}
+
+# dependency — Dependency Health Audit
+
+Audit the health, security, and compliance of project dependencies. Covers
+vulnerability scanning, outdated packages, licence obligations, transitive
+risk, pinning policy, and supply chain hygiene.
+
+## Scope vs related skills
+
+- **This skill** — full dependency health: vulnerabilities, freshness, licences,
+  pinning policy, supply chain
+- **`security`** — includes a lightweight vulnerability gate as part of OWASP A06;
+  for a full dependency audit use this skill instead
+- **`verify`** — includes a quick vuln check in the quality gate loop; escalates
+  to this skill for deeper investigation
+
+**Golden rule: A dependency is owned code you didn't write. Treat it with the
+same scrutiny as your own code.**
+
+______________________________________________________________________
+
+## Step 0: Detect the Stack
+
+```bash
+# Identify package manifests
+ls pyproject.toml poetry.lock requirements*.txt \
+   package.json package-lock.json yarn.lock pnpm-lock.yaml \
+   go.mod go.sum Cargo.toml Cargo.lock \
+   pom.xml build.gradle Gemfile Gemfile.lock 2>/dev/null
+
+# Detect Python version and package manager
+cat pyproject.toml 2>/dev/null | grep -E 'requires-python|tool\.poetry' | head -5
+cat .python-version 2>/dev/null
+which poetry && poetry --version 2>/dev/null || true
+which pip-audit && pip-audit --version 2>/dev/null || true
+```
+
+Document:
+
+```text
+Stack:       [Python | Node | Go | Rust | Java | other]
+Manager:     [Poetry | pip | npm | yarn | pnpm | cargo | go modules | other]
+Manifests:   [list of files found]
+Lock file:   [present | absent — flag if absent]
+```
+
+______________________________________________________________________
+
+## Part 1: Vulnerability Scan
+
+Run the appropriate scanner for each detected stack:
+
+```bash
+# Python — pip-audit (preferred) or safety
+if [ -f pyproject.toml ] || [ -f requirements.txt ]; then
+  pip-audit 2>/dev/null \
+  || safety check --full-report 2>/dev/null \
+  || echo "No Python vuln scanner found — install pip-audit: pip install pip-audit"
+fi
+
+# Node
+[ -f package.json ] && npm audit --json 2>/dev/null | head -100
+
+# Go
+if [ -f go.mod ]; then
+  govulncheck ./... 2>/dev/null \
+    || echo "govulncheck not found — install: go install golang.org/x/vuln/cmd/govulncheck@latest"
+fi
+
+# Rust
+if [ -f Cargo.toml ]; then
+  cargo audit 2>/dev/null \
+    || echo "cargo-audit not found — install: cargo install cargo-audit"
+fi
+
+# Java (Maven)
+[ -f pom.xml ] && mvn dependency-check:check -q 2>/dev/null || true
+```
+
+Triage findings by severity:
+
+```text
+Vulnerabilities found:
+  🔴 CRITICAL / HIGH: [package] [version] — [CVE] — [description]
+  🟡 MEDIUM:          [package] [version] — [CVE] — [description]
+  🟢 LOW / INFO:      [count] low-severity findings
+```
+
+**Remediation rule:** CRITICAL and HIGH must be resolved before release. MEDIUM
+should be tracked and resolved within the sprint. LOW may be deferred with
+documented rationale.
+
+______________________________________________________________________
+
+## Part 2: Outdated Packages
+
+```bash
+# Python (Poetry)
+poetry show --outdated 2>/dev/null | head -40
+
+# Python (pip)
+pip list --outdated 2>/dev/null | head -40
+
+# Node
+npm outdated 2>/dev/null | head -40
+
+# Go — check go.sum and go.mod for pinned versions
+go list -m -u all 2>/dev/null | grep '\[' | head -30
+
+# Rust
+cargo outdated 2>/dev/null | head -30
+```
+
+Classify each outdated package:
+
+| Package | Current | Latest | Type  | Action                    |
+| ------- | ------- | ------ | ----- | ------------------------- |
+| `foo`   | 1.2.0   | 1.2.5  | patch | update now                |
+| `bar`   | 2.1.0   | 3.0.0  | major | evaluate breaking changes |
+| `baz`   | 0.9.0   | 0.9.8  | patch | update now                |
+
+**Update priority:**
+
+- Patch updates: update immediately (no breaking changes expected)
+- Minor updates: update soon (check changelog for deprecations)
+- Major updates: plan upgrade (read migration guide, test thoroughly)
+
+______________________________________________________________________
+
+## Part 3: Licence Compliance
+
+Check licence obligations for all direct and transitive dependencies:
+
+```bash
+# Python
+if pip-licenses --version >/dev/null 2>&1; then
+  pip-licenses --format=markdown --with-urls 2>/dev/null | head -60
+elif python3 -m pip_licenses --help >/dev/null 2>&1; then
+  python3 -m pip_licenses 2>/dev/null | head -60
+else
+  echo "Install pip-licenses: pip install pip-licenses"
+fi
+
+# Node
+npx license-checker --summary 2>/dev/null | head -40
+
+# Go
+if go-licenses --help >/dev/null 2>&1; then
+  go-licenses report ./... 2>/dev/null | head -40
+else
+  echo "Install go-licenses: go install github.com/google/go-licenses@latest"
+fi
+```
+
+Classify licences by risk:
+
+| Risk   | Licences                           | Requirement                                        |
+| ------ | ---------------------------------- | -------------------------------------------------- |
+| Low    | MIT, BSD-2, BSD-3, Apache-2.0, ISC | Can use freely, attribution in docs                |
+| Medium | LGPL-2.1, LGPL-3.0                 | Dynamic linking OK; static linking requires review |
+| High   | GPL-2.0, GPL-3.0, AGPL-3.0         | May require open-sourcing your code                |
+| Review | Commercial, proprietary, unknown   | Requires legal review before use                   |
+
+Flag any High or Review licences:
+
+```text
+Licence issues:
+  🔴 [package] — [licence] — [risk] — [recommendation]
+```
+
+______________________________________________________________________
+
+## Part 4: Pinning Policy
+
+A healthy dependency policy requires reproducible builds:
+
+**Check for lock files:**
+
+- [ ] `poetry.lock` / `package-lock.json` / `yarn.lock` / `Cargo.lock` / `go.sum` exists
+- [ ] Lock file is committed to version control
+- [ ] Lock file is up to date with the manifest
+
+**Check for version constraints:**
+
+```bash
+# Python — look for unpinned deps
+cat pyproject.toml 2>/dev/null | grep -E '^\s+[a-z]' | grep -v '^#' | head -30
+
+# Flag overly loose constraints (e.g. "*", ">=1.0" with no upper bound in prod deps)
+```
+
+| Pattern                     | Risk   | Recommendation                               |
+| --------------------------- | ------ | -------------------------------------------- |
+| `package = "*"`             | High   | Pin to a compatible range                    |
+| `package = ">=1.0"`         | Medium | Add upper bound: `>=1.0,<3.0`                |
+| `package = "^1.0"` (Poetry) | Low    | Acceptable for non-critical deps             |
+| `package = "1.2.3"` (exact) | Low    | Fine for direct deps; brittle for transitive |
+| No lock file                | High   | Add lock file and commit it                  |
+
+______________________________________________________________________
+
+## Part 5: Transitive Risk
+
+Identify high-risk transitive (indirect) dependencies:
+
+```bash
+# Python — show full dependency tree
+if poetry --version >/dev/null 2>&1; then
+  poetry show --tree 2>/dev/null | head -60
+else
+  pip install pipdeptree 2>/dev/null && pipdeptree 2>/dev/null | head -60
+fi
+
+# Node
+npm list --depth=2 2>/dev/null | head -60
+
+# Go
+go mod graph 2>/dev/null | head -40
+```
+
+Flags to look for:
+
+- [ ] No single dependency with > 20 transitive deps (blast radius risk)
+- [ ] No abandoned packages (last release > 2 years, no recent commits)
+- [ ] No packages with a single maintainer for critical functionality
+- [ ] Core dependencies have active security policies (CVE response time < 30 days)
+
+```bash
+# Check for abandoned packages — look at last release dates
+# (manual step: check PyPI / npm registry for each critical dep)
+```
+
+______________________________________________________________________
+
+## Part 6: Supply Chain Hygiene
+
+```bash
+# Python — check if packages are installed from PyPI or custom source
+cat pyproject.toml 2>/dev/null | grep -E '\[\[tool\.poetry\.source\]\]' -A 5
+
+# Node — check for private registry config
+cat .npmrc 2>/dev/null
+cat package.json 2>/dev/null | grep -E '"registry"'
+
+# Check for dependency confusion risk (private package names published on public registry)
+# (manual step: search PyPI/npm for any internal package names)
+```
+
+Check:
+
+- [ ] All packages sourced from trusted, official registries
+- [ ] No `--extra-index-url` pointing to untrusted sources (Python)
+- [ ] Private package names are not also available on public registries (confusion attack)
+- [ ] `pip install` / `npm install` output reviewed for unexpected packages
+- [ ] CI pipeline pins the package manager version itself
+
+______________________________________________________________________
+
+## Output
+
+```text
+Dependency Audit Report
+═══════════════════════
+
+Stack:    [stack + manager]
+Scanned:  [N direct, N transitive dependencies]
+
+Vulnerabilities:
+  🔴 Critical/High: [N] — [list or "none"]
+  🟡 Medium:        [N] — [list or "none"]
+  🟢 Low:           [N]
+
+Outdated:
+  Patch updates available:  [N packages]
+  Minor updates available:  [N packages]
+  Major updates available:  [N packages]
+
+Licence issues:
+  🔴 High-risk licences: [list or "none"]
+  🟡 Review required:    [list or "none"]
+
+Pinning:
+  Lock file:     [present | absent]
+  Loose pins:    [list or "none"]
+
+Supply chain:
+  [clean | issues found — details]
+
+Action items (priority order):
+  1. [action] — [package] — [severity]
+  2. ...
+```

vstack/_templates/skills/design/config.yaml

@@ -0,0 +1,16 @@
+name: design
+version: 1.0.2
+description: |
+  Build a complete API design or service design from scratch. Produces OpenAPI
+  specs, error conventions, naming standards, pagination patterns, and versioning
+  policies. Use when asked to "design the API", "create a design system for this
+  service", "define the API standards", or "design this service interface".
+argument-hint: '[API or service to design]'
+
+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