nexus-dev-toolkit 3.0.1__tar.gz → 3.1.0__tar.gz

{nexus_dev_toolkit-3.0.1/nexus_dev_toolkit.egg-info → nexus_dev_toolkit-3.1.0}/PKG-INFO

@@ -1,16 +1,17 @@
 Metadata-Version: 2.4
 Name: nexus-dev-toolkit
-Version: 3.0.1
-Summary: LLM-agnostic developer workflow toolkit — Day 0 scaffold + Day 1 EPAV
+Version: 3.1.0
+Summary: Developer workflow toolkit for Claude Code — Day 0 scaffold + Day 1 EPAV
 Author-email: Ronald dela Cruz <rcdelacruz@users.noreply.github.com>
 License-Expression: MIT
 Project-URL: Homepage, https://nexus.coderstudio.co
+Project-URL: Documentation, https://nexus.coderstudio.co/docs
 Project-URL: Repository, https://github.com/rcdelacruz/nexus-dev-toolkit
 Project-URL: Issues, https://github.com/rcdelacruz/nexus-dev-toolkit/issues
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: mcp[cli]>=1.27.1
 Requires-Dist: typer>=0.12.0
 Requires-Dist: rich>=13.0.0
 Provides-Extra: dev
@@ -20,12 +21,11 @@ Dynamic: license-file
 
 # nexus-dev-toolkit
 
