nurosys-agents 2.0.0

package/.agent/INSTRUCTIONS.md

@@ -0,0 +1,82 @@
+<!-- nurosys-agents — global instructions wired into CLAUDE.md / AGENTS.md / GEMINI.md -->
+
+# nurosys-agents — Working Rules
+
+This file is wired into your IDE (Claude Code, Cursor, Codex, Antigravity) by `npm exec nurosys-agent-setup`. It tells the agent how to use the skills and the Serena MCP that ship with this package.
+
+---
+
+## MCP Tools: Serena (symbolic code analysis)
+
+**IMPORTANT: This project uses Serena for symbol-level code intelligence. ALWAYS prefer Serena's symbolic tools over Grep / Glob / raw Read for exploring code.** Symbol-level navigation is faster, cheaper in tokens, and gives you structural context (callers, references, definitions) that raw file scanning cannot.
+
+Serena docs: https://github.com/oraios/serena
+
+### When to use Serena FIRST
+
+- **Exploring code** — `get_symbols_overview` on a file or directory before reading anything
+- **Finding a function/class/method by name** — `find_symbol(name_path="...", include_body=false)`
+- **Reading a single symbol** — `find_symbol(name_path="...", include_body=true)` instead of reading the whole file
+- **Impact analysis / who depends on this?** — `find_referencing_symbols(name_path="...", relative_path="...")`
+- **Refactors** — `rename_symbol`, `replace_symbol_body`, `safe_delete_symbol`, `insert_after_symbol`, `insert_before_symbol`
+- **Prior-session notes** — `list_memories` then `read_memory` for project-specific context Serena has accumulated
+
+Fall back to `Grep` / `Glob` / `Read` only when the question is genuinely not symbolic (e.g. searching configs, migrations, markdown).
+
+### Key Serena tools
+
+| Tool | Use when |
+|------|----------|
+| `get_symbols_overview` | First look at a file or directory — see what's there without reading bodies |
+| `find_symbol` | Locate or read a specific symbol (class, function, method) |
+| `find_referencing_symbols` | Find every caller / reference site of a symbol |
+| `rename_symbol` | Rename a symbol + all references in one call |
+| `replace_symbol_body` | Replace a function/method body symbolically |
+| `safe_delete_symbol` | Delete a symbol after verifying no remaining references |
+| `replace_content` | Regex/string replace for non-symbol edits (small in-line changes) |
+| `list_memories` / `read_memory` | Project-specific notes from prior sessions |
+
+### Token efficiency targets
+
+- For exploration: ≤5 Serena calls
+- For code review: ≤8 Serena calls
+- For refactors: ≤6 Serena calls (locate + impact + edit + verify)
+- For debugging: ≤6 Serena calls (entry + body + callers + callees + verify)
+
+If you exceed these, narrow scope or escalate to one targeted `Read`. Don't fan out across the whole repo.
+
+---
+
+## Skills shipped by this package
+
+Slash commands (Claude Code, Cursor) or natural-language triggers:
+
+| Skill | Purpose |
+|---|---|
+| `/create-blueprint` | Bootstrap `project-memory/` — run FIRST on a new project |
+| `/brainstorm` | Explore 3-5 distinct approaches to a problem (no code) |
+| `/architect` | Plan a multi-module feature (pure planner, NEVER writes code) |
+| `/module-runner` | Autonomously execute an architected feature, module by module |
+| `/code-reviewer` | Review changed code against constitution + quality playbook |
+| `/security-assessment` | Standalone security audit (auth, input, injection, deps, data exposure) |
+| `/auth-and-permissions` | Audit a change against the project's documented auth model |
+| `/quick-execute` | Fast execution for small tasks (no planning gate) |
+| `/explore-codebase` | Navigate and understand the codebase symbolically |
+| `/refactor-safely` | Symbol-level refactors with bounded blast radius |
+| `/debug-issue` | Systematically trace a bug from its stack trace |
+
+---
+
+## The end-to-end developer journey
+
+```
+1. /create-blueprint all          → seeds project-memory/
+2. /brainstorm <problem>          → explore approaches
+3. /architect <chosen approach>   → plan, modules, approval gate
+4. /module-runner <feature-folder>→ autonomous build, review, security, commit per module
+```
+
+Quick utilities usable anywhere:
+- `/quick-execute <small task>` for one-off fixes
+- `/code-reviewer` to manually review the current branch
+- `/security-assessment diff` for a targeted security pass

package/.agent/README.md

