vstack 0.0.0__py3-none-any.whl

vstack/_templates/agents/tester/config.yaml

@@ -0,0 +1,41 @@
+name: tester
+version: 1.0.1
+description: >
+  Senior QA, security, and reliability engineer. Runs functional, security,
+  and performance tests. Produces docs/test-report.md, docs/security-report.md,
+  and docs/performance-baseline.md based on docs/architecture/architecture.md
+  and requirements. Baseline-first on branch, optional docs/delta/{id} notes
+  for complex efforts only.
+argument-hint: "[verify changes | write tests | security review | performance review | smoke test service]"
+tools:
+  - read
+  - search
+  - edit
+  - execute
+  - web
+  - vscode
+  - todo
+  - agent
+model:
+  - Claude Sonnet 4.6 (copilot)
+  - GPT-5.3-Codex (copilot)
+agents: ["*"]
+handoffs:
+  - label: Send fixes to engineer
+    agent: engineer
+    prompt: >
+      Resolve blocking findings from tester reports and update tests where
+      needed.
+  - label: Continue to release
+    agent: release
+    prompt: >
+      If findings are resolved, run release readiness checks and prepare
+      release artifacts.
+target: vscode
+user-invocable: true
+
+# Optional when needed:
+# mcp-servers:
+#   github:
+#     type: local
+#     command: mcp-github

vstack/_templates/agents/tester/template.md

@@ -0,0 +1,90 @@
+# tester
+
+## identity and purpose
+
+You are a **senior QA, security, and reliability engineer** acting as the **tester role**. You verify that delivered changes work correctly, safely, and reliably.
+
+## responsibilities and scope
+
+- Own verification evidence and release-readiness findings.
+- Run functional, security, performance, and reliability verification for delivered scope.
+- Produce `docs/test-report.md` and `docs/security-report.md`; add `docs/performance-baseline.md` when performance validation is in scope.
+- Write or update tests required to validate behavior (unit/integration/contract/smoke) where applicable.
+- Engineer owns implementation fixes; product owns acceptance and release decision.
+- Do not merge or release based on assumptions.
+- Do not hide blocking findings.
+- Do not bypass baseline reports with temporary-only notes.
+
+## principles
+
+- Baseline-first verification reports on branch.
+- Risk-based depth: prioritize high-impact paths and failure modes.
+- Evidence over opinion: every finding should be reproducible.
+- Block release for unresolved high-severity defects or security issues.
+- Escalate ambiguous requirements that undermine test verdicts.
+- Prefer deterministic checks and explicit acceptance criteria.
+
+## communication style
+
+- Clear verdicts with severity and reproduction steps.
+- Default concise mode: `ultra`.
+- Separate facts, impact, and recommendations.
+- Keep reports actionable for engineer and product.
+
+{{AGENT_SKILL_BOUNDARY}}
+
+## gate moments and handoffs
+
+Signal readiness before release proceeds:
+
+1. **Ready for acceptance review** — required checks completed and findings documented.
+1. **Ready for release** — no unresolved blocking defects or security-critical issues.
+
+Handoffs you own:
+
+- To engineer: reproducible defects with severity, impact, and recommended fix direction.
+- To product/release: explicit go/no-go verdict with residual risk summary.
+
+## how you work
+
+1. Read `docs/product/requirements.md`, `docs/architecture/architecture.md`, and relevant design/implementation context.
+1. Choose verification mode and scope using `@#inspect` (report-only) or `@#verify` (fix loop).
+1. Execute functional and contract checks for changed behavior and critical paths.
+1. Execute focused security/performance/reliability reviews via `@#security`, `@#performance`, and `@#guardrails` when applicable.
+1. Update or add tests required to prove expected behavior and prevent regressions.
+1. Write baseline reports: `docs/test-report.md`, `docs/security-report.md`, and `docs/performance-baseline.md` when performance validation is in scope. Include observability evidence in `docs/test-report.md` unless a dedicated observability report is used.
+1. Publish verdict and hand off blockers or release-readiness status.
+
+## deliverables and success criteria
+
+| Artifact                       | Role                                              |
+| ------------------------------ | ------------------------------------------------- |
+| `docs/test-report.md`          | creator                                           |
+| `docs/security-report.md`      | creator                                           |
+| `docs/performance-baseline.md` | creator (when performance validation is in scope) |
+| test files                     | creator                                           |
+
+- Verification coverage matches scope and risk.
+- Blocking issues are clearly identified with severity and reproducible evidence.
+- Baseline reports required for the current scope are current and decision-ready.
+
+## failure and escalation rules
+
+- Cannot execute required checks: escalate with explicit gap and risk.
+- Security-critical issue found: escalate immediately and block release.
+- Missing or stale required-for-scope artifacts: stop and report owners.
+
+## skills you use
+
+- `@#concise` — runtime response-style mode (`normal|compact|ultra|status`)
+- `@#inspect` — read-only verification audit, produces findings report
+- `@#security` — security audit
+- `@#performance` — performance review
+- `@#docs` — keep verification and audit documentation complete and current
+- `@#guardrails` — reliability and observability review
+- `@#explore` — codebase discovery and mapping
+- `@#analyse` — impact analysis, tradeoffs, feasibility
+- `@#code-review` — pre-merge review before release
+- `@#migrate` — database migration safety review
+- `@#dependency` — dependency vulnerability and health audit
+- `@#incident` — incident analysis and post-mortem writing

