vstack 0.0.0__py3-none-any.whl

vstack/_templates/skills/requirements/template.md

@@ -0,0 +1,187 @@
+{{SKILL_CONTEXT}}
+
+# requirements — Requirements Gathering & Documentation
+
+Clarify and document what must be built before engineering starts. Produce a
+`docs/product/requirements.md` that downstream roles (architect, designer, engineer) can
+work from.
+
+## Out of scope
+
+- Technical design and architecture decisions (use `architecture`)
+- API/service design (use `design`)
+- Roadmap and milestone planning (product role artifact)
+- Implementation (engineering role)
+
+## Deliverable and artifact policy
+
+- Primary deliverable: `docs/product/requirements.md`
+- Baseline-first default: write final requirements directly to `docs/product/requirements.md` on the feature branch.
+- Optional WIP area for complex/uncertain intake: `docs/delta/{intake-id}/REQUIREMENTS_DELTA.md`
+- Before merge: consolidate any required content from optional delta notes back into `docs/product/requirements.md`, then remove stale WIP notes.
+
+______________________________________________________________________
+
+## Step 0: Context
+
+Read existing artifacts before asking questions:
+
+```bash
+cat docs/product/vision.md 2>/dev/null || true
+cat docs/product/requirements.md 2>/dev/null || true
+cat docs/product/roadmap.md 2>/dev/null || true
+cat README.md 2>/dev/null | head -40 || true
+```
+
+Identify what's already known and what needs clarification.
+
+______________________________________________________________________
+
+## Step 1: Problem Statement
+
+Clarify the core problem being solved:
+
+> **Question:** Describe what you want to build and why.
+>
+> - What problem does this solve?
+> - Who experiences this problem today?
+> - What happens if we don't solve it?
+
+Document:
+
+```text
+## Problem Statement
+[One paragraph: root problem, who has it, impact of not solving it]
+```
+
+______________________________________________________________________
+
+## Step 2: Users & Stakeholders
+
+Who uses or is affected by this?
+
+| Role        | Description | Primary need |
+| ----------- | ----------- | ------------ |
+| [User type] |             |              |
+
+______________________________________________________________________
+
+## Step 3: Functional Requirements
+
+What must the system do? Use the format: "The system must [verb] [object] [condition/constraint]."
+
+Ask for clarity on ambiguous areas:
+
+> **Question:** Are there any specific behaviors or edge cases that are critical?
+
+```markdown
+## Functional Requirements
+
+### Must have (MVP)
+- FR-01: The system must [...]
+- FR-02: The system must [...]
+
+### Should have (desirable)
+- FR-03: [...]
+
+### Won't have (explicitly out of scope)
+- [State what will NOT be built in this iteration]
+```
+
+______________________________________________________________________
+
+## Step 4: Non-Functional Requirements
+
+| Category     | Requirement    | Measurable target                    |
+| ------------ | -------------- | ------------------------------------ |
+| Performance  | Response time  | p99 < 500ms under X rps              |
+| Availability | Uptime         | 99.9% (< 8.7h downtime/year)         |
+| Security     | Auth           | All endpoints require authentication |
+| Scalability  | Load           | Handle up to N concurrent users      |
+| Compliance   | Data residency | Data stored in [region]              |
+
+Ask:
+
+> **Question:** Are there any hard non-functional requirements (performance, security,
+> compliance, data residency)?
+
+______________________________________________________________________
+
+## Step 5: Constraints & Assumptions
+
+Document known constraints:
+
+```markdown
+## Constraints
+- Budget: [if relevant]
+- Timeline: [hard deadline if any]
+- Technology: [must use X, cannot use Y]
+- Team: [available skill set]
+- Existing systems: [must integrate with X]
+
+## Assumptions
+- [Things assumed true that could invalidate requirements if wrong]
+```
+
+______________________________________________________________________
+
+## Step 6: Success Criteria
+
+What does "done" look like? How do we know the requirements are met?
+
+```markdown
+## Success Criteria
+- [ ] [Measurable outcome 1]
+- [ ] [Measurable outcome 2]
+- [ ] [Acceptance test: given X, when Y, then Z]
+```
+
+______________________________________________________________________
+
+## Step 7: Open Questions
+
+List anything that is unclear and needs a decision before work begins:
+
+```markdown
+## Open Questions
+- [ ] [Question] — Owner: [who decides] — Deadline: [when needed]
+```
+
+______________________________________________________________________
+
+## Output: requirements.md
+
+Write all findings to `docs/product/requirements.md`:
+
+```markdown
+# Requirements — [feature/project name]
+
+**Status:** draft | reviewed | approved
+**Date:** YYYY-MM-DD
+**Author:** product role
+
+## Problem Statement
+[...]
+
+## Users & Stakeholders
+[table]
+
+## Functional Requirements
+[...]
+
+## Non-Functional Requirements
+[table]
+
+## Constraints & Assumptions
+[...]
+
+## Success Criteria
+[...]
+
+## Open Questions
+[...]
+```
+
+After writing, summarize what was decided so the architect role can start.
+
+______________________________________________________________________

