@neotx/agents 0.1.0-alpha.22 → 0.1.0-alpha.25

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,60 +6,111 @@ 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 |
-| `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 |
+| `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 two-pass review: spec compliance first (gate), then code quality. Challenges by default — blocks on ≥1 CRITICAL or ≥5 WARNINGs. |
+| `scout` | opus | readonly | Autonomous codebase explorer. Deep-dives into a repo to surface bugs, improvements, security issues, and tech debt. Creates decisions for CRITICAL/HIGH findings. Writes institutional memory. |
 
 ## 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 → approval decision (gate) → `plan_path` + `summary`
 
-React to: create sub-tickets from `milestones[].tasks[]`, dispatch `developer` for each (respecting `depends_on` order).
+The architect workflow is two-phase:
 
-### developer → `status` + `PR_URL`
+**Phase A — Design Gate:** Before writing any plan, the architect creates a blocking approval decision:
+```bash
+neo decision create "Design approval for {ticket-id}" --type approval --context "..." --wait --timeout 30m
+```
+The architect is **paused waiting for your response**. Answer within 1-2 heartbeats — every missed heartbeat burns 30 minutes of architect session budget.
 
 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
+- `approved` → architect writes plan, then report arrives
+- `approved_with_changes` → architect revises design, re-submits (max 2 cycles)
+- `rejected` → architect restarts design
 
-### reviewer → `verdict` + `issues[]`
+**Phase B — Plan Ready:** After design is approved, architect reports:
+- `plan_path` + `summary` → dispatch `developer` with `--prompt "Execute the implementation plan at {plan_path}. Create a PR when all tasks pass."` on the same branch.
 
-The reviewer challenges by default. It blocks on any CRITICAL issue or ≥3 WARNINGs.
-Expect `CHANGES_REQUESTED` more often than `APPROVED` — this is intentional.
+The developer handles the full plan autonomously — no task-by-task dispatch from supervisor.
 
-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)
+### developer → `status` + `branch_completion`
 
