Agents and skills

Nauro bundles two distinct artifact types. Workflow agents are rendered as Claude Code Markdown under ~/.claude/agents/<name>.md, Codex TOML under ~/.codex/agents/<name>.toml, and Cursor native custom-agent Markdown under <repo>/.cursor/agents/<name>.md in each registered repo.

Skills are SKILL.md files materialized under ~/.claude/skills/<name>/ for Claude Code and ~/.agents/skills/<name>/ for Codex; Cursor receives repo-local rules. In Cursor Agent chat, @-mention a rule by filename to invoke it explicitly, for example @nauro-adopt.

• There are exactly five bundled workflow roles, defined by AGENT_NAMES = ("nauro-planner", "nauro-executor", "nauro-reviewer", "nauro-tech-lead", "nauro-investigator") in agents/__init__.py. The same canonical instruction bodies render for Claude Code, Cursor, and Codex.
• There are exactly five bundled skills, named in skills/__init__.py (SkillName and SKILL_DESCRIPTIONS): nauro-adopt, nauro-ship-task, nauro-context, nauro-loop, and nauro-interview. nauro-adopt is always installed (SKILL_NAMES); the other four are opt-in (OPT_IN_SKILL_NAMES).
• Claude Code definitions use model: inherit and declare a restricted tools: allowlist. The Codex renderer carries the same description and instruction body into TOML and marks the planner, reviewer, tech-lead, and investigator read-only (sandbox_mode = "read-only"). The Cursor renderer keeps name, description, and model, drops the Claude tools: field, and sets readonly: true on the same four roles.
• The subagents are essential because they call Nauro’s MCP decision tools by design (check_decision, get_decision, search_decisions, and others); none of them calls propose_decision, flag_question, or update_state. 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",
    "nauro-investigator",
)

# cli/integrations/skills.py
SKILL_NAMES: tuple[str, ...] = ("nauro-adopt",)
OPT_IN_SKILL_NAMES: tuple[str, ...] = (
    "nauro-ship-task",
    "nauro-context",
    "nauro-loop",
    "nauro-interview",
)

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/integrations/skills.py (SKILL_NAMES, OPT_IN_SKILL_NAMES).

The planner plans changes; it does not edit files. It classifies doctrine risk GREEN/AMBER/RED via Nauro, writes a structured plan, and drafts decision additions, updates, or supersedes for the direct-user Delivery parent, which files them only after explicit user approval.

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 has a fixed 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 never files: it does not call propose_decision, flag_question, or update_state in any invocation. It returns the complete add, update, or supersede draft in the decision proposal template plus the related-decision assessment; the direct-user Delivery parent files the exact approved draft after verifying that both remain unchanged. A changed draft needs fresh approval.
• 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 needed for a plan.

# @nauro-planner frontmatter, line-wrapped for display; the
# mcp__nauro__* and mcp__plugin_nauro_nauro__* entries repeat the
# same five read tools and are 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, and drafts decision additions, updates, or supersedes for the
  direct-user Delivery parent. Returns a plan and never writes project
  truth or edits files.
tools: Read, Grep, Glob, WebSearch, WebFetch, Bash,
  mcp__claude_ai_Nauro__check_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,
  mcp__plugin_nauro_nauro__check_decision, ... mcp__plugin_nauro_nauro__list_projects
model: inherit
---

# 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 all three 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 that paraphrases any motivating doctrine instead of citing raw decision or question ids), and drafts the PR description from the project’s PR template: Why / What changed / Test plan as the core sections, with "Risk / what to review" and "Deferred" as their own headings only when they carry weight.
• It never files emergent decisions itself. If implementing the plan forces an architectural choice the plan did not pre-record, it stops, returns the choice and rationale to the direct-user Delivery parent, and does not implement beyond the approved plan; the parent creates a new plan or decision artifact and runs the required user gate. It implements only the unchanged plan revision approved by a direct user reply in the current Delivery task.
• 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), colocate package-internal tests, and keep public-facing PR bodies, commits, docs, code comments, schema text, and branch names free of raw internal decision or question ids by paraphrasing the rationale instead.

