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

package/README.md

@@ -0,0 +1,178 @@
+# @neotx/agents
+
+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.
+
+## Contents
+
+```
+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
+```
+
+## Built-in 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. |
+
+### Sandbox Modes
+
+- **readonly**: Agent can read files but cannot write. Safe for analysis tasks.
+- **writable**: Agent can read and write files. Used for implementation and fixes.
+
+### Model Selection
+
+- **opus**: Used for complex reasoning (architecture, security, implementation)
+- **sonnet**: Used for focused review tasks (quality, performance, coverage)
+
+## Creating Custom Agents
+
+Custom agents are defined in `.neo/agents/` in your project. You can create entirely new agents or extend built-in ones.
+
+### Agent YAML Schema
+
+```yaml
+name: my-agent                    # Required: unique identifier
+description: "What this agent does"  # Required for custom agents
+model: opus | sonnet | haiku      # Required for custom agents
+tools:                            # Required for custom agents
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - WebSearch
+  - WebFetch
+sandbox: writable | readonly      # Required for custom agents
+prompt: ../prompts/my-agent.md    # Path to system prompt (relative to YAML)
+```
+
+### Extending Built-in Agents
+
+Use `extends` to inherit from a built-in agent and override specific fields:
+
+```yaml
+name: my-developer
+extends: developer
+model: sonnet                     # Override: use sonnet instead of opus
+promptAppend: |
+  ## Additional Instructions
+  Always write tests before implementation.
+```
+
+When extending:
+- Unspecified fields inherit from the base agent
+- `prompt` replaces the base prompt entirely
+- `promptAppend` appends to the inherited prompt
+
+### The `$inherited` Token
+
+When extending an agent, you can add tools while keeping the inherited ones:
+
+```yaml
+name: research-developer
+extends: developer
+tools:
+  - $inherited      # Keep all tools from developer
+  - WebSearch       # Add web search capability
+  - WebFetch        # Add web fetch capability
+```
+
+Without `$inherited`, the tools list replaces the base entirely:
+
+```yaml
+name: minimal-developer
+extends: developer
+tools:
+  - Read            # Only these tools, not the inherited ones
+  - Edit
+```
+
+### Implicit Extension
+
+If your custom agent has the same name as a built-in, it implicitly extends it:
+
+```yaml
+# .neo/agents/developer.yml
+# No "extends:" needed — same name implies extends: developer
+name: developer
+model: sonnet                     # Override model
+promptAppend: |
+  Use the project's existing patterns.
+```
+
+## Prompts
+
+Each agent has a corresponding Markdown prompt in `prompts/`. The prompt defines:
+
+- The agent's role and responsibilities
+- Execution protocol
+- Output format expectations
+- Hard rules and constraints
+- Escalation conditions
+
+### Prompt Structure
+
+Prompts follow a consistent structure:
+
+```markdown
+# Agent Name
+
+One-sentence role definition.
+
+## Protocol
+Step-by-step execution protocol.
+
+## Output
+Expected JSON structure for agent output.
+
+## Escalation
+When to stop and report to the dispatcher.
+
+## Rules
+Non-negotiable constraints.
+```
+
+Runtime metadata (hooks, skills, memory, isolation) are injected by `@neotx/core` — not written in the prompt.
+
+### Referencing Prompts
+
+In agent YAML, reference prompts with a relative path:
+
+```yaml
+prompt: ../prompts/architect.md
+```
+
+The path is resolved relative to the YAML file's directory.
+
+## How @neotx/core Uses This Package
+
+The `@neotx/core` orchestrator:
+
+1. Loads all YAML files from `packages/agents/agents/` as built-in agents
+2. Loads all YAML files from `.neo/agents/` as custom agents
+3. Resolves extensions and merges configurations
+4. Reads and injects prompts into agent sessions
+Custom agents in `.neo/agents/` override or extend the built-ins from this package.
+
+## License
+
+MIT

package/SUPERVISOR.md

