nurosys-agents 2.0.0

package/.agent/backend/skills/brainstorm/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: brainstorm
+description: Explore 3-5 distinct approaches to a problem, feature, or architectural decision. Outputs structured options with tradeoffs and a recommendation. No code, no implementation, no planning artifacts — pure ideation. Use BEFORE `/architect` when the right approach is not yet obvious. Trigger with `/brainstorm <problem statement>`.
+disable-model-invocation: false
+---
+
+# Skill: brainstorm
+
+The thinking-out-loud skill. You produce **3-5 distinct approaches** to a problem, evaluate each honestly, and recommend one with the key tradeoff named.
+
+This skill **never writes code**, **never writes planning artifacts**, **never updates project-memory**. Its only output is a single structured response in the chat.
+
+Use it before `/architect` when the user hasn't yet decided _how_ to solve something. Use `/architect` after the user picks an approach.
+
+---
+
+## Phase 1 — Frame the problem
+
+Restate the problem in **one paragraph**. Capture:
+- What the user wants to achieve (the goal, not the solution)
+- The constraints they've stated explicitly
+- The implicit constraints you can infer from project-memory (only if relevant — read `constitution.md` only if the user's problem touches a constitutional concern)
+
+If the problem statement is too vague to generate distinct approaches, ask **exactly one** clarifying question and stop. Do not generate options on a misframed problem.
+
+---
+
+## Phase 2 — Light context gathering (optional, ≤3 Serena calls)
+
+Only if the problem requires knowing what currently exists in the codebase. Examples:
+- "Should we add rate limiting?" → check if any rate-limiting exists today (`find_symbol` for likely names)
+- "How should we structure feature X?" → look at how similar features are structured (`get_symbols_overview` on 1-2 sibling feature dirs)
+
+If the problem is purely conceptual ("JWT vs session cookies for our use case"), skip this phase entirely.
+
+**Hard cap: 3 Serena calls.** Brainstorming is cheap reasoning, not deep research.
+
+---
+
+## Phase 3 — Generate 3-5 distinct approaches
+
+Each approach must be **genuinely different in mechanism**, not just a parameter tweak of the same idea.
+
+Examples of distinct approaches:
+- For rate limiting: (a) Redis-backed token bucket middleware, (b) Postgres-row-based counter with cron eviction, (c) external service (Cloudflare/upstash), (d) per-handler decorator-based throttle.
+
+Examples of NOT distinct (these are variants of one approach):
+- (a) Redis with 60s window, (b) Redis with 5min window, (c) Redis with sliding window.
+
+If you can only come up with 2 distinct approaches, output 2. Don't pad to hit 3.
+
+---
+
+## Phase 4 — Evaluate each approach
+
+For each option, produce a compact block. **Use this exact structure** so the user can scan them in parallel:
+
+```
+### Option N: <short name>
+
+**Mechanism**: <one sentence — how it actually works>
+**Pros**: <2-4 bullets, concrete>
+**Cons**: <2-4 bullets, concrete>
+**Complexity**: <Low | Medium | High> — <one phrase justifying>
+**Reversibility**: <Easy | Moderate | Hard> — <one phrase justifying>
+**New dependencies**: <list, or "none">
+```
+
+Be honest about cons. If an option has a serious flaw, name it. The user can't make a good decision from sanitized comparisons.
+
+---
+
+## Phase 5 — Recommend
+
+End with a single **Recommendation** block:
+
+```
+### Recommendation: Option N
+
+**Why**: <one paragraph, the core reason this fits the user's constraints best>
+**Key tradeoff to accept**: <one sentence — the specific downside the user is signing up for>
+**Next step**: <one of: "Run /architect <chosen approach>" | "Run /quick-execute <task>" if trivial | "Run /create-blueprint <artifact>" if project-memory needs updating first>
+```
+
+If you genuinely cannot pick between two options because they trade off along axes only the user can weigh (e.g. "performance vs ops burden"), say so explicitly and present the choice to the user. Do not fake confidence.
+
+---
+
+## Do not
+
+- Write code (not even snippets — descriptions only)
+- Create files anywhere (`documentation/`, `project-memory/`, `src/`)
+- Use any tool other than read-only Serena/Read (≤3 calls)
+- Pad to N options when only K are genuinely distinct
+- Recommend "it depends" without naming the axes
+- Re-run brainstorm after the user picks — hand off to `/architect` or `/quick-execute`
+
+---
+
+## Example invocation flow
+
+```
+User: /brainstorm we need to add audit logging to all admin actions
+
+You: [Phase 1] Frame: User wants every admin-permission action recorded with actor, target, action type, timestamp. Constraint (from constitution): no PII in logs.
+
+[Phase 2] Skip — purely architectural.
+
+[Phase 3-4] Three options:
+
+### Option 1: Decorator-based audit hook
+**Mechanism**: A @Audit() decorator on controller methods writes to an audit_log table after success.
+**Pros**: ...
+**Cons**: ...
+...
+
+### Option 2: Middleware/interceptor capturing all authed requests
+...
+
+### Option 3: DB-trigger-based row-change capture
+...
+
+### Recommendation: Option 1
+**Why**: ...
+**Key tradeoff to accept**: Devs must remember to add @Audit() — no enforcement at compile time.
+**Next step**: Run /architect "audit logging via @Audit() decorator"
+```

package/.agent/backend/skills/code-reviewer/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: code-reviewer
+description: Full-stack code review for backend changes on the current branch. Reads all project-memory docs, audits changed files against the constitution/quality-playbook/auth-model/architecture/models, and writes a structured REVIEW_REPORT to documentation/reports/ (or the active feature folder). Trigger on any "review my changes", "review this branch", "do a code review", or "review <feature>" request.
+---
+
+# Skill: code-reviewer
+
+Use this skill to perform a thorough, standards-aligned code review of all uncommitted or branch-level changes. The output is a structured review report written to the project's `documentation/reports/` directory (or the active feature folder when one is clearly identified).
+
+---
+
+## When to trigger
+
+- User says "review my changes", "do a code review", "review this branch", or similar.
+- User asks for a review of a specific feature or module before merging.
+- Used automatically at the end of a feature-module implementation workflow.
+
+---
+
+## Phase 1 — Understand the change surface
+
+### 1.1 Identify changed files
+
+Run the following to understand what is in scope:
+
+```bash
+git status
+git diff --name-only HEAD
+git diff --name-only --cached
+```
+
+For a branch comparison against main:
+
+```bash
+git diff --name-only main...HEAD
+```
+
+Collect:
+- All modified, added, and deleted files.
+- The active branch name (to infer feature name and milestone if present).
+- Whether changes are staged, unstaged, or committed ahead of main.
+
+### 1.2 Infer feature and milestone
+
+Extract from the branch name or the changed file paths:
+- **Feature name**: the slug after `feature/`, `feat/`, or derived from the dominant changed folder under `src/apis/` (e.g. `influencer-discovery`).
+- **Milestone**: if module files exist under `documentation/features/<feature>/`, identify the highest module number being reviewed (e.g. `M3`). Otherwise use `M0` or omit.
+
+### 1.3 Use Serena symbolic tools first
+
+Before reading any file end-to-end, use Serena's symbolic tools for efficient structural analysis. **Always prefer symbol-level navigation over full-file reads.**
+
+| Need | Serena tool |
+|---|---|
+| List symbols (classes, functions, methods) in a changed file | `get_symbols_overview(relative_path="...")` |
+| Read a specific symbol's body | `find_symbol(name_path="ClassName/methodName", include_body=true)` |
+| Find all callers of a changed function (blast radius) | `find_referencing_symbols(name_path="...", relative_path="...")` |
+| Locate a class/service by name | `find_symbol(name_path="...", substring_matching=true)` |
+| Read prior session notes for this project | `list_memories` then `read_memory` (only if names look relevant) |
+
+For each changed file:
+1. `get_symbols_overview` first — see what symbols exist
+2. For changed symbols, `find_symbol` with `include_body=true` to read just that symbol
+3. For risky changes (mutations, query helpers, auth surfaces), `find_referencing_symbols` to see callers
+4. To verify test coverage, search for a test file alongside the source: `find_symbol(name_path="<TestedSymbol>", substring_matching=true)` and filter by paths matching the project's test glob (e.g. `*.spec.ts`, `*.test.ts` — check `project-memory/repo-map.md` for the project's convention)
+
+Fall back to raw `Read` only when Serena can't locate what you need (e.g. config files, migrations, non-code assets).
+
+**Token efficiency**: target ≤8 Serena calls for the full structural analysis phase. If you find yourself making more, you're probably reviewing too broadly — narrow scope or escalate to a targeted `Read` of one file.
+
+---
+
+## Phase 2 — Load project-memory context
+
+Read all of the following files in full before reviewing any code. These define the non-negotiable constraints for this codebase.
+
+| File | Purpose |
+|------|---------|
+| `project-memory/constitution.md` | Non-negotiable rules: structure, security, validation, auth, DI, SQL, error handling |
+| `project-memory/quality-playbook.md` | High-signal check patterns with symptoms, root causes, and preferred fixes |
+| `project-memory/auth-model.md` | JWT flow, guard chain, RBAC entities, tenant/resource scoping |
+| `project-memory/architecture.md` | System-level architecture decisions and module topology |
+| `project-memory/models.md` | Domain model inventory: Sequelize entities, associations, field contracts |
+| `project-memory/repo-map.md` | Module layout, naming conventions, reusable component registry |
+| `project-memory/core-memory.md` | Historical implementation decisions and completed module record |
+| `project-memory/README.md` | Index of all project-memory docs |
+
+If a file does not exist, skip it and note the omission in the review.
+
+---
+
+## Phase 3 — Review the changed code
+
+For each changed file, perform the following checks. Record every finding, tagged by severity.
+
+### 3.1 Structural alignment (Constitution §Project structure, repo-map.md §Module layout)
+
+- [ ] New feature modules follow the directory structure and naming convention defined in `project-memory/repo-map.md`.
+- [ ] All required files for this project type are present (see repo-map for the checklist: e.g., DB-backed features might need `.model.ts`, `.service.ts`, `.dto.ts`, etc.).
+- [ ] New models/entities are registered per `project-memory/repo-map.md` (e.g., in a models registry file).
+- [ ] Feature module is wired into the module tree per repo-map (e.g., imported in a root APIs module or feature module).
+- [ ] No new file duplicates functionality already documented in `project-memory/repo-map.md`.
+
+### 3.2 Security and auth (Constitution, quality-playbook)
+
+- [ ] Every endpoint has an explicit auth decision: protected (requires auth/permission) or intentionally public.
+- [ ] Protected endpoints use your project's auth guard/middleware (see `project-memory/auth-model.md`).
+- [ ] Permission/authorization checks happen both at endpoint level and service level where applicable.
+- [ ] Service/query layer enforces ownership/tenant scoping using authenticated context, never client-supplied IDs.
+- [ ] Identity and tenant context come from authenticated request context, never from request body/query.
+- [ ] No secrets or config values hardcoded in code; use your project's config service/mechanism.
+
+### 3.3 Input validation (Constitution, quality-playbook)
+
+- [ ] All endpoints validate inputs (body, query, path params) using your project's validation mechanism (e.g., DTOs, validation pipes, decorators).
+- [ ] No raw request data passed to services/repositories/queries; always validate at the boundary.
+- [ ] Unknown/extra fields are rejected for auth-sensitive and data-sensitive endpoints (explicit allowlist or default deny).
+
+### 3.4 Dependency injection and module wiring (Constitution, quality-playbook)
+
+- [ ] DI tokens/identifiers are defined consistently and reused across the module.
+- [ ] No new circular dependencies; if DI needs bidirectional wiring, it's explicitly documented.
+- [ ] Module/package imports and exports are correctly wired for all dependencies.
+- [ ] Controllers/handlers are thin; business logic lives in services, not at the boundary.
+
+### 3.5 Error handling (Constitution)
+
+- [ ] Client errors (validation, auth, resource not found) use appropriate status codes (4xx), not 500.
+- [ ] Errors are not silently swallowed; all error paths are logged or explicitly documented.
+- [ ] Error responses follow your project's consistent envelope shape (see `project-memory/constitution.md`).
+
+### 3.6 SQL and query safety (Constitution §9–11)
+
+- [ ] All user-influenced values are parameterized (use your ORM/query builder's parameterization mechanism, never string interpolation).
+- [ ] No string concatenation of request input into SQL templates.
+- [ ] Raw queries (if used) employ parameterization consistently with your project's query library (see `project-memory/repo-map.md` for patterns).
+- [ ] Row-level security applied via server-side tenant/ownership predicates, never from client-supplied IDs.
+
+### 3.7 Logging and PII (Constitution)
+
+- [ ] No secrets, tokens, passwords, credentials, or sensitive user data logged.
+- [ ] No full request/response bodies logged for auth-sensitive or PII-containing endpoints.
+- [ ] Logged context is actionable: route identifier, request/trace ID, function/service, error type/message.
+
+### 3.8 Dependencies (Constitution)
+
+- [ ] No new external dependency added without explicit justification (why not use existing libs?).
+- [ ] Prefer reusing your project's existing libraries and frameworks over adding new ones.
+
+### 3.9 Caching (Constitution)
+
+- [ ] Cache keys derived from canonicalized inputs using your project's cache key strategy.
+- [ ] Cache bypass/refresh happens only where freshness is explicitly required.
+- [ ] No accidental changes to cache key derivation or TTL semantics that would break stale invalidations.
+
+### 3.10 Model and domain alignment (project-memory/models.md)
+
+- [ ] New data models follow your project's ORM conventions and naming rules (see repo-map and models doc).
+- [ ] Table/entity metadata is explicit (table names, timestamps, field-to-column mappings).
+- [ ] Associations (foreign keys, relationships) are correctly defined; no orphaned or unmapped foreign keys.
+- [ ] Field naming is consistent with project conventions (e.g., snake_case in DB, camelCase in code).
+
+### 3.11 Architecture alignment (project-memory/architecture.md)
+
+- [ ] Changes respect the module topology and layers described in your architecture doc.
+- [ ] No new unexpected coupling between modules without documented rationale (see repo-map).
+- [ ] External-service integration (APIs, queues, caches, etc.) follows your project's established patterns.
+
+---
+
+## Phase 4 — Determine the output location
+
+Choose the report location based on context:
+
+| Condition | Output path |
+|-----------|-------------|
+| Active feature with a folder under `documentation/features/<feature>/` | `documentation/features/<feature>/REVIEW_REPORT_<feature>_<milestone>.md` |
+| General / no clearly scoped feature folder | `documentation/reports/REVIEW_REPORT_<feature>_<milestone>.md` |
+| No feature identifiable | `documentation/reports/REVIEW_REPORT_<branch-slug>.md` |
+
+Name the file using:
+- `<feature>` = feature slug in your project's naming convention (e.g., kebab-case).
+- `<milestone>` = module/phase label if applicable (e.g., `M3`), otherwise omit.
+
+---
+
+## Phase 5 — Write the review report
+
+Save the review report to the path determined in Phase 4. Use this template:
+
+```markdown
+# Backend Code Review Report
+
+## Feature
+`<feature-name>` — <short description of the change being reviewed>
+
+## Branch
+`<branch-name>`
+
+## Scope Reviewed
+<Bullet list of changed files/folders reviewed and what each covers>
+
+---
+
+## Findings
+
+### BLOCKER
+<List each blocker finding with:>
+- **File**: `path/to/file.ts` (line N if known)
+- **Issue**: What is wrong.
+- **Rule**: Which constitution / quality-playbook rule is violated.
+- **Fix**: Minimum change needed to resolve.
+
+*(none)* if no blockers.
+
+### HIGH
+<Same format. HIGH = must fix before merge, not necessarily a blocker today.>
+
+*(none)* if none.
+
+### MEDIUM
+<Same format. MEDIUM = should fix in this PR; acceptable to defer with documented rationale.>
+
+*(none)* if none.
+
+### LOW / SUGGESTION
+<Same format. LOW = nice-to-have improvements or style alignment.>
+
+*(none)* if none.
+
+---
+
+## Architecture Alignment
+<1–3 bullet points on how well the changes align with project-memory/architecture.md and repo-map.md. Note any deviations.>
+
+## Auth and Security Summary
+<1–2 sentences confirming auth coverage or identifying remaining gaps.>
+
+## Quality Gate Status
+
+| Gate | Status | Notes |
+|------|--------|-------|
+| TypeScript compile (`npx tsc --noEmit`) | pass / fail / not run | |
+| Lint (`npm run lint`) | pass / fail / not run | |
+| Unit tests | pass / fail / not run | |
+| E2E tests | pass / fail / not run | |
+
+Run the gates that are feasible given the current environment. Report blocked gates and whether they are pre-existing failures unrelated to these changes.
+
+## Recommendation
+
+**APPROVE** / **APPROVE WITH CONDITIONS** / **REQUEST CHANGES**
+
+<1–2 sentences explaining the recommendation and any required follow-up.>
+```
+
+---
+
+## Phase 6 — Output
+
+### 6.1 Standalone mode (default — user-invoked)
+
+After writing the report file, output to the user:
+
+1. The full path of the written report.
+2. A concise inline summary:
+   - Number of blockers, high, medium, low findings.
+   - Overall recommendation (APPROVE / APPROVE WITH CONDITIONS / REQUEST CHANGES).
+   - Any critical finding that must be addressed before merge.
+
+### 6.2 Sub-agent mode (invoked by `/module-runner`)
+
+Detect sub-agent mode from the parent agent's prompt — it will say "mode=subagent" or "sub-agent mode".
+
+In sub-agent mode:
+- **Do NOT write a REVIEW_REPORT file.** All findings go in the JSON return value.
+- Auto-approve internal decisions (no clarifying questions, no waiting for user input).
+- Skip the "Quality Gate Status" section (the runner handles build/test separately).
+- Return a JSON object to the parent:
+
+```json
+{
+  "verdict": "clean" | "fix_required" | "block",
+  "counts": { "blocker": 0, "high": 0, "medium": 0, "low": 0 },
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "BLOCKER" | "HIGH" | "MEDIUM" | "LOW",
+      "category": "structure" | "security" | "validation" | "di" | "errors" | "sql" | "logging" | "deps" | "caching" | "models" | "architecture",
+      "file": "<path:line>",
+      "issue": "<one sentence>",
+      "rule": "<which constitution / quality-playbook rule, or auth-model section>",
+      "fix": "<one sentence>",
+      "required": true | false
+    }
+  ]
+}
+```
+
+`verdict = block` if any BLOCKER. `verdict = fix_required` if any HIGH or MEDIUM with `required=true`. `verdict = clean` otherwise.
+
+The parent (`/module-runner`'s code-fixer step) consumes this JSON and applies fixes for `required=true` findings only.
+
+---
+
+## Quality gates for the review itself
+
+Before finalizing the report, verify:
+
+- [ ] Every finding links to a specific constitution/quality-playbook rule or project-memory doc section.
+- [ ] Every finding names the exact file (and line where possible).
+- [ ] The report does not describe what code does — it states what is wrong and what the fix is.
+- [ ] Auth and validation coverage has been explicitly confirmed or flagged, not assumed.
+- [ ] No findings are added for purely stylistic preferences without a rule citation.
+- [ ] The gate status table reflects actual command output, not assumptions.
+
+---
+
+## Notes
+
+- This skill reads project-memory docs but does NOT modify them. After implementation modules, `core-memory.md` is updated by `/module-runner` (in its Step 7), not this skill.
+- If this review is triggered mid-module (not post-implementation), findings should feed back into the implementation, not the merge decision.
+- For auth-heavy changes, complement this review with `/auth-and-permissions` — either run it manually after, or rely on `/module-runner` which invokes both `/code-reviewer` and `/security-assessment` as part of its per-module pipeline.
+- This skill does NOT do security audits beyond the basics in §3.2. For a dedicated, structured security review, use `/security-assessment`.