Skip to content

TEAM-BUNDLE.md

Latest commit

 

History

History
108 lines (77 loc) · 4.53 KB

TEAM-BUNDLE.md

File metadata and controls

108 lines (77 loc) · 4.53 KB
Raw

GitNexus agent teaching bundle — team install

Portable rules + hooks + skills + scripts for graph-first agents (Cursor hooks, Zed profiles). Built for this repo; reusable on other projects with one rename step.

Standalone installer: gitnexus-agent-kit — install / update / uninstall scripts for any repo (upstream for this teaching bundle). Updates migrate legacy cursor-gitnexus-kit layouts automatically.

Team-facing guide: docs/GITNEXUS-CURSOR-GUIDE.md — plain language for developers (what enforcement feels like, npm run gitnexus:health).

What's in the bundle

Included Purpose
.cursor/rules/gitnexus*.mdc Always-on agent contract (Cursor)
.cursor/hooks.json + .cursor/hooks/** Block grep-first; field grep → Cypher; staleness gate; auto-refresh on session start
.gnkit/lib/cypher-helpers.mjs Copy-paste Cypher recipes (ACCESSES, CALLS, overrides)
.gnkit/skills/ + symlinks Playbooks (enforcement, scenarios, exploring, …)
scripts/gitnexus-setup.sh One-shot team installer
scripts/sync-cursor-gitnexus-teaching.sh Re-sync skills symlinks after pull
scripts/gitnexus-verify.mjs Runtime-aware kit verification
scripts/gitnexus-agent.mjs Agent CLI (agent-status / agent-refresh)
scripts/install-git-hooks.sh + .githooks/pre-commit PDG index refresh on commit
.vscode/settings.json npm task settings (optional)
.gitnexusignore GitNexus-only excludes (large caches)
package.json.scripts.snippet.json npm scripts to merge

Automatic: install-from-bundle.sh and gitnexus:setup run merge-package-scripts.mjs --write, which adds or overwrites all gitnexus:* and hooks:install scripts in package.json (creates package.json if missing).

NOT included (per-target repo)

Excluded Why
.gitnexus/ index Built locally via npm run gitnexus:refresh; pre-commit upgrades it with npm run gitnexus:full-pdg
.cursor/skills/generated/ Area skills from gitnexus analyze --skills on that codebase
IDE skill symlinks Created by install/update from canonical store

Large generated caches (recommended)

If the repo has thousands of non-source files (e.g. large data shards, generated reports, fixtures), add them to both:

  • .gitignore — keep git clean
  • .gitnexusignore — same gitignore syntax; keeps gitnexus analyze fast

Example: ignore data/ and reports/ in both files. After changing ignores, re-index:

npm run gitnexus:agent-refresh

/tmp full (tmpfs ENOSPC)

On Linux, /tmp is often a tmpfs (RAM disk, ~7–8G). When it hits 100%, gitnexus analyze fails with ENOSPC even if your NVMe has hundreds of GB free.

All gitnexus:* npm scripts route temp files to .tmp-agent/ on the project disk (override: GITNEXUS_TMPDIR).

If refresh still fails:

df -h /tmp
sudo du -sh /tmp/* 2>/dev/null | sort -hr | head -10
rm -rf /tmp/cursor-sandbox-cache/*    # often safe
npm run gitnexus:clean-tmp            # project temp only
npm run gitnexus:agent-refresh

Pack (this repo)

npm run gitnexus:pack
# → gitnexus-cursor-teaching-v2-YYYYMMDDTHHMMSSZ.tar.gz

Install (another repo)

tar -xzf gitnexus-cursor-teaching-*.tar.gz -C /path/to/their-repo --strip-components=1
cd /path/to/their-repo
GITNEXUS_REPO_NAME=their-repo-name bash scripts/gitnexus-teaching/install-from-bundle.sh

Or use the standalone kit (recommended):

/path/to/gitnexus-agent-kit/bin/install.sh /path/to/their-repo --runtime both

After install (every dev)

  1. Restart your IDE (MCP + hooks / Zed profile)
  2. npm run gitnexus:agent-status — index fresh?
  3. Start Agent chats with: "Read gitnexus-workspace skill, then …"

Auto-refresh: On Agent session start, hooks run npm run gitnexus:agent-refresh if the index is behind HEAD (skip with GITNEXUS_SKIP_SESSION_REFRESH=1). While stale, a shell guard blocks non-gitnexus commands until refresh succeeds — agents must not tell users to run analyze manually.

Daily commands

npm run gitnexus:verify          # full kit check
npm run gitnexus:agent-status    # staleness (agent runs autonomously)
npm run gitnexus:agent-refresh   # re-index when stale
npm run gitnexus:sync-teaching   # after pulling rule/skill updates
npm run gitnexus:setup -- --quick  # hooks/skills only, skip index

Prerequisites

  • Node.js >= 22.9.0
  • git
  • Cursor and/or Zed with MCP enabled