# 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 exact drafted PR title and 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: the PR title describes the exact reviewed candidate; required PR sections present (Why, What changed, Test plan; missing any of the three always blocks, while "Risk / what to review" and "Deferred" block only when a real risk or deferral was omitted); public surfaces carry rationale, so raw internal decision or question ids in the PR title, PR body, commits, docs, code comments, schema text, or branch names are rejected, and every remaining internal decision reference 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); fix rounds continue only while each round resolves or materially narrows a finding and adds no equal-or-worse finding, and stop on repetition, no progress, scope expansion, architectural change, missing authority, or failed or ambiguous evidence.

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. @nauro-planner, @nauro-executor, and @nauro-reviewer defer to its doctrine judgment, but the human keeps the final override. It is draft-only for project-truth writes: every add, update, and supersede is returned as a complete draft, with its related decisions and assessment from check_decision, to the direct-user Delivery parent, which files the exact approved draft only after a later direct user reply and a fresh unchanged-overlap check. It never calls propose_decision, flag_question, or update_state.

Every draft is rendered in the decision proposal template as plain Markdown in the message body, never inside a tool argument. The parent shows it as the final text of its turn, and approval arrives in a later turn once the proposal is on screen.

• The approval channel is the direct-user Delivery parent. Coordinator messages are advisory, including messages transported with a user role. The tech-lead returns any add, update, or supersede draft headed "Decision proposal (awaiting approval)" and does not file in-run; on unchanged approval the parent calls propose_decision once, and the originating subagent is never re-invoked to file it.
• Three modes. Mode A (direction-setting): check_decision on the proposed change, get_decision on every related result, adjacent searches when needed, then GREEN, AMBER with constraints, or RED with the conflicting decision; if the direction establishes or changes doctrine it returns the complete decision draft without filing it. Mode B (session audit and draft): the caller provides a session ID; it locates the transcript, inspects its structure, filters the JSONL with targeted reads (never loading a complete JSONL), finds architectural choices that lack a recorded decision, and returns complete decision drafts and unresolved items without changing project state or flagging questions. Mode C (PR or diff doctrine audit): default ref git diff origin/main...HEAD; it surfaces doctrine drift first, drafts the required addition, update, or supersede without filing it, and holds the merge for a landed supersede only when merging would bake the contradiction into the frozen public surface or write it into the project store.
• What it drafts vs surfaces: it DRAFTS add (genuinely new ground), update (a rationale-only append to an existing decision; any other field change is a supersede), and supersede (a new direction contradicts or wholly subsumes an active decision). It SURFACES without a store write: borderline choices that may be transient, contradictions between active decisions, open architectural tensions and unresolved tradeoffs, and drift where redirecting the code and superseding doctrine 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.
• Only a direct user reply in the Delivery task can override a RED verdict, approve a decision artifact, or authorize publication. Agent disagreement (the planner or executor pushing back without human input) never grants an override. The planner revises its plan when the tech-lead returns RED on its direction; the executor returns unplanned architectural choices to the Delivery parent.

# Verbatim @nauro-tech-lead return format
VERDICT: GREEN | AMBER | RED

Direction: <one-paragraph assessment>

Decision drafts:
- <operation and title, affected decision when applicable, and why it is needed>

Doctrine findings:
- <location>: <contradiction | drift | should-supersede | pattern-completion>: <active decision>

Surfaced for human review:
- <item>: <why human judgment is required>

Decisions consulted:
- <decision>: <what it says>

Summary: <one-line result>

Source: packages/nauro/src/nauro/agents/nauro-tech-lead.md (frontmatter, "Draft-only project-truth boundary", "Decision proposal template", three modes, "What you draft and what you surface", "When you outrank other agents", "Return format", Hard rules).

The investigator investigates Nauro use and development cycles across Claude and Codex logs. It finds supported defects, repeated friction, drift, useful outcomes, and gaps in follow-through, checks current code and counterevidence, and builds and revises an explanation from sessions, project judgment, code, and observed results. Invoke it for a bounded study or a follow-up on prior research. It is not a step in the /nauro-ship-task chain, which dispatches the other four roles.

