nexus-dev-toolkit-jev 3.1.9__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- nexus_dev_toolkit_jev-3.1.9/LICENSE +21 -0
- nexus_dev_toolkit_jev-3.1.9/PKG-INFO +262 -0
- nexus_dev_toolkit_jev-3.1.9/README.md +238 -0
- nexus_dev_toolkit_jev-3.1.9/nexus_cli.py +1031 -0
- nexus_dev_toolkit_jev-3.1.9/nexus_dev_toolkit_jev.egg-info/PKG-INFO +262 -0
- nexus_dev_toolkit_jev-3.1.9/nexus_dev_toolkit_jev.egg-info/SOURCES.txt +46 -0
- nexus_dev_toolkit_jev-3.1.9/nexus_dev_toolkit_jev.egg-info/dependency_links.txt +1 -0
- nexus_dev_toolkit_jev-3.1.9/nexus_dev_toolkit_jev.egg-info/entry_points.txt +3 -0
- nexus_dev_toolkit_jev-3.1.9/nexus_dev_toolkit_jev.egg-info/requires.txt +11 -0
- nexus_dev_toolkit_jev-3.1.9/nexus_dev_toolkit_jev.egg-info/top_level.txt +3 -0
- nexus_dev_toolkit_jev-3.1.9/nexus_server.py +16 -0
- nexus_dev_toolkit_jev-3.1.9/pyproject.toml +54 -0
- nexus_dev_toolkit_jev-3.1.9/setup.cfg +4 -0
- nexus_dev_toolkit_jev-3.1.9/tests/test_cli.py +645 -0
- nexus_dev_toolkit_jev-3.1.9/tests/test_iac_package_resolvers.py +220 -0
- nexus_dev_toolkit_jev-3.1.9/tests/test_server.py +21 -0
- nexus_dev_toolkit_jev-3.1.9/tests/test_typesafe_judgments.py +230 -0
- nexus_dev_toolkit_jev-3.1.9/tools/__init__.py +0 -0
- nexus_dev_toolkit_jev-3.1.9/tools/agents/__init__.py +0 -0
- nexus_dev_toolkit_jev-3.1.9/tools/agents/code-reviewer.md +86 -0
- nexus_dev_toolkit_jev-3.1.9/tools/agents/database-reviewer.md +95 -0
- nexus_dev_toolkit_jev-3.1.9/tools/agents/deployment-reviewer.md +97 -0
- nexus_dev_toolkit_jev-3.1.9/tools/agents/monitoring-reviewer.md +95 -0
- nexus_dev_toolkit_jev-3.1.9/tools/agents/performance-reviewer.md +98 -0
- nexus_dev_toolkit_jev-3.1.9/tools/agents/pr-verifier.md +63 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/__init__.py +14 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/arch_ingest.py +299 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/graph_backend.py +88 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/judgment.py +50 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/package_resolver.py +624 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/project_rules.py +267 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/__init__.py +0 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/apply.md +44 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/code-review.md +24 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/commit.md +48 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/create-pr.md +64 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/database-review.md +91 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/deployment-review.md +94 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/dev-tasks-planner.md +196 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/epav.md +46 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/evaluate.md +45 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/monitoring-review.md +91 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/performance-review.md +93 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/plan.md +46 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/pr-review.md +35 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/scaffold.md +419 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/skills/validate.md +57 -0
- nexus_dev_toolkit_jev-3.1.9/tools/epav/task_loader.py +228 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ronald dela Cruz
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,262 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: nexus-dev-toolkit-jev
|
|
3
|
+
Version: 3.1.9
|
|
4
|
+
Summary: Developer workflow toolkit for Claude Code — Day 0 scaffold + Day 1 EPAV (experimental TypeSafe/Jev build -- installs as nexus-jev/nexus-jev-mcp, side by side with the real nexus-dev-toolkit)
|
|
5
|
+
Author-email: Ronald dela Cruz <rcdelacruz@users.noreply.github.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://nexus.coderstudio.co
|
|
8
|
+
Project-URL: Documentation, https://nexus.coderstudio.co/docs
|
|
9
|
+
Project-URL: Repository, https://github.com/rcdelacruz/nexus-dev-toolkit
|
|
10
|
+
Project-URL: Issues, https://github.com/rcdelacruz/nexus-dev-toolkit/issues
|
|
11
|
+
Requires-Python: >=3.10
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Requires-Dist: mcp[cli]<2.0.0,>=1.27.1
|
|
15
|
+
Requires-Dist: typer>=0.12.0
|
|
16
|
+
Requires-Dist: rich>=13.0.0
|
|
17
|
+
Provides-Extra: dev
|
|
18
|
+
Requires-Dist: pytest>=8.0.0; extra == "dev"
|
|
19
|
+
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
|
|
20
|
+
Requires-Dist: typesafe-sdk<1.0.0,>=0.7.0; extra == "dev"
|
|
21
|
+
Provides-Extra: typesafe
|
|
22
|
+
Requires-Dist: typesafe-sdk<1.0.0,>=0.7.0; extra == "typesafe"
|
|
23
|
+
Dynamic: license-file
|
|
24
|
+
|
|
25
|
+
# nexus-dev-toolkit
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
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.
|
|
29
|
+
|
|
30
|
+
**[Documentation](https://nexus.coderstudio.co/docs)**
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Why
|
|
35
|
+
|
|
36
|
+
Ad-hoc AI prompting doesn't scale. Every dev prompts differently, context drifts, and nobody knows what the AI was told last sprint.
|
|
37
|
+
|
|
38
|
+
nexus-dev-toolkit gives your team a single workflow:
|
|
39
|
+
|
|
40
|
+
- **Day 0** — scaffold the project once, production-grade, zero credentials needed
|
|
41
|
+
- **Day 1** — every feature follows the same four steps: evaluate → plan → apply → validate
|
|
42
|
+
|
|
43
|
+
Every skill, every rule, every pattern lives in the project repo — versioned, shared, and enforced.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Setup
|
|
48
|
+
|
|
49
|
+
### 1. Install prerequisites
|
|
50
|
+
|
|
51
|
+
**uv** (recommended package manager):
|
|
52
|
+
```bash
|
|
53
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**Claude Code:**
|
|
57
|
+
```bash
|
|
58
|
+
npm install -g @anthropic-ai/claude-code
|
|
59
|
+
claude login
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
**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.
|
|
63
|
+
|
|
64
|
+
| | With graphify | Without graphify |
|
|
65
|
+
|---|---|---|
|
|
66
|
+
| Context loading | Scoped subgraph — fast, low token cost | Full file reads — slow, high token cost |
|
|
67
|
+
| Blast radius | Accurate, graph-backed | Best-effort, grep-based |
|
|
68
|
+
| Auto-update | PostToolUse hook keeps graph current | N/A |
|
|
69
|
+
| EPAV skills | Full capability | Degraded but functional |
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
uv tool install graphifyy # PyPI package name has double y; command is "graphify"
|
|
73
|
+
graphify install # registers /graphify skill into Claude Code
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
**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.
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
npm i -g @colbymchenry/codegraph
|
|
80
|
+
codegraph install # wires codegraph into Claude Code / OpenCode / etc.
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### 2. Install nexus-dev-toolkit
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
uv tool install nexus-dev-toolkit
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### 3. Initialize your project
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
cd my-project
|
|
93
|
+
nexus init . # Claude Code (default), prompts for graphify/codegraph/none + TypeSafe
|
|
94
|
+
nexus init . --tool opencode # OpenCode
|
|
95
|
+
nexus init . --graph-backend codegraph # skip the graph-backend prompt, use codegraph
|
|
96
|
+
nexus init . --typesafe # skip the TypeSafe prompt, enable it
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**TypeSafe/Jev** _(optional)_ — replaces a handful of hardcoded keyword-matching
|
|
100
|
+
heuristics in the EPAV tools (which architecture-doc section is about auth vs.
|
|
101
|
+
security, which of ~30 stack tags an arch doc mentions, which package manager
|
|
102
|
+
or IaC tool fits a free-text hint, which CSV column means "acceptance
|
|
103
|
+
criteria") with an actual judgment call. Every one of those tools works
|
|
104
|
+
exactly the same without it — TypeSafe is off by default, `pip install
|
|
105
|
+
nexus-dev-toolkit` never installs it, and every judgment falls back to the
|
|
106
|
+
original heuristic if it isn't enabled or the API call fails. Enable at init
|
|
107
|
+
with `--typesafe` (or answer `y` at the prompt), then set `TYPESAFE_API_KEY`
|
|
108
|
+
(get one at https://console.typesafe.ai/). `nexus doctor` reports whether
|
|
109
|
+
it's wired up and whether the key is set. See `tools/README.md` for how it's
|
|
110
|
+
implemented.
|
|
111
|
+
|
|
112
|
+
### 4. Place your reference docs
|
|
113
|
+
|
|
114
|
+
Before running `/scaffold`, put everything Claude needs in `docs/`:
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
docs/
|
|
118
|
+
├── arch-docs/ ← architecture doc, ADRs
|
|
119
|
+
├── figma/ ← Figma export ZIP
|
|
120
|
+
├── brd/ ← Business Requirements Document
|
|
121
|
+
└── prd/ ← Product Requirements Document
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### 5. Start Day 0
|
|
125
|
+
|
|
126
|
+
Open the project in Claude Code and run:
|
|
127
|
+
```
|
|
128
|
+
/scaffold
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
`/scaffold` runs EVALUATE first then stops. You drive each phase by typing the next command:
|
|
132
|
+
|
|
133
|
+
```
|
|
134
|
+
/scaffold → (review) → /plan → (review) → /apply → (review) → /validate
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### 6. Build the knowledge graph
|
|
138
|
+
|
|
139
|
+
After `/scaffold` completes, build whichever backend you chose at init:
|
|
140
|
+
```
|
|
141
|
+
/graphify . # if you chose graphify
|
|
142
|
+
codegraph install && codegraph init # if you chose codegraph, run in your terminal
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
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.
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## The Workflow
|
|
150
|
+
|
|
151
|
+
### Day 0 — `/scaffold` (once per project)
|
|
152
|
+
|
|
153
|
+
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 `apply`d against real cloud accounts on Day 0.
|
|
154
|
+
|
|
155
|
+
### Day 1 — EPAV (every feature, every sprint)
|
|
156
|
+
|
|
157
|
+
```
|
|
158
|
+
/evaluate <task> → /plan → /apply → /validate
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
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.
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## What `nexus init` Creates
|
|
166
|
+
|
|
167
|
+
`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`.
|
|
168
|
+
|
|
169
|
+
**Claude Code** (`nexus init .`):
|
|
170
|
+
```
|
|
171
|
+
.claude/
|
|
172
|
+
├── commands/ ← EPAV skills + 5 reviewer skills (/code-review, etc.)
|
|
173
|
+
├── agents/ ← 5 reviewer subagents (code-reviewer, database-reviewer, etc.)
|
|
174
|
+
└── settings.json ← PostToolUse: graphify auto-updates after every file edit (graphify backend only)
|
|
175
|
+
knowledge/
|
|
176
|
+
├── rules/ ← coding standards, arch decisions
|
|
177
|
+
├── patterns/ ← reusable implementation patterns
|
|
178
|
+
├── prompts/dev/ ← task prompt templates
|
|
179
|
+
└── retros/ ← retrospective notes
|
|
180
|
+
.mcp.json ← MCP server config
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
**OpenCode** (`nexus init . --tool opencode`):
|
|
184
|
+
```
|
|
185
|
+
.opencode/
|
|
186
|
+
├── commands/ ← same EPAV skills + reviewer skills
|
|
187
|
+
├── agents/ ← same reviewer subagents (adapted for OpenCode)
|
|
188
|
+
└── plugins/
|
|
189
|
+
└── graphify.js ← tool.execute.after: graphify auto-update (graphify backend only)
|
|
190
|
+
knowledge/ ← same structure
|
|
191
|
+
opencode.json ← MCP server config
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## Commands
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
nexus init . # Claude Code — set up .claude/ + knowledge/ + .mcp.json
|
|
200
|
+
nexus init . --tool opencode # OpenCode — set up .opencode/ + knowledge/ + opencode.json
|
|
201
|
+
nexus --version # show installed version
|
|
202
|
+
nexus update # update the CLI itself; asks whether to also sync in a real terminal
|
|
203
|
+
nexus update --sync # skip the prompt, always sync the current project's skills/agents too
|
|
204
|
+
nexus sync # sync built-in skills & agents to latest (custom files untouched)
|
|
205
|
+
nexus doctor # validate project setup
|
|
206
|
+
|
|
207
|
+
nexus skill list # list all skills in .claude/commands/
|
|
208
|
+
nexus skill add my-review # create a custom skill
|
|
209
|
+
|
|
210
|
+
nexus agent list # list all subagents in .claude/agents/
|
|
211
|
+
nexus agent add my-agent # create a custom subagent
|
|
212
|
+
|
|
213
|
+
nexus rule list # list all rules in knowledge/rules/
|
|
214
|
+
nexus rule add api-standards # create a project rule
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## MCP Server
|
|
220
|
+
|
|
221
|
+
`nexus init` writes `.mcp.json` automatically. For Claude Desktop, add manually:
|
|
222
|
+
|
|
223
|
+
```json
|
|
224
|
+
{
|
|
225
|
+
"mcpServers": {
|
|
226
|
+
"nexus": {
|
|
227
|
+
"command": "uvx",
|
|
228
|
+
"args": ["--refresh", "--from", "nexus-dev-toolkit", "nexus-mcp"]
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Add `[typesafe]` to the package name (`"nexus-dev-toolkit[typesafe]"`) to enable
|
|
235
|
+
TypeSafe/Jev-powered detection — `nexus init --typesafe` does this for you.
|
|
236
|
+
|
|
237
|
+
### MCP Tools
|
|
238
|
+
|
|
239
|
+
| Tool | Purpose |
|
|
240
|
+
|---|---|
|
|
241
|
+
| `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 |
|
|
242
|
+
| `load_task` | Load a CSV task row into context — maps whatever column headers your CSV actually uses onto the standard task fields |
|
|
243
|
+
| `generate_project_rules` | Generate `AGENTS.md` from arch doc |
|
|
244
|
+
| `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 |
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## Custom Skills
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
nexus skill add my-code-review
|
|
252
|
+
# Edit .claude/commands/my-code-review.md
|
|
253
|
+
# Type /my-code-review in Claude Code
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
Custom skills live alongside built-in skills in `.claude/commands/` — versioned in your repo, shared across the team.
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
260
|
+
## License
|
|
261
|
+
|
|
262
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
# nexus-dev-toolkit
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
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.
|
|
5
|
+
|
|
6
|
+
**[Documentation](https://nexus.coderstudio.co/docs)**
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Why
|
|
11
|
+
|
|
12
|
+
Ad-hoc AI prompting doesn't scale. Every dev prompts differently, context drifts, and nobody knows what the AI was told last sprint.
|
|
13
|
+
|
|
14
|
+
nexus-dev-toolkit gives your team a single workflow:
|
|
15
|
+
|
|
16
|
+
- **Day 0** — scaffold the project once, production-grade, zero credentials needed
|
|
17
|
+
- **Day 1** — every feature follows the same four steps: evaluate → plan → apply → validate
|
|
18
|
+
|
|
19
|
+
Every skill, every rule, every pattern lives in the project repo — versioned, shared, and enforced.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Setup
|
|
24
|
+
|
|
25
|
+
### 1. Install prerequisites
|
|
26
|
+
|
|
27
|
+
**uv** (recommended package manager):
|
|
28
|
+
```bash
|
|
29
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
**Claude Code:**
|
|
33
|
+
```bash
|
|
34
|
+
npm install -g @anthropic-ai/claude-code
|
|
35
|
+
claude login
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
**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.
|
|
39
|
+
|
|
40
|
+
| | With graphify | Without graphify |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| Context loading | Scoped subgraph — fast, low token cost | Full file reads — slow, high token cost |
|
|
43
|
+
| Blast radius | Accurate, graph-backed | Best-effort, grep-based |
|
|
44
|
+
| Auto-update | PostToolUse hook keeps graph current | N/A |
|
|
45
|
+
| EPAV skills | Full capability | Degraded but functional |
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
uv tool install graphifyy # PyPI package name has double y; command is "graphify"
|
|
49
|
+
graphify install # registers /graphify skill into Claude Code
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
**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.
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
npm i -g @colbymchenry/codegraph
|
|
56
|
+
codegraph install # wires codegraph into Claude Code / OpenCode / etc.
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### 2. Install nexus-dev-toolkit
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
uv tool install nexus-dev-toolkit
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### 3. Initialize your project
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
cd my-project
|
|
69
|
+
nexus init . # Claude Code (default), prompts for graphify/codegraph/none + TypeSafe
|
|
70
|
+
nexus init . --tool opencode # OpenCode
|
|
71
|
+
nexus init . --graph-backend codegraph # skip the graph-backend prompt, use codegraph
|
|
72
|
+
nexus init . --typesafe # skip the TypeSafe prompt, enable it
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
**TypeSafe/Jev** _(optional)_ — replaces a handful of hardcoded keyword-matching
|
|
76
|
+
heuristics in the EPAV tools (which architecture-doc section is about auth vs.
|
|
77
|
+
security, which of ~30 stack tags an arch doc mentions, which package manager
|
|
78
|
+
or IaC tool fits a free-text hint, which CSV column means "acceptance
|
|
79
|
+
criteria") with an actual judgment call. Every one of those tools works
|
|
80
|
+
exactly the same without it — TypeSafe is off by default, `pip install
|
|
81
|
+
nexus-dev-toolkit` never installs it, and every judgment falls back to the
|
|
82
|
+
original heuristic if it isn't enabled or the API call fails. Enable at init
|
|
83
|
+
with `--typesafe` (or answer `y` at the prompt), then set `TYPESAFE_API_KEY`
|
|
84
|
+
(get one at https://console.typesafe.ai/). `nexus doctor` reports whether
|
|
85
|
+
it's wired up and whether the key is set. See `tools/README.md` for how it's
|
|
86
|
+
implemented.
|
|
87
|
+
|
|
88
|
+
### 4. Place your reference docs
|
|
89
|
+
|
|
90
|
+
Before running `/scaffold`, put everything Claude needs in `docs/`:
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
docs/
|
|
94
|
+
├── arch-docs/ ← architecture doc, ADRs
|
|
95
|
+
├── figma/ ← Figma export ZIP
|
|
96
|
+
├── brd/ ← Business Requirements Document
|
|
97
|
+
└── prd/ ← Product Requirements Document
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### 5. Start Day 0
|
|
101
|
+
|
|
102
|
+
Open the project in Claude Code and run:
|
|
103
|
+
```
|
|
104
|
+
/scaffold
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`/scaffold` runs EVALUATE first then stops. You drive each phase by typing the next command:
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
/scaffold → (review) → /plan → (review) → /apply → (review) → /validate
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### 6. Build the knowledge graph
|
|
114
|
+
|
|
115
|
+
After `/scaffold` completes, build whichever backend you chose at init:
|
|
116
|
+
```
|
|
117
|
+
/graphify . # if you chose graphify
|
|
118
|
+
codegraph install && codegraph init # if you chose codegraph, run in your terminal
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
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.
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## The Workflow
|
|
126
|
+
|
|
127
|
+
### Day 0 — `/scaffold` (once per project)
|
|
128
|
+
|
|
129
|
+
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 `apply`d against real cloud accounts on Day 0.
|
|
130
|
+
|
|
131
|
+
### Day 1 — EPAV (every feature, every sprint)
|
|
132
|
+
|
|
133
|
+
```
|
|
134
|
+
/evaluate <task> → /plan → /apply → /validate
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
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.
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## What `nexus init` Creates
|
|
142
|
+
|
|
143
|
+
`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`.
|
|
144
|
+
|
|
145
|
+
**Claude Code** (`nexus init .`):
|
|
146
|
+
```
|
|
147
|
+
.claude/
|
|
148
|
+
├── commands/ ← EPAV skills + 5 reviewer skills (/code-review, etc.)
|
|
149
|
+
├── agents/ ← 5 reviewer subagents (code-reviewer, database-reviewer, etc.)
|
|
150
|
+
└── settings.json ← PostToolUse: graphify auto-updates after every file edit (graphify backend only)
|
|
151
|
+
knowledge/
|
|
152
|
+
├── rules/ ← coding standards, arch decisions
|
|
153
|
+
├── patterns/ ← reusable implementation patterns
|
|
154
|
+
├── prompts/dev/ ← task prompt templates
|
|
155
|
+
└── retros/ ← retrospective notes
|
|
156
|
+
.mcp.json ← MCP server config
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
**OpenCode** (`nexus init . --tool opencode`):
|
|
160
|
+
```
|
|
161
|
+
.opencode/
|
|
162
|
+
├── commands/ ← same EPAV skills + reviewer skills
|
|
163
|
+
├── agents/ ← same reviewer subagents (adapted for OpenCode)
|
|
164
|
+
└── plugins/
|
|
165
|
+
└── graphify.js ← tool.execute.after: graphify auto-update (graphify backend only)
|
|
166
|
+
knowledge/ ← same structure
|
|
167
|
+
opencode.json ← MCP server config
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## Commands
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
nexus init . # Claude Code — set up .claude/ + knowledge/ + .mcp.json
|
|
176
|
+
nexus init . --tool opencode # OpenCode — set up .opencode/ + knowledge/ + opencode.json
|
|
177
|
+
nexus --version # show installed version
|
|
178
|
+
nexus update # update the CLI itself; asks whether to also sync in a real terminal
|
|
179
|
+
nexus update --sync # skip the prompt, always sync the current project's skills/agents too
|
|
180
|
+
nexus sync # sync built-in skills & agents to latest (custom files untouched)
|
|
181
|
+
nexus doctor # validate project setup
|
|
182
|
+
|
|
183
|
+
nexus skill list # list all skills in .claude/commands/
|
|
184
|
+
nexus skill add my-review # create a custom skill
|
|
185
|
+
|
|
186
|
+
nexus agent list # list all subagents in .claude/agents/
|
|
187
|
+
nexus agent add my-agent # create a custom subagent
|
|
188
|
+
|
|
189
|
+
nexus rule list # list all rules in knowledge/rules/
|
|
190
|
+
nexus rule add api-standards # create a project rule
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## MCP Server
|
|
196
|
+
|
|
197
|
+
`nexus init` writes `.mcp.json` automatically. For Claude Desktop, add manually:
|
|
198
|
+
|
|
199
|
+
```json
|
|
200
|
+
{
|
|
201
|
+
"mcpServers": {
|
|
202
|
+
"nexus": {
|
|
203
|
+
"command": "uvx",
|
|
204
|
+
"args": ["--refresh", "--from", "nexus-dev-toolkit", "nexus-mcp"]
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Add `[typesafe]` to the package name (`"nexus-dev-toolkit[typesafe]"`) to enable
|
|
211
|
+
TypeSafe/Jev-powered detection — `nexus init --typesafe` does this for you.
|
|
212
|
+
|
|
213
|
+
### MCP Tools
|
|
214
|
+
|
|
215
|
+
| Tool | Purpose |
|
|
216
|
+
|---|---|
|
|
217
|
+
| `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 |
|
|
218
|
+
| `load_task` | Load a CSV task row into context — maps whatever column headers your CSV actually uses onto the standard task fields |
|
|
219
|
+
| `generate_project_rules` | Generate `AGENTS.md` from arch doc |
|
|
220
|
+
| `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 |
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## Custom Skills
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
nexus skill add my-code-review
|
|
228
|
+
# Edit .claude/commands/my-code-review.md
|
|
229
|
+
# Type /my-code-review in Claude Code
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Custom skills live alongside built-in skills in `.claude/commands/` — versioned in your repo, shared across the team.
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## License
|
|
237
|
+
|
|
238
|
+
[MIT](LICENSE)
|