← back to home

Getting Started

nexus-dev-toolkit gives your team a repeatable AI-assisted workflow in two distinct phases: Day 0 — a one-time production-grade project boilerplate, run once by one person — and Day 1 — the daily EPAV loop every developer runs for every feature, for the life of the project.

Day 0 is a one-person job. One owner — usually the tech lead — runs /scaffold once, before anyone starts feature work. Individual developers should never run /scaffold during Day 1: doing so re-scaffolds the project. Once Day 0 is done, every developer works exclusively in Day 1, forever.

Overview

Once your project is set up, this is what you'll run every day:

/evaluate <task>  →  /plan  →  /apply  →  /validate  →  /code-review

One task from your dev tasks CSV, four EPAV steps plus a code review, repeat forever. Full Day 1 walkthrough ↓

/code-review isn't one of the four EPAV phases — it's a separate reviewer skill — but it's the recommended last step before calling a task done. 4 more reviewer skills (database, deployment, performance, monitoring) are also available any time — see built-in skills.

Autonomous loop — apply ↔ validate can retry itself without a human cranking every turn. See the loop guide.
First time in this project? You need install and a one-time Day 0 scaffold before Day 1 applies — both covered next, in order: Setup → Day 0 → Day 1.

Setup

1
Install uv
$ curl -LsSf https://astral.sh/uv/install.sh | sh
2
Install Claude Code
$ npm install -g @anthropic-ai/claude-code
$ claude login
3
Install graphify (strongly recommended)
graphify builds a queryable knowledge graph of your codebase — every file, function, and relationship mapped. EPAV skills query this graph before touching any code to understand blast radius and cross-file dependencies.

With graphify: scoped subgraph queries — fast, accurate, low token cost. Auto-updates after every file edit via the PostToolUse hook.
Without graphify: EPAV skills still work but fall back to full file reads — slower, more token-heavy, and blast radius analysis is best-effort only. 
$ uv tool install graphifyy
$ graphify install    # registers /graphify skill into Claude Code
Alternative: codegraph — a different knowledge-graph tool EPAV skills can use instead of graphify. 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.
4
Install nexus-dev-toolkit
$ uv tool install nexus-dev-toolkit

nexus init

Run once inside your project folder. All nexus commands operate on the current directory by default — .claude/, knowledge/, and .mcp.json are created relative to where you run them.

Always cd into your project first, then run nexus init . — the dot means "here". 
$ cd my-project
$ nexus init .                        # Claude Code (default)
$ nexus init . --tool opencode       # OpenCode

Claude Code (default)

