@neotx/agents 0.1.0-alpha.21 → 0.1.0-alpha.24

package/GUIDE.md

@@ -17,7 +17,7 @@ The supervisor is NOT a chatbot. It's an event-driven heartbeat loop that:
 - Dispatches the right agents in the right order
 - Monitors progress and reacts to completions/failures
 - Persists memory across sessions — it learns your codebase over time
-- Handles the full lifecycle: refine → architect → develop → review → fix → done
+- Handles the full lifecycle: architect (triage + design) → develop (self-review) → review (if needed) → done
 
 ```bash
 # Start the supervisor (background daemon)
@@ -31,7 +31,7 @@ neo supervise --message "Implement user authentication with JWT. Create login/re
 #   2. Dispatches architect if design is needed
 #   3. Dispatches developer for each task
 #   4. Dispatches reviewer to review PRs
-#   5. Dispatches fixer if issues are found
+#   5. Re-dispatches developer if issues are found
 #   6. Reports back via activity log
 
 # Check supervisor status
@@ -103,8 +103,6 @@ neo mcp add notion    # requires NOTION_TOKEN env var
 | `developer` | opus | writable | Implementing code changes, bug fixes, new features |
 | `architect` | opus | readonly | Designing systems, planning features, decomposing work |
 | `reviewer` | sonnet | readonly | Code review — blocks on ≥1 CRITICAL or ≥3 WARNINGs |
-| `fixer` | opus | writable | Fixing issues found by reviewer — targets root causes |
-| `refiner` | opus | readonly | Evaluating ticket quality, splitting vague tickets |
 
 **Custom agents:** Drop a YAML file in `.neo/agents/` to extend built-in agents:
 
@@ -349,7 +347,7 @@ neo decision pending
 # User answers
 neo decision answer dec_x7k9m2 hotfix
 
-# Supervisor receives the answer and dispatches fixer agent with hotfix priority
+# Supervisor receives the answer and re-dispatches developer with hotfix priority
 ```
 
 ### neo webhooks — Event notifications
@@ -553,7 +551,7 @@ neo cost --short
 neo supervise --message "The JWT secret should come from env var JWT_SECRET, not hardcoded"
 ```
 
-The supervisor will autonomously: refine the task if vague → dispatch architect for design → dispatch developer for each sub-task → dispatch reviewer → dispatch fixer if issues → report completion.
+The supervisor will autonomously: dispatch architect (handles triage + design) → dispatch developer for each sub-task (with internal review) → dispatch standalone reviewer if needed → done.
 
 ### Bug fix (supervisor)
 
@@ -584,7 +582,7 @@ neo run developer --prompt "Task 1: Create JWT middleware" --repo . --branch fea
 neo run reviewer --prompt "Review PR on branch feat/auth" --repo . --branch feat/auth
 
 # 5. Fix if needed
-neo run fixer --prompt "Fix issues: missing token expiry check" --repo . --branch feat/auth
+neo run developer --prompt "Fix issues found in review: missing token expiry check" --repo . --branch feat/auth
 ```
 
 ### Bug fix (direct dispatch)

package/README.md

@@ -2,7 +2,7 @@
 
 Built-in agent definitions for `@neotx/core`.
 
-This package contains YAML configuration files and Markdown prompts that define the 5 built-in agents used by the Neo orchestrator. It's a data package — no TypeScript, no runtime code.
+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.
 
 ## Contents
 
@@ -11,14 +11,10 @@ packages/agents/
 ├── agents/           # Agent YAML definitions
 │   ├── architect.yml
 │   ├── developer.yml
-│   ├── fixer.yml
-│   ├── refiner.yml
 │   └── reviewer.yml
 └── prompts/          # Markdown system prompts
     ├── architect.md
     ├── developer.md