vstack/_templates/instructions/git/config.yaml

@@ -0,0 +1,4 @@
+name: git
+description: Git and release hygiene conventions. Use when creating commits, branches, or release-related changes.
+applyTo: "**/*"
+version: 0.1.0

vstack/_templates/instructions/git/template.md

@@ -0,0 +1,36 @@
+Use these Git and release hygiene conventions in this project.
+
+## Branch naming
+
+1. Use `type/short-description` branch names.
+1. Keep branch names lowercase and use hyphens to separate words.
+1. Use one of these allowed branch types when branch validation is enabled:
+   `feature`, `bugfix`, `hotfix`, `release`, `chore`, `feat`, `fix`, `docs`,
+   `refactor`, `perf`, `test`, `ci`, `build`, `style`, `opt`, `patch`, `dependabot`.
+
+## Commit messages
+
+1. Use Conventional Commits: `type(optional-scope)!: short summary`.
+1. Keep commit subjects clear, imperative, and within repository limits.
+1. Keep the commit subject at 100 characters or fewer when commit policy CI enforces this limit.
+1. Include `!` or a `BREAKING CHANGE:` footer when behavior changes are breaking.
+1. Keep commit type and scope aligned with repository policy.
+
+## SemVer alignment
+
+1. Treat commit messages as release inputs when the repository uses semantic version automation.
+1. Ensure major, minor, and patch intent is reflected in the commit type and breaking markers.
+1. Do not merge release-impacting changes with ambiguous commit messages.
+
+## Security and credentials
+
+1. Never ask users to paste passphrases, tokens, API keys, or private keys into chat.
+1. Never echo or log secrets from terminal prompts, command output, or environment variables.
+1. Never place credentials in commit messages, source files, workflow files, or documentation.
+1. Prefer existing secure authentication flows (for example SSH agent, OS keychain, `gh auth`).
+
+## Safe Git operations
+
+1. Avoid force pushes and destructive history rewrites unless explicitly requested and approved.
+1. Keep commits focused and reviewable.
+1. Prefer local verification before pushing release-impacting changes.

vstack/_templates/instructions/python/config.yaml

@@ -0,0 +1,4 @@
+name: python
+description: Python coding conventions for projects. Use when writing or reviewing Python modules, tests, CLI code, and package internals.
+applyTo: "**/*.py"
+version: 0.1.1

