vstack 0.0.0__py3-none-any.whl

vstack/_templates/skills/pr/template.md

@@ -0,0 +1,108 @@
+{{SKILL_CONTEXT}}
+
+# pr — Commit, Push & Open Pull Request
+
+Push the current branch and open a PR targeting main. This is the final step
+before CI/CD takes over.
+
+## Out of scope
+
+- Running tests (use `verify`)
+- Writing release notes (use `release-notes`)
+- Merging or deploying — CI/CD handles that after merge
+
+## Deliverable and artifact policy
+
+- Primary deliverable: release pull request targeting main
+- Baseline-first default: use existing branch artifacts directly; do not create parallel release records outside baseline docs.
+- PR body source: `docs/releases/{date}.md` when present
+- Before merge: ensure release artifact references in the PR body reflect final baseline files.
+
+______________________________________________________________________
+
+## Step 1: Pre-flight
+
+```bash
+# Confirm not on main
+BRANCH=$(git branch --show-current)
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  echo "ERROR: on $BRANCH — create a feature branch first"
+  exit 1
+fi
+echo "Branch: $BRANCH"
+
+# Check release notes exist
+DATE=$(date +%Y-%m-%d)
+RELEASE_FILE="docs/releases/${DATE}.md"
+[ -f "$RELEASE_FILE" ] || echo "WARN: $RELEASE_FILE not found — PR body will be empty"
+
+# Show what will be included
+git status --short
+git log origin/main..HEAD --oneline
+```
+
+______________________________________________________________________
+
+## Step 2: Commit
+
+Stage and commit any uncommitted changes:
+
+```bash
+git add -A
+git diff --cached --stat
+
+# Only commit if there are staged changes
+git diff --cached --quiet || git commit -m "release: $(date +%Y-%m-%d)"
+```
+
+______________________________________________________________________
+
+## Step 3: Push
+
+```bash
+git push --set-upstream origin "$BRANCH"
+```
+
+______________________________________________________________________
+
+## Step 4: Open PR
+
+```bash
+DATE=$(date +%Y-%m-%d)
+RELEASE_FILE="docs/releases/${DATE}.md"
+BODY=""
+[ -f "$RELEASE_FILE" ] && BODY=$(cat "$RELEASE_FILE")
+
+gh pr create \
+  --base main \
+  --title "release: ${DATE}" \
+  --body "$BODY"
+```
+
+If `gh` is not available:
+
+```bash
+echo "Open PR manually:"
+echo "  Title: release: $(date +%Y-%m-%d)"
+echo "  Base:  main"
+echo "  Head:  $BRANCH"
+echo "  URL:   https://github.com/<org>/<repo>/compare/main...$BRANCH"
+```
+
+______________________________________________________________________
+
+## Step 5: Report to user
+
+Report the PR URL and next steps:
+
+```text
+PR created: <url>
+
+CI/CD will now:
+- Run tests and security scan
+- Build and publish container image
+- Determine version (semantic-release / conventional commits)
+- Deploy after approval and merge
+```
+
+______________________________________________________________________

vstack/_templates/skills/refactor/config.yaml

@@ -0,0 +1,18 @@
+name: refactor
+version: 1.0.1
+description: |
+  Structured refactoring for backend services, APIs, and libraries. Identifies
+  code smells, plans incremental changes, executes without altering observable
+  behavior, and verifies correctness. Use when asked to "refactor this",
+  "clean up this module", "reduce duplication", or "improve structure without
+  changing behavior". Never changes behavior — if behavior must change, stop
+  and use the engineering role.
+argument-hint: '[module, file, or area to refactor]'
+
+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/refactor/template.md

