Graphify Sidecar Workflow

Run Graphify as generated working memory for repo structure, then promote only durable lessons into the wiki or project docs.

Trigger

Use this workflow when Kevin asks to build/query a repo graph, reduce repo exploration tokens with a focused subgraph, understand path/impact between modules, assess PR risk, onboard into a project, or make Graphify remember whether an answer helped.

Do not use this workflow for ordinary wiki questions. Those stay on QMD - Local Wiki Search Engine and QMD Embed Workflow.

Ordered Steps

Classify the question. If it is about compiled wiki knowledge, run qmd first.
Load skills/engineering/graphify-sidecar/SKILL.md.
If the target is another Kevin project, read its root AGENTS.md repo-graph auto-block. If the block is missing, run agent-docs scaffold for that repo before broad architecture work.
Check whether a graph exists:

npm run graphify:sidecar -- status

Build or refresh the graph if needed. In the wiki repo:

npm run graphify:sidecar -- build .

For another project repo, run from that project's root:

PROJECT_ROOT="$(pwd)" && cd ~/Documents/GitHub/kevin-wiki && npm run graphify:sidecar -- build "$PROJECT_ROOT" --run outputs/graphify/<repo> --no-viz

Ask the narrowest graph question that fits:

npm run graphify:sidecar -- query "where is auth initialized?"
npm run graphify:sidecar -- path "Auth" "Database"
npm run graphify:sidecar -- explain "RateLimiter"
npm run graphify:sidecar -- affected "BillingService" --depth 2

For another project repo, include the same run directory:

cd ~/Documents/GitHub/kevin-wiki && npm run graphify:sidecar -- query "where is auth initialized?" --run outputs/graphify/<repo>

Read raw files only after the graph has narrowed the candidate set.
Save outcome feedback when the answer was meaningfully useful, wrong, or corrected:

npm run graphify:sidecar -- save-result --question "where is auth initialized?" --answer-file outputs/graphify-answer.md --outcome useful
npm run graphify:sidecar -- reflect

Output And Promotion

Generated artifacts live under outputs/graphify/ and are not durable wiki truth. They can be used as evidence during a task, but the durable record should be one of:

A wiki page update when the lesson changes tool routing, architecture knowledge, or a reusable decision.
A skill update when the lesson changes how agents should operate.
A project doc or ADR when the lesson is repo-specific and belongs with that codebase.
A no-op note in the final answer when no durable update is justified.

Failure Conditions

Stop instead of pretending success when:

Graphify is unavailable and neither graphify, uvx, nor uv can run it.
The graph is stale enough that path/explain answers would be misleading.
The user asks to install hooks or rewrite agent config without explicitly accepting the conflict risk.
The target contains private documents where qmd or direct local search would answer with less exposure.

Closeout

If this workflow changes durable wiki pages, skills, or routing, run the normal routing/index refresh:

npm run skill-registry
npm run routing-doctor
npx tsx scripts/build-index.ts
qmd update
qmd embed

Append wiki/log.md for user-visible changes.

Timeline

2026-07-03 | Added the project-entry path: agent-docs emits repo-graph guidance, agents build project graphs from the wiki checkout, and generated graph artifacts stay outside target repos by default. Source: User request, 2026-07-03
2026-07-02 | Created the Graphify sidecar workflow with explicit qmd boundary, safe wrapper commands, and promotion rules for Graphify reflections. Source: User request, 2026-07-02

Source: User request, 2026-07-03