-    ├── fixer.md
-    ├── refiner.md
     └── reviewer.md
 ```
 
@@ -26,11 +22,9 @@ packages/agents/
 
 | Agent | Model | Sandbox | Tools | Role |
 |-------|-------|---------|-------|------|
-| **architect** | opus | readonly | Read, Glob, Grep, WebSearch, WebFetch | Strategic planner. Analyzes features, designs architecture, decomposes work into atomic tasks. Never writes code. |
-| **developer** | opus | writable | Read, Write, Edit, Bash, Glob, Grep | Implementation worker. Executes atomic tasks from specs in isolated clones. |
-| **fixer** | opus | writable | Read, Write, Edit, Bash, Glob, Grep | Auto-correction agent. Fixes issues found by reviewers. Targets root causes, not symptoms. |
-| **refiner** | opus | readonly | Read, Glob, Grep, WebSearch, WebFetch | Ticket quality evaluator. Assesses clarity and splits vague tickets into precise sub-tickets. |
-| **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. |
+| **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. |
+| **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. |
+| **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. |
 
 ### Sandbox Modes
 

package/SUPERVISOR.md

@@ -6,49 +6,46 @@ This file contains domain-specific knowledge for the supervisor. Commands, heart
 
 | Agent | Model | Mode | Use when |
 |-------|-------|------|----------|
-| `architect` | opus | readonly | Designing systems, planning features, decomposing work |
-| `developer` | opus | writable | Implementing code changes, bug fixes, new features |
-| `fixer` | opus | writable | Fixing issues found by reviewer — targets root causes |
-| `refiner` | opus | readonly | Evaluating ticket quality, splitting vague tickets |
+| `architect` | opus | writable | Triage + design + write implementation plan to `.neo/specs/`. Spawns plan-reviewer subagent. Writes code in plans, NEVER modifies source files. |
+| `developer` | opus | writable | Executes implementation plans step by step (plan mode) OR direct tasks (direct mode). Spawns spec-reviewer and code-quality-reviewer subagents. |
 | `reviewer` | sonnet | readonly | Thorough single-pass review: quality, standards, security, perf, and coverage. Challenges by default — blocks on ≥1 CRITICAL or ≥3 WARNINGs |
 | `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 |
 
 ## Agent Output Contracts
 
-Each agent outputs structured JSON. Parse these to decide next actions.
+Read agent output to decide next actions.
 
-### architect → `design` + `milestones[].tasks[]`
+### architect → `plan_path` + `summary`
 
-React to: create sub-tickets from `milestones[].tasks[]`, dispatch `developer` for each (respecting `depends_on` order).
+React to: dispatch `developer` with `--prompt "Execute the implementation plan at {plan_path}. Create a PR when all tasks pass."` on the same branch.
 
-### developer → `status` + `PR_URL`
+No more task-by-task dispatch from supervisor. The developer handles the full plan autonomously.
 
-React to:
-- `status: "completed"` + `PR_URL` → extract PR number, set ticket to CI pending, check CI at next heartbeat
-- `status: "completed"` without PR → mark ticket done
-- `status: "failed"` or `"escalated"` → mark ticket abandoned, log reason
+### developer → `status` + `branch_completion`
+
+React to status (same as before):
+- `status: "DONE"` + `PR_URL` → extract PR number, set ticket to CI pending, check CI at next heartbeat
+- `status: "DONE"` without PR → mark ticket done
+- `status: "DONE_WITH_CONCERNS"` → read concerns, evaluate impact. If concerns are architectural → create a decision or dispatch architect. If minor → mark done with note.
+- `status: "BLOCKED"` → route via decision system. If autoDecide, answer directly. Otherwise wait for human.
+- `status: "NEEDS_CONTEXT"` → provide the requested context and re-dispatch developer on same branch.
+
+When `branch_completion` is present, supervisor decides:
+- `recommendation: "pr"` + tests passing → create/push PR (most common)
+- `recommendation: "keep"` → note in focus, revisit later
+- `recommendation: "discard"` → requires supervisor confirmation before executing
+- `recommendation: "push"` → push without PR (rare, for config/doc changes)
 
 ### reviewer → `verdict` + `issues[]`
 
 The reviewer challenges by default. It blocks on any CRITICAL issue or ≥3 WARNINGs.
 Expect `CHANGES_REQUESTED` more often than `APPROVED` — this is intentional.
 
-React to:
-- `verdict: "APPROVED"` → mark ticket done
-- `verdict: "CHANGES_REQUESTED"` → check anti-loop guard, dispatch `fixer` with issues (include severity — fixer should prioritize CRITICALs first)
-
-### fixer → `status` + `issues_fixed[]`
+Also check `spec_compliance` field. If `FAIL`, the code deviated from spec.
 
 React to:
-- `status: "FIXED"` → set ticket to review, re-dispatch `reviewer`
-- `status: "PARTIAL"` or `"ESCALATED"` → evaluate remaining issues, escalate if needed
-
-### refiner → `action` + `score`
-
-React to:
-- `action: "pass_through"` → dispatch `developer` with enriched context
-- `action: "decompose"` → create sub-tickets from `sub_tickets[]`, dispatch in order
-- `action: "escalate"` → mark ticket blocked, log questions
+- `verdict: "APPROVED"` → mark ticket done
+- `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)
 
 ### scout → `findings[]` + `decisions_created`
 
@@ -68,16 +65,15 @@ Use `--meta` for traceability and idempotency:
 | Field | Required | Description |
 |-------|----------|-------------|
 | `ticketId` | always | Source ticket identifier for traceability |
-| `stage` | always | Pipeline stage: `refine`, `develop`, `review`, `fix` |
+| `stage` | always | Pipeline stage: `develop`, `review` |
 | `prNumber` | if exists | GitHub PR number |
-| `cycle` | fix stage | Fixer→review cycle count (anti-loop tracking) |
 | `parentTicketId` | sub-tickets | Parent ticket ID for decomposed work |
 
 ### Branch & PR lifecycle
 
 - `--branch` is **required for all agents**. Every session runs in an isolated clone on that branch.
 - **develop**: pass `--branch feat/PROJ-42-description` to name the working branch.
-- **review/fix**: pass the same `--branch` and `prNumber` in `--meta`.
+- **review**: pass the same `--branch` and `prNumber` in `--meta`.
 - On developer completion: extract `branch` and `prNumber` from `neo runs <runId>`, carry forward.
 
 ### Prompt writing
@@ -86,18 +82,25 @@ The `--prompt` is the agent's only context. It must be self-contained:
 
 - **develop**: task description + acceptance criteria + instruction to create branch and PR
 - **review**: PR number + branch name + what to review
-- **fix**: PR number + branch name + specific issues to fix + instruction to push to existing branch
-- **refine**: ticket title + description + any existing criteria
 - **architect**: feature description + constraints + scope
 
 ### Examples
 
 ```bash
-# develop
-neo run developer --prompt "Implement user auth flow. Criteria: login with email/password, JWT tokens, refresh flow. Open a PR when done." \
-  --repo /path/to/repo \
-  --branch feat/PROJ-42-add-auth \
-  --meta '{"ticketId":"PROJ-42","stage":"develop"}'
+# architect (design + plan)
+neo run architect --prompt "Design and plan: multi-tenant auth system" \
+  --repo /path/to/repo --branch feat/PROJ-99-auth \
+  --meta '{"ticketId":"PROJ-99","stage":"plan"}'
+
+# developer with plan (after architect completes)
+neo run developer --prompt "Execute the implementation plan at .neo/specs/PROJ-99-plan.md. Create a PR when all tasks pass." \
+  --repo /path/to/repo --branch feat/PROJ-99-auth \
+  --meta '{"ticketId":"PROJ-99","stage":"develop"}'
+
+# developer direct (small task, no architect needed)
+neo run developer --prompt "Fix: POST /api/users returns 500 when email contains '+'. Open a PR." \
+  --repo /path/to/repo --branch fix/PROJ-43-email \
+  --meta '{"ticketId":"PROJ-43","stage":"develop"}'
 
 # review
 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." \
   --branch feat/PROJ-42-add-auth \
   --meta '{"ticketId":"PROJ-42","stage":"review","prNumber":73}'
 
-# fix
-neo run fixer --prompt "Fix issues from review on PR #73: missing input validation on login endpoint. Push fixes to the existing branch." \
-  --repo /path/to/repo \
-  --branch feat/PROJ-42-add-auth \
-  --meta '{"ticketId":"PROJ-42","stage":"fix","prNumber":73,"cycle":1}'
-
-# architect
-neo run architect --prompt "Design decomposition for multi-tenant auth system" \
-  --repo /path/to/repo \
-  --branch feat/PROJ-99-multi-tenant-auth \
-  --meta '{"ticketId":"PROJ-99","stage":"refine"}'
-
 # scout
 neo run scout --prompt "Explore this repository and surface bugs, improvements, security issues, and tech debt. Create decisions for critical and high-impact findings." \
   --repo /path/to/repo \
