vstack 0.0.0__py3-none-any.whl

vstack/_templates/skills/analyse/template.md

@@ -0,0 +1,188 @@
+{{SKILL_CONTEXT}}
+
+{{BASE_BRANCH}}
+
+# analyse — Technical Analysis
+
+Investigate a technical question, impact, or tradeoff. Produce a structured
+analysis report. Do not implement changes — that is engineering role work.
+
+## Out of scope
+
+- Fixing bugs (use `debug`)
+- Performance benchmarking with code changes (use `performance`)
+- Architecture decisions (use `architecture` + `adr`)
+- Implementation (engineering role)
+- Full test run (use `verify`)
+
+______________________________________________________________________
+
+## Step 0: Define the Question
+
+Clarify exactly what is being analysed:
+
+> **Question:** What is the specific question or concern to investigate?
+>
+> - Impact analysis: "What breaks if we change X?"
+> - Tradeoff analysis: "Compare approach A vs approach B"
+> - Feasibility analysis: "Can we do X given constraints Y?"
+> - Root cause analysis: "Why does X happen?"
+> - Risk analysis: "What are the risks of doing/not doing X?"
+>   **Default:** Open-ended investigation based on user's context
+
+Document:
+
+```text
+Analysis type: [impact | tradeoff | feasibility | root-cause | risk | other]
+Question:      [Precise question being answered]
+Scope:         [What's in and out of scope for this analysis]
+```
+
+______________________________________________________________________
+
+## Phase 1: Evidence Gathering
+
+Gather all relevant context before drawing any conclusions:
+
+```bash
+# Understand the current state
+git log --oneline -20
+cat TODOS.md 2>/dev/null | head -30 || true
+
+# Find relevant code
+# (adjust search terms to the specific question)
+grep -r -n "TODO\|FIXME\|DEPRECATED" \
+  --include='*.ts' --include='*.py' --include='*.go' \
+  --exclude-dir=node_modules . 2>/dev/null | head -20
+```
+
+For **impact analysis**, find all call sites / dependents:
+
+```bash
+# Find all usages of a symbol, function, or interface
+grep -r -n "SYMBOL_NAME" \
+  --include='*.ts' --include='*.py' --include='*.go' \
+  --exclude-dir=node_modules . 2>/dev/null
+```
+
+For **dependency analysis**:
+
+```bash
+# Dependency graph (if available)
+[ -f package.json ] && npx madge --circular --extensions ts ./src 2>/dev/null || true
+```
+
+______________________________________________________________________
+
+## Phase 2: Dimension Analysis
+
+Structure the analysis around the relevant dimensions for the question type:
+
+### For impact analysis:
+
+- What systems/services/consumers are affected?
+- What is the blast radius? (local, service-wide, cross-service, user-facing)
+- Are breaking changes involved?
+- What is the rollback strategy?
+- Migration effort estimate
+
+### For tradeoff analysis:
+
+For each option:
+
+| Dimension         | Option A | Option B |
+| ----------------- | -------- | -------- |
+| Complexity        |          |          |
+| Performance       |          |          |
+| Maintainability   |          |          |
+| Cost              |          |          |
+| Risk              |          |          |
+| Time to implement |          |          |
+
+### For feasibility analysis:
+
+- Technical feasibility: can this be built with current stack/skills?
+- Constraints: what limits apply (time, budget, API limits, data size)?
+- Dependencies: what must be true for this to work?
+- Risks: what could prevent success?
+
+### For root cause analysis:
+
+- What is the observed symptom?
+- What are the contributing factors?
+- Primary cause vs contributing causes
+- Timeline: when did this start? What changed?
+
+### For risk analysis:
+
+| Risk | Likelihood      | Impact          | Mitigation |
+| ---- | --------------- | --------------- | ---------- |
+| ...  | High/Medium/Low | High/Medium/Low | ...        |
+
+______________________________________________________________________
+
+## Phase 3: Data & Evidence
+
+Support findings with concrete evidence:
+
+```bash
+# Metrics, logs, or data that support the analysis
+# Error rates, latency percentiles, query counts, etc.
+```
+
+Reference specific:
+
+- Code locations (file:line)
+- Data points (error counts, latency numbers, test results)
+- Documentation (ADRs, design docs, API specs)
+
+______________________________________________________________________
+
+## Phase 4: Findings & Conclusions
+
+Present findings clearly:
+
+```markdown
+## Findings
+
+### [Finding 1 — short title]
+[Evidence + explanation]
+
+### [Finding 2]
+[Evidence + explanation]
+```
+
+State conclusions with confidence level:
+
+- **Certain:** evidenced directly from code/data
+- **Probable:** well-supported by evidence but not confirmed
+- **Uncertain:** hypothesis that requires further investigation
+
+______________________________________________________________________
+
+## Analysis Report
+
+```text
+## Analysis Report — [topic] — [date]
+
+### Question
+[The specific question answered]
+
+### TL;DR
+[2-3 sentence executive summary of the most important finding]
+
+### Findings
+[Structured findings with evidence]
+
+### Recommendation
+[If applicable: what to do based on the analysis]
+[NOT an implementation plan — just the recommended direction]
+
+### Open Questions
+[What remains unclear and needs further investigation]
+
+### Confidence
+[Overall confidence level: high / medium / low — and why]
+```
+
+______________________________________________________________________

