agent-workflow-collab

name	agent-workflow-collab
description	Use for reusable agent workflow collab recipes in software and coding-agent work.

Agent workflow & collaboration — recipes (generic tier)

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

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

generic

Treat every path, command, method/symbol name, behavior claim, parser vocabulary, pipeline-diagram step, and enumerated API/export list in a project's docs (PLAN/DESIGN/README/AGENTS.md/etc.) as an unverified hypothesis: ls the path, grep the symbol, walk the actual code's step order, source vocabularies from the live parser, and diff against current source before trusting it, because files get moved or renamed often. 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. When porting or restructuring from a fast-moving source, your initial structural map goes stale -- re-diff EACH module against live source as you port it and copy the source's NAMED constants rather than inlining literals. Cross-check the live working tree against git status, not a memory note or README: a dirty checkout can show files only as deleted-tracked yet still partially imported, so distinguish 'present and usable now' from 'tracked upstream / deleted locally', and 'framework exists' from 'framework is intact'. (Illustrative: an AGENTS.md pointed at a moved README path; a referenced script belonged to a different component; a design doc grew from 12 to 103 lines between two reads.) _{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/.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. 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)}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

19. 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 knowledge/research-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 source (never average), takes the union of coverage, and drops out-of-jurisdiction content; first confirm each draft exists and is non-empty (a sandboxed CLI can silently fail to write its file). The generate-then-synthesize pattern STILL needs an explicit 'validate the synthesized output against the source' stage, because synthesis propagates subtle factual errors downstream (in one run a synthesized spatial claim was wrong and broke the implementation that trusted it) -- verify load-bearing facts against source before relying on them. The output is INSTRUCTIONS for a downstream agent (build plan, stubs, spec), not work for the generator agent. Drive sub-models through their CLIs (not raw API calls) so they inherit their own tools/skills, grant scope via --add-dir, run analysis-only agents read-only, and have the sub-agent retrieve source via its own tools. Order stages bottom-up by dependency and give each doc non-overlapping jurisdiction. Store prompts as version-controlled templates with {{variable}} substitution. Long blocking CLI calls look hung, so emit per-stage 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)}

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

generic

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 context assembled into its prompt, runtime events log progress, and the agent acts by leaving inspectable artifacts (comments, documents, memories, subtasks, proposals) rather than silently mutating state, so a human can accept or reject. Keep the roster small and purpose-built with detailed per-role instructions -- a large noisy roster adds friction without leverage. Before a consequential mutation, search prior memories (facts, lessons, failure patterns, playbooks, anti-patterns) for the observed weakness so the system reuses past lessons; on a win, record the result as a playbook to compound knowledge. Make orchestration optional and non-blocking for the core task (skip wakeups with a warning when the agent CLI is unavailable but still complete the core work), 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)}

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

generic

Document an agent's operating loop, 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 that mix fast high-frequency updates with slowly-accreted knowledge, reserve a protected region (delimited by explicit markers such as / ) for the slowly-accreted lessons and let only the slow-update process rewrite it; fast 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}

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

generic

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, have a session-start hook rotate each session's buffer into an archive, and periodically (roughly weekly) have a review step cluster lessons recurring across INDEPENDENT archived buffers and propose promote/keep/cull, graduating keepers into a durable best-practices doc -- a lesson seen many times in one session is not yet a keeper, while a boring lesson seen across 3 sessions outranks a brilliant one seen once. More broadly, markdown prompt files can be load-bearing runtime, not just docs: skills, lifecycle prompts (start/wake/tick/sleep/die), and a memory-format spec can be executed by the operator agent, a wake hook can auto-start a recurring meta-loop, and the agent can be 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)}

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

generic

Maintain a tight cross-session working-context file (e.g. WORKING_CONTEXT.md) as a one-screen live state file recording ONLY the current objective, active work-item/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 in artifacts and git history); a recorded objective in it is the resume 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}

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

generic · ⚠ session-derived, unverified

For resumable multi-session work, a workflow that held up: maintain a TODO.md of open issues, write a deep code-grounded root-cause report before coding, then a written fix-implementation plan, then implement, parking deferred/lower-priority issues as notes in TODO.md so they are not lost. End a multi-session build by writing a self-contained cold-pickup handoff prompt (not a status note) into a committed markdown file, 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-component README answering a fixed set of questions 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)}

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

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

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

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

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

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

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

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

33. 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 (e.g. TODO.md) rather than only patching code, so the next iteration does not reintroduce the bug: capture status, impact, root-cause hypothesis, fix path, test evidence, and the current workaround. Keep a running NOTES.md / build log of protocol quirks, environment gotchas, and surprises while bringing up something new, and structure research as multiple interlinked cross-linked docs rather than one monolith. Write a reusable guide keyed on error messages (troubleshooting-by-symptom) with exact commands and file:line refs, a preflight checklist, and non-obvious traps (e.g. dependency flattening, ABI/version pinning, validation-gate caveats), placed alongside existing how-to docs. _{sources: opencode:ses_20c066070ffeBjXMnfQULai0Lw, opencode:ses_20a41d230fferPYcSsh385tuSR, opencode:ses_2240b911bffeRPYWAkhpoMH1eS, opencode:ses_2251f2219ffe0h3Sjj47eVLHrt (+1)}

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

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

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

37. 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 in. 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, concrete evaluation dimensions, and for instrumentation a target spec detailed enough to post-mortem 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, produce a source-verified 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. _{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)}

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

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

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

generic · negative result

Deprecate, don't delete, overlapping or superseded components, but make active-vs-historical status loud where readers (humans and agents) look first. Mark a subsumed component deprecated and route everything to the single canonical entry point while keeping its code as an optional artifact family. When a workspace holds more than one implementation of the same thing, state as a hard rule (in AGENTS.md/README) that agents must not inspect/test/run/ship/modify the deprecated one unless explicitly asked; remove it from default commands but preserve 'why this is still here' breadcrumbs. When superseding logic, keep the previous version reachable as a named legacy entrypoint (e.g. evaluate_strategy_v1) for regression/comparison and tag decision artifacts with a version so you can tell which engine produced them. Retire dead code into an archive/ tree whose paths MIRROR the original layout so restore is a mechanical git mv back. In living design docs, mark superseded assumptions and reversals EXPLICITLY (e.g. 'earlier assumption X was WRONG') and mark stale critique docs as historical once 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)}

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

generic · ⚠ session-derived, unverified

Re-read a restrictive instruction literally before letting it gut your plan, distinguishing a forbidden alternate path from a forbidden capability (e.g. a 'no live raw-capture run paths' rule may forbid only a parallel execution mode, not all capture). Instruction/onboarding files (AGENTS.md, README, MISSION-style docs) routinely point at read-first docs absent from the checkout, describe a parent layout when cwd is already the leaf dir (so referenced files live one level up), or assert false env facts ('no pyproject.toml at root' when one exists). Before acting on any path, inspect the real tree and verify env claims; if mandated docs are missing, do not stall -- fall back to on-disk sources of truth (root README, per-component README/DESIGN/TODO), 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 the dirs it points at and treat drift (moved paths, obsolete 'do not touch' notes, deleted components) as a finding to fix. On an obvious typo of a domain term, grep docs 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)}

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