vstack/_templates/instructions/python/template.md

@@ -0,0 +1,37 @@
+Use these Python conventions in this project.
+
+## Design and readability
+
+1. Prefer explicit, domain-meaningful names over abbreviations.
+1. Keep functions focused; split functions that mix parsing, I/O, and business rules.
+1. Prefer straightforward control flow over clever one-liners.
+1. Raise precise exceptions with actionable error messages.
+
+## Typing and APIs
+
+1. Add type hints to public functions, methods, and module-level constants.
+1. Keep public interfaces stable and backward compatible unless the task explicitly allows breaking changes.
+1. Use dataclasses or TypedDict for structured data instead of untyped dicts when shape is known.
+
+## Imports and dependencies
+
+1. Group imports as standard library, third-party, and local modules.
+1. Keep imports minimal and remove unused imports.
+1. Avoid adding runtime dependencies unless there is a clear benefit over stdlib or existing project dependencies.
+
+## Testing and verification
+
+1. Add or update tests for every behavioral change.
+1. Prefer focused unit tests first; add integration coverage when behavior crosses module boundaries.
+1. Cover success paths, edge cases, and expected failures.
+
+## I/O, paths, and safety
+
+1. Prefer pathlib over string-based path manipulation.
+1. Use context managers for files, sockets, and subprocess resources.
+1. Never hardcode secrets or tokens in code or tests.
+
+## Tooling alignment
+
+1. Keep code compatible with repository linting and type-checking standards.
+1. Do not silence lint/type errors unless there is a documented, task-specific reason.

vstack/_templates/prompts/code-review/config.yaml

@@ -0,0 +1,10 @@
+name: code-review
+description: Review a change for bugs, regressions, and missing tests.
+argument-hint: "[scope or files to review]"
+agent: engineer
+model: GPT-5.3-Codex (copilot)
+tools:
+  - read
+  - search
+  - edit
+version: 0.1.0

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

@@ -0,0 +1,39 @@
+Review the selected code or diff for production risk.
+
+Focus only on issues with real impact:
+
+- correctness and edge cases
+- security and data exposure
+- performance and scalability
+- maintainability and ownership boundaries
+- missing tests for changed behavior
+
+Ignore:
+
+- style-only preferences with no runtime impact
+- speculative risks without evidence in this change
+
+Output exactly in this format:
+
+## Must fix
+
+List blocking issues that should be resolved before merge.
+
+## Should consider
+
+List non-blocking improvements worth addressing now.
+
+## Looks good
+
+List intentional strengths in this change.
+
+For each item:
+
+- cite the relevant file/section
+- explain why it matters in one short sentence
+- give one concrete fix suggestion
+
+End with:
+
+- Merge recommendation: yes / no / yes-with-conditions
+- Biggest remaining risk: one sentence

vstack/_templates/skills/_partials/base-branch.md

@@ -0,0 +1,8 @@
+```bash
+# Detect base branch (main / master / develop / trunk)
+BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null) \
+  || BASE=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}') \
+  || BASE=$(git branch -r 2>/dev/null | grep -E '/(main|master|develop|trunk)' | head -1 | sed 's|.*origin/||') \
+  || BASE="main"
+echo "Base branch: $BASE"
+```

vstack/_templates/skills/_partials/observability-checklist.md

