Agents and skills

Nauro bundles two distinct artifact types. Subagents are Claude Code roles materialized as ~/.claude/agents/<name>.md files with inline frontmatter (name / description / tools / model).

Skills are SKILL.md files materialized under ~/.claude/skills/<name>/, with per-surface equivalents for Cursor and Codex.

• There are exactly four bundled subagents, defined by AGENT_NAMES = ("nauro-planner", "nauro-executor", "nauro-reviewer", "nauro-tech-lead") in agents/__init__.py.
• There are exactly four bundled skills, named in skills/__init__.py (SkillName and SKILL_DESCRIPTIONS): nauro-adopt, nauro-ship-task, nauro-handoff, nauro-context. nauro-adopt is always installed (SKILL_NAMES); the other three are opt-in (OPT_IN_SKILL_NAMES).
• Subagents are all model: opus per their frontmatter, and each declares a restricted tools: allowlist that includes Nauro's MCP tools under both the mcp__claude_ai_Nauro__* (cloud connector) and mcp__nauro__* (local stdio) prefixes.
• What makes the subagents load-bearing is that they call Nauro's MCP decision tools by design (check_decision, get_decision, propose_decision, and others). The personal-subagent path (@planner / @executor / @reviewer without the nauro- prefix) is explicitly not a substitute, because it does not wire the doctrine gates.

# agents/__init__.py
AGENT_NAMES: tuple[str, ...] = (
    "nauro-planner",
    "nauro-executor",
    "nauro-reviewer",
    "nauro-tech-lead",
)

# cli/commands/setup.py
SKILL_NAMES: tuple[str, ...] = ("nauro-adopt",)
OPT_IN_SKILL_NAMES: tuple[str, ...] = ("nauro-ship-task", "nauro-handoff", "nauro-context")

Source: packages/nauro/src/nauro/agents/__init__.py (AGENT_NAMES, render_agent); packages/nauro/src/nauro/skills/__init__.py (SKILL_DESCRIPTIONS, SkillName, render_skill); packages/nauro/src/nauro/cli/commands/setup.py (SKILL_NAMES, OPT_IN_SKILL_NAMES).

The planner plans changes; it does not edit files. Its frontmatter description: classifies doctrine risk GREEN/AMBER/RED via Nauro, writes a structured plan, drafts supersedes when proposals contradict active doctrine, and records new decisions before handoff.

It returns a plan; it does not edit files. Bash is for read-only investigation only (git log, grep, ls, gh view), never for writes.

• Before any tool calls it restates the intent in one sentence and asks if the paraphrase reveals ambiguity. Step 1 is doctrine triage: it calls check_decision with the proposed approach and classifies the response.
• GREEN: no related decisions, or clearly off-topic ones (spot-check the top one or two via get_decision).
• AMBER: adjacent decisions that touch the same surface area, name the same dependency, or share keywords but do not directly contradict (get_decision on every one; spot-check adjacent areas via search_decisions).
• RED: at least one active decision directly contradicts, OR the proposal would supersede an active decision (get_decision on every one, read in full).
• The verdict goes in the plan as a one-line header before "Why": the verdict word plus the comma-separated decision numbers it touches, so the reader sees the doctrine cost upfront.
• On RED it drafts the supersede by default (title, rationale, what is being replaced, what is being rejected) at the top of the plan. It may refuse to draft only under all four "decision-spam" criteria: the related decision was filed within the last 7 days, at confidence: high, the proposal restates an alternative explicitly named-and-rejected in that decision's rejected field, and the proposal carries no new evidence. The user can override the refusal by asking for the draft anyway.
• The plan follows the PR-template shape: DOCTRINE verdict line / Why / Approach / What changes / What's deferred / Test plan. When AMBER or RED, 2-3 alternatives with concrete tradeoffs are mandatory and the user picks before commit; when GREEN, alternatives are at the planner's discretion.
• It files via propose_decision only after the user agrees with the direction (operation add / update / supersede; prefer add when uncertain; update and supersede provide affected_decision_id). It never drafts implementation code.
• Fail-safe: if check_decision is unreachable it must NOT infer a verdict from git log or first-principles and call it GREEN. It stamps the header DOCTRINE: PROVISIONAL — check_decision unreachable and hands the decision to proceed back to the parent.
• It will not read credential or token files (~/.claude/.credentials.json, .env, *.pem, key caches) during investigation; they are never load-bearing for a plan.

