agent-workflow-collab

name	agent-workflow-collab
description	Use for agent workflow collab recipes in scripted Coworld policy optimization.

Agent workflow & collaboration — recipes (loop tier)

On-demand recipes (13). Trigger→action heuristics; pull the relevant one when its situation arises.

1. 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)}

2. 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}

3. 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}

4. 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)}

5. 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)}

6. 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}

7. Commit after every experiment so bisection stays consistent

loop · negative result

Commit after every experiment in a hypothesis-driven policy-optimization loop so bisection and revert stay clean. Accumulating all changes in the working tree lets a per-file 'git checkout' during bisection create an inconsistent cross-module state -- e.g. one module emitting 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}

8. 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}

9. 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. Provide a fallback provider path (e.g. Bedrock converse primary, OpenCode CLI fallback) so one direct-API failure does not stall the loop. 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}

10. 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}

11. 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)}

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

loop

Use a users/// 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)}

13. 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}