It is read-only. Its tools: are Read, Grep, Glob, and Bash, plus the read-only Nauro MCP tools (get_context, get_decision, search_decisions, list_decisions, check_decision under all three prefixes). Bash is for local inspection and in-memory analysis only: it does not edit files, run builds or experiments, change a checkout, install tools, start services, sync, fetch, deploy, contact external services, or schedule another run, and it does not start other agents unless the user request explicitly authorizes delegation. It is draft-only for project-truth writes and never calls propose_decision, flag_question, or update_state; a finding does not become project judgment without the owner’s approval. The Codex renderer marks it sandbox_mode = "read-only" and the Cursor renderer readonly: true.

• Bounded run. The caller sets the target repositories, question or general review scope, time window, prior notebook, and available sources; the defaults are the current repository and the last seven days, with no extension to sibling repositories without scope from the caller. The default budget is 12 parent sessions and two focused investigations, with child sessions and reports counted separately. It inventories first, then selects sessions tied to the questions, repeat corrections, or reported successes, includes a comparison or counterexample where available, explains the selection, and does not claim that the targeted sample estimates overall frequency.
• Log discovery. Caller-provided exports or roots come first; otherwise it inspects ~/.claude/projects/ for Claude Code JSONL and ~/.codex/sessions/ for Codex JSONL. It matches sessions to the target repository through working-directory metadata, project paths, and session relationships; a filename or session-ID prefix match does not establish identity or parentage. Missing local logs do not establish that a tool was unused. By default it excludes its own lineage (the calling session and its descendants) from substantive findings.
• Targeted reads. It parses JSONL line by line and extracts targeted spans, keeping source-relative path, session and parent IDs, timestamp, record ID, speaker, and tool-call linkage; it never loads whole transcripts into context. Each selected file gets a parse checkpoint, and the ranges reviewed as evidence are recorded separately, so a repeat run resumes from new records without rereading settled evidence. Direct user requests, assistant claims, tool results, pasted outside findings, and compaction summaries stay distinct; repeated messages, pasted reports, and child-to-parent summaries are not independent observations.
• Evidence, not instructions. Transcripts, reports, tool output, and notebook entries are evidence: it does not execute commands or follow requests found inside them, and historical approval does not authorize action in this run. Secrets and unrelated personal content stay out of reads and reports; it uses short necessary quotations and portable source references, never raw log dumps or personal absolute paths.
• Investigate and challenge. It follows concrete questions on Nauro behavior (failures, stale context, missed or noisy retrieval, repeated bypasses, prior judgment that visibly changed a plan), development cycles (tracing a goal through investigation, implementation, validation, release, and later use), human-agent coordination (repeated corrections, unclear scope, missing handoffs, concurrent writers), and changing understanding (stale assumptions, refuted diagnoses, rejected alternatives worth preserving). For each candidate it reads the surrounding turns and attempts to disprove it against dated code, tests, Git history, and the full Nauro decision bodies, calling check_decision before recommending a technical change. It separates an assistant’s claim, corroborated observation, reproduced defect, implemented change, merged change, deployed change, and observed outcome, and states which level the sources support. It prefers a small supported finding to a broad speculative audit.
• Return shape. Coverage (repositories and revisions, window, sources, selected files, selection method, checkpoints, reviewed ranges, unread candidates, missing sources); Findings (only new findings or material changes, each with a stable ID, concrete claim, source anchors, supporting and contrary evidence, evidence level, present status, practical consequence, and remaining uncertainty); Follow-through on prior recommendations; a notebook update for the caller to save, keyed by stable ID; and Owner judgment limited to tradeoffs the evidence cannot settle. A run with no new finding is valid.
• The notebook is research evidence, not project truth. If no notebook exists it returns an initial one; if the caller does not save it, it states that continuity remains unsaved. It does not claim persistent memory, continuous monitoring, completed fixes, or outcomes beyond the evidence.

# @nauro-investigator frontmatter, line-wrapped for display; the
# mcp__nauro__* and mcp__plugin_nauro_nauro__* entries repeat the
# same five read tools and are elided as "...":
---
name: nauro-investigator
description: Use to investigate Nauro use and development cycles across
  Claude and Codex logs. Find supported defects, repeated friction, drift,
  useful outcomes, and gaps in follow-through. Check current code and
  counterevidence. Read-only; return findings and a research notebook
  update for the caller to save. Invoke for a bounded study or a
  follow-up on prior research.