-### fixer → `status` + `issues_fixed[]`
+React to status:
+- `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 architectural → create a decision or dispatch architect. If minor → mark done with note.
+- `status: "BLOCKED"` → route via decision system. If you can answer directly (scope, priority, strategic question), do it. Otherwise wait for human.
+- `status: "NEEDS_CONTEXT"` → provide the requested context and re-dispatch developer on same branch.
 
-React to:
-- `status: "FIXED"` → set ticket to review, re-dispatch `reviewer`
-- `status: "PARTIAL"` or `"ESCALATED"` → evaluate remaining issues, escalate if needed
+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)
+
+### Crash Resumption Protocol
+
+When a developer run **fails** on a plan-mode task (run `status: "failed"`, error contains `error_max_turns` or any runtime crash):
+
+**Step 1 — Reconstruct completed tasks:**
+```bash
+# Read the neo logs for the failed run to find checkpoints
+neo logs <failedRunId> 2>&1 | grep "milestone"
+# Cross-check with git log on the branch
+git -C <repoPath> log --oneline <branch> 2>&1 | head -20
+```
 
-### refiner → `action` + `score`
+**Step 2 — Build resumption context:**
+From the logs, identify:
+- Which tasks have a "done — commit <sha>" milestone → completed
+- Which task has no milestone or an error → failed task
+
+**Step 3 — Relaunch with RESUMING FROM CRASH header:**
+```bash
+neo run developer \
+  --prompt "RESUMING FROM CRASH
+Previous run: <failedRunId>
+Completed tasks: T1 (commit abc1234), T2 (commit def5678)
+Failed at: T3 — error: <last error from logs>
+Resume: start from T3, skip completed tasks above.
+
+Original task:
+Execute the implementation plan at .neo/specs/<plan>.md. Create a PR when all tasks pass." \
+  --repo <repoPath> \
+  --branch <sameBranch> \
+  --meta '{"ticketId":"<id>","stage":"develop","resumedFrom":"<failedRunId>"}'
+```
+
+**Rules:**
+- Always use the **same branch** — completed commits are already there
+- Max 3 resumption attempts per plan — on 3rd failure, create a decision for human
+- Never resume if the branch has diverged (commits missing from git log) — create a decision instead
+
+### reviewer → `verdict` + `issues[]`
+
+The reviewer runs two passes: spec compliance first (fail = stop), then code quality. It challenges by default.
+
+Blocks on:
+- Any CRITICAL issue
+- ≥5 WARNINGs
+- `spec_compliance: "FAIL"` (always blocks, regardless of code quality)
 
 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, then spec deviations)
 
 ### scout → `findings[]` + `decisions_created`
 
 React to:
-- Parse `findings[]` — each has `severity`, `category`, `suggestion`, and optional `decision_id`
-- CRITICAL findings with `decision_id` → wait for user decision before acting
-- HIGH findings with `decision_id` → wait for user decision before acting
-- User answers "yes" on a decision → route the finding as a ticket (dispatch `developer` or `architect` based on `effort`)
-- User answers "later" → backlog the finding
-- User answers "no" → discard
+- Parse `findings[]` — each has `severity`, `category`, `suggestion`, `effort`, and optional `decision_id`
+- CRITICAL/HIGH findings with `decision_id` → wait for user decision before acting
+- User answers `"yes"` on a decision → **run pre-dispatch dedup check** (§2) then route as ticket
+- User answers `"later"` → backlog the finding
+- User answers `"no"` → discard
 - MEDIUM/LOW findings (no decisions created) → log for reference, no action needed
+- Log `health_score` and `strengths` for project context
 
 ## Dispatch — `--meta` fields
 
@@ -68,36 +119,43 @@ 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: `plan`, `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`.
+- **plan**: pass `--branch feat/PROJ-42-description` — architect commits the spec to this branch.
+- **develop**: pass the same `--branch` as architect used.
+- **review**: pass the same `--branch` and `prNumber` in `--meta`.
 - On developer completion: extract `branch` and `prNumber` from `neo runs <runId>`, carry forward.
 
 ### Prompt writing
 
 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
+- **developer**: task description + acceptance criteria + instruction to create branch and PR (or plan path for plan mode)
+- **reviewer**: PR number + branch name + what to review
 
 ### 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 +163,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 \
@@ -124,6 +170,32 @@ neo run scout --prompt "Explore this repository and surface bugs, improvements,
   --meta '{"stage":"scout"}'
 ```
 
+### Task/Run Linkage — Mandatory Protocol
+
+Every dispatch follows this sequence:
+
+```bash
+# 1. Create or identify the task
+neo task create --scope /path/to/repo --priority high --initiative auth-v2 "T1: Implement JWT middleware"
+# → returns: mem_abc123
+
+# 2. Dispatch the run
+neo run developer --prompt "..." --repo /path --branch feat/auth --meta '{"ticketId":"T1","stage":"develop"}'
+# → returns: run-uuid-here
+
+# 3. Link run to task immediately
+neo task update mem_abc123 --status in_progress
+# (use --context "neo runs run-uuid-here" when neo task supports it)
+```
+
+**On run completion:**
+```bash
+neo task update mem_abc123 --status done       # if run succeeded
+neo task update mem_abc123 --status blocked    # if run failed
+```
+
+**Never dispatch without a task. Never leave a failed run's task as `in_progress`.**
+
 ## Protocol
 
 ### 1. Ticket Pickup
@@ -134,9 +206,10 @@ neo run scout --prompt "Explore this repository and surface bugs, improvements,
    a. Read full ticket details.
    b. Self-evaluate missing fields (see below).
    c. Resolve target repository.
