nexus-dev-toolkit

Developer workflow toolkit for Claude Code and OpenCode. Gives any team a structured Day 0 scaffold and repeatable Day 1 feature cycle via the EPAV methodology.

Documentation

---

Why

Ad-hoc AI prompting doesn't scale. Every dev prompts differently, context drifts, and nobody knows what the AI was told last sprint.

nexus-dev-toolkit gives your team a single workflow:

• Day 0 — scaffold the project once, production-grade, zero credentials needed
• Day 1 — every feature follows the same four steps: evaluate → plan → apply → validate

Every skill, every rule, every pattern lives in the project repo — versioned, shared, and enforced.

---

Setup

1. Install prerequisites

uv (recommended package manager):

curl -LsSf https://astral.sh/uv/install.sh | sh

Claude Code:

npm install -g @anthropic-ai/claude-code
claude login

graphify (strongly recommended) — builds a queryable knowledge graph of your codebase. EPAV skills query this graph to understand blast radius and cross-file dependencies before touching any code.

	With graphify	Without graphify
Context loading	Scoped subgraph — fast, low token cost	Full file reads — slow, high token cost
Blast radius	Accurate, graph-backed	Best-effort, grep-based
Auto-update	PostToolUse hook keeps graph current	N/A
EPAV skills	Full capability	Degraded but functional

uv tool install graphifyy   # PyPI package name has double y; command is "graphify"
graphify install             # registers /graphify skill into Claude Code

codegraph (alternative to graphify) — a different knowledge-graph tool EPAV skills can use instead. Pick one, not both; nexus doctor warns if it finds graphs from both built in the same project.

npm i -g @colbymchenry/codegraph
codegraph install   # wires codegraph into Claude Code / OpenCode / etc.

2. Install nexus-dev-toolkit

uv tool install nexus-dev-toolkit

3. Initialize your project

cd my-project
nexus init .                                        # Claude Code (default), prompts for graphify/codegraph/none + TypeSafe
nexus init . --tool opencode                        # OpenCode
nexus init . --graph-backend codegraph              # skip the graph-backend prompt, use codegraph
nexus init . --typesafe                             # skip the TypeSafe prompt, enable it

TypeSafe/Jev (optional) — replaces a handful of hardcoded keyword-matching heuristics in the EPAV tools (which architecture-doc section is about auth vs. security, which of ~30 stack tags an arch doc mentions, which package manager or IaC tool fits a free-text hint, which CSV column means "acceptance criteria") with an actual judgment call. Every one of those tools works exactly the same without it — TypeSafe is off by default, pip install nexus-dev-toolkit never installs it, and every judgment falls back to the original heuristic if it isn't enabled or the API call fails. Enable at init with --typesafe (or answer y at the prompt), then set TYPESAFE_API_KEY (get one at https://console.typesafe.ai/). nexus doctor reports whether it's wired up and whether the key is set. See tools/README.md for how it's implemented.

4. Place your reference docs

Before running /scaffold, put everything Claude needs in docs/:

docs/
├── arch-docs/   ← architecture doc, ADRs
├── figma/       ← Figma export ZIP
├── brd/         ← Business Requirements Document
└── prd/         ← Product Requirements Document

5. Start Day 0

Open the project in Claude Code and run:

/scaffold

/scaffold runs EVALUATE first then stops. You drive each phase by typing the next command:

/scaffold → (review) → /plan → (review) → /apply → (review) → /validate

6. Build the knowledge graph

After /scaffold completes, build whichever backend you chose at init:

/graphify .                              # if you chose graphify
codegraph install && codegraph init      # if you chose codegraph, run in your terminal

This generates graphify-out/graph.json or .codegraph/codegraph.db — EPAV skills use whichever is present, or fall back to full file reads if neither is built yet. Run nexus doctor any time to check which backend is active.

---

The Workflow

Day 0 — /scaffold (once per project)