tools: Read, Grep, Glob, Bash,
  mcp__claude_ai_Nauro__get_context, mcp__claude_ai_Nauro__get_decision,
  mcp__claude_ai_Nauro__search_decisions, mcp__claude_ai_Nauro__list_decisions,
  mcp__claude_ai_Nauro__check_decision,
  mcp__nauro__get_context, ... mcp__nauro__check_decision,
  mcp__plugin_nauro_nauro__get_context, ... mcp__plugin_nauro_nauro__check_decision
model: inherit
---

Source: packages/nauro/src/nauro/agents/nauro-investigator.md (frontmatter, "Authority and scope", "Start a bounded run", "Find and read Claude and Codex logs", "Investigate and challenge", "Return findings and a notebook update"); packages/nauro/src/nauro/agents/__init__.py (read-only agent set for the Codex and Cursor renderers).

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

After restarting the agent, invoke it as /nauro-adopt in Claude Code or $nauro-adopt in Codex. Cursor uses the installed repo rule.

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 Step 0 and Steps 1-11 in full. Chat surfaces (Claude.ai, 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).
• Rapid cited seed (Step 0): on filesystem surfaces, complete classified proposals can be shown in one batch. A batch confirm is explicit approval for each unchanged proposal selected. If the Step 7 recheck changes its operation, payload, related decisions, or assessment, the revised proposal needs fresh approval. There is no blanket second gate for unchanged confirmed cards.
• Write loop (Step 7) per candidate: check_decision -> get_decision -> classify add/update/supersede/skip -> present the complete proposal and overlaps for approval -> propose_decision with the operation-specific signature. Earlier keep replies select candidates but do not approve a write. confidence defaults to medium; high only when a source explicitly says "accepted" or "approved".
• 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 (surface-specific closing message).

The ship-task skill orchestrates a non-trivial code change end-to-end through planner -> executor -> reviewer -> tech-lead -> user-confirm -> push, with Nauro doctrine gates at every architectural choice. The investigator is not part of the chain. The direct-user Delivery parent is the sole authority carrier: only a direct user reply in the current Delivery task can approve a plan, project-truth write, push, or PR creation, and subagents only draft project-truth writes. After the surface-specific dispatch capability is established, the normal chain runs without per-step prompting and pauses at its explicit GATEs.

Cursor boundary. Cursor receives the nauro-ship-task.mdc rule and runs the chain through its native custom agents /nauro-planner, /nauro-executor, /nauro-reviewer, and /nauro-tech-lead, installed under .cursor/agents/ in every registered repo. Before planning or changing files it verifies that all four .cursor/agents/nauro-*.md files exist and that the Cursor runtime loaded the native definitions and can dispatch each configured name; a generic Task agent or prompt mention does not qualify. If any definition or native dispatch capability is missing, it explains that the chain is unavailable and stops before planning, mutation, project-truth writes, commit, push, or PR creation; it does not reproduce the roles inline or use a generic-agent fallback. Cursor custom agents inherit the parent session’s MCP tools, so readonly: true does not deny MCP write tools; the explicit draft-only instruction and the Delivery-parent authority contract remain the portable controls. Use Claude Code or Codex for the complete bundled delivery chain when Cursor cannot dispatch the native agents.