@@ -0,0 +1,283 @@
+{{SKILL_CONTEXT}}
+
+{{BASE_BRANCH}}
+
+# refactor — Structured Refactoring
+
+Improve the internal structure of code without changing its observable behavior.
+Refactoring is not rewriting. Every step must leave tests green.
+
+## Out of scope
+
+- Fixing bugs (use `debug`)
+- Adding features (engineering role)
+- Performance optimizations that change behavior (use `performance`)
+- Architecture redesign (use `architecture`)
+- Security fixes (use `security`)
+
+**Golden rule: If all tests pass before and after each step, the refactor is
+correct. If behavior changes, stop — that is a feature or bug fix, not a refactor.**
+
+______________________________________________________________________
+
+## Step 0: Define the Scope
+
+> **Question:** What needs refactoring and why?
+>
+> - Which file(s), module(s), or area(s)?
+> - What is the motivation? (duplication, complexity, naming, coupling, size)
+> - What must NOT change? (public API, behavior, performance characteristics)
+>   **Default:** Identify smells in the specified area and propose a plan.
+
+```bash
+# Understand the current state
+git log --oneline -10
+git diff <base> --stat 2>/dev/null | head -20
+
+# Find the files to refactor
+# Read the area before touching anything
+```
+
+Document:
+
+```text
+Scope:       [file(s) or module(s)]
+Motivation:  [duplication | complexity | naming | coupling | size | other]
+Constraints: [what must not change]
+```
+
+______________________________________________________________________
+
+## Step 1: Establish a Baseline
+
+**Never start refactoring without a green test baseline.**
+
+{{RUN_TESTS}}
+
+If tests are red before you start:
+
+```text
+⛔ STOP: Tests are failing before the refactor begins.
+   Fix failing tests first, or confirm with the user that the failures are
+   pre-existing and unrelated to this refactor scope.
+```
+
+Record the baseline:
+
+```text
+Baseline:
+  Tests:    [N passed, N failed, N skipped]
+  Coverage: [N%]
+  Lint:     [clean | N warnings]
+```
+
+______________________________________________________________________
+
+## Step 2: Identify Code Smells
+
+Scan the target area for common smells:
+
+```bash
+# Long files
+wc -l $(find . -name '*.py' -o -name '*.ts' -o -name '*.go' \
+  2>/dev/null | grep -v node_modules | grep -v .venv) 2>/dev/null | sort -rn | head -20
+
+# Duplicated patterns
+grep -r -n "TODO\|FIXME\|HACK\|XXX" \
+  --include='*.py' --include='*.ts' --include='*.go' \
+  --exclude-dir=node_modules --exclude-dir=.venv --exclude-dir=.git \
+  . 2>/dev/null | head -20
+```
+
+| Smell                   | Description                           | Refactoring                 |
+| ----------------------- | ------------------------------------- | --------------------------- |
+| Long function           | > 30 lines, multiple responsibilities | Extract function            |
+| Long file               | > 300 lines                           | Extract module              |
+| Duplicate code          | Same logic in 2+ places               | Extract shared function     |
+| Magic numbers/strings   | Unnamed literals                      | Named constant              |
+| Deep nesting            | > 3 levels                            | Early return / guard clause |
+| Long parameter list     | > 4 parameters                        | Parameter object            |
+| Inappropriate naming    | Misleading or vague names             | Rename                      |
+| Dead code               | Unused functions/variables            | Remove                      |
+| Comment explaining code | Code needs a comment to be understood | Rewrite the code            |
+| Mutable global state    | Module-level mutable variables        | Encapsulate                 |
+
+Produce a prioritized smell list:
+
+```text
+Smells found:
+  P1 (high impact): [smell] — [location]
+  P2 (medium):      [smell] — [location]
+  P3 (low):         [smell] — [location]
+```
+
+______________________________________________________________________
+
+## Step 3: Plan the Refactoring
+
+Break the refactoring into small, independent steps. Each step must:
+
+1. Change exactly one thing
+1. Leave tests green
+1. Be reviewable in isolation
+
+```text
+Refactoring plan:
+  Step 1: [specific change] — [file] — [smell addressed]
+  Step 2: [specific change] — [file] — [smell addressed]
+  Step 3: ...
+
+Estimated scope: [N files, N functions]
+Risk:            [Low | Medium — reason]
+```
+
+**Stop and confirm with user if:**
+
+- The plan requires changing a public API or exported interface
+- The plan requires changing database schema
+- More than 10 files are affected
+
+______________________________________________________________________
+
+## Step 4: Execute — One Step at a Time
+
+For each planned step:
+
+1. Make the change
+1. Run tests immediately
+1. Confirm green before moving to the next step
+
+{{RUN_TESTS}}
+
+### Common refactoring patterns
+
+**Extract function (Python):**
+
+```python
+# Before
+def process_order(order):
+    # validate
+    if not order.get("id"):
+        raise ValueError("missing id")
+    if order.get("amount", 0) <= 0:
+        raise ValueError("amount must be positive")
+    # process
+    ...
+
+# After
+def _validate_order(order: dict) -> None:
+    if not order.get("id"):
+        raise ValueError("missing id")
+    if order.get("amount", 0) <= 0:
+        raise ValueError("amount must be positive")
+
+def process_order(order: dict) -> None:
+    _validate_order(order)
+    ...
+```
+
+**Guard clause (replace nested conditionals):**
+
+```python
+# Before
+def process(item):
+    if item is not None:
+        if item.active:
+            if item.value > 0:
+                return item.value * 2
+    return None
+
+# After
+def process(item):
+    if item is None:
+        return None
+    if not item.active:
+        return None
+    if item.value <= 0:
+        return None
+    return item.value * 2
+```
+
+**Named constant:**
+
+```python
+# Before
+if status_code == 429:
+    time.sleep(60)
+
+# After
+HTTP_TOO_MANY_REQUESTS = 429
+RATE_LIMIT_BACKOFF_SECONDS = 60
+
+if status_code == HTTP_TOO_MANY_REQUESTS:
+    time.sleep(RATE_LIMIT_BACKOFF_SECONDS)
+```
+
+**Parameter object:**
+
+```python
+# Before
+def create_user(name, email, role, department, manager_id, start_date):
+    ...
+
+# After
+@dataclass
+class CreateUserRequest:
+    name: str
+    email: str
+    role: str
+    department: str
+    manager_id: str
+    start_date: date
+
+def create_user(request: CreateUserRequest) -> User:
+    ...
+```
+
+______________________________________________________________________
+
+## Step 5: Verify
+
+After all steps are complete, run the full verification suite:
+
+{{RUN_TESTS}}
+
+Check:
+
+- [ ] All tests still pass (same count as baseline)
+- [ ] Coverage has not dropped
+- [ ] No new lint warnings introduced
+- [ ] No public interfaces changed (unless explicitly in scope)
+- [ ] No behavior changes (verify with diff)
+
+```bash
+# Review what changed
+git diff --stat
+git diff
+```
+
+______________________________________________________________________
+
+## Output
+
+```text
+Refactoring Summary
+═══════════════════
+
+Scope:     [file(s) / module(s)]
+Smells:    [N identified]
+Steps:     [N completed]
+
+Changes made:
+  ✅ [Step 1 description] — [file]
+  ✅ [Step 2 description] — [file]
+  ...
+
+Result:
+  Tests:    [N passed — same as baseline]
+  Coverage: [N% — unchanged or improved]
+  Lint:     [clean]
+
+Public API changed: No
+Behavior changed:   No
+```