@@ -0,0 +1,282 @@
+# Supervisor — Domain Knowledge
+
+This file contains domain-specific knowledge for the supervisor. Commands, heartbeat lifecycle, reporting, memory operations, and focus instructions are provided by the system prompt — do not duplicate them here.
+
+## Available Agents
+
+| 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 |
+
+## Agent Output Contracts
+
+Each agent outputs structured JSON. Parse these to decide next actions.
+
+### architect → `design` + `milestones[].tasks[]`
+
+React to: create sub-tickets from `milestones[].tasks[]`, dispatch `developer` for each (respecting `depends_on` order).
+
+### developer → `status` + `PR_URL`
+
+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
+
+### 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[]`
+
+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
+
+### 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
+- MEDIUM/LOW findings (no decisions created) → log for reference, no action needed
+
+## Dispatch — `--meta` fields
+
+Use `--meta` for traceability and idempotency:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `ticketId` | always | Source ticket identifier for traceability |
+| `stage` | always | Pipeline stage: `refine`, `develop`, `review`, `fix` |
+| `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`.
+- 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
+
+### 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"}'
+
+# review
+neo run reviewer --prompt "Review PR #73 on branch feat/PROJ-42-add-auth." \
+  --repo /path/to/repo \
+  --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 \
+  --branch main \
+  --meta '{"stage":"scout"}'
+```
+
+## Protocol
+
+### 1. Ticket Pickup
+
+1. Query your tracker for ready tickets, sorted by priority.
+2. Check capacity: `neo runs --short` and `neo cost --short`.
+3. For each ticket (up to capacity):
+   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.
+
+### 2. Routing
+
+| 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` |
+| 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
+
+1. Parse output for `PR_URL`, extract PR number.
+2. Update tracker → CI pending.
+3. 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.
+6. CI pending → note in focus, check at next heartbeat.
+
+### 5. On Developer/Fixer Completion — no PR
+
+Update tracker → done.
+
+### 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.
+
+### 8. 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:
+  - `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
+
+Update tracker → abandoned. Log the failure reason.
+
+## Pipeline State Machine
+
+```
+ready → in progress → ci pending → in review → done
+             │             │            │
+             │             │ failure     │ changes requested
+             │             ▼            ▼
+             │          fixing ◄────────┘
+             │             │
+             │             └──→ in review (re-review)
+             │
+             └──→ blocked (escalation/budget/anti-loop)
+             └──→ abandoned (terminal failure)
+```
+
+## Self-Evaluation (Missing Ticket Fields)
+
+Infer missing fields before routing:
+
+**Type:**
+- "crash", "error", "broken", "fix", "regression" → `bug`
+- "add", "create", "implement", "build", "new" → `feature`
+- "refactor", "clean", "improve", "optimize" → `chore`
+- 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
+
+**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"
+
+**Priority** (when unset): `medium`
+
+## Idle Behavior — Scout Dispatch
+
+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"`
+
+## Safety Guards
+
+### Anti-Loop Guard
+- Max **6** fixer→review 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.
+- Do NOT attempt a 4th variant.
+
+### Budget Enforcement
+- Check `neo cost --short` before every dispatch.
+- Never dispatch if budget would be exceeded.
+

package/agents/developer.yml

@@ -1,5 +1,5 @@
 name: developer
-description: "Implementation worker. Executes atomic tasks from specs in isolated worktrees. Follows strict scope discipline."
+description: "Implementation worker. Executes atomic tasks from specs in isolated clones. Follows strict scope discipline."
 model: opus
 tools:
   - Read

package/agents/reviewer.yml

@@ -0,0 +1,10 @@
+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."
+model: sonnet
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+sandbox: readonly
+prompt: ../prompts/reviewer.md

package/agents/scout.yml

@@ -0,0 +1,12 @@
+name: scout
+description: "Autonomous codebase explorer. Deep-dives into a repository to surface bugs, improvements, security issues, tech debt, and optimization opportunities. Produces actionable decisions for the supervisor."
+model: opus
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - WebSearch
+  - WebFetch
+sandbox: readonly
+prompt: ../prompts/scout.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neotx/agents",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.21",
   "description": "Built-in agent definitions and prompts for @neotx/core",
   "type": "module",
   "license": "MIT",
@@ -12,7 +12,8 @@
   "files": [
     "agents",
     "prompts",
-    "workflows"
+    "SUPERVISOR.md",
+    "GUIDE.md"
   ],
   "keywords": [
     "ai-agents",