# Verbatim @nauro-planner frontmatter, with the
# "Use proactively..." sentence elided as "...":
---
name: nauro-planner
description: Use to plan a non-trivial change before any code is written.
  Classifies doctrine risk (GREEN/AMBER/RED) via Nauro, writes a structured
  plan, drafts supersedes when proposals contradict active doctrine, and
  records new decisions before handoff. ... Returns a plan; does not edit files.
tools: Read, Grep, Glob, WebSearch, WebFetch, Bash,
  mcp__claude_ai_Nauro__check_decision, mcp__claude_ai_Nauro__propose_decision,
  mcp__claude_ai_Nauro__get_decision, mcp__claude_ai_Nauro__search_decisions,
  mcp__claude_ai_Nauro__list_decisions, mcp__claude_ai_Nauro__list_projects,
  mcp__nauro__check_decision, ... mcp__nauro__list_projects
model: opus
---

# The doctrine-verdict header the planner emits (derived from
# the plan shape in nauro-planner.md Step 4)
DOCTRINE: AMBER — informed by decisions 42, 57

Why: ...
Approach: ...  (2-3 alternatives with tradeoffs, mandatory on AMBER/RED)
What changes: ...
What's deferred: ...
Test plan: ...

Source: packages/nauro/src/nauro/agents/nauro-planner.md (frontmatter, "Required steps before returning", "Hard rules").

The executor implements an already-approved plan. It has full edit/write/test access: its tools: are Read, Write, Edit, Grep, Glob, Bash, NotebookEdit, WebSearch, WebFetch, TodoWrite, plus the read-only Nauro MCP tools (check_decision, get_decision, search_decisions, list_decisions under both prefixes).

It does not invent scope, refactor outside the plan, or add unrequested features.

• Test-first discipline: for a new function, command, or behavior it writes a failing test first, then implements to green. This is skipped for pure refactors, bug-fix-is-the-repro cases, and one-line changes.
• Local completion only. It explicitly does NOT git push, does NOT run gh pr create, and does NOT mark the task complete. It runs lint (ruff format + ruff check, checking the project Makefile for the canonical command), runs the relevant test suite, keeps cross-package dependency pins in sync (regenerate every affected manifest in the same commit), commits (default one commit per PR, subject under 72 chars, imperative voice, body with a Why paragraph and a decision-reference footer if any), and drafts the PR description in the project's template shape (Why / Approach / What changed / What to review / Deferred / Test plan).
• It never files emergent decisions itself: it has no user channel mid-run and propose_decision commits on Tier 1 clean, so inline filing would install binding doctrine with no human gate. Instead it names the choice and rationale in its handoff, flagged as an emergent decision, for the parent to gate and route to whoever owns the filing (the planner, or @nauro-tech-lead for a doctrine move).
• On a reviewer block it fixes only what was flagged, re-runs lint and tests, and signals ready for re-review: no scope expansion.
• Handoff to the parent: branch name plus commit SHAs (subject lines only), lint/test results, the full drafted PR body (ready to paste into gh pr create --body), and the explicit instruction to invoke @nauro-reviewer on the local diff and not push until the reviewer approves and the user confirms.
• Code conventions enforced: no personal /Users/<name>/... paths anywhere (even on private repos), no internal labels or dated milestones in public-facing diffs, default to no comments, prefer startswith / find / slicing over regex in this Python codebase, assert exact exit codes (== N, not != 0), and colocate package-internal tests.

