vstack 2.2.0

VS Code-native AI engineering workflow system for microservices, libraries, and backend systems.

The VS Code-native AI workflow system for backend engineering.

vstack installs structured agents, skills, instructions, and prompts into .github/ so GitHub Copilot Agent Mode can run repeatable backend workflows with clear role boundaries.

It provides a fixed role model for end-to-end software delivery: product, architect, designer, engineer, tester, and release.

Best for

• Backend and API teams using GitHub Copilot Agent Mode in VS Code
• Repositories that want consistent planning, implementation, verification, and release flow
• Teams that want reusable AI workflows instead of one-off prompt crafting

What you get

• Fixed role model: product, architect, designer, engineer, tester, release
• Template-driven install model from src/vstack/_templates/
• Backend-first verification, security, and release discipline
• Standard-library-only runtime dependencies

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

Prompt catalog

Prompts are .prompt.md files installed to .github/prompts/. Invoke them via the VS Code command palette (Chat: Run Prompt File) or the Copilot Chat attach button.

Prompt	Purpose
api-design-review	Review an API design or OpenAPI spec for correctness
architecture-risk	Identify architectural risks and mitigation priorities
code-review	Review a change for bugs, regressions, and missing tests
dependency-audit	Audit dependencies for vulnerabilities and licence risks
incident-timeline	Build an evidence-based incident timeline and post-mortem
migration-safety	Review DB migration safety, rollback, and zero-downtime
release-readiness	Evaluate release readiness from reports and open blockers

Quick start

Install with pipx, then install vstack artifacts into your repository:

pipx install vstack
vstack install --target /path/to/your/project
vstack validate

Run a first task in Copilot Agent Mode:

@tester /verify Check this repository and summarize findings

Expected result:

• vstack validate reports no unresolved template tokens
• Agent command returns a concrete verification summary for your repository

Why this helps

• Consistent role boundaries for planning, implementation, validation, and release
• Reusable skills and instructions instead of ad hoc prompts
• Better release hygiene with documented workflows and CI alignment

Core commands

vstack --version
vstack validate
vstack install --target /path/to/your/project
vstack manifest verify --target /path/to/your/project
vstack manifest status --target /path/to/your/project
vstack manifest upgrade --target /path/to/your/project

Common usage patterns

Repository-scoped install (recommended for teams):

vstack install --target /path/to/your/project

Profile-wide install (optional defaults for all projects):

vstack install --global

By default, vstack install preserves existing unmanaged files and local edits to tracked files by comparing the current file contents with the SHA-256 checksum recorded in vstack.json. Use --adopt-name <name> to start tracking one existing unmanaged file without overwriting it. vstack uninstall also preserves locally modified tracked files unless you explicitly pass --force or --force-name <name>. Use vstack manifest status --target ... (or vstack status --target ...) to see what still matches the manifest. If a legacy manifest schema is detected, run vstack manifest upgrade --target ... first.

If you already have agents, skills, or other files in .github/, run a dry-run first to see what would be preserved before committing:

vstack install --dry-run --target /path/to/your/project

The summary lists preserved files as type/name selectors (e.g. agent/engineer). Resolve each conflict with --force-name type/name to overwrite, --adopt-name type/name to take ownership without overwriting, or --force to overwrite everything.

Fast troubleshooting

• Command not found after install: ensure your pipx binary path is in PATH
• Validation error: rerun vstack install --target ... and then vstack validate
• Agent results look generic: explicitly invoke a role (for example @tester) before a skill

Full documentation

For complete documentation (including architecture details, workflow diagrams, and contributor guides), use GitHub:

• GitHub repository
• Full README
• Documentation
• Contributing guide
• Security policy