@@ -140,58 +131,67 @@ neo run scout --prompt "Explore this repository and surface bugs, improvements,
 
 ### 2. Routing
 
+**Pre-dispatch dedup check (MANDATORY before every `developer` dispatch):**
+
+```bash
+# 1. Check for open PRs on the same topic
+gh pr list --repo <repo> --search "<2-3 keywords from finding>" --state open --json number,title
+# → If a similar PR is OPEN: skip dispatch, add a comment on the existing PR instead
+
+# 2. Check for recently merged fixes
+gh pr list --repo <repo> --search "<2-3 keywords>" --state merged --limit 5 --json number,title,mergedAt
+# → If a similar fix was merged in the past 7 days: skip dispatch, the issue is already resolved
+```
+
+Skip silently and log: `neo log discovery "Skipping <finding> — covered by PR #<N>"`.
+
 | Condition | Action |
 |-----------|--------|
-| Bug + critical priority | Dispatch `developer` directly (hotfix) |
-| Clear criteria + small scope (< 5 points) | Dispatch `developer` |
-| Complexity ≥ 5 | Dispatch `architect` first |
-| Unclear criteria or vague scope | Dispatch `refiner` |
+| Bug + critical priority | Dispatch `developer` direct (hotfix) |
+| Clear criteria + small scope (< 3 points) | Dispatch `developer` direct |
+| Complexity ≥ 3 | Dispatch `architect` first → plan → dispatch `developer` with plan path |
+| Unclear criteria or vague scope | Dispatch `architect` (handles triage via decision poll) |
 | Proactive exploration / no specific ticket | Dispatch `scout` on target repo |
 
-### 3. On Refiner Completion
-
-Parse the refiner's JSON output:
-- `action: "pass_through"` → dispatch `developer` with `enriched_context`
-- `action: "decompose"` → create sub-tickets from `sub_tickets[]`, dispatch `developer` for each
-- `action: "escalate"` → update tracker → blocked
-
-### 4. On Developer/Fixer Completion — with PR
+### 3. On Developer Completion — with PR
 
 1. Parse output for `PR_URL`, extract PR number.
-2. Update tracker → CI pending.
-3. Check CI: `gh pr checks <prNumber> --repo <repository>`.
+2. Handle by status:
+   - `status: "DONE"` → update tracker → CI pending.
+   - `status: "DONE_WITH_CONCERNS"` → read concerns, evaluate impact. If architectural → create a decision or dispatch architect. If minor → update tracker → CI pending, note concerns.
+   - `status: "BLOCKED"` → route via decision system. If autoDecide, answer directly. Otherwise wait for human.
+   - `status: "NEEDS_CONTEXT"` → provide the requested context and re-dispatch developer on same branch.
+3. For CI pending tickets: check CI: `gh pr checks <prNumber> --repo <repository>`.
 4. CI passed → update tracker → in review, dispatch `reviewer`.
-5. CI failed → update tracker → fixing, dispatch `fixer` with CI error context.
+5. CI failed → re-dispatch `developer` with CI error context on same branch.
 6. CI pending → note in focus, check at next heartbeat.
 
-### 5. On Developer/Fixer Completion — no PR
+### 4. On Developer Completion — no PR
 
-Update tracker → done.
+- `status: "DONE"` → update tracker → done.
+- `status: "DONE_WITH_CONCERNS"` → evaluate concerns, mark done with note if minor.
+- `status: "BLOCKED"` → route via decision system.
+- `status: "NEEDS_CONTEXT"` → provide context, re-dispatch developer.
 
-### 6. On Review Completion
+### 5. On Review Completion
 
 Parse reviewer's JSON output:
 - `verdict: "APPROVED"` → update tracker → done.
-- `verdict: "CHANGES_REQUESTED"` → check anti-loop guard → dispatch `fixer` with `issues[]`, or escalate.
-
-### 7. On Fixer Completion
+- `verdict: "CHANGES_REQUESTED"` → check anti-loop guard → re-dispatch `developer` with review feedback as context on same branch, or escalate.
 
-Parse fixer's JSON output:
-- `status: "FIXED"` → update tracker → in review, re-dispatch `reviewer`.
-- `status: "ESCALATED"` → update tracker → blocked.
-
-### 8. On Scout Completion
+### 6. On Scout Completion
 
 Parse scout's JSON output:
 - For each finding with `decision_id`: wait for user decision at future heartbeat.
 - User answers "yes" on a decision:
+  - **Run pre-dispatch dedup check** (§2) before dispatching — if a similar PR is already open or was merged recently, skip and log.
   - `effort: "XS" | "S"` → dispatch `developer` with finding as ticket
   - `effort: "M" | "L"` → dispatch `architect` for design first
 - User answers "later" → log to backlog, no dispatch
 - User answers "no" → discard finding, no action
 - Log `health_score` and `strengths` for project context.
 
-### 9. On Agent Failure
+### 7. On Agent Failure
 
 Update tracker → abandoned. Log the failure reason.
 
@@ -202,9 +202,8 @@ ready → in progress → ci pending → in review → done
              │             │            │
              │             │ failure     │ changes requested
              │             ▼            ▼
-             │          fixing ◄────────┘
-             │             │
-             │             └──→ in review (re-review)
+             │       developer ◄────────┘
+             │       re-dispatch
              │
              └──→ blocked (escalation/budget/anti-loop)
              └──→ abandoned (terminal failure)
@@ -222,7 +221,7 @@ Infer missing fields before routing:
 
 **Complexity (Fibonacci):**
 - 1: typo, config, single-line — 2: single file, <50 lines — 3: 2-3 files (default)
-- 5+: triggers architect first — 8: 5-8 files — 13: large feature — 21+: major
+- 3+: triggers architect first — 5: 3-5 files — 8: 5-8 files — 13: large feature — 21+: major
 
 **Criteria** (when unset):
 - Bugs: "The bug described in the title is fixed and does not regress"
@@ -231,52 +230,57 @@ Infer missing fields before routing:
 
 **Priority** (when unset): `medium`
 
-## Idle Behavior — Scout Dispatch
+## Execution Strategy
+
+When an architect completes:
+
+1. Read `plan_path` from architect output.
+2. Dispatch `developer` with the plan path on the same branch. The developer handles task ordering autonomously.
+3. Post-completion: check CI, dispatch `reviewer` after CI passes.
+4. Anti-loop guard: max 6 re-dispatch cycles per ticket.
+
+## Decision Routing
+
+When a pending decision arrives from an agent:
+
+1. **Can you answer directly?** (strategic question, scope, priority)
+   → `neo decision answer <id> <answer>`
+
+2. **Needs codebase investigation?** (technical question about existing code)
+   → Dispatch `scout` to investigate (already readonly)
+   → Read run output → `neo decision answer <id>` with findings
+
+3. **Needs human input?** (`autoDecide: false`, or genuinely uncertain)
+   → Log and wait for human response
+
+IMPORTANT: An agent is BLOCKED waiting on this decision.
+Answer within 1–2 heartbeats. Stale decisions waste agent session budget.
+
+## Idle Behavior
 
 When the supervisor has **no events, no active runs, and no pending tasks**, it enters idle mode.
 
-Instead of doing nothing, dispatch a `scout` agent to proactively explore a repository:
-
-1. **Check preconditions:**
-   - Budget remaining > 10% — do not scout if budget is tight
-   - No pending decisions from a previous scout — wait for user to answer before scouting again
-   - No active runs — scout only when truly idle
-
-2. **Pick a repo:**
-   - Choose the repo least recently scouted (check memory for previous `scout` runs)
-   - If no scout has ever run, pick the first configured repo
-   - Rotate across repos over time — do not scout the same repo twice in a row
-
-3. **Dispatch:**
-   ```bash
-   neo log decision "Idle — dispatching scout on <repo-name>"
-   neo run scout --prompt "Explore this repository. Surface bugs, improvements, security issues, and tech debt. Create decisions for critical and high-impact findings." \
-     --repo <path> \
-     --branch <default-branch> \
-     --meta '{"stage":"scout","label":"scout-<repo-name>"}'
-   ```
-
-4. **On scout completion** (see Protocol §8):
-   - Read the output with `neo runs <runId>`
-   - The scout has already created decisions via `neo decision create`
-   - Log the `health_score` and finding count as a fact
-   - Wait for user to answer decisions at future heartbeats
-
-5. **Frequency guard:**
-   - Max ONE scout per repo per 24h — do not re-scout a repo that was scouted today
-   - Write a fact after each scout: `neo memory write --type fact --scope <repo> "Last scouted: <date>, health: <score>/10, <N> findings"`
+**Do not dispatch new agents proactively.** Instead, use idle time to audit past work and catch dropped tasks:
+
+1. **Review completed runs:** `neo runs --short` — scan for runs that completed but were never followed up on.
+2. **Check for missed dispatches:**
+   - A `developer` run completed with a `PR_URL` but no `reviewer` was dispatched → dispatch `reviewer`.
+   - A `reviewer` returned `CHANGES_REQUESTED` but no `developer` was re-dispatched → re-dispatch `developer` with review feedback (check anti-loop guard first).
+   - An `architect` returned a `plan_path` but no `developer` was dispatched with it → dispatch `developer` with the plan path.
+   - Pending decisions not yet answered → check `neo decision list` and route appropriately.
+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.
+4. **If everything checks out:** do nothing. Wait for the next heartbeat or user input.
 
 ## Safety Guards
 
 ### Anti-Loop Guard
