vstack 3.0.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

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:

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