vstack

A small, opinionated Claude Code plugin for the ticket → merged PR workflow: investigate before coding, prove root causes, lock scope, verify with real output, and keep PR and ticket write-ups short.

It adapts to each repo instead of assuming a stack. Run setup once and every other skill reads the result.

Install

From GitHub (marketplace):

/plugin marketplace add <your-github-user>/vstack
/plugin install vstack@vstack

Local (development):

claude --plugin-dir ./vstack

Or add the folder as a local marketplace:

/plugin marketplace add ./vstack
/plugin install vstack@vstack

After edits, run /reload-plugins. Validate with claude plugin validate ./vstack.

Skills

Commands are namespaced: /vstack:<skill>.

Skill	What it does
setup	Once per repo. Detects type-check/lint/test/probe commands, tracker, git host, ticket-key pattern and docs location into .claude/vstack.json.
investigate	New feature: read-only search that ends in a verdict: reuse, extend, or create new.
rca	Bug: reproduce, prove the root cause, write the RCA and proposed fix. No code.
plan	Scope-locked plan: exact files, code to reuse, explicit out-of-scope list. Needs your approval.
build	Implements the approved plan with the smallest diff; stops if it needs files outside the plan.
verify	Runs the configured gates and an independent diff review; reports real pass/fail.
probe	Checks that data is correct, via the repo's probe script or a throwaway read-only one.
pr-description	≤120-word PR description: what, why, how to test.
jira-comment	≤80-word ticket update for QA/PM, in Jira markup when the tracker is Jira.
flow	Optional: chains all of the above with approval checkpoints. Explicit invocation only.

Subagents

• code-explorer: read-only codebase search in its own context.
• fresh-eyes-reviewer: reviews the diff against the plan with no memory of how it was written.

Hooks

Local only: no network, nothing destructive. Scripts are Node, so they run the same on Windows, macOS and Linux.

• Block force-push and destructive git: git push --force/-f/--force-with-lease, git reset --hard, git clean -f.
• Block .env access: Read/Edit/Write and shell commands touching .env* (.env.example is allowed).
• Auto-format: runs the project's own local Prettier on the single edited file, only if Prettier is installed and configured. Never uses npx.

Quick start

cd my-repo
/vstack:setup                       # once; confirm the detected commands
/vstack:rca PROJ-123                # bug: reproduce and find the root cause
/vstack:plan PROJ-123               # approve the scope
/vstack:build PROJ-123
/vstack:verify PROJ-123
/vstack:pr-description PROJ-123
/vstack:jira-comment PROJ-123

Or run it all with checkpoints: /vstack:flow PROJ-123 bug.

Work files (investigation.md, rca.md, plan.md) are written to .claude/vstack/work/<KEY>/. setup adds that folder to .git/info/exclude so it never gets committed.

Principles

• Nothing is committed, pushed, or posted for you.
• A skill never invents a command the repo doesn't define; missing tools are skipped.
• Each skill does one job and has a definition of done.

License

MIT