{"id":50817269,"url":"https://github.com/vintasoftware/vinta-ai-workflows","last_synced_at":"2026-06-13T10:33:45.953Z","repository":{"id":362077850,"uuid":"1229445430","full_name":"vintasoftware/vinta-ai-workflows","owner":"vintasoftware","description":"A set of skills to configure the AI workflow on a new or existing project on Vinta Software","archived":false,"fork":false,"pushed_at":"2026-06-02T12:40:18.000Z","size":548,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T14:23:30.634Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vintasoftware.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-05T03:47:06.000Z","updated_at":"2026-06-02T12:40:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vintasoftware/vinta-ai-workflows","commit_stats":null,"previous_names":["vintasoftware/vinta-ai-workflows"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/vintasoftware/vinta-ai-workflows","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintasoftware%2Fvinta-ai-workflows","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintasoftware%2Fvinta-ai-workflows/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintasoftware%2Fvinta-ai-workflows/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintasoftware%2Fvinta-ai-workflows/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vintasoftware","download_url":"https://codeload.github.com/vintasoftware/vinta-ai-workflows/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintasoftware%2Fvinta-ai-workflows/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34281700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-13T10:33:45.223Z","updated_at":"2026-06-13T10:33:45.939Z","avatar_url":"https://github.com/vintasoftware.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vinta-ai-workflows\n\nBootstrap AI tooling — AGENTS.md, sub-agents, project skills, multi-vendor wiring — into any project, then get out of the way.\n\nDistributed as a private 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).\n\n## Quick start\n\n```bash\n# 1. Add the package to the target project.\ncd ~/code/my-project\nnpm install -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git#0.1.0\n\n# 2. Install the bootstrap skills for your AI tool.\nnpx vinta-ai-workflows install --tool claude-code\n#   or --tool agents (covers Codex + Cursor + Copilot in one go)\n#   or --tool all\n\n# 3. Open the project in the AI tool, run the orchestrator.\n#   Claude Code → /vinta-bootstrap-ai-tools\n\n# 4. Review and commit the generated layout.\ngit add ai-tools/ AGENTS.md .claude/ .codex/ .cursor/ .github/ .agents/\ngit commit -m \"Bootstrap ai-tools layout\"\n\n# 5. Remove the builder skills — one-shot done.\nnpx vinta-ai-workflows uninstall --tool claude-code\nnpm uninstall vinta-ai-workflows\n```\n\nPrerequisites: Node ≥ 18, SSH access to the private repo (or a registry token if your team mirrors it).\n\n## Why this is useful\n\nAfter bootstrap, the project ships with **three foundation skills** that take a feature from raw prompt to merged code:\n\n```\n   raw prompt / ticket\n            │\n            ▼\n   ┌─────────────────┐    ai-plans/YYYY-MM-DD-FEATURE_NAME_SPEC.md\n   │   create-spec   │───►  what + why (Business Context, Hypothesis,\n   └─────────────────┘      Use-cases, Acceptance, Negative scope,\n            │               Open questions, Risks)\n            ▼\n   ┌─────────────────┐    ai-plans/YYYY-MM-DD-FEATURE_NAME_PLAN.md\n   │  plan-feature   │───►  how + when (Goals, Decisions, Data Model,\n   └─────────────────┘      Phased Rollout, Touch List, Risks)\n            │\n            ▼\n   ┌─────────────────┐    one stacked branch per phase + tracking file\n   │  implement-plan │───►  plan/\u003cfeature\u003e/phase-1, phase-2, ...\n   └─────────────────┘      pushed to GitHub / GitLab / etc.\n```\n\nYou also get: an `AGENTS.md` tuned to the codebase, 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.\n\n**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`](#staying-in-sync-with-upstream) — 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.\n\nThe 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.\n\n## The AI workflow after bootstrap\n\n### 1. Spec generation — `create-spec`\n\n**Trigger:** `/create-spec`, \"write a spec for X\", \"draft a spec for the new \u003cfeature\u003e\". Runs as soon as you have a prompt or ticket and need structure before planning.\n\n**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.\n\n**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`.\n\n**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.\n\n### 2. Implementation plan generation — `plan-feature`\n\n**Trigger:** `/plan-feature`, \"plan the \u003cfeature\u003e\", \"break this spec into phases\". Reads the matching `*_SPEC.md` (paired by date + feature name) before drafting.\n\n**What it does:** translates the spec into a phased delivery plan. Output sections:\n\n- **Goals + Non-goals** — what's in / out of scope.\n- **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.\n- **Data Model Changes** — migrations + rollout order.\n- **Phased Rollout** — each phase declares: `id`, `title`, `goal`, `Suggested AI model` (per vendor — implement-plan picks the cheapest available), `reusable_skills` (other project skills the implementer should invoke), `Changes`, `Tests`, `Acceptance`, plus flags for `is_cross_repo` and `is_flag_removal` (both deferred).\n- **Risk \u0026 Rollout Notes**, **Open Questions**, **Touch List**.\n\nPhases 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.\n\n**Output:** `ai-plans/YYYY-MM-DD-FEATURE_NAME_PLAN.md`. Same `FEATURE_NAME` prefix as the spec so `ls ai-plans/` groups pairs.\n\n**Hand-off:** review the plan with the team — feature-flag decision, phase boundaries, cross-repo dependencies, rollback story. Once approved, move to `implement-plan`.\n\n### 3. Phase-by-phase execution — `implement-plan`\n\n**Trigger:** `/implement-plan`, \"implement the \u003cfeature\u003e 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).\n\n**Per-phase loop** (Step 1 of the skill):\n\n1. **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.\n2. **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.\n3. **Spawn the right agent type.** `implementer` by default; switch to a stack-specialist (`migration-author`, `deploy-author`, etc.) when that role's risk dominates the phase.\n4. **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.\n5. **Three-layer review** before merging the phase branch:\n   - **Layer 1 — mechanical**: read every diff, confirm outer gate ran green, scope-creep + secrets scan.\n   - **Layer 2 — plan compliance**: walk every \"Changes\" item, every \"Tests\" entry, the Acceptance line, AGENTS.md conventions, any reusable-skill compliance, feature-flag wiring, cross-phase consistency.\n   - **Layer 3 — independent reviewer**: spawn a fresh `reviewer` agent with no implementation context. Findings triaged BLOCKER / SHOULD-FIX / NIT.\n6. **Fix loop**: each finding → spawn a `fixer` agent (separate session) that re-runs inner + outer loops; orchestrator never edits directly. Repeat until all three layers are clean.\n\n**Branch model — one branch per phase, stacked:**\n\n```bash\n# First executed phase — branches from the default branch.\ngit checkout main \u0026\u0026 git pull --ff-only\ngit checkout -b plan/\u003cfeature-kebab\u003e/phase-1\n# implementer's commits land here\ngit push -u origin plan/\u003cfeature-kebab\u003e/phase-1\n\n# Phase 2 stacks on phase 1 — never branches back to main.\ngit checkout plan/\u003cfeature-kebab\u003e/phase-1\ngit checkout -b plan/\u003cfeature-kebab\u003e/phase-2\ngit push -u origin plan/\u003cfeature-kebab\u003e/phase-2\n\n# Phase 3 stacks on phase 2, etc.\n```\n\nEach phase's PR (or branch, depending on the project's PR policy captured at bootstrap) targets the previous phase's branch, not `main`. This keeps the diff per PR scoped to a single phase, makes review manageable, and lets the team merge phases sequentially as approvals land — earlier phases ship to production while later ones are still in review.\n\n**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/\u003cfeature-kebab\u003e` 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`](schemas/vinta-ai-workflows-config.v1.schema.json) for the field definition.\n\n**Tracking file** — `ai-plans/TRACKING_\u003cfeature-kebab\u003e.md`. The orchestrator writes it from `git diff` + the agent's report (not the agent's narration). Records: completed phases (status, model used, branch, base, e2e+screenshots when applicable, 5–15 line summary), current phase, remaining phases, deferred phases. Acts as the durable context handoff between phase prompts. Deleted on plan completion.\n\n**Phases the orchestrator never auto-executes:**\n\n- **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.\n- **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.\n\n**Failure handling:** if a phase fails Layer 1 / 2 / 3 + fixer escalation, orchestrator stops, posts the agent's report, and asks how to proceed. It does not silently rerun, skip, or escalate models without the user.\n\n#### PR creation: single flow via `prs-context` + `open-pr.sh`\n\n`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](skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/scripts/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`.\n\nWhat actually happens depends on two signals:\n\n1. **Project PR creation policy** — captured at bootstrap. Either \"agents create PRs\" or \"branches only, humans open PRs\".\n2. **`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.\n\n| PR policy | inline comments | What the **Open PR via context file** step does |\n|---|---|---|\n| agents create | off | Write file (empty `# Comments`); run `open-pr.sh` → PR opened, no inline comments. |\n| agents create | on  | Write file (full); run `open-pr.sh` → PR opened, all comments posted. |\n| branches only | off | Skip the step. Human opens PR manually. |\n| branches only | on  | Write file (durable record); **don't** run script. Publish later via `open-pr-from-context` from a CLI-equipped session. |\n\n`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).\n\n**Required tools** for `open-pr.sh` (install before any policy = \"agents create\" run, and on any session that will publish a `pending` file later):\n\n- **`bash` 4+** — already present on macOS (3.2 ships by default; install 4+ via `brew install bash`) and Linux.\n- **`git`**.\n- **[`yq`](https://github.com/mikefarah/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.\n- **[`jq`](https://stedolan.github.io/jq/)** — used to iterate the comment list and parse `gh` / `glab` JSON output.\n- **One of [`gh`](https://cli.github.com)** (for GitHub) **or [`glab`](https://gitlab.com/gitlab-org/cli)** (for GitLab), authenticated.\n\nInstall commands:\n\n```bash\n# macOS\nbrew install yq jq gh                    # GitHub\nbrew install yq jq glab                  # GitLab\n\n# Debian / Ubuntu\nsudo apt install yq jq                   # check yq version — some distros ship the Python wrapper;\n                                          # if so, install Mike Farah's binary from the GitHub releases.\n# gh: see cli.github.com#installation\n# glab: see gitlab.com/gitlab-org/cli#installation\n\n# Auth (once per machine)\ngh auth login                            # GitHub\nglab auth login                          # GitLab\n```\n\nThe script bails early with `missing dependency: \u003cname\u003e` 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.\n\n### Putting it together\n\n```\n# Day 1 — discovery + scoping\n/create-spec           # interview → ai-plans/2026-05-12-CHECKOUT_FLOW_SPEC.md\n# review with team, iterate\n\n# Day 2 — planning\n/plan-feature          # reads spec → ai-plans/2026-05-12-CHECKOUT_FLOW_PLAN.md\n# review feature flag, phase boundaries, rollback story\n\n# Day 3+ — execution\n/implement-plan        # orchestrator runs phase 1 → phase 2 → ... → phase N-1\n                       # each phase: implementer + reviewer + fixer agents,\n                       # one stacked branch + PR per phase\n# merge phase branches sequentially as approvals land\n# soak phase 1 in prod → soak phase 2 → ...\n# once feature flag's flip-on criterion is met:\n#   invoke the flag-removal skill on the deferred phase N\n```\n\nStandalone 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).\n\n## Cheat sheet — what lands in your project\n\nQuick inventory of what `vinta-bootstrap-ai-tools` writes into your repo's `ai-tools/` layout (and exposes via per-vendor wiring at `.claude/skills/`, `.agents/skills/`, etc.). Two disclaimers up front:\n\n\u003e **Optional foundation skills are gated by the bootstrap interview.** `systematic-debugging`, `add-e2e-test`, `add-env-var`, and `add-one-off-script` ship **only** if the user says yes during `vinta-bootstrap-ai-tools` Step 0 (or later opts in via `vinta-sync-ai-tools`). They are not in every bootstrapped project. The opt-in is recorded in `.vinta-ai-workflows.yaml` under `foundation_skills.*.enabled` and is sticky across syncs.\n\u003e\n\u003e **Stack-specific skills and sub-agents are user-supplied.** This package ships **detection signals + category lists** per stack ([resources/stacks/](skills/vinta-bootstrap-ai-tools/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.\n\n### Foundation skills (project-agnostic)\n\nLand at `ai-tools/skills/\u003cname\u003e/SKILL.md`. Always-on unless flagged optional.\n\n| Skill | Status | What it does |\n|---|---|---|\n| [`create-spec`](skills/vinta-derive-skills/resources/foundation-skills/create-spec/SKILL.md) | always | Interview-driven spec doc from a raw prompt / ticket → `ai-plans/YYYY-MM-DD-FEATURE_NAME_SPEC.md`. |\n| [`plan-feature`](skills/vinta-derive-skills/resources/foundation-skills/plan-feature/SKILL.md) | always | Phased delivery plan from the matching spec → `ai-plans/YYYY-MM-DD-FEATURE_NAME_PLAN.md`. |\n| [`create-qa-use-cases`](skills/vinta-derive-skills/resources/foundation-skills/create-qa-use-cases/SKILL.md) | always | Bootstrap `QA_USE_CASES.md` from the active spec / plan. Called by `plan-feature` when missing. |\n| [`open-pr-from-context`](skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/SKILL.md) | always | Publish a `.vinta-ai-workflows/prs-context/\u003cfeature\u003e/\u003cphase\u003e.md` file as a real PR + inline comments via `gh` / `glab`. Bundles [`open-pr.sh`](skills/vinta-derive-skills/resources/foundation-skills/open-pr-from-context/scripts/open-pr.sh). |\n| `implement-plan` | always (generated) | Phase-by-phase plan execution. Generated from a template with project commands + branch / PR / co-author policy. |\n| `amend-plan` | always (generated) | History-rewriting companion to `implement-plan` — revises in-flight plans, amends prior-phase commits, force-pushes, rebases stacked downstream branches. |\n| `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. |\n| `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. |\n| `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). |\n| [`add-one-off-script`](skills/vinta-derive-skills/resources/foundation-skills/add-one-off-script/SKILL.md) | **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. |\n\n### Foundation sub-agents (project-agnostic)\n\nLand at `ai-tools/agents/\u003cname\u003e.yaml` (canonical YAML; `setup-ai-tools.mjs` emits per-vendor copies into `.claude/agents/`, `.cursor/`, `.codex/`, `.github/`). Always-on trio.\n\n| Agent | Access | Role |\n|---|---|---|\n| `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. |\n| `reviewer` | read-only | Adversarial reviewer. Reads phase + diff + AGENTS.md, outputs `BLOCKER` / `SHOULD-FIX` / `NIT` findings with `file:line`. Does not edit. |\n| `fixer` | read-write | Applies one reviewer finding (or one named test failure). Smallest correct change, re-runs gates, reports. |\n\nStack templates may add specialists like `migration-author` (Django) or `deploy-author` (Medplum) — see disclaimer above.\n\n## Staying in sync with upstream\n\nBootstrap 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.**\n\n### The flow at a glance\n\n```bash\n# 1. Pull the new package version (or update the git+ssh ref).\nnpm update vinta-ai-workflows\n\n# 2. Run the sync skill from your AI tool.\n#    Claude Code → /vinta-sync-ai-tools\n```\n\nThat'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.\n\n### How it stays safe\n\nThe 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`](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:\n\n| Bucket | Meaning | Default |\n|---|---|---|\n| `affects-project` | Touches enabled surface area (e.g. an enabled foundation skill's body changed). | One prompt per change: `Apply` / `Skip` / `Show diff`. |\n| `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. |\n| `config-schema-change` | New field, schema migration, or major-bump. | Migrated automatically; required new fields prompt for a value. |\n| `tooling` | Setup-script / gitignore / packaging tweaks. | Batched under one prompt. |\n| `not-applicable` | Project opted out, or change targets an unused stack. | Listed for transparency, not applied. |\n\nEvery 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.\n\nAt the end of a run:\n\n- Approved changes apply (templates re-rendered from the config, new foundation skills copied, config schema migrated, setup script re-run idempotently).\n- Every YAML file in the project re-validates against its schema.\n- `vinta_ai_workflows_version` + `last_synced_at` get bumped in `.vinta-ai-workflows.yaml`.\n- A final report lists Applied / Skipped / Newly disabled / Orphan diffs (changes without changelog entries — flagged, never auto-applied).\n\n### Two related but narrower flows\n\n- [`vinta-update-project-skills`](skills/vinta-update-project-skills/SKILL.md) — 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.\n- `vinta-ai-workflows update` (CLI, see [Update](#update) below) — refreshes the **builder skills themselves** (the `vinta-*` set in `.\u003cvendor\u003e/skills/`) when running with `--copy`. Symlink installs already track package updates automatically.\n\n### When to sync\n\nAfter any of these, schedule a sync run:\n\n- `npm update vinta-ai-workflows` or pulling a newer git+ssh ref.\n- A teammate bumped the version pin in `package.json`.\n- The package shipped a new foundation skill, stack, or schema field you want to opt into.\n- The project's `.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.\n\nIf `OLD_VERSION === NEW_VERSION`, the skill prints \"already up to date\" and exits without touching anything.\n\n## Running the bootstrap skills\n\nSkills 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:\n\n| Tool | Invocation |\n|---|---|\n| Claude Code | `/vinta-bootstrap-ai-tools` (in chat) |\n| OpenAI Codex | `/skills` then pick, or `$vinta-bootstrap-ai-tools` mention |\n| Cursor | `/vinta-bootstrap-ai-tools` in Agent chat |\n| VS Code + Copilot | `/vinta-bootstrap-ai-tools` in Copilot Chat |\n\nStart with `vinta-bootstrap-ai-tools` — it orchestrates the others.\n\nTo bring a previously-bootstrapped project up to date with a newer package version, invoke `vinta-sync-ai-tools` — see [Staying in sync with upstream](#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`](skills/vinta-update-project-skills/SKILL.md).\n\n## Install variants\n\nThe package is private. Two install paths.\n\n### A. From git+ssh (no registry needed)\n\nEach developer's GitHub SSH key needs read access to the repo. Then:\n\n```bash\n# inside the target project\nnpm  install -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git\npnpm add  -D   git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git\nyarn add  -D   git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git\nbun  add  -d   git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git\n```\n\nPin a tag/commit when you want determinism:\n\n```bash\nnpm install -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git#0.1.0\n```\n\n### B. From GitHub Packages (if/when published)\n\nIn the project root, add `.npmrc`:\n\n```ini\n@vinta:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n```\n\nExport `GITHUB_TOKEN` (a Personal Access Token with `read:packages` and the `repo` scope for private repos), then:\n\n```bash\nnpm install -D vinta-ai-workflows\n```\n\n### One-shot via npx (no install)\n\nIf you don't want the dep tracked in `package.json`:\n\n```bash\nnpx -y -p git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git \\\n  vinta-ai-workflows install --tool all\n```\n\n### Picking a tool\n\nAfter install, the bin is available at `node_modules/.bin/vinta-ai-workflows`:\n\n```bash\nnpx vinta-ai-workflows install --tool claude-code\n# or:\npnpm vinta-ai-workflows install --tool claude-code\n./node_modules/.bin/vinta-ai-workflows install --tool claude-code\n```\n\n`--tool` accepts: `claude-code`, `codex`, `cursor`, `copilot`, `agents`, `all`.\n\n**Universal install (Codex + Cursor + Copilot)** — `.agents/skills/` is recognized by all three. A single `--tool agents` install covers them:\n\n```bash\n# One install, three tools.\nnpx vinta-ai-workflows install --tool agents\n\n# Pair with Claude Code (which only reads .claude/skills/).\nnpx vinta-ai-workflows install --tool claude-code\n```\n\n### Copy instead of symlink\n\nBy 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/`):\n\n```bash\nnpx vinta-ai-workflows install --tool all --copy\n```\n\nEach copied skill gets a `.installed-by-vinta-ai-workflows` marker file used by `uninstall` and `update` to recognize what the script owns.\n\n### Subset of skills\n\n```bash\nnpx vinta-ai-workflows install --tool claude-code \\\n  --skills vinta-bootstrap-ai-tools,vinta-write-agents-md\n```\n\n`npx vinta-ai-workflows list` prints all available skills.\n\n### Dry run\n\n```bash\nnpx vinta-ai-workflows install --tool all --dry-run\n```\n\nPrints planned actions, touches nothing.\n\n## Update\n\n\u003e **Looking to bring a bootstrapped project up to date with the latest skills, templates, and best practices?** That's [Staying in sync with upstream](#staying-in-sync-with-upstream) — `vinta-sync-ai-tools`, invoked from the AI tool. The CLI `update` command described here is narrower: it only refreshes the builder skills (the `vinta-*` set under `.\u003cvendor\u003e/skills/`) and is mostly only relevant for `--copy` installs.\n\nRefresh installed builder skills against the latest package version:\n\n```bash\n# 1. Pull the new package version.\nnpm  update vinta-ai-workflows\npnpm update vinta-ai-workflows\n# Or for git+ssh, just re-install with the new ref:\nnpm install -D git+ssh://git@github.com:vintasoftware/vinta-ai-workflows.git#v0.2.0\n\n# 2. Re-link / re-copy builder skills (only needed for --copy installs).\nnpx vinta-ai-workflows update --tool all\n\n# 3. From your AI tool, sync the project against the new package version.\n#    Claude Code → /vinta-sync-ai-tools\n```\n\nStep 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.\n\nStep 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](#staying-in-sync-with-upstream) for the full flow.\n\n## Uninstall\n\nAfter the bootstrap is committed, remove the skills:\n\n```bash\nnpx vinta-ai-workflows uninstall --tool all\n```\n\nThen drop the package itself:\n\n```bash\nnpm  uninstall vinta-ai-workflows\npnpm remove    vinta-ai-workflows\n```\n\n### What `uninstall` removes\n\nThe uninstaller is conservative on purpose:\n\n- **Symlinks** are removed only if their target points back into the package's `skills/` directory (or the link is dangling).\n- **Copied directories** are removed only if they contain the `.installed-by-vinta-ai-workflows` marker file.\n- **Anything else** (hand-authored skills, third-party skills, files lacking the marker) is left in place with a warning.\n\nEmpty `.\u003cvendor\u003e/skills/` directories are removed after the last managed entry leaves; the parent `.claude/`, `.agents/`, etc. are left alone since they likely hold other content.\n\n### Manual uninstall (no Node available)\n\n```bash\nSKILLS=\"vinta-analyze-codebase vinta-bootstrap-ai-tools vinta-derive-skills \\\n        vinta-derive-subagents vinta-install-ai-tools-setup \\\n        vinta-update-project-skills vinta-write-agents-md\"\n\nfor vendor in .claude/skills .agents/skills .cursor/skills .github/skills; do\n  for skill in $SKILLS; do\n    rm -rf \"$vendor/$skill\"\n  done\n  rmdir \"$vendor\" 2\u003e/dev/null\ndone\n```\n\n## Per-tool paths\n\nVerified against official docs as of 2026-05.\n\n| Tool | Project path | Source |\n|---|---|---|\n| Claude Code | `.claude/skills/` | native |\n| OpenAI Codex | `.agents/skills/` | [docs](https://developers.openai.com/codex/skills) |\n| Cursor | `.cursor/skills/` (also `.agents/skills/`) | [docs](https://cursor.com/docs/skills) |\n| VS Code + Copilot | `.github/skills/` (also `.claude/skills/`, `.agents/skills/`) | [docs](https://code.visualstudio.com/docs/copilot/customization/agent-skills) |\n\nCodex walks `.agents/skills/` from cwd up to the repo root, so an install at the project root covers nested working directories too.\n\n## CLI reference\n\n```\nvinta-ai-workflows \u003ccommand\u003e [options]\n\nCommands:\n  install     Place skills under \u003ctarget\u003e/.\u003cvendor\u003e/skills/\n  update      Re-install (uninstall + install) so latest source content lands\n  uninstall   Remove skills (only artifacts created by this CLI)\n  list        List available skills\n\nOptions:\n  --tool \u003cname\u003e       claude-code | codex | cursor | copilot | agents | all\n                      Aliases: claude, openai-codex, vscode, vscode-copilot,\n                               github-copilot, universal\n  --target \u003cdir\u003e      Project root (default: cwd)\n  --skills \u003ca,b,c\u003e    Subset of skills (default: all)\n  --copy              Copy instead of symlink\n  --dry-run, -n       Plan only\n  --help, -h          Help\n```\n\nProject 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.\n\n## Repo internals\n\n\u003e \"Skills\" here = the [Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-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.\n\n```\nvinta-ai-workflows/\n├── package.json             # vinta-ai-workflows — exposes vinta-ai-workflows bin\n├── vinta-ai-workflows.mjs    # CLI: install / update / uninstall / list\n├── README.md\n└── skills/\n    ├── vinta-analyze-codebase/\n    ├── vinta-bootstrap-ai-tools/   # orchestrator — calls the others\n    ├── vinta-derive-skills/\n    ├── vinta-derive-subagents/\n    ├── vinta-install-ai-tools-setup/\n    ├── vinta-update-project-skills/\n    └── vinta-write-agents-md/\n```\n\n`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.\n\n### Why the `vinta-` prefix?\n\nOnce installed, these skills sit alongside the user's own project skills in the same `.\u003cvendor\u003e/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.\n\n### Why one-shot\n\nThe `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.\n\n→ Install, run once via `/vinta-bootstrap-ai-tools` (or whatever invocation your tool uses), commit the generated `ai-tools/` layout, then `uninstall`.\n\nWhen this package gains new versions later, [`vinta-sync-ai-tools`](#staying-in-sync-with-upstream) 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.\n\n### Updating skills in this repo\n\nIf you modify a `vinta-*` skill source under `skills/`:\n\n- **Symlink installs** (default): consumers get updates as soon as their `node_modules/vinta-ai-workflows/` refreshes (next `npm install` / `git+ssh` re-pull).\n- **Copy installs** (`--copy`): consumers must re-run `vinta-ai-workflows update` with the same flags. The CLI removes the previous copy and writes fresh content + marker.\n\nTo bring a bootstrapped project up to date with newer builder-skill source, run [`vinta-sync-ai-tools`](#staying-in-sync-with-upstream) 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`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvintasoftware%2Fvinta-ai-workflows","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvintasoftware%2Fvinta-ai-workflows","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvintasoftware%2Fvinta-ai-workflows/lists"}