vstack/_templates/skills/architecture/config.yaml

@@ -0,0 +1,18 @@
+name: architecture
+version: 1.0.2
+description: |
+  Engineering-lead plan review. Lock in the execution plan —
+  service boundaries, data models, API contracts, error handling, test strategy,
+  distributed systems correctness, migrations, and observability. Walks through
+  issues with opinionated recommendations. Use when asked to "review the architecture",
+  "engineering review", or "lock in the plan". Proactively suggest when the user
+  has a plan and is about to start coding — catch architecture issues before implementation.
+argument-hint: '[plan or system 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

vstack/_templates/skills/architecture/template.md

@@ -0,0 +1,213 @@
+{{SKILL_CONTEXT}}
+
+# architecture — Engineering Plan Review
+
+Review the plan before any code is written. Identify issues, give opinionated
+recommendations, and produce a final verdict.
+
+## Out of scope
+
+- Writing ADRs for each decision (use `adr`)
+- DX/API ergonomics review (use `consult`)
+- Implementation (engineering role)
+- Gathering requirements (use `requirements`)
+- Writing the design document (use `design` for API/service design)
+
+## Deliverable and artifact policy
+
+- Primary deliverable: `docs/architecture/architecture.md`
+- Additional deliverables when needed: `docs/architecture/adr/NNN-*.md` for significant structural decisions.
+- Baseline-first default: write final architecture decisions directly to `docs/architecture/architecture.md` on the feature branch.
+- Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/ARCHITECTURE_DELTA.md`
+- Before merge: consolidate any required content from optional delta notes back into baseline architecture docs and keep ADRs in `docs/architecture/adr/`.
+
+## Review philosophy
+
+Review the plan thoroughly before any code changes. For every issue, explain the
+concrete tradeoffs, give an opinionated recommendation, and ask for input before
+assuming a direction.
+
+## Priority Hierarchy
+
+If running low on context or asked to compress: Step 0 > Service/contract diagram > Test diagram > Opinionated recommendations > Everything else.
+**Never skip Step 0 or the service/contract diagram.**
+
+## Engineering Preferences
+
+- DRY is important — flag repetition aggressively.
+- Well-tested code is non-negotiable; rather too many tests than too few.
+- "Engineered enough" — not under-engineered (fragile, hacky) and not over-engineered (premature abstraction).
+- Bias toward explicit over clever.
+- Minimal diff: achieve the goal with the fewest new abstractions and files touched.
+- Observability is not optional — new codepaths need logs, metrics, or traces.
+- Security is not optional — new codepaths need threat modeling.
+- Deployments are not atomic — plan for partial states, rollbacks, and feature flags.
+- Diagrams for all data flows, state machines, and service dependencies.
+
+## Cognitive Patterns — How Great Engineering Leads Think
+
+These are not checklist items — they are the instincts experienced leads develop:
+
+1. **State diagnosis** — Is the team falling behind, treading water, repaying debt, or innovating? Each demands a different intervention.
+1. **Blast radius instinct** — Every decision evaluated through "what's the worst case and how many systems/teams does it affect?"
+1. **Boring by default** — "Every company gets about three innovation tokens." Everything else should be proven technology.
+1. **Incremental over revolutionary** — Strangler fig, not big bang. Canary, not global rollout. Refactor, not rewrite.
+1. **Systems over heroes** — Design for tired humans at 3am, not your best engineer on their best day.
+1. **Reversibility preference** — Database migrations, API breaking changes, and service renames are one-way doors. Everything else: feature flags, canaries, gradual rollouts.
+1. **Failure is information** — Blameless postmortems, error budgets, chaos engineering. Incidents are learning opportunities.
+1. **Org structure IS architecture** — Conway's Law. Design both intentionally.
+1. **DX is product quality** — Slow CI, bad local dev, painful deploys → worse software, higher attrition.
+1. **Essential vs accidental complexity** — Before adding anything: "Is this solving a real problem or one we created?"
+1. **Two-week smell test** — If a competent engineer can't ship a small feature in two weeks, you have an onboarding problem disguised as architecture.
+1. **Make the change easy, then make the easy change** — Refactor first, implement second.
+1. **Error budgets over uptime targets** — SLO of 99.9% = 0.1% downtime budget to spend on shipping.
+1. **API contracts are public promises** — Breaking changes require major version bumps and migration plans.
+1. **Idempotency is not optional** — All state-mutating operations must be safe to retry.
+
+## BEFORE YOU START: Design Doc Check
+
+```bash
+# Look for existing design docs
+find . -name '*design*.md' -o -name '*adr*.md' -o -name 'DESIGN.md' 2>/dev/null | head -5
+ls docs/ 2>/dev/null | grep -i 'design\|architecture\|adr' || true
+```
+
+If a design doc exists, read it. Use it as the source of truth for the problem statement, constraints, and chosen approach.
+
+## Step 0: Scope Challenge
+
+Before reviewing anything, answer:
+
+1. **What existing code already partially or fully solves each sub-problem?**
+1. **What is the minimum set of changes that achieves the stated goal?** Flag deferrable work.
+1. **Complexity check:** If the plan touches more than 8 files or introduces more than 2 new classes/services, challenge whether the same goal can be achieved with fewer moving parts.
+1. **Search check:** For each architectural pattern or infrastructure component introduced:
+   - Does the runtime/framework have a built-in? Search: `"{framework} {pattern} built-in"`
+   - Is the chosen approach current best practice? Search: `"{pattern} best practice {current year}"`
+   - Are there known footguns? Search: `"{framework} {pattern} pitfalls"`
+1. **TODOS cross-reference:** Read `TODOS.md` if it exists. Are any deferred items blocking this plan? Can any be bundled?
+1. **Completeness check:** Is the plan doing the complete version or a shortcut? With AI coding, completeness costs minutes. Recommend the complete version.
+1. **Distribution check:** If the plan introduces a new artifact (CLI, library, container image), does it include the build/publish pipeline?
+
+## Step 1: Service Boundary & Data Model Review
+
+Produce a service topology diagram. Prefer Mermaid when possible; use ASCII only
+as a fallback when Mermaid would be less clear or unsupported.
+
+```mermaid
+flowchart LR
+        A[Service A<br>this plan] -->|HTTP or gRPC| B[Service B<br>existing]
+        A -->|publishes| C[Event Bus]
+```
+
+Review:
+
+1. Are service boundaries aligned with business domains (Conway's Law)?
+1. Is data ownership clear — exactly one service owns each entity?
+1. Are there any circular dependencies?
+1. Is the data model correct and complete? (Schema, indexes, constraints, migrations)
+1. Is the communication style appropriate? (sync HTTP vs async events vs batch)
+
+## Step 2: Interface Boundary Review
+
+1. Are external interfaces identified and named for each service?
+1. Is API-first established as a principle — contracts defined before implementation?
+1. Is the communication style per boundary appropriate? (sync REST/gRPC vs async events vs batch)
+1. Are breaking change policies established? (semver, deprecation windows)
+1. Are cross-cutting concerns assigned? (auth, rate limiting, tracing headers)
+
+> Detailed API contracts, schemas, and error envelopes are the designer's responsibility.
+
+## Step 3: Error Handling & Resilience
+
+For every external call, answer:
+
+- What HTTP/gRPC status codes can be returned?
+- What is the retry strategy? (exponential backoff, jitter, max retries)
+- Is the operation idempotent? If not, what prevents duplicate processing?
+- Is there a circuit breaker? What triggers open/half-open/closed transitions?
+- What is the fallback behavior when the dependency is unavailable?
+- What happens on partial failure (some items succeed, some fail)?
+- What is the dead letter queue strategy for async operations?
+
+## Step 4: Data Integrity & Migration Review
+
+1. Are all database migrations backward-compatible (expand-contract pattern)?
+1. Are there any operations that can't be rolled back?
+1. Is there a data migration plan for existing records?
+1. Are there any race conditions in concurrent writes? (optimistic locking, transactions)
+1. Is the event sourcing / CQRS boundary clear if applicable?
+
+## Step 5: Test Strategy
+
+Produce a test plan:
+
+```text
+Unit tests:          [list key units under test]
+Integration tests:   [list key integration points]
+Contract tests:      [list API contracts under test]
+Smoke tests:         [list post-deploy verification steps]
+Performance tests:   [if needed — define criteria]
+```
+
+Review:
+
+1. Are all error paths tested, not just the happy path?
+1. Are there contract tests for each API boundary?
+1. Is there a test data strategy? (fixtures, test factories, seed data)
+1. Can tests run in CI without external dependencies? (use mocks/stubs for external services)
+1. Is test coverage adequate for the risk level?
+
+## Step 6: Observability Plan
+
+{{OBSERVABILITY_CHECKLIST}}
+
+1. What structured log events are emitted at key decision points?
+1. What metrics are introduced? Are SLOs defined?
+1. Are distributed traces created for cross-service calls?
+1. Are there new alerts? Are runbooks documented?
+1. Are dashboards updated to include new services/endpoints?
+
+## Step 7: Security Review
+
+1. What new attack surface does this introduce?
+1. Is input validation complete for all user-controlled inputs?
+1. Is secret management handled correctly? (No secrets in code, env files, or logs)
+1. Are there OWASP Top 10 risks to address?
+1. Is authorization checked at every new endpoint/operation?
+
+## Step 8: Performance Review
+
+1. What are the acceptance criteria for latency? (p50, p95, p99)
+1. Are there N+1 query issues in database access patterns?
+1. Are expensive operations cached? Is cache invalidation correct?
+1. Is the system designed to scale horizontally?
+1. Are there any synchronous operations that should be asynchronous?
+
+## Step 9: CI/CD Review
+
+1. Does the CI pipeline test the new code paths?
+1. Is the deployment strategy defined? (blue/green, canary, rolling)
+1. Is the rollback procedure documented and tested?
+1. Are feature flags used for gradual rollout?
+1. Is the performance regression test plan defined?
+
+## Step 10: Final Recommendations
+
+For each issue found: concrete recommendation with rationale. Classify as:
+
+- **BLOCKING:** Must be resolved before coding starts.
+- **IMPORTANT:** Should be resolved in this PR.
+- **DEFERRED:** Document in TODOS.md with rationale for deferral.
+
+Final verdict: **READY TO IMPLEMENT** / **NEEDS REVISION** / **RETHINK REQUIRED**
+
+## Step 11: Record Architectural Decisions
+
+For each significant structural decision made during this review (technology choices, service boundaries, resilience strategy, data ownership, security posture):
+
+- Write an ADR via `@#adr`.
+- Cross-reference related ADRs.
+- Update `docs/architecture/architecture.md` to reflect the final decisions.
+
+______________________________________________________________________

