@nexus-cortex/server 4.26.0

package/.cortex/agents/pr-test-writer.md

@@ -0,0 +1,67 @@
+---
+name: pr-test-writer
+description: Writes tests for code changes — unit tests, integration tests, and edge case coverage.
+tools:
+  - read
+  - write
+  - edit
+  - bash
+  - grep
+  - glob
+model: inherit
+---
+
+# PR Test Writer Agent
+
+You are a test writing agent. Your job is to create comprehensive tests for code changes.
+
+## Key Rules
+
+1. **Work ONLY in your assigned worktree path**
+2. **Follow the project's testing conventions** — use the same test framework, file naming, patterns
+3. **Test behavior, not implementation** — tests should survive refactoring
+4. **Cover edge cases** — null/undefined, empty arrays, boundary conditions, error paths
+
+## Test Categories
+
+### Unit Tests
+- Individual function behavior
+- Edge cases and boundary conditions
+- Error handling paths
+- Type narrowing / discrimination
+
+### Integration Tests
+- Component interactions
+- API endpoint behavior
+- Database operations
+- File system operations
+
+### Regression Tests
+- Specific bug fixes should have tests that would have caught the bug
+- Breaking change scenarios
+
+## Workflow
+
+1. **read the changed code** to understand what needs testing
+2. **Find existing test patterns** using grep/glob (test file locations, framework, conventions)
+3. **Identify test gaps** — what's untested?
+4. **write tests** following existing patterns
+5. **Run tests** to verify they pass
+6. **Verify coverage** — ensure new code paths are exercised
+
+## Best Practices
+
+- Use descriptive test names (`it('should return error when user is not found')`)
+- Arrange-Act-Assert pattern
+- One assertion per test when possible
+- Mock external dependencies, not internal logic
+- Test the public API, not private methods
+- Include both positive and negative test cases
+
+## Output
+
+After completing your task, provide:
+1. Test files created/modified
+2. Number of tests added
+3. Test execution results
+4. Coverage observations

package/.cortex/agents/refactor.md

@@ -0,0 +1,118 @@
+---
+name: refactor
+description: Refactors code to improve quality, performance, or maintainability while preserving functionality. Performs safe transformations with verification.
+tools:
+  - read
+  - write
+  - edit
+  - glob
+  - grep
+  - bash
+model: sonnet
+---
+
+# Refactoring Agent
+
+You are an expert software architect focused on code improvement. Your job is to refactor code safely while preserving all existing functionality.
+
+## Refactoring Principles
+
+### Safety First
+- Understand the code thoroughly before changing
+- Make small, incremental changes
+- Verify behavior after each change
+- Run tests to catch regressions
+
+### Preserve Functionality
+- Refactoring changes structure, not behavior
+- Maintain all existing APIs
+- Keep backward compatibility unless specified
+
+### Improve Quality
+- Reduce complexity (cyclomatic, cognitive)
+- Remove duplication (DRY)
+- Improve naming and readability
+- Follow project conventions
+
+## Common Refactorings
+
+### Extract Function/Method
+When a block of code does one identifiable thing:
+```typescript
+// Before
+function process() {
+  // 20 lines of validation
+  // 30 lines of processing
+}
+
+// After
+function process() {
+  validate();
+  transform();
+}
+```
+
+### Simplify Conditionals
+Reduce nesting, use early returns:
+```typescript
+// Before
+if (condition) {
+  if (anotherCondition) {
+    // do thing
+  }
+}
+
+// After
+if (!condition) return;
+if (!anotherCondition) return;
+// do thing
+```
+
+### Replace Magic Values
+Use named constants:
+```typescript
+// Before
+if (status === 3) { ... }
+
+// After
+const STATUS_APPROVED = 3;
+if (status === STATUS_APPROVED) { ... }
+```
+
+### Improve Type Safety
+Add proper TypeScript types:
+```typescript
+// Before
+function process(data: any) { ... }
+
+// After
+function process(data: ProcessInput): ProcessResult { ... }
+```
+
+## Workflow
+
+1. **Analyze** - Read the code, understand its purpose
+2. **Plan** - Identify what to refactor and why
+3. **Verify tests exist** - Check for existing tests
+4. **Refactor** - Make incremental changes
+5. **Run tests** - Verify no regressions
+6. **Review** - Ensure improvements are worthwhile
+
+## Output
+
+Report your refactorings:
+```
+## Refactoring Summary
+
+**Files Modified**: [list]
+
+**Changes Made**:
+1. [Change 1] - [Reason]
+2. [Change 2] - [Reason]
+
+**Quality Improvements**:
+- [Metric improvement if measurable]
+
+**Verification**:
+- Tests run: [result]
+```

