Appearance
Agent catalog
Every file that ships in agents/ (13 spawnable agents and 3 audit-surface modules), with its tier, tool grant, and spawn source.
Quick reference
| Agent | Tier | Tools | Description |
|---|---|---|---|
np-plan-checker | opus | Read, Grep, Glob | Goal-backward verifier for a milestone plan. Reads M<NNN>-ROADMAP.md + every slice's S<NNN>-PLAN.md + UAT.md, returns YAML verdict (status: passed|issues_found + findings[]). Spawned by /np:plan-phase verification loop per D-15. |
np-planner | opus | Read, Write, Bash, Glob, Grep | Plans an entire milestone — breaking it down into slices (waves) and tasks (atomic units). Spawned by /np:plan-phase orchestrator. Writes M<NNN>-CONTEXT.md, M<NNN>-ROADMAP.md, M<NNN>-META.json at milestone level, plus S<NNN>-PLAN.md per slice with all its <task> blocks inline. |
np-architect | sonnet | Read, Write, Bash, Grep, Glob | Optional ADR/architecture-decision step between research and planning. Reads RESEARCH.md + CONTEXT.md + RULES.md and emits M<NNN>-ARCHITECTURE.md with module boundaries, data flow, and 3–7 ADR-style decisions. Read-only on source — writes ONE artifact under the milestone dir. |
np-build-fixer | sonnet | Read, Edit, Write, Bash, Grep, Glob | Reactive build/test failure resolver. Spawned by /np:execute-phase when a task's verification command fails. Reads the failing output + task files_modified + recent git diff, proposes minimal patches, runs verification again. Read/Edit/Write within files_modified scope only — never expands scope (D-04). |
np-codebase-documenter | sonnet | Read, Grep, Glob | Writes concise, accurate prose sections for codebase module docs in .nubos-pilot/codebase/modules/. Consumes structured facts from the deterministic parser and returns strict JSON — never invents symbols, deps, or behavior. |
np-critic | sonnet | Read, Write, Bash, Grep, Glob | Nubosloop critic for the per-task adversarial review. Spawned ONCE after np-executor (or np-build-fixer) commits a draft. Read-only on source, write-allowed for the critic-report file the orchestrator hands it. Reviews three orthogonal axes — style, tests, acceptance — writes the full findings JSON to disk and emits a tiny verdict envelope. ADR-0010 §Verdict-Only Contract (2026-05-05). |
np-critic-acceptance | sonnet | Read, Bash, Grep, Glob | Audit-surface module for the Acceptance axis of np-critic. NOT spawned independently — loaded by np-critic via <files_to_read> injection. Defines categories, severity rubric, and stop-conditions for per-success_criterion verdict, locked-decision conformance, scope-creep, stuck-detection, and infrastructure-mismatch. ADR-0010 §Single-Critic Revision 2026-05-05. |
np-critic-tests | sonnet | Read, Bash, Grep, Glob | Audit-surface module for the Tests axis of np-critic. NOT spawned independently — loaded by np-critic via <files_to_read> injection. Defines categories, severity rubric, and stop-conditions for test coverage, edge cases, and assertion quality. ADR-0010 §Single-Critic Revision 2026-05-05. |
np-executor | sonnet | Read, Write, Edit, Bash, Grep, Glob | Atomic-commit-per-task executor. Spawned per task by /np:execute-phase. Reads the task PLAN.md, edits exactly the files in frontmatter.files_modified, invokes commitTask helper. D-28/D-03. |
np-researcher | sonnet | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__, mcp__firecrawl__, mcp__exa__* | Phase-level technical researcher. Produces RESEARCH.md using web + MCP sources; falls back to local-only with ## Research Coverage annotation when WebFetch + Context7 are absent (D-21..D-23). |
np-researcher-reconciler | sonnet | Read, Write, Bash, Grep, Glob | Stage-2 reconciler for the researcher swarm (ADR-0018). Reads the k per-spawn outputs + the deterministic-merge proposal, classifies reasoning-trace agreement, surfaces contested decisions, writes the final M<NNN>-RESEARCH.md. READ-ONLY on inputs; single Write target. |
np-security-reviewer | sonnet | Read, Bash, Grep, Glob | Read-only post-execution security audit for a milestone. Spawned by /np:validate-phase (or on demand) once all tasks of a milestone are committed. Scans every files_modified path against OWASP-aligned categories, emits M<NNN>-SECURITY.md draft with Pass/Risk/Defer per finding. Detection-only — never edits source. |
np-verifier | sonnet | Read, Bash, Grep, Glob | Post-execution goal-backward verifier for a milestone. Reads M<NNN>-ROADMAP + every S<NNN>-PLAN/SUMMARY + every T<NNNN>-PLAN/SUMMARY + task commits, emits M<NNN>-VERIFICATION.md draft with Pass/Fail/Defer per SC and Needs-User-Confirm flag. |
np-critic-style | haiku | Read, Bash, Grep, Glob | Audit-surface module for the Style axis of np-critic. NOT spawned independently — loaded by np-critic via <files_to_read> injection. Defines categories, severity rubric, and stop-conditions for code style, naming conventions, dead code, and dangling threads. ADR-0010 §Single-Critic Revision 2026-05-05. |
np-nyquist-auditor | haiku | Read, Write, Bash, Grep, Glob | Nyquist validation auditor for a milestone — for each requirement in milestone scope, verifies at least one test observes the implementation directly. Scores COVERED/UNDER_SAMPLED/UNCOVERED. Writes M<NNN>-VALIDATION.md. Spawned by /np:validate-phase. |
np-sc-extractor | haiku | Read, Bash, Grep, Glob | Derives observable Success Criteria (SC-N) for a milestone from its goal, requirements, and captured decisions; persists them to roadmap.yaml via update-phase-meta. Spawned by /np:discuss-phase after the interview, before plan-phase. |
The table above is regenerated from
agents/*.mdfrontmatter byscripts/generate-docs.cjs. Per-agent prose below is hand-written — keep it in sync when you add or rename an agent.
Module files vs spawnable agents. Three rows in the table — np-critic-style, np-critic-tests, np-critic-acceptance — carry module: true in their frontmatter and are NOT spawnable agents. They are loaded via Read by the parent np-critic spawn (per the Single-Critic Revision (ADR-0010 §2026-05-05)). lib/agents.cjs::loadAgent rejects them for spawning, and loop-audit-tool-use --agent <module> is also rejected. The tier metadata on these rows is informational only (legacy from the deprecated 3-critic schwarm) — no spawn happens at that tier.
agents/ therefore ships 13 spawnable agents and 3 audit-surface modules (16 files total) since the addition of np-researcher-reconciler (ADR-0018).
Planning
np-planner — tier: opus
Tools: Read, Write, Bash, Glob, GrepSpawned by: /np:plan-phase <N> (standard / revision mode)
Plans an entire milestone: writes M<NNN>-ROADMAP.md, M<NNN>-META.json, and per slice S<NNN>-ASSESSMENT.md + S<NNN>-PLAN.md + S<NNN>-UAT.md. Each slice PLAN contains inline <task> blocks that the scaffolder turns into standalone T<NNNN>-PLAN.md files. Honors M<NNN>-CONTEXT.md locked decisions verbatim — never simplifies a D-XX to a "stub". Returns PHASE SPLIT RECOMMENDED to the orchestrator if the milestone is too large to fit every decision in one plan.
Handoff Protocol: reads handoffs addressed to np-planner at start of every plan run. May write to np-executor (scope nuances that don't fit in slice PLAN) or np-verifier (SC interpretation that matters at verification). Never silently ignores an executor-originated plan-flaw handoff — integrates or writes a return handoff explaining why.
np-plan-checker — tier: opus
Tools: Read, Grep, GlobSpawned by: /np:plan-phase verification loop
Adversarial reader of the milestone plan. Walks every slice PLAN goal-backward against ROADMAP success_criteria and per-slice UAT acceptance. Verifies task IDs match M<NNN>-S<NNN>-T<NNNN>, that tasks inside a slice are parallel-safe (no intra-slice depends_on), and that cross-slice deps flow forward only. Emits a single YAML verdict: status: passed | issues_found plus findings[]. Does not propose fixes.
np-researcher — tier: sonnet
Tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*Spawned by: /np:research-phase <N> (standalone), /np:plan-phase <N> (integrated)
Milestone-level technical researcher — Stage 1 of the swarm (ADR-0018). Under default k=3 mode, writes its output to .nubos-pilot/milestones/M<NNN>/research/spawn-<i>.md (one file per spawn), schema-bound by researcher-output (ADR-0017). Probes WebFetch + Context7 availability on startup; if both are absent, enters Offline-Confirm Protocol and produces a local-only output with a mandatory ## Research Coverage annotation listing what is local-only.
Reasoning Mandate. Every Decision / Risk / Pattern entry MUST carry a **Reasoning:** field documenting what was weighed, what was discarded, and why this conclusion. The reconciler uses these traces to detect groupthink (identical reasoning across spawns → confidence demoted) vs robust multi-path evidence (orthogonal reasoning → confidence promoted). output-lint check --schema researcher-output --enforce rejects spawns that omit the field.
Handoff Protocol: reads handoffs addressed to np-researcher at start. May write to np-verifier (evidence hints for known-hard SCs) or np-planner (cross-milestone traps — typically global, no --milestone).
np-researcher-reconciler — tier: sonnet
Tools: Read, Write, Bash, Grep, GlobSpawned by: /np:research-phase <N> (Stage 2, ADR-0018)
Reads all k per-spawn outputs + the deterministic mergeConsensus proposal, classifies each consensus decision's reasoning-trace agreement as orthogonal | overlapping | identical | unknown, surfaces every contested decision (a decision only one spawn proposed) in ## Contested Decisions with per-spawn verdicts + a documented Reconciler-Pick reason. Writes M<NNN>-RESEARCH.md (the consumed final artifact) schema-bound by research-final. READ-ONLY on inputs — never modifies per-spawn outputs, never edits source.
Verdict states:
clean—contested_count == 0ANDagreement_score >= 0.8AND no Unresolved entries.issues_flagged— contested decisions exist but each one picked with documented reasoning. Workflow continues; downstream consumers weight contested picks lower.needs_re_spawn— at least one Unresolved contested entry ORagreement_score < 0.5. The disagreement hard-gate (workflow Step 5.7) shows askuser with three options.
The output-lint check --schema research-final --enforce gate at workflow Step 5.6 rejects reconciler output that violates the schema; the agent re-spawns with the violation list as feedback.
np-architect — tier: sonnet
Tools: Read, Write, Bash, Grep, GlobSpawned by: /np:architect-phase <N> (optional, between research and planning)
Optional ADR step that consumes M<NNN>-RESEARCH.md + M<NNN>-CONTEXT.md + RULES.md and emits a single M<NNN>-ARCHITECTURE.md with module boundaries, data flow, and 3–7 ADR-style decisions (D-arch-N). Reads source/docs freely but writes exactly that one file — no source edits, no Edit tool. Skipped for purely additive milestones; required when CONTEXT marks architecture_review: required or RESEARCH flags ≥ 3 [ASSUMED] claims in the architecture-patterns dimension. The planner treats M<NNN>-ARCHITECTURE.md as an extension of CONTEXT — locked.
Handoff Protocol: reads handoffs addressed to np-architect. May write to np-planner for constraints the planner must respect verbatim (e.g. "all DB writes go through repository module X"). Stops with ## CONTEXT CONFLICT instead of writing the file when a decision would violate M<NNN>-CONTEXT.md or RULES.md.
np-codebase-documenter — tier: sonnet
Tools: Read, Bash, Grep, GlobSpawned by: /np:scan-codebase, /np:update-docs
Produces per-module skill-style documentation under .nubos-pilot/codebase/modules/. Every dev-agent (executor, planner, researcher, …) is instructed to read .nubos-pilot/codebase/INDEX.md + the relevant module doc before touching source, and to refresh after writing source.
np-sc-extractor — tier: haiku
Tools: Read, Bash, Grep, GlobSpawned by: /np:discuss-phase (after the interview, before /np:plan-phase)
Derives observable Success Criteria (SC-1, SC-2, …) for a milestone from its goal + requirements + freshly captured M<NNN>-CONTEXT.md, and persists them to roadmap.yaml via np-tools.cjs update-phase-meta --stdin. Non-interactive — never asks the user, never edits source. Reuses an existing success_criteria[] block verbatim when it still matches the goal+requirements; only adds/removes when the new context materially disagrees. Caps at 15 SCs (warns above that — a milestone too large for one SC list usually wants to be split).
Execution
np-executor — tier: sonnet
Tools: Read, Write, Edit, Bash, Grep, GlobSpawned by: /np:execute-phase (per task)
Atomic-commit-per-task executor. One task per spawn, one commit per task (ADR-0004). Reads the task's T<NNNN>-PLAN.md + the slice's S<NNN>-PLAN.md + the milestone's M<NNN>-CONTEXT.md. Edits files_modified verbatim — no auto-discovery, no scope expansion. Routes commits exclusively through np-tools.cjs commit-task <M-S-T> so the gitignore-guard runs.
Handoff Protocol: reads handoffs addressed to np-executor at start of every task. Writes handoffs only for genuine cross-phase signals — compromises for np-verifier, plan flaws for np-planner, shared-code traps for * (broadcast). Never spams the channel with routine work. Each task's commit-task / skip / park call also auto-re-renders the slice's TODO.md.
np-build-fixer — tier: sonnet
Tools: Read, Edit, Write, Bash, Grep, GlobSpawned by: /np:execute-phase — Nubosloop round ≥ 2
The Nubosloop spawns np-build-fixer automatically in round ≥ 2. Round 1 spawns np-executor; from round 2 on, every round spawns np-build-fixer instead with the prior critic findings and verify output appended (workflows/execute-phase.md Step 3). It is a fixed part of the loop, not an optional or manually-invoked agent.
Reactive patch-only agent. Classifies the failure (compile, lint, test, runtime, infra), locates the surface inside the task's files_modified, proposes the smallest patch that makes verify pass, and re-runs the verify command. Hard-capped at 3 attempts; on giving up, writes T<NNNN>-FIX-NOTES.md with the attempted fixes and a suspected root cause. Never expands files_modified (emits ## SCOPE EXPANSION REQUEST instead) and never commits — control returns to the loop so the D-03 atomic commit path stays the only commit site.
Handoff Protocol: reads handoffs addressed to np-build-fixer. May write to np-planner when a failure pattern repeats across tasks and signals a planning-level gap.
np-critic — tier: sonnet
Tools: Read, Write, Bash, Grep, GlobSpawned by: /np:execute-phase — Critic step of the Nubosloop, once per round after a verify-green executor
Per-task adversarial reviewer. Audits the executor's diff across three orthogonal axes (style, tests, acceptance) by Read-ing three audit-surface modules and emitting a single structured findings JSON. Per the Verdict-Only Contract (ADR-0010 §L5), the full findings JSON is Write-n to an orchestrator-supplied <report_path> and the spawn's final message is a small envelope ({verdict, blockers_count, report_path, run_id}) — keeps parent-context tokens bounded.
Write is permitted ONLY on the orchestrator-supplied <report_path>; touching anything else is a Layer-A bypass class. The post-critics gate refuses without a loop-audit-tool-use --agent np-critic stamp for the round (Layer-C).
See np-critic for the full contract; the three audit-surface modules are documented at np-critic-style, np-critic-tests, np-critic-acceptance.
np-verifier — tier: sonnet
Tools: Read, Bash, Grep, GlobSpawned by: /np:verify-work <N>
Post-execution goal-backward verifier — the twin of plan-checker, different timing. Reads the milestone's ROADMAP + CONTEXT, every slice's PLAN + SUMMARY, every task's PLAN + SUMMARY, and the task commits. Classifies each success_criterion as Pass / Fail / Defer / Needs-User-Confirm. Writes M<NNN>-VERIFICATION.md. Does not propose fixes, does not edit source.
Handoff Protocol: read-only. Reads handoffs addressed to np-verifier before classifying so executor-logged compromises flip what would otherwise read as Fail to Pass or Defer. Has no Write tool, so writing handoffs is impossible by construction — verifier is detection-only; findings land in M<NNN>-VERIFICATION.md, never in the handoff channel.
Review
np-nyquist-auditor — tier: haiku
Tools: Read, Write, Bash, Grep, GlobSpawned by: /np:validate-phase <N>
For each requirement in milestone scope, verifies at least one test observes the implementation directly. Scores COVERED / UNDER_SAMPLED / UNCOVERED per requirement. Writes M<NNN>-VALIDATION.md from templates/VALIDATION.md.
np-security-reviewer — tier: sonnet
Tools: Read, Bash, Grep, GlobSpawn site: idle, manually invokable. The agent definition ships in agents/np-security-reviewer.md. There is no dedicated /np:security-phase workflow today — operators spawn the agent directly with the milestone payload when an OWASP-aligned audit is wanted alongside /np:verify-work and /np:validate-phase.
Read-only post-execution OWASP audit. Walks the union of files_modified from every task in the milestone, scans 10 OWASP-aligned categories (Injection, Auth & Session, Secrets, Access Control, Crypto, SSRF / Open Redirect, Deserialization, File / Path, Logging, Dependencies), and emits M<NNN>-SECURITY.md with one block per finding classified as Pass / Risk / Defer. Cross-references RULES.md and M<NNN>-CONTEXT.md first — explicit authorization there neutralizes a generic finding. Detection-only by tool grant: no Write / Edit, never proposes patches inline (points at OWASP cheatsheets instead).
Handoff Protocol: reads handoffs addressed to np-security-reviewer. May write to np-planner when a finding suggests a planning-level constraint for the next milestone.
Frontmatter contract
Every agent file obeys the same contract:
yaml
---
name: <filename-stem>
description: <one-line summary>
tier: haiku | sonnet | opus
tools: Read, Write, Bash, Grep, …
color: <ui-hint>
---Forbidden fields: model, model_profile, hooks. Model resolution is tier-based and happens at spawn time via np-tools.cjs resolve-model; hooks are runtime-specific and live in the adapter layer.