• Prerequisite: the bundled workflow agents must be installed via nauro adopt --with-subagents (or nauro setup all --with-subagents); if missing, the chain cannot run and stops. Claude Code dispatches the named @nauro-* agents.
• Codex dispatch capability check: before planning or mutation, the skill verifies all four chain-role TOML definitions under ~/.codex/agents/ and inspects the dispatcher for agent_type or an equivalent custom-agent selector. A matching task_name alone is not proof of custom-agent dispatch. If the selector is unavailable, the skill explains the weaker instruction-level Codex fallback and asks for explicit approval before doing any work. A decline or missing definition stops the chain.
• 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) fires for every plan. The parent shows the recommendation, why it matters, the semantic boundary, material risks or exceptions, deferrals, and what approval authorizes, then waits for direct user approval of that exact plan revision; approval authorizes only implementation and local validation. A decision draft from the planner or tech-lead is shown as the complete proposal, exactly as it would be filed, as the final text of its turn; approval must arrive in a later direct user reply, after which the parent reruns the overlap check and calls propose_decision once. A plan-time decision is filed and confirmed before the executor is dispatched.
• Local review (doctrine pass): after the reviewer returns APPROVE or APPROVE WITH NITS, @nauro-tech-lead runs in Mode C on the same reviewed revision. GREEN proceeds; AMBER surfaces constraints at the push gate; RED pauses (redirect or supersede first; no push past RED without explicit human override). Neither role writes project truth or authorizes publication, and the reviewer’s bug pass and the tech-lead’s doctrine pass are deliberately separate concerns. When review blocks, only the findings go back to the executor, and correction continues only while each round resolves or materially narrows a finding.
• GATE 2 (publication approval) shows the semantic change, any material reviewer finding or nit, any doctrine constraint, every visible exception, and the exact PR title and full PR body, then asks "Push and open PR?" and waits for a direct user reply approving that exact publication revision; routine filenames, counts, and hashes stay in the internal audit record. If the candidate, PR title, or PR body differs from the reviewed artifact, the affected review is reopened before asking. On approval it pushes the reviewed commit, writes the approved body to a file, and runs gh pr create --title <exact-approved-title> --base <reviewed-base> --body-file <approved-body-file>, never passing the body inline; if gh is unavailable it returns the compare URL without claiming that a PR exists.
• If doctrine is unavailable, the chain holds; if an approved decision cannot be filed and confirmed, it holds before the next mutation or publication step: code and its decision land together, with no push-now-file-later split.

$ # install the bundled workflow agents and opt-in skills
$ nauro adopt --with-skills --with-subagents
$ # or, for an already-adopted repo / all surfaces:
$ nauro setup all --with-skills --with-subagents

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

Source: packages/nauro/src/nauro/skills/ship_task_body.md (Authority boundary, Prerequisites, Pre-step, Steps 1-8, Rules); packages/nauro/src/nauro/skills/__init__.py (per-surface ship-task prerequisites and dispatch checks); packages/nauro/src/nauro/cli/integrations/orchestrator.py (SHIP_TASK_NEEDS_SUBAGENTS_NOTICE, SUBAGENTS_CONNECTOR_NAME_NOTICE); packages/nauro/src/nauro/cli/commands/adopt.py (--with-subagents / --with-skills).

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; finds and reads a brief another agent left; or captures a resume brief so your next session can reconstruct the in-flight state. It composes only existing MCP tools (get_context, get_raw_file, flag_question) alongside the agent’s own filesystem write and the nauro status shell command, and never files a decision. The earlier standalone /nauro-handoff skill is retired; its capture-and-resume flow is now this skill’s Resume mode, and the legacy handoffs/ directory is never written to.

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, the in-flight state your next session must reconstruct. Decisions are the formal record; briefs hold the working state 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; Resume is offered when the user asks for a fresh-session prompt, a handoff of the work, or a resume doc, and runs once the user accepts; 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 or capture 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.
• Resume pulls L1 context (get_context(level="L1")) so the brief reflects the project’s real state, then stages a resume brief: a role-and-mission line, a verify-don’t-trust preamble, a state snapshot, expected-state anchors with stop-if-fail semantics (branch heads, open PR numbers, test counts, each checked against origin/main), a guardrails block, the next concrete step, done criteria, and pointers into durable channels. The target path is context/<slug>.md, the same namespace and slug scheme as shared briefs.
• The Resume gate. Before any store mutation, the agent surfaces the staged file path, the literal RESUME: pointer text, and the paste-back prompt the next session will receive, then waits for explicit user approval; auto-mode does not override the gate. On approval it writes the brief, flags the RESUME pointer, and syncs if the project is cloud-linked (a local-only store is already reachable by a same-machine session). The paste-back prompt tells the fresh session to pull the brief and verify every anchor before doing any work.
• Adjudicate. A brief is authored by another agent, or by your own prior session, 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>")

