Agent workflow & collaboration — recipes

On-demand recipes (56). Each is a trigger→action heuristic; pull the relevant one when its situation arises. Tier tags and ⚠ (unverified) as in AGENTS.md.

1. Treat every doc name, claim, and structural survey as unverified until re-diffed against live source

loop

Every path, command, client-method, request-model name, behavior claim, parser vocabulary, pipeline-diagram step, and enumerated API/export list in a player's docs (PLAN/DESIGN/README/AGENTS.md/COOKBOOK/reviewer feedback) is an unverified hypothesis: ls the path, grep the symbol, walk the actual code's step order, source the action/observation vocabulary from the live parser, and diff against current source before trusting it, because players/bots/docs get moved or renamed often (crewborg's AGENTS.md pointed at COWORLD_README.md under packages/coworld/src/coworld/ when docs had moved to packages/coworld/docs/; a referenced scripts/capture.py belonged to a different player; a README promised mode completion/stalling decide() never implemented; an audit found docs listing trace-adapter names absent from code, omitting real modules like coworld_json_bridge.py and classes SharedMemoryView/AsyncStrategy/StrategyRunner, and listing events the SDK never emits; a pipeline diagram omitted a config-gated role-rebalancing step). Run a separate audit pass per error class (naming, paths, structure, protocol, status) rather than one generic pass, and re-read docs before finalizing because they drift on disk mid-session (a diagnoser design doc grew from 12 to 103 lines between two reads). When porting or restructuring from a fast-moving source, your initial structural map goes stale, so re-diff EACH module against live source as you port it (two parity bugs: a sub-state record missing fields the source had since added after it grew ~93 lines, and ported threshold logic that dropped an early-out) and copy the source's NAMED tuning constants (Crewmate*-style) rather than inlining literals, which silently breaks parity. Cross-check the live working tree against git status, not a memory note or README: a dirty checkout can list policies (modulabot, old cogames wrappers) only as deleted tracked files gone from disk, and 'framework exists' is not 'framework is intact' -- a live run failed because a cogames-agents checkout had many tracked files deleted yet still imported partially. Distinguish 'present and usable now' from 'tracked upstream / deleted locally'. For recovered/legacy tools, read actual imports and asset-path logic, not the header (one claimed PYTHONPATH=among_them was needed when the script self-located via Path(file).resolve().parent.parent, and listed Pillow though only pygame and numpy were imported). _{sources: auggie:02627f61-aac0-42a0-a290-3595e010abba, auggie:5d1ff8d5-2505-4dca-af45-56d3070363e2, auggie:c5674179-5e48-4584-a7a9-f75d2cd3c61b, auggie:f0d3adc1-1e28-4400-a8fb-94959c6722b5 (+11)}

2. Resolve doc contradictions by reading authoritative source, never by averaging; never document phantom limitations; then fix the code gap

generic · negative result

Source is authority on current behavior. Resolve contradictions between docs, sibling docs, or independently-generated drafts by reading the authoritative game-engine/SDK source and picking the correct answer, never by averaging or hedging; prefer the draft carrying concrete values, types, file paths, and function names (one reporter's DESIGN.md said the event-log player column was int16 while its sibling README said int64, the canonical value). For Coworld role work the authoritative contract lives in metta (e.g. reporter contract at packages/coworld/src/coworld/docs/roles/reporter.md; cross-check docs/roles/<role>.md, COWORLD_README.md, types.py for schema, GAME_RUNTIME_README.md for env contracts, certifier.py for what validation runs) and a player repo's READMEs merely restate it. Do NOT document limitations or fallback paths the agent never exercises: a DESIGN.md falsely listed 'missing JSON fallback' as a P0 limitation, but the agent never serves the JSON protocol, so a non-binary first message would be a runner misconfiguration, not an agent gap -- phantom limitations send future work in the wrong direction. Before implementing from a design doc, reconcile its internal contradictions and conflicts with code as the bug to fix (a doc said a mode had 'one required method' in one section but required mode_enter and mode_switch_cleanup elsewhere; a doc said a target 'is kept for at least N ticks before re-selection' when code never re-selected; a spec claimed a per-object 'extra' dict persists across resets when it was a dataclass field reset to {}). After reconciling docs to source, the CODE is often the new gap (with docs now saying int64, among_them_summarizer.py and paint_arena_summarizer.py still used pa.int16()): flag that as the next task rather than treating doc alignment as done, and when code under-delivers vs intent, implement the intent AND update the doc to the new actual behavior in the same change. Maintain separate living docs (intended-behavior design, a source-verified impl plan with a dated current-gap list, migration docs) so later phases never silently depend on undelivered features. _{sources: bitworld/among_them/players/mod_talks/LLM_VOTING.md, personal_labs/crewrift_lab/crewrift/crewborg/docs/designs/suspicion.md, players_checkouts/players/users/james/personal_cogs/persephone/agents/, auggie:c5674179-5e48-4584-a7a9-f75d2cd3c61b (+11)}

3. Re-verify subagent file:line citations against source; anchor reference docs to a Source Map

generic · ⚠ session-derived, unverified

Personally re-verify load-bearing claims and file:line citations from a research subagent against source (direct Read plus targeted grep) before turning them into a design doc: a subagent reported crewrift killer attribution as 'lost,' but reading recordKill(killerIndex), addReward(killerIndex, KillReward), and the killCooldown reset (sim.nim:2553-2555) showed the single-kill case IS recoverable from post-tick state. For a large Nim source (sim.nim ~10k lines), fan out parallel focused research subagents that each return file:line citations, then cross-validate their reports against each other on load-bearing facts (object-id bases, the camera-from-map-object trick, the walkability sprite, edge-triggered input) before accepting any claim. Anchor every claim in the resulting reference doc to a source file and line range via a 'Source Map' table (frame size, packet bytes, button bits, config validation, game-over transition -> source locations) and cite every source file a snapshot doc depends on, so the doc is verifiable and survives engine/platform drift. _{sources: claude-code:27659fc3-8e40-469f-beda-31ddd5c6ceca, claude-code:3dd8c20f-7122-4a7c-9400-e9b7f6799a28, claude-code:c3f94a33-5444-4aba-8885-1e452bdb7514, claude-code:cb446cb3-1370-4f0b-9de6-34f05b9e5880}

4. Game-policy design docs drift from code FAST: verify field-by-field, re-measure baselines, pin the default-lean contract

loop · negative result

Game-policy design docs drift from code fast; treat every numeric tuning value and emitted-trace field as suspect until checked against source. One pass found: wrong scratch-state field counts (an undocumented huntKillConfirmed flag), a trace event documented with richer fields than code emitted (code emitted only target_color), a tuning constant documented in one place when it lived in two, a stale path-lookahead constant, a temporal-memory doc still labeled 'not yet started' after shipping, territory features still called 'untapped' after being parsed, a policy docstring claiming the wrong version, and a doc claiming 191 tests when the real baseline was 214. Re-measure baselines and re-read code rather than trusting documented numbers. Drift on trace/log DEFAULTS is especially dangerous: a doc still calling a verbose per-tick stream 'lean' or 'the default forensic stream' leads a future agent to re-enable the mode that blew past the log cap -- update docs in the same change AND add a test pinning the default-lean contract so the regression cannot creep back. _{sources: alpha_cog/audits/research-audit-2026-05-04.md, codex:019e00c0-d889-7d72-9781-3e90e7c1c7b9, codex:019e0140-e554-78e3-b66f-80634cc63f5d, codex:019e037c-5f9b-7ad1-8bf3-539709c4da15 (+9)}

5. Run doc-vs-code reconciliation as research hygiene targeting load-bearing files; audit version labels separately from flags

loop · ⚠ session-derived, unverified

Each iterate-loop session starts by reading docs and forming hypotheses, so stale docs misdirect future work -- run a doc-vs-code reconciliation before the next experiment, targeting the load-bearing files: the always-loaded agent file (shipped flags, code org, stage pipeline, policy classes), the strategy doc (current-state/next-steps recent experiments may have invalidated), the navigation-design doc (must reflect the latest fix, not the superseded approach), and the experiments README. Audit version LABELs separately from feature-flag lists (people update flags but forget to bump the label, causing 'V9' vs 'V10' mismatches) and cross-check the live flag set against the matching policy class in the historical-policies module. Distinguish stale code-referencing doc strings from genuinely-correct field-name references before 'fixing' them -- some 'chatroom' references were stale UI terminology (now 'WHISP'/'whisper') but others correctly referenced an actual chatroom field still named that in perception types. _{sources: opencode:ses_1ff5c89a6ffe2a8C5jUiIdLK4l, opencode:ses_1ffc701efffeS5c5ueXd2vWIkD}

6. Edit the design doc first; keep it current-state, scope AGENTS.md tightly, delete interim plan docs

generic · ⚠ session-derived, unverified

When editing a contract-bearing repo, treat the design doc (e.g. docs/REPORTER_DESIGN.md) as the source of truth and edit it FIRST before touching implementation or tests; after scoping with the human, ask outstanding design questions explicitly one-by-one before drafting a decision entry rather than batching assumptions. A living spec must read as CURRENT STATE not narrated history: confine evolution to the decision log, mark superseded rows inline, and after an iterative conversation rewrite the messy doc into a formal spec tuned for coding-agent readers. Keep a player's AGENTS.md scoped to what is needed to write effective code -- fold researched answers in rather than leaving an 'open questions' section, and strip leftover template-mirroring language (among-them/coborg references) once the player has its own design. James wants interim planning/correction .md docs DELETED once their work lands, not archived (GRADER_REPO_CORRECTION_PLAN.md and PAINT_ARENA_COGS_V_CLIPS_GRADER_PLAN.md were removed in the final commit) -- treat plan .md files as scaffolding to remove. _{sources: auggie:a1385085-652c-4b2c-a080-791afa05f93b, claude-code:48add98e-a83d-4348-97bf-0079c48c42d6, claude-code:c6965c58-2cb9-46fb-8b29-bad3f3e9e77f, claude-code:cb446cb3-1370-4f0b-9de6-34f05b9e5880 (+1)}

7. Resolve design open questions one at a time by blast radius, then propagate to every doc

generic · ⚠ session-derived, unverified

Resolve design-audit / open-question items ONE at a time, tiered by strategic blast radius (highest first), driving each to a decision before the next, and keep each finding scoped (don't blur a chat-packet fix into a task-status finding) so each edit stays reviewable. When an answer changes a mechanic, propagate the correction to EVERY document that states it (design doc, rulebook, game API) with a source citation or the docs re-diverge. Re-verify against real game code before editing the doc. Audit a high-level design against its per-role strategy docs, not in isolation -- the implementable thresholds live in the strategy docs and the gap to the design's contentless 'mode' is the actionable output; organize findings by severity (CRITICAL = cannot implement without resolving). _{sources: codex:019dfe49-9c5e-76c0-86b8-99fbc2cf01b3, opencode:ses_1fb148d00ffe5ob6k0yKT3aHke, opencode:ses_200bab964ffe5MjqDy3HjInDmF, opencode:ses_1fb8906dcffete6Fy63Vc7IEPv}

8. A protocol migration is a cross-cutting doc pass; point docs at one spec but keep negative-contrast notes

loop · ⚠ session-derived, unverified

A contract/protocol migration leaves stale claims scattered across many docs (per-component READMEs/DESIGN files, a repo-level migration table, root README, PLAN.md), not in one constant; flipping them all is a separate cross-cutting documentation pass the migration plan rarely surfaces, so budget for it. Point each doc at the single source-of-truth spec rather than restating the protocol inline, but KEEP explicit negative-contrast mentions (e.g. 'NOT the JSON coworld.player.v1') because those document why the agent does not share the SDK's JSON bridge. Consolidate parallel strategy/validation docs to one canonical version in the same pass (delete the pointer/index file, rename the real doc to strategy.md, fix cross-references) and keep any validation command list complete and identical across every doc that lists it (one player's full suite was test_expanding, test_gathering_mode, test_spatial_territory, test_role_negotiation, test_talk_protocol, test_memory_death, test_frontier_phase; docs listing a subset were the drift found). _{sources: auggie:c5674179-5e48-4584-a7a9-f75d2cd3c61b, claude-code:1402d3ec-c565-4576-ba22-97942b9f9d0b, claude-code:27984094-3b9e-4e67-92c5-da2a61ceb32a, claude-code:b1fb3772-05cf-4de7-b1d7-a0732e2a61e3}

9. In a shared worktree, scope strictly to your files and leave sibling agents' in-flight work untouched

loop · ⚠ session-derived, unverified

In a multi-agent workshop/worktree repo, sibling agents' in-progress edits appear as pre-existing uncommitted/untracked changes in files you are about to touch. Before editing, re-read live file contents and run git status/diff; scope your patch strictly to files your task owns, make additive-only changes, and leave all pre-existing dirty/untracked state untouched -- reverting to a 'clean' baseline destroys other agents' work and assuming a clean baseline clobbers in-flight work. When staging/committing, scope to the player subtree, stage only your own hunks (do not commit when unrelated uncommitted work sits in the parent repo), check the staged set, call out pre-existing changes so they are not mistaken for yours, and clean up only your own generated test artifacts. Pre-existing test failures that trace to files other agents modified are NOT your regressions: run the focused test subset for your feature first to confirm it is green, then run the full suite only to capture complete state, and do not 'fix' failures you did not cause. _{sources: auggie:02627f61-aac0-42a0-a290-3595e010abba, claude-code:91060045-312c-4787-9819-a1421d228d61, claude-code:b09cd025-18e0-41cc-abe0-039562b0ab0d, codex:019e004f-1647-77a1-9e58-fa29c8f8ef89 (+7)}

10. Respect blast-radius limits: do not edit shared/load-bearing modules; build stage N additive-only

loop · ⚠ session-derived, unverified

Respect explicit blast-radius limits in shared game-bot repos with many sibling players: touch only the targeted agent's files and do NOT edit shared belief/tuning/types modules, which are load-bearing across multiple bots -- unscoped edits there risk cross-bot regressions and get reverted. A hard 'MAY MODIFY / MUST NOT TOUCH' file-scope contract plus a 'if you need to change an off-limits file, STOP and report' rule lets parallel stage builders land changes with zero collisions. When building stage N on top of a shipped stage N-1 (or adding a helper to a shared state object like ActionMemory), read the prior modules first to get real signatures rather than guessing, make the change additive-only (do not alter existing fields, semantics, or clear() behavior), add only the new stage's files/tests, then run BOTH the new stage's tests AND the prior stage's contract tests, and verify protected files' diffs are empty at the end. _{sources: codex:019e0138-b924-7210-98fd-3fb3ada47fe9, codex:019e031e-f7d3-7342-a7d9-96993bc91097, codex:019e0374-ec44-76d0-89a6-d8ec407a8894, codex:019e03bc-5520-7e72-aa5c-a572ead62b91 (+1)}

11. On a tightly-specified task, resist scope creep and keep the diff attributable

generic · ⚠ session-derived, unverified

Touch only the named files, inspect only the small API surfaces you actually call (registry, pipeline hooks, frame parsing, evaluators), make the minimal change, then run the exact verification command specified and confirm the expected pass line. Do NOT refactor or compact unrelated code after tests go green, and do not bundle unrelated improvements into a single-bug fix -- the extra diff gets reverted; keep it to the bug plus a focused regression test. Honor explicit scope-limiters like 'do not read DESIGN.md' or 'do not refactor after tests pass'. Target the directory/module structure the TASK specifies, not the layout sketched in the design doc (e.g. an explore_views/ package vs a doc's top-level sketch). _{sources: codex:019e081d-ff5d-7111-90ab-9b441207a6ee, codex:019e0850-a17c-7021-b7fc-31f3ece88326, codex:019e0904-6125-7dc1-9dc9-5c8dea8c59eb, codex:019e090d-a88d-76f2-b1f5-cd3e4eda9381 (+2)}

12. Watch for collateral edits riding along a focused change; diff before declaring done

generic · ⚠ session-derived, unverified

Trimming or compacting a change can sweep in unrelated edits: deleting one completed TODO entry can accidentally drop adjacent unrelated TODO sections. Before finishing, diff carefully and restore any deletions outside requested scope; reconcile docs by removing only the completed TODO entry matching the now-finished work. Also re-read live source before editing a self-contained scripted agent to confirm current state rather than assuming a prior change already landed, and keep generated plan/spec/doc files ASCII-only (box-drawing characters in directory trees were flagged and replaced with plain ASCII). _{sources: codex:019e04e9-a838-7fe1-aa8a-fdb7d67de0b4, codex:019e04d1-5052-7b42-907f-c0a2e3d539a8, codex:019e0691-0971-7623-9fb2-5b1aed778856}

13. Implement new behavior units by copying a sibling and reusing the shared contract

loop · ⚠ session-derived, unverified

Before implementing a new behavior unit/module in a layered player policy, read an existing sibling unit and surrounding files: copy its style and integration glue (how it signals completion, how directives are consumed, naming/export conventions) and reuse the shared constants module (e.g. ext_keys.py) rather than inventing a new mode contract or redefining constants. Implement a new mode as a standalone file with small local helpers (role/team coercion, target selection, event checks, completion signaling) rather than mutating shared state dataclasses, keeping the change isolated. Drive the dataclass fields/enums/ext-keys from the doc's or task's data-shape contract, not invented names, since mismatched field names surface later as silent bugs in strategy code that reads them. _{sources: codex:019e0817-8cba-79c2-aed4-d8bb6a4261d0, codex:019e05e2-eadc-70a1-a58f-add2c62f1046, codex:019e05c4-f9e2-74d0-bcd3-53bbf33c209b, codex:019e05ef-a042-79c3-aa22-fd78a9e2333d}

14. Rewrite toward a known-good sibling bot rather than deepening a broken approach

generic · ⚠ session-derived, unverified

When stuck on a hard mechanism (cross-thread result delivery, a movement controller), find a sibling policy in the same codebase that already exhibits the desired behavior ('its movement is basically perfect') and reverse-engineer/port its mechanism rather than inventing new machinery. Comparing the broken policy against a known-good one surfaces the exact missing mechanics (velocity tracking, coast prediction, active braking, velocity-gated interaction). A simpler rewrite based on a known-good bot is often the right answer. _{sources: opencode:ses_1fc949520ffe2UNDsOqbbL5T9a, opencode:ses_21b008642ffeCM6Q48G44aM6k0}

15. Never trust a delegate's or prior turn's 'done'; verify against disk and the real environment

generic · negative result · ⚠ session-derived, unverified

file_change events in a run log indicate INTENT, not persisted changes: an apply_patch verification failure plus a timeout lost most generated edits (7 test files plus a belief_update module) while the log still showed them changed, and only the first two fixes persisted. After any large multi-file edit or delegated run, reconcile from ground truth with git diff / git status -u before declaring done; do not resume from where the agent claims it left off. Sandboxed delegates (Codex and similar) cannot run live/integration tests needing a network server (Node.js, websocket), so a green delegated run is unit-level signal only -- re-run the real integration/live match yourself in the actual environment before believing it. _{sources: codex:019e03bf-6d47-7093-a40b-351c325bde5a, opencode:ses_1fc4873c9ffewN1hHBGGZTZiST, opencode:ses_1fed7bbaaffe4qARc9KvRdpGAC, opencode:ses_1fa63b520ffeQP7WMCZiDebllG (+1)}

16. Codex headless times out mid-self-refactor; capture thread_id and resume

generic · negative result · ⚠ session-derived, unverified

codex exec frequently times out on a single phase even at a 10-minute bash timeout, especially when it self-initiates a refactor/compaction after a first working version: it writes a file, tests pass, then deletes the file to compact it and times out mid-recreation, leaving the file GONE. Capture the thread_id from the initial thread.started JSON event so you can resume with codex exec resume <thread_id> "..." --json (resumed sessions reliably finish, e.g. recreating the deleted file); set a generous timeout (max ~10 min) and budget for at least one resume; treat 'timed out while printing the file for review' as success if import/test checks already passed, and verify the artifact on disk. _{sources: opencode:ses_1fa65507bffexDcakAPT4pHA1d}

17. Drive multi-agent build waves from the module DAG; sequence anything sharing a file

generic · negative result · ⚠ session-derived, unverified

Parallel sub-agents that invoke a coding tool via shell SHARE the workspace and run shell commands concurrently, so two agents editing the same file race and corrupt each other's edits, and writes to a shared file (e.g. TODO.md) are last-write-wins. Only parallelize stages whose file sets are provably disjoint -- realistically only true leaf modules (geometry/OCR/sprite-match/frame helpers, ~half the code) parallelize cleanly for ~2-3x, not 10x; layers above perception are serially dependent. Compute the unblocked-stage set from the plan's dependency graph, run that wave, verify with diffs plus unit tests, commit per stage, then recompute the next set. When stages must touch one file, partition edits precisely up front and state boundaries in each prompt (e.g. 'Stage 5 inserts hook calls into pipeline.py; Stage 4, leave pipeline.py untouched'). Verify a subagent type actually has write/edit access with a one-shot test first. _{sources: opencode:ses_1fed7bbaaffe4qARc9KvRdpGAC, opencode:ses_1fb1787afffemhwtF09UMzPc5V, opencode:ses_224322057ffexj7SYlcfVA0zgy}

18. Inline load-bearing context for delegates and demand file:line proof for their claims

generic · ⚠ session-derived, unverified

Minimize a delegated coding agent's file-reading time by inlining the load-bearing context (dataclass definitions, belief-state shape, the exact functions to implement) directly in the prompt rather than only pointing at file paths. Conversely, do not accept a subagent's mechanism claim (e.g. 'gear stations check vibes') without code-level proof: require exact file:line citations to handler filters/mutations -- holding that standard forced a retraction of a wrong claim. Sub-agent # TODO markers for behavior that genuinely needs live-game data are expected handoffs to the iterate-on-live-episodes phase, not defects, but track them in a TODO doc. _{sources: opencode:ses_1fa65507bffexDcakAPT4pHA1d, opencode:ses_223c540d9ffe8nF6kcU1RXf0wp, opencode:ses_1fed7bbaaffe4qARc9KvRdpGAC}

19. Prove a 'merged' stacked PR actually reached main before deleting the branch

generic · ⚠ session-derived, unverified

GitHub's MERGED label and gh's state field lie about Graphite stacks: a Graphite squash-merge can show state CLOSED with mergedAt null, and a stacked PR whose base is another stack branch (not main) merges its squash commit into that base, so if an earlier sibling was squash-merged to main first, the later PR lands on an orphaned base and its work silently never reaches main. Before deleting a 'merged' branch, prove the code is on main: git merge-base --is-ancestor <branch-tip> origin/main (expect yes), confirm a branch-new file exists in origin/main, and check the two-dot diff origin/main..<branch-tip> is empty. To recover work that never reached main, KEEP the branch (its tip holds all the work) and either open a fresh PR from it targeting main directly or cherry-pick the tip onto a new branch off current main; do not delete the branch first. _{sources: claude-code:3837ef5e-3e9c-41bc-b290-df5865581698, claude-code:f42b7a73-a78a-4277-8d09-d3c64bbe415e}

20. Graphite/PR mechanics: gt track parents, point origin at GitHub, dry-run, protect un-pushed commits, diff huge PRs per-file

generic · negative result · ⚠ session-derived, unverified · tool: gt (Graphite CLI)

Chaining PR base branches on GitHub does NOT make them a Graphite stack: Graphite tracks parents in its own local metadata, so register them with gt track (metadata-only, safe), and clear bogus 'needs restack'/'N ahead' state by resetting local main to the GitHub commit (preserving local-only commits on a side branch first). gt submit pushes/fetches against the 'origin' remote regardless of per-branch upstreams and infers repo owner/name from origin's URL, so a local-clone origin makes submit unreachable (GitHub API 404) and submit refuses when local trunk main does not match origin/main -- rename the local-clone remote and point origin at GitHub before submitting (or override owner/name in .git/.graphite_repo_config), and move work commits onto the feature branch / realign main to origin/main. Run a gt submit dry-run first to catch stale metadata; gt create branches off the currently-TRACKED branch in metadata, not your last checkout, so verify and correct the stack parent after creating; gt modify is version-fragile (rejected --no-ai, choked on repeated message args) so fall back to a non-interactive git commit --amend then let gt submit update the PR. For stacked-PR merge conflicts, use git to determine the actual conflicting hunks rather than eyeballing code. gh pr diff fails on huge PRs (HTTP 406, over 20000 lines), so a ~25k-line extraction PR cannot be diffed whole -- review by listing changed files and pulling individual file diffs. Switching to main reverts all un-merged feature commits out of the working tree, and un-pushed local-only commits are the single on-disk copy, so back them up with git push -u before risky branch moves (untracked design docs follow you across switches automatically). --publish/--publish submit creates an empty body, so after submit replace the body via gh with a reviewer-facing description and do a final readback (open/published/mergeable/checks). _{sources: claude-code:1402d3ec-c565-4576-ba22-97942b9f9d0b, claude-code:1c7117ad-9bee-4658-8937-e92adbc1a6ae, claude-code:25488cd9-61d5-4231-bd87-e2744b6db043, claude-code:eb751ed4-c198-4b0d-819e-1a3002f4f341 (+4)}

21. Keep each PR one coherent unit: split dirty branches, commit a pure revert first

generic · ⚠ session-derived, unverified

Keep each PR a single coherent change. Split a multi-purpose dirty branch into focused stacked PRs -- pre-existing unrelated work (e.g. a maker_v1 coworld-shape migration) was moved to its own PR underneath so the P0 PR stayed focused, and other dirty files were left untouched and enumerated; do not bundle carried-over work into a new player's first PR. When an in-progress refactor's diff grows tangled, revert to a clean baseline and commit the pure revert FIRST (undo everything except the one intended removal, with no replacement), then start the replacement fresh. _{sources: claude-code:10f74020-e0e6-4515-8d0c-f071d41766ad, claude-code:ca5e32ea-3dad-42a9-8991-0f07d28b1060}

22. Reconstruct clean commits incrementally and keep generated artifacts out of the diff

generic · ⚠ session-derived, unverified

Reconstructing lettered/semantic commits from a single large untracked file (e.g. a 4500-line .nim) is error-prone with git add -p; the reliable approach is to save the final version, start from the base file, re-apply each lettered change incrementally, and commit after each step. Match the repo's commit style (imperative present tense, motivation-first) by reading git log first. Remove generated artifacts (e.g. a tmp/ replay directory from an aborted CLI attempt) before committing so the patch shows only meaningful source/doc/test changes. _{sources: opencode:ses_224eeb40bffeZqmBRcrjFgPFul, codex:019ea9af-7020-7550-b427-d3478fed2057}

23. Commit after every experiment so bisection stays consistent

generic · negative result

Commit after every experiment so bisection and revert stay clean. Accumulating all changes in the working tree lets a per-file 'git checkout' during bisection create an inconsistent state (one module sending arguments another module can no longer parse), which silently broke a policy to a 0.00 score. _{sources: archive/cogames_playground/alpha_cog/experiments/notebook/hypotheses/H}

24. Review PR head against fresh origin/main; check real SDK signatures; submit self-owned reviews as COMMENT

generic · negative result · ⚠ session-derived, unverified

For a Graphite-stacked PR review, review the PR head against freshly-fetched origin/main, not the local working tree, so the diff matches what reviewers see. Even small player PRs depend heavily on SDK/protocol contracts, so check the actual SDK signatures and callback shapes rather than assuming imports are correct. GitHub rejects a REQUEST_CHANGES review when the authenticated account owns the PR -- submit the same findings as a normal review comment (event: COMMENT) instead. _{sources: codex:019e7174-3079-7351-b8ea-b1bfcb917ff4}

25. Verify manifest-only PRs and per-repo branch protection rather than assuming check outcomes

generic · ⚠ session-derived, unverified

For multi-repo manifest changes, use one consistent branch name and commit message in every repo so parallel PRs are easy to track, and treat manifest-only PRs as truly manifest-only by verifying the live diff (gh pr diff --name-only) touches only coworld_manifest.json / coworld_manifest_template.json with no code or Dockerfiles. Branch protection varies per repo, so a red required check does not reliably predict merge behavior: one repo merged a squash despite a failing required check while metta's REVIEW_REQUIRED policy blocks even with green checks. Confirm protection rules per repo rather than assuming a red check blocks or a green check unblocks. _{sources: codex:019e746d-062c-78d3-a0ed-ef2fcb892baf, codex:019e74bf-7764-7fd2-82e5-8f66c5ff9e1d}

26. Drive player-knowledge generation as an observable multi-model CLI fan-out with a source-validating synthesizer

generic · negative result · ⚠ session-derived, unverified

Drive a player-knowledge generation pipeline as a fan-out to multiple models via their CLIs (e.g. claude / codex exec / opencode headless) then a synthesizer that prefers the more specific draft, resolves contradictions by reading the actual game source (never average), takes the union of coverage, and drops out-of-jurisdiction content; first confirm each draft actually exists and is non-empty (in one run a Codex draft was never written because its sandbox blocked the file write). The multi-CLI generate-then-synthesize pattern improves quality but STILL needs an explicit 'validate the synthesized report against the codebase' stage, because synthesis alone propagates subtle spatial/geometric errors downstream: a synthesized report claimed spawn position equaled the button position ('may work immediately without movement') when players actually spawn in a circle of radius ~28 around the home point, so the implementation agent's no-movement action failed -- verify exact coordinates, layout, and obstacle presence against source before relying on them. The output is INSTRUCTIONS for a downstream future coding agent (build plan, stubs, decoder spec), not work for the generator agent -- do not 'helpfully' implement the player yourself. Drive sub-models through their CLIs (not raw API calls) so they inherit their own tools/skills; grant scope via --add-dir <game_source>/--add-dir <output_dir>, run cwd inside the game source, run analysis-only Codex read-only (-s read-only --ephemeral -o <file>), and make the sub-agent retrieve source via its own tools rather than pasting it in. Order stages bottom-up by dependency (overview -> rules/interface -> state/decoding/strategy/impl/README) and give each doc non-overlapping jurisdiction ('every fact lives in exactly one doc'). Store prompts as version-controlled templates (prompts/ with _preamble.md, synthesizer.md, doc*.md, {{variable}} substitution). Long blocking calls look hung (each claude -p ... --bare blocked 30-90s; a 14-doc run was 15-30 min of silence), so emit per-stage INFO progress plus a --skip-existing-resume flag. Asking a CLI sub-model 'what model are you?' is unreliable -- control the model via config/flags. _{sources: claude-code:33356b24-de19-46ae-ad01-810557f4d9b1, claude-code:7b66497b-650c-4bba-b410-6c854f59163d, claude-code:d4cde1e2-f4b5-4bd6-bf05-dd48002edf58, claude-code:d59631cb-a50e-42e8-a102-56ffb0864b55 (+2)}

27. Run the post-episode loop as parallel analyses plus one synthesis; assess state before acting as coordinator

loop

Run the post-episode improvement loop as parallel analysis passes (root-cause findings, metric/score analysis, episode report) followed by a single synthesis step that produces one policy proposal, rather than serializing or merging the analyses, so each pass stays focused and the proposal integrates all three. Before acting in a coordinator role, first assess state by reading episode stats, artifacts, current policy version, and existing task documents, and do not duplicate work already captured in those documents. _{sources: coworld-source-repos.crewrift-upload/optimizers/instructions/mvp/orche, claude-code:38ddef93-3214-489f-a178-33dddf030d9e, claude-code:f56285d5-42aa-49e2-92d5-844f590d7865}

28. Use the fixed crewrift agent roster; route param vs source-code changes correctly

crewrift · ⚠ session-derived, unverified

Use the fixed crewrift improvement-loop agent roster (orchestrator, debugger, analyst, reporter, exploiter, policy-improver, policy-engineer, skill-improver) and do not invent new agents. Route param-only changes to policy-improver; if a proposal needs source-code edits (not just config params), require policy-engineer to materialize the codeChangePlan in a workspace. Routing this wrong wastes a loop iteration. _{sources: claude-code:38ddef93-3214-489f-a178-33dddf030d9e, claude-code:f56285d5-42aa-49e2-92d5-844f590d7865}

29. Drive the optimizer via inspectable artifacts, a small roster, durable sessions, and reusable memory

loop

Drive agent work through a durable runtime session model: a task or comment (including @mentions) wakes an agent via a wakeup queue, the agent gets scoped task/policy/episode/memory/skill context assembled into its prompt, runtime events log progress, and the agent acts by leaving inspectable artifacts (comments, documents, memories, subtasks, policy proposals) rather than silently mutating state, so a human can accept or reject. Keep the roster small and purpose-built (Orchestrator, Debugger, Analyst) with detailed per-role instructions -- a large noisy roster adds friction without leverage. Before mutating a policy, memory_search prior memories (game_fact, policy_lesson, failure_pattern, playbook, anti_pattern) for the observed weakness so the loop reuses past lessons; on a win, memory_create the result as a playbook to compound knowledge. Make orchestration optional and non-blocking for scoring (skip wakeups with a warning when COAGENT_AGENT_CLI is unavailable but still complete episode scoring), and watchdog stale sessions/runs so stalled work stays visible. _{sources: coworld-source-repos.crewrift-upload/optimizers/CLAUDE.md, coworld-source-repos.crewrift-upload/optimizers/README.md, optimizers/docs/OPTIMIZER-MVP-SESSION-SUMMARY.md, coworld-source-repos.crewrift-upload/optimizers/.cursor/skills/mcp-opt (+2)}

30. Document the optimizer loop once canonically; protect cross-episode lessons in a SLOW_UPDATE region

loop

Document the optimizer operating loop (observe -> diagnose -> act -> verify -> promote), its safety gate, worked examples, and the full tool catalog in ONE canonical place rather than duplicating per-skill, so they never drift. In durable report/dossier docs, reserve a protected SLOW_UPDATE region (delimited by <!-- SLOW_UPDATE_START --> / <!-- SLOW_UPDATE_END -->) for cross-episode lessons and let only the epoch-boundary slow-update process rewrite it; fast per-episode updates and human edits must not touch that region, so accumulated learning is not clobbered by frequent writes. _{sources: coworld-source-repos.crewrift-upload/optimizers/skills/optimizer-mcp/S, coworld-source-repos.crewrift-upload/optimizers/skills/optimizer-mcp/r, coworld-source-repos.crewrift-upload/optimizers/instructions/mvp/analy, coworld-source-repos.crewrift-upload/optimizers/instructions/mvp/orche}

31. Constrain LLM self-edits to surgical str_replace ops with a fallback provider and dual-gate meta-edits

loop · tool: code_evolution.py

When an LLM self-edits policy code in an evolution loop, constrain each step to 1-3 surgical edits via a str_replace-style tool (path + old + new) over a fixed editable-file allowlist to keep each step reviewable and bound the blast radius; let it edit BOTH decision code (thresholds, trigger priorities, strategic logic in a coordinator like brain.py) AND role-specific prompt templates, since play quality comes from tuning both. Keep a failed inference attempt explicit in the optimizer state so the next bounded iteration can retry safely. Improve the optimizer's OWN skills under the same discipline: propose a skill edit as a stage-1 LLM-judge screen, accept only if it strictly improves the dual gate, and buffer rejections in a rejected-edit buffer; run this skill_epoch every K passes plus a slower loop_health check to catch stalls. _{sources: bitworld/among_them/bot-policies/sidecar/code_evolution.py, optimizers/docs/optimizer-primitives.md, optimizers/skills/continuous-optimization/SKILL.md}

32. Run a self-improving lesson loop on cross-session recurrence; markdown prompt files are load-bearing runtime

loop

Run a self-improving lesson loop keyed on cross-session RECURRENCE, not in-session hit counts. Write candidate lessons freely into a deliberately-noisy per-session buffer (e.g. TENTATIVE_LESSONS.md); a SessionStart hook rotates each session's buffer into lessons_archive/. Periodically (roughly weekly) a review skill (/lessons-review) clusters lessons recurring across INDEPENDENT archived buffers and proposes promote/keep/cull, graduating keepers into a durable best_practices.md -- a lesson seen many times in one session is not yet a keeper, while a boring lesson seen in 3 sessions outranks a brilliant one seen once. More broadly, markdown prompt files can be load-bearing runtime, not just docs: skills (setup/play/evaluate/analyze/improve), lifecycle prompts (start/wake/tick/sleep/die), and the memory-format spec can be executed by the operator agent (softmax-cli / Claude Code / OpenCode), the meta-loop can be auto-started (a wake hook launches /loop 30m improve.md), and the player is a persistent entity whose identity/intention/memory/todos live as committed files so it resumes across restarts. _{sources: personal_labs/crewrift_lab/.claude/skills/lessons-review/SKILL.md, personal_labs/crewrift_lab/AGENTS.md, personal_labs/crewrift_lab/lessons_archive/README.md, claude-code:0e7b14ca-ffd5-4137-9456-47485d3c6f87 (+1)}

33. Keep a one-screen WORKING_CONTEXT.md as the cross-session resume signal

generic

Maintain a tight cross-session 'working context' file (WORKING_CONTEXT.md) as a one-screen live state file recording ONLY the current objective, active policy/version, working lens, and load-bearing facts. Read it on startup to resume, update it as you learn, prune anything no longer load-bearing, and clear-and-reseed it when pivoting. It is not a log or report archive (those live with episodes and in git history); a recorded objective in it is the resume-the-loop signal. _{sources: claude-code:f70c9801-7ee7-499b-97f9-4fd0848a6b8e, codex:019de5a5-fadf-70b3-8773-2072cabae94c, personal_labs/crewrift_lab/AGENTS.md, personal_labs/crewrift_lab/WORKING_CONTEXT.md}

34. For resumable multi-session work, write root-cause/fix-plan docs, a cold-pickup handoff, and committed PLAN/DESIGN/README

loop · ⚠ session-derived, unverified

For multi-issue policy debugging, a workflow that worked: maintain a TODO.md of open bugs, write a deep code-grounded root-cause report before coding, then a written fix-implementation plan, then implement, parking deferred/lower-priority bugs as notes in TODO.md so they are not lost. End a multi-session player build by writing a self-contained cold-pickup handoff prompt (not a status note) into a committed markdown file in the destination folder, because the next session starts cold with only what was persisted: name the durable docs to read in order (PLAN -> DESIGN -> README), shipped-vs-next milestone with PR links, open design decisions to confirm before coding, the literal first commands to run (including any toolchain recovery procedure), hard constraints, a repo-path cheat-sheet, and known-flake recovery procedures. Maintain a per-agent README answering a fixed set of questions (strategy, current status, leaderboard score once submitted, what's next) and a phase-numbered IMPL_PLAN whose sections reference their own design docs. Keep durable plans in committed PLAN.md/DESIGN.md, not only in chat. _{sources: claude-code:067e7439-cbd1-4b26-9b3f-d054bde3aa40, claude-code:91060045-312c-4787-9819-a1421d228d61, claude-code:940b2eb9-3677-4c05-8754-c9cfa163f531, claude-code:b2b2f1e5-537c-4acf-abfb-4490b0abc27a (+1)}

35. Run phased builds with load-bearing handoff docs that capture tribal knowledge

generic · ⚠ session-derived, unverified

Preferred workflow for a substantial rewrite/new agent: assess how insulated the target subsystem is; produce a codebase-inspection report verifying claims against code; agree on design via Q&A (listing underspecified points, open questions, pushback); write a design doc with an appended implementation plan; implement in numbered phases (phase 0 = scaffolding that compiles with stubs). Each phase ships a complete tested slice; at phase end confirm handoff info is preserved in code and design doc, retire the consumed handoff with a historical header noting completion and divergences, write the next-phase handoff, and author a ready-to-paste prompt. The handoff should capture tribal knowledge the code omits (exact pipeline ordering and where the next phase plugs in, fixture-data shapes, host-language gotchas, button-mask bit conventions, the pathfinding walk-mask location, a prioritized files-to-read-first list) -- higher-value than re-summarizing the design. _{sources: opencode:ses_204495c66ffe7u8C8SOiEX1zdH, opencode:ses_21e58aef7ffeoJ7uZeDgGBCfIh, opencode:ses_21b1e7074ffeYT9RjQFHNPlNKX, opencode:ses_21b475c59ffeOFBSt0jbwsGras (+1)}

36. Record execution divergence and chosen options in design/TODO docs, never silently

generic · ⚠ session-derived, unverified

Record HOW execution diverged from the plan instead of rewriting history: when implementation phases compress and renumber, add a lead-in note explaining it; in TODO.md mark items resolved with a date rather than deleting them; when implementation picks one of a design's options, record which option, why, and any post-implementation API deltas (e.g. cross-layer target visibility via working.intent['target_position']; a shipped ring buffer exposing window_max/window_mean/fraction_at_most/fraction_equal vs the design's simpler fraction/window_min) or the doc becomes misleading. For a design-first session, brainstorm candidates, let the human pick directions, write decisions to a design-doc section (with explicit cut/deferred items, schema sketch, tuning knobs) and only then implement; lock non-perturbing replayable instrumentation in the doc with a final issue-surfacing pass before touching policy code. Design tracing/logging as an explicitly extensible system (recorded in a design doc) before adding many tasks so new tasks emit traces without bespoke wiring; in an iterate-on-policy loop, traceability of which mode was active and why is load-bearing signal you reason from between episodes. _{sources: opencode:ses_20aad554dffe3dzhaUQ8zuBnZT, opencode:ses_21a4b4fa0ffe6EhdZLacMU1JE4, opencode:ses_21f95b9fcffejcGcsPObrSAZFs, opencode:ses_21fdab7c0ffeyW9gOCR3FyrI7b (+1)}

37. Write mode docs as self-contained references against a gold-standard template

loop · ⚠ session-derived, unverified

A behavior/mode design doc should describe what the behavior IS -- a self-contained reference you could re-implement from (components, parameters, invariants) -- not a phase-numbered improvement log. Strip 'Files changed'/'Implementation plan' sections and name the doc after the mode ('Meeting Mode - Design Document'), not the change phase ('Phase 6.3 - Cursor Navigation + Timer Fix'). Hold every mode to one gold-standard template covering: purpose/role, parameters, full decision-logic cascade, subsystem details, scratch state with initial values, tuning constants, incoming/outgoing reflex-interaction tables, trace-event JSON schemas, default directive, action-layer contract, the LLM-snapshot context, and open questions. Trivial modes get a proportionally shorter doc; pure no-op stub modes get none. Maintain a modes glossary in the top-level DESIGN.md, and co-locate a 'Running' section (build commands, flag table, lobby examples, parity-test invocations) so the one discoverable artifact is authoritative. Specify mode transitions explicitly: minimum mode duration, hysteresis/cooldown to prevent thrashing, and protection windows for in-progress interactions -- without hysteresis a policy that re-evaluates every tick oscillates between modes and never completes a multi-tick interaction. Make implicit cycles first-class (a probe cycle -- decide target, approach, interact, extract, retreat -- deserves named states, a per-cycle time budget, and abort conditions), and treat temporal/urgency mechanics as a tracked quantity modes read rather than implicit vibes. _{sources: opencode:ses_1fb8906dcffete6Fy63Vc7IEPv, opencode:ses_2067f7b41ffe0wSvJ4MZlE58Q1, opencode:ses_206fd87a6ffel8Y8ooSpgw4Aeo, opencode:ses_224322057ffexj7SYlcfVA0zgy}

38. When deduping docs, keep one authoritative 'what to do' and preserve the 'why' next to pointers

generic · ⚠ session-derived, unverified

When restructuring/deduping docs that may drop content: make ONE file the single authoritative source for the 'what to do' steps and trim others to keep only the 'why' (rationale, heuristics, cautionary tales, sample-size/episode-length reasoning) -- pointer-plus-rationale beats both full duplication and deleting rationale. The failure mode: replacing inline procedural steps with pointers preserves the RULE but silently kills the RATIONALE (e.g. 'pre-create the hypothesis file before running' survived as a step but its reason -- crash insurance so the idea survives an interrupted run -- was lost). A global find-and-replace for a renamed structure is insufficient: references hide across CLAUDE.md, experiments/README.md, protocol.md, optimizer scripts, and in-code docstrings, each pointing to the old target by a different role, so redirect each to the specific new subdirectory; prioritize agent-facing workflow docs over cosmetic docstring cites. Forward references across a PR stack are acceptable if explained in the PR description. _{sources: opencode:ses_1ff55b501ffeLso6dyHqZ2o8Bc, opencode:ses_1ff344748ffeIooJBfFGRt6YG0, opencode:ses_20acc31f1ffeLnsxS6seOLhz0s, opencode:ses_20b14e3aaffe6TJnfnmV5DdVmT (+1)}

39. Correct living docs the moment an empirical finding contradicts them; split process knowledge from findings

generic

Correct living docs (MISSION.md/COGAMES.md, strategy docs, workflow/submission docs) immediately when an empirical finding contradicts them -- treat the doc update as part of the discovery, not a later chore. Document edge cases the moment you find them (e.g. 'no matching season -> validation runs against wrong pool -> --skip-validation is correct'), preventing the next agent from re-deriving it or wrongly skipping validation around a genuine bug. Maintain two synchronized stores for an iterative research project: an append-only per-entry log of what happened, and a curated reference of what to do today; update both when a finding stabilizes. At session close, extract process-level meta-knowledge (HOW experiments are run -- validation approaches that cannot work for a hypothesis class, workflow shortcuts, bug classes, tool limits) SEPARATELY from experiment findings (WHAT they found). _{sources: opencode:ses_22033c323ffeaukf7T2ZfJOoMR, opencode:ses_21faa7b9bffezLlGGJpB1MVzZS, alpha_cog/AGENTS.md}

40. Keep living docs to current state and update them in the same change; scope canonical docs and dirs

loop

Keep living documentation describing only the current supported state, not history: keep deletion inventories and migration handoffs out, point only at the current supported run path (e.g. the Coworld run path), and audit docs touched in a session before committing -- do not reintroduce instructions for local game servers, raw-frame-capture run paths, hosted-play shims, or legacy bundle-upload commands. When refactoring behavior config, treat README/design/AGENTS docs as part of the change: docs describing env-controlled behavior become stale and must be updated to the new config composition root in the same task; after moving a module's import path (e.g. perception relocated under orpheus.perception), import only through the new path to prevent import drift. Point fresh agents at the canonical Among Them docs (among_them/README.md, guided_bot/README.md, guided_bot/coworld/README.md, INSPECTING_RESULTS.md, DC_DEBUGGING_PLAYBOOK.md) and update them when the Coworld command surface changes. Keep a shared common/ directory small and implementation-focused (low-level perception kernels active policies import) -- no run harnesses, server launchers, upload helpers, or one-off debug scripts -- and when primary docs deliberately avoid depending on the upstream source projects, keep historical source-repo pointers in a separate non-required reference file. _{sources: players_checkouts/players/users/james/personal_cogs/among_them/README., players_checkouts/players/users/james/personal_cogs/AGENTS.md, players_checkouts/players_2/players/crewrift/crewborg/docs/designs/con, players_checkouts/players/users/james/personal_cogs/persephone/README. (+3)}

41. Doc patches against wrapped prose fail silently; verify each edit applied

generic · negative result · ⚠ session-derived, unverified

Patches against wrapped prose docs (README/design docs/AGENTS.md) fail SILENTLY and apply nothing when exact line context doesn't match due to wrapping differences or duplicated text. Apply doc edits as small, line-accurate patches rather than one broad multi-line block, and verify each patch actually applied rather than assuming success. _{sources: codex:019eaee5-b54e-79f2-bf0f-ac59a6a1eae2}

42. Audit lifecycle: dated report, fix the checklist, then archive; truth-preserving role-repo shells

generic · ⚠ session-derived, unverified

Write a doc audit as a dated report under docs/ with a TODO checklist of immediately-fixable drift items, fix them, then once fully checked off archive the finished audit to an audits/ directory -- keeping docs/ for living references. Keep 'LLM-ready' framework docs source-verifiable by stating what exists today versus what is aspirational (context schema + validator + trace events exist, but no provider/prompt-layer/shadow-runner/runtime-handoff yet) and update stale baselines like test counts. When a role repo's scaffolding is stale and misleading, strip it to a truth-preserving shell (delete fake runnables, blank scaffolds, obsolete docs) but keep one authoritative README that is a lookup map: purpose, current empty/runtime-pending status, authoritative metta paths, a contract snapshot, repo boundaries/non-goals, and a checklist for adding the first real implementation. _{sources: codex:019df3f0-db41-7561-8184-8832002dba41, codex:019e131a-1bb0-7400-b54a-f208202b291d, codex:019e74f1-3908-79c3-a5f2-7eba06b2f7e8}

43. Hand plans to implementers with collapsed contracts and verified companion docs

generic

Before handing a plan to an implementing agent, collapse conflicting API shapes for the same operation into one result type (two different advance signatures became a single ReplayStep shape) or the implementer wastes effort reconciling contradictory contracts. When a handoff/design doc references companion docs, verify they exist in the checkout first (one handoff's original was missing and referenced an also-missing config doc, so both had to be copied in). Treat a doc that over-specifies brittle details (exact error strings, preservation rules) or under-documents required public-doc updates as a defect to correct in the same patch. When changing a shared function signature, keep a deprecated backward-compatible wrapper so existing callers compile while the new call site uses the full signature (e.g. a projection function that gained a required player-position argument), letting the change land without a big-bang caller update. _{sources: codex:019e8aca-584f-7821-af97-25a1500c403d, codex:019e9a48-09ad-7892-9be7-89e5ccc690e2, players/player_sdk/docs/handoff-mode-registry-factory.md, codex:019e03bc-5520-7e72-aa5c-a572ead62b91}

44. Clean up monitoring scaffolding and stop grinding once the user's bottleneck is fixed

generic · ⚠ session-derived, unverified

Background status pollers started for monitoring can outlive the turn with closed stdin, so track the PID and kill it explicitly when done rather than leaving a dangling watcher; remove debugging scaffolding (symlinks like a clients/ symlink, temp dirs) once the real fix lands, flagging it with the exact cleanup command, because the workaround becomes redundant after the root cause is fixed. Resolve the user's actual bottleneck first and treat further optimization as optional -- after the headline complaint ('runs too slow') was fixed by the first one or two phases, flag the remaining phases as diminishing returns and check in with the human before grinding on. _{sources: codex:019ea9af-7020-7550-b427-d3478fed2057, opencode:ses_200deb284ffe7RFSHqkkWQqwAx, opencode:ses_21e7f66a8ffeNFrL2URK8EWAn7}

45. Capture frictions, known limitations, and submission traps as durable docs, not just code patches

generic · ⚠ session-derived, unverified

When a known limitation or regression-prone requirement surfaces, record it as durable spec in project docs (TODO.md) rather than only patching code, so the next iteration does not reintroduce the bug: capture status, impact, root-cause hypothesis, fix path, live-test evidence, and the current workaround (e.g. agents can read their role from the overworld HUD instead of the role-reveal screen). Keep a running NOTES.md / build log of protocol quirks, environment gotchas, and pacing surprises while bringing up a new player, and structure research as multiple interlinked docs/*.md files (e.g. cogames-policy-api.md, research-sources.md) with explicit cross-links rather than one monolith. Write a reusable submission guide keyed on error messages (troubleshooting-by-symptom) with exact commands and file:line refs, a preflight checklist (Docker up, authenticated, season name), and non-obvious traps (bundle flattening, transitive Nim deps, ABI/version pinning, the validation-gate caveat for perception bots), placed as a game-general guide alongside existing how-to docs. _{sources: opencode:ses_20c066070ffeBjXMnfQULai0Lw, opencode:ses_20a41d230fferPYcSsh385tuSR, opencode:ses_2240b911bffeRPYWAkhpoMH1eS, opencode:ses_2251f2219ffe0h3Sjj47eVLHrt (+1)}

46. Gate shared-code extraction on real second-consumer reuse; keep the foundations layer one-directional

generic · ⚠ session-derived, unverified

Gate shared-code extraction on real reuse: only promote a utility into a common/_shared/ directory once at least two consumers actually use it; do not speculatively grow shared perception/util code for a single consumer. Treat code duplicated inline across a second consumer (e.g. a BundleReader copied into two reporters) as the 'second-consumer' signal to extract; intentional duplication during a migration is acceptable but should trigger the extraction follow-up. Design a shared/foundations helper library as 'the dependency, not a dependent', with no upward imports into the policy code that consumes it -- this one-directional rule lets existing policies call into it without circular imports and is what makes a foundations layer adoptable. When converting importable policies into standalone projects, expect genuinely cross-policy utilities to resist full self-containment (e.g. a _shared/ module of geometry/roles/context/entity_map/goal/trace helpers consumed by multiple variants); surface that shared seam to the human and let it stay shared rather than force-isolating to a false ideal of zero coupling. _{sources: auggie:ac491a46-e7f7-4271-a1c0-f0e69987d424, claude-code:1402d3ec-c565-4576-ba22-97942b9f9d0b, claude-code:2426100f-257d-4100-ba93-2097175a999c, claude-code:940b2eb9-3677-4c05-8754-c9cfa163f531 (+1)}

47. Extend shared engine/tool code minimally: copy or subclass, prefer existing formats, split PRs

generic · ⚠ session-derived, unverified

When extending shared engine code for a game player, copy or subclass rather than editing upstream: keep player work inside the players/ tree and extend provider wrappers via inheritance or a local copy, reusing existing vendored clients (e.g. an HTTP provider wrapper) without modifying shared engine source. When extending a shared tool (coworld-crewrift expand_replay.nim), keep the diff minimal and prefer the tool's existing general output formats over a bespoke single-consumer mode (a --format events-jsonl mode was rejected for the existing JSONL format); preserve existing behavior as default (keep text mode default when adding JSONL). When a task touches both a shared SDK and a player's consumption, split into stacked PRs even if developed in one tree: base = SDK surface (API, exports, docs, tests), top = player integration; likewise split player code (bitworld) from public docs (metta) into cross-referenced PRs. Record a defect in a shared LOWER layer as a TODO in THAT layer's directory, not only in the consuming design. A skill that activates on work merely TOUCHING a tool (an 'experience-request analysis' skill firing on any expand_replay edit) is a scoping smell -- it should describe how to use the tool for its actual purpose, belongs in the relevant repo (player_lab), and vestigial copies elsewhere should be removed. _{sources: codex:019eaee5-b54e-79f2-bf0f-ac59a6a1eae2, codex:019eb326-beb5-7b03-890e-732da6aa6746, opencode:ses_1fb48dd11fferLGXS1vWdHa0wS, opencode:ses_219e032f9ffeqy8OzInbZDP27R (+2)}

48. Verify which checkout/project a path refers to; stage experiments separately; record provenance; scope coupled-repo commits

loop

Use a users/<handle>/<project>/ staging area separate from the canonical players/ directory and graduate code into players/ only by explicit copy, keeping half-baked work from being treated as a shipped policy; a subtree like players/among_them/coborg/ (a live ~5,100-line git-tracked package picked up by the root pyproject.toml setuptools packages.find glob players.among_them.*) is fine to read but archiving it is separate cleanup. Beware name collisions: the archived BitWorld 'Among Them' tree (players/among_them/) is distinct from the still-active users/james/personal_cogs/among_them/ guided_bot Nim league bot (deliberately not archived) -- verify which one a path refers to, and point a contractor/deliverable at the actual checkout, not an unrelated monorepo. When two agents work coupled repos (a player and its Player SDK), scope each commit/PR to only your own repo because the other may have modified the shared dependency, and after a reviewed SDK PR merges, sync to the merged state and re-read the final API before building on it (review feedback like dropping a tick tag or removing a namespace param changes the surface). When collating external code, record per-artifact provenance (source repo, exact commit, what was excluded) in a source-provenance.md, watch for provenance drift (a note saying 'web UI left out' while a dashboard.html is still present), and do not infer authorship from the collation repo's git log (it shows only post-collation edits) -- state authorship as inference when the checkout cannot prove it. _{sources: players_checkouts/players/archive/README.md, auggie:ac491a46-e7f7-4271-a1c0-f0e69987d424, auggie:c5674179-5e48-4584-a7a9-f75d2cd3c61b, claude-code:1c7117ad-9bee-4658-8937-e92adbc1a6ae (+4)}

49. Add instrumentation as an isolated additive call over a narrow surface you identified up front

generic · ⚠ session-derived, unverified

Treat new instrumentation (a trace stream, a structured emission) as an isolated additive call: do not entangle it with unrelated pre-existing local edits to the same file, keeping the change reviewable and leaving in-flight work for its owner. Identify the narrow compatibility surface BEFORE editing, not after: confirm exactly which call sites still emit legacy strings (e.g. pipeline callable logs, hook failures, outer-loop failures), pin those, then add structured emission beside them -- knowing the surface is narrow up front prevents a sprawling refactor of the policy pipeline. When a diagnostic/tracing need would be expensive/invasive or cut against a clean layer boundary (e.g. a belief-layer update function with no access to the trace writer), prefer leaving a discoverable, clearly-marked TODO at the point of interest (e.g. '# TODO Stage 8 follow-up:') over half-implementing it or threading cross-cutting plumbing through the interface -- unless tracing that exact path is the task's actual goal. _{sources: codex:019e00a3-98da-75b3-89f8-ed86e1fc3b99, codex:019e0383-1db4-7f90-a085-04e6f27b26e5, codex:019e03bd-5f9b-7482-a03a-24cb99c6c7ed}

50. Read source first when stuck; meta-prompt loose instructions into explicit task+eval specs; adapt the loop for discovery phases

generic · ⚠ session-derived, unverified

For open-ended behavior debugging or high-stakes instrumentation, meta-prompt first: steer with 'generate a really good prompt for yourself instructing you to figure out why, then follow it', forcing a layout of known facts, observed metrics, and the specific questions before diving into traces. For a loose instruction ('run it, evaluate, meta-prompt yourself a better version'), inspect the project code first and rewrite it into an explicit task plus evaluation spec (named stages, a smoke-test plan like --through-stage 2 first, concrete evaluation dimensions, and for instrumentation a target spec detailed enough to post-mortem, overlay on recorded frames, and drive automated evaluation), confirming the design with the human before implementing. When a loop is 'going down research rabbit holes based on assumptions that didn't work,' stop guessing and read the actual source first (pull the game repo + read the coworld CLI code), produce a source-verified markdown guide, verify it empirically, and have an independent agent double-check. A 'discovery' phase has no code and therefore no red/green unit tests; adapt the loop to gather data -> populate plan-doc placeholders with real IDs -> review -> ship, flowing the discovered IDs forward into every later phase so the migration stays actionable from one source. _{sources: claude-code:0919285d-1374-4827-b596-6e7107d95526, claude-code:7bca307c-7349-423e-90c7-544957a43935, claude-code:962c8ab4-4ea3-4aaa-9f6d-20ea3cfce003, claude-code:b09cd025-18e0-41cc-abe0-039562b0ab0d (+1)}

51. Confirm what would be lost before a cleanup deletion; check for an existing flag; treat architecture reversals as deliberate proposals

generic · negative result

Before a consolidation/cleanup deletion, confirm what would be lost: an 'aggressive consolidate to one direction' commit wiped a whole tools/ directory (~2666 lines of asset bakers, waypoint editor, frame viewer) with no runtime equivalent. Before deleting offline tooling, confirm the artifacts it generates can still be regenerated (an editor for a hand-maintained graph is not reproducible from the baked output alone); before acting on a 'delete src/' instruction, identify and migrate out the critical live logic (metrics, parsing) and check what passing tests depend on that tree. Before writing code to disable/change a subsystem, check whether an env-var/flag already exists for exactly that behavior (GUIDED_BOT_LLM_DISABLE=1 already hard-disabled the LLM) -- a code change is justified only if determinism is needed regardless of shipping environment. And treat a major architecture reversal (removing the Nim core to make a bot pure-Python, or any core-language rewrite) as a deliberate, separately-decided proposal with its own design doc and validation plan, NOT a creeping migration smuggled through individual PRs or folded into a cleanup meant only to consolidate run surfaces. _{sources: players_checkouts/players/users/james/personal_cogs/among_them/guided_, players_checkouts/players/users/james/personal_cogs/among_them/guided_, auggie:02627f61-aac0-42a0-a290-3595e010abba, auggie:5d1ff8d5-2505-4dca-af45-56d3070363e2 (+3)}

52. Don't blind-delete 'dead' helpers during a merge; check callers and the coupling boundary

generic · ⚠ session-derived, unverified

Before deleting 'duplicate' or 'dead' helpers during a merge, grep for actual callers and check tests/trace consumers -- auto-merge can preserve helpers a refactor meant to remove, and some are still referenced by feature code you are keeping (e.g. layout/grid-origin helpers reused by chat-attribution). Use the coupling boundary to keep the merge minimal: if each bot's helpers are self-contained and unimported by siblings, leave legacy helpers in place. Distinguish load-bearing fields from debug-only fields first -- a per-line screen-coordinate y field used only for debug trace and asserted by no test needs no precise reconstruction. _{sources: opencode:ses_21ece5489ffeFZNEP6Ehx80GI1}

53. Deprecate superseded code/players/strategy loudly rather than deleting; mirror the archive and keep legacy entrypoints

loop · negative result

Deprecate, don't delete, overlapping or superseded components, but make active-vs-historical status loud where agents read first. When a visual-exploration stage's doc-generation role was subsumed by the canonical generator, mark it deprecated, make the canonical generator the single entry point, and keep its capture/annotation/fixture code as an optional artifact family. When a workspace holds more than one player implementation, state in AGENTS.md/README as a hard rule that agents must not inspect/test/run/ship/modify the deprecated player unless explicitly asked; remove the old player from default commands but preserve 'why this shared package is here' breadcrumbs, or the next maintainer loses the rationale for a shared kernel that outlived its consumer. When superseding a strategy, keep the previous engine reachable as a named legacy entrypoint (e.g. evaluate_strategy_v1) for regression and comparison rather than deleting it, and tag decision facts (e.g. role-lease facts) with a strategy version so traces can tell which engine produced a decision. Retire dead code into an archive/ tree whose paths MIRROR the original repo layout so restore is a mechanical git mv back. In living design docs, mark superseded assumptions and reversals EXPLICITLY rather than silently deleting them (e.g. flagging that an earlier 'death respawns at hub' assumption was WRONG -- death leaves the agent in place with gear/hearts cleared) and mark stale critique docs as historical once their failures are fixed, so they aren't mistaken for current evidence of breakage. _{sources: codex:019e13cd-d482-7133-a38d-c683c32a3004, codex:019e131b-8f24-7903-b52a-8ea3ce3a822c, archive/cogames_playground/bulbacog/designs/OUTER_LOOP_AND_MODES.md, players_checkouts/players/archive/README.md (+2)}

54. Migrate a player to the public CLI in one pass: delete custom scripts, run the real interface

loop · ⚠ session-derived, unverified

When migrating a player to a public package/CLI flow, in the same pass delete the old custom scripts/servers and purge their documentation: enumerate then remove every non-coworld script (raw runners, custom servers, hosted bits) and strip docs referencing them, leaving a single clean run path via 'uv run coworld'. Running the bot through the public interface also tests how usable that interface actually is. Persist non-obvious launch invariants (e.g. 'server must run from dir X, launcher from dir Y') into a directory-local AGENTS.md/CLAUDE.md placed where the game lives so it auto-loads, converting a one-time discovery into a permanent guardrail. _{sources: codex:019e2886-d576-7770-be1b-6d92ca97761e, opencode:ses_200cdca2fffeNC2dxiT8W9quAt}

55. Read restrictive instructions literally and verify AGENTS.md paths/env against the real tree before acting

loop · ⚠ session-derived, unverified

Re-read a restrictive instruction literally before letting it gut your plan, distinguishing a forbidden alternate run path from a forbidden capability: an AGENTS.md 'no live raw-frame-capture run paths' rule was first read as banning all frame capture, but on re-read it only forbade a parallel non-Coworld execution mode and documenting it as a runtime path, while dev-only tooling/tests and instrumenting a legitimate uv run coworld session were still allowed. Coworld/cogames workshop repos routinely have AGENTS.md/mission files that point at read-first docs (MISSION.md, COGAMES.md, COGAMES_CLI.md) absent from the checkout, or describe a parent '<game>/<agent>/' layout when the cwd is already the player/game directory (so referenced files live one level up), and may assert false env facts ('no pyproject.toml at root' when one exists). Before acting on any path, inspect the real directory tree and verify env claims; if mandated docs are missing, do not stall -- fall back to on-disk sources of truth (root README, per-agent README/DESIGN.md/TODO.md), proceed with the scoped change, and flag the missing docs as drift. Treat a plan/design doc as possibly stale at the start of a phase: grep/find the source dirs it points at and treat any drift (moved paths, obsolete 'do not touch' notes, deleted bots) as a finding to fix in the doc. When a setup instruction has an obvious typo of a domain term ('cowor4old' for 'coworld'), grep docs/README/AGENTS for the literal string; zero hits means use the corrected term rather than inventing a concept. _{sources: auggie:5d1ff8d5-2505-4dca-af45-56d3070363e2, claude-code:910f4bed-0d44-4b30-bf8f-9ecb5297ba4e, codex:019e004f-1647-77a1-9e58-fa29c8f8ef89, codex:019e0138-b924-7210-98fd-3fb3ada47fe9 (+5)}

56. Brief sub-agents at locked scope in concrete terms, admit uncertainty, and treat a bug report as a legitimate terminal action

generic · negative result · ⚠ session-derived, unverified

When handing a design report to a coding sub-agent, a report that solves a harder or different problem than asked is worse than no report (a human rejected an over-engineered 'register_factory' SDK-change brief that had drifted) -- lock scope to exactly the asked-for change and confirm code facts before writing the brief. Do not leak pattern jargon into design discussion with a collaborator who has not opted into it (a 'DI seam' reference drew 'I don't know what that is'); name the concrete mechanism ('pass the LLM client in instead of building it inside the mode') rather than the pattern label. When a project is in flux (roles/contracts still in open PRs), check out the in-flight branch and diff it against main to answer design questions, but state remaining confusion explicitly -- the human preferred honest 'still unsure' answers plus questions over confident guesses. When a tool bug you do not own (e.g. a replay viewer stuck 'waiting on players to connect') cannot be fixed locally, pulling latest to re-check the repro and writing a self-contained bug report is a legitimate terminal action -- file the issue against the repo whose public surface accepts issues, with an explicit one-line path pointer to where the fix actually lands (when the fix lives in a repo with issues disabled) plus a minimal stdlib-only repro, and do not rathole on infra you do not own. _{sources: claude-code:4ec865f5-bcbc-44f1-b109-a27d69f55506, claude-code:77de2491-bdb8-4277-b759-175ea5203c28, claude-code:93aaeccd-fa2d-4581-8f93-3e77e556db21, claude-code:d48f9347-7884-4ea2-8659-230051d86410}