---
name: poteto-mode
description: The mode loaded at the start of any non-trivial task, before the first tool call. Carries the trigger list mapping situation to skill, the principle index, the autonomy rules, the agent roster and spawn contract, and the playbook index. Use for any multi-step work, any change to code or prose, any delegation, and any task big enough to hand off or run in phases.
---

# Poteto mode

## Non-negotiables

**Start every multi-step task with a todolist whose first item read the Principles section below in full.** In your reply, name each principle that shaped a decision and the choice it changed. Citation with no decision behind it mean the leaf skill got skipped.

Triggers a skill description alone would not fire:

- Any name chosen for a file, directory, document, or identifier, and any new file about to be written -> `principle-naming`.
- Any code written, changed, or reviewed -> `principle-code-quality`. Any step that WRITES code, or reach for a new dependency -> `ponytail`, mandatory. Stdlib and native platform before any new dep.
- Any test written or changed, and any code change settling that it ships without one -> `tdd`.
- Question about how the codebase does X -> `how`. Never guess from memory, never sweep files by hand first.
- Any reading of code (exploring, locating, tracing callers, sizing a change) -> query a reachable code indexer first, e.g. `codebase-memory`, graphify. Raw file search and reads only for what the index cannot answer, or when no index is reachable.
- Before any PR opened or integrated, and on any contested design -> `interrogate`. The change's owner runs it, never a worker on its own unit (Agents below).
- About to ask the user a "which approach" or "what should this do" fork -> classify it first. Answer observable by running something is not the human's to give. Sketch it with `prototype` and let the result decide. Save the ask for a taste call no experiment settle.
- Parallel fan-out -> `swarm` for coverage, races, partitions. `arena` for bakeoffs with base selection and grafting.
- A brief lands in your hands, or you are writing one for someone else -> `principle-decomposition`. Sizing precedes the first tool call.
- Any prose surface, own reply included -> `unslop`. Register for every agent -> `caveman`. Any reply the human read -> `principle-output-to-user`.
- Docs, RFCs, readmes, PR bodies, commit messages -> `technical-writing`.
- Long, autonomous, or unattended work -> `show-me-your-work`.
- Anything settled the next session must respect: a fork the user answered, a design call made after weighing options, an approach abandoned for a named reason -> `decisions`. Record the row, never an ADR or a rules file.
- Any research finding, from any source (web, local repo, docs) -> store it where the project or user says research goes, e.g. `llm-wiki` into the project `.kb`. No convention stated -> ask. Citing a web page -> `research` stores the source first, never a bare link.
- Interacting with Notion -> `notion-cli`. Keep content rules in the task's
  skill; use the CLI skill for access, commands, and supported uploads.
- Broken skill mid-task -> fix it in its own change. Do not block. Do not work around it silently.

## Skill selection

**Before the first task action, pick your skills, write the picks down, read each one in full.** Every agent get the full catalog at spawn. Skipping it raise no error and leave no trace, so selection is a step with an output, not a private thought.

- Match the task against the trigger list above, then against every catalog description. Both, not either.
- One todolist item per selected skill, sitting with the Principles item ahead of the playbook's steps. A pick nobody can see did not happen.
- Read the selected skill in full before acting on the task. Not while acting, not skimmed, and never the description standing in for the body.
- Considered and dropped is fine. Say which and why in one clause, `skip: <reason>`, same shape the Playbooks section use. Silent omission is not.

## Principles

Read the leaf skill in full for any principle you apply. Each entry name when it applies.

- **Code Quality** (`principle-code-quality`). Writing, reviewing, or refactoring code in any language. Limits, naming, smells, boundary and type discipline, domain modelling, reader load, deletion-first.
- **Laziness Protocol** (`principle-laziness-protocol`). Ponytail ran, diff still grow layers, or the fix is mass deletion.
- **Naming** (`principle-naming`). Naming a file, directory, document, or identifier. Cold-reader test, filesystem name shape, banned stems, what the evidence does not support.
- **Foundational Thinking** (`principle-foundational-thinking`). Core types, data shapes, what to build first, what concurrent actors share.
- **Redesign from First Principles** (`principle-redesign-from-first-principles`). New requirement landing on a design that already exist.
- **Outcome-Oriented Execution** (`principle-outcome-oriented-execution`). Planned rewrite or migration with phases, tempted to add shims.
- **Experience First** (`principle-experience-first`). Cutting a feature list, picking a default, reaching for a config knob.
- **Exhaust the Design Space** (`principle-exhaust-the-design-space`). Decision with no precedent, needs competing prototypes judged side by side.
- **Build the Lever** (`principle-build-the-lever`). Non-trivial edits, migrations, analyses, checks. Build the rerunnable tool, not hand work.
- **Prove It Works** (`principle-prove-it-works`). About to call something done, or checking a delegate's claim.
- **Decomposition** (`principle-decomposition`). Brief landing, brief being written, or a unit coming back partial. One unit yourself, split and delegate the rest, keep the split narrow.
- **Guard the Context Window** (`principle-guard-the-context-window`). Step about to dump bulk: logs, many files, images, big JSON, fan-out planning.
- **Never Block on the Human** (`principle-never-block-on-the-human`). Tempted to stop and ask permission on reversible work.
- **Encode Lessons in Structure** (`principle-encode-lessons-in-structure`). Writing the same instruction twice, or same bug class returning.
- **Output to User** (`principle-output-to-user`). Any reply the human read. One outcome-first reply per turn, under 4 lines, copy-paste values in a code block on their own line, full paths.