@@ -0,0 +1,36 @@
+### Observability Checklist
+
+**Always — every new code path:**
+
+| Aspect              | Check                                                            |
+| ------------------- | ---------------------------------------------------------------- |
+| **Structured logs** | Key events emit structured log with correlation ID               |
+| **Error logs**      | All `catch` / error handlers log at ERROR level with stack trace |
+
+**Where the stack supports it:**
+
+| Aspect      | Check                                                     |
+| ----------- | --------------------------------------------------------- |
+| **Metrics** | Counters/histograms for request rate, error rate, latency |
+| **Traces**  | Distributed trace spans created for cross-service calls   |
+
+**Consider — based on risk and system maturity:**
+
+Think through how failures and performance degradation will be visible in production.
+Not every item is required, but each should be consciously decided:
+
+| Aspect         | Question                                                       |
+| -------------- | -------------------------------------------------------------- |
+| **Alerts**     | How will an error spike or reliability degradation be noticed? |
+| **Dashboards** | Where will this service/endpoint show up in monitoring?        |
+| **Runbook**    | If this fails at 3am, does someone know what to do?            |
+
+> **SLI / SLO / SLA** — three related concepts:
+>
+> - **SLI** (Indicator): the actual measurement — e.g. error rate, p99 latency
+> - **SLO** (Objective): the internal target — e.g. "error rate < 0.1%", "p99 < 200ms"
+> - **SLA** (Agreement): the contractual promise to customers, with consequences if missed
+>
+> Alerts fire when an SLO is at risk. Not every project needs formal SLOs — but every project benefits from knowing what "degraded" looks like.
+
+*Observability is first-class scope, not post-launch cleanup.*

vstack/_templates/skills/_partials/run-tests.md

@@ -0,0 +1,22 @@
+```bash
+# Detect test runner and run tests
+if [ -f package.json ]; then
+  if grep -q '"vitest"' package.json 2>/dev/null; then
+    npx vitest run
+  elif grep -q '"jest"' package.json 2>/dev/null; then
+    npx jest
+  elif grep -q '"bun"' package.json 2>/dev/null; then
+    bun test
+  else
+    npm test
+  fi
+elif [ -f pyproject.toml ] || [ -f setup.py ]; then
+  python -m pytest -v
+elif [ -f go.mod ]; then
+  go test ./...
+elif [ -f Cargo.toml ]; then
+  cargo test
+else
+  echo "No recognized test framework detected."
+fi
+```

vstack/_templates/skills/_partials/skill-context.md

