vinta-ai-workflows

Bootstrap a project's AI-tooling layout (`ai-tools/AGENTS.md`, `ai-tools/skills/`, `ai-tools/agents/*.yaml`) plus the multi-vendor setup script that wires the canonical sources into Claude Code, Cursor, Codex, and VS Code Copilot. Project-agnostic — adapts to whatever stack it finds. Detects langs, frameworks, build tools, deploy paths, multi-tenancy patterns, and CI conventions, interviews the user for the gaps, then drafts AGENTS.md, the foundation sub-agents (implementer / reviewer / fixer), and a starter set of project-specific skills. Stack-specific skill + agent templates (Medplum, Django, …) live as resources and get copied when the detected stack matches. Use when invoked in a fresh repo that doesn't yet have an `ai-tools/` directory, or to refresh an existing one. Orchestrates several sub-skills — see "Sub-skill flow" below.

Provision a fully-runnable git worktree for parallel feature work so a long-running plan (or experiment) can build, test, lint, run migrations, and hit databases without disturbing the main checkout — or other parallel worktrees. Reads the active plan (when given one) plus the project's `.gitignore`, package manifests, env templates, and docker config to decide what to symlink, what to copy, what to fork (DBs, env files, compose project names, test databases, sandboxes). Use when the user says "set up a worktree for plan X", "create an isolated env for this feature", "I want to run two plans in parallel without breaking the main checkout", or when [implement-plan](../implement-plan/SKILL.md) opts in via Step 0 question (c). NOT for one-off branch switches that don't need a separate runnable copy of the app.

Author project-specific skills under `ai-tools/skills/`. Always copies the project-agnostic foundation set (`plan-feature`, `create-spec`, `open-pr-from-context`) verbatim from this skill's bundled resources; ships `create-qa-use-cases` and keeps `plan-feature`'s e2e sections only when `add-e2e-test` is enabled. Generates `implement-plan` from a parameterized template using project-specific commands + branch / commit / PR conventions captured in the bootstrap interview. Asks the user whether `add-e2e-test` and `add-env-var` are needed (optional foundation skills — only ship if applicable). Stack-specific skills (Medplum, Django, etc) come from user-supplied templates pointed at by the orchestrator — see [bootstrap-ai-tools/resources/stacks/<stack>/notes.md](../vinta-bootstrap-ai-tools/resources/stacks/) for the categories per stack.

Author a phased implementation plan for a new feature following the repo's `ai-plans/` conventions. Use when the user asks to "plan", "design", "scope", or "break down" a feature, write an implementation plan / IMPLEMENTATION_PLAN.md, or turn a spec/idea into a phased roadmap. Always interrogates the requester before drafting.

Write or consume a session-continuation handoff document under `.vinta-ai-workflows/handoffs/` so a fresh agent session (or a different agent / teammate) can resume in-flight work without re-deriving context. Use when the user says "hand this off", "write a handoff", "wrap this up for another agent", "prepare a handoff doc", or — in resume mode — "pick up from the handoff", "resume from handoff", or points at a handoff file. Captures goal, current state, decisions with rationale, files touched, verification status, and the exact next step.

Run an extremely strict maintainability review of a diff — abstraction quality, giant files, and spaghetti-condition growth. This is a deep, on-demand structural audit, harsher than the normal per-phase review: it hunts for "code judo" reframes that make whole branches, helpers, modes, or layers disappear rather than polishing what's there. Use when the user asks for a "thermo-nuclear code quality review", "thermonuclear review", "deep code quality audit", or "harsh maintainability review", or when the standard review flow escalates a structural concern. Opt-in only — do not auto-run it on every diff; it is meant to be invoked deliberately. Read-only: it reports findings and hands each fix to a fixer, it does not edit code itself.

Lint every `SKILL.md` under `skills/` (and optionally `dev-skills/`) for the contract any agent runtime expects — frontmatter `name:` matches dir name, `description:` exists and is dense, no surviving `{{PLACEHOLDER}}` strings (except in declared template files), every relative markdown link resolves, every declared `resources/` / `scripts/` path actually exists. Pure read-only — reports findings, exits 1 on errors. Use before committing changes that touched a skill body, or as a quick repo-wide health check. Faster + cheaper than the broader `vinta-update-project-skills` flow.

Walk a repository and produce a structured inventory of its languages, frameworks, build tools, test setups, deploy targets, monorepo shape, env model, multi-tenancy patterns, and CI providers. Used by [vinta-bootstrap-ai-tools](../vinta-bootstrap-ai-tools/SKILL.md) as the first step before drafting AGENTS.md / sub-agents / skills, but also runnable standalone when you want a quick "what is this codebase made of" report. Produces an in-memory inventory that downstream skills consume; does not write files.

Refresh the user's project skills under `ai-tools/skills/` against the latest versions in this `vinta-ai-workflows` repo. Detects which project skills came from the bundled foundation set or stack templates, computes a per-file diff against the current source, presents the proposed changes, and only applies them after the user explicitly accepts each one. Skills the user authored themselves (no matching upstream source) are detected and left alone. Use after pulling a new version of `vinta-ai-workflows` to bring an existing project up to date without re-running the full bootstrap. Read-only by default — every write is gated on explicit user approval.

Install the multi-vendor `setup-ai-tools.mjs` script in the target project, wire up a `pnpm setup:ai-tools` (or equivalent) script alias, ensure the YAML parser dependency is present, then run the script to generate per-vendor AGENTS.md / skill / sub-agent files. Final step of [vinta-bootstrap-ai-tools](../vinta-bootstrap-ai-tools/SKILL.md). Idempotent — safe to re-run after editing canonical sources.

