nurosys-agents

Portable AI agent skills for Claude Code, Cursor, and Codex — supports backend, frontend, and full-stack monolith projects. One install gives you a coherent end-to-end developer journey: brainstorm → plan → architect → autonomously build.

Built on Serena for symbol-level code intelligence (replaces the older code-review-graph peer dependency).

v2.0 note: This package was previously published as nurosys-agent-skills. It has been renamed to nurosys-agents with a refreshed skill set and Serena as the MCP. See "Migrating from v1.x" below if you're upgrading.

Install

npm install --save-dev nurosys-agents
npm exec nurosys-agent-setup

The setup wizard detects your stack (backend / frontend / monolith) and asks which IDE(s) you use, then wires everything: skills, MCP, project-memory rules, IDE-specific module-runner.

Serena runs via uvx. If you don't have it: https://docs.astral.sh/uv/getting-started/installation/

The end-to-end journey

Backend (NestJS / Express / Fastify / Koa)

1. /create-blueprint all          → bootstrap project-memory/
2. /brainstorm <problem>          → explore 3-5 approaches
3. /architect <chosen approach>   → plan modules + approval gate (NEVER writes code)
4. /module-runner <feature-dir>   → autonomous build, review, security, commit per module

Frontend (React / Next.js — adds a UX-planning step)

1. /create-blueprint all          → bootstrap project-memory/ (incl. design-system.md)
2. /brainstorm <problem>          → explore 3-5 approaches
3. /ux-architect <feature>        → UX/layout plan with component reuse from /vuexy-component-guide
4. /architect <feature>           → technical module plan referencing the UX plan (NEVER writes code)
5. /module-runner <feature-dir>   → autonomous build, lint, test, review, security, commit per module

Plus on-demand utilities (both stacks):

• /quick-execute <small task> — fast execution, no plan gate
• /code-reviewer — review the current branch
• /security-assessment [diff|full|path:X] — standalone security audit
• /explore-codebase / /refactor-safely / /debug-issue — Serena-powered navigation tools

Skills

| Skill | Purpose | |---|---| | /create-blueprint | Bootstrap project-memory/ artifacts from your codebase (constitution, auth-model, repo-map, architecture, models, quality-playbook, core-memory). Run first on a new project. | | /brainstorm | Explore 3-5 distinct approaches to a problem. No code, no files written. | | /architect | Pure planner. Reads project-memory, consults /auth-and-permissions and /security-assessment as read-only sub-agents, writes a module-wise plan + per-module prompts. Never writes code. Hard approval gate before module prompts are generated. | | /module-runner | The autonomous executor. For each planned module: spawns sub-agents for implement → build/test → code review → fixes → security audit → fixes → commit → push. Main agent stays clean. IDE-specific variants: Claude Code (Task tool), Cursor (subagents), Codex (foreground fallback). | | /code-reviewer | Full constitution-aligned review. Standalone writes documentation/reports/REVIEW_REPORT_*.md; sub-agent mode returns JSON for /module-runner. | | /security-assessment | Auth, input, injection, deps, data-exposure, crypto/secrets audit. Standalone writes documentation/reports/SECURITY_ASSESSMENT_*.md; sub-agent mode returns JSON. | | /auth-and-permissions | Generic auth review, fully driven by project-memory/auth-model.md (no hardcoded framework names). Used by /code-reviewer for auth-heavy reviews and by /architect to draft auth approach during planning. | | /quick-execute | Fast execution for small tasks. Hard guardrail STOPs and recommends /architect if scope exceeds 3 files or touches auth / data-model / public-API / dependencies. | | /explore-codebase | Symbol-level navigation (Serena). | | /refactor-safely | Bounded-blast-radius refactors via Serena's symbolic edit tools (rename_symbol, replace_symbol_body, safe_delete_symbol). | | /debug-issue | Stack-trace-driven debugging with Serena. |

Frontend-only additions

| Skill | Purpose | |---|---| | /ux-architect | Pure UX planner. Reads project-memory/design-system.md + repo-map.md + auth-model.md, consults /vuexy-component-guide as a sub-agent to maximize component reuse, surveys existing pages via Serena, writes <feature>_UX_PLAN.md. Never writes code. Hands off to /architect for technical decomposition. | | /vuexy-component-guide | MUI v7 + Vuexy component reference. Standalone mode = conversational guidance. Sub-agent mode (used by /ux-architect) = JSON reuse-candidates + gaps. |

Frontend /code-reviewer additionally enforces 23 React-specific rules (Rules of React, rerender optimization, rendering performance, advanced patterns).

Frontend /security-assessment covers client-side concerns: XSS, CSP, NEXT_PUBLIC_ leakage, third-party scripts, cookies/storage.

Frontend /auth-and-permissions audits client-side gating (private routes, useAuth, permission keys) — UI correctness, not the security boundary itself (server enforces).

What gets created in your project

Claude Code

| Path | Purpose | |---|---| | .claude/skills/<name>/ | Skill directories (symlinks into the package) | | .claude/agents/module-runner.md | Claude-variant module-runner | | .mcp.json | Serena MCP registration (Claude Code) | | CLAUDE.md, AGENTS.md | Project instructions (symlinked to package INSTRUCTIONS.md) |

Cursor

| Path | Purpose | |---|---| | .cursor/mcp.json | Serena MCP registration | | .cursor/rules/serena.mdc | Always-apply rule: use Serena before grep/read | | .cursor/rules/<skill>.mdc | One description-triggered rule per skill | | .cursor/subagents/<name>.md | 6 subagent wrappers used by Cursor-variant /module-runner |

Codex

| Path | Purpose | |---|---| | AGENTS.md | Project instructions (shared with Claude Code) | | .codex/rules/default.rules | Starlark exec policy: allows npm, git, node, uvx | | .codex/workflows/module-runner.md | Codex-variant module-runner (foreground fallback) | | ~/.codex/config.toml | User-level Serena MCP config |

Project-memory wiring (all IDEs)

Run npm exec nurosys-setup-rules after /create-blueprint all to wire project-memory/*.md into IDE rule systems.

Migrating from v1.x (nurosys-agent-skills)

If you have v1.x installed:

1. npm uninstall nurosys-agent-skills
2. npm install --save-dev nurosys-agents
3. npm exec nurosys-agent-setup (re-runs setup with new package layout)
4. Optional cleanup of old artifacts:
   • rm scripts/run-feature-modules.sh (replaced by /module-runner skill)
   • Remove code-review-graph from MCP configs if present (Serena replaces it)

The major changes in v2:

• Renamed: nurosys-agent-skills → nurosys-agents
• Serena replaces code-review-graph as the MCP
• /architect never writes code — its only outputs are planning documents
• /module-runner replaces feature-module-runner — IDE-native sub-agent orchestration (Task tool / Cursor subagents) instead of a shell script
• New skills: /brainstorm, /quick-execute, /security-assessment
• /auth-and-permissions is fully generic — driven entirely by project-memory/auth-model.md
• Deleted workflows: build-feature-backend.workflow.md, backend-quality-review.md, add-new-api-feature-module.md, feature-module-runner.md (their content absorbed into /module-runner or moved to per-project project-memory/architecture.md)

Stack support

| Stack | Status | |---|---| | Backend (NestJS / Express / Fastify / Koa) | ✅ First-class (v2.0) | | Frontend (React / Next.js) | ✅ First-class (v2.1) — same architecture as backend plus /ux-architect + /vuexy-component-guide | | Monolith (full-stack repo: Node API + React frontend) | ✅ First-class (v2.1) — mirrors the frontend skill set (backend skills + /ux-architect + /vuexy-component-guide) |

License

MIT