vinta-ai-workflows
Advanced tools
Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.
Bootstrap AI tooling — AGENTS.md, sub-agents, project skills, multi-vendor wiring — into any project, then get out of the way.
Distributed as an npm package (vinta-ai-workflows) with a CLI that installs / updates / uninstalls a set of one-shot bootstrap skills into the project's vendor-specific skill directories (Claude Code, Codex, Cursor, VS Code + GitHub Copilot).
# 1. Add the package to the target project.
cd ~/code/my-project
npm install -D vinta-ai-workflows
# 2. Install the bootstrap skills for your AI tool.
npx vinta-ai-workflows install --tool claude-code
# or --tool agents (covers Codex + Cursor + Copilot in one go)
# or --tool all
# 3. Open the project in the AI tool, run the orchestrator.
# Claude Code → /vinta-bootstrap-ai-tools
# 4. Review and commit the generated layout.
git add ai-tools/ AGENTS.md CLAUDE.md .claude/ .codex/ .cursor/ .github/ .agents/
git commit -m "Bootstrap ai-tools layout"
# 5. Remove the builder skills — one-shot done.
npx vinta-ai-workflows uninstall --tool claude-code
npm uninstall vinta-ai-workflows
Pin a version for determinism with npm install -D vinta-ai-workflows@0.2.0. Prerequisites: Node ≥ 18.
After bootstrap, the project ships with three foundation skills that take a feature from raw prompt to merged code:
raw prompt / ticket
│
▼
┌─────────────────┐ ai-plans/YYYY-MM-DD-FEATURE_NAME_SPEC.md
│ create-spec │───► what + why (Business Context, Hypothesis,
└─────────────────┘ Use-cases, Acceptance, Negative scope,
│ Open questions, Risks)
▼
┌─────────────────┐ ai-plans/YYYY-MM-DD-FEATURE_NAME_PLAN.md
│ plan-feature │───► how + when (Goals, Decisions, Data Model,
└─────────────────┘ Phased Rollout, Touch List, Risks)
│
▼
┌─────────────────┐ one branch per phase (independent phases run in
│ implement-plan │───► parallel lanes) + a tracking dir
└─────────────────┘ plan/<feature>/phase-1, phase-2, wave-1, ...
You also get: an AGENTS.md tuned to the codebase — a regular file at the repo root, with per-vendor aliases (CLAUDE.md, .github/copilot-instructions.md) symlinked to it — project-specific sub-agents and skills derived from the actual stack, and per-vendor wiring so Claude Code / Codex / Cursor / Copilot all see the same artifacts.
The project keeps getting better without re-bootstrapping. vinta-ai-workflows ships new foundation skills, sharper templates, schema additions, and best-practice updates lifted from real projects. A bootstrapped repo pulls those in via vinta-sync-ai-tools — one command from the AI tool, per-change Apply / Skip / Show diff gating, opt-outs sticky across runs, schema migrations automatic. No manual re-scaffolding, no clobbered hand-tuning, no drift between projects on the same package version. This is treated as a first-class capability of the package, not an afterthought.
The bootstrap skills are one-shot. They scaffold the project once and are removed — they don't pollute the slash menu, and they can't accidentally overwrite hand-tuned output on a future run. Sync handles every later upgrade.
create-specTrigger: /create-spec, "write a spec for X", "draft a spec for the new ". Runs as soon as you have a prompt or ticket and need structure before planning.
What it does: interviews the requester before drafting — never turns a vague prompt into a plausible-sounding spec by guessing. The interview covers Business Context, Hypothesis, Objectives, Use-cases, State transitions, Acceptance scenarios, Negative scope, Alternatives considered, Open questions, and Risks assumed.
Output: ai-plans/YYYY-MM-DD-FEATURE_NAME_SPEC.md with the fixed section structure above. YYYY-MM-DD = today; FEATURE_NAME = UPPERCASE_WITH_UNDERSCORES.
Hand-off: confirm scope with the requester, then move to plan-feature. The spec is the contract; the plan is the build pipeline. Plans without specs produce plausible-sounding but unverified work.
plan-featureTrigger: /plan-feature, "plan the ", "break this spec into phases". Reads the matching *_SPEC.md (paired by date + feature name) before drafting.
What it does: translates the spec into a phased delivery plan. Output sections:
.workflow.json transcribes the same roster). Reviews are not staffed: both implement-plan and vinta-ai-maestro review each phase with thermo-nuclear-review-loop, which spawns its own reviewer. Then each phase declares: id, title, goal, Assigned to (which crew member takes it — implement-plan resolves their tier to the cheapest available model), reusable_skills (other project skills the implementer should invoke), Changes, Tests, Acceptance, plus flags for is_cross_repo and is_flag_removal (both deferred).Phases are sized so the slowest path (e.g. cross-repo producer wiring, external integration approval) starts in Phase 1 and fast in-repo work fills in behind. Large mutation phases get split (4a / 4b / 4c) rather than monolithic.
Output: ai-plans/YYYY-MM-DD-FEATURE_NAME_PLAN.md. Same FEATURE_NAME prefix as the spec so ls ai-plans/ groups pairs.
Hand-off: review the plan with the team — feature-flag decision, phase boundaries, cross-repo dependencies, rollback story. Once approved, move to implement-plan.
implement-planTrigger: /implement-plan, "implement the plan", "execute phase N of plan X". Asks which plan if ambiguous, then drives every in-scope phase to completion without further prompts (unless a phase fails after retries).
Per-phase loop (Step 1 of the skill):
implementer by default; switch to a stack-specialist (migration-author, deploy-author, etc.) when that role's risk dominates the phase.review-phase runs the thermo-nuclear-review-loop skill with the orchestrator as the loop's host. One reviewer sub-agent, with no implementation context and one tier above the tier the implementer ran at, reviews the phase diff against the phase body and the plan's Goals and Guiding Decisions. Its findings go back to the phase's own implementer, which verifies each one, fixes the justified ones, rejects the rest with counter-evidence, re-runs the gates and commits the round. A question only a person can settle (an unreachable scenario, a scope call, a destructive step) comes to you as a structured question. The orchestrator never edits code.Branch model — one branch per phase, based on that phase's dependencies:
Every phase in the plan declares what it needs (**Depends on**: Phase 1 (the BookmarkFolder model), …). That line — not the phase's number — decides both when it runs and what it branches from.
# A phase with no dependencies — branches from the default branch.
git checkout main && git pull --ff-only
git checkout -b plan/<feature-kebab>/phase-1
git push -u origin plan/<feature-kebab>/phase-1
# A phase depending on exactly one phase — branches from it.
git checkout plan/<feature-kebab>/phase-1
git checkout -b plan/<feature-kebab>/phase-2
git push -u origin plan/<feature-kebab>/phase-2
# A phase depending on several — branches from a merge of them.
git checkout -B plan/<feature-kebab>/integ-4 plan/<feature-kebab>/phase-2
git merge --no-ff plan/<feature-kebab>/phase-3
git checkout -b plan/<feature-kebab>/phase-4
Each phase's PR (or branch, depending on the project's PR policy captured at bootstrap) targets its own base, not main. This keeps the diff per PR scoped to a single phase, makes review manageable, and lets the team merge as approvals land. A plan whose phases form a chain produces exactly the classic stack; a plan with independent phases produces several short stacks, reunited by per-wave integration branches (plan/<feature-kebab>/wave-<N>).
Parallel phases. Because the plan carries a dependency graph, implement-plan implements independent phases at the same time — one worktree lane per phase in flight, each with its own dev + test database and compose stack, so concurrent test runs don't collide. A phase starts the moment every phase it depends on is green and a lane frees up; a failed phase blocks only its dependents while the rest of the plan keeps going. On by default (run_options.implement-plan.parallel_phases, capped by max_parallel_lanes, default 3), it requires prepare-worktree and refuses to run rather than silently falling back to sequential when worktrees aren't available. A chain-shaped plan runs one phase at a time — same scheduler, one lane.
Alternative: modular commits. Teams that prefer one branch + one PR per plan can set policies.commit_strategy: modular-commits in .vinta-ai-workflows.yaml. Under that mode, every phase pushes its atomic unit commits (one per service, use-case wire-up, init export, serializer field, refactor, or bug fix — tests in the same commit as code) to a single plan/<feature-kebab> branch; the PR opens once after Phase 1 review and gets updated as later phases push. The third option, commit_strategy: ask, prompts implement-plan at Step 0 (alongside the existing pause_between_phases / generate_inline_comments opt-ins) and caches the answer in the tracking file. Default is stacked-branches — the model documented above. See schemas/vinta-ai-workflows-config.v1.schema.json for the field definition.
Tracking directory — ai-plans/TRACKING_<feature-kebab>/. The orchestrator writes it from git diff + the agent's report (not the agent's narration): run.md for run options, the resolved dependency graph, and the lane pool; one phase-<id>.md per phase (status, model used, branch, base, wave, e2e+screenshots when applicable, 5–15 line summary); waves/wave-<N>.md for each integration merge. It is a directory rather than one file so concurrent lanes never write the same path — each phase's entry is committed on that phase's own branch, which keeps wave merges clean. Acts as the durable context handoff between phase prompts, scoped per phase to its own dependencies. Deleted on plan completion.
Phases the orchestrator never auto-executes:
is_cross_repo: true) — work in another repository. Marked deferred in tracking; orchestrator continues to the next in-repo phase. Don't block on cross-repo work.implement-plan. Marked deferred; orchestrator ends the run with a hand-off note.Failure handling: if a phase's gates stay red after escalation, or its review stops unapproved, orchestrator stops, posts the agent's report, and asks how to proceed. It does not silently rerun, skip, or escalate models without the user.
prs-context + open-pr.shimplement-plan has one path for opening PRs: write a .vinta-ai-workflows/prs-context/{feature-name}/{phase-name}.md file, then run the bundled open-pr.sh script. No raw gh pr create / glab mr create calls live elsewhere in the flow. The file is the durable record; the script is the publisher. The .vinta-ai-workflows/prs-context/ directory is auto-added to .gitignore by setup-ai-tools.mjs.
What actually happens depends on two signals:
generate_inline_comments opt-in — Step 0 per-run question, off by default. Yes → agent picks 3–10 non-obvious diff spots and writes them to the file's # Comments block. No → file's # Comments block is empty; only # Title + # Description populate.| PR policy | inline comments | What the Open PR via context file step does |
|---|---|---|
| agents create | off | Write file (empty # Comments); run open-pr.sh → PR opened, no inline comments. |
| agents create | on | Write file (full); run open-pr.sh → PR opened, all comments posted. |
| branches only | off | Skip the step. Human opens PR manually. |
| branches only | on | Write file (durable record); don't run script. Publish later via open-pr-from-context from a CLI-equipped session. |
open-pr.sh exit codes propagate: 0 = PR up + comments OK, 1 = PR up but ≥1 comment failed (failures listed by (file:line)), 2 = hard failure (file stays status: pending so re-running after fixing the gap is safe).
Required tools for open-pr.sh (install before any policy = "agents create" run, and on any session that will publish a pending file later):
bash 4+ — already present on macOS (3.2 ships by default; install 4+ via brew install bash) and Linux.git.yq (Mike Farah's Go binary — not the Python yq wrapper). Used to read/write the file's YAML frontmatter and parse the comments list.jq — used to iterate the comment list and parse gh / glab JSON output.gh (for GitHub) or glab (for GitLab), authenticated.Install commands:
# macOS
brew install yq jq gh # GitHub
brew install yq jq glab # GitLab
# Debian / Ubuntu
sudo apt install yq jq # check yq version — some distros ship the Python wrapper;
# if so, install Mike Farah's binary from the GitHub releases.
# gh: see cli.github.com#installation
# glab: see gitlab.com/gitlab-org/cli#installation
# Auth (once per machine)
gh auth login # GitHub
glab auth login # GitLab
The script bails early with missing dependency: <name> if any are absent. If a runner can't install them (e.g. minimal CI image), the project's PR policy must be set to "branches only" at bootstrap so the Open PR via context file step skips the script — humans open PRs from the pushed branch.
# Day 1 — discovery + scoping
/create-spec # interview → ai-plans/2026-05-12-CHECKOUT_FLOW_SPEC.md
# review with team, iterate
# Day 2 — planning
/plan-feature # reads spec → ai-plans/2026-05-12-CHECKOUT_FLOW_PLAN.md
# review feature flag, phase boundaries, rollback story
# Day 3+ — execution
/implement-plan # orchestrator runs phase 1 → phase 2 → ... → phase N-1
# each phase: implementer + a review loop until approval,
# one stacked branch + PR per phase
# merge phase branches sequentially as approvals land
# soak phase 1 in prod → soak phase 2 → ...
# once feature flag's flip-on criterion is met:
# invoke the flag-removal skill on the deferred phase N
Standalone re-invocation works at every step — kick create-spec again when the requirements shift mid-plan, re-run plan-feature after contract changes, restart implement-plan mid-feature (it picks up from the tracking file, never re-runs completed phases).
Quick inventory of what vinta-bootstrap-ai-tools writes into your repo's ai-tools/ layout — plus AGENTS.md at the repo root, the one artifact that lives outside it — and exposes via per-vendor wiring at .claude/skills/, .agents/skills/, etc. Two disclaimers up front:
Optional foundation skills are gated by the bootstrap interview.
systematic-debugging,add-e2e-test,add-env-var,add-one-off-script,prepare-worktree,thermo-nuclear-code-quality-review, andhandoff-to-clientship only if the user says yes duringvinta-bootstrap-ai-toolsStep 0 (or later opts in viavinta-sync-ai-tools). They are not in every bootstrapped project. The opt-in is recorded in.vinta-ai-workflows.yamlunderfoundation_skills.*.enabledand is sticky across syncs.Stack-specific skills and sub-agents are user-supplied. This package ships detection signals + category lists per stack (resources/stacks/ — Django, Medplum, Next.js App Router, Python package, TypeScript monorepo), not the bodies. When a stack is detected, the orchestrator asks the user for a path / URL to their team's existing template. If no template exists, the category is recorded as a gap in the final summary, not auto-drafted. Bodies are project- and team-specific; one shared template doesn't fit every team's conventions.
The 0.2.0 alpha line adds five foundation skills and restructures plan execution. Two ship in every bootstrapped project, three are opt-in:
handoff (always) — writes a session-continuation doc to .vinta-ai-workflows/handoffs/ so a fresh session, a different agent, or a teammate can resume in-flight work without re-deriving context. Write mode gathers the goal, what's verified vs. still assumed, decisions and the alternatives rejected, landmines, and the single concrete next step from the repo, never from memory. Resume mode reads a handoff and re-checks its claims against the repo before trusting them.deslop-comments (always) — rewrites the comments and doc blocks a task touched into Simple English, stripping AI-slop vocabulary and negative framing. Comment-only: no renames, no behavior change. integrate-phase / amend-plan run it over the PR-context prose they write, vinta-ai-maestro runs it as each phase's deslop chore, and it is also invokable standalone ("deslop these comments").prepare-worktree (opt-in) — provisions a fully-runnable git worktree for parallel plan work so a long-running plan can build, test, migrate, and hit databases without disturbing the main checkout. It reads the plan plus .gitignore / manifests / env / docker config and gives every worktree its own copy of the dependency dirs (never a symlink) and decides per remaining ignored path whether to copy, fork, or share (dev DB, env files, compose project name). It also ships an OS-level write-guard — sandbox-run.sh (sandbox-exec / bwrap) for subprocess runtimes and a PreToolUse hook for Claude Code's in-process subagents — so a stray write back to the main checkout fails at the kernel layer instead of relying on a cooperative "stay in the worktree" instruction. implement-plan Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase.thermo-nuclear-code-quality-review (opt-in) — a deliberately harsh, on-demand structural-maintainability audit of a diff (abstraction quality, giant files, spaghetti-condition growth) that hunts for "code-judo" reframes collapsing whole branches / helpers / modes / layers rather than polishing them. Read-only — it reports findings and hands each fix to a fixer. The per-phase review loop already applies a structural-simplification lens on every phase; this is the deliberate deep audit for when a change touches core architecture, crosses ~1,000 lines, or carries a structural smell worth a dedicated pass.handoff-to-client (opt-in, API-only repos) — generates a self-contained markdown document for the client teams consuming the repo's API: every endpoint / operation added, changed, deprecated, or removed on the current branch vs. the default branch, with request/response shapes derived from the code, auth + error changes, breaking-change flags judged from the strictest plausible client, one realistic example per operation, and per-platform migration notes. Template-rendered from skills.handoff-to-client.* config (required client_platforms, plus api_style / api_spec_path / output_dir).Alongside the new skills, implement-plan was decomposed into a modular plan-execution unit — a thin conductor plus three co-shipped single-purpose sub-skills (implement-phase, review-phase, integrate-phase). review-phase is now the one review implementation shared by implement-plan, amend-plan, and systematic-debugging. The behavior is unchanged; the split is for reviewability and determinism. Two more knobs land in .vinta-ai-workflows.yaml: agent_models (set a tier per fixer / worktree_prep / integrate so the merge-conflict fixer and mechanical steps aren't stuck on the runtime default; reviewer is deprecated and ignored since 0.7.0, because the review runs one tier above the implementer), and E2E tests are now opt-in in both plan-feature and implement-plan (they make runs materially slower; default off, re-enable per-run or per-project).
Land at ai-tools/skills/<name>/SKILL.md. Always-on unless flagged optional.
| Skill | Status | What it does |
|---|---|---|
create-spec | always | Interview-driven spec doc from a raw prompt / ticket → ai-plans/YYYY-MM-DD-FEATURE_NAME_SPEC.md. |
plan-feature | always | Phased delivery plan from the matching spec → ai-plans/YYYY-MM-DD-FEATURE_NAME_PLAN.md. |
create-qa-use-cases | always | Bootstrap QA_USE_CASES.md from the active spec / plan. Called by plan-feature when missing. |
open-pr-from-context | always | Publish a .vinta-ai-workflows/prs-context/<feature>/<phase>.md file as a real PR + inline comments via gh / glab. Bundles open-pr.sh. |
implement-plan | always (generated) | Phase-by-phase plan execution. Thin conductor: parses the plan, resolves one WORKROOT, and runs a fixed pipeline per phase (implement-phase → review-phase → integrate-phase), tracking + reporting. Generated from a template with project commands + branch / PR / co-author policy. |
implement-phase | always (unit) | Plan-execution sub-skill co-shipped with implement-plan: compose the implementer prompt, pick the model, spawn one implementer subagent for a single phase. |
review-phase | always (unit) | Plan-execution sub-skill: runs the thermo-nuclear-review-loop over one phase with the conductor as host — one reviewer sub-agent one tier above the implementer, the phase's own implementer fixing, questions to the human, until the reviewer explicitly approves. Shared by implement-plan, amend-plan, and systematic-debugging. |
integrate-phase | always (unit) | Plan-execution sub-skill: push the reviewed phase along the project's commit strategy + open the PR via context file. Under commit_strategy = ask, ships as integrate-phase-stacked + integrate-phase-modular. |
amend-plan | always (generated) | History-rewriting companion to implement-plan — revises in-flight plans, amends prior-phase commits, force-pushes, rebases stacked downstream branches. Reuses review-phase + implement-phase's shared prompt loop. |
handoff | always | Session-continuation handoff doc → .vinta-ai-workflows/handoffs/. Write captures goal, verified-vs-unverified state, decisions + rejected alternatives, landmines, and the single next step — gathered from the repo, never memory. Resume verifies a handoff's claims against the repo before continuing from its next step. |
deslop-comments | always | Rewrite comments + doc blocks touched during a task into Simple English, and delete the ones that shouldn't exist at all — where-used lists, another module's internals, restatements of the code, deferred-work notes, paths not taken (comment-only; no renames, no behavior change). integrate-phase / amend-plan run it over the PR-context file, vinta-ai-maestro runs it as each phase's deslop chore, and it's invokable standalone. |
thermo-nuclear-review-loop | always | Review-and-fix loop over a change: the running agent spawns one reviewer sub-agent, verifies its findings, fixes the justified ones and answers the rest, until the reviewer explicitly approves under a strict code-quality standard. Scope questions go to the human instead of being assumed. It is the per-phase review on both execution paths: review-phase runs it with the conductor as host, and vinta-ai-maestro runs it as each phase's review chore once the gates are green. Also invokable standalone. |
write-unit-test | default-on (generated) | Write durable unit tests for a unit of behavior, enforcing six framework-agnostic rules + this project's captured test conventions, with runner- and stack-specific best-practice packs. Ships automatically whenever a unit-test framework is detected (set disabled to opt out). Generated from a template; config under skills.write-unit-test.*. See below. |
systematic-debugging | opt-in | Root-cause-first debugging with project-specific repro commands + MCP evidence-gathering (error tracking, traces, logs, metrics, alerts). Renders from a catalogue of observability MCP servers the user declares. |
add-e2e-test | opt-in | Add an e2e test. Body covers e2e framework, page-object pattern, auth/storage-state, seed helpers, tenant scoping, screenshot conventions. |
add-env-var | opt-in | Propagate a new env var through every layer (.env.example, build tool envPrefix, build cache hash, app config, AGENTS.md, CI, deploy injection). |
add-one-off-script | opt-in | Author one-off operational scripts (backfills, cleanups, ad-hoc fixes). Ships a BaseOneOffScript class (Python + TS) enforcing dry-run default, idempotency, batched DB ops, segmented CSV backups, signal-safe interruption, multi-sink logging. |
prepare-worktree | opt-in | Provision a fully-runnable git worktree for parallel plan work — reads the plan + .gitignore + manifests + env / docker config and gives each worktree its own dependency copy (never a symlink) and decides per remaining ignored path whether to copy / fork / share (dev DB, env files, compose project name). Ships an OS-level write-guard (sandbox-run.sh + a Claude Code PreToolUse hook) so stray writes to the main checkout fail at the kernel layer. implement-plan Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase. |
thermo-nuclear-code-quality-review | opt-in | Deliberately harsh structural-maintainability audit of a diff — abstraction quality, giant files, spaghetti-condition growth — hunting "code-judo" reframes that collapse whole branches / helpers / modes / layers. Read-only; hands each fix to fixer. The per-phase review loop carries a condensed structural lens; this is the deliberate deep audit on top of it. |
handoff-to-client | opt-in | (API-only repos) Generate a self-contained API-change handoff doc for the client teams consuming the repo's API — every endpoint / operation added / changed / deprecated / removed vs the default branch, with request/response shapes, auth + error changes, breaking-change flags, one example per operation, and per-platform migration notes. Template-rendered from skills.handoff-to-client.* config (client platforms, API style, spec path). |
write-unit-test in depthAgents write tests that pass but assert too little, mock everything, leave data behind, or couple to internals — this skill exists so you don't have to babysit that. It bakes in six framework-agnostic rules that hold for every test in every stack:
assert result, len(x) == 3 are too weak).Plus a "run it green, then break the code to watch it go red" step and a name-for-the-behavior / one-reason-to-fail convention.
The skill also covers the bug-fix case, in a Regression tests section. The test has to fail without the fix, so revert the fix to check when the test came second. Name it for what must not happen. Assert the cause too, when the visible symptom can look right while the bug is still there. Record a state that settles instead of only its final value. When no test can cover the regression, the PR says so.
Framework guidance ships as best-practice packs on two independent axes, so a project only ever receives advice for frameworks it actually uses (a FastAPI repo never gets Django guidance; a pure library gets no web-framework pack):
resources/packs/runners/) — how to structure, assert, and mock. One, picked by the detected test runner: pytest, vitest, or jest.resources/packs/stacks/) — DB isolation, framework client, domain mocks. Every matched stack's pack ships (a project can match several — e.g. Next.js + React, or TanStack Start + React): django, fastapi, flask, medplum, react, nextjs, tanstack-start, react-router, prisma, plus pure-library packs python-package / typescript-package for framework-less packages.Project preferences are captured at bootstrap (and inferred from an existing suite, then confirmed) under skills.write-unit-test.*: test_style (classes vs functions), data_setup (factories / fixtures / inline), assertion_style, db_isolation, plus free-form additional_conventions. Each defaults to framework-default, deferring to the pack. New frameworks slot in by adding a pack under write-unit-test-packs/ and a detection signal — no schema change.
Land at ai-tools/agents/<name>.yaml (canonical YAML; setup-ai-tools.mjs emits per-vendor copies into .claude/agents/, .cursor/, .codex/, .github/). Always-on trio.
| Agent | Access | Role |
|---|---|---|
implementer | read-write | Default coder for one plan phase. Reads AGENTS.md + plan + phase body, runs inner + outer test gates, reports back. Never branches, pushes, opens PRs, or adds AI co-author trailers. |
reviewer | read-only | Adversarial reviewer for reviews the team asks for. Reads phase + diff + AGENTS.md, outputs BLOCKER / SHOULD-FIX / NIT findings with file:line. Does not edit. review-phase does not use it: its loop spawns a general-purpose reviewer, so one standard applies. |
fixer | read-write | Resolves one merge conflict between phases, applies one review finding handed over cold, or fixes one named test failure. Smallest correct change, re-runs gates, reports. |
Stack templates may add specialists like migration-author (Django) or deploy-author (Medplum) — see disclaimer above.
Integrations are external tools that ship their own skill. The bootstrap asks about each one. When one is enabled, the tool's own CLI installs and updates its skill. This package never copies, renders or edits that skill. Enabling one is recorded under integrations in .vinta-ai-workflows.yaml.
| Integration | What it adds |
|---|---|
pr-review-canvas | A review canvas for every PR an agent opens: the diff grouped by topic, with attention points for the reviewer, shared as a PR comment and read in a local app (pr-review serve). integrate-phase runs /pr-review-canvas <n> after open-pr.sh publishes the PR. plan-feature adds an after_pr review-canvas chore so that vinta-ai-maestro does the same on each phase PR. Offered only for GitHub / GitLab projects where agents open PRs. |
The tool itself is a machine-level install, like gh, and the bootstrap never installs it:
npm install -g @vintasoftware/pr-review-canvas
When the CLI is present, the bootstrap runs pr-review install-skill --claude-dir ai-tools/skills --codex-dir ai-tools/skills, so one copy in ai-tools/skills/pr-review-canvas/ serves every vendor. Refresh it with pr-review upgrade, and check it with pr-review doctor. Do not edit the copy: the tool stamps a hash into it and reports an edited copy as stale. Sharing and other settings live in the tool's own pr-review.config.yml.
Bootstrap is a snapshot. vinta-ai-workflows keeps shipping — new foundation skills, refined templates, sharper agent prompts, schema additions, stack support, best-practice updates lifted from real projects. Pulling those into a previously-bootstrapped repo is a first-class flow, not an afterthought. This is one of the most important capabilities of the package.
# 1. Pull the new package version.
npm update vinta-ai-workflows
# 2. Run the sync skill from your AI tool.
# Claude Code → /vinta-sync-ai-tools
That's it. The sync skill walks every release between the project's recorded version and the new one, proposes per-change updates, and bumps the project's version stamp at the end.
The single source of truth is .vinta-ai-workflows.yaml at the repo root (written at bootstrap, schema: schemas/vinta-ai-workflows-config.v1.schema.json). It records every opt-in the project made — which foundation skills are enabled, which stacks are applied, which vendors are wired, which policies (PR creation, commit strategy, AI co-author, commit style) hold. vinta-sync-ai-tools reads this file and uses it to classify every upstream change into one of:
| Bucket | Meaning | Default |
|---|---|---|
affects-project | Touches enabled surface area (e.g. an enabled foundation skill's body changed). | One prompt per change: Apply / Skip / Show diff. |
opt-in-offer | New optional surface area the project doesn't have. | Description shown; offer to enable. Skip is sticky — recorded in the config so future syncs don't re-propose it. |
config-schema-change | New field, schema migration, or major-bump. | Migrated automatically; required new fields prompt for a value. |
tooling | Setup-script / gitignore / packaging tweaks. | Batched under one prompt. |
not-applicable | Project opted out, or change targets an unused stack. | Listed for transparency, not applied. |
Every per-change decision is explicit — nothing is silently overwritten. Each affects-project change is a separate prompt, so hand-tuned wording in one skill body can stay while another is refreshed. Hand-edits to a rendered skill body that would be clobbered surface a warning before re-render.
At the end of a run:
vinta_ai_workflows_version + last_synced_at get bumped in .vinta-ai-workflows.yaml.vinta-update-project-skills — refresh only the foundation-skill bodies under ai-tools/skills/ against the latest source. Per-skill diff with explicit accept gate. vinta-sync-ai-tools calls this internally for foundation-skill body diffs; invoke it standalone when that's the only thing you want refreshed.vinta-ai-workflows update (CLI, see Update below) — refreshes the builder skills themselves (the vinta-* set in .<vendor>/skills/) when running with --copy. Symlink installs already track package updates automatically.After any of these, schedule a sync run:
npm update vinta-ai-workflows or pulling a newer git+ssh ref.package.json..vinta-ai-workflows.yaml is missing — the sync skill's first step is a "Bootstrap the config file" path that reverse-extracts state from existing artifacts and interview-fills gaps before continuing.If OLD_VERSION === NEW_VERSION, the skill prints "already up to date" and exits without touching anything.
Skills are discovered automatically by name + description. Trigger one in plain language ("bootstrap ai-tools for this repo") or invoke explicitly via slash command. The vinta- prefix is part of the slash name:
| Tool | Invocation |
|---|---|
| Claude Code | /vinta-bootstrap-ai-tools (in chat) |
| OpenAI Codex | /skills then pick, or $vinta-bootstrap-ai-tools mention |
| Cursor | /vinta-bootstrap-ai-tools in Agent chat |
| VS Code + Copilot | /vinta-bootstrap-ai-tools in Copilot Chat |
Start with vinta-bootstrap-ai-tools — it orchestrates the others.
To bring a previously-bootstrapped project up to date with a newer package version, invoke vinta-sync-ai-tools — see Staying in sync with upstream above. To refresh only the foundation-skill bodies under ai-tools/skills/ (a narrower flow), invoke vinta-update-project-skills.
The package is published to the public npm registry. Three install paths.
# inside the target project
npm install -D vinta-ai-workflows
pnpm add -D vinta-ai-workflows
yarn add -D vinta-ai-workflows
bun add -d vinta-ai-workflows
Pin a version when you want determinism:
npm install -D vinta-ai-workflows@0.2.0
Use this to install a branch or commit that isn't published yet — each developer's GitHub SSH key needs read access to the repo:
# inside the target project
npm install -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git
pnpm add -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git
yarn add -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git
bun add -d git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git
Pin a tag/commit when you want determinism:
npm install -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git#0.1.0
If you don't want the dep tracked in package.json:
npx -y -p vinta-ai-workflows vinta-ai-workflows install --tool all
After install, the bin is available at node_modules/.bin/vinta-ai-workflows:
npx vinta-ai-workflows install --tool claude-code
# or:
pnpm vinta-ai-workflows install --tool claude-code
./node_modules/.bin/vinta-ai-workflows install --tool claude-code
--tool accepts: claude-code, codex, cursor, copilot, agents, all.
Universal install (Codex + Cursor + Copilot) — .agents/skills/ is recognized by all three. A single --tool agents install covers them:
# One install, three tools.
npx vinta-ai-workflows install --tool agents
# Pair with Claude Code (which only reads .claude/skills/).
npx vinta-ai-workflows install --tool claude-code
By default the CLI symlinks each skill into the vendor path back to the package's installed location under node_modules/. Use --copy if your build pipeline doesn't preserve symlinks, or if other contributors check out the project without this dep installed (e.g. you commit .claude/):
npx vinta-ai-workflows install --tool all --copy
Each copied skill gets a .installed-by-vinta-ai-workflows marker file used by uninstall and update to recognize what the script owns.
npx vinta-ai-workflows install --tool claude-code \
--skills vinta-bootstrap-ai-tools,vinta-write-agents-md
npx vinta-ai-workflows list prints all available skills.
npx vinta-ai-workflows install --tool all --dry-run
Prints planned actions, touches nothing.
Looking to bring a bootstrapped project up to date with the latest skills, templates, and best practices? That's Staying in sync with upstream —
vinta-sync-ai-tools, invoked from the AI tool. The CLIupdatecommand described here is narrower: it only refreshes the builder skills (thevinta-*set under.<vendor>/skills/) and is mostly only relevant for--copyinstalls.
Refresh installed builder skills against the latest package version:
# 1. Pull the new package version.
npm update vinta-ai-workflows
pnpm update vinta-ai-workflows
# Or for git+ssh, just re-install with the new ref:
npm install -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git#v0.2.0
# 2. Re-link / re-copy builder skills (only needed for --copy installs).
npx vinta-ai-workflows update --tool all
# 3. From your AI tool, sync the project against the new package version.
# Claude Code → /vinta-sync-ai-tools
Step 2's update command is sugar for uninstall followed by install with the same flags. Symlink installs (the default) pick up package updates automatically without step 2.
Step 3 is the important one: it re-renders foundation skill templates from the project's .vinta-ai-workflows.yaml, offers any new opt-in surface area, migrates the config schema if needed, and bumps the project's recorded version. See Staying in sync with upstream for the full flow.
After the bootstrap is committed, remove the skills:
npx vinta-ai-workflows uninstall --tool all
Then drop the package itself:
npm uninstall vinta-ai-workflows
pnpm remove vinta-ai-workflows
uninstall removesThe uninstaller is conservative on purpose:
skills/ directory (or the link is dangling)..installed-by-vinta-ai-workflows marker file.Empty .<vendor>/skills/ directories are removed after the last managed entry leaves; the parent .claude/, .agents/, etc. are left alone since they likely hold other content.
SKILLS="vinta-analyze-codebase vinta-bootstrap-ai-tools vinta-derive-skills \
vinta-derive-subagents vinta-install-ai-tools-setup \
vinta-update-project-skills vinta-write-agents-md"
for vendor in .claude/skills .agents/skills .cursor/skills .github/skills; do
for skill in $SKILLS; do
rm -rf "$vendor/$skill"
done
rmdir "$vendor" 2>/dev/null
done
Verified against official docs as of 2026-05.
| Tool | Project path | Source |
|---|---|---|
| Claude Code | .claude/skills/ | native |
| OpenAI Codex | .agents/skills/ | docs |
| Cursor | .cursor/skills/ (also .agents/skills/) | docs |
| VS Code + Copilot | .github/skills/ (also .claude/skills/, .agents/skills/) | docs |
Codex walks .agents/skills/ from cwd up to the repo root, so an install at the project root covers nested working directories too.
vinta-ai-workflows <command> [options]
Commands:
install Place skills under <target>/.<vendor>/skills/
update Re-install (uninstall + install) so latest source content lands
uninstall Remove skills (only artifacts created by this CLI)
list List available skills
Options:
--tool <name> claude-code | codex | cursor | copilot | agents | all
Aliases: claude, openai-codex, vscode, vscode-copilot,
github-copilot, universal
--target <dir> Project root (default: cwd)
--skills <a,b,c> Subset of skills (default: all)
--copy Copy instead of symlink
--dry-run, -n Plan only
--help, -h Help
Project scope only — there is no user-scope mode. The vinta- skills are intended to bootstrap a single project at a time and then come back out.
"Skills" here = the Agent Skills format: a folder containing a
SKILL.md(with YAML frontmatter) plus referenced resources/scripts. Recognized natively by Claude Code, Codex, Cursor, and VS Code Copilot.
vinta-ai-workflows/
├── package.json # vinta-ai-workflows — exposes vinta-ai-workflows bin
├── vinta-ai-workflows.mjs # CLI: install / update / uninstall / list
├── README.md
└── skills/
├── vinta-analyze-codebase/
├── vinta-bootstrap-ai-tools/ # orchestrator — calls the others
├── vinta-derive-skills/
├── vinta-derive-subagents/
├── vinta-install-ai-tools-setup/
├── vinta-update-project-skills/
└── vinta-write-agents-md/
vinta-bootstrap-ai-tools is the entry point — walks a fresh repo, runs the others in order. The rest can also be invoked individually to refresh a single artifact.
The repository is also a pnpm workspace. packages/ holds private, unpublished packages that are not part of what install puts in your project — the files whitelist excludes the directory. The one worth knowing about is packages/vinta-ai-maestro: an opt-in daemon that executes the ai-plans/<feature>.workflow.json files plan-feature emits, scheduling independent phases across worktree lanes. Each phase there is implemented, gated, then reviewed by its own implementer through the thermo-nuclear-review-loop skill until the loop's reviewer approves, comment-cleaned by deslop-comments, and gated once more before it integrates. Nothing requires it; the skills path runs the same plans with no daemon installed.
vinta- prefix?Once installed, these skills sit alongside the user's own project skills in the same .<vendor>/skills/ directory. The prefix makes ownership obvious in slash menus and on disk: anything under vinta-* is managed by this package and gets removed by uninstall; anything else belongs to the project.
The vinta- skills bootstrap a project's AI tooling. Once the project has its own ai-tools/ layout, AGENTS.md, sub-agents, and per-vendor wiring, they have nothing left to do. Leaving them installed pollutes the slash-command menu and risks a future re-run overwriting hand-tuned output.
→ Install, run once via /vinta-bootstrap-ai-tools (or whatever invocation your tool uses), commit the generated ai-tools/ layout, then uninstall.
When this package gains new versions later, vinta-sync-ai-tools walks the changelog, proposes per-change updates against the project's opt-in surface (recorded in .vinta-ai-workflows.yaml), and only applies what the user explicitly accepts.
If you modify a vinta-* skill source under skills/:
node_modules/vinta-ai-workflows/ refreshes (next npm install / git+ssh re-pull).--copy): consumers must re-run vinta-ai-workflows update with the same flags. The CLI removes the previous copy and writes fresh content + marker.To bring a bootstrapped project up to date with newer builder-skill source, run vinta-sync-ai-tools from the AI tool — it re-renders templates, offers new opt-ins, migrates the config schema, and delegates foundation-skill body diffs to vinta-update-project-skills.
FAQs
Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.
The npm package vinta-ai-workflows receives a total of 310 weekly downloads. As such, vinta-ai-workflows popularity was classified as not popular.
We found that vinta-ai-workflows demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
GitHub is tightening GitHub Actions security with new restrictions on privileged pull request workflows. Here's what changes and how maintainers are affected.
Security News
/Application Security
A practical guide to securing GitHub Actions against supply chain attacks, covering malicious pull requests, credential theft, dependency risks, and release pipelines.
Security News
Composer 2.11 adds dependency cooldowns, joining package managers that delay new releases to reduce supply chain risks while allowing urgent security updates.