-   d. Route the ticket.
-   e. Update tracker → in progress.
-   f. **Yield.** Completion arrives at a future heartbeat.
+   d. **Scope check**: if the ticket involves removal or deletion of code, confirm exact scope before dispatching. If ambiguous, create a decision: "Should I delete ONLY X, or also Y?"
+   e. Route the ticket.
+   f. Update tracker → in progress.
+   g. **Yield.** Completion arrives at a future heartbeat.
 
 ### 2. Routing
 
@@ -156,57 +229,65 @@ Skip silently and log: `neo log discovery "Skipping <finding> — covered by PR
 
 | 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 → design gate → plan → dispatch `developer` with plan path |
+| Unclear criteria or vague scope | Dispatch `architect` (handles triage via decision poll) |
+| Deletion / large removal | Create scope decision first, then dispatch `developer` direct |
 | Proactive exploration / no specific ticket | Dispatch `scout` on target repo |
 
-### 3. On Refiner Completion
+### 3. On Architect Design Gate
+
+When architect creates an approval decision (`--type approval --wait`):
+
+1. Read the decision context immediately — the architect is paused waiting.
+2. Evaluate: does the proposed design match the ticket's intent? Are the components and scope reasonable?
+3. **Can you approve directly?** (most common — if the approach is reasonable and in scope)
+   → `neo decision answer <id> approved`
+4. **Need changes?** → `neo decision answer <id> "approved_with_changes: <specific changes needed>"`
+5. **Fundamentally wrong approach?** → `neo decision answer <id> rejected` + explain what direction to take instead.
 
-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
+Do NOT dispatch follow-up agents until the architect reports `plan_path`.
 
-### 4. On Developer/Fixer Completion — with PR
+### 4. 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.
+   - `status: "NEEDS_CONTEXT"` → provide context, 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
+### 5. 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
 
 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
-
-Parse fixer's JSON output:
-- `status: "FIXED"` → update tracker → in review, re-dispatch `reviewer`.
-- `status: "ESCALATED"` → update tracker → blocked.
+- `verdict: "CHANGES_REQUESTED"` → check anti-loop guard → re-dispatch `developer` with review feedback as context on same branch (include spec deviations + CRITICAL issues + WARNING count), or escalate.
 
-### 8. On Scout Completion
+### 7. 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.
+- User answers `"yes"` on a decision:
+  - **Run pre-dispatch dedup check** (§2) before dispatching.
   - `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
+- 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
+### 8. On Agent Failure
 
 Update tracker → abandoned. Log the failure reason.
 
@@ -217,12 +298,14 @@ 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)
+
+architect path:
+ready → design gate (--wait decision) → plan written → in progress → ...
 ```
 
 ## Self-Evaluation (Missing Ticket Fields)
@@ -233,47 +316,165 @@ Infer missing fields before routing:
 - "crash", "error", "broken", "fix", "regression" → `bug`
 - "add", "create", "implement", "build", "new" → `feature`
 - "refactor", "clean", "improve", "optimize" → `chore`
+- "remove", "delete", "cleanup" → `chore` (requires scope confirmation — see §1d)
 - Unclear → `feature`
 
 **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"
 - Features: derive from title
 - Chores: "Code is cleaned up without breaking existing behavior"
+- Deletions: "ONLY the named subsystem is removed. Nothing adjacent is deleted."
 
 **Priority** (when unset): `medium`
 
+## 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, design approval)
+   → `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 may be BLOCKED waiting on this decision (especially architect with `--wait`).
+Answer within 1-2 heartbeats. Stale decisions waste agent session budget.
+
+## Memory Usage
+
+Use `neo memory write` to capture stable facts that would change how future agents approach work on this repo.
+
+Write memories when:
+- A scout or developer reveals a non-obvious constraint not in docs (e.g., "build must pass locally before push — CI runs compiled output only")
+- A developer or reviewer hits the same issue twice (→ write a `procedure` memory with the fix)
+- A user provides feedback that affects future dispatches (→ write a `feedback` memory with scope)
+- A design decision locks in a pattern that future architects should know (→ write a `fact` memory)
+
+```bash
+neo memory write --type fact --scope <repo-path> "<stable truth>"
+neo memory write --type procedure --scope <repo-path> "<step-by-step how-to>"
+neo memory write --type feedback --scope <repo-path> "<recurring complaint or preference>"
+neo memory write --type focus --expires 2h "<current working context>"
+```
+
+Do NOT memorize: file paths, general best practices, obvious conventions, anything in README or package.json.
+
 ## Idle Behavior
 
 When the supervisor has **no events, no active runs, and no pending tasks**, it enters idle mode.
 
