CLAUDE.md#

Development guidelines for vit, a social toolkit for personalized software built with Bun.

Project Overview#

vit is a Node CLI for discovering, vetting, remixing, and shipping software capabilities:

• vit login, vit init, vit doctor — authentication and environment setup
• vit beacon, vit config — project beacon inspection and user configuration
• vit firehose — listen to Jetstream for cap events
• vit ship, vit skim — publish and read caps

Source layout:

• bin/vit.js - executable entrypoint
• src/cli.js - root Commander program
• src/cmd/ - subcommand modules
• src/lib/ - shared helpers

Commands#

make install    # Install dependencies with bun
make test       # Run tests with bun
make clean      # Remove node_modules

Development Principles#

• Simple code - Prefer plain functions. Keep scripts self-contained.
• DRY, KISS - Extract common logic, prefer simple solutions.
• YAGNI - Don't build for cases that don't exist yet; no speculative flags, options, or abstractions. No backwards-compatibility shims — update call sites directly when you rename or move something.
• Fail fast - Validate inputs and external state early. Clear error messages. Surface failures, don't swallow them into a success-looking result.
• Verify before you claim - Recall is a hypothesis, not evidence. Verify atproto/Jetstream behavior, an API shape, or a dependency's defaults against the live source before it lands in code or a commit — a quick check beats a reversal. Contract tests round-trip the real serialization boundary, not a mock of both sides.
• Vocabulary alignment - VOCAB.md is the source of truth for all project terminology. All project descriptions, CLI help strings, documentation, and skill files must use terminology consistent with VOCAB.md. When VOCAB.md is updated, propagate changes to every file that references vit's vocabulary in the same commit.

Testing Standards#

1. No real home access — tests must never read or write ~/.local, ~/.config, ~/.claude, or any path under the real $HOME. Use HOME and XDG_CONFIG_HOME env overrides to redirect to temp dirs.
2. No live HTTP — tests must not make requests to external hosts (github.com, explore.v-it.org, etc.). Use Bun.serve() local servers with canned responses, or mock.module() for dependencies that make HTTP calls.
3. No global mutation — tests must not call process.chdir(). Pass directory arguments to functions instead. If process.chdir is unavoidable, wrap in try/finally.
4. Temp dir lifecycle — create temp dirs with join(tmpdir(), '.test-{name}-{random}') in beforeEach, clean up with rmSync(dir, { recursive: true, force: true }) in afterEach.
5. Subprocess isolation — tests using run() isolate via env overrides and CLI flags. In-process tests may use mock.module() only when env/flag isolation is impossible (e.g., mocking isomorphic-git in beacon tests).

Verification#

• Always run make test before committing — all tests must pass.
• Hand-test affected CLI commands (./bin/vit.js <command>) to verify behavior beyond what tests cover.

Releasing#

Every commit that changes files in bin/ or src/ — the packaged CLI code — must be followed by a release and publish to npm:

make ship              # bump patch version, tag, push, publish to npm
make ship BUMP=minor   # for new commands or features
make ship BUMP=major   # for breaking changes

This is non-negotiable. If your commit touches bin/ or src/, run make ship before you're done. Use patch (default) for fixes and small improvements, minor for new commands or features, major for breaking changes.

make ship runs tests, bumps the version in package.json, creates a git commit and tag (vX.Y.Z), pushes to origin, and publishes to npm — all in one step.

Individual targets if needed:

• make release — test, bump, commit, tag, push (no npm publish)
• make publish — npm publish only (assumes version is already bumped)

Hosting#

This repo contains three deployable things:

The site does NOT auto-deploy. After changing anything in docs/ (pages, decks, assets), you must run make deploy-site to publish. Both site and explore are Cloudflare Workers — deployment requires a wrangler login OAuth session.

File Headers#

All JS source files must include this header immediately after the shebang line:

// SPDX-License-Identifier: MIT
// Copyright (c) 2026 sol pbc

Add this header to .js files in bin/ and src/. Do not add headers to docs/, node_modules/, or non-source files.

Skills#

Agent skills for this project live in skills/. When authoring or updating skills, follow the Claude agent skills best practices:

• Keep SKILL.md concise — under 500 lines. Only add context Claude doesn't already have.
• Use progressive disclosure: essentials inline, details in referenced files one level deep.
• Use gerund or action-oriented naming (lowercase-hyphens only) for skill names.
• Write descriptions in third person that specify both what the skill does and when to use it.
• Test with all target models (Haiku, Sonnet, Opus) as effectiveness varies.

Dogfooding#

Ship meaningful work as caps. Use vit ship after completing a feature, fix, or improvement — not for typos or formatting.

vit ship --title "Short Title" --description "One sentence of value." --ref "three-word-slug" --kind feat <<'EOF'
Body paragraph explaining what the cap does and how it works.
EOF

Flags:

• --title: concise noun phrase (2–5 words)
• --description: one sentence explaining the value
• --ref: three lowercase hyphenated words — a memorable discovery slug
• --kind: one of feat, fix, test, docs, refactor, chore, perf, style
• --recap <ref>: link to a prior cap this one derives from (e.g. after vit remix)
• Body (stdin): short paragraph for another developer or agent who might adopt it