From 8a6a3c97779d9fbe1bf690ea0ea9fe4dbc99f6ef Mon Sep 17 00:00:00 2001 From: Erik Schaareman Date: Wed, 22 Apr 2026 00:02:16 +0200 Subject: [PATCH 1/2] chore(dx): improve onboarding flow and feedback templates --- .../DISCUSSION_TEMPLATE/first-run-report.md | 35 ++ .../model-cost-feedback.md | 27 + .../onboarding-feedback.md | 28 + .github/agents/architect.agent.md | 4 +- .github/agents/designer.agent.md | 2 +- .github/agents/engineer.agent.md | 2 +- .github/agents/product.agent.md | 4 +- .github/agents/release.agent.md | 2 +- .github/agents/tester.agent.md | 2 +- .github/instructions/git.instructions.md | 2 +- .github/instructions/python.instructions.md | 2 +- .github/prompts/code-review.prompt.md | 2 +- .github/skills/adr/SKILL.md | 2 +- .github/skills/analyse/SKILL.md | 2 +- .github/skills/architecture/SKILL.md | 2 +- .github/skills/cicd/SKILL.md | 2 +- .github/skills/code-review/SKILL.md | 2 +- .github/skills/concise/SKILL.md | 2 +- .github/skills/consult/SKILL.md | 2 +- .github/skills/container/SKILL.md | 2 +- .github/skills/debug/SKILL.md | 2 +- .github/skills/dependency/SKILL.md | 2 +- .github/skills/design/SKILL.md | 2 +- .github/skills/docs/SKILL.md | 2 +- .github/skills/explore/SKILL.md | 2 +- .github/skills/guardrails/SKILL.md | 2 +- .github/skills/incident/SKILL.md | 2 +- .github/skills/inspect/SKILL.md | 2 +- .github/skills/migrate/SKILL.md | 2 +- .github/skills/onboard/SKILL.md | 2 +- .github/skills/openapi/SKILL.md | 2 +- .github/skills/performance/SKILL.md | 2 +- .github/skills/pr/SKILL.md | 2 +- .github/skills/refactor/SKILL.md | 2 +- .github/skills/release-notes/SKILL.md | 2 +- .github/skills/requirements/SKILL.md | 2 +- .github/skills/security/SKILL.md | 2 +- .github/skills/verify/SKILL.md | 2 +- .github/skills/vision/SKILL.md | 2 +- .github/vstack.json | 4 +- CHANGELOG.md | 52 ++ README.md | 585 +++++++++++++----- .../adr/001-vscode-native-variant.md | 2 +- .../_templates/agents/architect/config.yaml | 2 +- .../_templates/agents/product/config.yaml | 2 +- tests/vstack/agents/test_generation.py | 2 +- 46 files changed, 600 insertions(+), 215 deletions(-) create mode 100644 .github/DISCUSSION_TEMPLATE/first-run-report.md create mode 100644 .github/DISCUSSION_TEMPLATE/model-cost-feedback.md create mode 100644 .github/DISCUSSION_TEMPLATE/onboarding-feedback.md diff --git a/.github/DISCUSSION_TEMPLATE/first-run-report.md b/.github/DISCUSSION_TEMPLATE/first-run-report.md new file mode 100644 index 0000000..5a2937c --- /dev/null +++ b/.github/DISCUSSION_TEMPLATE/first-run-report.md @@ -0,0 +1,35 @@ +--- +title: "[First Run Report] " +labels: + - onboarding + - first-run +--- + +## Outcome + +- Status: success / partial / blocked +- Repository-scoped install used: yes/no + +## Commands you ran + +Paste the exact commands in order. + +## Expected vs actual + +- Expected: +- Actual: + +## Errors (if any) + +Paste relevant error output snippets. + +## Environment details + +- OS: +- Python version: +- vstack version: +- Copilot mode used: Agent / Ask / Edit + +## Follow-up + +What would have made this first run easier? diff --git a/.github/DISCUSSION_TEMPLATE/model-cost-feedback.md b/.github/DISCUSSION_TEMPLATE/model-cost-feedback.md new file mode 100644 index 0000000..80f6080 --- /dev/null +++ b/.github/DISCUSSION_TEMPLATE/model-cost-feedback.md @@ -0,0 +1,27 @@ +--- +title: "[Model and Cost Feedback] " +labels: + - models + - cost + - feedback +--- + +## Role and task + +Which role/task were you running (for example `@architect`, `/verify`, `/security`)? + +## Model used + +Which model did you use? + +## Quality and speed + +How would you rate output quality and response speed? + +## Cost-value tradeoff + +Did the selected model feel cost-effective for this task? + +## Preferred default + +Which default model would you prefer for this role/task and why? diff --git a/.github/DISCUSSION_TEMPLATE/onboarding-feedback.md b/.github/DISCUSSION_TEMPLATE/onboarding-feedback.md new file mode 100644 index 0000000..c05ad99 --- /dev/null +++ b/.github/DISCUSSION_TEMPLATE/onboarding-feedback.md @@ -0,0 +1,28 @@ +--- +title: "[Onboarding Feedback] " +labels: + - onboarding + - feedback +--- + +## Context + +- First time using vstack: yes/no +- Setup mode used: project (`--target`) / global (`--global`) +- Environment: OS, Python version, editor version + +## What worked well + +Describe the parts of onboarding that felt clear and fast. + +## Where you got stuck + +List the exact step(s), commands, or docs that were unclear. + +## Time to first successful result + +How long did it take to run your first successful `@tester /verify` flow? + +## Suggested improvements + +If you could improve one thing for first-time users, what would it be? diff --git a/.github/agents/architect.agent.md b/.github/agents/architect.agent.md index a261849..05ae1e2 100644 --- a/.github/agents/architect.agent.md +++ b/.github/agents/architect.agent.md @@ -18,9 +18,9 @@ tools: agents: - * model: - - Claude Opus 4.6 (copilot) - Claude Sonnet 4.6 (copilot) - GPT-5.3-Codex (copilot) + - Claude Opus 4.7 (copilot) user-invocable: true target: vscode handoffs: @@ -120,4 +120,4 @@ Handoffs you own: - `@#analyse` — impact analysis, tradeoffs, feasibility - + diff --git a/.github/agents/designer.agent.md b/.github/agents/designer.agent.md index 51dd744..127197f 100644 --- a/.github/agents/designer.agent.md +++ b/.github/agents/designer.agent.md @@ -131,4 +131,4 @@ Handoffs you own: - `@#openapi` — OpenAPI 3.1 spec writing and review - + diff --git a/.github/agents/engineer.agent.md b/.github/agents/engineer.agent.md index 3645ea4..7d78676 100644 --- a/.github/agents/engineer.agent.md +++ b/.github/agents/engineer.agent.md @@ -121,4 +121,4 @@ Only delegate when workstreams are genuinely independent. - `@#incident` — incident analysis and post-mortem writing - + diff --git a/.github/agents/product.agent.md b/.github/agents/product.agent.md index c7d60eb..43166a4 100644 --- a/.github/agents/product.agent.md +++ b/.github/agents/product.agent.md @@ -18,8 +18,8 @@ agents: - * model: - Claude Sonnet 4.6 (copilot) - - Claude Opus 4.6 (copilot) - GPT-5.3-Codex (copilot) + - Claude Opus 4.7 (copilot) user-invocable: true target: vscode handoffs: @@ -122,4 +122,4 @@ Handoffs you own: - `@#onboard` — contributor onboarding guide generation - + diff --git a/.github/agents/release.agent.md b/.github/agents/release.agent.md index a83a7b9..44f139a 100644 --- a/.github/agents/release.agent.md +++ b/.github/agents/release.agent.md @@ -118,4 +118,4 @@ Handoffs you own: - `@#code-review` — final review before PR is opened - + diff --git a/.github/agents/tester.agent.md b/.github/agents/tester.agent.md index cab4107..4689f6b 100644 --- a/.github/agents/tester.agent.md +++ b/.github/agents/tester.agent.md @@ -126,4 +126,4 @@ Handoffs you own: - `@#incident` — incident analysis and post-mortem writing - + diff --git a/.github/instructions/git.instructions.md b/.github/instructions/git.instructions.md index 5624dc5..47cbc8d 100644 --- a/.github/instructions/git.instructions.md +++ b/.github/instructions/git.instructions.md @@ -41,4 +41,4 @@ Use these Git and release hygiene conventions in this project. 1. Prefer local verification before pushing release-impacting changes. - + diff --git a/.github/instructions/python.instructions.md b/.github/instructions/python.instructions.md index 3aafaf1..574415e 100644 --- a/.github/instructions/python.instructions.md +++ b/.github/instructions/python.instructions.md @@ -42,4 +42,4 @@ Use these Python conventions in this project. 1. Do not silence lint/type errors unless there is a documented, task-specific reason. - + diff --git a/.github/prompts/code-review.prompt.md b/.github/prompts/code-review.prompt.md index ad3f96a..e3c1aec 100644 --- a/.github/prompts/code-review.prompt.md +++ b/.github/prompts/code-review.prompt.md @@ -50,4 +50,4 @@ End with: - Biggest remaining risk: one sentence - + diff --git a/.github/skills/adr/SKILL.md b/.github/skills/adr/SKILL.md index 588879d..a1eb261 100644 --- a/.github/skills/adr/SKILL.md +++ b/.github/skills/adr/SKILL.md @@ -199,4 +199,4 @@ After writing, state the file path and summary so the architect or product role ______________________________________________________________________ - + diff --git a/.github/skills/analyse/SKILL.md b/.github/skills/analyse/SKILL.md index 34bf610..8abe845 100644 --- a/.github/skills/analyse/SKILL.md +++ b/.github/skills/analyse/SKILL.md @@ -227,4 +227,4 @@ ______________________________________________________________________ ______________________________________________________________________ - + diff --git a/.github/skills/architecture/SKILL.md b/.github/skills/architecture/SKILL.md index 003baaf..e12828b 100644 --- a/.github/skills/architecture/SKILL.md +++ b/.github/skills/architecture/SKILL.md @@ -280,4 +280,4 @@ For each significant structural decision made during this review (technology cho ______________________________________________________________________ - + diff --git a/.github/skills/cicd/SKILL.md b/.github/skills/cicd/SKILL.md index ae5ed5c..b81e10e 100644 --- a/.github/skills/cicd/SKILL.md +++ b/.github/skills/cicd/SKILL.md @@ -201,4 +201,4 @@ ______________________________________________________________________ ______________________________________________________________________ - + diff --git a/.github/skills/code-review/SKILL.md b/.github/skills/code-review/SKILL.md index 87214ed..0111f34 100644 --- a/.github/skills/code-review/SKILL.md +++ b/.github/skills/code-review/SKILL.md @@ -219,4 +219,4 @@ Confidence: [HIGH/MEDIUM/LOW — explain if not HIGH] ______________________________________________________________________ - + diff --git a/.github/skills/concise/SKILL.md b/.github/skills/concise/SKILL.md index 9f21470..41c1917 100644 --- a/.github/skills/concise/SKILL.md +++ b/.github/skills/concise/SKILL.md @@ -160,4 +160,4 @@ ______________________________________________________________________ - [ ] User confirmation/status returned in deterministic format - + diff --git a/.github/skills/consult/SKILL.md b/.github/skills/consult/SKILL.md index ae12e15..b76fdd0 100644 --- a/.github/skills/consult/SKILL.md +++ b/.github/skills/consult/SKILL.md @@ -227,4 +227,4 @@ reason: [one sentence] ______________________________________________________________________ - + diff --git a/.github/skills/container/SKILL.md b/.github/skills/container/SKILL.md index b0f99d8..e433bf4 100644 --- a/.github/skills/container/SKILL.md +++ b/.github/skills/container/SKILL.md @@ -154,4 +154,4 @@ ______________________________________________________________________ ______________________________________________________________________ - + diff --git a/.github/skills/debug/SKILL.md b/.github/skills/debug/SKILL.md index 5b4920c..7d702d3 100644 --- a/.github/skills/debug/SKILL.md +++ b/.github/skills/debug/SKILL.md @@ -279,4 +279,4 @@ Prevention: [any follow-up items] ______________________________________________________________________ - + diff --git a/.github/skills/dependency/SKILL.md b/.github/skills/dependency/SKILL.md index de1740b..b58a119 100644 --- a/.github/skills/dependency/SKILL.md +++ b/.github/skills/dependency/SKILL.md @@ -325,4 +325,4 @@ Action items (priority order): ``` - + diff --git a/.github/skills/design/SKILL.md b/.github/skills/design/SKILL.md index 8136908..dd07f30 100644 --- a/.github/skills/design/SKILL.md +++ b/.github/skills/design/SKILL.md @@ -263,4 +263,4 @@ Output a complete design document to `docs/design/design.md` or `openapi.yaml`: ______________________________________________________________________ - + diff --git a/.github/skills/docs/SKILL.md b/.github/skills/docs/SKILL.md index ebc9f46..a8a39c5 100644 --- a/.github/skills/docs/SKILL.md +++ b/.github/skills/docs/SKILL.md @@ -167,4 +167,4 @@ Skipped (n/a): ______________________________________________________________________ - + diff --git a/.github/skills/explore/SKILL.md b/.github/skills/explore/SKILL.md index d91d4a0..3e39b84 100644 --- a/.github/skills/explore/SKILL.md +++ b/.github/skills/explore/SKILL.md @@ -241,4 +241,4 @@ Stack: [language, framework, runtime versions] ______________________________________________________________________ - + diff --git a/.github/skills/guardrails/SKILL.md b/.github/skills/guardrails/SKILL.md index 00f9544..39d9368 100644 --- a/.github/skills/guardrails/SKILL.md +++ b/.github/skills/guardrails/SKILL.md @@ -77,4 +77,4 @@ Explicitly ask to "disable guardrails". ______________________________________________________________________ - + diff --git a/.github/skills/incident/SKILL.md b/.github/skills/incident/SKILL.md index 132f25c..738f8da 100644 --- a/.github/skills/incident/SKILL.md +++ b/.github/skills/incident/SKILL.md @@ -325,4 +325,4 @@ Status: [Draft — ready for team review] ``` - + diff --git a/.github/skills/inspect/SKILL.md b/.github/skills/inspect/SKILL.md index 3872141..89fe02e 100644 --- a/.github/skills/inspect/SKILL.md +++ b/.github/skills/inspect/SKILL.md @@ -165,4 +165,4 @@ ______________________________________________________________________ ______________________________________________________________________ - + diff --git a/.github/skills/migrate/SKILL.md b/.github/skills/migrate/SKILL.md index bcf01e1..2653d46 100644 --- a/.github/skills/migrate/SKILL.md +++ b/.github/skills/migrate/SKILL.md @@ -337,4 +337,4 @@ Pre-deploy checklist: ``` - + diff --git a/.github/skills/onboard/SKILL.md b/.github/skills/onboard/SKILL.md index dc58fc6..1504a2f 100644 --- a/.github/skills/onboard/SKILL.md +++ b/.github/skills/onboard/SKILL.md @@ -321,4 +321,4 @@ Gaps remaining (if any): ``` - + diff --git a/.github/skills/openapi/SKILL.md b/.github/skills/openapi/SKILL.md index 3f12c20..807d2ce 100644 --- a/.github/skills/openapi/SKILL.md +++ b/.github/skills/openapi/SKILL.md @@ -414,4 +414,4 @@ Summary: [N critical, N warnings, N info] `$ref` for all reusable schemas, and validate it passes linting. - + diff --git a/.github/skills/performance/SKILL.md b/.github/skills/performance/SKILL.md index b25b7a4..5296893 100644 --- a/.github/skills/performance/SKILL.md +++ b/.github/skills/performance/SKILL.md @@ -258,4 +258,4 @@ ______________________________________________________________________ ______________________________________________________________________ - + diff --git a/.github/skills/pr/SKILL.md b/.github/skills/pr/SKILL.md index 373f356..ed7ae1d 100644 --- a/.github/skills/pr/SKILL.md +++ b/.github/skills/pr/SKILL.md @@ -140,4 +140,4 @@ CI/CD will now: ______________________________________________________________________ - + diff --git a/.github/skills/refactor/SKILL.md b/.github/skills/refactor/SKILL.md index a8e7a13..455755d 100644 --- a/.github/skills/refactor/SKILL.md +++ b/.github/skills/refactor/SKILL.md @@ -385,4 +385,4 @@ Behavior changed: No ``` - + diff --git a/.github/skills/release-notes/SKILL.md b/.github/skills/release-notes/SKILL.md index 113cf68..1b0b388 100644 --- a/.github/skills/release-notes/SKILL.md +++ b/.github/skills/release-notes/SKILL.md @@ -159,4 +159,4 @@ Keep existing entries intact. ______________________________________________________________________ - + diff --git a/.github/skills/requirements/SKILL.md b/.github/skills/requirements/SKILL.md index e72b42a..e1eaf1a 100644 --- a/.github/skills/requirements/SKILL.md +++ b/.github/skills/requirements/SKILL.md @@ -219,4 +219,4 @@ After writing, summarize what was decided so the architect role can start. ______________________________________________________________________ - + diff --git a/.github/skills/security/SKILL.md b/.github/skills/security/SKILL.md index c008a32..a374ada 100644 --- a/.github/skills/security/SKILL.md +++ b/.github/skills/security/SKILL.md @@ -295,4 +295,4 @@ Scope: [full/diff/dependency/config] ______________________________________________________________________ - + diff --git a/.github/skills/verify/SKILL.md b/.github/skills/verify/SKILL.md index fcc29d6..adcb7e0 100644 --- a/.github/skills/verify/SKILL.md +++ b/.github/skills/verify/SKILL.md @@ -282,4 +282,4 @@ scope: [path/component/full] ______________________________________________________________________ - + diff --git a/.github/skills/vision/SKILL.md b/.github/skills/vision/SKILL.md index cbf9b5c..ab0685d 100644 --- a/.github/skills/vision/SKILL.md +++ b/.github/skills/vision/SKILL.md @@ -208,4 +208,4 @@ Present as: "Overall assessment: [READY/NEEDS REVISION/SCOPE CHANGE] because [1- ______________________________________________________________________ - + diff --git a/.github/vstack.json b/.github/vstack.json index 1f6c2db..ea78985 100644 --- a/.github/vstack.json +++ b/.github/vstack.json @@ -1,6 +1,6 @@ { - "vstack_version": "0.0.0.post3.dev0+df3fe6e", - "installed_at": "2026-04-20T22:37:59.699083+00:00", + "vstack_version": "1.2.5", + "installed_at": "2026-04-21T21:51:23.985830+00:00", "artifacts": { "skills": [ { diff --git a/CHANGELOG.md b/CHANGELOG.md index 73a617e..efa18b7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,57 @@ # Changelog +## 1.2.6 - 2026-04-22 + +DX and onboarding quality release. + +### Added in 1.2.6 + +- Added GitHub Discussion templates for onboarding and adoption feedback: + - `onboarding-feedback` + - `first-run-report` + - `model-cost-feedback` +- Added team setup guidance in `README.md` with project-first install flow and expected outcomes. +- Added explicit expected output examples for first install validation in `README.md`. +- Added a troubleshooting decision flowchart in `README.md`. + +### Changed in 1.2.6 + +- Restructured `README.md` for faster onboarding with clearer quick paths, role usage guidance, and troubleshooting navigation. +- Updated architect and product agent template model ordering and regenerated installed agent artifacts. +- Updated generated artifact metadata and aligned generation tests with current template output. + +## 1.2.5 - 2026-04-21 + +CI dependency maintenance release. + +### Changed in 1.2.5 + +- GitHub Actions: bumped `actions/checkout` from v5 to v6. + +## 1.2.4 - 2026-04-21 + +CI dependency maintenance release. + +### Changed in 1.2.4 + +- GitHub Actions: bumped `actions/upload-artifact` from v4 to v7. + +## 1.2.3 - 2026-04-21 + +Release workflow dependency maintenance. + +### Changed in 1.2.3 + +- GitHub Actions: bumped `softprops/action-gh-release` from v2 to v3. + +## 1.2.2 - 2026-04-21 + +Security workflow dependency maintenance. + +### Changed in 1.2.2 + +- GitHub Actions: bumped `trufflesecurity/trufflehog` from `3.88.2` to `3.94.3`. + ## 1.2.1 - 2026-04-21 README rendering fix release. diff --git a/README.md b/README.md index 1bdfa77..99ed881 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,17 @@ vstack -[![Python](https://img.shields.io/badge/python-3.11--3.14-0B8A6F)](pyproject.toml) -[![Verify](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/verify.yml?branch=main&label=verify&color=1D6FA5)](https://github.com/eschaar/vstack/actions/workflows/verify.yml) -[![Security](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/security.yml?branch=main&label=security&color=B15E00)](https://github.com/eschaar/vstack/actions/workflows/security.yml) -[![Runtime](https://img.shields.io/badge/runtime-stdlib%20only-5B6C8F)](pyproject.toml) -[![License](https://img.shields.io/github/license/eschaar/vstack?color=5F7A1F)](LICENSE) +[![Python version](https://img.shields.io/badge/python-3.11--3.14-0B8A6F "Supported Python versions")](pyproject.toml) +[![Verify status](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/verify.yml?branch=main&label=verify&color=1D6FA5 "Build and test status")](https://github.com/eschaar/vstack/actions/workflows/verify.yml) +[![Security checks](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/security.yml?branch=main&label=security&color=B15E00 "Security workflow status")](https://github.com/eschaar/vstack/actions/workflows/security.yml) +[![Runtime: stdlib only](https://img.shields.io/badge/runtime-stdlib%20only-5B6C8F "No runtime dependencies")](pyproject.toml) +[![License: MIT](https://img.shields.io/github/license/eschaar/vstack?color=5F7A1F "Project license")](LICENSE) +[![GitHub Discussions](https://img.shields.io/badge/discussions-ask%20%26%20share-blueviolet?logo=github "GitHub Discussions")](https://github.com/eschaar/vstack/discussions) +> **The VS Code-native AI workflow system for backend engineering.** + vstack is a VS Code-native AI engineering workflow system for backend services, libraries, APIs, and adjacent platform work. It installs structured agents, skills, instructions, and prompts into `.github/` so GitHub Copilot Agent Mode @@ -26,7 +29,7 @@ but was rebuilt around a template-driven, VS Code-first workflow model. ______________________________________________________________________ -## Why vstack +## ❔ Why vstack - Fixed role model with explicit ownership boundaries - Template-driven install model from `src/vstack/_templates/` @@ -36,119 +39,263 @@ ______________________________________________________________________ ______________________________________________________________________ -## Quickstart +## 🧭 Quick navigation + +For new users: + +- Quickstart +- Quick check +- Using vstack in Copilot Agent Mode +- Try it now +- Troubleshooting -Requires **Python 3.11-3.14**. +For experienced users: -### Distribution status +- Role summary +- Example usage +- All vstack CLI commands +- Workflow +- Development +- CI and Release Automation -vstack is not published to PyPI yet. The current workflow is source-based usage -from this repository. +### ⚡ Quick paths + +#### New user path (2 minutes) + +```bash +pipx install git+https://github.com/eschaar/vstack.git +vstack install --target /path/to/your/project +vstack validate +``` + +Then in Copilot Agent Mode: + +```text +@tester /verify Check this repository and summarize findings +``` -### 1. Clone and install the development environment +#### Power user path (30 seconds) + +```bash +vstack install --target /path/to/your/project && vstack verify --target /path/to/your/project +``` + +Then jump straight into your role workflow: + +```text +@architect Review contracts in src/api/ +@engineer /code-review +@tester /security +``` + +```mermaid +flowchart LR + A[Install CLI] --> B[Install artifacts per repo] + B --> C[Validate setup] + C --> D[Run @tester /verify] + D --> E[Role-based flow] +``` + +______________________________________________________________________ + +## 🚀 Quickstart + +> New here? Start with `pipx install ...`, then run `vstack install --target ...`, then try `@tester /verify` in Copilot Agent Mode. + +### ⚡ Install with pipx (recommended) + +You can install and use vstack directly without cloning: + +```bash +pipx install git+https://github.com/eschaar/vstack.git +``` + +Afterwards, the `vstack` command is available everywhere: + +```bash +# Recommended: install vstack artifacts per project/repository +vstack install --target /path/to/your/project + +# Optional: install profile-wide defaults for all VS Code projects +vstack install --global +``` + +### 🐙 Alternative: manual clone and install ```bash git clone git@github.com:eschaar/vstack.git cd vstack poetry install +poetry run vstack install --target /path/to/your/project ``` -### 2. Install the artifacts +### 🤝 Team setup (recommended for teams) + +Use repository-scoped installation so every contributor and CI run uses the same agent setup. -From the checked-out repository, install artifacts into one repository: +1. Install artifacts into the repository. +1. Commit the generated `.github/` artifacts. +1. Require `verify.yml` and `security.yml` checks before merge. ```bash -poetry run vstack install --target /path/to/your/project +# From your repository root +vstack install --target /path/to/your/project +git add .github +git commit -m "chore: install vstack artifacts" ``` -Or install into your VS Code profile so the artifacts are available across projects: +Expected outcome: + +- Teammates get the same agents and skills after `git pull`. +- CI validates the same repository-level setup. + +## 🚦 Quick check: Is vstack working? + +After install, run: ```bash -poetry run vstack install --global +vstack --version +vstack validate +``` + +If you see the version and no errors, your install is working. + +Expected output (example): + +```text +vstack 1.2.5 +Validation passed: no unresolved template tokens ``` -If you prefer, you can also run the package entrypoint after an editable install in -your active environment. +### First use example -### 3. Open Copilot Agent Mode and invoke a role +Open Copilot Agent Mode and run: ```text -@product Review my plan for a payments service -@architect Review the API contracts in src/api/ -@tester /security Audit the authentication module +@tester /verify Check this repository and summarize findings ``` -No extra VS Code settings are required. Installed role agents are discovered from -workspace `.github/agents/` and from the VS Code user profile. +You should receive a concise verification summary for your current workspace. + +### 💬 Using vstack in Copilot Agent Mode + +For new users (first 5 minutes): + +- Follow the 3-step flow below exactly once. +- Start with `@tester /verify` to confirm the setup works. + +For experienced users: + +- Use direct role invocation (`@product`, `@architect`, `@engineer`, etc.) for context-rich execution. +- Use direct skills (`/verify`, `/security`, `/code-review`) for focused, faster runs. + +1. **Open Copilot Chat** + - Use `Ctrl+Shift+I` (Windows/Linux) or `Cmd+Shift+I` (Mac), or click the Copilot icon in the sidebar. +1. **Switch to Agent Mode** + - In the Copilot Chat panel, change the mode selector from `Ask` to `Agent`. +1. **Invoke a role agent** + - Type e.g.: + ```text + @product Review my plan for a payments service + @architect Review the API contracts in src/api/ + @tester /security Audit the authentication module + ``` + - The `@role` prefix selects the corresponding agent. You can add a skill command (e.g. `/security`) after the agent for a focused procedure. + +**How it works:** + +- When you use `@role` (e.g. `@tester`), the agent loads all relevant skills and instructions for that role. Skills are discovered automatically and routed by the agent based on your request. +- If you use only a skill (e.g. `/verify`), a prompt, or an instruction (without an explicit agent), VS Code Copilot Agent Mode will use the default agent for the context (typically `@tester` for verification-related skills, or the most relevant role based on your workspace and prompt). This means you can use `/verify`, `/security`, or other skills directly, and they will work even without specifying an agent. +- Agents are not invoked automatically; you must use the `@role` prefix to select a specific agent and role context. Skills, prompts, and instructions are always auto-discovered and available in the background. +- For maximum control and clarity, always specify the agent (`@role`) when you want a particular role's framing, default behavior, or skill routing. ______________________________________________________________________ -## Flow +#### 🧩 Visual: How agents, skills, instructions, and prompts interact ```mermaid -flowchart LR - A[Product intent] --> B["@product"] - B --> C["@architect"] - C --> D["@designer"] - D --> E["@engineer"] - E --> F["@tester"] - F --> G["@release"] - B -. focused procedure .-> H["requirements or vision"] - F -. focused procedure .-> I["verify, security, performance"] +flowchart TD + subgraph "VS Code Copilot Agent Mode" + A["User prompt"] + B["Agent (e.g. @tester)"] + C["Skills (e.g. /verify, /security)"] + D["Instructions"] + E["Prompts"] + end + A --> B + B --> C + B --> D + B --> E + C -.-> B + E -.-> B + D -.-> B ``` -The exact deliverable can be a microservice, API, package, library, app, or broader -system. The product vision defines scope; vstack defines how the work is carried. +**Legend:** + +- **Agents** (`@role`): Main entrypoint, routes and coordinates work. +- **Skills** (`/skill`): Reusable procedures, invoked by agents or directly. +- **Instructions**: Baseline policies, always loaded by agents. +- **Prompts**: Reusable prompt artifacts, used as needed. ______________________________________________________________________ -## Building Blocks +## 🧪 Try it now -| Artifact type | Purpose | Typical invocation | -| ------------- | ---------------------------------------------------------- | ---------------------- | -| Agents | Main operating interface for role-based work | `@product`, `@tester` | -| Skills | Reusable task procedures | `/verify`, `/security` | -| Instructions | Baseline policy and repo guardrails | auto-loaded by context | -| Prompts | Reusable prompt artifacts where direct prompting is useful | explicit prompt use | +Open Copilot Agent Mode and enter: -Boundary rule: +```text +@tester /verify Check this repo +``` -- Policies belong in instructions. -- Procedures belong in skills. +You should see a verification summary for your current project. -See [docs/design/instructions.md](docs/design/instructions.md), -[docs/design/skills.md](docs/design/skills.md), and -[docs/architecture/adr/013-instructions-vs-skills-boundary.md](docs/architecture/adr/013-instructions-vs-skills-boundary.md). +______________________________________________________________________ + +## 🧑‍💻 Role summary + +| Role | Emoji | Invocation | Primary areas | Example invocation | +| --------- | ----- | ------------ | ------------------------------------------------------- | ------------------------------------- | +| Product | 🧑‍💼 | `@product` | Vision, requirements, onboarding, docs | `@product Review my plan` | +| Architect | 🏗️ | `@architect` | Architecture, ADRs | `@architect Review the API contracts` | +| Designer | 🎨 | `@designer` | Service design, OpenAPI, DX review | `@designer Review the OpenAPI spec` | +| Engineer | 🛠️ | `@engineer` | Implementation, debugging, refactoring, dependency work | `@engineer /code-review` | +| Tester | 🧪 | `@tester` | Verification, security, incident review, performance | `@tester /verify` | +| Release | 🚀 | `@release` | Release notes, PR creation, release gating | `@release Prepare release notes` | + +### Role-to-skill mapping + +| Role | Invocation | Primary skills | Default concise mode | +| --------- | ------------ | ------------------------------------------------------- | -------------------- | +| product | `@product` | vision, requirements, onboard, docs | compact | +| architect | `@architect` | architecture, adr | normal | +| designer | `@designer` | design, openapi, consult, docs | compact | +| engineer | `@engineer` | code-review, debug, refactor, migrate, dependency, docs | compact | +| tester | `@tester` | verify, inspect, security, incident, dependency, docs | ultra | +| release | `@release` | release-notes, pr, docs | compact | ______________________________________________________________________ -## Roles +> ℹ️ **Tip:** Use the `@role` prefix for full context and best results. Skills like `/verify` also work directly, but explicit roles give you more control. -| Role | Invocation | Primary areas | -| --------- | ------------ | ------------------------------------------------------- | -| product | `@product` | vision, requirements, onboarding, docs | -| architect | `@architect` | architecture, ADRs | -| designer | `@designer` | service design, OpenAPI, DX review | -| engineer | `@engineer` | implementation, debugging, refactoring, dependency work | -| tester | `@tester` | verification, security, incident review, performance | -| release | `@release` | release notes, PR creation, release gating | +______________________________________________________________________ -Full skill index: [docs/design/skills.md](docs/design/skills.md) +> 💡 **Pro tip:** Try combining agents and skills for focused tasks, e.g. `@tester /security` or `@engineer /code-review`. ______________________________________________________________________ -## Example Usage +## 📝 Example usage ### Idea to release -1. `@product` to lock requirements and success criteria -1. `@architect` to define service boundaries and ADRs -1. `@designer` to define APIs, schemas, and flows -1. `@engineer` to implement -1. `@tester` to verify behavior and risk -1. `@release` to prepare the release path +1. `@product` to lock requirements and success criteria. +1. `@architect` to define service boundaries and ADRs. +1. `@designer` to define APIs, schemas, and flows. +1. `@engineer` to implement. +1. `@tester` to verify behavior and risk. +1. `@release` to prepare release artifacts and PR flow. -### Direct skill usage when you want a focused tool +### Direct skill usage | Goal | Agent invocation | Optional direct skill | | ------------------- | ---------------- | --------------------- | @@ -160,84 +307,225 @@ ______________________________________________________________________ | Security audit | `@tester` | `/security` | | Performance check | `@tester` | `/performance` | -You can also force a skill through an agent when you want the role framing and the -procedure together, for example `@tester /security`. - -### Subagent pattern - -The product agent can invoke other agents as subagents to orchestrate a complete flow: +### Subagent orchestration pattern ```text @product Deliver a requirements-to-release plan for a new payments service ``` -Typical downstream path: +Typical downstream path: `@product` -> `@architect` -> `@designer` -> `@engineer` -> `@tester` -> `@release`. + +______________________________________________________________________ + +## ❓ FAQ -- `@product` -> requirements -- `@architect` -> architecture -- `@designer` -> API contract -- `@engineer` -> implementation -- `@tester` -> verification -- `@release` -> release gating +**Q: Why don't I see agents in Copilot?** +A: In a specific repository, run `vstack install --target /path/to/your/project` (or run `vstack install` from the repo root), then reload VS Code. Use `--global` only when you want profile-wide defaults. + +**Q: Which Python version do I need?** +A: Python 3.11–3.14 (see badges above). + +**Q: How do I reset the install?** +A: For one repository, run `vstack uninstall --target /path/to/your/project` and then reinstall with `vstack install --target /path/to/your/project`. Use `--global` only for profile-wide defaults. + +**Q: Where can I ask questions or give feedback?** +A: [Start a discussion or ask a question here.](https://github.com/eschaar/vstack/discussions) ______________________________________________________________________ -## Using vstack in Copilot Agent Mode +## 🧹 Uninstall / Reset -### 1. Open Copilot Chat +To remove vstack artifacts from your project or profile, use the CLI: + +```bash +# Uninstall vstack artifacts from your current project +vstack uninstall --target /path/to/your/project -Use `Ctrl+Shift+I` or `Cmd+Shift+I`, or click the Copilot icon in the sidebar. +# Uninstall vstack artifacts from your global VS Code profile +vstack uninstall --global +``` -### 2. Switch to Agent Mode +To remove vstack itself (the CLI): -In the Copilot Chat panel, switch the mode selector from `Ask` to `Agent`. +```bash +# If installed with pipx +pipx uninstall vstack -### 3. Invoke a role +# If installed with pip in an active environment +pip uninstall vstack -```text -@product Review my plan for the new payments service -@architect Review the API contracts in src/api/ -@tester -@tester Run a security audit +# If installed from a local clone for development +rm -rf .venv ``` -Each role agent uses the appropriate skills automatically. You can also ask a role -to use a specific skill: +You can also manually remove any leftover `.github/agents`, `.github/skills`, etc. if needed. -```text -@tester use the verify skill with regression focus and report findings -@tester run the security skill on the auth module +## ⚡ Essential CLI commands + +```bash +vstack --version # Show vstack version +vstack validate # Validate current vstack install +vstack install --target . # Install vstack artifacts into current project +vstack install --global # Install vstack artifacts globally +vstack uninstall --target . # Uninstall vstack artifacts from current project +vstack uninstall --global # Uninstall vstack artifacts globally ``` -### 4. Available roles and their primary skills +______________________________________________________________________ -| Role | Invocation | Primary skills | Default concise mode | -| --------- | ------------ | ------------------------------------------------------- | -------------------- | -| product | `@product` | vision, requirements, onboard, docs | compact | -| architect | `@architect` | architecture, adr | normal | -| designer | `@designer` | design, openapi, consult, docs | compact | -| engineer | `@engineer` | code-review, debug, refactor, migrate, dependency, docs | compact | -| tester | `@tester` | verify, inspect, security, incident, dependency, docs | ultra | -| release | `@release` | release-notes, pr, docs | compact | +## 📖 All vstack CLI commands + +| Command | Description | +| ------------------------------- | ---------------------------------------------------- | +| `vstack --version` | Show vstack version | +| `vstack validate` | Validate vstack install and check for issues | +| `vstack verify` | Verify source templates and/or installed output | +| `vstack verify --target DIR` | Verify installed artifacts in DIR/.github | +| `vstack verify --global` | Verify artifacts in your VS Code global profile | +| `vstack install --target DIR` | Install vstack artifacts into a project | +| `vstack install --global` | Install vstack artifacts into your VS Code profile | +| `vstack install --dry-run` | Preview install actions without writing files | +| `vstack uninstall --target DIR` | Uninstall vstack artifacts from a project | +| `vstack uninstall --global` | Uninstall vstack artifacts from your VS Code profile | +| `vstack uninstall` | Uninstall from the current directory default target | ______________________________________________________________________ -## Model Guidance +## 🤝 How to contribute -| Use case | Recommended model | -| ------------------------ | ------------------------------------ | -| `@product`, `@architect` | Claude Sonnet 4.6 or Claude Opus 4.6 | -| `@tester`, `@engineer` | Claude Sonnet 4.6 | -| `@release` | Claude Sonnet 4.6 | -| Complex debugging | Claude Opus 4.6 or GPT-5.3 Codex | -| Quick tasks | Any model | +Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, code style, and how to get started. -Claude Sonnet 4.6 is the best balance of speed, quality, and cost for most runs. -Use Claude Opus 4.6 for architecture reviews or complex debugging. +______________________________________________________________________ + +## 🛠️ Troubleshooting + +Quick index: +[Installation and environment](#installation-and-environment) · [Copilot Agent Mode](#copilot-agent-mode) · [CI parity and badges](#ci-parity-and-badges) · [VS Code search noise](#vs-code-search-noise) + +```mermaid +flowchart TD + A[Problem observed] --> B{Install or environment issue?} + B -->|Yes| C[Check pipx/poetry/python version] + B -->|No| D{Agents visible in Copilot?} + D -->|No| E[Run vstack install --target and reload VS Code] + D -->|Yes| F{CI mismatch or badge confusion?} + F -->|CI mismatch| G[Run make bootstrap then make check or make ci] + F -->|Badge no status| H[Verify PR-based workflow trigger] + F -->|Search noisy| I[Set search.exclude and files.watcherExclude] + C --> J[Resolved] + E --> J + G --> J + H --> J + I --> J +``` + +### Installation and environment + +- Issue: `pipx: command not found` + Action: Install pipx with `pip install --user pipx`. +- Issue: `poetry: command not found` + Action: Follow the Poetry install guide at [https://python-poetry.org/docs/#installation](https://python-poetry.org/docs/#installation). +- Issue: `Python version not supported` + Action: Use Python 3.11-3.14. +- Issue: `Permission denied` during install or uninstall + Action: Check directory permissions and rerun with appropriate privileges. +- Issue: `Could not detect VS Code user data directory` + Action: Run with an explicit target, for example `vstack install --target ~/.config/Code/User`. + +### Copilot Agent Mode + +- Issue: Agents do not appear in one repository + Action: Run `vstack install --target /path/to/your/project` (or run `vstack install` from that repository root), then reload VS Code. +- Issue: Agents appear in one repository but not another + Action: Install per repository with `vstack install --target ...` in each repo, or use `vstack install --global` for profile-wide defaults. +- Issue: Agents still do not appear + Action: Confirm templates exist under `src/vstack/_templates/agents/`, then run `Developer: Reload Window` in VS Code. +- Issue: Agent does not execute actions + Action: Make sure Copilot is in Agent Mode, not Ask or Edit mode. + +### CI parity and badges + +- Issue: Checks pass in CI but fail locally + Action: Run `make bootstrap` once per clone, then run `make check`. +- Issue: Need to mirror the CI quality gate locally + Action: Run `make ci`. +- Issue: Verify or Security badge shows no status + Action: These workflows are PR-based, so main may not always show a latest status. + +### VS Code search noise + +- Issue: Search results are noisy + Action: Exclude `.venv`, `venv`, `env`, `node_modules`, `__pycache__`, `dist`, `build`, and `.git`. +- Issue: Search still feels slow or cluttered + Action: Configure both `search.exclude` and `files.watcherExclude` in VS Code settings. ______________________________________________________________________ -## Tips +## 🔄 Workflow + +```mermaid +flowchart LR + A[Product intent] --> B["@product"] + B --> C["@architect"] + C --> D["@designer"] + D --> E["@engineer"] + E --> F["@tester"] + F --> G["@release"] + B -. focused procedure .-> H["requirements or vision"] + F -. focused procedure .-> I["verify, security, performance"] +``` + +The exact deliverable can be a microservice, API, package, library, app, or broader +system. The product vision defines scope; vstack defines how the work is carried. + +______________________________________________________________________ + +## 🧱 Building Blocks + +| Artifact type | Purpose | Typical invocation | +| ------------- | ---------------------------------------------------------- | ---------------------- | +| Agents | Main operating interface for role-based work | `@product`, `@tester` | +| Skills | Reusable task procedures | `/verify`, `/security` | +| Instructions | Baseline policy and repository guardrails | auto-loaded by context | +| Prompts | Reusable prompt artifacts where direct prompting is useful | explicit prompt use | + +Boundary rule: + +- Policies belong in instructions. +- Procedures belong in skills. + +See [docs/design/instructions.md](docs/design/instructions.md), +[docs/design/skills.md](docs/design/skills.md), and +[docs/architecture/adr/013-instructions-vs-skills-boundary.md](docs/architecture/adr/013-instructions-vs-skills-boundary.md). + +______________________________________________________________________ + +## 🧠 Model Guidance + +| Use case | Recommended model floor (or higher) | +| ------------------------ | ---------------------------------------------------- | +| `@product`, `@architect` | Claude Sonnet 4.6+, GPT-5.3-Codex+, Claude Opus 4.6+ | +| `@tester`, `@engineer` | Claude Sonnet 4.6+ or GPT-5.3-Codex+ | +| `@release` | Claude Sonnet 4.6+ | +| Complex debugging | GPT-5.3-Codex+ or Claude Opus 4.6+ | +| Quick tasks | Any model with tool and agent-mode support | + +Why these version floors: + +- Reliable tool use and structured instruction following in Agent Mode. +- Better multi-step planning and stronger handling of long procedural prompts. +- Better compatibility with subagent-style orchestration and role handoffs. +- More stable output quality for repository-scale reviews and verification loops. + +Practical cost guidance: + +- Use Claude Sonnet 4.6+ as the default for most runs (best speed/cost balance). +- Use GPT-5.3-Codex+ for deep code reasoning, debugging, and implementation-heavy tasks. +- Use Claude Opus 4.6+ selectively for high-ambiguity architecture tradeoffs where the extra cost is justified. + +______________________________________________________________________ + +## 💡 Practical Tips ### Give the agent project context @@ -280,7 +568,11 @@ use `normal` regardless of active mode. ______________________________________________________________________ -## Development +More info: [docs/product/roadmap.md](docs/product/roadmap.md), [docs/architecture/architecture.md](docs/architecture/architecture.md) + +______________________________________________________________________ + +## 🛠️ Development Requires **Poetry** and **Python 3.11-3.14**. @@ -334,7 +626,7 @@ poetry run vstack install ______________________________________________________________________ -## Repository Structure +## 🗂️ Repository Structure ```text vstack/ @@ -359,7 +651,7 @@ vstack/ ______________________________________________________________________ -## CI and Release Automation +## 🚦 CI and Release Automation | Workflow | Trigger | Purpose | | -------------- | ----------------------------- | ----------------------------------------------------------- | @@ -384,56 +676,7 @@ Recommended branch protection for `main`: ______________________________________________________________________ -## Troubleshooting - -### Agents are not appearing - -1. Run `vstack install --global` or `poetry run vstack install --global` -1. Confirm the templates exist under `src/vstack/_templates/agents/` -1. Reload VS Code with `Developer: Reload Window` - -### Agent is not running commands - -Make sure Copilot is in Agent Mode, not Ask or Edit mode. - -### Best-practice local workflow - -1. Run `make bootstrap` once per machine or clone. -1. Run `make check` before every commit. -1. Run `make ci` when you want to mirror the main quality gate locally. - -### Search results are noisy - -Use workspace-local exclusions in VS Code: - -```json -{ - "search.exclude": { - "**/.venv": true, - "**/venv": true, - "**/env": true, - "**/node_modules": true, - "**/__pycache__": true, - "**/dist": true, - "**/build": true, - "**/.git": true - }, - "files.watcherExclude": { - "**/.venv/**": true, - "**/venv/**": true, - "**/env/**": true, - "**/node_modules/**": true, - "**/__pycache__/**": true, - "**/dist/**": true, - "**/build/**": true, - "**/.git/**": true - } -} -``` - -______________________________________________________________________ - -## Further Reading +## 📚 Further Reading - [docs/architecture/architecture.md](docs/architecture/architecture.md) - [docs/design/design.md](docs/design/design.md) @@ -444,6 +687,6 @@ ______________________________________________________________________ ______________________________________________________________________ -## License +## 📄 License MIT. See [LICENSE](LICENSE). diff --git a/docs/architecture/adr/001-vscode-native-variant.md b/docs/architecture/adr/001-vscode-native-variant.md index affee1a..7c532c5 100644 --- a/docs/architecture/adr/001-vscode-native-variant.md +++ b/docs/architecture/adr/001-vscode-native-variant.md @@ -13,7 +13,7 @@ automation — unsuitable for backend/microservice workflows where browser autom irrelevant. VS Code + GitHub Copilot is a dominant development environment that lacked an equivalent -system. Modern models (Claude Sonnet/Opus 4.6, GPT-5.3 Codex) can execute multi-step +system. Modern models (Claude Sonnet/Opus 4.6+, GPT-5.3 Codex) can execute multi-step workflows via VS Code Agent Mode. ## decision diff --git a/src/vstack/_templates/agents/architect/config.yaml b/src/vstack/_templates/agents/architect/config.yaml index 7e76404..11b11d8 100644 --- a/src/vstack/_templates/agents/architect/config.yaml +++ b/src/vstack/_templates/agents/architect/config.yaml @@ -18,9 +18,9 @@ tools: - todo - agent model: - - Claude Opus 4.6 (copilot) - Claude Sonnet 4.6 (copilot) - GPT-5.3-Codex (copilot) + - Claude Opus 4.7 (copilot) agents: ["*"] handoffs: - label: Continue to design diff --git a/src/vstack/_templates/agents/product/config.yaml b/src/vstack/_templates/agents/product/config.yaml index 60fe874..88ac033 100644 --- a/src/vstack/_templates/agents/product/config.yaml +++ b/src/vstack/_templates/agents/product/config.yaml @@ -17,8 +17,8 @@ tools: - agent model: - Claude Sonnet 4.6 (copilot) - - Claude Opus 4.6 (copilot) - GPT-5.3-Codex (copilot) + - Claude Opus 4.7 (copilot) agents: ["*"] handoffs: - label: Continue to architecture diff --git a/tests/vstack/agents/test_generation.py b/tests/vstack/agents/test_generation.py index 896fe15..ec98d18 100644 --- a/tests/vstack/agents/test_generation.py +++ b/tests/vstack/agents/test_generation.py @@ -26,9 +26,9 @@ def test_architect_agent_includes_model_and_handoffs(self, tmp_path: Path) -> No assert parsed.metadata.get("name") == "architect" assert parsed.metadata.get("model") == [ - "Claude Opus 4.6 (copilot)", "Claude Sonnet 4.6 (copilot)", "GPT-5.3-Codex (copilot)", + "Claude Opus 4.7 (copilot)", ] handoffs = parsed.metadata.get("handoffs") From 2cb8a8754ee03542e13acd2ea8c19a88600d50d9 Mon Sep 17 00:00:00 2001 From: Erik Schaareman Date: Wed, 22 Apr 2026 00:38:05 +0200 Subject: [PATCH 2/2] feat(ci): add PyPI publish job with OIDC trusted publishing --- .github/agents/architect.agent.md | 2 +- .github/agents/designer.agent.md | 2 +- .github/agents/engineer.agent.md | 2 +- .github/agents/product.agent.md | 2 +- .github/agents/release.agent.md | 2 +- .github/agents/tester.agent.md | 2 +- .github/instructions/git.instructions.md | 2 +- .github/instructions/python.instructions.md | 2 +- .github/prompts/code-review.prompt.md | 2 +- .github/skills/adr/SKILL.md | 2 +- .github/skills/analyse/SKILL.md | 2 +- .github/skills/architecture/SKILL.md | 2 +- .github/skills/cicd/SKILL.md | 2 +- .github/skills/code-review/SKILL.md | 2 +- .github/skills/concise/SKILL.md | 2 +- .github/skills/consult/SKILL.md | 2 +- .github/skills/container/SKILL.md | 2 +- .github/skills/debug/SKILL.md | 2 +- .github/skills/dependency/SKILL.md | 2 +- .github/skills/design/SKILL.md | 2 +- .github/skills/docs/SKILL.md | 2 +- .github/skills/explore/SKILL.md | 2 +- .github/skills/guardrails/SKILL.md | 2 +- .github/skills/incident/SKILL.md | 2 +- .github/skills/inspect/SKILL.md | 2 +- .github/skills/migrate/SKILL.md | 2 +- .github/skills/onboard/SKILL.md | 2 +- .github/skills/openapi/SKILL.md | 2 +- .github/skills/performance/SKILL.md | 2 +- .github/skills/pr/SKILL.md | 2 +- .github/skills/refactor/SKILL.md | 2 +- .github/skills/release-notes/SKILL.md | 2 +- .github/skills/requirements/SKILL.md | 2 +- .github/skills/security/SKILL.md | 2 +- .github/skills/verify/SKILL.md | 2 +- .github/skills/vision/SKILL.md | 2 +- .github/vstack.json | 4 +-- .github/workflows/release.yml | 31 ++++++++++++++++++--- CHANGELOG.md | 9 +++--- README.md | 28 +++++++++++++++---- tests/vstack/cli/test_commands.py | 6 ++-- 41 files changed, 96 insertions(+), 54 deletions(-) diff --git a/.github/agents/architect.agent.md b/.github/agents/architect.agent.md index 05ae1e2..b7f69e2 100644 --- a/.github/agents/architect.agent.md +++ b/.github/agents/architect.agent.md @@ -120,4 +120,4 @@ Handoffs you own: - `@#analyse` — impact analysis, tradeoffs, feasibility - + diff --git a/.github/agents/designer.agent.md b/.github/agents/designer.agent.md index 127197f..adc6386 100644 --- a/.github/agents/designer.agent.md +++ b/.github/agents/designer.agent.md @@ -131,4 +131,4 @@ Handoffs you own: - `@#openapi` — OpenAPI 3.1 spec writing and review - + diff --git a/.github/agents/engineer.agent.md b/.github/agents/engineer.agent.md index 7d78676..963b57c 100644 --- a/.github/agents/engineer.agent.md +++ b/.github/agents/engineer.agent.md @@ -121,4 +121,4 @@ Only delegate when workstreams are genuinely independent. - `@#incident` — incident analysis and post-mortem writing - + diff --git a/.github/agents/product.agent.md b/.github/agents/product.agent.md index 43166a4..d74a59f 100644 --- a/.github/agents/product.agent.md +++ b/.github/agents/product.agent.md @@ -122,4 +122,4 @@ Handoffs you own: - `@#onboard` — contributor onboarding guide generation - + diff --git a/.github/agents/release.agent.md b/.github/agents/release.agent.md index 44f139a..d712d1e 100644 --- a/.github/agents/release.agent.md +++ b/.github/agents/release.agent.md @@ -118,4 +118,4 @@ Handoffs you own: - `@#code-review` — final review before PR is opened - + diff --git a/.github/agents/tester.agent.md b/.github/agents/tester.agent.md index 4689f6b..53076ac 100644 --- a/.github/agents/tester.agent.md +++ b/.github/agents/tester.agent.md @@ -126,4 +126,4 @@ Handoffs you own: - `@#incident` — incident analysis and post-mortem writing - + diff --git a/.github/instructions/git.instructions.md b/.github/instructions/git.instructions.md index 47cbc8d..ac98449 100644 --- a/.github/instructions/git.instructions.md +++ b/.github/instructions/git.instructions.md @@ -41,4 +41,4 @@ Use these Git and release hygiene conventions in this project. 1. Prefer local verification before pushing release-impacting changes. - + diff --git a/.github/instructions/python.instructions.md b/.github/instructions/python.instructions.md index 574415e..de5263a 100644 --- a/.github/instructions/python.instructions.md +++ b/.github/instructions/python.instructions.md @@ -42,4 +42,4 @@ Use these Python conventions in this project. 1. Do not silence lint/type errors unless there is a documented, task-specific reason. - + diff --git a/.github/prompts/code-review.prompt.md b/.github/prompts/code-review.prompt.md index e3c1aec..86774d6 100644 --- a/.github/prompts/code-review.prompt.md +++ b/.github/prompts/code-review.prompt.md @@ -50,4 +50,4 @@ End with: - Biggest remaining risk: one sentence - + diff --git a/.github/skills/adr/SKILL.md b/.github/skills/adr/SKILL.md index a1eb261..e043b44 100644 --- a/.github/skills/adr/SKILL.md +++ b/.github/skills/adr/SKILL.md @@ -199,4 +199,4 @@ After writing, state the file path and summary so the architect or product role ______________________________________________________________________ - + diff --git a/.github/skills/analyse/SKILL.md b/.github/skills/analyse/SKILL.md index 8abe845..7895332 100644 --- a/.github/skills/analyse/SKILL.md +++ b/.github/skills/analyse/SKILL.md @@ -227,4 +227,4 @@ ______________________________________________________________________ ______________________________________________________________________ - + diff --git a/.github/skills/architecture/SKILL.md b/.github/skills/architecture/SKILL.md index e12828b..69ed5c4 100644 --- a/.github/skills/architecture/SKILL.md +++ b/.github/skills/architecture/SKILL.md @@ -280,4 +280,4 @@ For each significant structural decision made during this review (technology cho ______________________________________________________________________ - + diff --git a/.github/skills/cicd/SKILL.md b/.github/skills/cicd/SKILL.md index b81e10e..1cd8506 100644 --- a/.github/skills/cicd/SKILL.md +++ b/.github/skills/cicd/SKILL.md @@ -201,4 +201,4 @@ ______________________________________________________________________ ______________________________________________________________________ - + diff --git a/.github/skills/code-review/SKILL.md b/.github/skills/code-review/SKILL.md index 0111f34..3841d4d 100644 --- a/.github/skills/code-review/SKILL.md +++ b/.github/skills/code-review/SKILL.md @@ -219,4 +219,4 @@ Confidence: [HIGH/MEDIUM/LOW — explain if not HIGH] ______________________________________________________________________ - + diff --git a/.github/skills/concise/SKILL.md b/.github/skills/concise/SKILL.md index 41c1917..8a31af6 100644 --- a/.github/skills/concise/SKILL.md +++ b/.github/skills/concise/SKILL.md @@ -160,4 +160,4 @@ ______________________________________________________________________ - [ ] User confirmation/status returned in deterministic format - + diff --git a/.github/skills/consult/SKILL.md b/.github/skills/consult/SKILL.md index b76fdd0..9bd9711 100644 --- a/.github/skills/consult/SKILL.md +++ b/.github/skills/consult/SKILL.md @@ -227,4 +227,4 @@ reason: [one sentence] ______________________________________________________________________ - + diff --git a/.github/skills/container/SKILL.md b/.github/skills/container/SKILL.md index e433bf4..0e69340 100644 --- a/.github/skills/container/SKILL.md +++ b/.github/skills/container/SKILL.md @@ -154,4 +154,4 @@ ______________________________________________________________________ ______________________________________________________________________ - + diff --git a/.github/skills/debug/SKILL.md b/.github/skills/debug/SKILL.md index 7d702d3..5f01c1b 100644 --- a/.github/skills/debug/SKILL.md +++ b/.github/skills/debug/SKILL.md @@ -279,4 +279,4 @@ Prevention: [any follow-up items] ______________________________________________________________________ - + diff --git a/.github/skills/dependency/SKILL.md b/.github/skills/dependency/SKILL.md index b58a119..4575d83 100644 --- a/.github/skills/dependency/SKILL.md +++ b/.github/skills/dependency/SKILL.md @@ -325,4 +325,4 @@ Action items (priority order): ``` - + diff --git a/.github/skills/design/SKILL.md b/.github/skills/design/SKILL.md index dd07f30..4f0fdce 100644 --- a/.github/skills/design/SKILL.md +++ b/.github/skills/design/SKILL.md @@ -263,4 +263,4 @@ Output a complete design document to `docs/design/design.md` or `openapi.yaml`: ______________________________________________________________________ - + diff --git a/.github/skills/docs/SKILL.md b/.github/skills/docs/SKILL.md index a8a39c5..002e127 100644 --- a/.github/skills/docs/SKILL.md +++ b/.github/skills/docs/SKILL.md @@ -167,4 +167,4 @@ Skipped (n/a): ______________________________________________________________________ - + diff --git a/.github/skills/explore/SKILL.md b/.github/skills/explore/SKILL.md index 3e39b84..1b6f5c8 100644 --- a/.github/skills/explore/SKILL.md +++ b/.github/skills/explore/SKILL.md @@ -241,4 +241,4 @@ Stack: [language, framework, runtime versions] ______________________________________________________________________ - + diff --git a/.github/skills/guardrails/SKILL.md b/.github/skills/guardrails/SKILL.md index 39d9368..643e1eb 100644 --- a/.github/skills/guardrails/SKILL.md +++ b/.github/skills/guardrails/SKILL.md @@ -77,4 +77,4 @@ Explicitly ask to "disable guardrails". ______________________________________________________________________ - + diff --git a/.github/skills/incident/SKILL.md b/.github/skills/incident/SKILL.md index 738f8da..32e1848 100644 --- a/.github/skills/incident/SKILL.md +++ b/.github/skills/incident/SKILL.md @@ -325,4 +325,4 @@ Status: [Draft — ready for team review] ``` - + diff --git a/.github/skills/inspect/SKILL.md b/.github/skills/inspect/SKILL.md index 89fe02e..84c233d 100644 --- a/.github/skills/inspect/SKILL.md +++ b/.github/skills/inspect/SKILL.md @@ -165,4 +165,4 @@ ______________________________________________________________________ ______________________________________________________________________ - + diff --git a/.github/skills/migrate/SKILL.md b/.github/skills/migrate/SKILL.md index 2653d46..772ea60 100644 --- a/.github/skills/migrate/SKILL.md +++ b/.github/skills/migrate/SKILL.md @@ -337,4 +337,4 @@ Pre-deploy checklist: ``` - + diff --git a/.github/skills/onboard/SKILL.md b/.github/skills/onboard/SKILL.md index 1504a2f..9afc139 100644 --- a/.github/skills/onboard/SKILL.md +++ b/.github/skills/onboard/SKILL.md @@ -321,4 +321,4 @@ Gaps remaining (if any): ``` - + diff --git a/.github/skills/openapi/SKILL.md b/.github/skills/openapi/SKILL.md index 807d2ce..6361a98 100644 --- a/.github/skills/openapi/SKILL.md +++ b/.github/skills/openapi/SKILL.md @@ -414,4 +414,4 @@ Summary: [N critical, N warnings, N info] `$ref` for all reusable schemas, and validate it passes linting. - + diff --git a/.github/skills/performance/SKILL.md b/.github/skills/performance/SKILL.md index 5296893..4f060d3 100644 --- a/.github/skills/performance/SKILL.md +++ b/.github/skills/performance/SKILL.md @@ -258,4 +258,4 @@ ______________________________________________________________________ ______________________________________________________________________ - + diff --git a/.github/skills/pr/SKILL.md b/.github/skills/pr/SKILL.md index ed7ae1d..28f7012 100644 --- a/.github/skills/pr/SKILL.md +++ b/.github/skills/pr/SKILL.md @@ -140,4 +140,4 @@ CI/CD will now: ______________________________________________________________________ - + diff --git a/.github/skills/refactor/SKILL.md b/.github/skills/refactor/SKILL.md index 455755d..acdad5b 100644 --- a/.github/skills/refactor/SKILL.md +++ b/.github/skills/refactor/SKILL.md @@ -385,4 +385,4 @@ Behavior changed: No ``` - + diff --git a/.github/skills/release-notes/SKILL.md b/.github/skills/release-notes/SKILL.md index 1b0b388..7038e18 100644 --- a/.github/skills/release-notes/SKILL.md +++ b/.github/skills/release-notes/SKILL.md @@ -159,4 +159,4 @@ Keep existing entries intact. ______________________________________________________________________ - + diff --git a/.github/skills/requirements/SKILL.md b/.github/skills/requirements/SKILL.md index e1eaf1a..6f21e8d 100644 --- a/.github/skills/requirements/SKILL.md +++ b/.github/skills/requirements/SKILL.md @@ -219,4 +219,4 @@ After writing, summarize what was decided so the architect role can start. ______________________________________________________________________ - + diff --git a/.github/skills/security/SKILL.md b/.github/skills/security/SKILL.md index a374ada..c37a48d 100644 --- a/.github/skills/security/SKILL.md +++ b/.github/skills/security/SKILL.md @@ -295,4 +295,4 @@ Scope: [full/diff/dependency/config] ______________________________________________________________________ - + diff --git a/.github/skills/verify/SKILL.md b/.github/skills/verify/SKILL.md index adcb7e0..f0707f8 100644 --- a/.github/skills/verify/SKILL.md +++ b/.github/skills/verify/SKILL.md @@ -282,4 +282,4 @@ scope: [path/component/full] ______________________________________________________________________ - + diff --git a/.github/skills/vision/SKILL.md b/.github/skills/vision/SKILL.md index ab0685d..c6974e6 100644 --- a/.github/skills/vision/SKILL.md +++ b/.github/skills/vision/SKILL.md @@ -208,4 +208,4 @@ Present as: "Overall assessment: [READY/NEEDS REVISION/SCOPE CHANGE] because [1- ______________________________________________________________________ - + diff --git a/.github/vstack.json b/.github/vstack.json index ea78985..a3b683e 100644 --- a/.github/vstack.json +++ b/.github/vstack.json @@ -1,6 +1,6 @@ { - "vstack_version": "1.2.5", - "installed_at": "2026-04-21T21:51:23.985830+00:00", + "vstack_version": "1.3.0", + "installed_at": "2026-04-21T22:51:50.907279+00:00", "artifacts": { "skills": [ { diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e4b3997..cb1780f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -19,7 +19,7 @@ env: FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" jobs: - version-and-release: + release: # Computes semantic version from conventional commits, creates git tag, # and publishes GitHub release. name: Compute Version and Tag @@ -120,17 +120,19 @@ jobs: name: Release v${{ steps.version.outputs.version }} (${{ steps.release_date.outputs.date }}) generate_release_notes: true - build-artifacts: + build: # Build distributions only when semver-action reports a new release. name: Build Package Artifacts runs-on: ubuntu-latest - needs: version-and-release - if: github.event.pull_request.merged == true && needs.version-and-release.outputs.changed == 'true' + needs: release + if: github.event.pull_request.merged == true && needs.release.outputs.changed == 'true' steps: - name: Checkout uses: actions/checkout@v6 with: + # Full history and tags required by poetry-dynamic-versioning. + fetch-depth: 0 ref: ${{ github.event.pull_request.merge_commit_sha }} - name: Install Poetry @@ -151,3 +153,24 @@ jobs: with: name: python-dist path: dist/ + + publish: + # Publish distributions to PyPI via OIDC trusted publishing (no API tokens). + name: Publish to PyPI + runs-on: ubuntu-latest + needs: [release, build] + if: github.event.pull_request.merged == true && needs.release.outputs.changed == 'true' + environment: pypi + permissions: + # Required for OIDC trusted publishing. + id-token: write + + steps: + - name: Download build artifacts + uses: actions/download-artifact@v7 + with: + name: python-dist + path: dist/ + + - name: Publish to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/CHANGELOG.md b/CHANGELOG.md index efa18b7..fd2af57 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,10 +1,10 @@ # Changelog -## 1.2.6 - 2026-04-22 +## 1.3.0 - 2026-04-22 -DX and onboarding quality release. +DX, onboarding, and PyPI publishing release. -### Added in 1.2.6 +### Added in 1.3.0 - Added GitHub Discussion templates for onboarding and adoption feedback: - `onboarding-feedback` @@ -14,11 +14,12 @@ DX and onboarding quality release. - Added explicit expected output examples for first install validation in `README.md`. - Added a troubleshooting decision flowchart in `README.md`. -### Changed in 1.2.6 +### Changed in 1.3.0 - Restructured `README.md` for faster onboarding with clearer quick paths, role usage guidance, and troubleshooting navigation. - Updated architect and product agent template model ordering and regenerated installed agent artifacts. - Updated generated artifact metadata and aligned generation tests with current template output. +- Added PyPI publish job to release workflow using OIDC trusted publishing (no API tokens required). ## 1.2.5 - 2026-04-21 diff --git a/README.md b/README.md index 99ed881..242d973 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ vstack +[![PyPI version](https://img.shields.io/pypi/v/vstack?color=0B8A6F "Latest PyPI release")](https://pypi.org/project/vstack/) [![Python version](https://img.shields.io/badge/python-3.11--3.14-0B8A6F "Supported Python versions")](pyproject.toml) [![Verify status](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/verify.yml?branch=main&label=verify&color=1D6FA5 "Build and test status")](https://github.com/eschaar/vstack/actions/workflows/verify.yml) [![Security checks](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/security.yml?branch=main&label=security&color=B15E00 "Security workflow status")](https://github.com/eschaar/vstack/actions/workflows/security.yml) @@ -63,7 +64,7 @@ For experienced users: #### New user path (2 minutes) ```bash -pipx install git+https://github.com/eschaar/vstack.git +pipx install vstack vstack install --target /path/to/your/project vstack validate ``` @@ -104,10 +105,12 @@ ______________________________________________________________________ ### ⚡ Install with pipx (recommended) -You can install and use vstack directly without cloning: +`pipx` installs vstack in its own isolated environment so it never conflicts with +your project dependencies. The `vstack` command is then available globally across +all projects, regardless of which virtual environment is active. ```bash -pipx install git+https://github.com/eschaar/vstack.git +pipx install vstack ``` Afterwards, the `vstack` command is available everywhere: @@ -120,6 +123,21 @@ vstack install --target /path/to/your/project vstack install --global ``` +### 🐙 Alternative: install directly from GitHub + +To install the latest unreleased version directly from the repository without cloning: + +```bash +pipx install git+https://github.com/eschaar/vstack.git +``` + +Or a specific branch or tag: + +```bash +pipx install git+https://github.com/eschaar/vstack.git@main +pipx install git+https://github.com/eschaar/vstack.git@1.3.0 +``` + ### 🐙 Alternative: manual clone and install ```bash @@ -163,7 +181,7 @@ If you see the version and no errors, your install is working. Expected output (example): ```text -vstack 1.2.5 +vstack 1.3.0 Validation passed: no unresolved template tokens ``` @@ -430,7 +448,7 @@ flowchart TD - Issue: `Permission denied` during install or uninstall Action: Check directory permissions and rerun with appropriate privileges. - Issue: `Could not detect VS Code user data directory` - Action: Run with an explicit target, for example `vstack install --target ~/.config/Code/User`. + Action: Run `vstack install --global` to install into the VS Code user profile, or run `vstack install --target /path/to/your/project` to install into a specific project instead. ### Copilot Agent Mode diff --git a/tests/vstack/cli/test_commands.py b/tests/vstack/cli/test_commands.py index 66a729d..e7a95ff 100644 --- a/tests/vstack/cli/test_commands.py +++ b/tests/vstack/cli/test_commands.py @@ -62,13 +62,13 @@ def test_verify_only_filter_limits_checked_types(self, installed_target: Path) - f"vstack verify --only skill failed:\n{result.stdout}\n{result.stderr}" ) - def test_install_and_verify_exits_zero(self) -> None: + def test_install_and_verify_exits_zero(self, tmp_path: Path) -> None: """Test that install and verify exits zero.""" - install = run_vstack(["install"]) + install = run_vstack(["install", "--target", str(tmp_path)]) assert install.returncode == 0, ( f"vstack install failed:\n{install.stdout}\n{install.stderr}" ) - verify = run_vstack(["verify"]) + verify = run_vstack(["verify", "--target", str(tmp_path)]) assert verify.returncode == 0, f"vstack verify failed:\n{verify.stdout}\n{verify.stderr}" def test_validate_with_empty_templates_returns_non_zero(self, tmp_path: Path) -> None: