notescraft/specs/agents/README.md

Working with MiniMax M3.1 Flash agents

For the orchestrator (Claude Code or the owner). The agent-facing brief is minimax-m3-1-flash.md; the launcher prepends it to a task file.

Facts (verified 2026-10-20)

• Model id MiniMax-M3.1-Flash (the released model; the Preview id MiniMax-M3.1-Flash-Preview is retired in ~/.pi/agent/models.json). 1M context, text and image input, reasoning, Anthropic-compatible API at https://api.minimax.io/anthropic.
• Owner has no usage limit until 2026-10-25: use it freely, but keep at most 3 agents running at once (earlier 4-6 parallel agents hit 429 rate_limit_error (2062) and Pi then looped writing 300 MB logs).
• Response cap about 16K tokens: tasks must be sliced so one file is written per tool call.

Harness choice

Harness	Command	Use for
Claude Code harness (scripts/mm-agent.sh)	claude -p with ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN read from Pi's models.json, --setting-sources project, --strict-mcp-config	code tasks. Edit/Write/Bash/Task tools, reads AGENTS.md, --max-turns bound, stream-json log. Tested 2026-10-20: wrote a file through the Write tool on the first try. Prints a harmless "unrecognized model, assumes 200k window" notice.
Pi (pi -p --provider minimax --model MiniMax-M3.1-Flash --no-session --thinking low)		research with web search and fetch (default extensions on), and scripts/pi-wave.sh worktree waves

Recommendation: Claude Code harness for coding, Pi for browsing research. Both stay inside the same model quota.

Briefing checklist (a task file must have)

OWNS (paths the agent may edit), READ FIRST (files and spec sections), GOAL (one paragraph), API (exact signatures wanted), STEPS (ordered, each at most about 150 lines), TESTS (named cases), VERIFY (exact commands), DO NOT (scope fences). The more exact, the fewer rounds.

Review before accepting (orchestrator)

1. git status shows only OWNS paths changed.
2. cargo xtask ci green (fmt, clippy -D warnings, tests, layers, tree, i18n).
3. Grep the diff for unwrap(, expect(, [ indexing on input, panic!, hardcoded UI strings.
4. Read the tests: they must assert behaviour, not just run.
5. Commit only when the owner asks.

Known failure modes

• Stalls after a giant single write: slice the task.
• Declares success without running clippy: the brief demands the pasted summary line; check it.
• Edits shared files (lib.rs, root Cargo.toml): list them under OWNS explicitly or forbid them.
• Invents dependencies: the brief lists the approved ones.

Skills and rules shipped to the agents (2026-10-20)

CLAUDE.md imports AGENTS.md; .claude/skills/notescraft-* (agent-workflow, rust-safety, verify-loop, egui-screen, engine-command, sync-protocol) and .claude/rules/*.md (path-scoped: rust-never-crash, ui-egui, engine-and-vault, sync, tests). The Claude Code harness loads them with --setting-sources project. Keep them short and example-first; when an agent repeats a mistake, add the fix to the skill's table, not to the task file.

Lesson 2026-10-20: the cap of 3 counts every MiniMax process

Running 2 Pi research agents + 1 Claude Code harness agent + a fourth launched too early produced 429 rate_limit_error (2062) and killed a research run (mobile-platform, rerun as a continuation). Count Pi research and harness agents together; launch the next only after a completion event. Research agents must write the output file in appended chunks early, so a cut-off keeps a partial draft that a continuation run can finish.

Lesson 2026-10-20: disk

/Volumes/Storage hit 100% (225 MiB free) because target/agent-ui/debug/incremental held 29 GB (and deps 28 GB). scripts/mm-agent.sh now sets CARGO_INCREMENTAL=0. Check df -h /Volumes/Storage before launching an agent; delete only target/agent-*/debug/incremental (regenerable), never target/debug.

Lesson 2026-10-20 (2): effective concurrency is 1 harness agent

Two Claude Code harness agents at once (collab-ot + server-hardening) hit 429 rate_limit_error on every request (api_retry attempts 1 to 10) while a Pi research run was also active; the harness sends more requests per minute than Pi. Run harness agents ONE AT A TIME with scripts/mm-queue.sh name1 name2 ... (waits for the running agent, retries an agent that only saw 429s, clears incremental caches when disk is low) and at most one Pi research run beside it. The owner's "up to 3 subagents" is a ceiling, not a target.

Lesson 2026-10-20 (3): MiniMax plan quota (error 2067) and the GLM fallback

After about 2 hours of heavy use (4 research and coding agents) MiniMax answered every request with 429 rate_limit_error: The Token Plan usage limit has been reached (2067); this is the plan's own quota, not a burst limit (a direct curl with 20 tokens fails the same way), so waiting minutes does not help and the owner's "no limit until 25 Oct" did not hold for this key at that moment. Fallback: GLM 5.3 Flash on Ollama Cloud through Pi: scripts/pi-agent.sh <name> scripts/mm/<name>.md [provider model] (default ollama-cloud glm-5.3-flash). It embeds this brief and the six notescraft-* skills in the prompt because Pi does not load .claude/skills. GLM allowed 3 concurrent agents earlier (see memory agent-model-routing); run tasks with disjoint OWNS side by side. Check MiniMax again with the curl in this section before switching back: curl -s https://api.minimax.io/anthropic/v1/messages -H "x-api-key: $KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model":"MiniMax-M3.1-Flash","max_tokens":20,"messages":[{"role":"user","content":"say ok"}]}' (read $KEY from ~/.pi/agent/models.json, never print it).