[init] OPERATOR_NOTES.md + opt-in judges/mandates/audits scaffolding + operating mode + location questions

[dep0we]

Status (post-init-wizard-arc)

The original scope of this issue was the stopgap scaffold script before #94's full conversational wizard. #94 shipped both PRs of arc on 2026-06-02 (#317 PR 1 of arc, #323 PR 2 of arc). Most of #142's original scope landed there. This rewrite preserves the issue number and tightens to residual scope only.

Origin: conversation 2026-05-12 (post-public-flip operator-experience gap discussion).

What's already shipped (via #94 arc)

• Agent name question → wizard Q1 (feat(init): #94 PR 1 of 2. atomic-agents init wizard #317).
• Folder scaffold → _render_files writes 7 template files per agent (feat(init): #94 PR 1 of 2. atomic-agents init wizard #317).
• Refuse-to-overwrite → 3-option collision prompt: Overwrite / Add-to-it / Cancel (feat(init): #94 PR 1 of 2. atomic-agents init wizard #317 + feat(init): atomic-agents init wizard PR 2 of 2 — researcher + writer + Add-to-it #323). Better than the original --force design.
• getting-started.md integration → wizard documented as the recommended path (feat(init): #94 PR 1 of 2. atomic-agents init wizard #317).
• 3 starter templates → advisor / researcher / writer (feat(init): #94 PR 1 of 2. atomic-agents init wizard #317 + feat(init): atomic-agents init wizard PR 2 of 2 — researcher + writer + Add-to-it #323).
• Q4 autonomy preset (Cautious / Balanced / Autonomous / Customize) → covers spec/28 4-action-class policy at scaffold time.
• Doctor handoff + opt-in test call → wizard ends with doctor verdict + optional one-shot LLM call (feat(init): #94 PR 1 of 2. atomic-agents init wizard #317).

Tracked elsewhere:

• LLM provider question (original [init] OPERATOR_NOTES.md + opt-in judges/mandates/audits scaffolding + operating mode + location questions #142 Q4) is now init wizard: multi-provider support — Anthropic / OpenAI / Moonshot via flag, env-var autodetect, or question #324 (multi-provider support: Anthropic / OpenAI / Moonshot via env-var autodetect, --provider flag, or Q0 question).

Residual scope (this issue, post-rewrite)

1. OPERATOR_NOTES.md operator-commitment capture

A new operator-authored markdown file at the agent root, seeded by the wizard from the operator's Q&A answers, then maintained by the operator over time as a "what did I commit to and why" log.

Not framework-required. Not parsed by the framework. Pure operator artifact. The value is retrospective review: "I picked the Balanced autonomy preset because I thought I'd be okay with external sends going to judge_required. Three weeks in, I've discovered I want every send to escalate to me. Time to re-tune judges.md."

Seeded shape (from wizard answers):

# Operator notes — <agent-name>

Initial deployment: <date>

## Decisions made at scaffold

- **Mission**: <operator's Q2 answer>
- **Scope in / Scope out**: <Q3a / Q3b>
- **Autonomy preset**: <Cautious | Balanced | Autonomous | Customize>. Reason: <operator-supplied at Q4-followup>
- **Voice posture**: <Q5 answer>
- **Communication preferences**: <Q6>
- **Hard refusals**: <Q7>
- **Operating mode**: <reactive | goal-driven | hybrid> (NEW: Q3.5; see §2 below)
- **LLM provider**: <anthropic | openai | moonshot> (from #324)
- **Judge layer**: <enabled | not enabled> (NEW: Q8.1; see §3)
- **Mandates**: <enabled | not enabled> (NEW: Q8.2)
- **Responsibility audit**: <enabled | not enabled> (NEW: Q8.3)

## Things I haven't decided yet

- [ ] Persona stubs — IDENTITY/SOUL/USER are scaffold output; review and tune after first runs
- [ ] Tools.md write paths — defaulted per autonomy preset; revisit when adding side-effectful tools
- [ ] Cost guardrails — defaulted to template per-provider conservative caps; tune after first runs reveal actual cost shape
- [ ] Memory recall pattern — INDEX.md is empty; first notes seed the recall pattern

## Decisions deferred

(operator adds entries over time as they realize \"I should think about this later\")

## Operator log

(append-only notes as the operator iterates the agent over time)

2. Operating mode question (Q3.5)

Templates today carry an ## Operating mode section (PR 2 of arc Round 1 fix) but the mode is inherited from template choice: advisor and writer are reactive, researcher is hybrid. The operator can edit the section post-scaffold but the wizard doesn't ask.

Add a Q3.5 between Q3 (scope) and Q4 (autonomy) that asks the operator to confirm or override the template's default mode. Plain-English options:

• reactive (default for advisor / writer) — agent runs when the operator invokes it; no autonomous loop.
• goal-driven — agent pursues a multi-step goal across sessions; resumes on each invocation.
• hybrid (default for researcher) — agent is reactive day-to-day but maintains background investigations.

Wizard renders the chosen mode into persona/IDENTITY.md ## Operating mode section.

3. Opt-in judges / mandates / audits scaffolding (Q8.1 / Q8.2 / Q8.3)

After Q7, ask three optional yes/no questions:

• Q8.1: Enable the judge layer? (default: no) If yes, scaffold <agent>/judges.md with a starter config (defaults: external_side_effect: judge_required, high_risk: escalate).
• Q8.2: Enable mandates? (default: no) If yes, scaffold <agent>/mandates.md with a header-only file. Operator authors mandates post-scaffold per spec/29.
• Q8.3: Enable responsibility audit? (default: no) If yes, scaffold <agent>/audits.md with defaults from spec/30 §"Audit config file" (or wherever that section lands when spec/30 locks).

Most operators will pick "no" on all three. Power users running judge-gated agents, mandate-bound agents, or audit-tracked agents get the stub files at scaffold time instead of hand-authoring them later.

Update TEMPLATE_SECTION_SCHEMA in atomic_agents/init/constants.py to declare the optional file shapes so Add-to-it section detection handles them correctly.

4. Location question (Q1.5)

Wizard today uses get_agents_root() (env var $ATOMIC_AGENTS_ROOT or ~/.atomic-agents/); doesn't ask. Small UX gap for operators who want their agents next to a project directory.

Add an optional Q1.5: "Where do you want this agent? (default: ~/.atomic-agents/)" Accept any absolute path; refuse path traversal via existing safe_resolve_under primitive. Default stays the same; the question is a confirmation with override.

5. Doctor check_operator_notes informational check

Add a new doctor check that looks for OPERATOR_NOTES.md at the agent root. Informational only (does not affect overall exit code). Status: "present" / "missing" with one-line nudge to create one for retrospective review.

Operators who hand-built agents pre-#94 will see "missing." Operators who used the wizard will see "present." The nudge text suggests running atomic-agents init --notes-only <agent> (TBD subcommand) to retroactively scaffold OPERATOR_NOTES.md for a hand-built agent.

Acceptance criteria

• OPERATOR_NOTES.md template file added at atomic_agents/init/templates/_shared/OPERATOR_NOTES.md (the underscore-prefix marks it as not-a-template-name; shared across all template choices).
• Wizard seeds OPERATOR_NOTES.md from Q1 through Q8.3 answers via string.Template.safe_substitute.
• Q3.5 (operating mode), Q1.5 (location), Q8.1 / Q8.2 / Q8.3 (judges / mandates / audits opt-in) added to wizard.py with plain-English option labels.
• judges.md / mandates.md / audits.md template stubs ship at atomic_agents/init/templates/_optional/ (or similar; not under a specific template tree because they're opt-in across templates).
• TEMPLATE_SECTION_SCHEMA in constants.py grows to declare optional file shapes so Add-to-it detection handles them.
• doctor.check_operator_notes informational check shipped.
• Tests: smoke test confirming OPERATOR_NOTES.md is seeded with the right values; unit test confirming opt-in scaffolds the right files; doctor check test covering present/missing.
• spec/35 amended: new MUSTs documenting OPERATOR_NOTES.md seeding contract + optional file scaffolding contract.
• CHANGELOG entry.

Out of scope

• Multi-agent project scaffolding (separate concern; defer).
• Wizard-driven hand-build retrofit (the --notes-only subcommand mentioned above is a v1.1 follow-up, file separately if pursued).
• AI-drafted OPERATOR_NOTES.md content (overlap with [init] --ai-assist flag for LLM-drafted persona bodies (Approach B fast-follow) #318 ai-assist; if [init] --ai-assist flag for LLM-drafted persona bodies (Approach B fast-follow) #318 ships first, ai-assist can extend to OPERATOR_NOTES.md too).

Dependencies

• Best to ship after init wizard: multi-provider support — Anthropic / OpenAI / Moonshot via flag, env-var autodetect, or question #324 (multi-provider) so the OPERATOR_NOTES.md "LLM provider" line is real, not a placeholder.
• No hard dependency on [init] --ai-assist flag for LLM-drafted persona bodies (Approach B fast-follow) #318 (ai-assist) or [init] Claude Code skill /atomic-init wrapping the CLI (v1.1, Approach C) #319 (Claude Code skill).

Why this is worth keeping vs closing

The OPERATOR_NOTES.md concept has no other home in the backlog. It's a structural-quality affordance per the feedback_atomic_agents_best_not_cheapest discipline: low-cost to ship, durable value for any operator who iterates an agent over weeks/months. The opt-in judges/mandates/audits scaffolding piece is similarly orphan scope: every power-user surface today requires post-scaffold hand-authoring.

References

• docs/spec/01-anatomy.md — the file list.
• docs/spec/30-... — responsibility audit config (locked or RFC, check current state).
• docs/spec/29-mandate-backend.md — mandates.md shape.
• docs/spec/...-judge-backend.md — judges.md shape.
• feat(init): #94 PR 1 of 2. atomic-agents init wizard #317 + feat(init): atomic-agents init wizard PR 2 of 2 — researcher + writer + Add-to-it #323 — the init-wizard arc that shipped the bulk of [init] OPERATOR_NOTES.md + opt-in judges/mandates/audits scaffolding + operating mode + location questions #142's original scope.
• init wizard: multi-provider support — Anthropic / OpenAI / Moonshot via flag, env-var autodetect, or question #324 — multi-provider support (covers the original Q4 LLM-provider question).
• [init] --ai-assist flag for LLM-drafted persona bodies (Approach B fast-follow) #318 / [init] Claude Code skill /atomic-init wrapping the CLI (v1.1, Approach C) #319 / [polish] Migrate doctor / bundle / corpus CLI output to rich (spec/35 canonical primitive) #320 / init wizard: preserve YAML frontmatter on Add-to-it merge #322 — sibling init-wizard follow-ups.

[dep0we]

Amendment: OPERATOR_NOTES.md "LLM provider" line accepts expanded enum (2026-06-03)

Meta-issue #325 expands the framework's LLM provider catalog from 3 to 7 (adds Grok #326, Deepseek #327, OpenRouter #328, Gemini #329 in core).

OPERATOR_NOTES.md's seeded template:

- **LLM provider**: <anthropic | openai | moonshot | grok | deepseek | openrouter | gemini> (from #324)

Trivial amendment. No structural change to this issue's scope; the template line accepts the expanded enum at render time. Wizard-side consumer is #324; this issue's seeding logic inherits whatever enum #324 ships.