Synthesize `ai-tools/AGENTS.md` from the inventory produced by [vinta-analyze-codebase](../vinta-analyze-codebase/SKILL.md) plus a focused interview for what the analysis can't see. Used by [vinta-bootstrap-ai-tools](../vinta-bootstrap-ai-tools/SKILL.md) as step 2; also runnable standalone to refresh AGENTS.md after a major refactor. Project-agnostic — sections are the same shape across stacks, content adapts. Symlinked into root `AGENTS.md` so Claude Code, Cursor, Codex, VS Code Copilot all read it natively.

Cut a release of `vinta-ai-workflows` — pick patch / minor / major / alpha bump, close the in-progress CHANGELOG section (stable only — alpha keeps it open), bump `package.json.version`, commit, tag, push. Asserts pre-flight conditions (clean working tree, on `main`, fetched, CHANGELOG section non-empty, schema enums match every shipped foundation skill, version bump matches the kind of change). Surfaces the npm publish command for the user to run manually — never auto-publishes. Alpha releases use `--tag alpha` dist-tag. Use when the user says "release", "cut a release", "tag 0.1.4", "alpha release", "0.2.0-alpha1", "publish".

Cut a new major version of a JSON Schema under `schemas/<name>.v<N>.schema.json` → `<name>.v<N+1>.schema.json` for a breaking change (removed required field, narrowed enum, type change). Copies the file, applies the breaking diff to v<N+1>, leaves v<N> in place during the deprecation window, and walks every consumer (skills bodies, `# yaml-language-server: $schema=...` directives, validators, sample payloads) to read both versions or migrate to v<N+1>. Updates `schemas/README.md` inventory and the package SemVer (major bump). Use only for genuinely breaking changes — additive fields and optional new properties belong in v<N> patch / minor releases.

Author `ai-tools/agents/*.yaml` for the target project. Always emits the foundation trio (`implementer`, `reviewer`, `fixer`); adds stack-specific specialists (e.g. `deploy-author` for Medplum, `migration-author` for Django) when the inventory from [vinta-analyze-codebase](../vinta-analyze-codebase/SKILL.md) matches a stack template under [bootstrap-ai-tools/resources/stacks/](../vinta-bootstrap-ai-tools/resources/stacks/). Each YAML follows the schema documented in `ai-tools/agents/README.md` so the setup script can generate per-vendor copies.

Bring a project up to date with the latest `vinta-ai-workflows` package version. Reads the project's `.vinta-ai-workflows.yaml` (the single source of truth for which surface area is enabled), reads the cloned package's `CHANGELOG.md` to enumerate releases since the project's recorded version, classifies each change against the project's opt-in surface (affects-project / opt-in-offer / config-schema-change / not-applicable), shows per-change diffs, asks the user one `AskUserQuestion` per change (`Apply` / `Skip` / `Show diff`), applies approved changes (re-render templates, add new foundation skills, patch setup script, migrate config schema), and bumps `vinta_ai_workflows_version` + `last_synced_at` at the end. Layers on top of [vinta-update-project-skills](../vinta-update-project-skills/SKILL.md), which it invokes for foundation-skill body diffs. Use after `npm update vinta-ai-workflows` or pulling a newer git+ssh ref.

Author a new foundation skill under `skills/vinta-derive-skills/resources/foundation-skills/<name>/` and wire it through every place the orphan-prevention contract requires (schema enum, bootstrap interview, derive-skills bucket, foundation-shape lists, outputs tree, CHANGELOG). Use when the user wants to add a project-agnostic skill that ships verbatim into target projects' `ai-tools/skills/` (or a template-rendered one, or an opt-in ask-first one). Walks the full schema-ripple checklist from `AGENTS.md` so no consumer is left half-wired.

Author a new stack template under `skills/vinta-bootstrap-ai-tools/resources/stacks/<stack>/notes.md` and wire it through the orchestrator's stack table + `vinta-analyze-codebase` detection signals + (when needed) the schema's `stacks` examples + CHANGELOG. Stack notes describe **categories** (skill + agent), **detection signals**, and **placeholders** the orchestrator asks the user about — they do NOT ship ready-made content. Use when adding support for a new framework / runtime that the bootstrap flow should recognize (e.g. SvelteKit, Phoenix, Rails, tRPC monorepo).

Author a safe operational one-off script (data backfill, ad-hoc cleanup, schema fixup, tenant migration outside the regular migration pipeline). Enforces a strict contract every script must follow — dry-run by default, idempotent on re-run, batched DB operations, streamed reads, segmented CSV backups before destructive writes, interruption-safe, and console + filesystem + S3 logging that survives the interruption. Generates a per-script folder (`<scripts_dir>/<YYYY-MM-DD>-<name>/`) containing the subclass + tests + (when a sister `run-one-off-script-<stack>` skill is invoked) the stack-specific runner artefact (Django mgmt command, Jupyter notebook, Medplum bot, Vercel Function, Lambda, K8s Job). The bundled `BaseOneOffScript` class delegates every runtime-specific concern (logging sink, lease, stop signal, artifact upload) to a pluggable `Runtime` interface — `LocalRuntime` is the default for plain CLI invocation; stack runner skills ship their own adapters. Use whenever the user asks for a one-off script, b

Find existing implementation plans and feature specs scattered across a project (`docs/`, `specs/`, `plans/`, root markdown, branch-named files, etc.) and migrate them to the canonical layout `ai-plans/YYYY-MM-DD-{FEATURE_NAME}_{PLAN|SPEC}.md`. Reads each candidate, proposes a target path (date + feature name + classification PLAN vs SPEC), shows the rename diff, and only renames after the user explicitly accepts each one. Run as step 6 of [vinta-bootstrap-ai-tools](../vinta-bootstrap-ai-tools/SKILL.md), or standalone any time afterwards. Read-only by default — every move is gated on per-file approval.