nurosys-agents 2.0.0

package/.agent/backend/skills/debug-issue/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: debug-issue
+description: Systematically trace and diagnose backend issues using Serena's symbolic tools. Trigger on "debug", "why is X failing", "trace this error", or any user-reported bug with a stack trace or symptom. Symbol-level, not full-file reads.
+---
+
+# Skill: debug-issue
+
+Trace bugs through the codebase using symbolic navigation. The rule: **follow the stack, don't grep the world**.
+
+## Steps
+
+1. **Capture the symptom precisely**
+   - Error message, stack trace, reproduction steps, expected vs actual behavior.
+   - If the user gave a stack trace, the top frame is your starting symbol.
+
+2. **Locate the suspected entry point**
+   - `find_symbol(name_path="<name from stack trace>", include_body=true)` — read the function/method where the error occurs.
+
+3. **Trace upstream callers**
+   - `find_referencing_symbols(name_path="...", relative_path="...")` — who calls this? The bug may be in a caller passing bad input.
+
+4. **Trace downstream callees**
+   - Read the body and identify what the suspect function calls into. `find_symbol(include_body=true)` on each callee that handles relevant data.
+
+5. **Check recent changes**
+   - `git log -p --follow <suspect-file>` — what changed recently in this file?
+   - If the issue is in a function that was just modified, that's likely the cause.
+
+6. **Read targeted memories**
+   - `list_memories` then `read_memory` if any look relevant (e.g. a prior bug in the same area).
+
+7. **Form a hypothesis and confirm**
+   - State the suspected cause concisely.
+   - Confirm by running the reproduction, adding a temporary log, or reading one more symbol.
+   - Don't write a fix until you can explain the root cause in one sentence.
+
+## Tips
+
+- **Stack trace is the map.** Walk frames from top down, reading symbol bodies along the way. Don't try to understand the whole module first.
+- **Recent changes are the most common cause** of a newly-reported bug. Check `git log` early.
+- **Callers AND callees.** A function can fail because of bad input (caller's fault) or bad logic (its own fault) — check both before concluding.
+- **Avoid speculative grepping.** If you find yourself searching for "this might be related", you've lost the trail — go back to the stack trace.
+
+## Token Efficiency
+
+- Target ≤6 Serena calls for typical debugging tasks: locate entry (1) + read body (1) + callers (1) + key callees (1-2) + verify (1).
+- If you need more, you're either solving the wrong problem or the bug is genuinely cross-cutting — pause and tell the user what you've found.
+
+## Do not
+
+- Fix the bug in this skill. This skill diagnoses; fixes go through `/quick-execute` (small) or `/architect` → `/module-runner` (large).
+- Read whole files when a symbol body suffices.
+- Add debug logging in production code paths without flagging it to the user.

package/.agent/backend/skills/explore-codebase/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: explore-codebase
+description: Navigate and understand a backend codebase efficiently using Serena's symbolic tools. Trigger when the user asks "where is X", "what does Y do", "how is Z wired", or asks for a tour of a module. Symbol-level navigation, not full-file reads.
+---
+
+# Skill: explore-codebase
+
+Use Serena to understand the codebase's structure and find specific code, without reading whole files.
+
+## Steps
+
+1. **Orient with project-memory first**
+   - If `project-memory/repo-map.md` exists, read it — it's the curated map of where things live.
+   - If `project-memory/architecture.md` exists, skim its module-topology section.
+   - This alone often answers "where is X" without any tool calls.
+
+2. **List symbols in candidate files**
+   - `get_symbols_overview(relative_path="<file or dir>")` — shows top-level symbols (classes, functions, modules) without reading their bodies.
+
+3. **Locate by name**
+   - `find_symbol(name_path="<name>", include_body=false)` — find a class/function/method by name. Add `substring_matching=true` for fuzzy match.
+   - Use `name_path="ClassName/methodName"` to scope to a class method.
+
+4. **Read targeted symbol bodies**
+   - `find_symbol(name_path="...", include_body=true)` — read only the symbol you need, not the whole file.
+
+5. **Trace relationships**
+   - `find_referencing_symbols(name_path="...", relative_path="...")` — find all callers of a function/class/method.
+   - This is the right tool for "what depends on this?" and impact analysis.
+
+6. **Check Serena memories**
+   - `list_memories` — see if prior sessions left notes (project_overview, tech_stack, etc.)
+   - `read_memory(memory_name="...")` if any look relevant.
+
+## Tips
+
+- **Project-memory before any tool call.** If `repo-map.md` answers the question, don't query Serena.
+- **Symbols before files.** Default to `get_symbols_overview` over `Read`; default to `find_symbol(include_body=true)` over `Read` on a known file.
+- **Narrow the search.** Always pass `relative_path` when you can — it's much faster than searching the whole repo.
+
+## Token Efficiency
+
+- Target ≤5 Serena calls for any exploration task.
+- If you can't pinpoint what you need in 5 calls, the question is too broad — ask the user to narrow it.
+- Never read a file's whole content just to find one symbol. Use Serena.

package/.agent/backend/skills/quick-execute/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: quick-execute
+description: Fast execution for small backend tasks (bug fixes, tiny features, quick refactors). No planning gate, no approval cycle. Use when the user asks for a short, well-scoped change and there is no need for architectural design. Trigger with `/quick-execute <task>` or natural-language descriptions of a small change.
+disable-model-invocation: false
+---
+
+# Skill: quick-execute
+
+A no-friction execution skill. Skip planning, skip approval gates, ship the change.
+
+**Use it for:** typo fixes, single-function bug fixes, swapping a constant, adding a missing validation, renaming a variable, tightening a log message, small refactors confined to one file.
+
+**Do NOT use it for:** anything touching auth, data models, public API contracts, or more than ~3 files. Those go through `/architect`.
+
+---
+
+## Phase 1 — Understand the task
+
+Read the user's request. If anything is genuinely ambiguous (not a stylistic preference — a load-bearing decision), ask **exactly one** clarifying question. Otherwise proceed.
+
+If the task description references a file or symbol the user already has open, treat that as the starting point — don't re-search for it.
+
+---
+
+## Phase 2 — Locate (Serena-first, ≤3 calls)
+
+Use Serena to pinpoint the code that needs to change.
+
+| Need | Tool |
+|---|---|
+| Find a symbol by name | `find_symbol(name_path="...", include_body=false)` |
+| Inspect a file's structure | `get_symbols_overview(relative_path="...")` |
+| Find callers before changing a function | `find_referencing_symbols(...)` |
+| Read a specific symbol's body | `find_symbol(name_path="...", include_body=true)` |
+
+**Hard cap: 3 Serena calls.** If you can't pinpoint the change in 3 calls, the task is too vague for `/quick-execute` — STOP and recommend `/explore-codebase` or `/architect`.
+
+Project-memory: do **not** read project-memory docs in this skill. If the change is small enough for `/quick-execute`, it's small enough that constitution-level rules apply only if obviously violated.
+
+---
+
+## Phase 3 — Execute
+
+Make the change. Use Serena's symbolic edit tools where the change is symbol-shaped:
+
+- Replacing a whole function/class → `replace_symbol_body`
+- Inserting a new function near an existing one → `insert_after_symbol` / `insert_before_symbol`
+- Small in-line edits inside a larger symbol → `replace_content` (regex/string)
+
+No approval gate. No "here's what I'm about to do" preamble. Just do it.
+
+---
+
+## Phase 4 — Verify
+
+Run the smallest verification that covers the change:
+
+1. **If a test file exists for the affected code** — run `npm test -- <scoped pattern>`. If it passes, done.
+2. **If no test exists but there's a build step** — run `npm run build` (or the project's equivalent from `package.json` scripts).
+3. **If neither applies** — state explicitly: "No automated verification available. Manual check: [one concrete thing the user should try]."
+
+Do not write a new test just to verify a `/quick-execute` change. If the change needs new tests, it's outside this skill's scope.
+
+---
+
+## Phase 5 — Summarize
+
+One paragraph. State:
+
+- What changed (1 sentence, file + symbol)
+- Why (1 sentence, the user's intent restated)
+- How it was verified (1 sentence)
+
+No bulleted lists, no headings, no "what's next" section. Just the paragraph.
+
+---
+
+## Hard Guardrails (STOP and recommend `/architect`)
+
+If during execution you discover any of the following, **stop immediately** and tell the user the task needs `/architect`:
+
+- The change requires editing more than 3 files
+- The change touches `project-memory/auth-model.md` concerns (guards, permissions, tenant scoping)
+- The change touches a database model, migration, or schema
+- The change modifies a public API contract (request/response shape of any endpoint)
+- The change requires installing or upgrading a dependency
+- You realize there are callers/consumers that need coordinated updates
+
+Tell the user: "This is bigger than `/quick-execute` is designed for. Recommend `/architect <task>` to plan it properly." Do not partially execute and leave the system in an inconsistent state.
+
+---
+
+## Do not
+
+- Plan. There is no plan phase in this skill.
+- Ask for approval. The user invoked `/quick-execute` precisely to skip that.
+- Make unrelated improvements ("while I'm here, I also cleaned up..."). Stay in scope.
+- Update `project-memory/core-memory.md`. Small changes don't earn a history entry.
+- Commit or push. Leave that to the user.

package/.agent/backend/skills/refactor-safely/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: refactor-safely
+description: Plan and execute backend refactors with confidence. Uses Serena's symbolic tools for impact analysis (callers, references) and symbolic edits (rename, replace_symbol_body, safe_delete_symbol). Trigger on "rename", "refactor", "extract", "split", "consolidate", "move" requests.
+---
+
+# Skill: refactor-safely
+
+Symbol-level refactors with bounded blast radius. The rule: **map impact first, then edit**.
+
+## Steps
+
+1. **Locate the target symbol**
+   - `find_symbol(name_path="<name>", include_body=true)` — read the current definition.
+
+2. **Map blast radius**
+   - `find_referencing_symbols(name_path="<name>", relative_path="<file>")` — every caller/reference site.
+   - Count and review the result. If >20 references and the user asked for a quick rename, surface the impact: "This affects N call sites — confirm before I proceed."
+
+3. **Preview the plan**
+   - List the files and line ranges that will change.
+   - For renames: state the old → new name and how many sites update.
+   - For signature changes: list each caller and how it needs to adapt.
+   - Get user confirmation if the refactor touches more than a single file.
+
+4. **Apply the edit symbolically**
+   - **Rename**: `rename_symbol(name_path="...", relative_path="...", new_name="...")` — updates definition + all references in one call.
+   - **Replace a symbol's body**: `replace_symbol_body(name_path="...", relative_path="...", body="<new body>")`.
+   - **Insert near a symbol**: `insert_after_symbol` / `insert_before_symbol`.
+   - **Delete a symbol safely**: `safe_delete_symbol(name_path="...", relative_path="...")` — verifies no remaining references first.
+   - **Small in-line edits** (not symbol-shaped): `replace_content(relative_path="...", pattern="...", replacement="...")`.
+
+5. **Verify**
+   - `find_referencing_symbols` again on the new name (rename) or surrounding callers (signature change) — confirm everything was updated.
+   - Run `npm run build` and tests scoped to the affected modules.
+
+## Safety rules
+
+- **Never delete a symbol without `find_referencing_symbols` first.** Use `safe_delete_symbol` which does this check for you.
+- **For cross-module renames** (the symbol is exported and used by other modules), confirm with the user before running `rename_symbol`.
+- **For signature changes** (changing parameters), every caller must be updated. Don't apply a partial change — either update all sites or surface the list and stop.
+- **If `project-memory/architecture.md` documents the refactored area as stable / public API**, surface that to the user before proceeding.
+
+## Token Efficiency
+
+- Target ≤6 Serena calls per refactor: locate (1) + impact (1) + edit (1) + verify (1-3).
+- Don't re-read files after symbolic edits — Serena's edit tools are reliable; if they returned without error, the change is applied.

package/.agent/backend/skills/security-assessment/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: security-assessment
+description: Run a standalone security audit on the backend codebase, a diff, or a specific path. Covers auth, input surface, injection, dependencies, data exposure, crypto/secrets. Outputs a structured SECURITY_ASSESSMENT report with CRITICAL/HIGH/MEDIUM/LOW findings. Trigger with `/security-assessment [scope]` where scope is `diff`, `path:<path>`, or `full`. Also invoked as a sub-agent by `/module-runner` and `/architect`.
+disable-model-invocation: false
+---
+
+# Skill: security-assessment
+
+A focused security audit. Distinct from `/code-reviewer` — that skill checks quality + security together; this one goes deep on security only and produces a security-specific report.
+
+**Two invocation modes:**
+
+1. **Standalone (default)** — Triggered by user. Writes `documentation/reports/SECURITY_ASSESSMENT_<YYYY-MM-DD>.md` and presents a summary to the user.
+2. **Sub-agent mode** — Invoked by `/module-runner` (or `/architect` for a pre-design review). Returns a JSON object with findings and **does not write a file**. Detect this mode when invoked via a parent agent's Task call; the parent's prompt will say "sub-agent mode".
+
+---
+
+## Phase 1 — Determine scope
+
+Parse the invocation:
+
+| Invocation | Scope |
+|---|---|
+| `/security-assessment` (no args) | `diff` — audit changed files only (current branch vs main/master) |
+| `/security-assessment diff` | Same as above, explicit |
+| `/security-assessment path:src/auth` | Audit a specific path |
+| `/security-assessment full` | Audit the entire codebase (slow — confirm before proceeding) |
+
+If `full`, ask the user once: "Full-codebase audit may take significant time and tokens. Proceed?" Wait for confirmation. Skip this confirmation in sub-agent mode.
+
+For `diff` scope: run `git diff --name-only origin/main...HEAD` (fall back to `main` → `master` → `develop` if the prior branch doesn't exist) to get the file list.
+
+---
+
+## Phase 2 — Load auth model
+
+Read `project-memory/auth-model.md`. This is **non-optional** — the audit's auth checks are driven entirely by what's documented there (guard names, RBAC entities, tenant scoping rules, JWT claims, etc.).
+
+If `project-memory/auth-model.md` does not exist, **STOP**. Tell the user: "Cannot run security-assessment without `project-memory/auth-model.md`. Run `/create-blueprint auth-model` first."
+
+Also read these if they exist (skip silently if absent):
+- `project-memory/constitution.md` — for rules on logging/PII/secrets/error handling
+- `project-memory/models.md` — to identify which fields are sensitive (PII, credentials, tokens)
+
+---
+
+## Phase 3 — Map the audit surface with Serena
+
+Use Serena to identify what to check. Target ≤8 calls total.
+
+| Need | Tool |
+|---|---|
+| Find all controllers / route handlers in scope | `find_symbol(name_path="...Controller", substring_matching=true)` |
+| Find all guards/middleware referenced | `find_symbol` on guard class names from `auth-model.md` |
+| For each changed/in-scope file, get its structure | `get_symbols_overview(relative_path="...")` |
+| Find callers of sensitive functions (e.g. raw SQL, exec, JSON.parse) | `find_referencing_symbols` |
+| Locate auth-sensitive entry points | `find_symbol` on patterns like `@Post`, `@Put`, `@Delete` (or framework equivalents from `auth-model.md`) |
+
+**Do not read full files yet.** Build a list of audit targets first, then read only the bodies you need for specific checks in Phase 4.
+
+---
+
+## Phase 4 — Run the audit checks
+
+For each audit category, walk the relevant code paths. Use `find_symbol(..., include_body=true)` or `Read` (targeted, with offset/limit if the file is large) to inspect specific functions.
+
+### 4.1 Auth audit
+
+For every protected endpoint discovered in Phase 3:
+- Is the correct guard/middleware applied? (Compare against `auth-model.md`'s guard chain.)
+- Is the authenticated context extracted via the documented pattern (e.g. `@CurrentUser()`), not from request body/params?
+- Do queries reachable from this endpoint filter by user/tenant where ownership applies?
+- Are there any endpoints in scope that should be protected but aren't?
+
+### 4.2 Input surface audit
+
+For every controller/handler in scope:
+- Is input validated at the boundary (DTO + validation pipe, Zod schema, or equivalent from project conventions)?
+- Are any `req.body.*`, `req.params.*`, or `req.query.*` values flowing into queries, file paths, shell commands, or template rendering without escape?
+- Is user-supplied ID used as a trust boundary? (e.g. `body.userId` controlling whose data is fetched — should come from auth context)
+
+### 4.3 Injection audit
+
+Grep/search the changed code for:
+- Raw SQL strings concatenating variables (`` `SELECT ... ${var}` `` patterns)
+- ORM escape hatches: `Sequelize.literal`, `raw(`, `$queryRaw`, `query(` with string interpolation
+- `child_process.exec`/`execSync`/`spawn` with non-static argument arrays
+- Template rendering with `eval`, `Function`, or unescaped user input
+
+### 4.4 Dependency audit
+
+- If `package.json` changed in scope, examine each added/changed dep — is it reputable, maintained, and minimum-necessary?
+- Recommend running `npm audit --omit=dev` and capture summary if available (best-effort; do not block the audit if it errors).
+- Flag any deps known-vulnerable in security-critical paths (jsonwebtoken pre-9, lodash pre-4.17.21, etc.).
+
+### 4.5 Data exposure audit
+
+- Search for log calls (`console.log`, `logger.info`, etc.) in scope. For each, ask: does it include any field from `project-memory/models.md` that is marked sensitive? Does it include `password`, `token`, `secret`, `apiKey`, raw `email` if PII rules forbid it?
+- For each API response shape in scope, check that sensitive fields are excluded (compare response DTO/serializer against the model's sensitive fields).
+- Check error responses: do they leak stack traces, internal paths, or DB error text to clients?
+
+### 4.6 Crypto & secrets
+
+- Password hashing: bcrypt cost ≥ 10, argon2 with reasonable params, no MD5/SHA1 for passwords.
+- JWT: signing algorithm strong (HS256+ with strong secret, or RS/ES). No `alg: none`. Reasonable expiry.
+- Secrets: no hardcoded API keys, DB URIs, JWT secrets. All from `process.env` or a secret manager.
+- TLS: no `http://` to non-localhost services handling auth/PII; no `rejectUnauthorized: false` in production paths.
+
+---
+
+## Phase 5 — Synthesize findings
+
+For each issue discovered, assign a severity (see `templates/SECURITY_REPORT.md` for definitions):
+
+- **CRITICAL** — Exploitable now: auth bypass, RCE, cross-tenant data access, secret in repo
+- **HIGH** — Real risk with specific conditions: missing guard on sensitive endpoint, injection vector behind auth, known-vulnerable dep in active use
+- **MEDIUM** — Defense-in-depth gap: missing rate limit, verbose errors, weak validation
+- **LOW** — Hygiene: minor PII in logs, missing security header, etc.
+
+Discard speculative findings. If you can't articulate a concrete exploit path or concrete risk, it's not a finding.
+
+---
+
+## Phase 6 — Output
+
+### 6.1 Standalone mode
+
+Write the report to:
+```
+documentation/reports/SECURITY_ASSESSMENT_<YYYY-MM-DD>.md
+```
+
+Use `.agent/templates/SECURITY_REPORT.md` as the template. Fill every section. If a section has no findings, write "No findings." — do not delete the section.
+
+Then in the chat, present a **brief summary**:
+- Total findings by severity (e.g. "0 CRITICAL, 2 HIGH, 3 MEDIUM, 1 LOW")
+- The HIGH/CRITICAL findings in one line each
+- The report path
+
+Do not paste the full report into chat.
+
+### 6.2 Sub-agent mode
+
+Do **not** write a file. Return a JSON object to the parent agent:
+
+```json
+{
+  "verdict": "clean" | "fix_required" | "block",
+  "counts": { "critical": 0, "high": 0, "medium": 0, "low": 0 },
+  "findings": [
+    {
+      "severity": "CRITICAL" | "HIGH" | "MEDIUM" | "LOW",
+      "category": "auth" | "input" | "injection" | "deps" | "data_exposure" | "crypto" | "secrets" | "other",
+      "title": "<short>",
+      "files": ["<path:line>"],
+      "fix": "<one sentence>"
+    }
+  ]
+}
+```
+
+`verdict = block` if any CRITICAL. `verdict = fix_required` if any HIGH. `verdict = clean` otherwise.
+
+The parent agent (typically `/module-runner`'s security-fixer phase) consumes this JSON and decides what to fix automatically.
+
+---
+
+## Do not
+
+- Write code fixes in this skill. This skill only audits and reports. Fixes happen in `/module-runner`'s security-fixer phase (which is a separate sub-agent call) or are surfaced to the user in standalone mode.
+- Update `project-memory/`. Audit findings don't change the source of truth.
+- Speculate. Every finding must be backed by a specific file:line reference.
+- Run `/security-assessment full` without explicit confirmation (in standalone mode).
+- Run more than 8 Serena calls in Phase 3 — escalate to targeted Read instead.

package/.agent/backend/workflows/module-runner.claude.md

@@ -0,0 +1,226 @@
+---
+name: module-runner
+description: Autonomous per-module executor for backend features planned by `/architect`. Sequentially runs each module's prompt through a sub-agent pipeline (build → test → review → fix → security audit → fix → commit → push), keeping the main agent's context clean. Trigger with `/module-runner <feature-folder>`. Claude Code variant — uses the Task tool to spawn independent-context sub-agents.
+disable-model-invocation: false
+---
+
+# Skill: module-runner (Claude Code variant)
+
+The main agent here is the **orchestrator**. It does not implement, review, or audit anything itself. It dispatches each per-module phase to a sub-agent (Task tool, fresh context) and acts on the structured result.
+
+This keeps the main agent's context clean across 10+ module features — every heavy phase (loading project-memory, reading diffs, running review/audit logic) happens in a sub-agent that exits when done.
+
+---
+
+## Input
+
+The user invokes:
+```
+/module-runner <feature-folder>
+```
+
+Where `<feature-folder>` is `documentation/features/<feature_name>/`, containing:
+- `<feature>_MODULE_WISE_PLAN.md` — master plan
+- `<feature>_MODULE_<N>_<MODULE_NAME>.md` — one prompt per module
+
+---
+
+## Phase 0 — Validate input
+
+1. Confirm the folder exists.
+2. List `<feature>_MODULE_<N>_*.md` files. Sort by `<N>`.
+3. Confirm `<feature>_MODULE_WISE_PLAN.md` exists. Read it once to extract feature name and module count.
+4. Check git state: must be on a non-`main`/non-`master` branch. If on `main`, **STOP** and ask the user to create a feature branch first.
+5. Confirm `project-memory/` is intact (constitution, repo-map, auth-model, core-memory all present).
+
+Present a one-line summary to the user:
+> "Found N modules in <feature-folder>. Starting from Module 1. I'll commit + push after each module passes. Confirm to proceed?"
+
+Wait for confirmation.
+
+---
+
+## Per-module pipeline
+
+For each module file in order, run this pipeline. **Each numbered step is a sub-agent invocation** (Task tool, fresh context) **unless marked [Main]**.
+
+### Step 1 — Implement [Task sub-agent]
+
+Spawn a sub-agent with a self-contained prompt:
+
+> Task: Implement Module <N> — <MODULE_NAME> of feature `<feature_name>`.
+>
+> Read the full spec from: `documentation/features/<feature_name>/<feature>_MODULE_<N>_<MODULE_NAME>.md`.
+>
+> The prompt contains all curated context (repo-map excerpts, constitution rules, auth approach, prior decisions) and the full module specification.
+>
+> Execution rules:
+> - No placeholder code. Implement every file in the New Files / Modified Files tables.
+> - Honor the constitution rules inlined in the prompt's §1.
+> - Honor the auth approach inlined in the prompt's §1 (if present).
+> - Use Serena for symbol-level edits where appropriate; raw Write for new files.
+> - When done, return a JSON summary:
+>   `{ "files_changed": [...], "summary": "<one paragraph>", "blockers": [] }`
+>
+> Do NOT run tests, do NOT commit. Implementation only.
+
+Wait for completion. If `blockers` is non-empty, **STOP** and surface to user.
+
+### Step 2 — Build + Test [Main]
+
+In the main agent:
+```bash
+npm run build
+npm test
+```
+
+If both pass → go to Step 3.
+
+If either fails:
+- Spawn a [Task sub-agent] with the failure output:
+  > Task: The Module <N> implementation has build/test failures. Output below. Read the changed files (from the prior implementation summary) and fix the failures. Return `{ "fixed": true|false, "summary": "..." }`.
+- Re-run `npm run build` and `npm test`.
+- Allow **at most 2** fixer iterations. On the 3rd consecutive failure, **STOP** and surface to user.
+
+### Step 3 — Code review [Task sub-agent, sub-agent mode]
+
+Spawn a sub-agent invoking the `/code-reviewer` skill in sub-agent mode:
+
+> Task: Run `/code-reviewer` in sub-agent mode on the diff since the last commit. Module: <N> — <MODULE_NAME>.
+>
+> Auto-approve internal decisions per `/code-reviewer`'s sub-agent contract.
+> Return the structured findings JSON.
+
+Wait for completion. Parse the verdict:
+- `verdict = clean` → go to Step 5
+- `verdict = fix_required` → go to Step 4
+- `verdict = block` → **STOP** and surface findings to user
+
+### Step 4 — Code fixer [Task sub-agent]
+
+Spawn a sub-agent to apply the code-review findings:
+
+> Task: Apply the required-severity findings from this `/code-reviewer` output. JSON below.
+>
+> [paste the findings JSON from Step 3]
+>
+> Rules:
+> - Only fix findings marked BLOCKER, HIGH, or MED-with-`required=true`. Skip LOW and optional.
+> - Use Serena symbolic edits where the fix is symbol-shaped.
+> - Do not change scope beyond the listed findings.
+> - When done, return `{ "fixed": [<finding ids>], "skipped": [<finding ids with reason>], "summary": "..." }`.
+
+After the fixer returns, re-run `npm run build` and `npm test`. If they pass, go to Step 5. If they fail, treat as Step 2 retry (max 2 total fixer iterations before STOP).
+
+### Step 5 — Security audit [Task sub-agent, sub-agent mode]
+
+Spawn a sub-agent invoking the `/security-assessment` skill in sub-agent mode, scope = diff:
+
+> Task: Run `/security-assessment` in sub-agent mode, scope = diff (since last commit). Module: <N> — <MODULE_NAME>.
+> Return the structured findings JSON.
+
+Parse the verdict:
+- `verdict = clean` → go to Step 7
+- `verdict = fix_required` → go to Step 6
+- `verdict = block` → **STOP** and surface findings to user
+
+### Step 6 — Security fixer [Task sub-agent]
+
+Spawn a sub-agent to apply CRITICAL/HIGH security findings:
+
+> Task: Apply CRITICAL and HIGH security findings. JSON below.
+>
+> [paste findings JSON from Step 5]
+>
+> Rules:
+> - Fix every CRITICAL and HIGH. Skip MEDIUM and LOW unless explicitly tagged `must_fix`.
+> - Use Serena symbolic edits where possible.
+> - Return `{ "fixed": [...], "skipped": [...], "summary": "..." }`.
+
+After fixer returns, re-run `npm run build` and `npm test`. If they pass, go to Step 7. If they fail, **STOP** and surface to user (do not auto-retry security fixes).
+
+### Step 7 — Update project-memory [Main]
+
+In the main agent:
+
+1. Append a line to `project-memory/core-memory.md` under Completed modules:
+   > `<feature_name>: Module <N> completed (<one-line description>); next: Module <N+1>.`
+2. If the module added new modules/routes/services, update `project-memory/repo-map.md` accordingly.
+3. Update or create `MODULE.md` in the module's source directory using `.agent/templates/MODULE.md`.
+
+### Step 8 — Commit + push [Main]
+
+In the main agent:
+
+```bash
+git add .
+git commit -m "feat(MODULE_<N>): <one-line description from Step 1's implementation summary>"
+git push origin HEAD
+```
+
+If push fails (e.g. protected branch, missing upstream), surface the error and **STOP** — do not force-push, do not change branches.
+
+### Step 9 — Move to next module [Main]
+
+Print a one-line status:
+> "✅ Module <N>/<total> done. Moving to Module <N+1>."
+
+Return to Step 1 for the next module.
+
+---
+
+## After all modules
+
+Print a final summary:
+
+```
+Feature: <feature_name>
+Modules completed: <N>/<total>
+Total commits: <count>
+Branch: <current-branch>
+
+Per-module:
+- Module 1: <files changed count>, build ✅, review ✅, security ✅
+- Module 2: ...
+```
+
+Do **not** open a PR. Leave that to the user.
+
+---
+
+## Failure modes — when to STOP
+
+The runner **stops and surfaces to the user** (no automatic retry beyond what's specified per phase):
+
+- Build or test fails after 2 fixer iterations
+- `/code-reviewer` returns `verdict = block` (CRITICAL or unrecoverable findings)
+- `/security-assessment` returns `verdict = block` (CRITICAL)
+- Security fixer step fails build/tests on its first re-verification
+- `git push` fails
+- Implementation sub-agent returns non-empty `blockers`
+- Any sub-agent Task tool call errors out
+
+On STOP: clearly state which step failed, which module it was on, paste the relevant error/findings, and **do not** delete uncommitted work. The user resumes by re-running `/module-runner <feature-folder>` after fixing the blocker — the runner skips modules whose source files match the last committed state. (Detect this by checking `project-memory/core-memory.md` for "Module <N> completed" lines.)
+
+---
+
+## Sub-agent invocation contract (Claude Code Task tool)
+
+When spawning a sub-agent, the Task tool call must:
+
+- Use `subagent_type: "general-purpose"` (or a dedicated subagent type if one is configured)
+- Pass a fully self-contained prompt — the sub-agent has zero context from the main session
+- Request a JSON-shaped return value when the result will be consumed programmatically (review, security, fixer)
+- For background-friendly phases (review, security audit), use `run_in_background: true` only if Step ordering allows. The pipeline above is strictly sequential, so default to foreground.
+
+---
+
+## Do not
+
+- Implement, review, or audit in the main agent. Always delegate via Task.
+- Skip the build/test verification between phases.
+- Auto-retry beyond the limits specified.
+- Squash commits — one commit per module.
+- Push to `main` / `master` directly.
+- Open a PR — the user does that after reviewing the full branch.
+- Update `project-memory/core-memory.md` in the implementation/fixer/audit sub-agents. Only the main agent does that, in Step 7.