Joining an Existing nexus-dev-toolkit Project

AGENTS.md and knowledge/ are already committed and shared. Here's what a fresh clone still needs before /evaluate works.

PREREQS → INSTALL → NEXUS INIT → BUILD GRAPH

Module Overview

This is the Dev Track's equivalent of Module 8, aimed at the situation every developer actually runs into: not a legacy codebase that's never seen the AI SDLC framework, but a project your team is already running on nexus-dev-toolkit, that you personally are touching for the first time — a new hire, a new machine, a rebuilt laptop. The artifact chain, AGENTS.md, and knowledge/ already exist and are already good; what's missing is purely local to your machine, and this module is the checklist for getting it back.

At a glance
Covers	What's committed vs. gitignored in a nexus project; the four-step local setup on a fresh clone; building the knowledge graph for the first time; `nexus doctor` as the health check
When it runs	Immediately after cloning any repo that already runs on nexus — before your first `/evaluate`
Builds on	Dev 1 (the same install steps, run again on a new machine)
Leads into	Dev 2 onward — the daily EPAV loop, on the team's existing codebase

What you'll produce

A regenerated .claude/ (or .opencode/) and a freshly built knowledge graph on your local clone, confirmed healthy with nexus doctor — ready to run /evaluate on a real Dev Task.

What's Committed vs. What's Local to Your Machine

This project was scaffolded and is developed using nexus-dev-toolkit (EPAV: evaluate → plan → apply → validate) with graphify for codebase-aware AI assistance. AGENTS.md and knowledge/ (coding standards, patterns, design system spec) are committed and shared by the whole team — every clone sees the same ones. .claude/ (EPAV skills, commands, agents) and graphify-out/ (the built knowledge graph) are gitignored: they're machine-local, regenerated per clone, never synced through git.

Committed & shared	Local & gitignored — regenerate on every clone
`AGENTS.md`	`.claude/` (or `.opencode/`) — EPAV skills, reviewer subagents, settings/plugins
`knowledge/` — rules, patterns, prompts, retros	`graphify-out/` — the built knowledge graph

Local Setup, Four Steps

# 1. Prerequisites
curl -LsSf https://astral.sh/uv/install.sh | sh   # uv package manager
npm install -g @anthropic-ai/claude-code
claude login

# 2. graphify — builds the queryable knowledge graph EPAV skills use for
#    blast-radius/cross-file-dependency context instead of full file reads
uv tool install graphifyy   # PyPI name has double y; the command is "graphify"
graphify install            # registers /graphify skill into Claude Code

# 3. nexus-dev-toolkit itself — if already installed, update to the latest
#    version instead (EPAV skills/subagents ship inside the toolkit itself,
#    so a stale install silently misses fixes and new skills):
uv tool install nexus-dev-toolkit
nexus update   # run this even on an existing install, before nexus init

# 4. Regenerate .claude/ (EPAV skills, reviewer subagents, settings.json)
#    Run from the repo root — knowledge/ and AGENTS.md already exist and
#    won't be touched; review any prompts before overwriting.
nexus init .

Then inside Claude Code, build the graph once (and after any large refactor — normal edits keep it current automatically via the PostToolUse hook nexus init wires up, covered in Dev 4):

/graphify .

Run nexus doctor any time to check the toolkit and graph setup are healthy. See nexus-dev-toolkit's own docs for the full EPAV workflow (/evaluate → /plan → /apply → /validate) already referenced throughout AGENTS.md.

nexus doctor

OpenCode note

Same four steps. Step 1 installs OpenCode instead of (or alongside) Claude Code; step 4 becomes nexus init . --tool opencode; and the machine-local, gitignored folder is .opencode/ instead of .claude/ — graphify's auto-update runs via the .opencode/plugins/graphify.js plugin rather than a settings.json hook (Dev 4 covers the difference in full). Everything else — AGENTS.md, knowledge/, graphify-out/ — is identical either way.

Verification Checklist

nexus doctor reports a clean setup and shows which graph backend is active
.claude/commands/ (or .opencode/commands/) contains the EPAV skills — /evaluate, /plan, /apply, /validate, /code-review, and the rest
graphify-out/ exists and graphify query returns real results against the codebase
AGENTS.md and knowledge/ are untouched from what the repo already had — nexus init didn't overwrite anything shared
You can run /evaluate on a real Dev Task from docs/dev-tasks/ and get a normal EVALUATE SUMMARY

If AGENTS.md and knowledge/ aren't there at all

That's a different, heavier job — the project has never used nexus or the AI SDLC framework, and someone needs to introduce both for the first time (reverse-engineering a BRD/PRD/Architecture from the existing codebase, the way the core program's Module 8 teaches). That's not a per-developer setup task, and it's not what this page covers — flag it to your Tech Lead or Solutions Architect rather than attempting it solo on clone day.

Mindset & Etiquette on an AI-Assisted Team

Joining a project already on nexus means joining its habits, not just its tooling. The core program's first principle — AI augments, humans decide — is the baseline for everything below. "The AI wrote it" is not an acceptance criterion, on this project or any other.

Practice	Why it matters
Review `/plan` like you'd review a PR — before `/apply`, not after	The gate exists to catch a wrong approach at blueprint time. Approving on autopilot moves the review to after the code exists, which is slower and harder, not faster.
Read every diff before it's committed, AI-written or not	You own every line with your name on the commit. If you can't explain why a line is there, don't approve it at `/apply` and don't let `/validate` passing substitute for reading it.
Don't skip `/validate` or `/code-review` to hit a deadline	An unresolved `[BLOCKER]` or a `critical` finding blocking the task is the check doing its job, not an obstacle to route around.
Contribute the fix, not just the workaround	Correcting the same mistake more than once means a rule is missing from `knowledge/rules/`, not that you need to remember it better. Add it — the next teammate inherits the fix instead of repeating the correction.
Treat `knowledge/` as shared team memory, not personal scratch space	A pattern or rule you commit there changes how every teammate's sessions behave. Write it like a PR — clear, with a real example, peer-reviewed — per Dev 5 and Dev 7's quality bar.
Reference the Dev Task ID in commits and PRs	Not attribution theater — traceability. Anyone reading git log later should be able to walk a commit back to the acceptance criteria that justified it.
Grant new agents and skills the minimum tools they need	The built-in reviewers are read-only by design (Dev 4, Dev 6). When you build your own, match that discipline — expand scope deliberately, not by default.
Know that OpenCode and its free models stay in training	OpenCode, Big Pickle, Ox Alpha, and similar free-tier models (Dev 1) are for practicing the EPAV cycle and for personal projects. Real client engagements run on Claude Code only — don't carry a free-model habit into billable work.

A graceful fallback is a flagged gap, not a pass

When /evaluate degrades gracefully — missing graph, missing AGENTS.md, missing arch doc — that's EPAV telling you something's thinner than it should be, not giving you permission to proceed as if it were fine. Escalate it (see the callout above) rather than quietly working around it session after session.

Self-Check

I can name which two directories are committed and shared, and which two are local and gitignored.
I've run the four setup steps on a fresh clone and confirmed nexus doctor is clean.
I understand nexus init regenerates .claude/ (or .opencode/) without touching the shared AGENTS.md or knowledge/.
I've built the graph and confirmed a real query returns results against the actual codebase.
I know the difference between this setup task and a full first-time retrofit, and who to flag it to if it's the latter.
I can name at least three etiquette practices from the table above and why each one matters to teammates, not just to me.
I treat a graceful EPAV fallback as a gap to escalate, not a green light to keep going.