@@ -0,0 +1,21 @@
+## Skill Context
+
+This skill is part of **vstack** — a VS Code-native AI engineering workflow system.
+
+### AskUserQuestion Format
+
+When you need clarification, use this exact format — never invent or guess:
+
+> **Question:** [The specific question]
+> **Options:** A) … | B) … | C) …
+> **Default if no response:** [What you'll do]
+
+Never ask more than one question at a time without waiting for the answer.
+
+### Diagram Convention
+
+When producing hand-authored Markdown outputs, prefer Mermaid for flow,
+interaction, lifecycle, state, topology, dependency, and decision diagrams when
+the format is supported and improves clarity. Use ASCII as a fallback when
+Mermaid is unsupported or would be less readable. Keep ASCII/text trees for
+directory structures and other scan-friendly hierarchies.

vstack/_templates/skills/adr/config.yaml

@@ -0,0 +1,17 @@
+name: adr
+version: 1.0.2
+description: |
+  Architecture Decision Record writing. Documents a significant architectural
+  decision with context, alternatives considered, rationale, and impact.
+  Use when asked to "write an ADR", "document this decision", "record why we
+  chose X", or when a significant technical decision needs a permanent record.
+  Runs after a decision is made or while evaluating options.
+argument-hint: '[decision to record]'
+
+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/adr/template.md

@@ -0,0 +1,167 @@
+{{SKILL_CONTEXT}}
+
+# adr — Architecture Decision Record
+
+Document a significant technical decision so future contributors understand
+what was decided, why, and what alternatives were considered.
+
+## Out of scope
+
+- Architecture reviews of plans (use `architecture`)
+- Gathering requirements (use `requirements`)
+- Implementation (engineering role)
+- Running analysis to inform the decision (use `analyse`)
+
+______________________________________________________________________
+
+## Step 0: Context Gathering
+
+Read existing ADRs and architecture docs:
+
+```bash
+ls docs/architecture/adr/ 2>/dev/null | sort | head -20 || true
+cat docs/architecture/architecture.md 2>/dev/null | head -40 || true
+# Find highest existing ADR number
+ls docs/architecture/adr/*.md 2>/dev/null | grep -oE '[0-9]+' | sort -n | tail -1 || echo "0"
+```
+
+Determine the next ADR number (pad to 3 digits: 001, 002, ...).
+
+______________________________________________________________________
+
+## Step 1: Understand the Decision
+
+> **Question:** What decision are we recording?
+> **Options:** A) Decision already made — record it | B) Options still open — evaluate and recommend | C) Superseding an existing ADR — which one?
+> **Default if no response:** A (record an already-made decision)
+
+Document:
+
+```text
+Decision: [One-line statement of what was decided]
+Status:   proposed | accepted | rejected | deprecated | superseded
+Date:     YYYY-MM-DD
+```
+
+______________________________________________________________________
+
+## Step 2: Context
+
+Why does this decision need to be made? What forces are at play?
+
+Include:
+
+- The problem or requirement driving the decision
+- Relevant constraints (technical, organizational, timeline)
+- Dependencies on other decisions
+- What happens if no decision is made
+
+```markdown
+## Context
+[2-4 paragraphs explaining the situation, constraints, and why this matters]
+```
+
+______________________________________________________________________
+
+## Step 3: Alternatives Considered
+
+List all serious options that were evaluated. For each:
+
+```markdown
+### Option A: [Name]
+**Description:** [What this option is]
+**Pros:**
+- [...]
+**Cons:**
+- [...]
+**Why rejected:** [or "this is the chosen option"]
+```
+
+Include at least 2-3 alternatives. Including a "do nothing" option is recommended.
+
+______________________________________________________________________
+
+## Step 4: Decision
+
+State the chosen option clearly:
+
+```markdown
+## Decision
+We will [chosen option].
+
+[1-2 sentences on why this option was selected over alternatives]
+```
+
+______________________________________________________________________
+
+## Step 5: Rationale
+
+Explain the reasoning in depth:
+
+```markdown
+## Rationale
+[Detailed explanation: what made this the right choice given the context and constraints.
+Reference specific cons from rejected options and explain why they were acceptable tradeoffs.]
+```
+
+______________________________________________________________________
+
+## Step 6: Consequences & Impact
+
+```markdown
+## Consequences
+
+### Positive
+- [Expected benefits]
+
+### Negative / Tradeoffs
+- [Known downsides or limitations of this choice]
+
+### Risks
+- [What could go wrong, and how we'd detect or mitigate it]
+```
+
+______________________________________________________________________
+
+## Step 7: Related Decisions
+
+```markdown
+## Related ADRs
+- ADR-NNN: [title] — [relationship: supersedes / related to / depends on]
+```
+
+______________________________________________________________________
+
+## Output: ADR file
+
+Write to `docs/architecture/adr/NNN-<slug>.md` where NNN is the next available number and slug
+is a kebab-case title.
+
+```markdown
+# ADR-NNN: <title>
+
+**Date:** YYYY-MM-DD
+**Status:** proposed | accepted | rejected | deprecated | superseded
+
+## Context
+[...]
+
+## Decision
+[...]
+
+## Alternatives Considered
+[...]
+
+## Rationale
+[...]
+
+## Consequences
+[...]
+
+## Related ADRs
+[...]
+```
+
+After writing, state the file path and summary so the architect or product role can review.
+
+______________________________________________________________________

vstack/_templates/skills/analyse/config.yaml

@@ -0,0 +1,16 @@
+name: analyse
+version: 1.0.2
+description: |
+  Cross-cutting technical analysis. Investigates impact, tradeoffs, root causes,
+  or feasibility without implementing changes. Use when asked to "analyse this",
+  "investigate the impact", "what are the tradeoffs", "root cause analysis",
+  "is this feasible?", or "compare these approaches". Produces an analysis report.
+argument-hint: '[topic, change, or question to analyse]'
+
+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