# Resume flags its pointer the same way, after the user clears the gate
flag_question(question="RESUME: context/<slug>.md — <one-line remaining-work summary>")

# Find reads open-questions.md and locates the most relevant BRIEF: marker;
# the BRIEF: and RESUME: texts are literal so the find and resume flows can match them.

Source: packages/nauro/src/nauro/skills/context_body.md (three modes: Author and Find Steps 1-6, Resume Steps R1-R5, Rules); packages/nauro/src/nauro/skills/__init__.py (SKILL_DESCRIPTIONS['nauro-context']).

The interview skill helps you make tacit project reasoning explicit or stress-test a proposed choice. Elicit mode draws out reasoning that is not yet written down. Challenge mode tests a proposed choice against active Nauro decisions, repository evidence, alternatives, failure cases, and dependent choices.

• Explicit opt-in. The skill runs only when you ask to be interviewed, grilled, stress-tested, or helped to transfer reasoning into Nauro. A vague plan does not trigger it.
• Compact rounds. Each round asks at most three prerequisite-ready questions. Questions keep stable numbers, name finite choices directly when possible, and include an answer-first recommendation.
• No silent authority. Interview agreement is shared understanding, not project truth. The skill does not write during the interview or when you confirm the summary. If you ask to save the result, each decision, state, or question payload keeps its own exact approval gate.
• Main-context workflow. The user participates in every round, so the skill runs in the main agent context. It does not depend on bundled subagents or an external grilling skill.

Source: packages/nauro/src/nauro/skills/interview_body.md (Modes, interview engine, completion, and write gates); packages/nauro/src/nauro/skills/__init__.py (SKILL_DESCRIPTIONS['nauro-interview']).

The loop skill originates gated work and coordinates selected Program Delivery over /nauro-ship-task. For agent-originated work, run under the dynamic /loop command (/loop /nauro-loop), it mines the project’s existing store state read-only, ranks a small set of candidate tasks typed Delivery or Interview, and surfaces them for you to pick; on your pick it dispatches /nauro-ship-task <chosen task> byte-for-byte with every inner gate intact, then loops back. Work you name yourself enters as HUMAN-SELECTED and skips candidate origination, ORIENT, and SELECT without a redundant choice gate. The one authority it adds is task origination; it enumerates candidates and you select.

• ORIENT (read-only). It reads get_context(level="L0"), scans open-questions.md for RESUME: and BRIEF: pointers, runs diff_since_last_session, and reads list_decisions, then composes one to three ranked candidates, each typed Delivery or Interview, with a one-line rationale, its source signal, and its provenance. It writes nothing; on an empty mine it composes nothing and stops. A RESUME: anchor that no longer matches origin/main is demoted to "stale, surface" and reported, never ranked as live work.
• SELECT (mandatory gate). Candidates surface through AskUserQuestion with their rationale and provenance; you pick one or reject them all. There is no auto-pick path, not even for a single ranked candidate. check_decision output, when shown, is a raw related-decision list, never a verdict or recommendation.
• CHAIN. Your chosen candidate becomes the verbatim input to /nauro-ship-task, dispatched with all of its gates intact: the RED-supersede pause, plan approval, AMBER surfacing, the RED tech-lead pause, push confirmation, and the doctrine-disconnect hard-pause. Every plan still blocks for explicit approval; a standing "keep going" or auto-mode directive does not clear the SELECT gate, the plan gate, a tech-lead pause, or the push gate. An Interview candidate routes to /nauro-interview only after you confirm the route and mode, and its output never starts a Delivery by itself.
• Program mode. An opt-in Delivery policy for a selected program: the coordinator runs FRAME -> CHOOSE -> START -> ADVISE -> VERIFY -> ADVANCE, starting at most one fresh direct-user Delivery task per slice, advising at that task’s PLAN_READY and PUBLICATION_READY stops with READY or requested changes bound to the exact artifact revision, and verifying the PR and merge state independently before recommending at most one next action, which it never starts itself. Automatic launch requires runtime support to create, identify, inspect, and message that task; otherwise the coordinator returns one exact launch prompt for the surface’s nauro-ship-task command and stops. Coordinator advice never approves anything; only the direct user in the Delivery task can.
• No store-write authority. The loop never files a decision, never pushes, and never creates or edits a PR; it may run gh pr view or an equivalent read-only channel only for a required PR-backed anchor check. Every filing, PR, and push happens inside the dispatched chain after you clear the relevant chain gate. The one narrow exception is the scheduled ORIENT checkpoint below: a filesystem write under context/ plus its SELECT: pointer, which is process state, not doctrine. A standing "keep going" directive does not override the SELECT gate or any inner chain gate.
• Bounded and fail-closed. One direct-user Delivery may be active at a time; lifecycle, artifact, approval, or integration uncertainty fails closed and moves a program to held rather than counting as approval; a chain that self-halts, errors, returns an ambiguous result, or lacks authority stops and surfaces to you. The loop stops on an empty mine, and after a chain returns it writes nothing automatically and must present a new SELECT before any further agent-originated work.
• Two entry modes for agent-originated work. Synchronous: the dynamic /loop command repeats the skill in the parent session, which can pause for the SELECT gate. Scheduled headless ORIENT: your own scheduler (cron, a cloud routine, any wakeup; Nauro bundles none) fires the read-only mine, and the run parks the ranked set as a durable checkpoint at <store>/context/<slug>.md, flags the literal SELECT: context/<slug>.md — <summary> pointer on open-questions.md, syncs, and exits before any gate; an unattended run never surfaces SELECT. A later live session answers the parked SELECT: it locates the freshest unconsumed checkpoint, stops on one older than 24 hours as stale, re-verifies each candidate’s anchors against origin/main, and surfaces the survivors through AskUserQuestion.