.claude/
├── commands/
│   ├── scaffold.md          ← /scaffold         — Day 0 setup
│   ├── evaluate.md          ← /evaluate         — orient on task
│   ├── plan.md              ← /plan             — blueprint
│   ├── apply.md             ← /apply            — implement
│   ├── validate.md          ← /validate         — verify
│   ├── epav.md              ← /epav             — full cycle guide
│   ├── code-review.md       ← /code-review      — reviewer skill
│   ├── database-review.md   ← /database-review  — reviewer skill
│   ├── deployment-review.md ← /deployment-review
│   ├── performance-review.md← /performance-review
│   └── monitoring-review.md ← /monitoring-review
├── agents/
│   ├── code-reviewer.md
│   ├── database-reviewer.md
│   ├── deployment-reviewer.md
│   ├── performance-reviewer.md
│   └── monitoring-reviewer.md
└── settings.json            ← PostToolUse: graphify auto-update hook (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

Agents are automatically adapted for OpenCode compatibility — Claude Code-specific frontmatter fields (tools, model) are stripped on copy. The graphify plugin fires on every tool execution via tool.execute.after — only scaffolded if you picked graphify at nexus init's --graph-backend prompt. Pick codegraph instead and nothing is scaffolded here; codegraph wires and syncs itself via codegraph install && codegraph init. 
.opencode/
├── commands/
│   ├── scaffold.md          ← /scaffold         — Day 0 setup
│   ├── evaluate.md          ← /evaluate         — orient on task
│   ├── plan.md              ← /plan             — blueprint
│   ├── apply.md             ← /apply            — implement
│   ├── validate.md          ← /validate         — verify
│   ├── epav.md              ← /epav             — full cycle guide
│   ├── code-review.md       ← /code-review      — reviewer skill
│   ├── database-review.md   ← /database-review  — reviewer skill
│   ├── deployment-review.md ← /deployment-review
│   ├── performance-review.md← /performance-review
│   └── monitoring-review.md ← /monitoring-review
├── agents/
│   ├── code-reviewer.md
│   ├── database-reviewer.md
│   ├── deployment-reviewer.md
│   ├── performance-reviewer.md
│   └── monitoring-reviewer.md
└── plugins/
│   └── graphify.js          ← tool.execute.after: graphify auto-update (graphify backend only)
knowledge/
├── rules/
├── patterns/
├── prompts/dev/
└── retros/
opencode.json                ← MCP server config

Day 0 — /scaffold (one-time, reference)

Run once per project, by one person — usually the tech lead — before anyone starts feature work. Never re-run during Day 1. Produces a production-grade scaffold from your architecture document and Figma design. No business logic, no live integrations — mock auth, mock data, zero external dependencies.

Day 0's entry point is /scaffold, not /evaluate — it runs the same Evaluate → Plan → Apply → Validate shape as Day 1, just once, kicked off from your architecture doc instead of a task description.

Prerequisites

1
Place all reference documents in docs/
Keep everything Claude needs in one place:
  • docs/arch-docs/ — architecture doc, ADRs
  • docs/figma/ — Figma export ZIP
  • docs/brd/ — Business Requirements Document
  • docs/prd/ — Product Requirements Document
2
Run nexus init .
Sets up .claude/commands/, knowledge/, and .mcp.json.
3
Run /scaffold
/scaffold
Claude reads your docs and produces a production-grade scaffold.
4
Build the knowledge graph
/graphify .              # if you chose graphify at init
$ codegraph install && codegraph init  # if you chose codegraph, run in your terminal
Run after scaffold completes — now there's real code to graph. EPAV skills use whichever backend 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.
/scaffold runs EVALUATE first, then stops and waits. You review and type the next command to continue. The flow is:

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

What happens inside each of those four phases — EVALUATE, PLAN, APPLY, VALIDATE:

EVALUATE (via /scaffold, not typed separately)

Claude summarises 10 key decisions from your arch doc and Figma before writing a single line of code:

# Question
1 Stack decisions and why
2 Data model — tables, relationships, indexes
3 Infrastructure needed from day one
4 Middleware + auth flow
5 Error response format
6 Security rules and constraints
7 Design tokens — Figma oklch/hex → hsl() for web, Color() for Flutter
8 Component inventory — every component, variants, states
9 Layout patterns — grid, breakpoints, responsive
10 Iconography — library, sizes, style

Claude stops. Review the summary, then type /plan to continue.

PLAN (type /plan)

Blueprint only — no code. Four outputs:

Output Contents
Infrastructure Directory structure, schema, env vars, auth flow, error handler
UI shell Component list, props interfaces, page layouts, build order
AGENTS.md Project rules for all AI tools — coding standards, git conventions, quality gates
knowledge/ Coding standards, patterns, prompt templates, design system spec

Claude stops. Review the blueprint, then type /apply to generate code.

APPLY (type /apply)

First step — always: Claude calls resolve_package_versions before writing any file. Exact versions from the real package manager lock file — never from AI memory.

// MCP tool — call this first
resolve_package_versions({
  packages: ["next@16", "react@19", "@supabase/supabase-js@2"],
  stack_hint: "Next.js 16 TypeScript"
})
// → { "versions": { "next": "16.3.2", "react": "19.1.0", ... } }

Then generates everything in one scaffold:

Category Files
Config .gitignore, .env.example, ESLint, Prettier, TypeScript
Auth (mock) Login sets mock-role cookie (8h). No credentials checked. Route guard reads cookie.
Infrastructure Schema migration, error handler, health check, seed script
Git hooks Husky + lint-staged + commitlint. chmod +x .husky/pre-commit. HUSKY=0 for CI.
CI GitHub Actions: lint, typecheck, test, build
Design system Tailwind config, globals.css (hsl() tokens — never oklch), font loading
Components All components with every visual state — default, hover, focus, disabled, loading, empty, error
Pages All pages responsive at 320/768/1024/1440px with mock data
Project rules AGENTS.md, knowledge/rules/coding-standards.md
Never write "latest" or semver ranges (^ ~) in the package manifest. Use exact versions from resolve_package_versions. Never use npx create-next-app or any scaffold CLI.

VALIDATE (type /validate)

Build must pass first, then Claude runs a 19-point checklist:

Category Checks
Packages (4) Stable versions, no deprecated APIs, lock file pinned, no CVEs
Infrastructure (6) Structure matches arch, schema matches data model, env vars documented, production logging, security headers, DB pooling
UI fidelity (6) Matches Figma, responsive at 4 breakpoints, all visual states, WCAG AA, props typed for Day 1, no API calls in components
AGENTS.md + knowledge (2) Coding standards match arch, design system spec saved
Git hooks (1) Pre-commit hook configured and executable

Every [BLOCKER] and [FIX NOW] must be fixed before Day 0 is called complete.

Success: npm install && npm run dev works. Zero credentials needed.

Day 0 is done — that scaffold happens once. Everything below is Day 1: the loop you'll run for the rest of the project.

Day 1 — EPAV (the daily loop)

The same commands from the top of this page, in full, one phase at a time. One task from the dev tasks CSV. Four EPAV steps plus a code review. Repeat forever.

/evaluate <task>  →  /plan  →  /apply  →  /validate  →  /code-review

Want apply ↔ validate to retry itself automatically instead of waiting on a human each turn? See the autonomous loop guide.

/evaluate

Orient on the task before touching any code.

1
Knowledge graph query
graphify query or codegraph explore, whichever backend is active. Find all files the task touches. Map the blast radius — what else references those files.
2
Check knowledge/
Load relevant rules, patterns, and prior retros.
3
Output
Affected files, acceptance criteria restated, risks flagged. Stops and waits for approval.

/plan

Blueprint only — no code written.

1
Blast radius check
graphify path, or codegraph impact as the closest available check (it takes one symbol, not a file pair). Confirm relationships between primary files. State what else will be affected.
2
Numbered blueprint
File by file — what changes and why. Files created / modified / deleted. AGENTS.md rules that apply.
3
Wait for /apply
No code until the plan is approved.

/apply

Implement exactly what the plan says. No scope creep.

Day 1 replaces With
Mock data in components Real DB client calls
Mock auth cookie Real auth provider
Placeholder Route Handlers Validated API handlers with error handling
Schema file Applied migration + RLS policies

graphify auto-updates after every file edit — via the PostToolUse hook in .claude/settings.json (Claude Code) or the tool.execute.after plugin in .opencode/plugins/graphify.js (OpenCode). Both are installed automatically by nexus init if you picked graphify. codegraph updates itself via its own background sync daemon — no hook needed, and none is scaffolded.

/validate

1
Build must pass first
npm run build / flutter build apk / go build ./... — fix all errors before continuing.
2
Acceptance criteria
Every criterion from the CSV task: [PASS] / [FAIL] / [PARTIAL]
3
Classify and fix
[BLOCKER] and [FIX NOW] must be resolved before the task is done. [BACKLOG] items go to knowledge/retros/.
4
Contribute patterns back
If APPLY revealed a better approach, add it to knowledge/patterns/.

/code-review

Run once VALIDATE passes, before calling the task done. Not one of the four EPAV phases — a separate reviewer skill — but the recommended last step on every task. See built-in skills for the full reviewer list (database, deployment, performance, monitoring).

That's the full EPAV methodology — Day 0 and Day 1. Everything from here down is tooling reference: MCP setup, built-in skills & agents, custom skills, rules, and file layout. Read once, come back as needed.

MCP Server Setup

MCP tools power the graph queries and task-loading calls used throughout /evaluate and /apply above — set this up once, alongside install. nexus init writes .mcp.json automatically. For Claude Desktop, add manually:

Claude Code (project-level)

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

Claude Desktop (macOS)

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "nexus": {
      "command": "uvx",
      "args": ["--refresh", "--from", "nexus-dev-toolkit", "nexus-mcp"]
    }
  }
}

