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

package/README.md

@@ -0,0 +1,266 @@
+# @neotx/agents
+
+Built-in agent definitions and workflow templates for `@neotx/core`.
+
+This package contains YAML configuration files and Markdown prompts that define the 9 built-in agents and 5 workflows 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-coverage.yml
+│   ├── reviewer-perf.yml
+│   ├── reviewer-quality.yml
+│   ├── reviewer-security.yml
+│   └── reviewer.yml
+├── prompts/          # Markdown system prompts
+│   └── *.md
+└── workflows/        # Workflow YAML definitions
+    ├── feature.yml
+    ├── hotfix.yml
+    ├── refine.yml
+    ├── review-fast.yml
+    └── review.yml
+```
+
+## 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-quality** | sonnet | readonly | Read, Glob, Grep, Bash | Code quality reviewer. Catches bugs and DRY violations. Approves by default. |
+| **reviewer-security** | opus | readonly | Read, Glob, Grep, Bash | Security auditor. Flags directly exploitable vulnerabilities. Approves by default. |
+| **reviewer-perf** | sonnet | readonly | Read, Glob, Grep, Bash | Performance reviewer. Flags N+1 queries and O(n²) on unbounded data. Approves by default. |
+| **reviewer-coverage** | sonnet | readonly | Read, Glob, Grep, Bash | Test coverage reviewer. Recommends missing tests. Never blocks merge. |
+| **reviewer** | sonnet | readonly | Read, Glob, Grep, Bash | Single-pass unified reviewer. Covers all 4 lenses in one sweep. Lightweight alternative to parallel review. |
+
+### 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)
+
+## Built-in Workflows
+
+### feature
+
+Full development cycle: plan, implement, review, and fix.
+
+```yaml
+steps:
+  plan:
+    agent: architect
+    sandbox: readonly
+  implement:
+    agent: developer
+    dependsOn: [plan]
+  review:
+    agent: reviewer-quality
+    dependsOn: [implement]
+    sandbox: readonly
+  fix:
+    agent: fixer
+    dependsOn: [review]
+    condition: "output(review).hasIssues == true"
+```
+
+### review
+
+Parallel 4-lens code review. All reviewers run concurrently.
+
+```yaml
+steps:
+  quality:
+    agent: reviewer-quality
+    sandbox: readonly
+  security:
+    agent: reviewer-security
+    sandbox: readonly
+  perf:
+    agent: reviewer-perf
+    sandbox: readonly
+  coverage:
+    agent: reviewer-coverage
+    sandbox: readonly
+```
+
+### review-fast
+
+Single-pass lightweight review. One agent covers all 4 lenses — ideal for small PRs or budget-constrained runs.
+
+```yaml
+steps:
+  review:
+    agent: reviewer
+    sandbox: readonly
+```
+
+### hotfix
+
+Fast-track single-agent implementation. Skips planning for urgent fixes.
+
+```yaml
+steps:
+  implement:
+    agent: developer
+```
+
+### refine
+
+Ticket evaluation and decomposition for backlog grooming.
+
+```yaml
+steps:
+  evaluate:
+    agent: refiner
+    sandbox: readonly
+```
+
+## 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
+- Workflow and 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
+5. Loads workflows from `packages/agents/workflows/` and `.neo/workflows/`
+
+Custom agents in `.neo/agents/` override or extend the built-ins from this package.
+
+## License
+
+MIT

package/SUPERVISOR.md

@@ -0,0 +1,258 @@
+# 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.
+
+## Mindset
+
+- **Action-driven.** Dispatch actions, update state, yield. Never poll or wait.
+- **Event-reactive.** Run completions arrive as events at your next heartbeat. React then.
+- **Single source of truth.** All ticket state lives in your tracker. Query before acting, update immediately.
+
+## 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 |
+
+## 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
+
+## 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"}'
+```
+
+## 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` |
+
+### 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 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`
+
+## 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.
+
+## Rules
+
+1. **Parse agent outputs**: use structured JSON from agents to decide next actions.
+2. **Never modify code** — that is the agents' job.
+3. **Update tracker immediately**: on every state transition, no batching.
+4. **Refiner first**: when in doubt about ticket clarity.
+5. **Self-evaluate**: infer missing fields before routing.
+6. **Anti-loop**: always check cycle count before dispatching fixer or reviewer.
+7. **Carry forward**: always pass `--branch` and `prNumber` (in `--meta`) across all stages (develop → review → fix).
+8. **Track cost**: accumulate per ticket in focus.
+9. **Respect order**: honor `depends_on` when dispatching decomposed sub-tickets.
+
+## Memory Store
+
+Memory is managed via `neo memory`. Facts, procedures, and episodes persist in SQLite with **local semantic search** (all-MiniLM-L6-v2 embeddings via sqlite-vec). When agents are dispatched, the most relevant memories are automatically retrieved and injected into their prompts — no manual selection needed.
+
+### Commands
+```bash
+neo memory write --type fact --scope /path "Stable fact about repo"
+neo memory write --type focus --expires 2h "Current working context"
+neo memory write --type procedure --scope /path "How to do X"
+neo memory forget <id>
+neo memory search "keyword"          # semantic search across all memories
+neo memory list --type fact
+```
+
+### Writing good memories
+Write clear, descriptive content — memories are matched semantically, not by keywords. Good: "Uses Prisma ORM with PostgreSQL for all database access". Bad: "Prisma + PG".
+
+### Guidelines
+- **Facts**: stable truths about repos (stack, conventions, patterns)
+- **Focus**: ephemeral working context (expires automatically)
+- **Episodes**: auto-created on run completion — do not write manually
+- Use `neo log` for real-time TUI output, `neo memory write` for persistent knowledge
+- Use `notes/` for detailed multi-page plans and checklists

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/package.json

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