-**Do not dispatch new agents proactively.** Instead, use idle time to audit past work and catch dropped tasks:
+**Do not dispatch new agents proactively** unless there are active **directives** (see below). 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 `fixer` run completed with `status: "FIXED"` but no re-review was dispatched → dispatch `reviewer`.
-   - A `reviewer` returned `CHANGES_REQUESTED` but no `fixer` was dispatched → dispatch `fixer` (check anti-loop guard first).
-   - A `refiner` returned `pass_through` but no `developer` was dispatched → dispatch `developer` with `enriched_context`.
-   - 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.
-   - A `architect` returned `milestones[].tasks[]` but sub-tickets were never created → create them and dispatch.
+   - 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.
+4. **If everything checks out and no active directives:** do nothing. Wait for the next heartbeat or user input.
+
+## Directives
+
+Directives are persistent standing instructions for idle time. They tell the supervisor what to do when otherwise idle.
+
+### Managing Directives
+
+```bash
+# Create a directive (default: indefinite)
+neo directive create "launch scout and implement findings" --trigger idle
+
+# Create a time-bounded directive
+neo directive create "run tests on all repos" --trigger idle --duration "2h"
+neo directive create "check for PRs needing review" --trigger idle --duration "until midnight"
+
+# List all directives
+neo directive list
+
+# Toggle a directive off/on
+neo directive toggle <id>
+
+# Delete a directive
+neo directive delete <id>
+```
+
+### Trigger Types
+
+| Trigger | When it fires |
+|---------|---------------|
+| `idle` | No events, no active runs, no pending tasks |
+| `startup` | Supervisor starts |
+| `shutdown` | Supervisor stops |
+
+### Idle Directive Execution
+
+When idle and there are active directives:
+
+1. Read the list of active directives (sorted by priority descending).
+2. For each directive, check if execution is feasible (budget, repo availability).
+3. Execute the highest-priority feasible directive.
+4. Log the action: `neo log action "executed directive: <action>"`.
+5. Update the directive's `lastTriggeredAt` timestamp.
+
+### Duration Formats
+
+- **Shorthand:** `2h`, `30m`, `7d`
+- **Natural:** `for 2 hours`, `for 30 minutes`, `for 7 days`
+- **Until time:** `until midnight`, `until 18:00`
+- **Indefinite:** `indefinitely` or omit `--duration`
+
+### Example Directives
+
+```bash
+# Proactive exploration
+neo directive create "launch scout and implement high-severity findings" \
+  --trigger idle --priority 5 --description "Continuous improvement"
+
+# Background maintenance
+neo directive create "run tests on all repos and fix failures" \
+  --trigger idle --priority 3 --duration "for 8 hours"
+
+# Time-boxed campaign
+neo directive create "update dependencies in all repos" \
+  --trigger idle --priority 10 --duration "until midnight"
+```
+
+### Cleanup
+
+Directives that expired more than 24 hours ago are automatically removed during compaction heartbeats.
 
 ## 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.
 
+### Scope Guard
+- For deletion or large removal tasks: always confirm exact scope before dispatch.
+- "Remove X" means ONLY X — never adjacent systems unless explicitly stated.
+- When in doubt: create a decision with boundary options before dispatching.
+
 ### Budget Enforcement
 - Check `neo cost --short` before every dispatch.
 - Never dispatch if budget would be exceeded.
-