-[![PyPI version](https://img.shields.io/pypi/v/nexus-dev-toolkit)](https://pypi.org/project/nexus-dev-toolkit/)
-[![Python](https://img.shields.io/pypi/pyversions/nexus-dev-toolkit)](https://pypi.org/project/nexus-dev-toolkit/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 Developer workflow toolkit for Claude Code. Gives any team a structured Day 0 scaffold and repeatable Day 1 feature cycle via the EPAV methodology.
 
+**[Documentation](https://nexus.coderstudio.co/docs)**
+
 ---
 
 ## Why
@@ -83,33 +83,52 @@ cd my-project
 nexus init .
 ```
 
-### 4. Build the knowledge graph
+### 4. Place your reference docs
+
+Before running `/scaffold`, put everything Claude needs in `docs/`:
 
-Open the project in Claude Code and run:
 ```
-/graphify .
+docs/
+├── arch-docs/   ← architecture doc, ADRs
+├── figma/       ← Figma export ZIP
+├── brd/         ← Business Requirements Document
+└── prd/         ← Product Requirements Document
 ```
 
-This generates `graphify-out/graph.json` — required by all EPAV skills.
-
 ### 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, run in Claude Code:
+```
+/graphify .
+```
+
+This generates `graphify-out/graph.json` — required by all EPAV skills before starting Day 1.
+
 ---
 
 ## The Workflow
 
 ### Day 0 — `/scaffold` (once per project)
 
-EVALUATE → PLAN → APPLY → VALIDATE. Produces a production-grade project from your architecture document and Figma design: correct stack, mock auth, mock data, design system, AGENTS.md — zero external dependencies. Runs `npm install && npm run dev` (or equivalent) from commit one.
+Produces a production-grade project from your architecture document and Figma design: correct stack, mock auth, mock data, design system, AGENTS.md — zero external dependencies. Runs `npm install && npm run dev` (or equivalent) from commit one.
 
 ### Day 1 — EPAV (every feature, every sprint)
 
 ```
-/evaluate   →   /plan   →   /apply   →   /validate
+/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.

{nexus_dev_toolkit-3.0.1 → nexus_dev_toolkit-3.1.0}/README.md

@@ -1,11 +1,10 @@
 # nexus-dev-toolkit
 
-[![PyPI version](https://img.shields.io/pypi/v/nexus-dev-toolkit)](https://pypi.org/project/nexus-dev-toolkit/)
-[![Python](https://img.shields.io/pypi/pyversions/nexus-dev-toolkit)](https://pypi.org/project/nexus-dev-toolkit/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 Developer workflow toolkit for Claude Code. Gives any team a structured Day 0 scaffold and repeatable Day 1 feature cycle via the EPAV methodology.
 
+**[Documentation](https://nexus.coderstudio.co/docs)**
+
 ---
 
 ## Why
@@ -63,33 +62,52 @@ cd my-project
 nexus init .
 ```
 
-### 4. Build the knowledge graph
+### 4. Place your reference docs
+
+Before running `/scaffold`, put everything Claude needs in `docs/`:
 
-Open the project in Claude Code and run:
 ```
-/graphify .
+docs/
+├── arch-docs/   ← architecture doc, ADRs
+├── figma/       ← Figma export ZIP
+├── brd/         ← Business Requirements Document
+└── prd/         ← Product Requirements Document
 ```
 
-This generates `graphify-out/graph.json` — required by all EPAV skills.
-
 ### 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, run in Claude Code:
+```
+/graphify .
+```
+
+This generates `graphify-out/graph.json` — required by all EPAV skills before starting Day 1.
+
 ---
 
 ## The Workflow
 
 ### Day 0 — `/scaffold` (once per project)
 
-EVALUATE → PLAN → APPLY → VALIDATE. Produces a production-grade project from your architecture document and Figma design: correct stack, mock auth, mock data, design system, AGENTS.md — zero external dependencies. Runs `npm install && npm run dev` (or equivalent) from commit one.
+Produces a production-grade project from your architecture document and Figma design: correct stack, mock auth, mock data, design system, AGENTS.md — zero external dependencies. Runs `npm install && npm run dev` (or equivalent) from commit one.
 
 ### Day 1 — EPAV (every feature, every sprint)
 
 ```
-/evaluate   →   /plan   →   /apply   →   /validate
+/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.

{nexus_dev_toolkit-3.0.1 → nexus_dev_toolkit-3.1.0}/nexus_cli.py

@@ -16,7 +16,7 @@ app.add_typer(rule_app, name="rule")
 
 console = Console()
 
-_VERSION = "3.0.1"
+_VERSION = "3.1.0"
 
 _LOGO = """\
 [cyan]███╗   ██╗███████╗██╗  ██╗██╗   ██╗███████╗[/cyan]
@@ -52,8 +52,24 @@ _BUILTIN_SKILLS = [
     "apply.md",
     "validate.md",
     "epav.md",
+    "code-review.md",
+    "database-review.md",
+    "deployment-review.md",
+    "performance-review.md",
+    "monitoring-review.md",
 ]
 
+_AGENTS_SRC = Path(__file__).parent / "tools" / "agents"
+
+_BUILTIN_AGENTS = [
+    "deployment-reviewer.md",
+    "code-reviewer.md",
+    "performance-reviewer.md",
+    "monitoring-reviewer.md",
+    "database-reviewer.md",
+]
+
+
 # ── .claude/settings.json ────────────────────────────────────────────────────
 
 _CLAUDE_SETTINGS = {
@@ -95,6 +111,7 @@ def _init_project(project_dir: Path) -> list[str]:
     """
     nexus init — sets up:
       .claude/commands/     ← built-in skills
+      .claude/agents/       ← built-in subagents
       .claude/settings.json ← PostToolUse graphify hook
       knowledge/            ← empty scaffold
     """
@@ -111,6 +128,17 @@ def _init_project(project_dir: Path) -> list[str]:
             shutil.copy2(src, dest)
             created.append(f".claude/commands/{skill_name}")
 
+    # .claude/agents/ — copy built-in subagents
+    agents_dir = project_dir / ".claude" / "agents"
+    agents_dir.mkdir(parents=True, exist_ok=True)
+
+    for agent_name in _BUILTIN_AGENTS:
+        src = _AGENTS_SRC / agent_name
+        dest = agents_dir / agent_name
+        if src.exists() and not dest.exists():
+            shutil.copy2(src, dest)
+            created.append(f".claude/agents/{agent_name}")
+
     # .claude/settings.json — PostToolUse graphify hook
     settings_path = project_dir / ".claude" / "settings.json"
     if not settings_path.exists():

{nexus_dev_toolkit-3.0.1 → nexus_dev_toolkit-3.1.0/nexus_dev_toolkit.egg-info}/PKG-INFO

@@ -1,16 +1,17 @@
 Metadata-Version: 2.4
 Name: nexus-dev-toolkit
-Version: 3.0.1
-Summary: LLM-agnostic developer workflow toolkit — Day 0 scaffold + Day 1 EPAV
+Version: 3.1.0
+Summary: Developer workflow toolkit for Claude Code — Day 0 scaffold + Day 1 EPAV
 Author-email: Ronald dela Cruz <rcdelacruz@users.noreply.github.com>
 License-Expression: MIT
 Project-URL: Homepage, https://nexus.coderstudio.co
+Project-URL: Documentation, https://nexus.coderstudio.co/docs
 Project-URL: Repository, https://github.com/rcdelacruz/nexus-dev-toolkit
 Project-URL: Issues, https://github.com/rcdelacruz/nexus-dev-toolkit/issues
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: mcp[cli]>=1.27.1
 Requires-Dist: typer>=0.12.0
 Requires-Dist: rich>=13.0.0
 Provides-Extra: dev
@@ -20,12 +21,11 @@ Dynamic: license-file
 
 # nexus-dev-toolkit
 
-[![PyPI version](https://img.shields.io/pypi/v/nexus-dev-toolkit)](https://pypi.org/project/nexus-dev-toolkit/)
-[![Python](https://img.shields.io/pypi/pyversions/nexus-dev-toolkit)](https://pypi.org/project/nexus-dev-toolkit/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 Developer workflow toolkit for Claude Code. Gives any team a structured Day 0 scaffold and repeatable Day 1 feature cycle via the EPAV methodology.
 
+**[Documentation](https://nexus.coderstudio.co/docs)**
+
 ---
 
 ## Why
@@ -83,33 +83,52 @@ cd my-project
 nexus init .
 ```
 
-### 4. Build the knowledge graph
+### 4. Place your reference docs
+
+Before running `/scaffold`, put everything Claude needs in `docs/`:
 
-Open the project in Claude Code and run:
 ```
-/graphify .
+docs/
+├── arch-docs/   ← architecture doc, ADRs
+├── figma/       ← Figma export ZIP
+├── brd/         ← Business Requirements Document
+└── prd/         ← Product Requirements Document
 ```
 
-This generates `graphify-out/graph.json` — required by all EPAV skills.
-
 ### 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, run in Claude Code:
+```
+/graphify .
+```
+
+This generates `graphify-out/graph.json` — required by all EPAV skills before starting Day 1.
+
 ---
 
 ## The Workflow
 
 ### Day 0 — `/scaffold` (once per project)
 
-EVALUATE → PLAN → APPLY → VALIDATE. Produces a production-grade project from your architecture document and Figma design: correct stack, mock auth, mock data, design system, AGENTS.md — zero external dependencies. Runs `npm install && npm run dev` (or equivalent) from commit one.
+Produces a production-grade project from your architecture document and Figma design: correct stack, mock auth, mock data, design system, AGENTS.md — zero external dependencies. Runs `npm install && npm run dev` (or equivalent) from commit one.
 
 ### Day 1 — EPAV (every feature, every sprint)
 
 ```
-/evaluate   →   /plan   →   /apply   →   /validate
+/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.

{nexus_dev_toolkit-3.0.1 → nexus_dev_toolkit-3.1.0}/nexus_dev_toolkit.egg-info/SOURCES.txt

@@ -9,7 +9,15 @@ nexus_dev_toolkit.egg-info/dependency_links.txt
 nexus_dev_toolkit.egg-info/entry_points.txt
 nexus_dev_toolkit.egg-info/requires.txt
 nexus_dev_toolkit.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_server.py
 tools/__init__.py
+tools/agents/__init__.py
+tools/agents/code-reviewer.md
+tools/agents/database-reviewer.md
+tools/agents/deployment-reviewer.md
+tools/agents/monitoring-reviewer.md
+tools/agents/performance-reviewer.md
 tools/epav/__init__.py
 tools/epav/arch_ingest.py
 tools/epav/package_resolver.py
@@ -17,8 +25,13 @@ tools/epav/project_rules.py
 tools/epav/task_loader.py
 tools/epav/skills/__init__.py
 tools/epav/skills/apply.md
+tools/epav/skills/code-review.md
+tools/epav/skills/database-review.md
+tools/epav/skills/deployment-review.md
 tools/epav/skills/epav.md
 tools/epav/skills/evaluate.md
+tools/epav/skills/monitoring-review.md
+tools/epav/skills/performance-review.md
 tools/epav/skills/plan.md
 tools/epav/skills/scaffold.md
 tools/epav/skills/validate.md

{nexus_dev_toolkit-3.0.1 → nexus_dev_toolkit-3.1.0}/nexus_dev_toolkit.egg-info/requires.txt

@@ -1,4 +1,4 @@
-mcp[cli]>=1.0.0
+mcp[cli]>=1.27.1
 typer>=0.12.0
 rich>=13.0.0
 

{nexus_dev_toolkit-3.0.1 → nexus_dev_toolkit-3.1.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "nexus-dev-toolkit"
-version = "3.0.1"
-description = "LLM-agnostic developer workflow toolkit — Day 0 scaffold + Day 1 EPAV"
+version = "3.1.0"
+description = "Developer workflow toolkit for Claude Code — Day 0 scaffold + Day 1 EPAV"
 authors = [
     {name = "Ronald dela Cruz", email = "rcdelacruz@users.noreply.github.com"}
 ]
@@ -9,7 +9,7 @@ readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
 dependencies = [
-    "mcp[cli]>=1.0.0",
+    "mcp[cli]>=1.27.1",
     "typer>=0.12.0",
     "rich>=13.0.0",
 ]
@@ -20,6 +20,7 @@ nexus-mcp = "nexus_server:main"
 
 [project.urls]
 Homepage = "https://nexus.coderstudio.co"
+Documentation = "https://nexus.coderstudio.co/docs"
 Repository = "https://github.com/rcdelacruz/nexus-dev-toolkit"
 Issues = "https://github.com/rcdelacruz/nexus-dev-toolkit/issues"
 
@@ -42,6 +43,7 @@ include = ["tools*"]
 
 [tool.setuptools.package-data]
 "tools.epav" = ["skills/*.md"]
+"tools.agents" = ["*.md"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"

nexus_dev_toolkit-3.1.0/tests/test_cli.py

@@ -0,0 +1,105 @@
+import json
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from nexus_cli import app, _BUILTIN_SKILLS, _BUILTIN_AGENTS, _KNOWLEDGE_DIRS
+
+runner = CliRunner()
+
+
+@pytest.fixture()
+def tmp_project(tmp_path):
+    return tmp_path
+
+
+def test_init_creates_commands(tmp_project):
+    result = runner.invoke(app, ["init", str(tmp_project)])
+    assert result.exit_code == 0
+    commands_dir = tmp_project / ".claude" / "commands"
+    assert commands_dir.exists()
+    for skill in _BUILTIN_SKILLS:
+        assert (commands_dir / skill).exists(), f"Missing skill: {skill}"
+
+
+def test_init_creates_agents(tmp_project):
+    result = runner.invoke(app, ["init", str(tmp_project)])
+    assert result.exit_code == 0
+    agents_dir = tmp_project / ".claude" / "agents"
+    assert agents_dir.exists()
+    for agent in _BUILTIN_AGENTS:
+        assert (agents_dir / agent).exists(), f"Missing agent: {agent}"
+
+
+
+def test_init_creates_knowledge_dirs(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project)])
+    for d in _KNOWLEDGE_DIRS:
+        assert (tmp_project / d).exists(), f"Missing dir: {d}"
+
+
+def test_init_creates_settings_json(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project)])
+    settings = tmp_project / ".claude" / "settings.json"
+    assert settings.exists()
+    data = json.loads(settings.read_text())
+    assert "hooks" in data
+    assert "PostToolUse" in data["hooks"]
+
+
+def test_init_creates_mcp_json(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project)])
+    mcp = tmp_project / ".mcp.json"
+    assert mcp.exists()
+    data = json.loads(mcp.read_text())
+    assert "nexus" in data["mcpServers"]
+    assert data["mcpServers"]["nexus"]["command"] == "uvx"
+
+
+def test_init_idempotent(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project)])
+    result = runner.invoke(app, ["init", str(tmp_project)])
+    assert result.exit_code == 0
+    assert "Already initialized" in result.output
+
+
+def test_skill_add(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project)])
+    result = runner.invoke(app, ["skill", "add", "my-custom-skill", "--dir", str(tmp_project)])
+    assert result.exit_code == 0
+    skill_file = tmp_project / ".claude" / "commands" / "my-custom-skill.md"
+    assert skill_file.exists()
+    assert "/my-custom-skill" in skill_file.read_text()
+
+
+def test_skill_add_idempotent(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project)])
+    runner.invoke(app, ["skill", "add", "my-custom-skill", "--dir", str(tmp_project)])
+    result = runner.invoke(app, ["skill", "add", "my-custom-skill", "--dir", str(tmp_project)])
+    assert result.exit_code == 0
+    assert "already exists" in result.output
+
+
+def test_skill_list(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project)])
+    result = runner.invoke(app, ["skill", "list", "--dir", str(tmp_project)])
+    assert result.exit_code == 0
+    assert "/scaffold" in result.output
+    assert "/evaluate" in result.output
+
+
+def test_rule_add(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project)])
+    result = runner.invoke(app, ["rule", "add", "api-standards", "--dir", str(tmp_project)])
+    assert result.exit_code == 0
+    rule_file = tmp_project / "knowledge" / "rules" / "api-standards.md"
+    assert rule_file.exists()
+
+
+def test_rule_list(tmp_project):
+    runner.invoke(app, ["init", str(tmp_project)])
+    runner.invoke(app, ["rule", "add", "api-standards", "--dir", str(tmp_project)])
+    result = runner.invoke(app, ["rule", "list", "--dir", str(tmp_project)])
+    assert result.exit_code == 0
+    assert "api-standards" in result.output

nexus_dev_toolkit-3.1.0/tests/test_server.py

@@ -0,0 +1,21 @@
+from mcp.server.fastmcp import FastMCP
+
+from tools.epav import register_epav_tools
+
+
+def test_epav_tools_register():
+    mcp = FastMCP("test")
+    register_epav_tools(mcp)
+    tool_names = {t.name for t in mcp._tool_manager.list_tools()}
+    assert "ingest_architecture_doc" in tool_names
+    assert "load_task" in tool_names
+    assert "generate_project_rules" in tool_names
+    assert "resolve_package_versions" in tool_names
+
+
+def test_epav_tools_register_idempotent():
+    mcp = FastMCP("test")
+    register_epav_tools(mcp)
+    register_epav_tools(mcp)
+    tool_names = [t.name for t in mcp._tool_manager.list_tools()]
+    assert tool_names.count("load_task") == 1

nexus_dev_toolkit-3.1.0/tools/agents/code-reviewer.md

@@ -0,0 +1,93 @@
+---
+name: code-reviewer
+description: MUST BE USED for code reviews, code quality analysis, best practices enforcement, design patterns, refactoring suggestions, and maintainability improvements. Use proactively after code changes.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: sonnet
+---
+
+You are an expert Code Reviewer. Before reviewing any code, you MUST first discover the context of the repo you are working in.
+
+## Required Output Format (follow this every run)
+
+**Part 1 — Repo Context (markdown, always first):**
+
+```
+## Repo Context
+- **Stack:** <language>, <framework>, <version>
+- **Key dependencies:** <relevant libs>
+- **Conventions:** <naming, patterns, component structure in use>
+- **Linting:** <config found or none>
+```
+
+**Part 2 — Findings (JSON code block, immediately after the repo context):**
+
+```json
+{
+  "blocked": false,
+  "overall_severity": "critical|high|medium|low|info|none",
+  "summary": "2-3 sentence overview of the review",
+  "findings": [
+    {
+      "id": "CR-001",
+      "severity": "critical|high|medium|low|info",
+      "category": "bug|error-handling|complexity|naming|duplication|type-safety|performance|maintainability|security",
+      "file": "path/to/file",
+      "line": 42,
+      "title": "Short title",
+      "description": "What the problem is and why it matters",
+      "suggestion": "How to fix it"
+    }
+  ]
+}
+```
+
+Rules:
+- `blocked`: `true` if any finding has severity `critical`
+- `overall_severity`: highest severity across all findings; `none` if no findings
+- `file` and `line`: use `null` if not applicable
+- No prose after the JSON block
+
+If a `## Repo Context` block is already present in your input, copy it verbatim as your first section and skip Step 1 entirely.
+
+## Step 1: Discover Repo Context (MANDATORY — do this before anything else)
+
+1. **Read project docs** — look for `CLAUDE.md`, `AGENTS.md`, `README.md`, `docs/` for conventions and rules.
+2. **Identify the stack** — read the relevant manifest (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, etc.).
+3. **Check project structure** — run `find . -maxdepth 3 -type f | grep -v node_modules | grep -v .git | head -60`.
+4. **Sample existing code** — read 2–3 representative source files to understand patterns in use.
+5. **Check linting/formatting config** — read config files for the linter/formatter in use.
+
+Only after completing the above should you begin the review. Adapt all feedback to the actual stack found.
+
+## Review Checklist
+
+### Correctness
+- Logic errors, off-by-one errors, incorrect conditionals
+- Null/nil/undefined handling — are edge cases covered?
+- Concurrency issues — race conditions, shared mutable state
+- Error propagation — are errors caught, logged, and handled correctly?
+
+### Security
+- Input validation at system boundaries (user input, external APIs)
+- SQL injection, command injection, XSS risks
+- Secrets or credentials hardcoded or logged
+- Authentication and authorization checks present where needed
+
+### Code Quality
+- Functions doing too many things (single responsibility)
+- Deeply nested conditionals (>3 levels)
+- Duplicate logic that should be extracted
+- Naming — does the name describe what the thing actually does?
+- Dead code, commented-out code, TODOs without tickets
+
+### Maintainability
+- Complex logic without explanation (non-obvious WHY)
+- Missing or incorrect types/signatures
+- Test coverage — are critical paths tested?
+- Breaking changes — does this affect callers, APIs, or contracts?
+
+### Performance
+- N+1 query patterns
+- Unnecessary work inside loops
+- Missing indexes on frequently queried fields
+- Blocking operations on hot paths