nurosys-agents 2.0.0

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

@@ -0,0 +1,155 @@
+---
+name: module-runner
+description: Sequential per-module executor for backend features planned by `/architect`. Runs each module's prompt through a foreground pipeline (build → test → review → fix → security audit → fix → commit → push). Codex variant — runs all phases in a single context (no native sub-agent spawning). Trigger with `/module-runner <feature-folder>`.
+---
+
+# Skill: module-runner (Codex variant)
+
+Codex does not have native in-session sub-agent spawning (no equivalent of Claude Code's Task tool or Cursor's subagents API callable from within an agent run). This variant runs the same per-module pipeline **sequentially in a single context**.
+
+**Limitation acknowledgement:** On long features (10+ modules), this variant will accumulate context as it goes — review/audit phases load diffs and project-memory each iteration. For features with many modules, prefer Claude Code or Cursor where context isolation is native.
+
+The pipeline contract (build → test → review → fix → security → fix → commit → push) is identical; only the execution model differs.
+
+---
+
+## Input
+
+```
+/module-runner <feature-folder>
+```
+
+Where `<feature-folder>` is `documentation/features/<feature_name>/`.
+
+---
+
+## Phase 0 — Validate input
+
+1. Folder exists, module files present, sorted by `<N>`
+2. `_MODULE_WISE_PLAN.md` exists
+3. On a non-`main` branch
+4. `project-memory/` intact
+
+Confirm with the user before starting. Specifically warn:
+> "Codex variant: all phases run in this single conversation. For features with 10+ modules, context rot is possible. Continue?"
+
+---
+
+## Per-module pipeline
+
+For each module file in order:
+
+### Step 1 — Implement
+
+In this same conversation:
+
+1. Read the full module spec: `documentation/features/<feature_name>/<feature>_MODULE_<N>_<MODULE_NAME>.md`
+2. Implement every file in the New Files / Modified Files tables.
+3. Honor constitution rules and auth approach inlined in §1.
+4. Use Serena for symbol-level edits, raw Write for new files.
+5. No placeholder code. No skipped validation/auth/error handling.
+
+Track files changed in working memory (you'll need them for commit message in Step 8).
+
+### Step 2 — Build + Test
+
+```bash
+npm run build
+npm test
+```
+
+If pass → Step 3. If fail:
+- Inspect failures.
+- Fix.
+- Re-run.
+- Max 2 fix iterations. On 3rd failure, **STOP**.
+
+### Step 3 — Code review
+
+Invoke the `/code-reviewer` skill (foreground, same context). Capture findings.
+
+Verdict:
+- `clean` → Step 5
+- `fix_required` → Step 4
+- `block` → **STOP**
+
+### Step 4 — Apply code-review fixes
+
+Apply BLOCKER, HIGH, and required-MED findings from the review. Skip LOW.
+
+Re-run `npm run build && npm test`. If pass → Step 5. If fail → Step 2 retry logic (max 2 total).
+
+### Step 5 — Security audit
+
+Invoke the `/security-assessment` skill, scope = diff. Capture findings.
+
+Verdict:
+- `clean` → Step 7
+- `fix_required` → Step 6
+- `block` → **STOP**
+
+### Step 6 — Apply security fixes
+
+Apply CRITICAL and HIGH findings. Skip MEDIUM/LOW unless tagged `must_fix`.
+
+Re-run build/test. If pass → Step 7. If fail → **STOP** (no auto-retry).
+
+### Step 7 — Update project-memory
+
+1. Append to `project-memory/core-memory.md`:
+   > `<feature_name>: Module <N> completed (<one-line>); next: Module <N+1>.`
+2. Update `project-memory/repo-map.md` if new modules/routes added.
+3. Create/update `MODULE.md` in the module's source directory from `.agent/templates/MODULE.md`.
+
+### Step 8 — Commit + push
+
+```bash
+git add .
+git commit -m "feat(MODULE_<N>): <one-line description>"
+git push origin HEAD
+```
+
+If push fails, **STOP**.
+
+### Step 9 — Context-rot mitigation (Codex-specific)
+
+Before moving to the next module:
+
+- Discard any large intermediate artifacts from memory (review reports, security reports) — they're already saved as files if needed.
+- Re-summarize for yourself in one short paragraph: "Module <N> done. Files: [count]. Next: Module <N+1> covers [one-line]."
+
+This is the best Codex can do without true context isolation. It does not fully solve context rot but reduces it.
+
+### Step 10 — Next module
+
+Return to Step 1.
+
+---
+
+## After all modules
+
+Print final summary. Do not open a PR.
+
+---
+
+## Failure modes
+
+Same STOP conditions as the other variants:
+- Build/test fail after 2 fixer iterations
+- Review or security verdict = `block`
+- Security fixer build/test failure
+- `git push` failure
+
+Resume: re-run `/module-runner <feature-folder>`. Skip modules already marked completed in `core-memory.md`.
+
+---
+
+## Do not
+
+- Skip build/test between phases
+- Auto-retry beyond specified limits
+- Squash commits
+- Push to `main` / `master`
+- Open a PR
+- Bypass the review or security audit phases
+- Continue past 10 modules without warning the user about context rot

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

@@ -0,0 +1,212 @@
+---
+name: module-runner
+description: Autonomous per-module executor for backend features planned by `/architect`. Sequentially runs each module's prompt through a subagent pipeline (build → test → review → fix → security audit → fix → commit → push), keeping the main agent's context clean. Trigger with `/module-runner <feature-folder>`. Cursor variant — uses Cursor subagents (https://cursor.com/docs/subagents) to spawn independent-context delegates.
+disable-model-invocation: false
+---
+
+# Skill: module-runner (Cursor 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 Cursor subagent (fresh context per https://cursor.com/docs/subagents) and acts on the structured result.
+
+The pipeline is identical to the Claude Code variant; only the sub-agent invocation syntax differs.
+
+---
+
+## Required Cursor subagents
+
+This skill assumes the following Cursor subagents are configured (created during `npm exec nurosys-agent-setup`):
+
+| Subagent name | Purpose | Maps to |
+|---|---|---|
+| `/implementer` | Implements a single module per its prompt file | Step 1 |
+| `/code-reviewer` | Reviews a diff and returns findings JSON | Step 3 |
+| `/code-fixer` | Applies code-review findings to the diff | Step 4 |
+| `/security-auditor` | Audits a diff for security issues | Step 5 |
+| `/security-fixer` | Applies CRITICAL/HIGH security findings | Step 6 |
+| `/build-test-fixer` | Fixes build/test failures | Step 2 retry |
+
+If any of these subagents are missing in the Cursor workspace, **STOP** at Phase 0 and tell the user:
+> "This workspace is missing one or more required Cursor subagents: [list]. Run `npm exec nurosys-agent-setup` to install them."
+
+These subagents are thin wrappers — each is a Cursor subagent that delegates to the same SKILL.md files used by Claude Code (`/code-reviewer`, `/security-assessment`, `/auth-and-permissions`). The subagent definition lives in `.cursor/subagents/<name>.md` (created by `setup.js`).
+
+---
+
+## Input
+
+The user invokes:
+```
+/module-runner <feature-folder>
+```
+
+Where `<feature-folder>` is `documentation/features/<feature_name>/`, containing:
+- `<feature>_MODULE_WISE_PLAN.md`
+- `<feature>_MODULE_<N>_<MODULE_NAME>.md` per module
+
+---
+
+## Phase 0 — Validate input
+
+Same as Claude Code variant:
+1. Folder exists, module files present, sorted by `<N>`
+2. `_MODULE_WISE_PLAN.md` exists
+3. On a non-`main` branch
+4. `project-memory/` intact
+5. All required Cursor subagents are configured (see table above)
+
+Confirm with user before starting.
+
+---
+
+## Per-module pipeline
+
+For each module file in order, run this pipeline. Each numbered step delegates to a Cursor subagent (independent context) **unless marked [Main]**.
+
+### Step 1 — Implement
+
+Delegate to `/implementer`:
+
+> /implementer module=<N> feature=<feature_name>
+>
+> Read the full spec from: `documentation/features/<feature_name>/<feature>_MODULE_<N>_<MODULE_NAME>.md`.
+>
+> Execution rules:
+> - No placeholder code. Implement every file in the New Files / Modified Files tables.
+> - Honor constitution rules and auth approach inlined in the prompt's §1.
+> - Use Serena for symbol-level edits; raw write for new files.
+> - When done, return JSON: `{ "files_changed": [...], "summary": "<one paragraph>", "blockers": [] }`.
+> - Do NOT run tests, do NOT commit.
+
+Wait for completion (foreground). If `blockers` is non-empty, **STOP** and surface to user.
+
+### Step 2 — Build + Test [Main]
+
+```bash
+npm run build
+npm test
+```
+
+If both pass → Step 3.
+
+If either fails, delegate to `/build-test-fixer`:
+> /build-test-fixer module=<N>
+>
+> Failure output below. The recently changed files are: [from Step 1's `files_changed`]. Fix the failures.
+> Return `{ "fixed": true|false, "summary": "..." }`.
+
+Re-run build/test. Max 2 fixer iterations. On 3rd failure, **STOP**.
+
+### Step 3 — Code review
+
+Delegate to `/code-reviewer`:
+
+> /code-reviewer mode=subagent scope=diff module=<N>
+>
+> Return findings JSON per the `/code-reviewer` SKILL.md sub-agent contract.
+
+Parse the verdict:
+- `clean` → Step 5
+- `fix_required` → Step 4
+- `block` → **STOP**
+
+### Step 4 — Code fixer
+
+Delegate to `/code-fixer`:
+
+> /code-fixer module=<N>
+>
+> Findings JSON: [paste from Step 3]
+>
+> Apply BLOCKER, HIGH, and required-MED findings. Skip LOW and optional. Use Serena symbolic edits where possible.
+> Return `{ "fixed": [...], "skipped": [...], "summary": "..." }`.
+
+Re-run build/test. If pass → Step 5. If fail → treat as Step 2 retry (max 2).
+
+### Step 5 — Security audit
+
+Delegate to `/security-auditor`:
+
+> /security-auditor mode=subagent scope=diff module=<N>
+>
+> Return findings JSON per `/security-assessment` SKILL.md sub-agent contract.
+
+Parse the verdict:
+- `clean` → Step 7
+- `fix_required` → Step 6
+- `block` → **STOP**
+
+### Step 6 — Security fixer
+
+Delegate to `/security-fixer`:
+
+> /security-fixer module=<N>
+>
+> Findings JSON: [paste from Step 5]
+>
+> Apply CRITICAL and HIGH. Skip MEDIUM/LOW unless tagged `must_fix`.
+> Return `{ "fixed": [...], "skipped": [...], "summary": "..." }`.
+
+Re-run build/test. If pass → Step 7. If fail → **STOP** (no auto-retry on security fixes).
+
+### Step 7 — Update project-memory [Main]
+
+Same as Claude Code variant:
+1. Append "Module <N> completed" line to `project-memory/core-memory.md`
+2. Update `project-memory/repo-map.md` if new modules/routes added
+3. Create/update `MODULE.md` in the module's source directory
+
+### Step 8 — Commit + push [Main]
+
+```bash
+git add .
+git commit -m "feat(MODULE_<N>): <description>"
+git push origin HEAD
+```
+
+If push fails, **STOP**.
+
+### Step 9 — Next module [Main]
+
+Print status, return to Step 1 for next module.
+
+---
+
+## After all modules
+
+Print final summary (same format as Claude Code variant). Do not open a PR.
+
+---
+
+## Failure modes
+
+Same as Claude Code variant — `STOP` on:
+- Build/test failure after 2 fixer iterations
+- Review or security verdict = `block`
+- Security fixer build/test failure
+- `git push` failure
+- Implementation `blockers` non-empty
+- Any subagent call errors out
+
+Resume by re-running `/module-runner <feature-folder>` — runner skips modules already marked completed in `core-memory.md`.
+
+---
+
+## Cursor subagent invocation notes
+
+- Subagents have **independent context windows** (per https://cursor.com/docs/subagents) — pass everything they need explicitly. No "remember from earlier".
+- Use **foreground mode** for steps where the main agent needs the result to proceed (all steps in this pipeline). Background mode is not needed since the pipeline is strictly sequential.
+- Subagents return their final message to the parent. Request JSON output in the prompt for programmatically-consumed steps (review, security, fixers).
+- Parallelism is not used here — module-runner is sequential by design. (Cursor supports parallel subagent dispatch, but per-module steps depend on each other.)
+
+---
+
+## Do not
+
+Same prohibitions as Claude Code variant:
+- Don't implement/review/audit in the main agent
+- Don't skip build/test verification
+- Don't auto-retry beyond specified limits
+- Don't squash commits
+- Don't push to `main` / `master`
+- Don't open a PR
+- Don't update `core-memory.md` from inside subagents (Main only, Step 7)