Produces a production-grade project from your architecture document — plus a Figma design, for a project with a UI: correct stack, mock auth, mock data, design system, AGENTS.md — zero external dependencies. Runs npm install && npm run dev (or equivalent) from commit one. For an infrastructure-shaped project (Terraform/OpenTofu, Helm, Ansible), there's no Figma/UI/mock-auth step at all — it generates the IaC modules/playbooks/charts instead, validated with plan/lint/template, never applyd against real cloud accounts on Day 0.

Day 1 — EPAV (every feature, every sprint)

/evaluate <task>  →  /plan  →  /apply  →  /validate

Each step is a built-in skill in .claude/commands/. Every task starts from the dev tasks CSV. Every task ends with acceptance criteria verified.

---

What nexus init Creates

settings.json/graphify.js below are only created if you pick graphify (the default) at the --graph-backend prompt. Pick codegraph instead and neither is scaffolded — codegraph wires and syncs itself via codegraph install && codegraph init.

Claude Code (nexus init .):

.claude/
├── commands/          ← EPAV skills + 5 reviewer skills (/code-review, etc.)
├── agents/            ← 5 reviewer subagents (code-reviewer, database-reviewer, etc.)
└── settings.json      ← PostToolUse: graphify auto-updates after every file edit (graphify backend only)
knowledge/
├── rules/             ← coding standards, arch decisions
├── patterns/          ← reusable implementation patterns
├── prompts/dev/       ← task prompt templates
└── retros/            ← retrospective notes
.mcp.json              ← MCP server config

OpenCode (nexus init . --tool opencode):

.opencode/
├── commands/          ← same EPAV skills + reviewer skills
├── agents/            ← same reviewer subagents (adapted for OpenCode)
└── plugins/
    └── graphify.js    ← tool.execute.after: graphify auto-update (graphify backend only)
knowledge/             ← same structure
opencode.json          ← MCP server config

---

Commands

nexus init .                      # Claude Code — set up .claude/ + knowledge/ + .mcp.json
nexus init . --tool opencode      # OpenCode — set up .opencode/ + knowledge/ + opencode.json
nexus --version                   # show installed version
nexus update                      # update the CLI itself; asks whether to also sync in a real terminal
nexus update --sync               # skip the prompt, always sync the current project's skills/agents too
nexus sync                        # sync built-in skills & agents to latest (custom files untouched)
nexus doctor                      # validate project setup

nexus skill list                  # list all skills in .claude/commands/
nexus skill add my-review         # create a custom skill

nexus agent list                  # list all subagents in .claude/agents/
nexus agent add my-agent          # create a custom subagent

nexus rule list                   # list all rules in knowledge/rules/
nexus rule add api-standards      # create a project rule

---

MCP Server

nexus init writes .mcp.json automatically. For Claude Desktop, add manually:

{
  "mcpServers": {
    "nexus": {
      "command": "uvx",
      "args": ["--refresh", "--from", "nexus-dev-toolkit", "nexus-mcp"]
    }
  }
}

Add [typesafe] to the package name ("nexus-dev-toolkit[typesafe]") to enable TypeSafe/Jev-powered detection — nexus init --typesafe does this for you.

MCP Tools

Tool	Purpose
ingest_architecture_doc	Load arch doc → knowledge/rules/arch-summary.md; also classifies project_shape (web_app, mobile_app, backend_api, infrastructure, data_pipeline, cli_or_library) and has_infrastructure_component, so /scaffold knows whether to generate a UI shell, IaC deliverables, or both
load_task	Load a CSV task row into context — maps whatever column headers your CSV actually uses onto the standard task fields
generate_project_rules	Generate AGENTS.md from arch doc
resolve_package_versions	Resolve exact versions via the real tool — npm/pnpm/yarn/pub/go/cargo/maven/gradle/pip, or Terraform/OpenTofu, Helm, and Ansible for infrastructure-shaped projects

---

Custom Skills

nexus skill add my-code-review
# Edit .claude/commands/my-code-review.md
# Type /my-code-review in Claude Code

Custom skills live alongside built-in skills in .claude/commands/ — versioned in your repo, shared across the team.

---

License

MIT