Skip to content

Contributing to pi-vault-mind

Thank you for considering a contribution! This guide covers setup, testing, and how to submit changes.

Development setup

git clone <repo-url>
cd pi-vault-mind
pnpm install
pnpm build

Prerequisites

  • Node.js 20.6+ (matches the engines.node field in package.json)
  • pnpm 8+ (or npm 10+ — pnpm is used in CI)
  • No external binaries — pi-vault-mind is fully self-contained. Embeddings run via @xenova/transformers (downloaded on first use) or Ollama (if you choose the ollama provider). No external binary on PATH.

Project structure

src/                   ← TypeScript source for the extension
  index.ts             ← main extension entry point
  commands.ts          ← /wiki command tree
  tools.ts             ← LLM-callable tools (wiki_search, append_wiki, etc.)
  watcher.ts           ← passive file-watcher for @agent markers
  events.ts            ← before_agent_start + turn_end hooks
  lance.ts             ← LanceDB + embedding integration
  graph.ts             ← entity-relation graph
  settings-ui.ts       ← interactive TUI wizards
  state.ts             ← module state (active collection, etc.)
  types.ts             ← TypeScript types + DEFAULT_CONFIG

skills/                ← Agent Skills standard skills
  vault-mind/SKILL.md              ← root skill (the Manager)
  vault-mind-miner/SKILL.md        ← research/ingestion
  vault-mind-broadcaster/SKILL.md  ← NotebookLM artifacts
  vault-mind-heavy-lifter/SKILL.md ← external delegation
  vault-mind-manager/SKILL.md      ← manager persona
  vault-mind-setup/SKILL.md        ← setup wizard triggers

docs/                  ← MkDocs documentation site
mkdocs.yml             ← site build config
.github/workflows/     ← CI (build, test, docs deploy)

Workflow

  1. Fork and branch — create a feature branch from main
  2. Write code — TypeScript, strict mode preferred
  3. Check — pnpm check (runs biome check --write . && tsc --noEmit)
  4. Test — pnpm test (runs the Node.js test suite)
  5. Commit — follow Conventional Commits (the pre-commit hook runs biome check --write . && tsc --noEmit automatically)
  6. PR — describe what changed and why

Testing

# Build and run tests
pnpm build
pnpm test

Tests cover module exports, config loading, watcher file scanning, marker grouping, dispatch ID generation, and status reporting.

For manual end-to-end verification, see the End-to-End Manual Test procedure and the Automated Tests Checklist.

Code style

  • Prefer const / let, never var
  • Use === and !==
  • Prefer async/await over callbacks
  • Prefix internal functions with underscore or keep them module-private
  • Comments in /* ── Section ── */ style for major blocks
  • Biome handles formatting (see biome.json)

Commit message format

type(scope): short description

Longer explanation if needed. Wrap at 72 chars.

Closes #123
Type Use for
feat New tool, command, config option
fix Bug fix
docs README, skill, reference changes
test Adding or fixing tests
chore Build, dependencies, tooling
refactor Code change that is neither feat nor fix

Feature requests and bugs

Open an issue first. For bugs, include:

  • pi version (pi --version)
  • Node version (node -v)
  • Steps to reproduce
  • Expected vs actual behavior
  • Config file (redacted as needed)

License

By contributing, you agree that your contributions will be licensed under the same license as the project.