# Verbatim "What you do NOT do at this stage"
## What you do NOT do at this stage

- `git push` to any remote
- `gh pr create` or any PR-opening command
- Mark the task complete to the user

These happen only after the reviewer approves and the user confirms.

Source: packages/nauro/src/nauro/agents/nauro-executor.md (Scope discipline, Test-first, Surfacing emergent decisions, Code conventions, Local completion, "What you do NOT do at this stage", "When you finish").

The reviewer is read-only. It reviews a diff against the PR template and project conventions; it reads, never writes, commits, or pushes.

Bash is for read-only commands (git diff, git log, gh pr view, gh pr diff, grep).

• Two modes. Mode A (local pre-push, the default in the planner -> executor -> reviewer cycle) reads the drafted PR body from its prompt and the local diff (git diff origin/main...HEAD, or against the actual base branch). Mode B (remote PR audit) uses gh pr view / gh pr diff. Both dimensions and the return format are the same across modes.
• Pass 1, code review for real bugs only. A finding qualifies only if all six criteria hold: it meaningfully impacts accuracy, performance, security, or maintainability; is discrete and actionable; was introduced in this PR; is provably affected; is clearly not an intentional author choice; and the fix does not demand more rigor than the codebase shows. It explicitly prefers zero findings to weak findings. Bug shapes scanned include boundary/None handling, bare or swallowed exceptions, test weakening (broadened matchers, removed cases, pytest.raises removed, != replacing ==), caller mismatches, resource leaks, hardcoded values, stale comments, and concurrency hazards.
• Pass 2, policy enforcement. Hard rules BLOCK: required PR sections present (Why, Approach, What changed, What to review, What's deferred, Test plan; missing Why, Approach, or Test plan always blocks); every referenced decision resolves via get_decision; no personal paths; no internal labels in public repos; no raw template tokens (<!-- protocol:... -->) in distribution artifacts; cross-package dependency pins in sync.
• Soft flags report but do not block: dramatic copy, AI cadence (em-dash contrast pairs, "X, not just Y" parallelism) in user-facing copy, example-as-claim, explicit negation framings, casual code comments, scope creep, speculative infrastructure.
• It returns a structured VERDICT: APPROVE | BLOCK | APPROVE WITH NITS. Any qualifying code finding is a BLOCK; any hard-rule failure is a BLOCK; soft flags alone are APPROVE WITH NITS. In Mode A it appends a routing line telling the parent to surface for push confirmation (on approve) or hand failures back to the executor (on block), capped at 2 fix iterations before surfacing to the user.

VERDICT: APPROVE | BLOCK | APPROVE WITH NITS

Code findings (real bugs introduced in this PR):
- <file:line range>: <one-paragraph issue body; state trigger conditions explicitly>
(omit this block entirely if no code findings)

Hard-rule failures (if any):
- <rule>: <where in diff/PR>

Decision references checked:
- <decision reference>: resolved | UNRESOLVED

Soft flags:
- <location>: <issue> -> <suggested phrasing>

Summary: <one-line take>

Source: packages/nauro/src/nauro/agents/nauro-reviewer.md (two modes, six criteria, hard rules, soft flags, return format).

The tech-lead sets and maintains project direction and has write authority on Nauro doctrine. @nauro-planner, @nauro-executor, and @nauro-reviewer defer to it on architectural direction, but the human keeps the final override: every supersede and update passes through user approval before it calls propose_decision.

The kernel commits immediately on Tier 1 clean; there is no separate confirm step.

• The approval channel depends on invocation. Standalone (a human called it directly): it fires AskUserQuestion itself (options Approve and file / Reject / Modify draft) and files only on approval. Inside the /nauro-ship-task chain: the parent owns the gate, so it returns the drafted supersede/update marked "awaiting user approval" and does NOT fire AskUserQuestion in-run.
• Three modes. Mode A (direction-setting pre-work consult): check_decision + get_decision on every result, return GREEN/AMBER/RED. Mode B (post-session audit): the caller provides a Claude Code session ID; the transcript lives at ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl (encoded-cwd is the absolute cwd with each / replaced by -), filtered with jq/grep against the raw JSONL (never loading the whole file), files decisions made implicitly, and may call update_state. Mode C (PR/diff doctrine audit): default ref git diff origin/main...HEAD, requires a supersede first on drift and holds the merge.
• What it files vs surfaces: add (genuinely new ground, commits on Tier 1 clean; surface any similar_decisions), update (rationale-only append; the server consumes only rationale, while title / confidence / decision_type / reversibility / files_affected / rejected are rejected at the boundary, so use supersede for any of those), supersede (replace a contradicted or subsumed decision). It FLAGS via flag_question for open tensions and SURFACES (no file, no flag) for borderline "we decided X" moments, two active decisions that appear to contradict (meta-doctrine), or cases where redirect-versus-supersede are both defensible.
• It stays in the doctrine lane and explicitly does not replicate the reviewer's bug-finding pass; the reviewer can APPROVE a clean diff the tech-lead later flags for drift.
• RED is overridable inline by the human ("override RED on the cited decision, proceed"): the override surfaces in the transcript and does not require a supersede to be filed. update_state is replace-semantics (it wipes state_current.md to history) and used sparingly. Agent-side disagreement (planner or executor pushing back without human input) is not an override.

# AskUserQuestion gate for a supersede (Mode A step 5)
If the right move is to supersede an existing decision, draft the supersede
body, present it via AskUserQuestion (options: Approve and file / Reject /
Modify draft), and only on `Approve and file` call
propose_decision(operation="supersede", ...). The kernel commits immediately
on Tier 1 clean.

Source: packages/nauro/src/nauro/agents/nauro-tech-lead.md (frontmatter, three modes, "What you file vs what you surface", "When you outrank other agents", Hard rules).

The adopt skill runs after nauro adopt has wired MCP and installed the skill.

Its job is to seed the Nauro store via MCP write tools: docs supply rationale; code, config, tests, manifests, and git history supply evidence; and the user supplies the "why" via targeted probes when only evidence is present.

• Two surface modes. Filesystem-capable surfaces (Claude Code, Cursor, Codex CLI) run Steps 1-11 in full. Chat surfaces (Claude.ai, ChatGPT, Perplexity) have no shell: they operate only on content the user pastes (Step 3b), only against an already-adopted project, and skip the code-evidence path (Step 4) and Step 6b probes, jumping from Step 3b to Step 5.
• Already-adopted guard (Step 2): reads <repo>/.nauro/config.json (extract id and name), with a worktree fallback (compare git rev-parse --git-dir vs --git-common-dir) and a registry fallback (~/.nauro/registry.json, schema v2, where the dict key under projects IS the project id). The resolved id must be passed as project_id on every MCP call; auto-resolve routes to the default project, which may not be the one being seeded.
• Triage buckets (Step 6): documented decision (6a, needs explicit acceptance plus rationale in a source doc, or cross-doc stitching with both halves cited and both being docs); code-evidenced fact needing rationale (6b, filesystem only, one targeted probe per observation); stack inventory (6c, folded into the Step 8 update_state delta, never a decision); open question (Step 9 via flag_question); or ignore (Step 10).
• Write loop (Step 7) per candidate: check_decision -> get_decision -> classify add/update/supersede/skip -> propose_decision with the operation-specific signature. confidence defaults to medium; high only when a source explicitly says "accepted" or "approved". One propose_decision per candidate; surface any non-empty similar_decisions before the next candidate.
• Refusal contract (Step 10): never infer rationale from prose, never invent rejected alternatives, never treat demo prose, stack inventory, or code as a decision. Code evidence is "what", not "why"; it only becomes a decision once the user or a doc supplies rationale. No code-only dependency decisions.

# Operation-specific propose_decision signatures the write loop uses
# (adopt_body.md, Step 7)

# add (new ground)
propose_decision(project_id=..., title=..., rationale=...,
                 operation="add", rejected=..., confidence=...)

# update (rationale-only; server rejects every other field at the boundary)
propose_decision(project_id=..., rationale=...,
                 operation="update", affected_decision_id=...)

# supersede (replace / change metadata; pass the full new body)
propose_decision(project_id=..., title=..., rationale=...,
                 operation="supersede", affected_decision_id=...,
                 rejected=..., confidence=...)

Source: packages/nauro/src/nauro/skills/adopt_body.md (Surface modes, Steps 1-11, refusal contract); packages/nauro/src/nauro/cli/commands/adopt.py (closing message: "restart your agent and invoke /nauro-adopt to seed context").

The ship-task skill orchestrates a non-trivial code change end-to-end through @nauro-planner -> @nauro-executor -> @nauro-reviewer -> @nauro-tech-lead -> user-confirm -> push, with Nauro doctrine gates at every architectural choice. The chain runs without per-step prompting and pauses only at the two explicit GATEs.

• Prerequisite: the bundled @nauro-* subagents must be installed via nauro adopt --with-subagents (or nauro setup all --with-subagents); if missing, the chain cannot run and stops. The personal @planner/@executor/@reviewer path is explicitly not a substitute.
• Pre-step: if the planner returns RED with a supersede draft, the chain pauses before the executor sees anything; a RED the user does not resolve never reaches code. Only on explicit user approval (or an explicit "override RED on the cited decision, proceed") does the chain continue.
• GATE 1 (plan approval) always fires when propose_decision is in play; there is no low-stakes auto-proceed when doctrine writes are pending (stricter than the personal /ship-task skill). It also gates on high-stakes triggers: auth/credentials/secrets/tokens/signing/encryption; data-model/schema/storage-format/on-disk-or-database-layout changes; public-surface add/remove/rename (CLI commands, public functions, MCP tools, API endpoints, env vars, config keys); the nauro <-> nauro-core contract (or anything mcp-server consumes from nauro-core); dependency add/remove/major-version-bump; decisions with reversibility hard or moderate; or 2-3 genuinely architectural alternatives. With no doctrine writes and no high-stakes triggers it auto-proceeds with a one-paragraph summary.
• Step 6 (doctrine pass): after the reviewer returns APPROVE or APPROVE WITH NITS, @nauro-tech-lead runs in Mode C on the same local diff. GREEN proceeds; AMBER surfaces constraints at the push gate; RED pauses (redirect or supersede first; no push past RED without explicit human override). The reviewer's bug pass and the tech-lead's doctrine pass are deliberately separate concerns.
• GATE 2 (push confirmation) surfaces, in order: a one-paragraph summary (branch, commit hash, file count plus line delta, test result, reviewer and tech-lead verdicts, any decisions filed); then the drafted PR body verbatim in a fenced block; then asks "Push and open PR?" There is no push without an explicit yes/go/push. Skipping the verbatim body is a chain failure. On approval it pushes and runs gh pr create --body "...", paraphrasing doctrine moves in the Approach section rather than citing raw decision numbers.
• If a propose_decision is pending but the Nauro MCP server is disconnected, that is a hard pause: code and its decision must land together; no push-now-file-later split.

$ # install the bundled subagents (and the opt-in skills, incl. ship-task)
$ nauro adopt --with-subagents --with-skills
$ # or, for an already-adopted repo / all surfaces:
$ nauro setup all --with-subagents --with-skills

$ # then, after restarting the agent:
$ /nauro-ship-task add a --dry-run flag to the sync command

Source: packages/nauro/src/nauro/skills/ship_task_body.md (Prerequisites, Pre-step, Steps 1-8, Rules); packages/nauro/src/nauro/cli/commands/setup.py (SHIP_TASK_NEEDS_SUBAGENTS_NOTICE, SUBAGENTS_CONNECTOR_NAME_NOTICE); packages/nauro/src/nauro/cli/commands/adopt.py (--with-subagents / --with-skills).

The handoff skill captures a resumable session handoff into the project store, or resumes a prior one. It composes only existing MCP tools (get_context, update_state, flag_question, get_raw_file, diff_since_last_session) and never files a decision.

It is a real bundled skill (skills/handoff_body.md, in OPT_IN_SKILL_NAMES) installed via nauro adopt --with-skills.

• Mode is read from the invoking prompt. Capture runs at session end ("hand this off", "wrap up and hand off"); Resume runs at session start ("pick up where we left off", "resume"); ambiguous prompts ask the user. v1 targets the local-store path; pure chat surfaces with no local store are out of scope for this version.
• Capture: pull L1 context (get_context(level="L1")), write the full handoff body to <store>/handoffs/<slug>.md with the agent's own filesystem write (a short kebab-case slug, e.g. auth-refresh-cutover); handoffs are append-only, never overwrite or delete a prior one. Then a normal session-end update_state delta (REPLACE, roughly 5000-char cap; must be a one-line pointer and summary, never the handoff body), then flag the durable resume pointer.
• The resume pointer is a flagged question with the literal marker RESUME: handoffs/<slug>.md — <one-line summary>, which lives in the append-only open-questions.md (not state_current.md, to avoid the update_state REPLACE-clobber). A mandatory capture GATE surfaces the file path, the RESUME marker, and the delta, then waits for explicit user approval before nauro sync pushes the store.
• Resume: get_context L0 then L1, read open-questions.md via get_raw_file to find the most recent RESUME marker (stops with "no handoff to resume" if none), read the handoff body via get_raw_file, run diff_since_last_session for catch-up, then reconstruct and VERIFY every cited pointer (decision numbers, file paths, branches) against current store state before trusting it; handoff claims are hypotheses, not ground truth, and it reports drift.
• It resolves the RESUME flagged question only when a real decision has actually closed the work it pointed at; otherwise it leaves it open. The skill never files that closing decision itself (it runs in the main-agent context with no tool-lock, so autonomous filing is treated as a hazard).

# The literal resume-pointer marker flagged on capture (Step 4)
# and matched on resume (Step 8)
flag_question(question="RESUME: handoffs/<slug>.md — <one-line remaining-work summary>")

# on resume: read open-questions.md and locate the most recent RESUME: marker;
# the RESUME: text is literal so the resume flow can find it.

Source: packages/nauro/src/nauro/skills/handoff_body.md (two modes, Steps 1-12, Rules); packages/nauro/src/nauro/skills/__init__.py (SKILL_DESCRIPTIONS['nauro-handoff']).

The context skill writes a durable shared brief into the project store so other agents, a later session or a parallel one, can discover and pull it on demand, or finds and reads a brief another agent left. It is the N→N generalization of the 1→1 handoff: a handoff resumes your own next session, a brief broadcasts working context to any agent. It composes only existing MCP tools (get_context, get_raw_file, flag_question) and never files a decision.

It is a real bundled skill (skills/context_body.md, in OPT_IN_SKILL_NAMES) installed via nauro adopt --with-skills. A brief is free-form working context that is not yet a decision: a migration's half-finished state, a research synthesis, an investigation's findings, a map of a subsystem. Decisions remain the formal record; briefs are the connective tissue between them.

• Mode is read from the invoking prompt. Author runs when the user asks to share context for other agents; Find runs when the user asks what prior agents have shared; ambiguous prompts ask the user. v1 targets the local-store path; a pure chat surface with no local store can read briefs via get_raw_file but cannot author them in this version.
• Author writes the brief to <store>/context/<slug>.md with the agent's own filesystem write; the CLI push enumerates the whole store, so the file syncs with no code change. Briefs are append-only; on a slug clash the agent adds a disambiguator rather than overwriting. Each brief stays under MAX_BRIEF_BYTES (50 KiB); an over-cap brief is skipped at sync with a loud warning and kept on disk to trim and re-sync.
• Discovery is a flagged question with the literal marker BRIEF: context/<slug>.md — <one-line summary> on the set-union-merged open-questions.md, so pointers from concurrent authors all survive. There is no shared index file and no enumeration tool.
• Find orients with get_context, reads open-questions.md via get_raw_file to locate the BRIEF markers, picks the brief whose summary matches the task, and pulls it with get_raw_file. Briefs are pulled on demand and never auto-injected into get_context.
• Adjudicate. A brief is authored by another agent, so the reading agent treats the body as untrusted input and adjudicates it; the body is not ground truth. The author field is advisory and unverified, and carries no authority; the agent verifies any cited pointer against current store state before relying on it.

# Author flags this literal marker on the union-merged open-questions.md
flag_question(question="BRIEF: context/<slug>.md — <one-line summary>")

# Find reads open-questions.md and locates the most relevant BRIEF: marker;
# the BRIEF: text is literal so the find flow can match it.

Source: packages/nauro/src/nauro/skills/context_body.md (two modes, Author and Find); packages/nauro/src/nauro/skills/__init__.py (SKILL_DESCRIPTIONS['nauro-context']).

• Subagents install opt-in. nauro adopt --with-subagents (or nauro setup all --with-subagents) materializes the four nauro-*.md files into ~/.claude/agents/. Off by default to avoid overwriting customized files. --force-overwrite is only meaningful when --with-subagents is True and remove is False.
• Skills. nauro-adopt is always installed (into ~/.claude/skills/nauro-adopt/SKILL.md, ~/.agents/skills/nauro-adopt/SKILL.md for Codex, and <repo>/.cursor/rules/nauro-adopt.mdc for Cursor). --with-skills additionally installs the opt-in set (nauro-ship-task, nauro-handoff, nauro-context). The two flags are independent so subagents and skills can be adopted on separate cadences.
• Subagent install is bundle-owned (the nauro- namespace): on install the current bundle wins. If a nauro-<name>.md already exists and differs, it is refreshed from the bundle and the prior content is stashed to <name>.md.bak; --force-overwrite overwrites in place without the .bak. A byte-equal file is a no-op ("unchanged"). User-authored files without the nauro- prefix (e.g. a personal ~/.claude/agents/planner.md) are never touched.
• Only the Claude Code surface renders subagents today. render_agent returns the body verbatim for claude_code and raises NotImplementedError for cursor / codex, so materialize_agents emits a "skipped ~/.<surface> agents (not yet implemented)" line for those surfaces instead of crashing.
• Two install-time notices. If --with-skills is passed without --with-subagents, the CLI warns that nauro-ship-task references the bundled subagents (SHIP_TASK_NEEDS_SUBAGENTS_NOTICE). Whenever subagents are installed, it warns cloud users to name the remote MCP connector exactly Nauro so the subagents' mcp__claude_ai_Nauro__* tools resolve (SUBAGENTS_CONNECTOR_NAME_NOTICE).
• Running nauro adopt --with-subagents / --with-skills / --force-overwrite against an already-adopted repo routes to _install_into_adopted_repo, which materializes the artifacts without re-registering the project or rewriting .nauro/config.json. After install the user must restart the agent so it picks up the new files.

# --with-subagents help
--with-subagents  Install Nauro's bundled workflow subagents (@nauro-planner,
                  @nauro-executor, @nauro-reviewer, @nauro-tech-lead) into
                  ~/.claude/agents/. Off by default to avoid overwriting
                  customized files.