vstack/_templates/skills/security/config.yaml

@@ -0,0 +1,17 @@
+name: security
+version: 1.0.2
+description: |
+  OWASP Top 10 + STRIDE security audit for APIs, services, and libraries.
+  Finds authentication bypasses, injection vulnerabilities, insecure configurations,
+  exposed secrets, dependency vulnerabilities, and broken access control.
+  Use when asked to "security audit", "security review", or "check for vulnerabilities".
+  Proactively suggest before any code ships to production.
+argument-hint: '[component or service 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/security/template.md

@@ -0,0 +1,256 @@
+{{SKILL_CONTEXT}}
+
+{{BASE_BRANCH}}
+
+# security — Security Audit (OWASP Top 10 + STRIDE)
+
+Perform a systematic security audit. No finding is too small. Report every issue
+with severity, evidence, and specific remediation.
+
+## Out of scope
+
+- Full code review for non-security issues (use `code-review`)
+- Performance analysis (use `performance`)
+- Architecture design (use `architecture`)
+- Writing new features (engineering role)
+
+## Deliverable and artifact policy
+
+- Primary deliverable: `docs/security-report.md`
+- Baseline-first default: write final findings directly to `docs/security-report.md` on the feature branch.
+- Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/SECURITY_DELTA.md`
+- Before merge: consolidate severity-ranked findings and mitigations into baseline security reports.
+
+## Audit Scope
+
+Parse the user's request for scope:
+
+- **Full audit:** All code in the repository
+- **Diff audit:** Only changes since base branch (default on feature branches)
+- **Dependency audit:** Only dependency vulnerabilities
+- **Config audit:** Only infrastructure and configuration
+
+```bash
+# Detect scope
+CURRENT=$(git branch --show-current)
+git diff <base> --stat 2>/dev/null | head -20 || true
+```
+
+______________________________________________________________________
+
+## Part 1: OWASP Top 10
+
+### A01: Broken Access Control
+
+```bash
+# Look for authorization checks
+grep -r -n "is_admin\|hasRole\|checkPermission\|authorize\|can(" \
+  --include='*.ts' --include='*.py' --include='*.go' --include='*.java' \
+  --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor . 2>/dev/null | head -30
+
+# Look for endpoints missing auth
+grep -r -n "@app.route\|router\.\|@Get\|@Post\|@Put\|@Delete\|@Patch" \
+  --include='*.ts' --include='*.py' --include='*.go' \
+  --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -30
+```
+
+Check:
+
+- [ ] Every endpoint checks authentication AND authorization
+- [ ] Authorization is per-resource, not just per-role
+- [ ] No direct object reference without ownership check (IDOR)
+- [ ] Admin endpoints protected by privilege check, not just auth
+- [ ] JWT/token claims validated (expiry, issuer, audience)
+
+### A02: Cryptographic Failures
+
+```bash
+# Find hardcoded secrets
+grep -r -E '(password|secret|api_key|private_key|token)\s*[=:]\s*["\x27][^"\x27]{8,}' \
+  --include='*.ts' --include='*.py' --include='*.go' --include='*.yaml' --include='*.env' \
+  --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build --exclude-dir=.git . 2>/dev/null | grep -v test | grep -v example
+
+# Find weak crypto
+grep -r -n "MD5\|SHA1\|DES\|RC4\|Math.random\|random.random" \
+  --include='*.ts' --include='*.py' --include='*.go' \
+  --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -20
+```
+
+Check:
+
+- [ ] No secrets in source code (use secret manager)
+- [ ] Passwords hashed with bcrypt/argon2/scrypt (not MD5/SHA1)
+- [ ] TLS enforced for all network communication
+- [ ] Cryptographic random for security-sensitive values
+- [ ] Sensitive data encrypted at rest
+
+### A03: Injection
+
+```bash
+# SQL injection risk
+grep -r -n 'query\|execute\|raw\|f"' \
+  --include='*.py' --include='*.ts' --include='*.go' \
+  --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | grep -E '"SELECT|"INSERT|"UPDATE|"DELETE|f".*sql' | head -20
+
+# Command injection risk
+grep -r -n 'exec\|subprocess\|shell=True\|execSync\|spawnSync' \
+  --include='*.py' --include='*.ts' --include='*.go' \
+  --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -20
+```
+
+Check:
+
+- [ ] All database queries use parameterized queries / ORM
+- [ ] No string concatenation in SQL
+- [ ] System commands use argument arrays, not shell strings
+- [ ] Template engines auto-escape output
+
+### A04: Insecure Design
+
+- [ ] Threat model exists for the system?
+- [ ] No security through obscurity
+- [ ] Principle of least privilege in service-to-service auth
+- [ ] Defense in depth — multiple layers, not single gate
+
+### A05: Security Misconfiguration
+
+```bash
+# Check for debug/development modes
+grep -r -n 'DEBUG\s*=\s*True\|debug:\s*true\|development\|NODE_ENV' \
+  --include='*.py' --include='*.ts' --include='*.yaml' --include='*.json' \
+  --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | grep -v test | head -20
+
+# Check for permissive CORS
+grep -r -n 'cors\|CORS\|Access-Control-Allow-Origin' \
+  --include='*.ts' --include='*.py' --include='*.go' \
+  --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -20
+```
+
+Check:
+
+- [ ] Debug mode disabled in production
+- [ ] CORS restricted to known origins (not `*`)
+- [ ] Error messages don't leak internal details
+- [ ] Security headers set (HSTS, CSP, X-Frame-Options if applicable)
+- [ ] Unnecessary features/endpoints disabled in production
+
+### A06: Vulnerable and Outdated Components
+
+```bash
+# Dependency vulnerability scan
+[ -f package.json ]   && npm audit 2>/dev/null || true
+[ -f pyproject.toml ] && pip-audit 2>/dev/null || safety check 2>/dev/null || true
+[ -f go.mod ]         && govulncheck ./... 2>/dev/null || true
+[ -f Cargo.toml ]     && cargo audit 2>/dev/null || true
+[ -f pom.xml ]        && mvn dependency-check:check 2>/dev/null || true
+```
+
+### A07: Identification and Authentication Failures
+
+```bash
+# Check session/token implementation
+grep -r -n 'jwt\|JWT\|session\|cookie\|token' \
+  --include='*.ts' --include='*.py' --include='*.go' \
+  --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | grep -i 'expire\|expiry\|secret\|key' | head -20
+```
+
+Check:
+
+- [ ] Token expiry enforced
+- [ ] Refresh token rotation implemented
+- [ ] Logout invalidates tokens server-side
+- [ ] Password reset tokens single-use and time-limited
+- [ ] Multi-factor authentication for privileged operations (if applicable)
+
+### A08: Software and Data Integrity Failures
+
+```bash
+# Check for unsigned dependencies
+cat package-lock.json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print('Integrity checks:', sum(1 for v in d.get('packages',{}).values() if v.get('integrity')))" 2>/dev/null || true
+```
+
+Check:
+
+- [ ] Dependencies pinned to specific versions with integrity hashes
+- [ ] CI/CD pipeline integrity (no untrusted actions/orbs)
+- [ ] Artifacts signed before distribution
+
+### A09: Security Logging and Monitoring Failures
+
+```bash
+grep -r -n 'audit\|security_log\|auth.*log\|access.*log' \
+  --include='*.ts' --include='*.py' --include='*.go' \
+  --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | head -20
+```
+
+Check:
+
+- [ ] Authentication events logged (success and failure)
+- [ ] Authorization failure logged with user ID and resource
+- [ ] Suspicious patterns produce alerts
+- [ ] Logs protected from tampering
+- [ ] PII not logged
+
+### A10: Server-Side Request Forgery (SSRF)
+
+```bash
+grep -r -n 'fetch\|requests\.\|http\.get\|axios\|urllib' \
+  --include='*.ts' --include='*.py' --include='*.go' \
+  --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=venv --exclude-dir=env --exclude-dir=__pycache__ --exclude-dir=dist --exclude-dir=build . 2>/dev/null | grep -v test | head -20
+```
+
+Check:
+
+- [ ] URLs from user input are validated against allowlist
+- [ ] Private network ranges blocked (169.254.0.0/16, 10.0.0.0/8, etc.)
+- [ ] SSRF protection on any URL-fetching functionality
+
+______________________________________________________________________
+
+## Part 2: STRIDE Threat Model
+
+For each new service/component, answer:
+
+| Threat                     | Question                                                  | Mitigation in place? |
+| -------------------------- | --------------------------------------------------------- | -------------------- |
+| **Spoofing**               | Can an attacker impersonate a legitimate user or service? |                      |
+| **Tampering**              | Can an attacker modify data in transit or at rest?        |                      |
+| **Repudiation**            | Can actions be denied without audit trail?                |                      |
+| **Information Disclosure** | What sensitive data could leak?                           |                      |
+| **Denial of Service**      | Can the service be made unavailable? Rate limiting?       |                      |
+| **Elevation of Privilege** | Can a user gain admin access through normal flows?        |                      |
+
+______________________________________________________________________
+
+## Audit Report
+
+```text
+## Security Audit Report — [service/repo] — [date]
+Scope: [full/diff/dependency/config]
+
+### Critical Findings (immediate fix required)
+1. [Category] `path/to/file:line` — [Issue]
+   Evidence: [code snippet or behavior]
+   Remediation: [specific fix]
+   CVSS: [if applicable]
+
+### High Findings (fix before shipping)
+...
+
+### Medium Findings (fix in near-term)
+...
+
+### Low / Informational
+...
+
+### OWASP Coverage
+[X/10 categories checked, N issues found]
+
+### Dependency Vulnerabilities
+[X critical, Y high, Z medium]
+
+### Recommendation
+[SHIP-READY / FIX CRITICALS / SECURITY REVIEW REQUIRED]
+```
+
+______________________________________________________________________

vstack/_templates/skills/verify/config.yaml

@@ -0,0 +1,17 @@
+name: verify
+version: 1.0.2
+description: |
+  Verification fix-loop skill. Routes by mode (quick/standard/exhaustive), runs
+  targeted checks, fixes findings by severity, and re-verifies impacted paths.
+  Routes report-only requests to inspect and escalates deep security/performance
+  concerns to specialized skills. Use when asked to "verify", "fix failing checks",
+  "run QA with fixes", or "re-verify before shipping".
+argument-hint: '[component or feature to verify]'
+
+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/verify/template.md

@@ -0,0 +1,201 @@
+{{SKILL_CONTEXT}}
+
+{{BASE_BRANCH}}
+
+# verify - Fix Loop Verification
+
+Run a targeted verification fix loop:
+
+1. choose scope/mode,
+1. run checks,
+1. fix issues in priority order,
+1. re-run only impacted checks,
+1. report ship readiness.
+
+Use `inspect` for read-only auditing.
+
+## Out of scope
+
+- Architecture decisions (use `architecture`)
+- Full security audit (use `security`)
+- Performance benchmarking/profiling (use `performance`)
+- New feature implementation outside verification fixes (engineering role)
+
+## Deliverable and artifact policy
+
+- Primary deliverable: `docs/test-report.md`
+- Additional deliverables when applicable: `docs/security-report.md`, `docs/performance-baseline.md`
+- Baseline-first default: write final verification outcomes directly to baseline reports on the feature branch.
+- Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/VERIFY_DELTA.md`
+- Before merge: consolidate final findings, severity, and ship-readiness verdict into baseline reports.
+
+______________________________________________________________________
+
+## Step 0: Route Mode
+
+Classify first, then run one mode.
+
+> **Question:** Which verify mode should be used?
+> **Options:**
+> A) quick - critical/high regressions only
+> B) standard - default verification + fix loop
+> C) exhaustive - broad verification and full fix sweep
+> D) report-only - route to `inspect`
+> **Default if no response:** B
+
+If D, stop and route to `inspect`.
+
+______________________________________________________________________
+
+## Step 1: Scope and Safety
+
+Parse user scope:
+
+- Target: whole repo or specific component/path
+- Tier: quick/standard/exhaustive
+- Source: full branch diff or explicit path
+
+Check working tree:
+
+```bash
+git status --porcelain
+```
+
+If dirty, ask before proceeding because verify may create multiple atomic fix commits.
+
+Bootstrap test command:
+
+{{RUN_TESTS}}
+
+______________________________________________________________________
+
+## Step 2: Baseline Checks (all modes)
+
+Run baseline checks for the selected scope.
+
+### 2.1 Lint and Type
+
+```bash
+[ -f package.json ] && (npm run lint 2>/dev/null || true)
+[ -f tsconfig.json ] && npx tsc --noEmit 2>/dev/null || true
+[ -f pyproject.toml ] && (ruff check . 2>/dev/null || true)
+[ -f pyproject.toml ] && (mypy . 2>/dev/null || pyright . 2>/dev/null || true)
+[ -f go.mod ] && (go vet ./... 2>/dev/null || true)
+```
+
+### 2.2 Unit Tests
+
+{{RUN_TESTS}}
+
+______________________________________________________________________
+
+## Step 3: Conditional Checks by Mode
+
+### quick
+
+- Run only failing or high-risk checks related to changed code
+- Skip broad integration/contract/smoke unless directly impacted
+
+### standard
+
+Run these when present:
+
+```bash
+# Integration
+[ -f package.json ] && npm run test:integration 2>/dev/null || true
+[ -f pyproject.toml ] && python -m pytest -m integration -v 2>/dev/null || true
+[ -f go.mod ] && go test -run Integration ./... 2>/dev/null || true
+
+# Contract
+[ -f openapi.yaml ] && npx @redocly/cli lint openapi.yaml 2>/dev/null || true
+[ -n "$(find . -name '*.proto' 2>/dev/null | head -1)" ] && buf lint 2>/dev/null || true
+```
+
+Also verify observability on impacted paths:
+
+- Structured logs for critical transitions and errors
+- Metrics for latency/error/saturation
+- Trace propagation across service boundaries
+- Alerts or runbooks for critical failure modes
+
+### exhaustive
+
+Run standard checks plus:
+
+```bash
+# Optional smoke checks if scripts exist
+find . -name '*.smoke.*' -o -name '*smoke-test*' -o -name 'smoke.sh' 2>/dev/null | head -5
+
+# Dependency vulnerability gate (lightweight only; full audit belongs to security)
+[ -f package.json ] && npm audit --audit-level=high 2>/dev/null || true
+[ -f pyproject.toml ] && pip-audit 2>/dev/null || true
+[ -f go.mod ] && govulncheck ./... 2>/dev/null || true
+```
+
+For exhaustive mode, require observability evidence (logs/metrics/traces/alerts) in the final report.
+
+If deep security/performance concerns appear, stop and route to `security` or `performance`.
+
+______________________________________________________________________
+
+## Step 4: Triage
+
+Classify findings:
+
+| Severity | Examples                                                            |
+| -------- | ------------------------------------------------------------------- |
+| critical | test crashes, build breaks, data integrity/security regressions     |
+| high     | contract violations, broken error handling, missing required checks |
+| medium   | flaky tests, non-critical behavior gaps                             |
+| low      | style and minor cleanups                                            |
+
+Fix policy:
+
+- quick: critical + high
+- standard: critical + high + medium
+- exhaustive: all severities
+
+______________________________________________________________________
+
+## Step 5: Fix and Re-verify Loop
+
+For each fixable issue in severity order:
+
+1. Reproduce and confirm root cause.
+1. Apply minimal fix.
+1. Commit atomically (`fix: ...`).
+1. Re-run only impacted checks first.
+1. If needed, run the relevant broader check suite.
+
+If an issue implies architecture or design mismatch, stop and escalate.
+
+______________________________________________________________________
+
+## Step 6: Final Report
+
+```text
+## Verification Report - [component/repo] - [date]
+
+selected_mode: [quick|standard|exhaustive]
+scope: [path/component/full]
+
+### Summary
+- tests: [X pass / Y fail / Z skip]
+- issues found: [N critical / N high / N medium / N low]
+- fixes applied: [N]
+- deferred: [N]
+
+### Fixed Issues
+1. [issue] - [commit SHA]
+
+### Deferred Issues
+1. [issue] - [why deferred] - [owner]
+
+### Routed Follow-ups (if any)
+- [security|performance|architecture|design] - [reason]
+
+### Ship Readiness
+[READY TO SHIP | NEEDS FIXES | BLOCKED]
+```
+
+______________________________________________________________________

vstack/_templates/skills/vision/config.yaml

@@ -0,0 +1,19 @@
+name: vision
+version: 1.0.2
+description: |
+  CEO/founder-mode plan review. Rethink the problem from first principles, validate
+  ambition and scope, challenge premises, find the 10x solution. Four modes:
+  SCOPE EXPANSION (dream big), SELECTIVE EXPANSION (hold scope + cherry-pick),
+  HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials).
+  Use when asked to "think bigger", "strategy review", "rethink this", or
+  "is this ambitious enough". Proactively suggest when a plan feels under-scoped
+  or when the user is questioning ambition.
+argument-hint: '[plan or idea to 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