vince-setup

Files (1)

• SKILL.md

SKILL.md (first lines)

---
name: vince-setup
description: Create or refresh a verified Vince project/workspace profile containing real commands, branch and version rules, security boundaries, wire rigs, traps, and exact model mappings. Use for Vince onboarding, missing profiles, or repository convention drift.
---

# Vince — Setup

For a native plugin installation, first read `reference/plugin-tools.md` to locate bundled
scripts and use the read-only tools without reinstalling global skills.

Before the final user-facing response, apply `reference/brief.md`.

`vince-implement` and `vince-review` are deliberately project-agnostic. Everything specific to
a codebase lives in one file: **`.vince/profile.md`** at the project root. This skill writes it.

A profile is only useful if it is **true**. Every command you record must be one you actually
ran and watched succeed in this repo. A profile full of plausible-looking commands is worse than
no profile, because the next session will trust it.


## Communication and efficiency

Profiles are plain facts. Load `reference/voice.md` only for the user-facing findings report. Load
`reference/token-discipline.md` only for a large workspace inventory; group by stack, bound output,
and write only verified differences.

## Which mode are you in?

Decide this first, because it changes what you are allowed to claim.

| You are onboarding | Mode | Writes | Template |
|--------------------|------|--------|----------|
| A single repo | **repo** | the resolved repo profile | `profile.template.md` |
| A hub with many repos under it | **workspace** | `<workspace>/.vince/profile.md` | `workspace-profile.template.md` |
| A repo inside a hub that already has a profile | **repo (inheriting)** | the resolved repo profile, verified values only | `profile.template.md` |

**Resolve the repo path first — never assume `.vince/` is in the repo:**

```bash
python <toolkit>/scripts/install.py where --repo <repo>
```

By default per-repo config lives in a store outside the repo (`~/.vince/repos/<key>/`), keyed by
the origin remote. Work repos stay clean: nothing untracked, nothing to gitignore, nothing to
commit by accident. A repo that already has its own `.vince/profile.md` keeps using it — that is
the opt-in for repos you own and want the config committed for a team.

Signs you are in a hub: repos live in a sibling directory (`../repos/`, `packages/`, `services/`),
there is a repo manifest, or the user says so. If both a hub and a repo need doing, do the hub
first — the repo profile is then only what differs.

**The invariant for workspace mode: a hub profile cannot verify a command.** You are not going to
run a hundred suites from the hub, and a value nobody ran is not evidence. So in workspace mode
every command you record is `(inferred, unverified)` by construction, and you say so in the file.
Verified commands and observed baselines live in repo profiles, written on first touch. Do not
run one repo's suite and generalise it to a stack — that is one data point wearing a uniform.

In **store mode** there is nothing to gitignore, because nothing lands in the repo. Only when the
user has deliberately chosen in-repo config does `.vince/tasks/` need ignoring, and the profile
itself is then worth committing — it is project knowledge, not scratch.

## Discovery pass — workspace mode

Skip to the next section for a single repo.

1. **Map the estate.** Where the repos live, how many, and how to find the owning repo for a
   piece of work (a manifest file, a naming convention, a domain map). This is the section that
   saves the most time later, and it is one you *can* verify.
2. **Identify the stacks**, not the repos. Group by marker — `*.csproj`, `package.json` with
   React, `pyproject.toml`, `go.mod`. For each stack record the *default* commands, read out of
   manifests and CI config. Mark the block `inferred, unverified` and mean it.
3. **Estate-wide facts you genuinely can verify**: integration branch, branch naming, PR host,
   commit convention (`git log` across a few repos), tracker, isolation key, environments,
   memory targets. These are legitimately `verified`.
4. **Dependency order** between repo classes: shared lib → service → consumer → frontend.
5. **`task_root`**: usually the workspace, because work spans repos.
6. **Estate-wide gates and traps** — the additive sections. Ask the user what breaks repeatedly;
   it is usually known and unwritten.
7. **Sections you cannot start** — wire-proof rigs and mutation tooling are the usual two, since
   they need infra, credentials or a running environment. Mark them
   `blocked — <what is needed>`, not blank. A blank section reads as "nobody thought about it";
   `blocked — needs cluster credentials for the dev namespace` reads as a gap with an unblock.

Then stop. Do not attempt per-repo verification from the hub; that is first-touch work, and
claiming it here is exactly the failure this mode is designed to avoid.

## Discovery pass — repo mode

Work through these, running things rather than assuming. Anything you cannot determine is
recorded as `unknown` with a note — never as a guess.

**Inheriting from a hub?** Read the hub profile first, then record **only what differs or what
you verified**. A repo profile that copies the hub file wholesale creates two places to update
and guarantees drift. Run the inherited commands, write down the ones that worked and the
baseline you observed, and leave everything else to inheritance.

1. **Stack and layout.** Manifests (`package.json`, `*.csproj`, `pyproject.toml`, `go.mod`,
   `Cargo.toml`, `pom.xml`, `build.gradle`), the directory layout, whether it is one service or
   several, and where tests live.
2. **Commands, each one verified by running it.** Install/restore, build, unit suite, integration
   suite, E2E suite, lint, format check, type check. Record the exact invocation and, for the
   suite, the baseline counts you observed (`N passed / M failed / K skipped`). If a command
   fails on a clean checkout, that is a finding to report to the user, not something to paper
   over — record it as `broken: <output>`.
3. **Mutation testing.** Does the stack have a tool (StrykerJS/.NET, mutmut, PIT, go-mutesting,
   cargo-mutants), and is it already configured here? Record the **diff-scoped** invocation, not
   the full-suite one - per-task runs are only affordable incrementally. If nothing is
   configured, say whether one exists for the stack and what it would take, then record `none`;
   both skills fall back to hand mutation. Do not install one uninvited.
4. **Branch model.** The integration branch work merges into (`main`, `master`, `dev`,
   `develop`), the branch naming convention, and whether PRs go to a forge (GitHub, GitLab,
   Bitbucket) or elsewhere. `git remote -v` and `git branch -r` tell you most of it.
5. **Tracker and commit convention.** Is there a ticket key pattern in
   `git log --format='%s' -50`? Conventional commits? Nothing at all? Record what the history
   actually does, not what a CONTRIBUTING file wishes it did — and note the difference if they
   disagree.
6. **Versioning.** Does a version live in a manifest, and does CI require it bumped per change?
   Check recent merge commits for a bumped version file.
7. **Data isolation key.** Is this multi-tenant or multi-account? Find the field every query
   filters on (`tenantId`, `orgId`, `workspaceId`, `userId`) — or record `none (single-tenant)`.

From elroykanye/vince-gate, MIT.

More from elroykanye/vince-gate