Source: packages/nauro/src/nauro/skills/loop_body.md (Authority boundary, FRAME, CHOOSE with ORIENT, entry modes, SELECT, and ROUTE, START, ADVISE, VERIFY, ADVANCE, Held state and recovery, Synchronous non-program Delivery, Rules); packages/nauro/src/nauro/skills/__init__.py (SKILL_DESCRIPTIONS['nauro-loop']); packages/nauro/src/nauro/cli/integrations/skills.py (OPT_IN_SKILL_NAMES).

• Complete workflow. Run nauro adopt --with-skills --with-subagents in a new repo adoption, or nauro setup all --with-skills --with-subagents in an adopted project. This installs the complete bundled delivery workflow for Claude Code, Cursor, and Codex: user-global agent files for Claude Code and Codex, and per-repo .cursor/agents/ files alongside the skill rules for Cursor. Plain nauro adopt wires MCP and installs only the core nauro-adopt skill.
• Workflow agents install opt-in. --with-subagents materializes five nauro-*.md files into ~/.claude/agents/ for Claude Code, five nauro-*.toml files into ~/.codex/agents/ for Codex, and five nauro-*.md files into .cursor/agents/ in each registered repo for Cursor.
• 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-context, nauro-loop, nauro-interview). The two flags are independent so subagents and skills can be adopted on separate cadences.
• Nauro-owned files refresh safely. If an installed Nauro skill or agent definition differs from the current bundle, setup refreshes it and stashes the prior content in a sibling .bak. --force-overwrite skips the backup. Byte-equal files are unchanged, and files outside Nauro’s owned names are never touched.
• Two install-time notices. If --with-skills is passed without --with-subagents, the CLI warns that nauro-ship-task needs the bundled workflow agents. It also tells Claude Code cloud users to name the remote connector exactly Nauro so the Claude definitions’ mcp__claude_ai_Nauro__* tools resolve.
• 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.
• Verify before restart. Run nauro status to diagnose MCP, Codex hooks, skills, workflow agents, and AGENTS.md. Run nauro doctor separately to check store integrity. Then start a fresh agent session and make a Nauro MCP call.

nauro adopt --with-skills --with-subagents
nauro status
nauro doctor

# Restart, then:
# Claude Code: /nauro-adopt
# Codex: $nauro-adopt

