open source is social v-it.org
add CONTRIBUTING.md describing vit-native contribution workflow
+106
+106
CONTRIBUTING.md
+106
CONTRIBUTING.md
···
1
+
contributing to vit happens through vit itself.
2
+
you do not route work through pull requests or issues; you ship caps.
3
+
for the philosophy behind this system, read [docs/DOCTRINE.md](docs/DOCTRINE.md).
4
+
5
+
## prerequisites
6
+
7
+
- [bun](https://bun.sh) installed
8
+
- a [Bluesky](https://bsky.app) account
9
+
- vit installed (`bun install -g @aspect/vit` or `make install-user` from source)
10
+
11
+
## setup
12
+
13
+
run these one-time steps to join vit's own beacon:
14
+
15
+
```bash
16
+
vit setup
17
+
vit login <your-handle>.bsky.social
18
+
vit adopt vit:github.com/solpbc/vit
19
+
```
20
+
21
+
`setup` checks prerequisites.
22
+
`login` authenticates with Bluesky.
23
+
`adopt` forks or clones the repo.
24
+
then your agent runs `vit init` to initialize `.vit/` and set the beacon.
25
+
after this, you have a local workspace anchored to vit's beacon.
26
+
27
+
follow active contributors so your skim stream stays relevant:
28
+
29
+
```bash
30
+
vit follow <handle>
31
+
```
32
+
33
+
## the loop
34
+
35
+
you and your agent run one loop: skim -> vet -> remix or vouch -> ship.
36
+
this is a human and agent collaboration model, not a background automation model.
37
+
38
+
### skim
39
+
40
+
your agent browses the cap stream filtered to your beacon.
41
+
run `vit skim` (agent-only).
42
+
this surfaces new caps from people you follow.
43
+
44
+
### vet
45
+
46
+
you evaluate a cap locally with `vit vet <ref>` (human-only).
47
+
once satisfied, mark it trusted with `vit vet <ref> --trust`.
48
+
trusting is what unlocks remix and vouch.
49
+
50
+
### remix
51
+
52
+
your agent derives a vetted cap into your local codebase with a full implementation plan.
53
+
run `vit remix <ref>` (agent-only).
54
+
the remix is local, inspectable, and traceable to the source cap.
55
+
56
+
### vouch
57
+
58
+
you publicly vouch for a vetted cap.
59
+
run `vit vouch <ref>`.
60
+
this is optional but important: vouching stakes your reputation and surfaces quality.
61
+
62
+
### ship
63
+
64
+
your agent ships a new cap back to the network.
65
+
use this format:
66
+
67
+
```bash
68
+
vit ship --title "..." --description "..." --ref <three-word-ref> <<'BODY'
69
+
<cap body - markdown instructions>
70
+
BODY
71
+
```
72
+
73
+
`--ref` must be three lowercase words separated by dashes.
74
+
when shipping a derivative of a remixed cap, add `--recap <original-ref>` to keep provenance intact.
75
+
76
+
## what makes a good cap
77
+
78
+
- clear intent, scope, and risk assessment
79
+
- a descriptive `ref` (three lowercase words, dash-separated)
80
+
- one recognized kind: `feat`, `fix`, `test`, `docs`, `perf`, `sec`, `refactor`, or `chore`
81
+
- self-contained instructions so a human or agent can implement it
82
+
- full cap structure aligned to [docs/VOCAB.md](docs/VOCAB.md)
83
+
84
+
## local development
85
+
86
+
for work on vit's own code:
87
+
88
+
```bash
89
+
make install # install dependencies
90
+
make test # run tests (always before shipping)
91
+
```
92
+
93
+
keep code simple, fail fast, and DRY.
94
+
for full development guidance, read `CLAUDE.md`.
95
+
96
+
hand-test affected commands directly:
97
+
98
+
```bash
99
+
./bin/vit.js <command>
100
+
```
101
+
102
+
## license
103
+
104
+
vit is licensed under AGPL-3.0-only.
105
+
caps you ship inherit this license.
106
+
see `LICENSE` for the full text.