cc-os/plugins/os-vault/skills/onboard-project/SKILL.md

description
Manage per-project Graphify knowledge graphs — onboard, update, remove, and query codebase structure for the current repo

Scope: project graph at ./graphify-out/graph.json — codebase structure and module relationships for the current repo only. For cross-project evergreen knowledge, use /os-vault:query.

Onboard

Assessment-first onboarding per ADR-017. Do not run graphify extract bare — graphify does not honor .gitignore; it uses a separate .graphifyignore (same syntax). Without one, repos with node_modules/ or other dependency/build/cache dirs will walk every file and route all non-code content through the slow Ollama doc pass. Only non-code files hit the LLM; code uses the free tree-sitter AST pass.

Step 1 — Assess the repo. Survey before touching graphify. List top-level dirs and get a file-type/size profile. Identify what to exclude using the taxonomy below, then surface borderline cases (migrations, seeds, fixtures, sample data) for a human call — do not make that judgment unilaterally.

Meta-principle: index what a human authored as this project's source and knowledge; exclude anything that is (a) fetched, (b) generated/derived/compiled, (c) cached, (d) tooling/environment config, (e) bulk data or binary, or (f) secret. Recognize the KIND even in an unfamiliar stack — the example names are illustrative, not exhaustive. Weight remaining cost by non-code file count: only non-code files go through the Ollama doc pass (~15–25s each), so a stray docs-heavy tooling dir or a large lockfile is what blows up runtime, not source-file count.

Default-exclude categories:

#	Category	Illustrative names
1	Fetched dependencies	node_modules/, vendor/, .venv//venv/, target/, Pods/, site-packages/
2	Build / compiled / generated output	dist/, build/, out/, .next/, .svelte-kit/, bin/, obj/, *.min.js, source maps, generated dirs
3	Caches	.cache/, .vite/, .turbo/, __pycache__/, .pytest_cache/, .gradle/, .terraform/
4	VCS internals	.git/, .hg/, .svn/
5	Editor / IDE & AI-assistant tooling dirs	.vscode/, .idea/, .claude/, .codex/, .cursor/, .pi/, .impeccable/, .husky/ — these are full of markdown that floods the doc pass
6	Lockfiles (machine-generated, hit the LLM)	package-lock.json, yarn.lock, pnpm-lock.yaml, poetry.lock, Cargo.lock, composer.lock, Gemfile.lock
7	Coverage / reports / logs	coverage/, htmlcov/, test-results/, playwright-report/, *.log, logs/
8	Data, databases & bulk dumps	*.db, *.sqlite, pb_data/, large *.csv/*.json/*.parquet, snapshots — keep small schema/seed files that define structure; drop bulk data
9	Binary & media	images, audio, video, fonts, archives, PDFs/Office docs unless they ARE the knowledge
10	Secrets / env	.env, *.pem, credentials
11	graphify-out/	graphify's own output — avoid self-ingestion

For non-coding/writing/research projects the same principle holds but offenders shift: exported duplicates of source notes (PDF/HTML/DOCX exports of the same markdown — index the source, not the export), attachment/media folders, app config (.obsidian/), and archived old-version folders.

• Include candidates: source code (free AST pass) and genuine docs (README, design docs, ADRs).

Step 2 — Draft .graphifyignore. Write .gitignore-syntax rules from the assessment. Add a one-line rationale comment above each rule so the intent is clear later.

Step 3 — Confirm with the user. Present the proposed ignore list and rationale; adjust per feedback before writing anything. This is a judgment step, not a mechanical one — do not skip it.

Step 4 — Write the files. Write .graphifyignore at the repo root. Ensure graphify-out/ is in the project's .gitignore; add it if missing.

Step 5 — Build the graph.

graphify extract . --backend ollama --model qwen25-coder-7b-16k
graphify cluster-only .

qwen25-coder-7b-16k is the ollama_model in config.yaml — a 16k-context build of qwen2.5-coder:7b. Its larger context window reduces the number of chunks per document, which is the main onboarding-speed lever: inference is GPU-bound (~65 tok/s), so the cost is chunk-count × generation, not hardware. Note: GRAPHIFY_OLLAMA_NUM_CTX does not propagate through graphify's OpenAI-compatible path; the larger context comes from the model's own Modelfile.

Confirm ./graphify-out/graph.json exists before reporting done.

Incremental update

# Routine edits (no renames/deletions/moves)
graphify update .

# Structural changes (renames, deletions, directory moves)
graphify update . --force

Suggest running graphify update . after sessions involving significant refactoring, and --force after any renames or directory reorganization.

Remove

Delete graphify-out/ when the project is inactive or the graph is too stale. The graph is always rebuildable via the onboard sequence. Leave the .gitignore entry even after removal.

Query

graphify query "<question>" --graph ./graphify-out/graph.json

For traversal mechanics (graphify path, graphify explain, --budget, --dfs), see /os-vault:query — query mechanics are not duplicated here.

Graph path discovery

session_context.py injects the absolute path to graphify-out/graph.json when it exists. If no graph path is present in session context and you are working in a project context, suggest running the onboard sequence before proceeding with knowledge queries.

Constraints

• Never commit graphify-out/ — it is local, disposable, and rebuildable.
• Model is qwen25-coder-7b-16k (config.yaml ollama_model) — do not substitute. This is a 16k-context build of qwen2.5-coder:7b; using the smaller base model silently reduces context and increases chunk count.
• The .gitignore entry for graphify-out/ must survive even if the directory is deleted.