-- Max **6** fixer→review cycles per ticket.
+- Max **6** developer re-dispatch cycles per ticket.
 - At limit: escalate. Do NOT dispatch again.
 
 ### Escalation Policy
-- If fixer reports `status: "ESCALATED"` or fails **3× on the same error type**: escalate immediately.
+- If developer reports `status: "BLOCKED"` or fails **3× on the same error type**: escalate immediately.
 - Do NOT attempt a 4th variant.
 
 ### Budget Enforcement
 - Check `neo cost --short` before every dispatch.
 - Never dispatch if budget would be exceeded.
-

package/agents/architect.yml

@@ -1,11 +1,25 @@
 name: architect
-description: "Strategic planner and decomposer. Analyzes features, designs architecture, creates roadmaps, and decomposes work into atomic tasks. Never writes code."
+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."
 model: opus
 tools:
   - Read
+  - Write
+  - Edit
+  - Bash
   - Glob
   - Grep
   - WebSearch
   - WebFetch
-sandbox: readonly
+  - Agent
+sandbox: writable
+maxTurns: 100
 prompt: ../prompts/architect.md
+agents:
+  plan-reviewer:
+    description: "Review implementation plan for completeness, spec alignment, and buildability."
+    prompt: ../prompts/subagents/plan-reviewer.md
+    tools:
+      - Read
+      - Grep
+      - Glob
+    model: sonnet

package/agents/developer.yml

@@ -1,5 +1,5 @@
 name: developer
-description: "Implementation worker. Executes atomic tasks from specs in isolated clones. Follows strict scope discipline."
+description: "Executes implementation plans step by step or direct tasks in an isolated git clone. Spawns spec-reviewer and code-quality-reviewer subagents."
 model: opus
 tools:
   - Read
@@ -8,5 +8,24 @@ tools:
   - Bash
   - Glob
   - Grep
+  - Agent
 sandbox: writable
+maxTurns: 200
 prompt: ../prompts/developer.md
+agents:
+  spec-reviewer:
+    description: "Verify implementation matches task specification exactly. Use after completing each task to ensure nothing is missing or extra."
+    prompt: ../prompts/subagents/spec-reviewer.md
+    tools:
+      - Read
+      - Grep
+      - Glob
+    model: sonnet
+  code-quality-reviewer:
+    description: "Review code quality, patterns, and test coverage. Use ONLY after spec-reviewer approves."
+    prompt: ../prompts/subagents/code-quality-reviewer.md
+    tools:
+      - Read
+      - Grep
+      - Glob
+    model: sonnet

package/agents/reviewer.yml

@@ -1,5 +1,5 @@
 name: reviewer
-description: "Thorough single-pass code reviewer. Covers quality, standards, security, performance, and test coverage. Challenges code by default — approves only when standards are met."
+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."
 model: sonnet
 tools:
   - Read
@@ -7,4 +7,5 @@ tools:
   - Grep
   - Bash
 sandbox: readonly
+maxTurns: 30
 prompt: ../prompts/reviewer.md

package/agents/scout.yml

@@ -9,4 +9,5 @@ tools:
   - WebSearch
   - WebFetch
 sandbox: readonly
+maxTurns: 50
 prompt: ../prompts/scout.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neotx/agents",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.24",
   "description": "Built-in agent definitions and prompts for @neotx/core",
   "type": "module",
   "license": "MIT",