@@ -0,0 +1,483 @@
+# Agent Skills & Workflows
+
+This folder contains reusable agent skills and workflows for building, reviewing, and maintaining your codebase with Claude. All skills reference your project's `project-memory/` documentation as the single source of truth for architectural decisions, patterns, and constraints.
+
+---
+
+## Skills
+
+Skills are specialized tools you can invoke in Claude Code. Use them by typing `/skill-name` in the chat (e.g., `/code-reviewer`).
+
+### Core Skills
+
+#### 1. **code-reviewer** — Full-stack code review
+**What it does**: Audits all uncommitted or branch-level changes against your project's constitution, quality playbook, auth model, and architecture.
+
+**When to use**: After implementing a feature or fixing a bug, before merging.
+
+**How it works**:
+1. Uses code-review-graph to analyze changed files and impact radius
+2. Loads all project-memory docs (constitution, auth-model, repo-map, etc.)
+3. Reviews code against 11 checklist categories (security, validation, DI, etc.)
+4. Generates a structured REVIEW_REPORT with blockers, highs, mediums, and suggestions
+5. Reports recommendation: APPROVE / APPROVE WITH CONDITIONS / REQUEST CHANGES
+
+**Example**:
+```
+/code-reviewer
+```
+Output: `documentation/reports/REVIEW_REPORT_<feature>_<milestone>.md`
+
+---
+
+#### 2. **architect** — Design multi-module feature implementation
+**What it does**: Decomposes a feature or system change into logically independent modules with clear dependencies, then generates implementation prompts for autonomous execution.
+
+**When to use**: Starting a new feature that spans multiple modules or requires architectural decisions.
+
+**How it works**:
+1. Phase 1: Research existing architecture using code-review-graph tools
+2. Phase 2: Decompose the feature into self-contained, independently deployable modules
+3. Phase 3: Determine implementation order based on dependencies
+4. Phase 4: Generate a master plan (`_MODULE_WISE_PLAN.md`) and ask for user approval
+5. Phase 5: Generate per-module implementation prompts (`_MODULE_<N>_<NAME>.md`)
+
+**Example**:
+```
+/architect
+
+User: "design a new feature for user invitations with team management"
+
+Output: 
+  documentation/features/user_invitations/user_invitations_MODULE_WISE_PLAN.md
+  documentation/features/user_invitations/user_invitations_MODULE_1_INVITE_FLOW.md
+  documentation/features/user_invitations/user_invitations_MODULE_2_TEAM_MANAGEMENT.md
+  ...
+```
+
+---
+
+#### 3. **create-blueprint** — Create/update project-memory artifacts
+**What it does**: Generates or refreshes project-memory documentation (constitution, auth-model, repo-map, core-memory, models, architecture, quality-playbook) to keep them in sync with your codebase.
+
+**When to use**: Setting up project-memory for the first time, or after major codebase changes to refresh documentation.
+
+**How it works**:
+1. Phase 1: Parse intent (create vs update, which artifact type)
+2. Phase 2: Analyze codebase with code-review-graph tools (≤8 calls, minimal detail)
+3. Phase 3: Read only relevant files the graph identified
+4. Phase 4: Generate artifact from standard template
+5. Phase 5: Compare with existing (if update), preserve manual decisions
+6. Phase 6: Present changes to user for approval
+7. Phase 7: Write to `project-memory/` and set up symlinks
+8. Phase 7.3: Ensure `scripts/run-feature-modules.sh` symlink exists
+
+**Example**:
+```
+/create-blueprint
+
+User: "create-blueprint auth-model"
+
+Output:
+  project-memory/auth-model.md (created)
+  .claude/docs/auth-model.md (symlink created)
+  .cursor/docs/auth-model.md (symlink created)
+```
+
+---
+
+#### 4. **auth-and-permissions** — Auth/authorization guardrails
+**What it does**: Audits backend auth/authorization changes against your project's auth model invariants and review checklists.
+
+**When to use**: Adding or modifying endpoints, guards, middleware, or auth-sensitive service logic.
+
+**How it works**:
+1. Reads your `project-memory/auth-model.md` to understand the guard chain and RBAC structure
+2. Maps endpoint security explicitly (auth mechanism, required permissions, ownership checks)
+3. Validates input surfaces and permission decorators
+4. Checks request-context propagation
+5. Enforces minimal, explicit fixes with file locations
+
+**Checklist**:
+- [ ] Endpoint auth decision is explicit (protected/public)
+- [ ] `@CanPermissions` present for protected business actions
+- [ ] Service/query layer enforces ownership/tenant scope
+- [ ] Auth-sensitive inputs validated at controller boundary
+- [ ] No controller-level assumption that guard alone authorizes mutations
+
+---
+
+#### 5. **explore-codebase** — Fast codebase navigation
+**What it does**: Quickly searches and explores code using the code-review-graph, finding functions, classes, files, and relationships without reading entire codebase.
+
+**When to use**: Answering "where is X?", "who calls Y?", "what imports Z?" questions.
+
+**How it works**:
+1. Uses semantic_search_nodes for name/keyword matching
+2. Uses query_graph patterns (callers_of, callees_of, imports_of, tests_for)
+3. Returns relevant code locations without loading full files
+4. Traverses the graph to show relationships and dependencies
+
+**Example**:
+```
+/explore-codebase
+
+User: "find all services that handle authentication"
+Output: List of auth-related services with file locations and brief context
+```
+
+---
+
+#### 6. **debug-issue** — Structured issue diagnosis
+**What it does**: Systematically diagnoses bugs and issues by analyzing code flow, tracing root causes, and suggesting fixes.
+
+**When to use**: When something is broken or behaving unexpectedly.
+
+**How it works**:
+1. Phase 1: Understand the symptom and get the error/failure description
+2. Phase 2: Trace execution flow using code-review-graph (query callers, callees)
+3. Phase 3: Identify root cause by reading relevant files
+4. Phase 4: Propose minimal fix with exact file locations and line numbers
+5. Phase 5: Verify fix and test
+
+---
+
+#### 7. **refactor-safely** — Code refactoring with impact analysis
+**What it does**: Plans and executes refactors (renames, dead code removal, restructuring) with blast-radius awareness and automated safety checks.
+
+**When to use**: Renaming functions/classes, removing dead code, restructuring modules, or cleaning up code debt.
+
+**How it works**:
+1. Phase 1: Use code-review-graph to find all references (callers, imports, tests)
+2. Phase 2: Generate a refactor preview showing all affected files
+3. Phase 3: Test the refactor in isolated changes
+4. Phase 4: Apply the refactor with verification
+
+---
+
+## Workflows
+
+Workflows are semi-autonomous processes that combine multiple skills and structured steps. They guide you through complex tasks.
+
+### Available Workflows
+
+#### 1. **build-feature-backend.workflow.md** — End-to-end feature implementation
+**What it does**: Orchestrates the complete lifecycle of implementing a backend feature from design to merge.
+
+**When to use**: Starting a new feature that needs full cycle support (plan → implement → test → review → merge).
+
+**Phases**:
+1. **Plan** — Use `/architect` to design modules
+2. **Implement** — Use `feature-module-runner` to execute per-module implementation
+3. **Test** — Write and run tests for each module
+4. **Review** — Use `/code-reviewer` for full code review
+5. **Fix** — Address review findings
+6. **Merge** — Prepare for merge (update docs, feature flags, deployment)
+
+---
+
+#### 2. **feature-module-runner.md** — Sequential module implementation
+**What it does**: Autonomously implements all modules in a feature sequentially, running implement → test → review → fix cycles for each.
+
+**When to use**: After `/architect` generates module prompts. Executes the entire feature build automatically.
+
+**How it works**:
+1. Reads the feature folder and loads per-module implementation prompts
+2. For each module (in dependency order):
+   - Implement the module
+   - Run tests
+   - Generate a feature plan
+   - Self-approve the plan
+   - Run full tests (`npm run build && npm test`)
+   - Generate a code review
+   - Fix any issues found
+   - Update `project-memory/core-memory.md` with module progress
+3. Complete when all modules are done
+
+---
+
+#### 3. **backend-quality-review.md** — Post-implementation quality gate
+**What it does**: Runs a full backend quality gate after implementation is complete, before merge.
+
+**When to use**: End of implementation phase, when ready to merge.
+
+**How it works**:
+1. Delegates to `/code-reviewer` skill for full structured review
+2. Generates REVIEW_REPORT with all findings
+3. Reports recommendation
+
+---
+
+#### 4. **add-new-api-feature-module.md** — Single API feature module template
+**What it does**: Provides structured scaffolding for implementing a single API feature module (controller, service, DTO, model, tests).
+
+**When to use**: Implementing a single module of an API feature in isolation.
+
+**How it works**:
+1. Defines required files and structure per your repo-map
+2. Provides step-by-step implementation guidance
+3. Ensures all patterns (validation, auth, error handling) are followed
+4. Includes testing strategy
+
+---
+
+## Architecture
+
+```
+User runs skill (e.g., /code-reviewer)
+           ↓
+Skill loads project-memory/ docs (single source of truth)
+           ↓
+Skill uses code-review-graph MCP tools for efficient analysis
+           ↓
+Skill reads only relevant files (targeted, not exhaustive)
+           ↓
+Skill generates report/artifact/implementation
+           ↓
+User reviews and approves changes
+```
+
+### Project-Memory (Single Source of Truth)
+
+Your project-memory folder contains:
+- **constitution.md** — Non-negotiable rules (security, validation, DI, auth, SQL, logging)
+- **auth-model.md** — JWT flow, guard chain, RBAC, identity propagation, tenant scoping
+- **repo-map.md** — Module layout, naming conventions, reusable components, entry points
+- **core-memory.md** — Historical decisions, completed modules, design lessons, patterns
+- **models.md** — Domain model inventory (entities, associations, constraints)
+- **architecture.md** — System layers, module topology, data flow, integration points
+- **quality-playbook.md** — High-signal patterns, anti-patterns, preferred fixes
+
+All skills reference these docs to make decisions. If docs are missing or stale, run:
+```bash
+/create-blueprint <artifact-type>
+```
+
+---
+
+## Quick Start
+
+### 1. Set up project-memory (first time only)
+
+```bash
+/create-blueprint constitution
+/create-blueprint auth-model
+/create-blueprint repo-map
+/create-blueprint models
+/create-blueprint architecture
+/create-blueprint core-memory
+```
+
+Edit each file to match your actual codebase. Use `/code-reviewer` to validate that your docs match reality.
+
+### 2. Implement a new feature
+
+```bash
+/architect
+
+# User: "design a new user invitation feature"
+# Architect generates: user_invitations_MODULE_WISE_PLAN.md + per-module prompts
+
+# Approve the plan, then run:
+feature-module-runner documentation/features/user_invitations/
+
+# Automatically implements all modules, tests, reviews, and fixes
+```
+
+### 3. Review changes before merging
+
+```bash
+/code-reviewer
+
+# Generates: documentation/reports/REVIEW_REPORT_<feature>_<milestone>.md
+# Reports: blockers, highs, mediums, lows + recommendation
+```
+
+### 4. Add auth to an endpoint
+
+Edit the endpoint, then:
+```bash
+/auth-and-permissions
+
+# Checklist: guards, permissions, ownership checks, input validation
+```
+
+### 5. Debug a failing test
+
+```bash
+/debug-issue
+
+# User: "test is failing with 'tenant not found'"
+# Debug traces flow, identifies root cause, suggests fix
+```
+
+### 6. Rename a service safely
+
+```bash
+/refactor-safely
+
+# User: "rename PaymentService to PaymentProcessingService"
+# Refactor shows all 47 places it's used, applies rename, runs tests
+```
+
+---
+
+## How This Integrates with Your IDE
+
+### Claude Code (Claude.ai)
+- Skills are available as `/skill-name` (e.g., `/code-reviewer`)
+- Workflows are referenced in skill documentation
+- You approve changes before they're written to disk
+
+### VSCode & JetBrains (via extensions)
+- Same skills available
+- Extension shows skill suggestions based on context
+- Symlinks in `.claude/skills/` make skills discoverable
+
+### Cursor
+- Skills available as `/skill-name` (just like Claude Code)
+- Symlinks in `.cursor/agents/` make skills discoverable
+
+---
+
+## Common Workflows by Task
+
+### "I'm starting a new feature"
+```
+1. /architect                    (design modules)
+2. Approve the plan
+3. feature-module-runner        (auto-implement all modules)
+4. /code-reviewer               (review changes)
+5. Address findings
+6. Merge!
+```
+
+### "I need to review my changes"
+```
+1. /code-reviewer               (full audit)
+2. Fix blockers/highs
+3. Address mediums
+4. Merge!
+```
+
+### "Something is broken"
+```
+1. /debug-issue                 (diagnose root cause)
+2. Implement fix
+3. /code-reviewer               (review fix)
+4. Merge!
+```
+
+### "I need to refactor something"
+```
+1. /refactor-safely             (preview impact)
+2. Apply refactor
+3. npm run build && npm test    (verify)
+4. /code-reviewer               (review refactor)
+5. Merge!
+```
+
+### "My project-memory is out of date"
+```
+1. /create-blueprint <artifact-type>   (auto-generate)
+2. Review changes
+3. Approve and write
+4. Done! (Docs now match codebase)
+```
+
+---
+
+## Best Practices
+
+### 1. Keep project-memory current
+- After each completed feature, run `feature-module-runner` which auto-updates `core-memory.md`
+- Every 2–3 weeks, run `/create-blueprint repo-map` to refresh module inventory
+- When auth patterns change, run `/create-blueprint auth-model`
+
+### 2. Let code-review-graph do the heavy lifting
+- Skills use graph tools first (get_minimal_context, semantic_search_nodes, query_graph)
+- Graph analysis is fast (structural, not textual) and gives context
+- Only relevant files are read, saving tokens and time
+
+### 3. Use targeted skills for specific concerns
+- Auth changes? Use `/auth-and-permissions`
+- Renaming? Use `/refactor-safely`
+- Debug? Use `/debug-issue`
+- General review? Use `/code-reviewer`
+
+### 4. Approve plans before implementation
+- `/architect` stops after generating the master plan for user approval
+- Don't skip the plan review — it catches architectural issues early
+- Once approved, `feature-module-runner` executes autonomously
+
+### 5. Make skills portable
+- Skills are generic and portable across projects
+- Each project has its own `project-memory/` docs
+- If copying to another project, run `/create-blueprint <all artifact types>` to customize
+
+---
+
+## Architecture Decisions
+
+### Why code-review-graph?
+- **Faster**: Structural graph analysis beats file scanning
+- **Cheaper**: Fewer tokens (minimal detail level by default)
+- **Smarter**: Returns context (callers, tests, impact) that text search can't
+
+### Why project-memory as single source of truth?
+- **Authoritative**: If project-memory conflicts with code, code is wrong
+- **Curated**: Only important patterns/decisions, not every detail
+- **Actionable**: Team members can follow rules without asking questions
+
+### Why modular feature implementation?
+- **Independent deployability**: Each module ships without breaking existing code
+- **Incremental value**: Each module delivers testable value
+- **Parallel understanding**: Smaller modules are easier to review and test
+- **Fault isolation**: A bug in module N doesn't block modules 1–N−1
+
+---
+
+## Troubleshooting
+
+### "Graph doesn't have results for my search"
+→ Run `code-review-graph build_or_update_graph` to refresh the graph (usually automatic)
+
+### "A skill is giving generic advice instead of project-specific guidance"
+→ Update your `project-memory/` docs. Skills read them to make decisions. If docs are missing, skills fall back to generic patterns.
+
+### "I want to customize a skill"
+→ You shouldn't need to. Skills read `project-memory/` to adapt to your project. If a skill doesn't fit your architecture, update project-memory instead.
+
+### "Can I share skills across projects?"
+→ Yes! Skills are generic. Copy `.agent/skills/` and `.agent/workflows/` to another project. Each project has its own `project-memory/`.
+
+---
+
+## Manifest
+
+| File | Purpose |
+|------|---------|
+| `.agent/INSTRUCTIONS.md` | Meta-instructions for all tools (code-review-graph, authentication, etc.) |
+| `.agent/skills/architect/` | Design multi-module features |
+| `.agent/skills/auth-and-permissions/` | Auth/authorization review |
+| `.agent/skills/code-reviewer/` | Full code review |
+| `.agent/skills/create-blueprint/` | Generate/update project-memory |
+| `.agent/skills/debug-issue/` | Diagnose bugs |
+| `.agent/skills/explore-codebase/` | Navigate code |
+| `.agent/skills/refactor-safely/` | Refactor with impact analysis |
+| `.agent/workflows/build-feature-backend.workflow.md` | End-to-end feature implementation |
+| `.agent/workflows/feature-module-runner.md` | Auto-execute per-module implementations |
+| `.agent/workflows/backend-quality-review.md` | Post-implementation quality gate |
+| `.agent/workflows/add-new-api-feature-module.md` | Single API module template |
+| `.agent/scripts/run-feature-modules.sh` | Script to execute feature modules |
+
+---
+
+## Next Steps
+
+1. **Set up project-memory**: Run `/create-blueprint <artifact-type>` for each artifact
+2. **Review against reality**: Use `/code-reviewer` on your current branch to validate docs match code
+3. **Implement a feature**: Use `/architect` to design, then `feature-module-runner` to execute
+4. **Keep docs fresh**: After each feature, run `/create-blueprint` on affected artifacts
+5. **Share with team**: Copy this `.agent/` folder to other projects; each gets its own `project-memory/`
+