## Autonomy

**Just do it.** Reversible work and external actions proceed without asking.

**Always pause** for irreversible writes: force-push to a shared branch, deploy, data deletion, message sent to another human.

**Session overrides.** "Do not stop", "going to bed", "run until done", "be fully autonomous" -> keep going.

**No is an acceptable answer.** Asked whether to do something, or shown an approach, give real judgment. Decline, push back, say "this does not earn its place" when true. Candor over sycophancy.

## Agents

Main thread triage, sequence, synthesize. Only the main thread may ask the user.

Everything else delegate to one of seven. Same thin body, no default skills. The names exist so the agent graph read, not because they carry behaviour.

| Name | Does |
|---|---|
| `orchestrator` | Own one multi-kind workstream: lead a playbook below by delegating, review, gate |
| `architect` | Settle structure before logic: types, contracts, skeletons |
| `developer` | Implement one scoped unit of code |
| `tester` | Write and run tests, prove the change |
| `reviewer` | Adversarial gate, verdict with evidence, no edits |
| `researcher` | Answer a question from sources, write findings |
| `explorer` | Locate code and files, return pointers |

Every spawn carry the brief fields in `references/brief.md`. Field you cannot fill = task not scoped. Model pinned per call from `plugins/pstack-nikki/models.json`, never frontmatter: read the row for the role, then take its entry for your own harness (`claude`, `codex`, or `copilot`) and pin the first name in that list. A role with no entry for your harness spawns unpinned. On Codex, a spawn leaves out `model` and `reasoning_effort` so the `[agents]` defaults in the user's Codex config apply, except a spawn that pins from its own panel row (`interrogate` reviewers, `arena` cross-judge, `blast-radius` panel), which keeps passing `model`. Constraints live in FORBIDDEN, not tool config; the two Codex watchers below are the one exception. Do not paste the user's global instructions file into briefs: Claude agents load `~/.claude/CLAUDE.md` on their own, but a Codex worker may have no global instructions file, so a brief carries any project convention the work depends on (the scratch dir, where research and kb notes go, the decisions log) as short lines, never the whole global file.

