Agents

Subagents are the workhorse of nubos-pilot. Workflows orchestrate; agents read, write, and reason. Every agent is a single Markdown file with a fixed frontmatter contract and a free-form body.

The frontmatter contract (D-09)

---
name: <filename-stem>           # required, must equal the filename
description: <one-line summary> # required
tier: haiku | sonnet | opus     # required
tools: Read, Write, Bash, Grep  # required
color: <ui-hint>                # optional
---

Validation lives in lib/agents.cjs.validateAgentFrontmatter() and runs four gates in strict order:

1. REQUIRED — every required field non-empty.
2. FORBIDDEN — no field in {model, model_profile, hooks} may appear.
3. TIER_ENUM — tier must be one of the three allowed values.
4. Name match — frontmatter name must equal the filename stem.

First violation throws a NubosPilotError with a stable code; the remaining gates short-circuit. There is no caching: loadAgent() re-reads the file on every call so author edits are picked up immediately.

See the full reference for error codes, finding categories, and rationale.

Why no model / model_profile field?

Concrete model selection is tier-based. Embedding a literal model id in agent frontmatter:

• breaks portability across runtimes (Claude Code ≠ Codex ≠ Gemini ≠ OpenCode),
• bypasses the central Tier × Profile resolver in np-tools.cjs resolve-model,
• couples agent definitions to model-name churn that the resolver was built to absorb.

The resolver is consulted by the workflow at spawn time. The agent file itself never names a model.

Why no hooks field?

Hooks are runtime-specific syntax. Claude Code's hook format is not Codex's is not Gemini's. The portable agent contract stays clean by deferring lifecycle wiring to the runtime adapter layer in lib/runtime/.

Tier enum

Tier	Used for
opus	Goal-backward decomposition, adversarial review, decision-fidelity (planner, plan-checker, code-reviewer, security-auditor, eval-planner, framework-selector)
sonnet	Wide-context synthesis, execution, verification (researcher, executor, verifier, code-fixer, ai-researcher, ui-researcher, domain-researcher)
haiku	Bounded checks, classifications, audits (ui-checker, ui-auditor, eval-auditor, nyquist-auditor)

Tier assignments for the canonical three (planner, plan-checker, researcher) are pinned by ROADMAP SC-4 (D-13) and cannot be changed without an ADR.

Spawn flow

A workflow spawns an agent through whatever mechanism the host runtime exposes (Claude's Task tool, Codex equivalents, …). The orchestrator hands the agent:

• a <files_to_read> block enumerating every input path,
• the relevant CONTEXT.md decisions (D-01..D-NN),
• task-specific parameters via the agent's prompt body.

Agents are forbidden from spawning other agents. The orchestration graph is one level deep by design — no fan-out chains, no recursive agent trees.

The agent catalog

Seventeen subagents ship in agents/. See the catalog for the full list with tier, tools and spawn-source.

Mandatory initial read

Every agent body opens with this guard:

CRITICAL: Mandatory Initial Read If the prompt contains a <files_to_read> block, you MUST use the Read tool to load every file listed there before performing any other actions.

This is non-negotiable: it is what makes orchestrator-supplied context actually reach the agent. An agent that skips this step will reason from prior assumption and the verifier will catch it.