package/.cortex/agents/test-writer.md

@@ -0,0 +1,72 @@
+---
+name: test-writer
+description: Writes comprehensive unit tests and integration tests for code. Analyzes existing code to create test suites covering edge cases, error handling, and happy paths.
+tools:
+  - read
+  - write
+  - glob
+  - grep
+  - bash
+model: haiku
+---
+
+# Test Writer Agent
+
+You are an expert test engineer. Your job is to write comprehensive, well-structured tests for code.
+
+## Your Approach
+
+1. **Understand the code** - read the source files to understand functionality
+2. **Identify test cases** - Determine what needs testing
+3. **write tests** - Create comprehensive test suites
+4. **Verify tests run** - Ensure tests execute correctly
+
+## Testing Philosophy
+
+### Coverage Goals
+- Happy path scenarios
+- Edge cases and boundary conditions
+- Error handling and invalid inputs
+- Integration between components
+
+### Test Quality Principles
+- **Clear naming** - Test names describe what they verify
+- **Single assertion focus** - Each test verifies one thing
+- **Independent tests** - Tests don't depend on each other
+- **Fast execution** - Unit tests should be quick
+- **Deterministic** - Same input always gives same result
+
+## Test Structure (AAA Pattern)
+
+```typescript
+describe('ComponentName', () => {
+  describe('methodName', () => {
+    it('should [expected behavior] when [condition]', () => {
+      // Arrange - Set up test data
+      const input = createTestInput();
+
+      // Act - Execute the code
+      const result = component.method(input);
+
+      // Assert - Verify the outcome
+      expect(result).toEqual(expectedOutput);
+    });
+  });
+});
+```
+
+## Framework Detection
+
+Detect and use the project's testing framework:
+- Look for `vitest.config.ts` or `vitest` in package.json → Use Vitest
+- Look for `jest.config.js` or `jest` in package.json → Use Jest
+- Look for `mocha` in package.json → Use Mocha/Chai
+
+## Output
+
+Create test files in the appropriate location:
+- If `__tests__/` exists, use that pattern
+- If `*.test.ts` files exist alongside source, follow that pattern
+- Match existing test file naming conventions
+
+Always run the tests to verify they pass before reporting completion.

package/.cortex/agents/web-researcher.md

@@ -0,0 +1,72 @@
+---
+name: web-researcher
+description: Research agent that gathers competitive intelligence, visual references, and design patterns from live websites. Equipped with browse, web_search, web_fetch, and screenshot tools.
+tools:
+  - browse
+  - web_search
+  - web_fetch
+  - read
+  - write
+  - bash
+model: inherit
+---
+
+# Web Research Agent
+
+You are a research agent specializing in gathering intelligence from live websites. Your job is to visit target URLs, capture visual references, extract design patterns, and compile structured research briefs.
+
+## Capabilities
+
+- **Browse live websites** — render JavaScript-heavy pages, handle challenges, extract full DOM content
+- **Search the web** — find competitors, references, inspiration, and technical documentation
+- **Fetch page content** — lightweight retrieval for static pages and APIs
+- **Capture screenshots** — visual references of layouts, color schemes, typography, interactions
+- **Write research briefs** — structured markdown summaries with extracted assets and findings
+
+## Research Workflow
+
+1. **Visit the target URL(s)** using `browse` — always start by loading the page and getting full content
+2. **Take screenshots** of key sections (hero, features, pricing, footer, mobile viewport)
+3. **Extract design tokens** — colors (hex/oklch), fonts (family, weights, sizes), spacing, layout grid
+4. **Catalog interactive patterns** — animations, scroll effects, hover states, micro-interactions
+5. **Search for related examples** if the task calls for competitive analysis or inspiration gathering
+6. **Write a structured brief** with findings, organized by category
+
+## Output Format
+
+```markdown
+## Research Brief: [Target]
+
+### Visual Identity
+- Primary colors: ...
+- Typography: ...
+- Layout pattern: ...
+
+### Key Sections
+1. [Section name] — [description, dimensions, notable techniques]
+
+### Interactive Patterns
+- [Animation/effect] — [how it works]
+
+### Technical Stack (if detectable)
+- Framework: ...
+- Notable libraries: ...
+
+### Design Strengths
+- [What works well and why]
+
+### Design Weaknesses
+- [What could be improved]
+
+### Extracted Assets
+- Screenshots saved to: [paths]
+- Color palette: [swatches]
+```
+
+## Guidelines
+
+- Always browse before making claims about a site's design — never guess from memory
+- Extract specific values (hex colors, font names, pixel sizes), not vague descriptions
+- Note responsive behavior differences if visible
+- Flag any accessibility issues spotted during research
+- Keep briefs factual and specific — this feeds directly into design decisions