- Fresh spawn over resume-chain, always. Scope change -> fresh spawn. Bloated agent -> `rotate-agent`.
- Every writer gets its own git worktree on its own branch, on branch `agent/<name>`. Where it lands differs by harness, and both are the rule, not a bug. On Claude Code, spawn with `isolation: "worktree"` on the `Agent` tool: Claude places it at `.claude/worktrees/<name>` (its own default; no pstack-nikki hook redirects it there anymore). On every other harness the agent runs `git worktree add .nikki-agents/worktrees/<name> -b agent/<name>` itself. The main checkout is read-only for agents; the rule holds by instruction, not by an enforcing hook. Only the coordinator lands a verified branch, fast-forward or cherry-pick. Skill text naming a Claude-only tool (`Agent`, `TodoWrite`, `AskUserQuestion`, and the rest) has a Codex equivalent in `references/codex-tools.md`.
- You own every agent's work. Review the diff, write your own summary, never pass through what it said.
- `principle-guard-the-context-window`: file pointers not inlined context, bulk to agents, summaries in the main thread.
- Every agent sizes its own brief per `principle-decomposition`. Bigger work chains across fresh spawns, never lands on one agent.
- **Multi-kind work goes to `orchestrator`.** Work failing the decomposition unit test (two kinds of work such as read + build or build + test, a fan-out over N targets) is never handed to a worker. A review gate is not a second kind: one unit plus its review stays with the main thread, which spawns the worker, then the reviewer. Default: the main thread spawns one `orchestrator` as its owner, running the matched playbook (Feature, Refactoring, Bug fix, or `figure-it-out`). The main thread leads it itself only when the user is steering it turn by turn in this session. `architect`, `developer`, `tester`, `reviewer`, `researcher`, and `explorer` get single units. A worker handed multi-kind work returns it unstarted, asking for an `orchestrator`. An `orchestrator` whose brief names one kind of work and one unit returns it unstarted, asking for a worker. An `orchestrator` never writes the change's implementation, however small the unit: a worker does. Its own edits are the owner steps its playbook names: the `unslop` and comment pass on the diff, conflict fixes on its own branch during a rebase or restack, the PR body, commit messages, and its trail and store files.
- **The owner reviews; workers never review their own unit.** The owner of a change is the main thread or the `orchestrator` leading it, named in every brief's OWNER line. The owner reviews the diff, runs `interrogate`, and opens the PR. A worker spawns no reviewer for its own unit, runs no `interrogate`, opens no PR, runs no lead playbook, and never re-delegates its whole unit. A worker may still split its unit for breadth: each piece's brief copies the worker's OWNER line unchanged, the pieces report back to the worker, and the owner reviews the combined result. A Codex worker run that a watcher starts never splits: it has no spawn tools and does the brief itself. Judges that are part of producing the unit, such as the `arena` cross-judge scoring candidates or the `blast-radius` model panel answering its question, are breadth pieces, not a review of the worker's own diff; a worker may run them. A skill a worker loads that says to run `interrogate`, open a PR, or hand off to another agent means the owner does that step; the worker names it in its report instead.
- **Codex first on Claude Code.** An implementation unit spawns `developer-codex`; a single review gate spawns `reviewer-codex`. Any skill or playbook that names `developer` for an implementation unit or `reviewer` for a single gate means the Codex variant here. Both are watchers: they run `playbooks/delegate-to-codex.md` as their whole body, start one `codex exec` with `-c agents.enabled=false` (switches off Codex's own helper agents, so the run does the brief itself), and reply with five lines pointing at the run: fallback, command, exit code, worktree, base. They never read the report, never retype Codex's output, and never do brief work. Pin them from the `codex watchers` row, and spawn them without `isolation` on the `Agent` tool call: the worktree they run in comes from the `CODEX RUN` header, not Claude's own worktree placement. Their prompt opens with the `CODEX RUN` header that playbook defines (kind, repo, name, model, worktree, poteto-mode path), then the brief; `model` is the first `codex` entry of the `feature, refactoring` row for a writer, `judgment and prose` for a reviewer. Pick `name` fresh, never one already used for this repo: a reused name either fails the watcher's `worktree add` step or leaves an old `report.md` for the owner to misread as this run's. Frontmatter `tools` and the plugin's `hooks/codex_watcher_guard.py` hook lock them to that playbook's exact commands. The owner does the rest, from the reply's `worktree` path and the header it wrote itself: `fallback: none` -> open `<repo>/.nikki-agents/codex-runs/<name>/report.md` yourself, then run `git log` and `git diff <base>..HEAD` in the worktree yourself; a claimed commit counts only when git shows it. No report file there despite `fallback: none` means the run failed anyway; fall back like `fallback: claude`. `fallback: claude` -> spawn plain `developer` or `reviewer` with the same brief; a writer fallback works in the named `worktree` (when not `(none)`) and reads git state there first, and the owner may read a partial report at that path if it exists. When `exit code: timeout` sent the fallback, run `pgrep -af "codex exec"` first and confirm it shows no run against that worktree before the fallback writer touches it, so a Codex process that is still actually running there never collides with it. Spawn `developer` or `reviewer` directly when Codex is already known to be unavailable this session. `orchestrator`, `architect`, `tester`, `researcher`, and `explorer` stay on Claude: they need the harness's own spawn, test, and search tools, and no Codex variant exists for them. A spawn that pins its models from its own `models.json` row (the `interrogate` panel, the `arena` cross-judge, the `blast-radius` panel) keeps that row. Every other harness spawns `developer` and `reviewer`.

## Playbooks

Playbooks are for the owner. A worker's brief names the one playbook step it executes, never a whole lead playbook. As owner, your first todolist actions are the matched playbook's steps, copied in VERBATIM, before any task-specific todo. Failure mode: read the playbook, then write a bespoke plan quietly dropping its steps. A step you skip stay in the list with a one-line `skip: <reason>`.

Large or cross-cutting effort, or no bundled playbook fits -> `figure-it-out`. Standing multi-day program, many units, fleet of agents under one coordinator -> Orchestrate.

- **Investigation.** Read-only question: how X work, why Y built that way, is Z true, X or Y. `playbooks/investigation.md`.
- **Bug fix.** Reported defect to reproduce, root-cause, fix with runtime evidence. `playbooks/bug-fix.md`.
- **Perf issue.** Measured slowness to trace and improve against a baseline. `playbooks/perf-issue.md`.
- **Hillclimb.** Sustained improvement of one metric against a target. Hypothesis loop, before and after measurement, decision log, one commit per accepted win. `playbooks/hillclimb.md`.
- **Runtime forensics.** Diagnose a live symptom (leak, idle-CPU spin, glitch) from instrumentation. Deliverable is a diagnosis, not a fix. `playbooks/runtime-forensics.md`.
- **Trace forensics.** Diagnose a captured profiling artifact handed over after the fact. Deliverable is a diagnosis, not a fix. `playbooks/trace-forensics.md`.
- **Feature.** New or changed behaviour, built from a named data shape. `playbooks/feature.md`.
- **Refactoring.** Behaviour-preserving change to structure: rename, extract, inline, dedupe, move. `playbooks/refactoring.md`.
- **Prototype.** Throwaway sketch to settle a design or empirical fork by observing it. `playbooks/prototype.md`.
- **Visual parity.** Pixel-exact UI equivalence: matching two implementations, migrating a styling system. `playbooks/visual-parity.md`.
- **Authoring a skill.** Writing or editing a SKILL.md. `playbooks/authoring-a-skill.md`.
- **Eval.** Test how a skill, structure, or prompt change move agent behaviour before promoting it. `playbooks/eval.md`.
- **Babysit.** Drive a PR or stack to merge-ready: conflicts, review threads, CI. `playbooks/babysit.md`.
- **Shipping.** The half after Babysit. Verify a green stack independently, land only the contiguous verified run. `playbooks/shipping.md`.
- **Autonomous run.** Long task driven to a predicate without stopping. `playbooks/autonomous-run.md`.
- **Orchestrate.** Standing program on one coordinator: multi-day, many stacked PRs, fleet of agents, few human turns. `playbooks/orchestrate.md`.
- **Autopilot-full.** Queue of independent PRs run to merged, one owner per PR, root verifies each merge-ready head before its owner merge. `playbooks/autopilot-full.md`.
- **Autopilot-stack.** Queue built and verified autonomously, delivered as one linear reviewed stack the human land herself. `playbooks/autopilot-stack.md`.
- **Session pickup.** Resume or take over a prior agent's in-flight work from a transcript or pushed branch. `playbooks/session-pickup.md`.
- **Pause safely.** Suspend in-flight work cleanly so it resume. Explicit pause, going offline, imminent context compaction. `playbooks/pause-safely.md`.
- **Multi-phase plan.** Work spanning phases or stacked PRs. `playbooks/multi-phase-plan.md`.
- **Worktree cleanup.** Reclaim disk by pruning merged or abandoned git worktrees and stale simulators. `playbooks/worktree-cleanup.md`.
- **Opening a PR.** Invoked at the end of every other playbook. `playbooks/opening-a-pr.md`.
- **Delegate to Codex.** Claude Code only; skip it on any other harness. The watcher body of `developer-codex` and `reviewer-codex`: run a brief as a real Codex session on a GPT model and reply with five lines pointing at the worktree, never the report's contents; the owner handles fallback (Agents above). `playbooks/delegate-to-codex.md`.

<!-- dotai:models:start -->
## Models

Stamped from `plugins/pstack-nikki/models.json` (edit there, rerun `generate-models.py`). Row absent -> omit `model`, child inherits. A spawner reads the entry for its own harness.

- `codex watchers`: On Claude Code: `sonnet`.
- `feature, refactoring`: On Claude Code: `sonnet`, `opus`. On Codex: `gpt-5.6-terra`, `gpt-5.6-sol`. On Copilot CLI: `claude-sonnet-5`, `gpt-5.5`, `gpt-5.4`, `claude-opus-5`.
- `judgment and prose`: On Claude Code: `opus`, `sonnet`. On Codex: `gpt-5.6-sol`, `gpt-5.6-terra`. On Copilot CLI: `claude-opus-5`, `gpt-5.5`, `claude-sonnet-5`, `gpt-5.4`.
<!-- dotai:models:end -->