Source: packages/nauro/src/nauro/cli/commands/adopt.py (install flags, _install_into_adopted_repo, closing message); packages/nauro/src/nauro/cli/commands/setup.py (setup flags); packages/nauro/src/nauro/cli/integrations/orchestrator.py (notices); packages/nauro/src/nauro/cli/integrations/agents.py (materialize_agents); packages/nauro/src/nauro/cli/integrations/skills.py; packages/nauro/src/nauro/agents/__init__.py (render_agent).

• Exactly five bundled workflow agents: nauro-planner, nauro-executor, nauro-reviewer, nauro-tech-lead, nauro-investigator (AGENT_NAMES in agents/__init__.py). Claude Code Markdown uses model: inherit; Codex TOML omits a model field and renders name, description, optional sandbox_mode, and developer_instructions; Cursor Markdown keeps name, description, and model and adds readonly: true for the planner, reviewer, tech-lead, and investigator.
• Exactly five bundled skills: nauro-adopt (always installed, SKILL_NAMES), plus nauro-ship-task, nauro-context, nauro-loop, and nauro-interview (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.
• Workflow agents install into ~/.claude/agents/<name>.md for Claude Code, ~/.codex/agents/<name>.toml for Codex, and <repo>/.cursor/agents/<name>.md in each registered repo for Cursor via --with-subagents.
• 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: high (only with explicit source approval, such as a source that says "accepted" or "approved"), medium (the default), and low. reversibility values: easy, moderate, hard.
• 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 from the direct-user session, 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 never files: every add, update, and supersede returns as a complete draft in the decision proposal template, and the direct-user Delivery parent files the exact approved draft after a later direct user reply and a fresh unchanged-overlap check. The originating subagent is never re-invoked to file it.
• The investigator is read-only and draft-only: it studies Claude and Codex logs, current code, and Nauro decisions in a bounded run, excludes its own session lineage by default, and returns findings plus a research notebook update for the caller to save; the notebook is research evidence, not project truth.
• Required PR sections enforced by the reviewer: Why, What changed, Test plan; "Risk / what to review" and "Deferred" are conditional headings that block only when a real risk or deferral was omitted. The PR title must describe the exact reviewed candidate.
• /nauro-context Resume mode flags the literal marker RESUME: context/<slug>.md — <summary> in append-only open-questions.md after a user-approved gate; briefs, shared and resume alike, accumulate append-only under <store>/context/.
• /nauro-interview runs only on explicit user request, records no automatic project truth, and keeps separate approval gates for any later decision, state, or open-question write.
• /nauro-loop runs under /loop /nauro-loop, or as a scheduled headless ORIENT that parks a SELECT: checkpoint and exits; it originates one to three Delivery or Interview candidates from a read-only store mine and dispatches the chosen Delivery to /nauro-ship-task after a mandatory AskUserQuestion pick, while human-named work skips SELECT. It files nothing, pushes nothing, and stops on an empty mine.
• update_state is REPLACE semantics with a roughly 5000-character cap; it wipes state_current.md to history.
• ship-task waits for direct user approval of every exact plan revision, every complete decision proposal, and every exact publication (PR title and body); a coordinator message, standing instruction, previous approval, or subagent recommendation never grants that authority.
• Claude Code agent definitions list Nauro MCP tools under mcp__claude_ai_Nauro__* (cloud connector, which must be named exactly Nauro), mcp__nauro__* (local stdio), and mcp__plugin_nauro_nauro__* (the Nauro Claude Code plugin). Codex and Cursor do not share the connector-name constraint, since their renderers drop the Claude tools: field.
• render_agent returns the canonical Markdown body for claude_code, translates it into custom-agent TOML for codex and native custom-agent Markdown for cursor, and raises ValueError for any other surface.
• Complete Claude Code, Cursor, and Codex workflow: nauro adopt --with-skills --with-subagents. After installation, run nauro status, use nauro doctor for store integrity, restart, then invoke /nauro-adopt in Claude Code, $nauro-adopt in Codex, or @nauro-adopt in Cursor Agent chat.
• On reinstall, a differing Nauro-owned skill or agent definition is refreshed from the bundle and its prior content is saved to a sibling .bak unless --force-overwrite is passed. Byte-equal files are left unchanged; unrelated user files are not touched.