OpenCode (project-level)

nexus init . --tool opencode writes opencode.json automatically. To add manually:

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "nexus-mcp": {
      "type": "local",
      "command": ["uvx", "--refresh", "--from", "nexus-dev-toolkit", "nexus-mcp"]
    }
  }
}

MCP Tool Reference

Tool Purpose When to call
ingest_architecture_doc Extract arch doc sections → knowledge/rules/arch-summary.md Day 0, Step 2 — before /scaffold
load_task Load a CSV task row + knowledge-graph blast radius into context Day 1, start of /evaluate
generate_project_rules Generate AGENTS.md + knowledge/ structure from arch doc Day 0 PLAN — before writing files
resolve_package_versions Run real package manager in temp dir → exact pinned versions Day 0 APPLY — must be first step

Built-in Skills

The full list behind every command used so far — plus the reviewer skills, which aren't part of any EPAV phase and run on their own.

Skill Trigger Phase
EPAV Workflow
scaffold.md /scaffold Day 0 — one-time setup
evaluate.md /evaluate Day 1 — orient on task
plan.md /plan Day 1 — blueprint
apply.md /apply Day 1 — implement
validate.md /validate Day 1 — verify
epav.md /epav Day 1 — full cycle guide
Reviewers
code-review.md /code-review Review code quality, bugs, security
database-review.md /database-review Review schema, migrations, queries
deployment-review.md /deployment-review Review CI/CD, Docker, infra config
performance-review.md /performance-review Review performance and bottlenecks
monitoring-review.md /monitoring-review Review observability and alerting