# SUBAGENTS_CONNECTOR_NAME_NOTICE (verbatim):
Cloud users: name the remote MCP connector exactly `Nauro` so the bundled
@nauro-* subagents' `mcp__claude_ai_Nauro__*` tools resolve.

Source: packages/nauro/src/nauro/cli/commands/adopt.py (adopt --with-subagents / --with-skills / --force-overwrite, _install_into_adopted_repo, closing message); packages/nauro/src/nauro/cli/commands/setup.py (materialize_agents, materialize_skills_*, setup_all_surfaces, SHIP_TASK_NEEDS_SUBAGENTS_NOTICE, SUBAGENTS_CONNECTOR_NAME_NOTICE, ALL_RESTART_NOTICE); packages/nauro/src/nauro/agents/__init__.py (render_agent, emit_plugin_agents).

• Exactly four bundled subagents: nauro-planner, nauro-executor, nauro-reviewer, nauro-tech-lead (AGENT_NAMES in agents/__init__.py); all model: opus.
• Exactly four bundled skills: nauro-adopt (always installed, SKILL_NAMES), nauro-ship-task, nauro-handoff, and nauro-context (opt-in, OPT_IN_SKILL_NAMES).
• Doctrine verdicts are GREEN / AMBER / RED. The planner classifies via check_decision; RED means an active decision directly contradicts the proposal OR the proposal would supersede an active decision.
• Subagents install into ~/.claude/agents/<name>.md via nauro adopt --with-subagents or nauro setup all --with-subagents; off by default.
• Claude Code skills install into ~/.claude/skills/<name>/SKILL.md; Codex into ~/.agents/skills/<name>/SKILL.md; Cursor into <repo>/.cursor/rules/<name>.mdc.
• propose_decision operations: add, update, supersede. On update the server consumes only rationale; title / confidence / decision_type / reversibility / files_affected / rejected are rejected at the boundary.
• confidence values seen: medium (default) and high (only when a source explicitly says "accepted" or "approved"). reversibility values referenced: hard, moderate.
• The executor never pushes, never runs gh pr create, and never files decisions itself; it commits locally and hands off. Push and propose_decision happen only with explicit user approval.
• Reviewer verdicts: APPROVE | BLOCK | APPROVE WITH NITS. A qualifying code finding or any hard-rule failure is a BLOCK; soft flags alone are APPROVE WITH NITS.
• The tech-lead gates every supersede/update through AskUserQuestion (options Approve and file / Reject / Modify draft) when standalone; in the ship-task chain it returns drafts "awaiting user approval" for the parent to file. The kernel commits on Tier 1 clean with no separate confirm step.
• Required PR sections enforced by the reviewer: Why, Approach, What changed, What to review, What's deferred, Test plan.
• /nauro-handoff resume pointer is a flagged question with the literal marker RESUME: handoffs/<slug>.md — <summary> in append-only open-questions.md; handoffs accumulate append-only under <store>/handoffs/.
• update_state is REPLACE semantics with a roughly 5000-character cap; it wipes state_current.md to history.
• ship-task gates always when propose_decision is in play (no low-stakes auto-proceed), plus on high-stakes triggers (auth/secrets, data model/schema/storage, public surface, the nauro <-> nauro-core contract, dependency add/remove/major-bump, reversibility hard/moderate, 2-3 architectural alternatives).
• Subagents call Nauro MCP tools under two prefixes: mcp__claude_ai_Nauro__* (cloud connector, which must be named exactly Nauro) and mcp__nauro__* (local stdio).
• Only the claude_code surface renders subagents; render_agent raises NotImplementedError for cursor/codex and materialize_agents emits a "skipped … (not yet implemented)" line.
• On subagent (re)install, a differing customized nauro-<name>.md is refreshed from the bundle (prior content saved to <name>.md.bak unless --force-overwrite); a byte-equal file is left unchanged; only the bundle-owned nauro-* namespace is touched, never a user's own un-prefixed agent file.