About the setup commands
vinaya init, vinaya doctor, vinaya upgrade and vinaya eject share one engine. Every command that writes shows you the complete diff first and waits for your confirmation.
- Nothing runs when the package is installed.
PATHis never touched.- Branch protection is printed as a recommendation, never applied.
How it works
- 1
Detect
The command reads the repository and
vinaya.at the repository root. It never walks up to a parent folder, so a nested fixture never picks up an ancestor's config.config. json - 2
Build the operations
It builds a typed list of the operations it would perform.
- 3
Show the diff
It renders the complete diff. With
--dry-runit stops here and writes nothing. - 4
Confirm and apply
After you confirm, it applies the operations.
- 5
Record ownership
It records what Vinaya owns in the
managedmanifest insidevinaya..config. json upgraderegenerates only what the manifest lists, andejectremoves only what it lists.
The commands
| Command | Flags | Writes |
|---|---|---|
vinaya init | --dry-run, --yes, - | Yes, after confirmation |
vinaya init product <name> | --path <path>, --dry-run, --yes | One registry row and one projects entry |
vinaya doctor | --json | Never |
vinaya upgrade | --dry-run, --yes | Yes, after confirmation |
vinaya eject | --dry-run, --yes | Removes, after confirmation |
Installs Vinaya into the repository.
vinaya init --dry-run
vinaya initRequires a git repository and an authenticated gh. gh is not needed for --dry-run, or when there is no GitHub origin (label creation is then skipped).
Refuses a custom core.hooksPath. It never overwrites a file it does not own.
| Group | Files |
|---|---|
| Workflows | ., vinaya-, vinaya-, vinaya-, vinaya- |
| Git hooks (managed blocks) | pre-commit, pre-push, commit-msg in .vinaya/hooks/ (tracked, then git config core.), or in .husky/ or .git/hooks/ |
| Config | vinaya.: starter rings (both true), empty checks, starter briefSchema, then managed |
| Doctrine pointer | AGENTS.md, CLAUDE.md |
| Doc ownership | . |
| Scaffold folders | vinaya/, vinaya/ |
--agents includes skills | . |
--agents includes claude | ., ., . and . (Stop hook), .mcp.json (task-tools server) |
--agents includes gemini | ., . |
| Labels | Created if absent, never modified (tier, needs, type and other fixed labels) |
| Printed only | Branch protection, CODEOWNERS and principals recommendations; a note that agent-native commands need vinaya on PATH |
The manifest is written as soon as the files are on disk, before the labels, so a label failure never leaves files unowned.
Configuration
| Key | Used by |
|---|---|
managed | All four commands |
ci.setup | init, upgrade, doctor (added to the generated workflows) |
briefSchema.ack | doctor |
rings | upgrade (the version-3 migration) |
projects | init product, doctor |
See The file and its keys for each key.