vstack 3.1.1

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
• One runtime dependency: PyYAML

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

Quickstart — fresh install

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

# Install the CLI once, globally
pipx install vstack

# Move to your repository root and run install — no --target needed
cd /path/to/your/project
vstack install        # seeds .vstack/config.yaml and generates .github/ in the current directory
vstack validate       # confirm no errors

When you omit --target, vstack uses the current working directory. The equivalent explicit form is vstack install --target /path/to/your/project.

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

Quick upgrade

Patch or minor version (e.g. v3.1 → v3.2, same major)

Docs paths never change within a major version. Only .github/ artifacts are updated.

pipx upgrade vstack

cd /path/to/your/project
vstack init           # idempotent — safe to run in CI

Major version (e.g. v2 → v3)

Docs paths may change on a major version bump. Run vstack migrate before vstack init.

pipx upgrade vstack

cd /path/to/your/project
vstack migrate        # moves docs files to their new paths (auto-detects installed version)
vstack init           # regenerates .github/ artifacts

# Only if you see "Legacy manifest schema detected" in the output above:
vstack manifest upgrade
vstack init

Preview the docs moves without touching any files:

vstack migrate --dry-run

For upgrades spanning multiple major versions (e.g. v1 → v3), vstack migrate chains all intermediate steps automatically. Use --from and --to to specify the range explicitly if auto-detection from the manifest fails:

vstack migrate --from 1 --to 3
vstack init

Force reinstall (overwrite local edits)

vstack install --force                       # overwrite all managed artifacts
vstack install --force-name agent/engineer   # overwrite one specific artifact

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

# Run from your repository root (--target defaults to the current directory)
vstack install
vstack init
vstack migrate
vstack manifest verify
vstack manifest status
vstack manifest upgrade

# Or specify a path explicitly
vstack install --target /path/to/your/project

Common usage patterns

Repository-scoped install (recommended for teams):

# Move to your repository root and install there
cd /path/to/your/project
vstack install

# Or specify a path explicitly from any directory
vstack install --target /path/to/your/project

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

vstack install --global

vstack install is the first-run command: it seeds .vstack/config.yaml in your project (never overwrites), then generates .github/ artifacts from templates. vstack init re-runs generation idempotently — safe to use in CI after upgrading vstack.

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/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.

To skip artifact types or individual artifacts you do not need, edit .vstack/config.yaml:

exclude:
  skills:
    - terraform
    - helm
  instructions: all   # skip the entire type

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

# Run from your repository root
vstack install --dry-run

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 from your repository root 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