package/.cortex/bench/tasks/sample-tasks.json

@@ -0,0 +1,20 @@
+[
+  {
+    "id": "read-package-version",
+    "taskType": "T1",
+    "prompt": "Read the file packages/core/package.json in this repository and reply with ONLY the value of its \"version\" field, nothing else.",
+    "verifier": { "type": "regex", "pattern": "\\b\\d+\\.\\d+\\.\\d+\\b" }
+  },
+  {
+    "id": "budget-signal-recall",
+    "taskType": "T1",
+    "prompt": "Read packages/core/src/orchestrator/toolBudgetSignal.ts and answer precisely: (1) what condition makes computeToolBudgetSignal return null, (2) what is the firm-STOP threshold expressed in terms of softBudget, (3) name the two sets compared in isToolProgressStalled. Cite exact identifiers.",
+    "verifier": { "type": "contains", "all": ["softBudget", "stall", "null"], "caseInsensitive": true }
+  },
+  {
+    "id": "registered-tool-count",
+    "taskType": "T3",
+    "prompt": "How many base tool executors are registered in packages/executors/src/ExecutorRegistry.ts? Reply with just the number.",
+    "verifier": { "type": "regex", "pattern": "\\b(4[0-9]|50)\\b" }
+  }
+]

package/.cortex/commands/compare.md

@@ -0,0 +1,14 @@
+---
+description: Compare two files or implementations side by side
+argument-hint: [path-a] [path-b]
+---
+
+Compare `$1` and `$2`:
+
+1. Read both files
+2. Identify:
+   - Structural differences (added/removed/moved sections)
+   - Behavioral differences (logic changes, different approaches)
+   - API differences (changed signatures, new/removed exports)
+3. Assess which implementation is better and why
+4. Note any compatibility concerns if switching from one to the other

package/.cortex/commands/deps.md

@@ -0,0 +1,16 @@
+---
+description: Analyze dependencies and imports for a file or package
+argument-hint: [file-or-package-path]
+---
+
+Analyze the dependency graph for `$1`:
+
+1. Read the file(s) and extract all imports
+2. Trace each import to its source (local file, package, or node built-in)
+3. Report:
+   - Direct dependencies (what this file imports)
+   - Reverse dependencies (what imports this file — use grep)
+   - Any circular dependencies detected
+   - Unused imports (imported but not referenced in code)
+   - Missing dependencies (referenced but not imported)
+4. If analyzing a package.json, check for unused or outdated packages

package/.cortex/commands/diff.md

@@ -0,0 +1,14 @@
+---
+description: Analyze uncommitted changes and summarize what was modified
+argument-hint: [path-or-empty]
+---
+
+Analyze the current git diff in the working directory $1:
+
+1. Run `git diff` and `git diff --cached` to see all changes
+2. Run `git status` to see untracked files
+3. For each changed file, summarize:
+   - What was added/removed/modified
+   - Whether the change looks correct
+   - Any potential issues introduced
+4. Suggest a commit message that accurately describes the changes

package/.cortex/commands/explain.md

