@neotx/agents 0.1.0-alpha.22 → 0.1.0-alpha.24
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/GUIDE.md +5 -7
- package/README.md +4 -10
- package/SUPERVISOR.md +94 -87
- package/agents/architect.yml +16 -2
- package/agents/developer.yml +20 -1
- package/agents/reviewer.yml +2 -1
- package/agents/scout.yml +1 -0
- package/package.json +1 -1
- package/prompts/architect.md +185 -67
- package/prompts/developer.md +274 -42
- package/prompts/reviewer.md +35 -4
- package/prompts/subagents/code-quality-reviewer.md +49 -0
- package/prompts/subagents/plan-reviewer.md +34 -0
- package/prompts/subagents/spec-reviewer.md +43 -0
- package/agents/fixer.yml +0 -12
- package/agents/refiner.yml +0 -11
- package/prompts/fixer.md +0 -135
- package/prompts/refiner.md +0 -119
package/GUIDE.md
CHANGED
|
@@ -17,7 +17,7 @@ The supervisor is NOT a chatbot. It's an event-driven heartbeat loop that:
|
|
|
17
17
|
- Dispatches the right agents in the right order
|
|
18
18
|
- Monitors progress and reacts to completions/failures
|
|
19
19
|
- Persists memory across sessions — it learns your codebase over time
|
|
20
|
-
- Handles the full lifecycle:
|
|
20
|
+
- Handles the full lifecycle: architect (triage + design) → develop (self-review) → review (if needed) → done
|
|
21
21
|
|
|
22
22
|
```bash
|
|
23
23
|
# Start the supervisor (background daemon)
|
|
@@ -31,7 +31,7 @@ neo supervise --message "Implement user authentication with JWT. Create login/re
|
|
|
31
31
|
# 2. Dispatches architect if design is needed
|
|
32
32
|
# 3. Dispatches developer for each task
|
|
33
33
|
# 4. Dispatches reviewer to review PRs
|
|
34
|
-
# 5.
|
|
34
|
+
# 5. Re-dispatches developer if issues are found
|
|
35
35
|
# 6. Reports back via activity log
|
|
36
36
|
|
|
37
37
|
# Check supervisor status
|
|
@@ -103,8 +103,6 @@ neo mcp add notion # requires NOTION_TOKEN env var
|
|
|
103
103
|
| `developer` | opus | writable | Implementing code changes, bug fixes, new features |
|
|
104
104
|
| `architect` | opus | readonly | Designing systems, planning features, decomposing work |
|
|
105
105
|
| `reviewer` | sonnet | readonly | Code review — blocks on ≥1 CRITICAL or ≥3 WARNINGs |
|
|
106
|
-
| `fixer` | opus | writable | Fixing issues found by reviewer — targets root causes |
|
|
107
|
-
| `refiner` | opus | readonly | Evaluating ticket quality, splitting vague tickets |
|
|
108
106
|
|
|
109
107
|
**Custom agents:** Drop a YAML file in `.neo/agents/` to extend built-in agents:
|
|
110
108
|
|
|
@@ -349,7 +347,7 @@ neo decision pending
|
|
|
349
347
|
# User answers
|
|
350
348
|
neo decision answer dec_x7k9m2 hotfix
|
|
351
349
|
|
|
352
|
-
# Supervisor receives the answer and dispatches
|
|
350
|
+
# Supervisor receives the answer and re-dispatches developer with hotfix priority
|
|
353
351
|
```
|
|
354
352
|
|
|
355
353
|
### neo webhooks — Event notifications
|
|
@@ -553,7 +551,7 @@ neo cost --short
|
|
|
553
551
|
neo supervise --message "The JWT secret should come from env var JWT_SECRET, not hardcoded"
|
|
554
552
|
```
|
|
555
553
|
|
|
556
|
-
The supervisor will autonomously:
|
|
554
|
+
The supervisor will autonomously: dispatch architect (handles triage + design) → dispatch developer for each sub-task (with internal review) → dispatch standalone reviewer if needed → done.
|
|
557
555
|
|
|
558
556
|
### Bug fix (supervisor)
|
|
559
557
|
|
|
@@ -584,7 +582,7 @@ neo run developer --prompt "Task 1: Create JWT middleware" --repo . --branch fea
|
|
|
584
582
|
neo run reviewer --prompt "Review PR on branch feat/auth" --repo . --branch feat/auth
|
|
585
583
|
|
|
586
584
|
# 5. Fix if needed
|
|
587
|
-
neo run
|
|
585
|
+
neo run developer --prompt "Fix issues found in review: missing token expiry check" --repo . --branch feat/auth
|
|
588
586
|
```
|
|
589
587
|
|
|
590
588
|
### Bug fix (direct dispatch)
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Built-in agent definitions for `@neotx/core`.
|
|
4
4
|
|
|
5
|
-
This package contains YAML configuration files and Markdown prompts that define the
|
|
5
|
+
This package contains YAML configuration files and Markdown prompts that define the 4 built-in agents used by the Neo orchestrator. It's a data package — no TypeScript, no runtime code.
|
|
6
6
|
|
|
7
7
|
## Contents
|
|
8
8
|
|
|
@@ -11,14 +11,10 @@ packages/agents/
|
|
|
11
11
|
├── agents/ # Agent YAML definitions
|
|
12
12
|
│ ├── architect.yml
|
|
13
13
|
│ ├── developer.yml
|
|
14
|
-
│ ├── fixer.yml
|
|
15
|
-
│ ├── refiner.yml
|
|
16
14
|
│ └── reviewer.yml
|
|
17
15
|
└── prompts/ # Markdown system prompts
|
|
18
16
|
├── architect.md
|
|
19
17
|
├── developer.md
|
|
20
|
-
├── fixer.md
|
|
21
|
-
├── refiner.md
|
|
22
18
|
└── reviewer.md
|
|
23
19
|
```
|
|
24
20
|
|
|
@@ -26,11 +22,9 @@ packages/agents/
|
|
|
26
22
|
|
|
27
23
|
| Agent | Model | Sandbox | Tools | Role |
|
|
28
24
|
|-------|-------|---------|-------|------|
|
|
29
|
-
| **architect** | opus | readonly | Read, Glob, Grep, WebSearch, WebFetch | Strategic planner.
|
|
30
|
-
| **developer** | opus | writable | Read, Write, Edit, Bash, Glob, Grep | Implementation worker. Executes atomic tasks from specs in isolated clones. |
|
|
31
|
-
| **
|
|
32
|
-
| **refiner** | opus | readonly | Read, Glob, Grep, WebSearch, WebFetch | Ticket quality evaluator. Assesses clarity and splits vague tickets into precise sub-tickets. |
|
|
33
|
-
| **reviewer** | sonnet | readonly | Read, Glob, Grep, Bash | Single-pass unified reviewer. Covers quality, security, performance, and test coverage in one sweep. Challenges by default — blocks on critical issues. |
|
|
25
|
+
| **architect** | opus | readonly | Read, Glob, Grep, WebSearch, WebFetch, Agent | Strategic planner. Triages requests, designs architecture, decomposes work into atomic tasks, and spawns subagents when needed. Never writes code. |
|
|
26
|
+
| **developer** | opus | writable | Read, Write, Edit, Bash, Glob, Grep, Agent | Implementation worker. Executes atomic tasks from specs in isolated clones. Performs self-review and spawns subagents for complex steps. |
|
|
27
|
+
| **reviewer** | sonnet | readonly | Read, Glob, Grep, Bash | Two-pass unified reviewer. Covers quality, security, performance, and test coverage. Challenges by default — blocks on critical issues. |
|
|
34
28
|
|
|
35
29
|
### Sandbox Modes
|
|
36
30
|
|
package/SUPERVISOR.md
CHANGED
|
@@ -6,49 +6,46 @@ This file contains domain-specific knowledge for the supervisor. Commands, heart
|
|
|
6
6
|
|
|
7
7
|
| Agent | Model | Mode | Use when |
|
|
8
8
|
|-------|-------|------|----------|
|
|
9
|
-
| `architect` | opus |
|
|
10
|
-
| `developer` | opus | writable |
|
|
11
|
-
| `fixer` | opus | writable | Fixing issues found by reviewer — targets root causes |
|
|
12
|
-
| `refiner` | opus | readonly | Evaluating ticket quality, splitting vague tickets |
|
|
9
|
+
| `architect` | opus | writable | Triage + design + write implementation plan to `.neo/specs/`. Spawns plan-reviewer subagent. Writes code in plans, NEVER modifies source files. |
|
|
10
|
+
| `developer` | opus | writable | Executes implementation plans step by step (plan mode) OR direct tasks (direct mode). Spawns spec-reviewer and code-quality-reviewer subagents. |
|
|
13
11
|
| `reviewer` | sonnet | readonly | Thorough single-pass review: quality, standards, security, perf, and coverage. Challenges by default — blocks on ≥1 CRITICAL or ≥3 WARNINGs |
|
|
14
12
|
| `scout` | opus | readonly | Autonomous codebase explorer. Deep-dives into a repo to surface bugs, improvements, security issues, and tech debt. Creates decisions for the user |
|
|
15
13
|
|
|
16
14
|
## Agent Output Contracts
|
|
17
15
|
|
|
18
|
-
|
|
16
|
+
Read agent output to decide next actions.
|
|
19
17
|
|
|
20
|
-
### architect → `
|
|
18
|
+
### architect → `plan_path` + `summary`
|
|
21
19
|
|
|
22
|
-
React to:
|
|
20
|
+
React to: dispatch `developer` with `--prompt "Execute the implementation plan at {plan_path}. Create a PR when all tasks pass."` on the same branch.
|
|
23
21
|
|
|
24
|
-
|
|
22
|
+
No more task-by-task dispatch from supervisor. The developer handles the full plan autonomously.
|
|
25
23
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
- `status: "
|
|
24
|
+
### developer → `status` + `branch_completion`
|
|
25
|
+
|
|
26
|
+
React to status (same as before):
|
|
27
|
+
- `status: "DONE"` + `PR_URL` → extract PR number, set ticket to CI pending, check CI at next heartbeat
|
|
28
|
+
- `status: "DONE"` without PR → mark ticket done
|
|
29
|
+
- `status: "DONE_WITH_CONCERNS"` → read concerns, evaluate impact. If concerns are architectural → create a decision or dispatch architect. If minor → mark done with note.
|
|
30
|
+
- `status: "BLOCKED"` → route via decision system. If autoDecide, answer directly. Otherwise wait for human.
|
|
31
|
+
- `status: "NEEDS_CONTEXT"` → provide the requested context and re-dispatch developer on same branch.
|
|
32
|
+
|
|
33
|
+
When `branch_completion` is present, supervisor decides:
|
|
34
|
+
- `recommendation: "pr"` + tests passing → create/push PR (most common)
|
|
35
|
+
- `recommendation: "keep"` → note in focus, revisit later
|
|
36
|
+
- `recommendation: "discard"` → requires supervisor confirmation before executing
|
|
37
|
+
- `recommendation: "push"` → push without PR (rare, for config/doc changes)
|
|
30
38
|
|
|
31
39
|
### reviewer → `verdict` + `issues[]`
|
|
32
40
|
|
|
33
41
|
The reviewer challenges by default. It blocks on any CRITICAL issue or ≥3 WARNINGs.
|
|
34
42
|
Expect `CHANGES_REQUESTED` more often than `APPROVED` — this is intentional.
|
|
35
43
|
|
|
36
|
-
|
|
37
|
-
- `verdict: "APPROVED"` → mark ticket done
|
|
38
|
-
- `verdict: "CHANGES_REQUESTED"` → check anti-loop guard, dispatch `fixer` with issues (include severity — fixer should prioritize CRITICALs first)
|
|
39
|
-
|
|
40
|
-
### fixer → `status` + `issues_fixed[]`
|
|
41
|
-
|
|
42
|
-
React to:
|
|
43
|
-
- `status: "FIXED"` → set ticket to review, re-dispatch `reviewer`
|
|
44
|
-
- `status: "PARTIAL"` or `"ESCALATED"` → evaluate remaining issues, escalate if needed
|
|
45
|
-
|
|
46
|
-
### refiner → `action` + `score`
|
|
44
|
+
Also check `spec_compliance` field. If `FAIL`, the code deviated from spec.
|
|
47
45
|
|
|
48
46
|
React to:
|
|
49
|
-
- `
|
|
50
|
-
- `
|
|
51
|
-
- `action: "escalate"` → mark ticket blocked, log questions
|
|
47
|
+
- `verdict: "APPROVED"` → mark ticket done
|
|
48
|
+
- `verdict: "CHANGES_REQUESTED"` → check anti-loop guard, re-dispatch `developer` with review feedback as context on same branch (include severity — developer should prioritize CRITICALs first)
|
|
52
49
|
|
|
53
50
|
### scout → `findings[]` + `decisions_created`
|
|
54
51
|
|
|
@@ -68,16 +65,15 @@ Use `--meta` for traceability and idempotency:
|
|
|
68
65
|
| Field | Required | Description |
|
|
69
66
|
|-------|----------|-------------|
|
|
70
67
|
| `ticketId` | always | Source ticket identifier for traceability |
|
|
71
|
-
| `stage` | always | Pipeline stage: `
|
|
68
|
+
| `stage` | always | Pipeline stage: `develop`, `review` |
|
|
72
69
|
| `prNumber` | if exists | GitHub PR number |
|
|
73
|
-
| `cycle` | fix stage | Fixer→review cycle count (anti-loop tracking) |
|
|
74
70
|
| `parentTicketId` | sub-tickets | Parent ticket ID for decomposed work |
|
|
75
71
|
|
|
76
72
|
### Branch & PR lifecycle
|
|
77
73
|
|
|
78
74
|
- `--branch` is **required for all agents**. Every session runs in an isolated clone on that branch.
|
|
79
75
|
- **develop**: pass `--branch feat/PROJ-42-description` to name the working branch.
|
|
80
|
-
- **review
|
|
76
|
+
- **review**: pass the same `--branch` and `prNumber` in `--meta`.
|
|
81
77
|
- On developer completion: extract `branch` and `prNumber` from `neo runs <runId>`, carry forward.
|
|
82
78
|
|
|
83
79
|
### Prompt writing
|
|
@@ -86,18 +82,25 @@ The `--prompt` is the agent's only context. It must be self-contained:
|
|
|
86
82
|
|
|
87
83
|
- **develop**: task description + acceptance criteria + instruction to create branch and PR
|
|
88
84
|
- **review**: PR number + branch name + what to review
|
|
89
|
-
- **fix**: PR number + branch name + specific issues to fix + instruction to push to existing branch
|
|
90
|
-
- **refine**: ticket title + description + any existing criteria
|
|
91
85
|
- **architect**: feature description + constraints + scope
|
|
92
86
|
|
|
93
87
|
### Examples
|
|
94
88
|
|
|
95
89
|
```bash
|
|
96
|
-
#
|
|
97
|
-
neo run
|
|
98
|
-
--repo /path/to/repo \
|
|
99
|
-
--
|
|
100
|
-
|
|
90
|
+
# architect (design + plan)
|
|
91
|
+
neo run architect --prompt "Design and plan: multi-tenant auth system" \
|
|
92
|
+
--repo /path/to/repo --branch feat/PROJ-99-auth \
|
|
93
|
+
--meta '{"ticketId":"PROJ-99","stage":"plan"}'
|
|
94
|
+
|
|
95
|
+
# developer with plan (after architect completes)
|
|
96
|
+
neo run developer --prompt "Execute the implementation plan at .neo/specs/PROJ-99-plan.md. Create a PR when all tasks pass." \
|
|
97
|
+
--repo /path/to/repo --branch feat/PROJ-99-auth \
|
|
98
|
+
--meta '{"ticketId":"PROJ-99","stage":"develop"}'
|
|
99
|
+
|
|
100
|
+
# developer direct (small task, no architect needed)
|
|
101
|
+
neo run developer --prompt "Fix: POST /api/users returns 500 when email contains '+'. Open a PR." \
|
|
102
|
+
--repo /path/to/repo --branch fix/PROJ-43-email \
|
|
103
|
+
--meta '{"ticketId":"PROJ-43","stage":"develop"}'
|
|
101
104
|
|
|
102
105
|
# review
|
|
103
106
|
neo run reviewer --prompt "Review PR #73 on branch feat/PROJ-42-add-auth." \
|
|
@@ -105,18 +108,6 @@ neo run reviewer --prompt "Review PR #73 on branch feat/PROJ-42-add-auth." \
|
|
|
105
108
|
--branch feat/PROJ-42-add-auth \
|
|
106
109
|
--meta '{"ticketId":"PROJ-42","stage":"review","prNumber":73}'
|
|
107
110
|
|
|
108
|
-
# fix
|
|
109
|
-
neo run fixer --prompt "Fix issues from review on PR #73: missing input validation on login endpoint. Push fixes to the existing branch." \
|
|
110
|
-
--repo /path/to/repo \
|
|
111
|
-
--branch feat/PROJ-42-add-auth \
|
|
112
|
-
--meta '{"ticketId":"PROJ-42","stage":"fix","prNumber":73,"cycle":1}'
|
|
113
|
-
|
|
114
|
-
# architect
|
|
115
|
-
neo run architect --prompt "Design decomposition for multi-tenant auth system" \
|
|
116
|
-
--repo /path/to/repo \
|
|
117
|
-
--branch feat/PROJ-99-multi-tenant-auth \
|
|
118
|
-
--meta '{"ticketId":"PROJ-99","stage":"refine"}'
|
|
119
|
-
|
|
120
111
|
# scout
|
|
121
112
|
neo run scout --prompt "Explore this repository and surface bugs, improvements, security issues, and tech debt. Create decisions for critical and high-impact findings." \
|
|
122
113
|
--repo /path/to/repo \
|
|
@@ -156,45 +147,39 @@ Skip silently and log: `neo log discovery "Skipping <finding> — covered by PR
|
|
|
156
147
|
|
|
157
148
|
| Condition | Action |
|
|
158
149
|
|-----------|--------|
|
|
159
|
-
| Bug + critical priority | Dispatch `developer`
|
|
160
|
-
| Clear criteria + small scope (<
|
|
161
|
-
| Complexity ≥
|
|
162
|
-
| Unclear criteria or vague scope | Dispatch `
|
|
150
|
+
| Bug + critical priority | Dispatch `developer` direct (hotfix) |
|
|
151
|
+
| Clear criteria + small scope (< 3 points) | Dispatch `developer` direct |
|
|
152
|
+
| Complexity ≥ 3 | Dispatch `architect` first → plan → dispatch `developer` with plan path |
|
|
153
|
+
| Unclear criteria or vague scope | Dispatch `architect` (handles triage via decision poll) |
|
|
163
154
|
| Proactive exploration / no specific ticket | Dispatch `scout` on target repo |
|
|
164
155
|
|
|
165
|
-
### 3. On
|
|
166
|
-
|
|
167
|
-
Parse the refiner's JSON output:
|
|
168
|
-
- `action: "pass_through"` → dispatch `developer` with `enriched_context`
|
|
169
|
-
- `action: "decompose"` → create sub-tickets from `sub_tickets[]`, dispatch `developer` for each
|
|
170
|
-
- `action: "escalate"` → update tracker → blocked
|
|
171
|
-
|
|
172
|
-
### 4. On Developer/Fixer Completion — with PR
|
|
156
|
+
### 3. On Developer Completion — with PR
|
|
173
157
|
|
|
174
158
|
1. Parse output for `PR_URL`, extract PR number.
|
|
175
|
-
2.
|
|
176
|
-
|
|
159
|
+
2. Handle by status:
|
|
160
|
+
- `status: "DONE"` → update tracker → CI pending.
|
|
161
|
+
- `status: "DONE_WITH_CONCERNS"` → read concerns, evaluate impact. If architectural → create a decision or dispatch architect. If minor → update tracker → CI pending, note concerns.
|
|
162
|
+
- `status: "BLOCKED"` → route via decision system. If autoDecide, answer directly. Otherwise wait for human.
|
|
163
|
+
- `status: "NEEDS_CONTEXT"` → provide the requested context and re-dispatch developer on same branch.
|
|
164
|
+
3. For CI pending tickets: check CI: `gh pr checks <prNumber> --repo <repository>`.
|
|
177
165
|
4. CI passed → update tracker → in review, dispatch `reviewer`.
|
|
178
|
-
5. CI failed →
|
|
166
|
+
5. CI failed → re-dispatch `developer` with CI error context on same branch.
|
|
179
167
|
6. CI pending → note in focus, check at next heartbeat.
|
|
180
168
|
|
|
181
|
-
###
|
|
169
|
+
### 4. On Developer Completion — no PR
|
|
182
170
|
|
|
183
|
-
|
|
171
|
+
- `status: "DONE"` → update tracker → done.
|
|
172
|
+
- `status: "DONE_WITH_CONCERNS"` → evaluate concerns, mark done with note if minor.
|
|
173
|
+
- `status: "BLOCKED"` → route via decision system.
|
|
174
|
+
- `status: "NEEDS_CONTEXT"` → provide context, re-dispatch developer.
|
|
184
175
|
|
|
185
|
-
###
|
|
176
|
+
### 5. On Review Completion
|
|
186
177
|
|
|
187
178
|
Parse reviewer's JSON output:
|
|
188
179
|
- `verdict: "APPROVED"` → update tracker → done.
|
|
189
|
-
- `verdict: "CHANGES_REQUESTED"` → check anti-loop guard → dispatch `
|
|
180
|
+
- `verdict: "CHANGES_REQUESTED"` → check anti-loop guard → re-dispatch `developer` with review feedback as context on same branch, or escalate.
|
|
190
181
|
|
|
191
|
-
###
|
|
192
|
-
|
|
193
|
-
Parse fixer's JSON output:
|
|
194
|
-
- `status: "FIXED"` → update tracker → in review, re-dispatch `reviewer`.
|
|
195
|
-
- `status: "ESCALATED"` → update tracker → blocked.
|
|
196
|
-
|
|
197
|
-
### 8. On Scout Completion
|
|
182
|
+
### 6. On Scout Completion
|
|
198
183
|
|
|
199
184
|
Parse scout's JSON output:
|
|
200
185
|
- For each finding with `decision_id`: wait for user decision at future heartbeat.
|
|
@@ -206,7 +191,7 @@ Parse scout's JSON output:
|
|
|
206
191
|
- User answers "no" → discard finding, no action
|
|
207
192
|
- Log `health_score` and `strengths` for project context.
|
|
208
193
|
|
|
209
|
-
###
|
|
194
|
+
### 7. On Agent Failure
|
|
210
195
|
|
|
211
196
|
Update tracker → abandoned. Log the failure reason.
|
|
212
197
|
|
|
@@ -217,9 +202,8 @@ ready → in progress → ci pending → in review → done
|
|
|
217
202
|
│ │ │
|
|
218
203
|
│ │ failure │ changes requested
|
|
219
204
|
│ ▼ ▼
|
|
220
|
-
│
|
|
221
|
-
│
|
|
222
|
-
│ └──→ in review (re-review)
|
|
205
|
+
│ developer ◄────────┘
|
|
206
|
+
│ re-dispatch
|
|
223
207
|
│
|
|
224
208
|
└──→ blocked (escalation/budget/anti-loop)
|
|
225
209
|
└──→ abandoned (terminal failure)
|
|
@@ -237,7 +221,7 @@ Infer missing fields before routing:
|
|
|
237
221
|
|
|
238
222
|
**Complexity (Fibonacci):**
|
|
239
223
|
- 1: typo, config, single-line — 2: single file, <50 lines — 3: 2-3 files (default)
|
|
240
|
-
-
|
|
224
|
+
- 3+: triggers architect first — 5: 3-5 files — 8: 5-8 files — 13: large feature — 21+: major
|
|
241
225
|
|
|
242
226
|
**Criteria** (when unset):
|
|
243
227
|
- Bugs: "The bug described in the title is fixed and does not regress"
|
|
@@ -246,6 +230,32 @@ Infer missing fields before routing:
|
|
|
246
230
|
|
|
247
231
|
**Priority** (when unset): `medium`
|
|
248
232
|
|
|
233
|
+
## Execution Strategy
|
|
234
|
+
|
|
235
|
+
When an architect completes:
|
|
236
|
+
|
|
237
|
+
1. Read `plan_path` from architect output.
|
|
238
|
+
2. Dispatch `developer` with the plan path on the same branch. The developer handles task ordering autonomously.
|
|
239
|
+
3. Post-completion: check CI, dispatch `reviewer` after CI passes.
|
|
240
|
+
4. Anti-loop guard: max 6 re-dispatch cycles per ticket.
|
|
241
|
+
|
|
242
|
+
## Decision Routing
|
|
243
|
+
|
|
244
|
+
When a pending decision arrives from an agent:
|
|
245
|
+
|
|
246
|
+
1. **Can you answer directly?** (strategic question, scope, priority)
|
|
247
|
+
→ `neo decision answer <id> <answer>`
|
|
248
|
+
|
|
249
|
+
2. **Needs codebase investigation?** (technical question about existing code)
|
|
250
|
+
→ Dispatch `scout` to investigate (already readonly)
|
|
251
|
+
→ Read run output → `neo decision answer <id>` with findings
|
|
252
|
+
|
|
253
|
+
3. **Needs human input?** (`autoDecide: false`, or genuinely uncertain)
|
|
254
|
+
→ Log and wait for human response
|
|
255
|
+
|
|
256
|
+
IMPORTANT: An agent is BLOCKED waiting on this decision.
|
|
257
|
+
Answer within 1–2 heartbeats. Stale decisions waste agent session budget.
|
|
258
|
+
|
|
249
259
|
## Idle Behavior
|
|
250
260
|
|
|
251
261
|
When the supervisor has **no events, no active runs, and no pending tasks**, it enters idle mode.
|
|
@@ -255,25 +265,22 @@ When the supervisor has **no events, no active runs, and no pending tasks**, it
|
|
|
255
265
|
1. **Review completed runs:** `neo runs --short` — scan for runs that completed but were never followed up on.
|
|
256
266
|
2. **Check for missed dispatches:**
|
|
257
267
|
- A `developer` run completed with a `PR_URL` but no `reviewer` was dispatched → dispatch `reviewer`.
|
|
258
|
-
- A `
|
|
259
|
-
-
|
|
260
|
-
-
|
|
261
|
-
- A `refiner` returned `decompose` but no `sub-tickets` were created (and/or no `developer` was dispatched) → create sub-tickets from `sub_tickets[]`, then dispatch one `developer` per sub-ticket.
|
|
262
|
-
- A `architect` returned `milestones[].tasks[]` but sub-tickets were never created → create them and dispatch.
|
|
268
|
+
- A `reviewer` returned `CHANGES_REQUESTED` but no `developer` was re-dispatched → re-dispatch `developer` with review feedback (check anti-loop guard first).
|
|
269
|
+
- An `architect` returned a `plan_path` but no `developer` was dispatched with it → dispatch `developer` with the plan path.
|
|
270
|
+
- Pending decisions not yet answered → check `neo decision list` and route appropriately.
|
|
263
271
|
3. **Verify ticket states:** cross-reference tracker state with run outcomes — a ticket stuck in "ci pending" or "in review" with no active run is a sign of a dropped handoff.
|
|
264
272
|
4. **If everything checks out:** do nothing. Wait for the next heartbeat or user input.
|
|
265
273
|
|
|
266
274
|
## Safety Guards
|
|
267
275
|
|
|
268
276
|
### Anti-Loop Guard
|
|
269
|
-
- Max **6**
|
|
277
|
+
- Max **6** developer re-dispatch cycles per ticket.
|
|
270
278
|
- At limit: escalate. Do NOT dispatch again.
|
|
271
279
|
|
|
272
280
|
### Escalation Policy
|
|
273
|
-
- If
|
|
281
|
+
- If developer reports `status: "BLOCKED"` or fails **3× on the same error type**: escalate immediately.
|
|
274
282
|
- Do NOT attempt a 4th variant.
|
|
275
283
|
|
|
276
284
|
### Budget Enforcement
|
|
277
285
|
- Check `neo cost --short` before every dispatch.
|
|
278
286
|
- Never dispatch if budget would be exceeded.
|
|
279
|
-
|
package/agents/architect.yml
CHANGED
|
@@ -1,11 +1,25 @@
|
|
|
1
1
|
name: architect
|
|
2
|
-
description: "
|
|
2
|
+
description: "Analyzes feature requests, designs architecture, and writes implementation plans to .neo/specs/. Spawns plan-reviewer subagent. Writes code in plans, NEVER modifies source files."
|
|
3
3
|
model: opus
|
|
4
4
|
tools:
|
|
5
5
|
- Read
|
|
6
|
+
- Write
|
|
7
|
+
- Edit
|
|
8
|
+
- Bash
|
|
6
9
|
- Glob
|
|
7
10
|
- Grep
|
|
8
11
|
- WebSearch
|
|
9
12
|
- WebFetch
|
|
10
|
-
|
|
13
|
+
- Agent
|
|
14
|
+
sandbox: writable
|
|
15
|
+
maxTurns: 100
|
|
11
16
|
prompt: ../prompts/architect.md
|
|
17
|
+
agents:
|
|
18
|
+
plan-reviewer:
|
|
19
|
+
description: "Review implementation plan for completeness, spec alignment, and buildability."
|
|
20
|
+
prompt: ../prompts/subagents/plan-reviewer.md
|
|
21
|
+
tools:
|
|
22
|
+
- Read
|
|
23
|
+
- Grep
|
|
24
|
+
- Glob
|
|
25
|
+
model: sonnet
|
package/agents/developer.yml
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
name: developer
|
|
2
|
-
description: "
|
|
2
|
+
description: "Executes implementation plans step by step or direct tasks in an isolated git clone. Spawns spec-reviewer and code-quality-reviewer subagents."
|
|
3
3
|
model: opus
|
|
4
4
|
tools:
|
|
5
5
|
- Read
|
|
@@ -8,5 +8,24 @@ tools:
|
|
|
8
8
|
- Bash
|
|
9
9
|
- Glob
|
|
10
10
|
- Grep
|
|
11
|
+
- Agent
|
|
11
12
|
sandbox: writable
|
|
13
|
+
maxTurns: 200
|
|
12
14
|
prompt: ../prompts/developer.md
|
|
15
|
+
agents:
|
|
16
|
+
spec-reviewer:
|
|
17
|
+
description: "Verify implementation matches task specification exactly. Use after completing each task to ensure nothing is missing or extra."
|
|
18
|
+
prompt: ../prompts/subagents/spec-reviewer.md
|
|
19
|
+
tools:
|
|
20
|
+
- Read
|
|
21
|
+
- Grep
|
|
22
|
+
- Glob
|
|
23
|
+
model: sonnet
|
|
24
|
+
code-quality-reviewer:
|
|
25
|
+
description: "Review code quality, patterns, and test coverage. Use ONLY after spec-reviewer approves."
|
|
26
|
+
prompt: ../prompts/subagents/code-quality-reviewer.md
|
|
27
|
+
tools:
|
|
28
|
+
- Read
|
|
29
|
+
- Grep
|
|
30
|
+
- Glob
|
|
31
|
+
model: sonnet
|
package/agents/reviewer.yml
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
name: reviewer
|
|
2
|
-
description: "
|
|
2
|
+
description: "Two-pass reviewer: spec compliance first, then code quality. Covers quality, standards, security, performance, and test coverage. Challenges by default — approves only when standards are met."
|
|
3
3
|
model: sonnet
|
|
4
4
|
tools:
|
|
5
5
|
- Read
|
|
@@ -7,4 +7,5 @@ tools:
|
|
|
7
7
|
- Grep
|
|
8
8
|
- Bash
|
|
9
9
|
sandbox: readonly
|
|
10
|
+
maxTurns: 30
|
|
10
11
|
prompt: ../prompts/reviewer.md
|
package/agents/scout.yml
CHANGED