vstack/_templates/skills/release-notes/config.yaml

@@ -0,0 +1,16 @@
+name: release-notes
+version: 1.0.2
+description: |
+  Prepare release artifacts: verify all docs are present, write release notes,
+  own CHANGELOG.md updates, and produce docs/releases/{date}.md.
+  Use when asked to "write release notes", "update the changelog", or
+  "prepare release artifacts".
+argument-hint: '[version or changes to release]'
+
+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/release-notes/template.md

@@ -0,0 +1,127 @@
+{{SKILL_CONTEXT}}
+
+# release-notes — Release Artifact Preparation
+
+Verify all artifacts are complete, write release notes, and update the changelog.
+
+This skill owns both `docs/releases/{date}.md` and `CHANGELOG.md` updates.
+
+## Out of scope
+
+- Running tests or audits (use `verify`, `security`, `performance`)
+- Creating the PR (use `pr`)
+- Deployment — CI/CD takes over after merge
+
+## Deliverable and artifact policy
+
+- Primary deliverables: `docs/releases/{date}.md`, `CHANGELOG.md`
+- Baseline-first default: write final release artifacts directly to baseline docs on the feature branch.
+- Optional WIP area for complex/uncertain efforts: `docs/delta/{id}/RELEASE_DELTA.md`
+- Before merge: consolidate final release summary and changelog entries into baseline artifacts.
+
+______________________________________________________________________
+
+## Step 1: Artifact checklist
+
+Verify these files exist and are not empty:
+
+```bash
+for f in docs/product/requirements.md docs/architecture/architecture.md docs/design/design.md \
+          docs/test-report.md docs/security-report.md CHANGELOG.md; do
+  [ -f "$f" ] && echo "✓ $f" || echo "✗ MISSING: $f"
+done
+
+# Scope-conditional artifacts
+[ -f docs/performance-baseline.md ] && echo "✓ docs/performance-baseline.md" || echo "i docs/performance-baseline.md (optional unless performance validation is in scope)"
+[ -f docs/observability-baseline.md ] && echo "✓ docs/observability-baseline.md" || echo "i docs/observability-baseline.md (optional; observability evidence may be in docs/test-report.md)"
+```
+
+If any required artifact is missing: **STOP and report**. Do not proceed.
+If performance validation is in scope and `docs/performance-baseline.md` is missing: **STOP and report**.
+
+______________________________________________________________________
+
+## Step 2: Summarise changes
+
+Review what changed on this branch vs main:
+
+```bash
+git log origin/main..HEAD --oneline
+git diff origin/main --stat | head -30
+```
+
+Identify:
+
+- New features
+- Bug fixes
+- Breaking changes (if any)
+- Internal/infrastructure changes
+
+______________________________________________________________________
+
+## Step 3: Write `docs/releases/{date}.md`
+
+Date format: `YYYY-MM-DD` (today). Never overwrite an existing file.
+
+```bash
+DATE=$(date +%Y-%m-%d)
+RELEASE_FILE="docs/releases/${DATE}.md"
+[ -f "$RELEASE_FILE" ] && echo "ERROR: $RELEASE_FILE already exists" && exit 1
+mkdir -p docs/releases
+```
+
+Write the file with this structure:
+
+```markdown
+# Release {date}
+
+## summary
+[1–3 sentences: what changed and why it matters to users]
+
+## what's new
+- [user-visible feature or fix — lead with what the user can now DO]
+
+## fixed
+- [bug fixes]
+
+## internal
+- [infra, tooling, tests — optional]
+
+## artifacts reviewed
+| artifact | status |
+|----------|--------|
+| docs/product/requirements.md | ✓ |
+| docs/architecture/architecture.md | ✓ |
+| docs/design/design.md | ✓ |
+| docs/test-report.md | ✓ |
+| docs/security-report.md | ✓ |
+```
+
+Rules:
+
+- Write for users, not contributors
+- No internal tracking references
+- Every entry should make someone think "oh nice, I want that"
+
+______________________________________________________________________
+
+## Step 4: Update `CHANGELOG.md`
+
+Prepend a new entry at the top of `CHANGELOG.md`:
+
+```markdown
+## {date}
+
+### What's new
+- [user-visible changes]
+
+### Fixed
+- [bug fixes]
+
+### Internal
+- [optional]
+```
+
+Keep existing entries intact.
+
+______________________________________________________________________

vstack/_templates/skills/requirements/config.yaml

@@ -0,0 +1,17 @@
+name: requirements
+version: 1.0.2
+description: |
+  Collaborative requirements gathering and documentation. Clarifies what must be
+  built, defines success criteria, constraints, and non-functional requirements.
+  Produces a requirements.md document. Use when asked to "gather requirements",
+  "write the requirements", "define the spec", or "what are we building?".
+  Runs before architecture and design work begins.
+argument-hint: '[feature or system to document]'
+
+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