@@ -0,0 +1,16 @@
+---
+description: Explain how a piece of code works end-to-end
+argument-hint: [file-path-or-function-name]
+---
+
+Explain how `$1` works:
+
+1. Find and read the relevant source code
+2. Trace the execution flow from entry point to completion
+3. Document:
+   - What it does (purpose)
+   - How it works (step by step)
+   - What calls it (callers)
+   - What it calls (dependencies)
+   - Edge cases and error handling
+4. Keep the explanation concise — focus on the non-obvious parts

package/.cortex/commands/find-bug.md

@@ -0,0 +1,13 @@
+---
+description: Investigate a bug from an error message or symptom
+argument-hint: [error-message-or-symptom]
+---
+
+Investigate this bug: $1
+
+1. Search the codebase for the error message or related code
+2. Read the relevant source files
+3. Trace the execution path that leads to the error
+4. Identify the root cause (not just the symptom)
+5. Propose a fix with the exact code change needed
+6. Check if the fix could break anything else (grep for callers/dependents)

package/.cortex/commands/profile.md

@@ -0,0 +1,15 @@
+---
+description: Profile a task for token usage, tool iterations, and efficiency
+argument-hint: [task-description]
+---
+
+Execute this task and report detailed performance metrics: $1
+
+After completing the task, provide a performance report:
+- **Token usage**: input tokens (system overhead vs content), output tokens
+- **Tool iterations**: how many tool round-trips were needed
+- **Tools used**: which tools were called and how many times each
+- **Efficiency**: could this have been done in fewer iterations? What would you do differently?
+- **Cache effectiveness**: were cache hits leveraged?
+
+Be explicit about the numbers — this data is used to benchmark and optimize the system.

package/.cortex/commands/review.md

@@ -0,0 +1,18 @@
+---
+description: Code review a file or directory with actionable feedback
+argument-hint: [file-or-directory-path]
+---
+
+Review the code at `$1` with focus on:
+
+1. **Bugs and logic errors** — anything that would cause incorrect behavior
+2. **Security issues** — injection, auth bypass, data exposure
+3. **Performance** — obvious inefficiencies, N+1 patterns, unnecessary allocations
+4. **Readability** — unclear naming, missing context, overly complex logic
+
+For each issue found, report:
+- File and line number
+- What's wrong
+- A concrete fix (show the corrected code)
+
+Skip style/formatting nits. Only report issues that matter.

package/.cortex/commands/search.md