Built-in Agents

Subagents copied to .claude/agents/ on nexus init. Claude Code can spawn them automatically based on context, or you can ask Claude to use one directly.

Agent Triggers when
code-reviewer Code quality review, best practices, maintainability
database-reviewer Schema changes, migrations, query optimization
deployment-reviewer CI/CD pipelines, Docker, infrastructure config
performance-reviewer Performance bottlenecks, caching, resource usage
monitoring-reviewer Observability gaps, logging, metrics, alerting
Reviewers ship in two forms: as skills (/code-review) you invoke manually, and as agents (code-reviewer) Claude can spawn automatically. Both are installed by nexus init.

Custom Skills

$ nexus skill add my-review

Creates .claude/commands/my-review.md with a starter template. Edit it, then type /my-review in Claude Code. For OpenCode, manually copy the file to .opencode/commands/. 

# .claude/commands/code-review.md

# /code-review

**code-review** — review the current diff for correctness, security, and style.

## Steps

### 1 — Load context
Run graphify query on changed files. Check knowledge/rules/ for relevant standards.

### 2 — Review
Check: correctness, security, performance, style, test coverage.

### 3 — Output
Findings grouped by severity: [BLOCKER] / [FIX NOW] / [BACKLOG]

Rules

$ nexus rule add api-standards

Creates knowledge/rules/api-standards.md. Skills reference rules via knowledge/ — the AI reads them during EVALUATE and APPLY to enforce project standards.

All Commands

Command Description
Project Setup
nexus init [dir] Initialize for Claude Code (default)
nexus init [dir] --tool opencode Initialize for OpenCode
nexus update Update the nexus CLI itself to latest — does not touch any project's .claude/.opencode files. In a real terminal, asks whether to also sync the current directory; scripted/CI runs skip the prompt automatically
nexus update --sync Same as above, but skips the prompt and always syncs the current directory's skills/agents (skipped if it isn't a nexus project)
nexus sync [dir] Sync built-in skills & agents to latest versions (custom files untouched)
nexus doctor [dir] Validate project setup — checks tools, skills, agents, MCP config, knowledge graph (graphify/codegraph)
nexus --version Show installed version
Skills
nexus skill list List all skills in .claude/commands/
nexus skill add <name> Create a custom skill
Agents
nexus agent list List all subagents in .claude/agents/
nexus agent add <name> Create a custom subagent
Rules
nexus rule list List all rules in knowledge/rules/
nexus rule add <name> Create a project rule

knowledge/ Layout

knowledge/
├── rules/
│   ├── arch-summary.md      ← generated by ingest_architecture_doc
│   └── coding-standards.md  ← generated by generate_project_rules
├── patterns/
│   └── implement-and-test.md ← E→P→A→V pattern
├── prompts/dev/             ← task prompt templates
└── retros/                  ← [BACKLOG] items from /validate
built by CoderStudio Labs