vstack/_templates/skills/cicd/config.yaml

@@ -0,0 +1,16 @@
+name: cicd
+version: 1.0.2
+description: |
+  Write GitHub Actions CI/CD workflow configuration. Covers build, test, lint,
+  security scan, container publish, and deployment trigger workflows.
+  Use when asked to "write a CI pipeline", "set up GitHub Actions",
+  "add a workflow", or "configure CD".
+argument-hint: '[service or workflow to configure]'
+
+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/cicd/template.md

@@ -0,0 +1,169 @@
+{{SKILL_CONTEXT}}
+
+# cicd — GitHub Actions Workflows
+
+Write CI/CD pipeline configuration as `.github/workflows/*.yml` files.
+These files live in the PR — the pipeline runs after merge.
+
+## Out of scope
+
+- Application code changes (engineering role)
+- Container image authoring (use `container`)
+- Post-deploy monitoring (CI/CD's responsibility after merge)
+
+______________________________________________________________________
+
+## Step 1: Detect context
+
+```bash
+# Detect runtime and tooling
+ls pyproject.toml requirements.txt package.json go.mod Cargo.toml 2>/dev/null | head -5
+
+# Detect existing workflows
+ls .github/workflows/ 2>/dev/null || echo "No workflows found"
+
+# Detect container config
+ls Dockerfile 2>/dev/null && echo "Dockerfile present"
+```
+
+______________________________________________________________________
+
+## Step 2: CI workflow — `.github/workflows/ci.yml`
+
+Runs on every push and PR. Must pass before merge.
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Language-specific setup — pick the applicable block:
+
+      # Python
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy .
+      - run: pytest --tb=short
+
+      # Node
+      # - uses: actions/setup-node@v4
+      #   with: { node-version: "22" }
+      # - run: npm ci
+      # - run: npm run lint
+      # - run: npm test
+
+      # Go
+      # - uses: actions/setup-go@v5
+      #   with: { go-version: "1.22" }
+      # - run: go vet ./...
+      # - run: go test ./...
+```
+
+______________________________________________________________________
+
+## Step 3: Security scan — add to CI or separate workflow
+
+Add dependency and secret scanning:
+
+```yaml
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Dependency scan (pick one):
+      # Python
+      - run: pip install pip-audit && pip-audit
+
+      # Node
+      # - run: npm audit --audit-level=high
+
+      # Secret scan
+      - uses: trufflesecurity/trufflehog-actions-scan@main
+        with:
+          path: ./
+          base: ${{ github.event.repository.default_branch }}
+```
+
+______________________________________________________________________
+
+## Step 4: CD workflow — `.github/workflows/cd.yml`
+
+Runs on merge to main. Builds and publishes the container image, then triggers deployment.
+
+```yaml
+name: CD
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository }}:latest
+            ghcr.io/${{ github.repository }}:${{ github.sha }}
+```
+
+Adapt the deploy trigger to match the target platform (Fly.io, Render, Railway, K8s, etc.).
+
+______________________________________________________________________
+
+## Step 5: Branch protection (document, don't automate)
+
+Record in `docs/architecture/architecture.md` or a README section:
+
+```text
+Branch protection rules for `main`:
+- Require PR before merging
+- Require status checks: CI / test, CI / security
+- Require at least 1 approval
+- No force pushes
+```
+
+Configure these in GitHub → Settings → Branches.
+
+______________________________________________________________________
+
+## Step 6: Review checklist
+
+- [ ] CI workflow triggers on push + PR
+- [ ] Lint, type-check, and tests all run in CI
+- [ ] Security scan included
+- [ ] CD triggers only on merge to main
+- [ ] No secrets hardcoded in workflow files — use `secrets.*`
+- [ ] Container image tagged with both `latest` and `${{ github.sha }}`
+- [ ] Workflows validate locally: `act` (optional, for local testing)
+
+______________________________________________________________________

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

@@ -0,0 +1,16 @@
+name: code-review
+version: 1.0.2
+description: |
+  Pre-landing code review. Finds bugs that pass CI but break in production —
+  race conditions, missing error handling, API contract violations, observability
+  gaps, security issues, and performance landmines. Use when asked to "review",
+  "code review", "review this PR", or before merging.
+argument-hint: '[files, PR, or change 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