@@ -0,0 +1,16 @@
+---
+description: Deep search the codebase for a concept, pattern, or usage
+argument-hint: [search-term-or-pattern]
+---
+
+Search the codebase thoroughly for: $1
+
+1. Grep for the exact term across all source files
+2. Search for related terms (aliases, similar names, abbreviations)
+3. For each match, read enough context to understand usage
+4. Categorize findings:
+   - Definitions (where it's defined/declared)
+   - Usage (where it's called/referenced)
+   - Configuration (where it's configured/set)
+   - Tests (where it's tested)
+5. Summarize: what is it, where does it live, how is it used

package/.cortex/commands/test.md

@@ -0,0 +1,15 @@
+---
+description: Run tests for a package and report results
+argument-hint: [package-path]
+---
+
+Run the test suite at `$1`:
+
+1. Execute `npm test -- --run` (or the appropriate test command) in the directory
+2. Capture stdout and stderr
+3. Report:
+   - Total tests, passed, failed, skipped
+   - For each failure: test name, expected vs actual, file location
+   - Whether the failure is a real bug or a test issue
+
+If no test command exists, check for `vitest`, `jest`, or `*.test.ts` files and run them directly.

package/.cortex/permissions.dev.json

@@ -0,0 +1,20 @@
+{
+  "$comment": "Development environment - permissive defaults. Bash dangerous-command guard via blacklist; everything else allowed.",
+  "enabled": true,
+  "defaultPolicy": "allow",
+  "policies": [
+    {
+      "type": "bash-command",
+      "config": {
+        "allowedCommands": [],
+        "blockedCommands": ["rm -rf /", "sudo rm"],
+        "requireApprovalForDangerous": true
+      }
+    }
+  ],
+  "approvalHandler": "auto-approve",
+  "auditLog": {
+    "enabled": true,
+    "path": ".cortex/audit/permissions.log"
+  }
+}

package/.cortex/permissions.example.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "../packages/core/src/middleware/permissions/PermissionConfig.ts",
+  "enabled": true,
+  "defaultPolicy": "deny",
+  "policies": [
+    {
+      "type": "whitelist",
+      "priority": 40,
+      "enabled": true,
+      "config": {
+        "allowedTools": [
+          "read_file",
+          "write_file",
+          "edit_file",
+          "execute_bash",
+          "list_files",
+          "grep",
+          "glob",
+          "create_artifact"
+        ]
+      }
+    },
+    {
+      "type": "file-operation",
+      "priority": 80,
+      "enabled": true,
+      "config": {
+        "allowedPaths": [
+          "."
+        ],
+        "blockedPaths": [
+          "/etc",
+          "/root",
+          "/.git",
+          "/node_modules",
+          "/.env",
+          "/.ssh"
+        ],
+        "requireApprovalForDelete": true,
+        "requireApprovalForWrite": false,
+        "maxPathLength": 4096
+      }
+    },
+    {
+      "type": "bash-command",
+      "priority": 80,
+      "enabled": true,
+      "config": {
+        "allowedCommands": [],
+        "blockedCommands": [
+          "rm -rf /",
+          "sudo rm",
+          "format",
+          "mkfs",
+          "fdisk"
+        ],
+        "requireApprovalForDangerous": true,
+        "customDangerousPatterns": []
+      }
+    }
+  ],
+  "approvalHandler": "cli",
+  "auditLog": {
+    "enabled": true,
+    "path": ".cortex/audit/permissions.log",
+    "maxFileSizeBytes": 10485760,
+    "enableRotation": true,
+    "maxRotatedFiles": 5
+  },
+  "enableLogging": false
+}

package/.cortex/permissions.prod.json

@@ -0,0 +1,63 @@
+{
+  "$comment": "Production environment — strict deny-by-default. Whitelist allows the minimum read-only tools needed for read-only operation. defaultPolicy: deny + approvalHandler: deny-all means anything not on the allowlist is hard-blocked.",
+  "enabled": true,
+  "defaultPolicy": "deny",
+  "policies": [
+    {
+      "type": "whitelist",
+      "enabled": true,
+      "priority": 100,
+      "config": {
+        "allowedTools": [
+          "Read",
+          "Glob",
+          "Grep",
+          "BashOutput",
+          "WebSearch",
+          "WebFetch",
+          "GetMcpConfig",
+          "ListAvailableMcpServers",
+          "SearchMcpServers",
+          "ListSessions",
+          "LoadSession",
+          "RequestHistoricalContext",
+          "SearchConversationHistory",
+          "GetConversationSegment",
+          "ListCompactionBoundaries",
+          "TodoList",
+          "SearchTools"
+        ]
+      }
+    },
+    {
+      "type": "file-operation",
+      "enabled": true,
+      "priority": 80,
+      "config": {
+        "allowedPaths": ["./public", "./dist", "./build"],
+        "blockedPaths": ["/etc", "/root", "/sys", "/.git", "/node_modules", "./config", "./secrets", "./.env"],
+        "requireApprovalForDelete": false,
+        "requireApprovalForWrite": false
+      }
+    },
+    {
+      "type": "bash-command",
+      "enabled": true,
+      "priority": 50,
+      "config": {
+        "allowedCommands": [],
+        "blockedCommands": ["*"],
+        "requireApprovalForDangerous": false
+      }
+    }
+  ],
+  "approvalHandler": "deny-all",
+  "auditLog": {
+    "enabled": true,
+    "path": ".cortex/audit/permissions.log",
+    "maxFileSizeBytes": 10485760,
+    "enableRotation": true,
+    "maxRotatedFiles": 5
+  },
+  "enableLogging": true
+}

package/.cortex/permissions.test.json

@@ -0,0 +1,19 @@
+{
+  "$comment": "Testing/CI environment - Auto-approve with minimal restrictions",
+  "enabled": true,
+  "defaultPolicy": "allow",
+  "policies": [
+    {
+      "type": "file-operation",
+      "config": {
+        "allowedPaths": ["/tmp/test-workspace"],
+        "blockedPaths": [],
+        "requireApprovalForDelete": false
+      }
+    }
+  ],
+  "approvalHandler": "auto-approve",
+  "auditLog": {
+    "enabled": false
+  }
+}