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-workflowsPin 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.
Trigger: /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.
Trigger: /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:
- Goals + Non-goals — what's in / out of scope.
- Guiding Decisions — feature flag (key, scope, default, flip-on criterion if any), storage shape, tenant scoping, API contract, schema rules. Load-bearing — every phase reaches back here.
- Data Model Changes — migrations + rollout order.
- Phased Rollout — opens with a Crew table (the implementers this plan is staffed with, each with a tier; every implementer keeps one worktree and one session for the whole run, and the
.workflow.jsontranscribes the same roster). Reviews are not staffed: bothimplement-planandvinta-ai-maestroreview each phase withthermo-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 foris_cross_repoandis_flag_removal(both deferred). - Risk & Rollout Notes, Open Questions, Touch List.
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.
Trigger: /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):
- Compose a token-efficient prompt. AGENTS.md + the plan's Goals + Non-goals, Guiding Decisions, relevant Data Model Changes subsection, this phase's body under Phased Rollout, plus the running tracking summary (replaces full prior-phase content as context handoff). Don't dump the full plan into every prompt.
- Pick the model from the plan's per-phase suggestion. Filter to what the runtime can actually run, choose the cheapest survivor. Capability gap on retry → escalate one tier; after Tier 4, stop and surface to the user.
- Spawn the right agent type.
implementerby default; switch to a stack-specialist (migration-author,deploy-author, etc.) when that role's risk dominates the phase. - Implementer runs inner + outer loop. Inner: lint → scoped tests → typecheck on touched files; iterate until green. Outer (only after inner is green): full build + full test suite + e2e where applicable. Never commits, pushes, or proceeds with a red gate.
- Review loop before integrating the phase.
review-phaseruns thethermo-nuclear-review-loopskill 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. - Loop until the reviewer approves. The reviewer re-reads the whole diff on every pass, and the phase passes only on its explicit approval. After 20 passes that still return blockers, the orchestrator pauses and asks whether to continue for 20 more, stop the phase unapproved, or amend the plan.
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-4Each 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:
- Cross-repo phases (
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. - Flag-removal phase (always the last phase when a feature flag exists). Gated on real-world soak signal — handled by a dedicated flag-removal skill, not
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.
implement-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:
- Project PR creation policy — captured at bootstrap. Either "agents create PRs" or "branches only, humans open PRs".
generate_inline_commentsopt-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# Commentsblock. No → file's# Commentsblock is empty; only# Title+# Descriptionpopulate.
| 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):
bash4+ — already present on macOS (3.2 ships by default; install 4+ viabrew install bash) and Linux.git.yq(Mike Farah's Go binary — not the Pythonyqwrapper). Used to read/write the file's YAML frontmatter and parse the comments list.jq— used to iterate the comment list and parsegh/glabJSON output.- One of
gh(for GitHub) orglab(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 # GitLabThe 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-planrun it over the PR-context prose they write,vinta-ai-maestroruns it as each phase'sdeslopchore, 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 aPreToolUsehook 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-planStep 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 afixer. 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 fromskills.handoff-to-client.*config (requiredclient_platforms, plusapi_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). |
Agents 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:
- Mock only genuine externals — never the unit under test, its local collaborators, or the DB.
- Assert the full expected value, not counts or truthiness (
assert result,len(x) == 3are too weak). - Leave no trace — transaction-rollback where available, else clean up in teardown (runs on failure too).
- No external service that can't run in dev/test — stub at the boundary.
- Test logic stays literal — no loops/conditionals recomputing the expected value.
- Decouple from internals — assert observable state/output; survive a behavior-preserving rewrite.
- Kill nondeterminism — control every entropy source (clock, randomness, timezone/locale, iteration/DB order, concurrency); a flaky test is worse than none. Don't over-fit brittle text either — assert a stable anchor (error code, role, i18n key) for error messages and UI copy, not the exact churning prose.
- Cover the branches — aim high (95%+ branch coverage): every error path, guard, and edge gets a case. Coverage is the floor; correct assertions are the point.
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):
- Runner pack (
resources/packs/runners/) — how to structure, assert, and mock. One, picked by the detected test runner:pytest,vitest, orjest. - Stack pack(s) (
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 packspython-package/typescript-packagefor 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-canvasWhen 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-toolsThat'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:
- Approved changes apply (templates re-rendered from the config, new foundation skills copied, config schema migrated, setup script re-run idempotently).
- Every YAML file in the project re-validates against its schema.
vinta_ai_workflows_version+last_synced_atget bumped in.vinta-ai-workflows.yaml.- A final report lists Applied / Skipped / Newly disabled / Orphan diffs (changes without changelog entries — flagged, never auto-applied).
vinta-update-project-skills— refresh only the foundation-skill bodies underai-tools/skills/against the latest source. Per-skill diff with explicit accept gate.vinta-sync-ai-toolscalls 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 (thevinta-*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-workflowsor pulling a newer git+ssh ref.- A teammate bumped the version pin in
package.json. - The package shipped a new foundation skill, stack, or schema field you want to opt into.
- The project's
.vinta-ai-workflows.yamlis 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-workflowsPin a version when you want determinism:
npm install -D vinta-ai-workflows@0.2.0Use 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.gitPin a tag/commit when you want determinism:
npm install -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git#0.1.0If you don't want the dep tracked in package.json:
npx -y -p vinta-ai-workflows vinta-ai-workflows install --tool allAfter 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-codeBy 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 --copyEach 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-mdnpx vinta-ai-workflows list prints all available skills.
npx vinta-ai-workflows install --tool all --dry-runPrints 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-toolsStep 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 allThen drop the package itself:
npm uninstall vinta-ai-workflows
pnpm remove vinta-ai-workflowsThe uninstaller is conservative on purpose:
- Symlinks are removed only if their target points back into the package's
skills/directory (or the link is dangling). - Copied directories are removed only if they contain the
.installed-by-vinta-ai-workflowsmarker file. - Anything else (hand-authored skills, third-party skills, files lacking the marker) is left in place with a warning.
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
doneVerified 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.
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/:
- Symlink installs (default): consumers get updates as soon as their
node_modules/vinta-ai-workflows/refreshes (nextnpm install/git+sshre-pull). - Copy installs (
--copy): consumers must re-runvinta-ai-workflows updatewith 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.