nurosys-agents 2.0.0

package/README.md

@@ -0,0 +1,131 @@
+# nurosys-agents
+
+Portable backend AI agent skills for **Claude Code**, **Cursor**, and **Codex**. One install, drop into any backend project, and you get a coherent end-to-end developer journey: brainstorm → plan → architect → autonomously build.
+
+Built on **[Serena](https://github.com/oraios/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
+
+```bash
+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
+
+```
+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
+```
+
+Plus on-demand utilities:
+
+- `/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. |
+
+---
+
+## 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 / Vue / Vite) | ⏳ Carried over from v1; not yet refreshed for v2 architecture |
+| Monolith | ⏳ Same as frontend |
+
+Backend is the focus of v2.0. Frontend and monolith updates will follow.
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "nurosys-agents",
+  "version": "2.0.0",
+  "description": "Portable backend agent skills (architect, code-reviewer, security-assessment, auth-and-permissions, brainstorm, quick-execute, create-blueprint) plus a multi-IDE module-runner. Built on Serena for symbolic code analysis. Works with Claude Code, Cursor, and Codex.",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/nurosys/nurosys-agents.git"
+  },
+  "homepage": "https://gitlab.com/nurosys/nurosys-agents#readme",
+  "bugs": {
+    "url": "https://gitlab.com/nurosys/nurosys-agents/-/issues"
+  },
+  "keywords": [
+    "claude",
+    "agents",
+    "skills",
+    "code-review",
+    "architecture",
+    "ai-development",
+    "cursor",
+    "codex",
+    "openai",
+    "llm"
+  ],
+  "author": "Nurosys",
+  "license": "MIT",
+  "files": [
+    ".agent/",
+    "scripts/"
+  ],
+  "bin": {
+    "nurosys-agent-setup": "scripts/setup.js",
+    "nurosys-setup-rules": "scripts/setup-rules.js"
+  },
+  "scripts": {
+    "setup": "node scripts/setup.js",
+    "setup-rules": "node scripts/setup-rules.js"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/setup-rules.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+
+/**
+ * Writes MDC rule files from project-memory/ into IDE rule directories.
+ *
+ * - Cursor    → .cursor/rules/<name>.mdc  (real files with MDC frontmatter + @file reference)
+ * - Antigravity → .agents/rules/<name>.md  (symlinks, detected when .agents/ exists)
+ *
+ * Cursor MDC files contain proper YAML frontmatter so Cursor knows when to apply each rule.
+ * The body uses an @filename reference so the live project-memory content is sourced at
+ * context-injection time — project-memory files are never inlined here.
+ *
+ * Usage:
+ *   node scripts/setup-rules.js          # from project root
+ *   npm exec nurosys-setup-rules         # via package bin
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const projectRoot   = process.cwd();
+const projectMemory = path.join(projectRoot, 'project-memory');
+
+// Maps project-memory filename → rule config per IDE
+const RULE_MAP = [
+  {
+    source:            'constitution.md',
+    cursorTarget:      'constitution.mdc',
+    antigravityTarget: 'constitution.md',
+    description:       'Non-negotiable project rules and coding standards',
+    alwaysApply:       true,
+  },
+  {
+    source:            'architecture.md',
+    cursorTarget:      'architecture.mdc',
+    antigravityTarget: 'architecture.md',
+    description:       'System architecture, module topology, and data flow',
+    alwaysApply:       true,
+  },
+  {
+    source:            'repo-map.md',
+    cursorTarget:      'repo-map.mdc',
+    antigravityTarget: 'repo-map.md',
+    description:       'Repository module layout, naming conventions, and reusable components',
+    alwaysApply:       true,
+  },
+  {
+    source:            'auth-model.md',
+    cursorTarget:      'auth-model.mdc',
+    antigravityTarget: 'auth-model.md',
+    description:       'Auth model, JWT flow, guard chain, RBAC, and tenant scoping',
+    globs:             ['src/auth/**', 'src/core/auth/**'],
+    alwaysApply:       false,
+  },
+  {
+    source:            'models.md',
+    cursorTarget:      'models.mdc',
+    antigravityTarget: 'models.md',
+    description:       'Domain model inventory and entity definitions',
+    globs:             ['src/**/*.model.ts', 'src/**/*.entity.ts'],
+    alwaysApply:       false,
+  },
+  {
+    source:            'quality-playbook.md',
+    cursorTarget:      'quality-playbook.mdc',
+    antigravityTarget: 'quality-playbook.md',
+    description:       'Code quality patterns, anti-patterns, and preferred fixes for this project',
+    alwaysApply:       false,
+  },
+  {
+    source:            'core-memory.md',
+    cursorTarget:      'core-memory.mdc',
+    antigravityTarget: 'core-memory.md',
+    description:       'Project history, design decisions, and completed modules',
+    alwaysApply:       false,
+  },
+];
+
+function isSymlink(p) {
+  try { return fs.lstatSync(p).isSymbolicLink(); } catch { return false; }
+}
+
+function buildMdcContent(entry) {
+  const lines = ['---'];
+  lines.push(`description: "${entry.description}"`);
+  if (entry.globs && entry.globs.length) {
+    lines.push(`globs: [${entry.globs.map(g => `"${g}"`).join(', ')}]`);
+  }
+  lines.push(`alwaysApply: ${entry.alwaysApply}`);
+  lines.push('---');
+  lines.push('');
+  lines.push(`@project-memory/${entry.source}`);
+  return lines.join('\n') + '\n';
+}
+
+function writeCursorRules(rulesDir) {
+  let created = 0, updated = 0, skipped = 0, missing = 0;
+
+  fs.mkdirSync(rulesDir, { recursive: true });
+
+  for (const entry of RULE_MAP) {
+    const sourcePath = path.join(projectMemory, entry.source);
+    const targetPath = path.join(rulesDir, entry.cursorTarget);
+
+    if (!fs.existsSync(sourcePath)) {
+      console.log(`  ⚠️  Skipped ${entry.cursorTarget}: project-memory/${entry.source} not found`);
+      missing++;
+      continue;
+    }
+
+    const content = buildMdcContent(entry);
+
+    if (fs.existsSync(targetPath) && !isSymlink(targetPath)) {
+      const existing = fs.readFileSync(targetPath, 'utf8');
+      if (existing === content) {
+        console.log(`  ✅ ${entry.cursorTarget} (already up to date)`);
+        skipped++;
+        continue;
+      }
+      fs.writeFileSync(targetPath, content);
+      console.log(`  🔄 ${entry.cursorTarget} (updated frontmatter)`);
+      updated++;
+      continue;
+    }
+
+    // Remove stale symlink if present
+    if (isSymlink(targetPath)) fs.unlinkSync(targetPath);
+
+    fs.writeFileSync(targetPath, content);
+    console.log(`  ✅ ${entry.cursorTarget} → @project-memory/${entry.source}`);
+    created++;
+  }
+
+  return { created, updated, skipped, missing };
+}
+
+function wireAntigravityRules(rulesDir) {
+  let created = 0, skipped = 0, missing = 0;
+
+  fs.mkdirSync(rulesDir, { recursive: true });
+
+  for (const entry of RULE_MAP) {
+    const sourcePath = path.join(projectMemory, entry.source);
+    const targetPath = path.join(rulesDir, entry.antigravityTarget);
+
+    if (!fs.existsSync(sourcePath)) {
+      console.log(`  ⚠️  Skipped ${entry.antigravityTarget}: project-memory/${entry.source} not found`);
+      missing++;
+      continue;
+    }
+
+    if (isSymlink(targetPath)) {
+      console.log(`  ✅ ${entry.antigravityTarget} (already linked)`);
+      skipped++;
+      continue;
+    }
+
+    if (fs.existsSync(targetPath)) {
+      console.log(`  ⚠️  ${entry.antigravityTarget} exists as a real file — skipping`);
+      skipped++;
+      continue;
+    }
+
+    fs.symlinkSync(path.relative(rulesDir, sourcePath), targetPath);
+    console.log(`  ✅ ${entry.antigravityTarget} → project-memory/${entry.source}`);
+    created++;
+  }
+
+  return { created, skipped, missing };
+}
+
+function runSetupRules() {
+  console.log('\n── Project-memory rules ──────────────────────────────────────');
+
+  if (!fs.existsSync(projectMemory)) {
+    console.log('  ⚠️  project-memory/ not found — skipping rules.');
+    console.log('      Run /create-blueprint all, then re-run nurosys-agent-setup.');
+    return;
+  }
+
+  let ran = false;
+
+  // Cursor — .cursor/rules/*.mdc (real files with MDC frontmatter)
+  if (fs.existsSync(path.join(projectRoot, '.cursor'))) {
+    console.log('\n  Cursor (.cursor/rules/*.mdc)');
+    const { created, updated, skipped, missing } = writeCursorRules(
+      path.join(projectRoot, '.cursor', 'rules')
+    );
+    console.log(`   ${created} created, ${updated} updated, ${skipped} already set, ${missing} missing source`);
+    ran = true;
+  }
+
+  // Antigravity — .agents/rules/*.md (symlinks)
+  if (fs.existsSync(path.join(projectRoot, '.agents'))) {
+    console.log('\n  .agents/rules (symlinks from project-memory/)');
+    const { created, skipped, missing } = wireAntigravityRules(
+      path.join(projectRoot, '.agents', 'rules')
+    );
+    console.log(`   ${created} created, ${skipped} already set, ${missing} missing source`);
+    ran = true;
+  }
+
+  // Codex — .codex/rules/ uses Starlark execution policy, not markdown context files.
+  // Project-memory context is already available via AGENTS.md (created by nurosys-agent-setup).
+  if (fs.existsSync(path.join(projectRoot, '.codex'))) {
+    console.log('\n  Codex (.codex/rules/): Starlark execution policy only — project-memory wired via AGENTS.md.');
+    ran = true;
+  }
+
+  if (!ran) return;
+
+  const totalMissing = RULE_MAP.filter(e => !fs.existsSync(path.join(projectMemory, e.source))).length;
+  if (totalMissing > 0) {
+    console.log(`\n  ℹ️  ${totalMissing} project-memory files not yet generated.`);
+    console.log('      Run /create-blueprint all to generate them.');
+  }
+}
+
+if (require.main === module) {
+  console.log('🔧  Setting up IDE rules from project-memory/\n');
+  runSetupRules();
+}
+
+module.exports = { runSetupRules };