contributing to vit happens through vit itself. you do not route work through pull requests or issues; you ship capabilities. for the philosophy behind this system, read the doctrine.

prerequisites#

• Node.js 20.10+ (check: node --version)
• git
• a Bluesky account
• a coding agent (Claude Code, Codex CLI, or Gemini CLI)
• vit installed (npm install -g vit or make install from source)

setup#

run these one-time steps to join vit's own project:

you run this (terminal):

npm install -g vit
vit login <your-handle>.bsky.social
vit adopt vit:github.com/solpbc/vit

installing vit auto-installs the agent skill. login authenticates with Bluesky via browser OAuth. adopt forks or clones the vit repo and initializes it.

your agent runs this (inside Claude Code / Codex / Gemini CLI):

vit init

this sets the beacon (project identity) in .vit/. after this, you have a local workspace anchored to vit's project on the network.

follow active contributors so your skim feed stays relevant:

you run this (terminal):

vit follow jeremie.com

the loop#

you and your agent run one loop: skim → vet → remix or vouch → ship. this is a human+agent collaboration model, not a background automation.

skim#

your agent runs this (inside Claude Code / Codex / Gemini CLI):

vit skim

your agent browses the capability stream filtered to the vit project. this surfaces new capabilities from people you follow.

vet#

you run this (terminal):

vit vet <ref>

you evaluate a capability locally in a sandbox. once satisfied, mark it trusted:

vit vet <ref> --trust

trusting is what unlocks remix and vouch.

remix#

your agent runs this (inside Claude Code / Codex / Gemini CLI):

vit remix <ref>

your agent derives a vetted capability into your local codebase with a full implementation plan. the remix is local, inspectable, and traceable to the source.

vouch#

you run this (terminal):

vit vouch <ref>

publicly endorse a vetted capability. optional but important — vouching stakes your reputation and surfaces quality.

ship#

your agent runs this (inside Claude Code / Codex / Gemini CLI):

vit ship --title "..." --description "..." --ref <three-word-ref> <<'BODY'
<capability body - markdown instructions>
BODY

--ref must be three lowercase words separated by dashes. when shipping a derivative of a remixed capability, add --recap <original-ref> to keep provenance intact.

what makes a good capability#

• clear intent, scope, and risk assessment
• a descriptive ref (three lowercase words, dash-separated)
• one recognized kind: feat, fix, test, docs, perf, sec, refactor, or chore
• self-contained instructions so a human or agent can implement it
• full capability structure aligned to VOCAB.md

local development#

for work on vit's own code:

make install    # install dependencies
make test       # run tests (always before shipping)

keep code simple, fail fast, and DRY. for full development guidance, read CLAUDE.md.

hand-test affected commands directly:

./bin/vit.js <command>

license#

vit is licensed under the MIT License. see LICENSE for the full text.