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.

Supports either Serena (symbol-level LSP via uvx) or code-review-graph (knowledge graph via pip). You choose at npm exec nurosys-agent-setup; the choice is stored in .nurosys-agents.json.

v2.0 note: This package was previously published as nurosys-agent-skills. See "Migrating from v1.x" below if you're upgrading.

Install

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

Update

npm install nurosys-agents@latest
npm exec nurosys-agent-setup 

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

| Provider | Prerequisites | |----------|----------------| | code-review-graph (default) | Python 3.10+, pip install code-review-graph | | Serena | uv / uvx — 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 — navigation tools (Serena or code-review-graph per setup)

Linear task management (optional)

If you use Linear for issue tracking, you can integrate the nurosys-agents workflow directly into your task lifecycle. During setup, answer "Install Linear task management? [y/N]" to wire these six skills:

Backlog → Todo → In Progress → In Review → Done
  ↓         ↓         ↓           ↓
  /         /         /           /linear-mr-review
  prepare   engineer  develop

| Skill | Purpose | |---|---| | /linear-task-orchestrator | List your Linear issues, pick one, and route to the right next skill based on status + tags. | | /linear-create-backlog | File new work. Collects title, goal, context, priority → creates Backlog issue. | | /linear-prepare-backlog NUR-XXX | Enrich Backlog → Todo via /brainstorm subagent, optional /ux-architect (frontend/monolith only), follow-up questions, and scope refinement. | | /linear-engineer-task NUR-XXX | Pure planner. Runs /architect subagent, shows the plan, asks for approval, tags architecture-approved. Never writes code. | | /linear-develop-task NUR-XXX [--quick-execute] | Implements the issue via /module-runner (normal mode) or a single implementation subagent (quick-execute). Opens GitLab MR, sets In Review. | | /linear-mr-review NUR-XXX | Reviews the MR: runs /code-reviewer + /security-assessment in parallel, auto-fixes BLOCKER/HIGH/CRITICAL findings, adds system-reviewed tag. |

Setup: Answer yes to the Linear prompt during npm exec nurosys-agent-setup. You'll be asked for your Linear project name and team name, then the MCP will be registered for your IDE.

IDE support:

• Claude Code: run /mcp in Claude to authenticate with Linear (one-time setup)
• Cursor/Codex: authenticate via your IDE's MCP settings
• All three IDEs run the same end-to-end workflow

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: implement → build/test → code review → fixes → security audit → fixes → commit → push. Claude Code: skill at .claude/skills/module-runner/. Cursor: subagents. Codex: foreground workflow. | | /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 | Navigate the codebase (Serena symbols or code-review-graph queries — per .nurosys-agents.json). | | /refactor-safely | Bounded-blast-radius refactors (Serena symbolic edits or graph refactor_tool). | | /debug-issue | Systematic debugging from a stack trace or symptom (provider-specific tools). |

Linear task management (optional, all stacks)

| Skill | Purpose | |---|---| | /linear-task-orchestrator | Browse Linear issues in your configured project, pick one, and route to the correct next workflow (prepare-backlog, engineer-task, develop-task, mr-review). | | /linear-create-backlog | File new work in Linear with title, goal, context, priority → creates Backlog issue. Confirms before creating. | | /linear-prepare-backlog NUR-XXX | Promote Backlog → Todo: runs /brainstorm subagent, optional /ux-architect (frontend/monolith), asks scope/acceptance/deadline Qs, appends preparation notes. | | /linear-engineer-task NUR-XXX | Pure architect. Runs /architect subagent, presents plan, asks for approval, tags architecture-approved. Never writes code. | | /linear-develop-task NUR-XXX [--quick-execute] | Implements via /module-runner (normal) or single implementation subagent (quick mode). Opens GitLab MR to main, sets In Review. | | /linear-mr-review NUR-XXX | Reviews the MR: parallel /code-reviewer + /security-assessment subagents, fixes BLOCKER/HIGH/CRITICAL, tags system-reviewed, posts summary. |

Requires setup: run npm exec nurosys-agent-setup and answer yes to "Install Linear task management?"

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 your code-intelligence MCP, 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), including module-runner/ | | .claude/skills/linear-config/reference.md | Linear config (project, team, MCP server names) — real file, per-project | | .claude/agents/linear-*.md | Linear workflow agents (engineer-task, develop-task, mr-review) if installed | | .mcp.json | Serena or code-review-graph MCP; Linear (linear-server) if installed | | .nurosys-agents.json | { "codeIntel": "serena" \| "code-review-graph" } | | INSTRUCTIONS.md, CLAUDE.md, AGENTS.md | Generated project instructions (provider + shared skills) | | ~/.claude/plugins/installed_plugins.json | superpowers always; serena plugin only when Serena is selected |

Cursor

| Path | Purpose | |---|---| | .cursor/mcp.json | Serena or code-review-graph MCP; Linear (linear) if installed | | .cursor/rules/serena.mdc or code-review-graph.mdc | Always-apply MCP guidance (one file, per your setup choice) | | .cursor/rules/<skill>.mdc | One description-triggered rule per skill | | .cursor/rules/linear-*.mdc | Linear workflow rules (engineer-task, develop-task, mr-review) if installed | | .cursor/linear-config/reference.md | Linear config (copied from .claude/skills/) if installed | | .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/workflows/linear-*.md | Linear workflow definitions (engineer-task, develop-task, mr-review) if installed | | .codex/linear-config/reference.md | Linear config (copied from .claude/skills/) if installed | | ~/.codex/config.toml | User-level Serena or code-review-graph MCP (optional prompt); Linear (linear) if installed |

Project-memory wiring (all IDEs)

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

Upgrading from 2.3.x

If you already use nurosys-agents 2.3:

npm install nurosys-agents@latest
npm exec nurosys-agent-setup

Setup will:

• Ask which code intelligence MCP you want (code-review-graph is the default).
• Write .nurosys-agents.json and regenerate INSTRUCTIONS.md for that provider.
• Move Claude /module-runner from .claude/agents/module-runner.md to .claude/skills/module-runner/ (removes the legacy agent file).
• Swap MCP keys in .cursor/mcp.json / .mcp.json (only one of Serena or code-review-graph).

Cursor: /module-runner behavior is unchanged (same module-runner.cursor.md pipeline and subagents).

If CLAUDE.md / AGENTS.md still point at the old package INSTRUCTIONS symlink, delete them and re-run setup so they link to project INSTRUCTIONS.md.

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 stale MCP keys if you switch providers (re-run setup)

The major changes in v2:

• Renamed: nurosys-agent-skills → nurosys-agents
• Code intelligence: choose Serena or code-review-graph at setup (not both by default)
• /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)

See CHANGELOG.md for version-by-version notes.

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