nurosys-agents 2.0.0

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

@@ -0,0 +1,436 @@
+---
+name: architect
+description: Pure planner. Designs a multi-module implementation plan for a feature, system refactor, or capability change. Reads project-memory, decomposes work into ordered modules, consults read-only sub-agents (auth-and-permissions, security-assessment) for cross-cutting concerns, and writes ONLY planning documents under `documentation/features/<feature>/`. NEVER WRITES CODE. Hands off to `/module-runner` for execution.
+disable-model-invocation: false
+---
+
+# Skill: architect
+
+The planner. Designs a feature's modules, dependencies, contracts, and risks. Outputs documents the user can review before any code is written.
+
+## Hard guarantee — architect NEVER writes code
+
+This is the single most important rule of this skill.
+
+**What architect produces (and ONLY this):**
+- `documentation/features/<feature_name>/<feature>_MODULE_WISE_PLAN.md` — master plan
+- `documentation/features/<feature_name>/<feature>_MODULE_<N>_<MODULE_NAME>.md` — one prompt per module (input for `/module-runner`)
+
+**What architect MUST NOT touch:**
+- Anything under `src/`, `lib/`, `app/`, or any source-code directory
+- Tests, migrations, configs
+- Git (no commits, no branches, no pushes)
+- Dependencies (no `npm install`, no edits to `package.json`)
+- `project-memory/` except optionally appending to `core-memory.md` to note "feature X planned on <date>" — and even that is deferred to `/module-runner`'s wrap-up
+
+If at any point you feel the urge to write code "just to validate the plan", **stop**. The plan is a document; the execution is `/module-runner`'s job.
+
+---
+
+## When to trigger
+
+- User asks to "architect", "plan", "design", "break down", or "decompose" a feature
+- Work spans more than one module or service
+- A `/brainstorm` session produced a chosen approach and the user is ready to plan
+
+---
+
+## Output locations
+
+All outputs go under `documentation/features/<feature_name>/`:
+
+| File | Purpose |
+|------|---------|
+| `<feature>_MODULE_WISE_PLAN.md` | Master plan: modules, dependencies, contracts, rollout |
+| `<feature>_MODULE_<N>_<MODULE_NAME>.md` | Per-module prompt consumed by `/module-runner` |
+
+Naming:
+- `<feature_name>` is `snake_case` (e.g. `sse_streaming`, `audit_logging`)
+- `<N>` is the module number (e.g. `1`, `2`, `3`)
+- `<MODULE_NAME>` is abbreviated `UPPER_SNAKE_CASE` (e.g. `MODEL_LAYER`, `AUTH_GUARD`)
+
+---
+
+## Phase 0 — Prerequisites (HARD STOP)
+
+Confirm `project-memory/` exists. Required:
+
+- `project-memory/constitution.md`
+- `project-memory/repo-map.md`
+- `project-memory/auth-model.md`
+- `project-memory/architecture.md`
+- `project-memory/core-memory.md`
+
+If any are missing, **STOP** and respond:
+
+> ⚠️ `/architect` requires `project-memory/` artifacts to ground the plan. Missing:
+> - [list each missing file]
+>
+> Run `/create-blueprint all` (or `/create-blueprint <artifact>` for individual ones), then re-invoke `/architect <feature>`.
+
+Do not proceed to Phase 1 until every required file exists.
+
+---
+
+## Phase 1 — Research & Discovery (read-only)
+
+### 1.1 Read foundation docs
+
+Read in this order:
+
+| File | What you extract |
+|------|------------------|
+| `project-memory/constitution.md` | Non-negotiable rules the plan must honor |
+| `project-memory/architecture.md` | System layering, module boundaries, data flow |
+| `project-memory/repo-map.md` | Where things live, naming, reusable components |
+| `project-memory/auth-model.md` | Auth/permission model — needed if the feature touches protected resources |
+| `project-memory/core-memory.md` | Prior decisions, completed modules, lessons |
+| `project-memory/models.md` (if present) | Existing entities the feature may touch |
+| `project-memory/quality-playbook.md` (if present) | Patterns/anti-patterns to honor |
+
+### 1.2 Map existing code with Serena (≤8 calls)
+
+Use Serena's symbolic tools, not raw reads:
+
+| Need | Tool |
+|---|---|
+| List symbols in a relevant file | `get_symbols_overview(relative_path="...")` |
+| Find a class, service, or controller by name | `find_symbol(name_path="...", include_body=false)` |
+| Read a specific symbol body | `find_symbol(name_path="...", include_body=true)` |
+| Trace who calls a function | `find_referencing_symbols(...)` |
+| Project memories (Serena-stored notes from prior sessions) | `list_memories`, then `read_memory` if useful |
+
+Target: ≤8 calls. Only escalate to full-file `Read` if Serena can't surface what you need.
+
+### 1.3 Capture scope decisions (present to user before continuing)
+
+Write down explicitly:
+
+- **In scope** — what this plan delivers
+- **Out of scope** — what is deferred or handled elsewhere
+- **Assumptions** — anything the design depends on
+
+Show these to the user and ask for confirmation. Adjust before continuing.
+
+---
+
+## Phase 2 — Cross-cutting sub-agent consultations (read-only)
+
+For any module that touches a cross-cutting concern, consult the relevant sub-agent **as a planning input**. These sub-agents do not write code — they return structured advice that goes into the plan.
+
+Run consultations **in parallel** where supported (Claude Code Task / Cursor subagent background mode). Sub-agents only need a short prompt with the proposed module surface.
+
+| Concern | Sub-agent to invoke | What you ask for |
+|---|---|---|
+| New protected endpoints, role/permission changes, tenant scoping | `/auth-and-permissions` (planning_input mode) | Recommended guard, permission key, current-user extractor, ownership scope per endpoint |
+| Sensitive data, new external integrations, anything handling auth/PII/secrets | `/security-assessment` (pre-design review) | Risks specific to the proposed surface; constraints the design should respect |
+
+Sub-agent invocation contract (parent prompt):
+
+> Sub-agent mode. Proposed module surface: [list endpoints, services, entities, data flow]. Return planning_input JSON per your SKILL.md.
+
+Capture each sub-agent's returned JSON. Use it directly in the module specs (Phase 3) — don't paraphrase away the specifics.
+
+If a sub-agent flags a BLOCKER (e.g. no documented auth pattern fits, fundamental security flaw in the proposed approach), **stop and surface it to the user**. Do not silently adjust the plan around it.
+
+---
+
+## Phase 3 — Module Decomposition
+
+### 3.1 Decomposition principles
+
+1. **Single responsibility** — one module does one thing
+2. **Independent deployability** — a module can ship without breaking what's there
+3. **Explicit dependencies** — if Module B needs Module A, state it
+4. **Incremental value** — each module delivers testable value on its own
+5. **Smallest viable unit** — prefer more smaller modules; if a module is estimated >8 hours, split it
+
+### 3.2 Per-module fields
+
+For every module, define:
+
+| Field | Content |
+|---|---|
+| **Goal** | One-sentence purpose |
+| **Depends on** | Prerequisite modules (omit if standalone) |
+| **Estimated effort** | Time range (e.g. "4–6 hours") |
+| **Key deliverables** | Files / services / endpoints created or modified |
+| **New files** | Table of new files + purpose (omit if none) |
+| **Modified files** | Files this module changes (omit if none) |
+| **Architecture** | ASCII diagram or short description of interactions |
+| **Core interfaces / API** | TypeScript types, function signatures, endpoint contracts (text only) |
+| **Auth approach** | From `/auth-and-permissions` sub-agent output for this module (if applicable) |
+| **Security considerations** | From `/security-assessment` sub-agent output for this module (if applicable) |
+| **Implementation notes** | Patterns, edge cases, constraints, things to watch for |
+| **Error handling** | Explicit error scenarios and responses |
+| **How to test** | Concrete verification steps for this module alone |
+
+### 3.3 Architecture diagrams
+
+Use ASCII for any non-trivial module:
+
+```
+┌──────────────┐       ┌──────────────────┐
+│  Controller  │──────▶│  Service          │──────▶ DB / External
+└──────────────┘       └──────────────────┘
+```
+
+---
+
+## Phase 4 — Dependency Ordering
+
+### 4.1 Build the dependency graph
+
+- Map dependencies between modules
+- Identify standalone modules (these ship first)
+- Identify the critical path (longest dependent chain)
+
+### 4.2 Implementation order
+
+Present as a numbered vertical chain:
+
+```
+Module 1 — MODEL_LAYER (standalone)
+    │
+Module 2 — SERVICE_LAYER (depends on M1)
+    │
+Module 3 — API_ENDPOINTS (depends on M2)
+```
+
+### 4.3 Merge points
+
+- Which modules can merge individually (purely additive, backward compatible)?
+- Which must merge together (tightly coupled contract)?
+- Which need a feature flag?
+
+---
+
+## Phase 5 — Write `<feature>_MODULE_WISE_PLAN.md`
+
+Save to `documentation/features/<feature_name>/<feature>_MODULE_WISE_PLAN.md`.
+
+Structure:
+
+```markdown
+# [Feature Name] — Module-Wise Plan
+
+[One-paragraph description of what this plan delivers and why.]
+
+> **Scope decisions (confirmed):**
+> - In scope: ...
+> - Out of scope: ...
+> - Assumptions: ...
+
+---
+
+## Module Overview
+
+| # | Module | Depends On | Effort | Key Deliverables |
+|---|--------|-----------|--------|------------------|
+| 1 | ...    | —         | X–Y hr | ...              |
+| 2 | ...    | M1        | X–Y hr | ...              |
+
+---
+
+## Module 1 — [Name]
+
+**Goal**: ...
+
+### Auth approach (from /auth-and-permissions consultation)
+[Inline the relevant snippet from sub-agent JSON, if applicable]
+
+### Security considerations (from /security-assessment consultation)
+[Inline the relevant snippet, if applicable]
+
+### New Files
+| File | Purpose |
+|------|---------|
+| ... | ... |
+
+### Architecture
+[ASCII diagram]
+
+### Core interfaces / API
+[Text only — TypeScript signatures, endpoint contracts]
+
+### Implementation notes
+- ...
+
+### Error handling
+- ...
+
+### How to test
+- ...
+
+---
+
+## Module 2 — [Name]
+...
+
+---
+
+## Implementation Order
+
+[Dependency chain diagram]
+
+**Recommended merge points:**
+- ...
+
+---
+
+## Environment / Config Additions
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| ...      | ...     | ...     |
+
+---
+
+## Files Inventory
+
+| File | Action | Module |
+|------|--------|--------|
+| ...  | Create/Modify | M1 |
+```
+
+---
+
+## Phase 6 — Approval Gate (HARD STOP)
+
+After writing `_MODULE_WISE_PLAN.md`, **STOP**. Do not proceed to Phase 7. Do not generate module prompt files yet.
+
+Present the plan to the user:
+- Path to the plan file
+- One-paragraph summary of the modules
+- The implementation order
+- Any sub-agent findings that materially shaped the plan
+
+Wait for explicit user approval. If the user requests changes, update the plan and re-present.
+
+---
+
+## Phase 7 — Generate Per-Module Prompts
+
+Only after explicit user approval.
+
+### 7.1 Output files
+
+For each module `N`:
+```
+documentation/features/<feature_name>/<feature>_MODULE_<N>_<MODULE_NAME>.md
+```
+
+### 7.2 Per-module prompt format
+
+Each file must follow this template:
+
+````markdown
+You are implementing **Module <N> — <Module Name>** of the `<feature_name>` feature.
+The master plan was reviewed and approved. Proceed autonomously through all phases.
+
+Execute under the `/module-runner` skill — it owns the per-module lifecycle (implement → test → review → fix → security audit → fix → commit → push).
+
+---
+
+## 1. Relevant context (curated for this module only)
+
+### Repo context
+<Curated repo-map excerpt — see §7.3 curation rules>
+
+### Constitution rules (those this module can violate)
+<Inline only the constitution sections relevant to this module>
+
+### Auth approach (from architect's /auth-and-permissions consultation)
+<Inline the endpoint-level auth plan, if applicable>
+
+### Prior decisions (from core-memory)
+<Inline only the entries this module builds on or must not contradict>
+
+---
+
+## 2. Module specification
+
+<Full module section copied verbatim from the approved _MODULE_WISE_PLAN.md.
+Omit empty subsections.>
+
+---
+
+## 3. Execution rules
+
+- No placeholder code. No skipping validation, authz, or error handling.
+- Preserve module boundaries documented in `project-memory/repo-map.md`.
+- Use the project's documented config mechanism for env vars — never hardcode.
+- After implementation, the `/module-runner` pipeline will run build + tests + code review + security audit. Do not bypass these.
+- After all phases complete, `/module-runner` updates `project-memory/core-memory.md` for this module — you do not.
+````
+
+### 7.3 Content curation rules
+
+1. **Module specification** — copy the full module section from `_MODULE_WISE_PLAN.md` verbatim into §2. Omit empty subsections (no "New Files" if none, no "Depends on" if standalone).
+
+2. **Curated repo-map context** — under §1 "Repo context", include only the sections from `repo-map.md` this module needs:
+
+   | Always | Conditional |
+   |---|---|
+   | Naming conventions | Modules this one touches or depends on |
+   | Key entry points | Reusable components this module will use |
+   |  | Core/shared service entries if this module uses auth/config/persistence/messaging |
+   |  | Models registry entries if this module creates or references entities |
+
+   Target: ~30–50 lines of focused context. Omit the rest.
+
+3. **Curated constitution rules** — under §1 "Constitution rules", inline only sections this module could actually violate:
+
+   | Module touches | Include these sections |
+   |---|---|
+   | New endpoints | Auth/guard rules, input validation, error envelope |
+   | DB models/queries | SQL safety, parameterization, row-level scoping |
+   | External services | Outbound timeout/retry rules |
+   | Config/secrets | Config rules, no `process.env` in feature logic |
+   | Any new code | DI/module wiring rules |
+
+   Never paste the full constitution.
+
+4. **Auth approach inline** — if the architect's `/auth-and-permissions` consultation produced a planning JSON for this module, inline its endpoint-by-endpoint guidance directly. Don't summarize away the specifics.
+
+5. **Core-memory inline** — only entries this module depends on or must not contradict. Unrelated history is noise.
+
+6. **Replace placeholders** — `<feature_name>`, `<N>`, `<MODULE_NAME>` with actual values.
+
+7. **No code** — the prompt file describes what to build, not how to write it.
+
+### 7.4 Confirmation
+
+After generating all module prompt files, present:
+- List of all generated file paths
+- The implementation order
+- The hand-off command: `/module-runner documentation/features/<feature_name>/`
+
+---
+
+## Quality gates
+
+Before finalizing the plan, verify:
+
+- [ ] All modules have a clear Goal
+- [ ] Dependencies between modules are explicit and acyclic
+- [ ] Each module has a concrete How-to-test section
+- [ ] No module violates `project-memory/constitution.md`
+- [ ] Modules with auth surfaces have an inlined auth approach from sub-agent consultation
+- [ ] Modules with sensitive data have inlined security considerations
+- [ ] Implementation order respects the dependency graph
+- [ ] Files Inventory covers every file change
+- [ ] Scope decisions are documented and user-confirmed
+
+---
+
+## Hand-off to `/module-runner`
+
+The plan is now ready for execution. Architect's work is done.
+
+The user runs:
+```
+/module-runner documentation/features/<feature_name>/
+```
+
+`/module-runner` reads each module prompt in order, spawns sub-agents for build/review/security/fix, and commits each module before moving on. Architect does not participate in execution.

