@nexus-cortex/server 4.26.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.cortex/agents/AGENT_PROFILE_GUIDE.md +307 -0
- package/.cortex/agents/README.md +268 -0
- package/.cortex/agents/a-frontend-landing-page-designer.md +41 -0
- package/.cortex/agents/autoresearch-agent.md +49 -0
- package/.cortex/agents/code-reviewer.md +63 -0
- package/.cortex/agents/context-research.md +26 -0
- package/.cortex/agents/doc-writer.md +92 -0
- package/.cortex/agents/explore.md +63 -0
- package/.cortex/agents/new-model-api-integrator-analyst.md +41 -0
- package/.cortex/agents/plan.md +109 -0
- package/.cortex/agents/pr-architecture-reviewer.md +77 -0
- package/.cortex/agents/pr-code-quality.md +78 -0
- package/.cortex/agents/pr-implementer.md +50 -0
- package/.cortex/agents/pr-security-auditor.md +62 -0
- package/.cortex/agents/pr-test-writer.md +67 -0
- package/.cortex/agents/refactor.md +118 -0
- package/.cortex/agents/test-writer.md +72 -0
- package/.cortex/agents/web-researcher.md +72 -0
- package/.cortex/bench/tasks/sample-tasks.json +20 -0
- package/.cortex/commands/compare.md +14 -0
- package/.cortex/commands/deps.md +16 -0
- package/.cortex/commands/diff.md +14 -0
- package/.cortex/commands/explain.md +16 -0
- package/.cortex/commands/find-bug.md +13 -0
- package/.cortex/commands/profile.md +15 -0
- package/.cortex/commands/review.md +18 -0
- package/.cortex/commands/search.md +16 -0
- package/.cortex/commands/test.md +15 -0
- package/.cortex/permissions.dev.json +20 -0
- package/.cortex/permissions.example.json +71 -0
- package/.cortex/permissions.prod.json +63 -0
- package/.cortex/permissions.test.json +19 -0
- package/.cortex/skills/autoresearch/SKILL.md +77 -0
- package/.cortex/skills/autoresearch/personas/README.md +45 -0
- package/.cortex/skills/autoresearch/personas/aggressive-refactor.md +25 -0
- package/.cortex/skills/autoresearch/personas/creative.md +29 -0
- package/.cortex/skills/autoresearch/personas/perf-hunter.md +27 -0
- package/.cortex/skills/autoresearch/personas/precise.md +23 -0
- package/.cortex/skills/autoresearch/personas/root-cause.md +26 -0
- package/.cortex/skills/autoresearch/personas/security-auditor.md +29 -0
- package/.cortex/skills/autoresearch/personas/skeptic-reviewer.md +31 -0
- package/.cortex/skills/autoresearch/personas/test-first.md +25 -0
- package/.cortex/skills/best-of-n/SKILL.md +76 -0
- package/.cortex/skills/cortex/SKILL.md +834 -0
- package/.cortex/skills/cortex-bench/SKILL.md +354 -0
- package/.cortex/skills/docx/SKILL.md +83 -0
- package/.cortex/skills/pdf-documents/SKILL.md +297 -0
- package/.cortex/skills/pdf-documents/sections/01-image-acquisition.md +132 -0
- package/.cortex/skills/pdf-documents/sections/02-ai-image-generation.md +274 -0
- package/.cortex/skills/pdf-documents/sections/03-paper-sizes.md +89 -0
- package/.cortex/skills/pdf-documents/sections/04-design-system.md +549 -0
- package/.cortex/skills/pdf-documents/sections/05-css-print-rules.md +135 -0
- package/.cortex/skills/pdf-documents/sections/06-svg-charts.md +100 -0
- package/.cortex/skills/pdf-documents/sections/07-templates.md +224 -0
- package/.cortex/skills/pdf-documents/sections/08-scaled-output.md +164 -0
- package/.cortex/skills/pdf-documents/sections/09-preview-qa.md +66 -0
- package/.cortex/skills/pdf-documents/sections/10-reading-pdfs.md +499 -0
- package/.cortex/skills/pdf-documents/sections/11-form-filling.md +241 -0
- package/.cortex/skills/pptx/SKILL.md +90 -0
- package/.cortex/skills/resume-analyst/SKILL.md +373 -0
- package/.cortex/skills/verify-work/SKILL.md +74 -0
- package/.cortex/skills/xlsx/SKILL.md +101 -0
- package/.cortex/system-messages/messages/WORK_QUALITY.md +159 -0
- package/.cortex/system-messages/registry.json +18 -0
- package/LICENSE +202 -0
- package/NOTICE +2 -0
- package/README.md +13 -0
- package/bin/cortex-daemon.js +47 -0
- package/bin/cortex-server.js +15 -0
- package/dist/index.d.ts +30 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +513 -0
- package/dist/index.js.map +1 -0
- package/dist/middleware/cors.d.ts +10 -0
- package/dist/middleware/cors.d.ts.map +1 -0
- package/dist/middleware/cors.js +11 -0
- package/dist/middleware/cors.js.map +1 -0
- package/dist/middleware/errorHandler.d.ts +10 -0
- package/dist/middleware/errorHandler.d.ts.map +1 -0
- package/dist/middleware/errorHandler.js +15 -0
- package/dist/middleware/errorHandler.js.map +1 -0
- package/dist/routes/approval.d.ts +2 -0
- package/dist/routes/approval.d.ts.map +1 -0
- package/dist/routes/approval.js +96 -0
- package/dist/routes/approval.js.map +1 -0
- package/dist/routes/config.d.ts +2 -0
- package/dist/routes/config.d.ts.map +1 -0
- package/dist/routes/config.js +70 -0
- package/dist/routes/config.js.map +1 -0
- package/dist/routes/health.d.ts +2 -0
- package/dist/routes/health.d.ts.map +1 -0
- package/dist/routes/health.js +1031 -0
- package/dist/routes/health.js.map +1 -0
- package/dist/routes/mcp.d.ts +2 -0
- package/dist/routes/mcp.d.ts.map +1 -0
- package/dist/routes/mcp.js +251 -0
- package/dist/routes/mcp.js.map +1 -0
- package/dist/routes/messages.d.ts +5 -0
- package/dist/routes/messages.d.ts.map +1 -0
- package/dist/routes/messages.js +136 -0
- package/dist/routes/messages.js.map +1 -0
- package/dist/routes/middleware.d.ts +2 -0
- package/dist/routes/middleware.d.ts.map +1 -0
- package/dist/routes/middleware.js +146 -0
- package/dist/routes/middleware.js.map +1 -0
- package/dist/routes/models.d.ts +2 -0
- package/dist/routes/models.d.ts.map +1 -0
- package/dist/routes/models.js +29 -0
- package/dist/routes/models.js.map +1 -0
- package/dist/routes/permissions.d.ts +2 -0
- package/dist/routes/permissions.d.ts.map +1 -0
- package/dist/routes/permissions.js +253 -0
- package/dist/routes/permissions.js.map +1 -0
- package/dist/routes/pr.d.ts +2 -0
- package/dist/routes/pr.d.ts.map +1 -0
- package/dist/routes/pr.js +222 -0
- package/dist/routes/pr.js.map +1 -0
- package/dist/routes/sessions.d.ts +2 -0
- package/dist/routes/sessions.d.ts.map +1 -0
- package/dist/routes/sessions.js +628 -0
- package/dist/routes/sessions.js.map +1 -0
- package/dist/routes/system-messages.d.ts +2 -0
- package/dist/routes/system-messages.d.ts.map +1 -0
- package/dist/routes/system-messages.js +146 -0
- package/dist/routes/system-messages.js.map +1 -0
- package/dist/routes/tools.d.ts +2 -0
- package/dist/routes/tools.d.ts.map +1 -0
- package/dist/routes/tools.js +79 -0
- package/dist/routes/tools.js.map +1 -0
- package/package.json +63 -0
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
# Agent Profile Guide
|
|
2
|
+
|
|
3
|
+
This guide covers how to create, configure, and use Task Agent profiles in Nexus Cortex.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
Task Agents are specialized sub-agents that can be spawned via the `Task` tool to handle complex, multi-step operations. Each agent is defined by a markdown file with YAML frontmatter configuration.
|
|
8
|
+
|
|
9
|
+
## Directory Structure
|
|
10
|
+
|
|
11
|
+
Agents are loaded from two locations:
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
.cortex/
|
|
15
|
+
└── agents/ # Project-specific agents
|
|
16
|
+
├── explore.md
|
|
17
|
+
├── code-reviewer.md
|
|
18
|
+
└── test-writer.md
|
|
19
|
+
|
|
20
|
+
~/.cortex/agents/ # Personal agents (shared across projects)
|
|
21
|
+
└── my-custom-agent.md
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Project agents take precedence over personal agents with the same name.
|
|
25
|
+
|
|
26
|
+
## Creating an Agent Profile
|
|
27
|
+
|
|
28
|
+
### Basic Structure
|
|
29
|
+
|
|
30
|
+
```markdown
|
|
31
|
+
---
|
|
32
|
+
name: agent-name
|
|
33
|
+
description: Brief description of when to use this agent.
|
|
34
|
+
tools:
|
|
35
|
+
- Read
|
|
36
|
+
- Write
|
|
37
|
+
- Grep
|
|
38
|
+
model: sonnet
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
# Agent Title
|
|
42
|
+
|
|
43
|
+
Your system prompt goes here. This defines the agent's personality,
|
|
44
|
+
capabilities, and behavior guidelines.
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### Frontmatter Schema
|
|
48
|
+
|
|
49
|
+
| Field | Type | Required | Description |
|
|
50
|
+
|-------|------|----------|-------------|
|
|
51
|
+
| `name` | string | Yes | Unique identifier (alphanumeric + hyphens, max 64 chars) |
|
|
52
|
+
| `description` | string | Yes | When to use this agent (shown in tool description) |
|
|
53
|
+
| `tools` | string[] or "all" | Yes | Allowed tools or "all" for unrestricted access |
|
|
54
|
+
| `model` | string | Yes | Model alias or full ID, or "inherit" for parent's model |
|
|
55
|
+
|
|
56
|
+
### Name Requirements
|
|
57
|
+
|
|
58
|
+
- Alphanumeric characters and hyphens only
|
|
59
|
+
- 1-64 characters
|
|
60
|
+
- Must be unique within the same location (project/personal)
|
|
61
|
+
- Case-sensitive
|
|
62
|
+
|
|
63
|
+
Valid: `code-reviewer`, `test123`, `my-agent`
|
|
64
|
+
Invalid: `Code Reviewer`, `test_writer`, `a-really-long-name-that-exceeds-the-maximum-allowed-length-of-64-characters`
|
|
65
|
+
|
|
66
|
+
## Tool Configuration
|
|
67
|
+
|
|
68
|
+
### Restricted Tool Access
|
|
69
|
+
|
|
70
|
+
Specify which tools the agent can use:
|
|
71
|
+
|
|
72
|
+
```yaml
|
|
73
|
+
tools:
|
|
74
|
+
- Read # Read files
|
|
75
|
+
- Glob # Find files by pattern
|
|
76
|
+
- Grep # Search file contents
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The agent will only have access to these tools. Any attempt to use other tools will be blocked.
|
|
80
|
+
|
|
81
|
+
### Full Tool Access
|
|
82
|
+
|
|
83
|
+
For agents that need all capabilities:
|
|
84
|
+
|
|
85
|
+
```yaml
|
|
86
|
+
tools: all
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
**Warning**: Use `all` sparingly. Restricted tools improve safety and focus.
|
|
90
|
+
|
|
91
|
+
### Available Tools
|
|
92
|
+
|
|
93
|
+
Core file operations:
|
|
94
|
+
- `Read` - Read file contents
|
|
95
|
+
- `Write` - Create/overwrite files
|
|
96
|
+
- `Edit` - Edit existing files
|
|
97
|
+
- `Glob` - Find files by pattern
|
|
98
|
+
- `Grep` - Search file contents
|
|
99
|
+
|
|
100
|
+
Shell operations:
|
|
101
|
+
- `Bash` - Execute shell commands
|
|
102
|
+
- `BashOutput` - Get output from background shells
|
|
103
|
+
- `KillShell` - Terminate shells
|
|
104
|
+
|
|
105
|
+
Web operations:
|
|
106
|
+
- `WebSearch` - Search the web
|
|
107
|
+
- `WebFetch` - Fetch web pages
|
|
108
|
+
|
|
109
|
+
Planning and UI:
|
|
110
|
+
- `TodoWrite` - Manage task lists
|
|
111
|
+
- `AskUserQuestion` - Ask user questions
|
|
112
|
+
- `ExitPlanMode` - Exit plan mode
|
|
113
|
+
|
|
114
|
+
Special:
|
|
115
|
+
- `Task` - Spawn sub-agents (use carefully to avoid infinite loops)
|
|
116
|
+
- `SlashCommand` - Execute slash commands
|
|
117
|
+
- `Skill` - Use skills
|
|
118
|
+
|
|
119
|
+
## Model Configuration
|
|
120
|
+
|
|
121
|
+
### Model Aliases
|
|
122
|
+
|
|
123
|
+
Use convenient aliases for common models:
|
|
124
|
+
|
|
125
|
+
```yaml
|
|
126
|
+
model: sonnet # Claude Sonnet 4.5
|
|
127
|
+
model: opus # Claude Opus 4.1
|
|
128
|
+
model: haiku # Claude 3.5 Haiku
|
|
129
|
+
model: gemini # Gemini 2.5 Pro
|
|
130
|
+
model: grok # Grok 4.1 Fast
|
|
131
|
+
model: deepseek # DeepSeek Chat
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Full Model IDs
|
|
135
|
+
|
|
136
|
+
Specify exact models:
|
|
137
|
+
|
|
138
|
+
```yaml
|
|
139
|
+
model: claude-sonnet-4-5-20250929
|
|
140
|
+
model: gemini-2.5-flash
|
|
141
|
+
model: gpt-4o
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Inherit Parent Model
|
|
145
|
+
|
|
146
|
+
Use the same model as the parent session:
|
|
147
|
+
|
|
148
|
+
```yaml
|
|
149
|
+
model: inherit
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### Available Aliases
|
|
153
|
+
|
|
154
|
+
| Alias | Model |
|
|
155
|
+
|-------|-------|
|
|
156
|
+
| `sonnet`, `claude-sonnet`, `sonnet-4.5` | claude-sonnet-4-5-20250929 |
|
|
157
|
+
| `opus`, `claude-opus`, `opus-4` | claude-opus-4-1-20250805 |
|
|
158
|
+
| `haiku`, `claude-haiku`, `haiku-3.5` | claude-3-5-haiku-20241022 |
|
|
159
|
+
| `gemini`, `gemini-pro`, `gemini-2.5` | gemini-2.5-pro |
|
|
160
|
+
| `gemini-flash`, `flash` | gemini-2.5-flash |
|
|
161
|
+
| `grok`, `grok-4`, `grok-fast` | grok-4.1-fast-reasoning |
|
|
162
|
+
| `deepseek` | deepseek-v4-pro |
|
|
163
|
+
| `reasoner` | deepseek-v4-pro |
|
|
164
|
+
| `gpt4`, `gpt-4` | gpt-4.1 |
|
|
165
|
+
| `o1`, `o3`, `o4-mini` | (OpenAI reasoning models) |
|
|
166
|
+
|
|
167
|
+
## System Prompt Best Practices
|
|
168
|
+
|
|
169
|
+
### Structure
|
|
170
|
+
|
|
171
|
+
1. **Role definition** - What the agent is and does
|
|
172
|
+
2. **Approach/methodology** - How the agent works
|
|
173
|
+
3. **Guidelines** - Rules and constraints
|
|
174
|
+
4. **Output format** - Expected response structure
|
|
175
|
+
|
|
176
|
+
### Example
|
|
177
|
+
|
|
178
|
+
```markdown
|
|
179
|
+
---
|
|
180
|
+
name: security-auditor
|
|
181
|
+
description: Performs security audits on code, identifying vulnerabilities and suggesting fixes.
|
|
182
|
+
tools:
|
|
183
|
+
- Read
|
|
184
|
+
- Glob
|
|
185
|
+
- Grep
|
|
186
|
+
model: opus
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
# Security Auditor Agent
|
|
190
|
+
|
|
191
|
+
You are a security expert specializing in application security.
|
|
192
|
+
|
|
193
|
+
## Your Role
|
|
194
|
+
|
|
195
|
+
Analyze code for security vulnerabilities including:
|
|
196
|
+
- Injection attacks (SQL, Command, XSS)
|
|
197
|
+
- Authentication/authorization flaws
|
|
198
|
+
- Data exposure risks
|
|
199
|
+
- Cryptographic weaknesses
|
|
200
|
+
|
|
201
|
+
## Approach
|
|
202
|
+
|
|
203
|
+
1. Read relevant files systematically
|
|
204
|
+
2. Check for known vulnerability patterns
|
|
205
|
+
3. Assess severity (Critical/High/Medium/Low)
|
|
206
|
+
4. Provide remediation guidance
|
|
207
|
+
|
|
208
|
+
## Output Format
|
|
209
|
+
|
|
210
|
+
Report each finding as:
|
|
211
|
+
|
|
212
|
+
### [Severity] [Vulnerability Type]
|
|
213
|
+
**Location**: file:line
|
|
214
|
+
**Description**: What the issue is
|
|
215
|
+
**Impact**: What could happen
|
|
216
|
+
**Remediation**: How to fix it
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### Tips
|
|
220
|
+
|
|
221
|
+
- **Be specific** - Clear instructions produce better results
|
|
222
|
+
- **Include examples** - Show expected output format
|
|
223
|
+
- **Define scope** - What should and shouldn't be done
|
|
224
|
+
- **Set constraints** - Quality standards, safety rules
|
|
225
|
+
|
|
226
|
+
## Using Agents
|
|
227
|
+
|
|
228
|
+
### Via Task Tool
|
|
229
|
+
|
|
230
|
+
The Task tool spawns agents:
|
|
231
|
+
|
|
232
|
+
```
|
|
233
|
+
Use the Task tool to spawn the code-reviewer agent with:
|
|
234
|
+
- task: "Review the authentication module for security issues"
|
|
235
|
+
- agent: "code-reviewer"
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
### Agent Selection
|
|
239
|
+
|
|
240
|
+
The parent LLM selects agents based on the task and agent descriptions. Write clear descriptions to improve selection accuracy.
|
|
241
|
+
|
|
242
|
+
### Monitoring
|
|
243
|
+
|
|
244
|
+
Sub-agent events are streamed to the parent:
|
|
245
|
+
- `agent:started` - Agent begins execution
|
|
246
|
+
- `agent:progress` - Progress updates (tokens, turns)
|
|
247
|
+
- `agent:tool_call` - Tool usage
|
|
248
|
+
- `agent:text` - Output text
|
|
249
|
+
- `agent:completed` - Execution complete
|
|
250
|
+
- `agent:error` - Errors encountered
|
|
251
|
+
|
|
252
|
+
## Advanced Configuration
|
|
253
|
+
|
|
254
|
+
### Timeout Settings
|
|
255
|
+
|
|
256
|
+
Configure via Task tool options (not in agent definition):
|
|
257
|
+
|
|
258
|
+
```
|
|
259
|
+
timeout: 300000 # 5 minutes (default)
|
|
260
|
+
maxTurns: 10 # Maximum conversation turns
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### Permission Inheritance
|
|
264
|
+
|
|
265
|
+
Agents inherit permission policies from the parent session:
|
|
266
|
+
- Parent's whitelist/blacklist policies apply
|
|
267
|
+
- File operation restrictions are enforced
|
|
268
|
+
- Bash command policies carry over
|
|
269
|
+
|
|
270
|
+
Agents cannot exceed parent permissions, only further restrict them.
|
|
271
|
+
|
|
272
|
+
## Troubleshooting
|
|
273
|
+
|
|
274
|
+
### Agent Not Found
|
|
275
|
+
|
|
276
|
+
Check:
|
|
277
|
+
1. File is in `.cortex/agents/` or `~/.cortex/agents/`
|
|
278
|
+
2. File has `.md` extension
|
|
279
|
+
3. YAML frontmatter is valid
|
|
280
|
+
4. Name matches file name (recommended)
|
|
281
|
+
|
|
282
|
+
### Invalid Configuration
|
|
283
|
+
|
|
284
|
+
Common issues:
|
|
285
|
+
- Missing required field (`name`, `description`, `tools`, `model`)
|
|
286
|
+
- Invalid tool name (check spelling, case-sensitive)
|
|
287
|
+
- Invalid model alias (check available aliases)
|
|
288
|
+
- Invalid name format (special characters)
|
|
289
|
+
|
|
290
|
+
### Agent Errors
|
|
291
|
+
|
|
292
|
+
Check the agent:error event for details. Common causes:
|
|
293
|
+
- Tool restrictions blocking required operations
|
|
294
|
+
- Model API errors
|
|
295
|
+
- Timeout exceeded
|
|
296
|
+
- Invalid system prompt
|
|
297
|
+
|
|
298
|
+
## Example Agents
|
|
299
|
+
|
|
300
|
+
See the other files in this directory for complete examples:
|
|
301
|
+
|
|
302
|
+
- `explore.md` - Fast codebase exploration
|
|
303
|
+
- `code-reviewer.md` - Code review
|
|
304
|
+
- `test-writer.md` - Test generation
|
|
305
|
+
- `doc-writer.md` - Documentation
|
|
306
|
+
- `refactor.md` - Code refactoring
|
|
307
|
+
- `plan.md` - Implementation planning
|
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
# Agent Dispatch Modes — Nexus Cortex
|
|
2
|
+
|
|
3
|
+
This directory contains Task Agent profiles. The orchestrator spawns agents via `child_process.fork()` when the LLM calls the `Task` tool. Agents run as independent processes with their own orchestrator instance, tools, and session.
|
|
4
|
+
|
|
5
|
+
## Quick Reference
|
|
6
|
+
|
|
7
|
+
| Mode | Agents | Communication | Workspace | Trigger |
|
|
8
|
+
|------|--------|--------------|-----------|---------|
|
|
9
|
+
| **Solo** | 1 | None | Shared | 1 Task tool call |
|
|
10
|
+
| **Parallel** | N | None | Shared | N Task tool calls in same turn |
|
|
11
|
+
| **Team** | N | Briefing + Broadcasting | Shared | N Task calls (auto-detected) |
|
|
12
|
+
| **Git Worktree** | N | Briefing + Broadcasting | Isolated per agent | WorkspaceManager + N Task calls |
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Mode 1: Solo Agent
|
|
17
|
+
|
|
18
|
+
A single Task tool call spawns one agent. The agent runs independently, completes its work, and returns results to the orchestrator.
|
|
19
|
+
|
|
20
|
+
### When to Use
|
|
21
|
+
- Focused single-domain tasks (code review, exploration, test writing)
|
|
22
|
+
- Tasks that don't benefit from parallelization
|
|
23
|
+
|
|
24
|
+
### Usage
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
# Via cortex CLI — model dispatches a solo agent internally
|
|
28
|
+
cortex --quiet "Review packages/core/src/orchestrator/APIClient.ts for security issues"
|
|
29
|
+
|
|
30
|
+
# Via API
|
|
31
|
+
curl -s http://localhost:4000/v1/messages \
|
|
32
|
+
-H "Content-Type: application/json" \
|
|
33
|
+
-d '{"messages":[{"role":"user","content":"Use the code-reviewer agent to review APIClient.ts"}]}'
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### How It Works
|
|
37
|
+
1. LLM calls Task tool with agent name and prompt
|
|
38
|
+
2. Orchestrator spawns child process via `SubAgentProcessManager.spawnAgent()`
|
|
39
|
+
3. Agent runs with its own tools, model, and system prompt (from `.cortex/agents/{name}.md`)
|
|
40
|
+
4. IPC events stream back: tool calls, text, progress, completion
|
|
41
|
+
5. Agent result returned as tool_result to parent LLM
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Mode 2: Parallel Agents
|
|
46
|
+
|
|
47
|
+
Multiple Task tool calls in the same LLM response are dispatched simultaneously via `Promise.all`. Agents run independently with no communication between them.
|
|
48
|
+
|
|
49
|
+
### When to Use
|
|
50
|
+
- Independent tasks that can run concurrently
|
|
51
|
+
- Multiple searches or analyses that don't need to share findings
|
|
52
|
+
- Speed-critical workflows where wall-clock time matters
|
|
53
|
+
|
|
54
|
+
### Usage
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
# The model decides to parallelize based on the prompt
|
|
58
|
+
cortex --quiet "Search for all usages of deprecated API patterns AND check test coverage for the auth module"
|
|
59
|
+
|
|
60
|
+
# Explicit multi-agent dispatch
|
|
61
|
+
cortex --quiet "Use 3 parallel explore agents to search for: (1) all WebSocket code, (2) all authentication middleware, (3) all rate limiting logic"
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### How It Works
|
|
65
|
+
1. LLM emits N Task tool calls in a single response
|
|
66
|
+
2. `handleToolCalls()` in orchestrator separates Task tools from regular tools
|
|
67
|
+
3. All N agents spawned simultaneously via `Promise.all`
|
|
68
|
+
4. Each agent runs independently — no shared state or communication
|
|
69
|
+
5. All results collected and returned to parent LLM
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Mode 3: Team Agents
|
|
74
|
+
|
|
75
|
+
When the orchestrator detects >1 Task tools in the same response, it automatically activates team mode. Each agent receives a **team briefing** prepended to its prompt, and when any agent completes, its findings are **broadcast** to still-running siblings.
|
|
76
|
+
|
|
77
|
+
### When to Use
|
|
78
|
+
- Tasks where agents benefit from knowing about each other's work
|
|
79
|
+
- PR review (security + quality + architecture agents share findings)
|
|
80
|
+
- Any parallel dispatch where cross-pollination of results adds value
|
|
81
|
+
|
|
82
|
+
### Usage
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
# PR review — dispatches 3 audit agents as a team
|
|
86
|
+
cortex --pr review owner/repo 42
|
|
87
|
+
|
|
88
|
+
# Custom team dispatch
|
|
89
|
+
cortex --quiet "Dispatch a team of 3 agents: one to review security, one to review performance, one to check test coverage for the auth refactor"
|
|
90
|
+
|
|
91
|
+
# Via API
|
|
92
|
+
curl -s http://localhost:4000/v1/messages \
|
|
93
|
+
-H "Content-Type: application/json" \
|
|
94
|
+
-d '{"messages":[{"role":"user","content":"Use parallel agents to review the auth module. Dispatch pr-security-auditor, pr-code-quality, and pr-architecture-reviewer as a team."}]}'
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### How It Works
|
|
98
|
+
1. LLM emits N Task tool calls in a single response
|
|
99
|
+
2. `handleToolCalls()` detects N > 1, calls `injectTeamBriefing()`
|
|
100
|
+
3. Each agent's prompt gets prepended with:
|
|
101
|
+
```
|
|
102
|
+
📋 **Team Briefing**
|
|
103
|
+
You are part of a {N}-agent team working in parallel.
|
|
104
|
+
|
|
105
|
+
Teammates:
|
|
106
|
+
- {agent-1}: {assignment}
|
|
107
|
+
- {agent-2}: {assignment}
|
|
108
|
+
|
|
109
|
+
The orchestrator will forward relevant findings from teammates.
|
|
110
|
+
Focus on YOUR assignment. Do not duplicate others' work.
|
|
111
|
+
```
|
|
112
|
+
4. Agents run in parallel
|
|
113
|
+
5. When Agent A completes, `broadcastGuidance()` sends summary to Agents B, C
|
|
114
|
+
6. Running agents receive guidance via IPC → `injectGuidance()` → ephemeral `<system-reminder>` or thinking block
|
|
115
|
+
7. All results collected and returned to parent LLM
|
|
116
|
+
|
|
117
|
+
### Cross-Agent Communication Path
|
|
118
|
+
```
|
|
119
|
+
Agent A completes
|
|
120
|
+
→ SubAgentProcessManager.broadcastGuidance(summary, excludeAgentA)
|
|
121
|
+
→ IPC message type 'guidance' sent to Agent B, C
|
|
122
|
+
→ agent-mode.ts handler pushes to pendingGuidance[]
|
|
123
|
+
→ orchestrator.injectGuidance(message, 'team_update')
|
|
124
|
+
→ injectThinkingBlock() dual-path:
|
|
125
|
+
Google: thinking block
|
|
126
|
+
Others: <system-reminder> tag
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## Mode 4: Git Worktree (Isolated Workspace)
|
|
132
|
+
|
|
133
|
+
Combines team mode with per-agent git worktree isolation. Each agent works in its own branch and directory, preventing file conflicts. The `WorkspaceManager` tool manages the worktree lifecycle.
|
|
134
|
+
|
|
135
|
+
### When to Use
|
|
136
|
+
- Multiple agents editing the same codebase simultaneously
|
|
137
|
+
- PR implementation with parallel feature branches
|
|
138
|
+
- Multi-repo operations (clone external repos for each agent)
|
|
139
|
+
- Any scenario where agents might create conflicting file changes
|
|
140
|
+
|
|
141
|
+
### Usage
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
# Internal development — multiple agents on different features
|
|
145
|
+
cortex --quiet "Use WorkspaceManager to create 2 worktrees (branch auth-refactor and branch api-cleanup), then dispatch pr-implementer agents to each worktree with specific tasks"
|
|
146
|
+
|
|
147
|
+
# External PR — clone and review
|
|
148
|
+
cortex --pr review external-org/repo 42
|
|
149
|
+
|
|
150
|
+
# Multi-repo workflow
|
|
151
|
+
cortex --quiet "Clone owner/upstream-lib into a worktree AND create a local worktree for this repo's changes. Dispatch agents to update shared types in both."
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### How It Works
|
|
155
|
+
1. LLM calls `WorkspaceManager` tool to create worktrees:
|
|
156
|
+
- `create` mode: `git worktree add /tmp/workspace-{id} -b {branch}`
|
|
157
|
+
- `clone` mode: `git clone {repo} /tmp/repo-{id}` then worktree
|
|
158
|
+
2. WorkspaceManager returns structured JSON with worktree paths
|
|
159
|
+
3. LLM includes worktree paths in Task prompts for each agent
|
|
160
|
+
4. Team briefing includes workspace paths for each teammate
|
|
161
|
+
5. Each agent operates in its isolated worktree
|
|
162
|
+
6. After agents complete, LLM can:
|
|
163
|
+
- `diff` mode: See what each agent changed
|
|
164
|
+
- `cleanup` mode: Remove worktrees
|
|
165
|
+
|
|
166
|
+
### WorkspaceManager Modes
|
|
167
|
+
|
|
168
|
+
| Mode | Command | Returns |
|
|
169
|
+
|------|---------|---------|
|
|
170
|
+
| `create` | `git worktree add /tmp/workspace-{id} -b {branch}` | worktree path |
|
|
171
|
+
| `clone` | `git clone {repo}` + `git worktree add` | worktree path |
|
|
172
|
+
| `status` | `git worktree list` | all active worktrees |
|
|
173
|
+
| `diff` | `git -C {path} diff {base}` | diff content |
|
|
174
|
+
| `cleanup` | `git worktree remove {path}` | confirmation |
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## Visual Monitoring (Optional)
|
|
179
|
+
|
|
180
|
+
Set `AGENT_TMUX_MONITOR=true` to enable tmux pane monitoring for parallel agents.
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
# Enable monitoring
|
|
184
|
+
AGENT_TMUX_MONITOR=true cortex --quiet "Dispatch 3 parallel agents..."
|
|
185
|
+
|
|
186
|
+
# View in browser
|
|
187
|
+
open http://localhost:4001/tmux/team-{dispatchId}
|
|
188
|
+
|
|
189
|
+
# Attach in terminal
|
|
190
|
+
tmux attach -t team-{dispatchId}
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
Each agent gets its own tmux pane showing live IPC events:
|
|
194
|
+
- `🔧 Read /path/to/file` — tool calls
|
|
195
|
+
- Agent text output
|
|
196
|
+
- `Turn 3 | 5.2K tokens | 12.3s` — progress
|
|
197
|
+
- `✅ Done: {summary}` — completion
|
|
198
|
+
- `❌ Error: {message}` — errors
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## Agent Profiles in This Directory
|
|
203
|
+
|
|
204
|
+
### General Purpose
|
|
205
|
+
| Agent | Model | Tools | Use Case |
|
|
206
|
+
|-------|-------|-------|----------|
|
|
207
|
+
| `explore` | inherit | Read, Glob, Grep | Fast codebase exploration |
|
|
208
|
+
| `code-reviewer` | inherit | Read, Grep, Glob | Code review with findings |
|
|
209
|
+
| `test-writer` | inherit | Read, Write, Edit, Bash, Grep, Glob | Test generation |
|
|
210
|
+
| `doc-writer` | inherit | Read, Write, Edit, Glob, Grep | Documentation |
|
|
211
|
+
| `refactor` | inherit | Read, Write, Edit, Bash, Grep, Glob | Code refactoring |
|
|
212
|
+
| `plan` | inherit | Read, Glob, Grep | Implementation planning |
|
|
213
|
+
| `context-research` | inherit | Read, Grep, Glob, WebSearch, WebFetch | Research with web access |
|
|
214
|
+
|
|
215
|
+
### PR Review Team
|
|
216
|
+
| Agent | Model | Tools | Role in Team |
|
|
217
|
+
|-------|-------|-------|-------------|
|
|
218
|
+
| `pr-security-auditor` | inherit | Grep, Read, Bash | Scan for vulnerabilities, malicious code, supply chain risks |
|
|
219
|
+
| `pr-code-quality` | inherit | Read, Grep, Glob | Review style, complexity, anti-patterns, test gaps |
|
|
220
|
+
| `pr-architecture-reviewer` | inherit | Read, Grep, Glob, Bash | Breaking changes, API surface, dependency impact |
|
|
221
|
+
| `pr-implementer` | inherit | Read, Edit, Write, Bash, Grep, Glob | Implement code changes in git worktree |
|
|
222
|
+
| `pr-test-writer` | inherit | Read, Write, Edit, Bash, Grep, Glob | Write tests for PR changes |
|
|
223
|
+
|
|
224
|
+
### Specialized
|
|
225
|
+
| Agent | Model | Tools | Use Case |
|
|
226
|
+
|-------|-------|-------|----------|
|
|
227
|
+
| `new-model-api-integrator-analyst` | inherit | all | Analyze new AI provider APIs for integration |
|
|
228
|
+
| `a-frontend-landing-page-designer` | inherit | all | Design frontend interfaces |
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## Creating a New Agent
|
|
233
|
+
|
|
234
|
+
See `AGENT_PROFILE_GUIDE.md` for the full guide. Quick version:
|
|
235
|
+
|
|
236
|
+
```markdown
|
|
237
|
+
---
|
|
238
|
+
name: my-agent
|
|
239
|
+
description: Brief description of when to use this agent.
|
|
240
|
+
tools:
|
|
241
|
+
- Read
|
|
242
|
+
- Write
|
|
243
|
+
- Grep
|
|
244
|
+
model: inherit
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
# My Agent
|
|
248
|
+
|
|
249
|
+
System prompt defining the agent's role, approach, and output format.
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
**Required fields**: `name`, `description`, `tools`, `model`
|
|
253
|
+
**Model options**: `inherit` (parent's model), aliases (`sonnet`, `opus`, `haiku`, `grok`), or full IDs
|
|
254
|
+
**Tools**: Array of tool names or `all` for unrestricted access
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## Troubleshooting
|
|
259
|
+
|
|
260
|
+
| Issue | Fix |
|
|
261
|
+
|-------|-----|
|
|
262
|
+
| Agent not found | Check `.cortex/agents/{name}.md` exists with valid YAML frontmatter |
|
|
263
|
+
| Team briefing not appearing | Ensure >1 Task tools in same LLM response |
|
|
264
|
+
| WorkspaceManager branch conflict | `git branch -D {branch}` to clean stale branches |
|
|
265
|
+
| Guidance not received | Check agent-mode.ts guidance handler, verify IPC is connected |
|
|
266
|
+
| Tmux monitoring not working | Verify `tmux` binary available, `AGENT_TMUX_MONITOR=true` |
|
|
267
|
+
| PR commands failing | Verify `gh auth status` — gh CLI must be authenticated |
|
|
268
|
+
| Model not found errors | Use registered model IDs (check `cortex --list-models`) |
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: landing-page-designer
|
|
3
|
+
description: A frontend landing page designer for rich beautiful landing pages
|
|
4
|
+
tools:
|
|
5
|
+
- read
|
|
6
|
+
- write
|
|
7
|
+
- edit
|
|
8
|
+
- glob
|
|
9
|
+
- grep
|
|
10
|
+
- bash
|
|
11
|
+
- web_fetch
|
|
12
|
+
model: gpt-5-mini
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# a-frontend-landing-page-designer
|
|
16
|
+
|
|
17
|
+
## Your Role
|
|
18
|
+
|
|
19
|
+
You are a specialized A frontend landing page designer for rich beautiful landing pages agent.
|
|
20
|
+
|
|
21
|
+
## Context from User
|
|
22
|
+
|
|
23
|
+
A frontend landing page designer for rich beautiful landing pages HTML/CSS,. js, and tailwind it should focus on easily extendable frameworks
|
|
24
|
+
|
|
25
|
+
## Responsibilities
|
|
26
|
+
|
|
27
|
+
- Understand and fulfill requests related to A frontend landing page designer for rich beautiful landing pages
|
|
28
|
+
- Use available tools effectively to accomplish tasks
|
|
29
|
+
- Provide clear explanations of your actions
|
|
30
|
+
- Ask for clarification when requirements are ambiguous
|
|
31
|
+
|
|
32
|
+
## Guidelines
|
|
33
|
+
|
|
34
|
+
- Be thorough and methodical in your approach
|
|
35
|
+
- Focus on quality and correctness
|
|
36
|
+
- Explain your reasoning when making decisions
|
|
37
|
+
- Follow best practices for the domain
|
|
38
|
+
|
|
39
|
+
## Output Format
|
|
40
|
+
|
|
41
|
+
Provide clear, well-structured output appropriate to the task.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: autoresearch-agent
|
|
3
|
+
description: Runs one auto-research experiment cycle on a single backlog deficiency — fix in an isolated worktree, measure base-vs-candidate through the statistical gate, and report a verified candidate. One of N the PM spawns per deficiency.
|
|
4
|
+
tools:
|
|
5
|
+
- read
|
|
6
|
+
- write
|
|
7
|
+
- edit
|
|
8
|
+
- glob
|
|
9
|
+
- grep
|
|
10
|
+
- bash
|
|
11
|
+
- research_backlog
|
|
12
|
+
- workspace_manager
|
|
13
|
+
model: deepseek-v4-flash
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# Auto-Research Agent
|
|
17
|
+
|
|
18
|
+
You are ONE of several auto-research agents the PM spawned on the **same** backlog deficiency. Your job: produce one candidate improvement and measure whether it is a REAL, verified improvement — then report. You do **not** merge anything yourself; the PM arbitrates across all agents and merges the verified winner.
|
|
19
|
+
|
|
20
|
+
## Read your task first
|
|
21
|
+
Your prompt contains:
|
|
22
|
+
- The **deficiency** (what to improve) and how it's measured (task-set / metric).
|
|
23
|
+
- An **EXECUTION MODE**: `native` or `mcp`.
|
|
24
|
+
- Your **strategy flavor** (e.g. conservative vs aggressive fix, a specific hypothesis). You are one of N varied arms — stay in your lane so the arms stay diverse.
|
|
25
|
+
|
|
26
|
+
## Operating rules — read before you start
|
|
27
|
+
- **If it is NOT measurable, FAIL FAST.** If the deficiency has no eval / repro / task-set you can run a base-vs-candidate measurement against, do NOT explore the codebase indefinitely. Within a few turns, set the deficiency `wont_fix` with the note "not measurable — needs a benchmark task-set/eval" and STOP. A long fruitless search is worse than an honest early bail.
|
|
28
|
+
- **Turn budget.** Reach a runnable experiment within ~15 turns. If you cannot, stop and report what is blocking (no metric, no repro, can't locate the code) — do not burn the whole budget searching.
|
|
29
|
+
- **Follow YOUR assigned strategy.** Pursue the persona/strategy in your prompt; do NOT converge on the same path as the other arms. If every arm does the same thing, the parallelism is wasted.
|
|
30
|
+
- **Always update the backlog before finishing** — `fixed`, `verified`, or `wont_fix` with a note. Never leave the deficiency `in_progress` and walk away.
|
|
31
|
+
|
|
32
|
+
## EXECUTION MODE: native (use the internal tools)
|
|
33
|
+
1. **`ResearchBacklog`** → `next` / confirm the deficiency; `in_progress` to claim it (use the experiment tag from your prompt).
|
|
34
|
+
2. **`WorkspaceManager`** → create an isolated **candidate worktree** off the base ref. NEVER edit the user's working tree.
|
|
35
|
+
3. **Apply your fix** in the worktree. Either run the headless Fixer — `cortex autoresearch fix --cwd <worktree> --prompt "<deficiency + your strategy>"` via Bash — or edit directly with Read/Edit/Write. Then commit it (`git -C <worktree> add -A && git -C <worktree> commit -m "..."`).
|
|
36
|
+
4. **Measure**: `cortex autoresearch experiment --experiment-tag <tag> --base-dir <base> --candidate-dir <worktree> --task-set <tasks> [--holdout-set <holdout>] --json` via Bash. (Add `--run-cmd '<eval>'` for a non-cortex target.)
|
|
37
|
+
5. **Read the JSON verdict**: `decision` (keep/discard), `effect`, `mergeEligible` (keep + FWER + holdout-verified).
|
|
38
|
+
6. **`ResearchBacklog`** → `fixed` (passed the discovery task) or — only after a holdout confirms — `verified`. Never `verified` on train alone.
|
|
39
|
+
|
|
40
|
+
## EXECUTION MODE: mcp (offload to the hosted harness)
|
|
41
|
+
Use the configured **auto-research MCP** tools instead of the internal CLI: submit the experiment, poll its status, read the verdict. Do **not** run the local `cortex autoresearch` CLI in this mode — the MCP server runs it for you in its container.
|
|
42
|
+
|
|
43
|
+
## Discipline (do not break these)
|
|
44
|
+
- **fixed ≠ verified.** A candidate that only passes the task that surfaced the deficiency is `fixed`, NOT verified. Only a HELD-OUT confirmation makes it `verified`.
|
|
45
|
+
- **Do not self-merge.** Report your candidate ref + its verdict; the PM applies the cross-arm gate and merges the single winner. With N parallel arms, some clear the bar by chance — central arbitration is what keeps that honest.
|
|
46
|
+
- **Stay isolated.** All work in your own worktree off the base ref; never touch the user's branch or working tree.
|
|
47
|
+
|
|
48
|
+
## Report back
|
|
49
|
+
Return: your candidate ref, the verdict JSON (`decision` / `effect` / `mergeEligible`), what you changed, and whether it is holdout-verified. Keep it tight — the PM is comparing N of these.
|