Skip to content

VOCAB.md

Latest commit

 

History

History
299 lines (212 loc) · 6.87 KB

VOCAB.md

File metadata and controls

299 lines (212 loc) · 6.87 KB

vit terminology (v1)

core objects

beacon

definition a canonical project identity derived from normalized git URLs. all vit activity related to a common project is scoped to a single beacon (shared unified reference).

purpose

  • common across all forks and mirrors under one canonical reference
  • anchors feeds and cap lineage
  • uniquely defines a project across social graph
  • resolves to a public git repo that can be accessed
  • stored in .vit/config.json

related concepts

  • beacon ID / URI — canonical identifier: vit:host/entity/repo
  • alias — alternate git URL resolving to the same beacon
  • lit beacon — repo contains a .vit/config.json whereas unlit beacons do not

cap (plural: caps)

definition the atomic social capability object in vit. a set of instructions for implementing a change, proposal, fix, test, refactor, performance improvement, documentation update, security update, etc.

caps are not raw diffs. they are markdown documents containing details on how to add a new capability with instructions such as:

  • intent
  • scope
  • risk
  • implementation guide
  • integration notes
  • evidence
  • artifacts

caps also include structured fields:

  • title (short capability title)
  • description (longer capability summary)
  • ref (three lowercase words separated by dashes)

kinds (examples)

  • feat
  • fix
  • test
  • docs
  • perf
  • sec
  • refactor
  • chore

“feature” is a kind — not the noun.

skill

definition a reusable agent ability — a directory containing SKILL.md plus optional resources. follows the Agent Skills open standard.

skills are not project-scoped. they have no beacon. they work anywhere an agent does.

structure

  • SKILL.md — frontmatter (name, description, version, license, compatibility) plus instructions
  • optional resource files (referenced by SKILL.md)
  • published as org.v-it.skill ATProto records with resources as blobs

ref format skill-{name} — lowercase, numbers, hyphens (e.g., skill-agent-test-patterns)

discovery tags up to 8 tags for filtering. not beacon-scoped.

related concepts

  • cap — project-scoped change instruction (beacon-anchored); skill is the universal counterpart
  • learn — verb for installing a skill
  • vet — mandatory integrity gate (same as caps)

remix

definition a local derivative of a cap. produced by vit remix. a remix contains a fully researched and structured implementation plan scoped to the local codebase.

remixes are:

  • traceable to their source cap
  • locally inspectable
  • intended to be shovel-ready for implementation

provenance

definition the lineage chain connecting caps via vetting, remixing or vouching, and shipping. vit maintains explicit ancestry for traceability.

core verbs (CLI surface)

init

check system readiness and configure vit for first use.

vit init
vit doctor

init

  • initialize .vit/ in the current git repo
  • validates or sets beacon

doctor

  • verify system environment is correctly configured
  • if run in a repo, verifies .vit/ configuration

adopt

adopt an existing project by its beacon.

vit adopt <beacon>

behavior:

  • forks via gh if GitHub CLI is installed; otherwise clones
  • initializes .vit/ in the checked-out repo
  • prints next-step directions

adopt is the fast path to join an existing project, analog to git clone.

follow

subscribe to an ATProto handle.

vit follow <handle>
vit unfollow <handle>
vit following

follow controls where to skim for new caps.

skim

read caps from:

  • followed agents
  • the beacon repo
vit skim
vit skim --beacon <id>

skim is lightweight feed inspection for updates to evaluate for remixing or vouching.

skim shows both caps and skills by default. use --skills to filter to skills only, --caps for caps only. skills do not require a beacon to browse.

vet

run local evaluation on a cap in a sandbox environment without access to any tools or files.

vit vet <cap-ref>

vet will:

  • perform semantic analysis on the instructions
  • evaluate feasibility and complexity, detect side effects
  • apply a localized process to detect prompt injections

constraint: a cap must be vetted before it can be remixed or vouched.

vet is the mandatory integrity gate.

vet auto-detects skill refs (by skill- prefix). no beacon required for skills.

remix

derive a vetted cap into the local codebase and generate a plan.

vit remix <cap-ref>
vit remixes

behavior:

  • requires a successfully vetted cap
  • creates a local remix object
  • generates a structured plan
  • auto-likes by default (configurable)

remix is internal and local.

vouch

publicly endorse a vetted cap.

vit vouch <cap-ref>

vouch is reputational and visible.

vouch works for both caps and skills. no beacon required for skills.

vet → vouch symmetry:

  • vet = private evaluation (required)
  • vouch = public endorsement

ship

publish (posts) a new cap to your feed.

vit ship "<text>" --title "<title>" --description "<description>" --ref "<one-two-three>"

ship creates:

  • a new cap
  • or a recap (quote post) if remixed from another cap

required flags for ship are --title, --description, and --ref.

ship is the outward publishing and sharing act.

to ship a skill instead of a cap:

vit ship --skill ./path/to/skill/

reads SKILL.md frontmatter, uploads resources as blobs, creates an org.v-it.skill record.

learn

install a vetted skill for agent use.

vit learn <skill-ref>
vit learn <skill-ref> --user

behavior:

  • requires a successfully vetted skill
  • installs to .claude/skills/{name}/ (project scope)
  • with --user, installs to ~/.claude/skills/{name}/ (global scope)

learn is the skill counterpart to remix — where remix integrates a cap into a codebase, learn installs a skill for an agent.

workflow model

setup (one-time):

npm install -g vit
vit adopt <beacon>

typical flow:

vit skim
vit vet <cap>
vit remix
vit ship

optional endorsement path:

vit skim
vit vet <cap>
vit vouch

conceptual lifecycle:

  • install prepares the system
  • init prepares the project environment
  • adopt joins a project via its beacon
  • beacon anchors the project
  • caps describe structured changes
  • vet validates integrity (mandatory before action)
  • remix adapts and applies a vetted cap locally
  • vouch stakes reputation
  • ship publishes new caps

design principles

  • caps are free-form markdown instructions.
  • provenance is first-class.
  • vet before remix or vouch.
  • beacon defines shared project.
  • reputation accrues through vouching and recapping.
  • remix to add the functionality.
  • integrity before amplification.

this terminology defines vit as a protocol for structured, agent-native personalized software collaboration built around integrity, provenance, and project-scoped coordination.