package/.agent/backend/skills/auth-and-permissions/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: auth-and-permissions
+description: Backend auth & authorization guardrails. Audits endpoints, guards, request-context propagation, and ownership/tenant scoping against the project's documented auth model. Generic across NestJS/Express/Fastify/Koa — driven entirely by `project-memory/auth-model.md`. Trigger on changes touching auth, login, jwt, session, middleware, permission, role, tenant, guard. Also invoked as a sub-agent by `/architect` and `/module-runner`.
+disable-model-invocation: false
+---
+
+# Skill: auth-and-permissions
+
+Audits a change for auth correctness. This skill is **fully generic** — it owns the *checks*, but the project's specific guard names, permission decorators, context-extraction patterns, and ownership rules come from `project-memory/auth-model.md`.
+
+**Two invocation modes:**
+
+1. **Manual / standalone** — Triggered by user or by `/code-reviewer` for a PR-level auth review. Produces a structured checklist note in chat (and optionally appended to a review report).
+2. **Sub-agent mode** — Invoked by `/architect` (during planning, to draft the auth approach for a planned module) or `/module-runner` (during per-module review). Returns a JSON object. Detect this mode from the parent's prompt — it will say "sub-agent mode".
+
+---
+
+## Phase 1 — Load the auth model
+
+Read `project-memory/auth-model.md`. From it, extract:
+
+| Concept (generic) | What you learn from auth-model.md (project-specific) |
+|---|---|
+| **Auth guard / middleware** | The class/function name(s) that enforce authentication |
+| **Permission decorator / metadata** | How permission requirements are declared on a handler |
+| **Current-user extractor** | The decorator/helper that yields authenticated identity inside a handler |
+| **Tenant / ownership key** | Which JWT claim or context field carries tenant/org/user identity for filtering |
+| **Public-endpoint convention** | How endpoints are explicitly marked public (e.g. `@Public()`, route exclusion list) |
+| **Token issuance flow** | Where tokens are minted, what algorithm, expiry, refresh strategy |
+
+If `project-memory/auth-model.md` does not exist, **STOP**. Tell the user: "Cannot audit auth without `project-memory/auth-model.md`. Run `/create-blueprint auth-model` first."
+
+Also read (if present, skip silently if absent):
+- `project-memory/constitution.md` §Security / §Validation / §Auth invariants — non-negotiable rules
+- `project-memory/repo-map.md` — file locations for auth implementation
+
+---
+
+## Phase 2 — Determine scope
+
+| Invocation | Scope |
+|---|---|
+| User-triggered with no args | Changed files on current branch (`git diff --name-only origin/main...HEAD`) |
+| `/auth-and-permissions path:<path>` | Specific path |
+| `/auth-and-permissions endpoint:<route>` | Single endpoint |
+| Sub-agent (from `/architect`) | The proposed module's planned surface (described in the parent prompt) |
+| Sub-agent (from `/module-runner`) | The current module's diff |
+
+---
+
+## Phase 3 — Identify the audit surface with Serena
+
+Locate the auth-relevant code in scope. Target ≤6 calls.
+
+- For each changed file, `get_symbols_overview` to list controllers/handlers
+- `find_symbol` on the auth guard / permission decorator names from `auth-model.md` — verify they appear where expected
+- `find_referencing_symbols` on the current-user extractor — verify handlers that need identity actually use it
+- If services touch a sensitive entity, `find_referencing_symbols` on the entity's repository/query helpers to trace ownership filtering
+
+---
+
+## Phase 4 — Run the checks (generic, driven by auth-model)
+
+For every endpoint/handler in scope:
+
+### 4.1 Authentication
+- [ ] Endpoint has an explicit auth decision: protected by the documented guard, **or** explicitly marked public via the documented convention. Implicit/missing is a finding.
+
+### 4.2 Authorization (permissions)
+- [ ] If the action is permission-gated (per `auth-model.md`), the documented permission decorator/metadata is present with the correct permission key.
+- [ ] Permission strings/enums match values defined in `auth-model.md` (no ad-hoc strings).
+
+### 4.3 Request-context propagation
+- [ ] Handlers that need user/tenant identity use the documented current-user extractor — never `req.body.userId`, `req.headers['x-user-id']`, or similar untrusted sources.
+- [ ] Context is propagated to services as a typed object, not as raw request fragments.
+
+### 4.4 Ownership / tenant scoping
+- [ ] For every query touching a tenant-scoped or user-owned entity, the query filters by the tenant/ownership key from auth context. Missing scope = blocker for sensitive resources.
+- [ ] Mutations (UPDATE/DELETE) verify ownership before applying — not by trusting an ID from the request body alone.
+
+### 4.5 Input validation at the auth boundary
+- [ ] Auth-sensitive inputs (credentials, tokens, permission grants, role assignments) are validated at the controller boundary with a typed DTO / schema.
+- [ ] Validation rejects unknown fields where the framework supports it (e.g. `forbidNonWhitelisted`).
+
+### 4.6 No business logic in the auth layer; no auth logic in the business layer
+- [ ] Guards/middleware do not perform business decisions (e.g. complex ownership traversal — that belongs in the service).
+- [ ] Services do not re-implement authentication (e.g. re-validating JWTs that the guard already validated).
+
+### 4.7 Token handling
+- [ ] No new ad-hoc token system introduced (use the issuance flow documented in `auth-model.md`).
+- [ ] No hardcoded JWT secrets, no `process.env.JWT_SECRET` access outside the documented auth module.
+- [ ] Token expiry/refresh behavior matches `auth-model.md`.
+
+---
+
+## Phase 5 — Output
+
+### 5.1 Manual / standalone mode
+
+Produce a chat response with this exact structure:
+
+```
+## Auth & Permissions Audit — <feature or scope>
+
+**Scope**: <files / endpoints reviewed>
+**Auth-model reference**: project-memory/auth-model.md (<one-line summary of relevant section>)
+
+### Endpoint inventory
+| Endpoint | Method | Auth decision | Permission | Owner/tenant scope | Verdict |
+|---|---|---|---|---|---|
+| /api/... | POST | <guard> | <permission-key> | by `tenantId` from context | ✅ |
+
+### Findings
+| Severity | Issue | File:line | Fix |
+|---|---|---|---|
+| BLOCKER / HIGH / MED / LOW | ... | ... | ... |
+
+### Verdict
+- **Decision**: ✅ Clear / ⚠️ Fix required / 🛑 Block
+- **Required fixes before merge**: <list, or "none">
+```
+
+`BLOCKER` for missing auth on a sensitive endpoint, missing ownership scoping on a sensitive resource, or hardcoded auth secrets. `HIGH` for missing validation on auth-sensitive input. `MED` for redundancy/layer-bleed issues. `LOW` for stylistic.
+
+### 5.2 Sub-agent mode — when called by `/architect` (planning input)
+
+Return a JSON object describing the **recommended auth approach** for the planned module. No file is written.
+
+```json
+{
+  "mode": "planning_input",
+  "endpoints": [
+    {
+      "route": "<method + path>",
+      "auth": "<guard name from auth-model>",
+      "permission": "<permission key from auth-model, or null>",
+      "current_user_extractor": "<decorator/helper name>",
+      "ownership_scope": "<which entity field filters by which context key>",
+      "validation_dto": "<recommended DTO name>"
+    }
+  ],
+  "notes": "<one short paragraph of any non-obvious considerations>"
+}
+```
+
+### 5.3 Sub-agent mode — when called by `/module-runner` (review)
+
+Return a JSON object with audit findings (same shape as `/security-assessment` sub-agent output, scoped to auth):
+
+```json
+{
+  "verdict": "clean" | "fix_required" | "block",
+  "findings": [
+    { "severity": "BLOCKER|HIGH|MED|LOW", "issue": "...", "file": "<path:line>", "fix": "..." }
+  ]
+}
+```
+
+`verdict = block` for any BLOCKER. `verdict = fix_required` for any HIGH. `verdict = clean` otherwise.
+
+---
+
+## Do not
+
+- Hardcode any framework-specific names (guards, decorators, helpers). If you find yourself writing a literal class name in this skill, stop — the right name lives in `project-memory/auth-model.md`.
+- Recommend installing an alternate auth library. The documented system is the system.
+- Fix code in this skill. Surface findings; fixes happen in `/module-runner` or by the user.
+- Update `project-memory/auth-model.md`. If the model itself is wrong, the user should run `/create-blueprint auth-model` to refresh it.