VoidBot/AGENTS.md

Use the voidbot MCP server whenever the task touches Discord history, archived GameCult discussion, indexed GameCult repositories, Aetheria lore, or owner notifications.

Commit completed work at the end of each pass unless the user explicitly asks to leave changes uncommitted or the work is clearly mid-surgery. Prefer small, intentional commits over letting a pile of unrelated edits rot in the worktree.

Canonical Project State

• Treat state/map.yaml as the canonical slow-changing project map.
• Treat state/scratch.md as disposable working memory for one bounded subgoal.
• Treat state/evidence.jsonl as the distilled durable ledger of what changed future belief.
• Treat notes/fresh-workspace-handoff.md as the compact re-entry packet.
• Treat notes/voidbot-current-system-map.md as the source-grounded explanation of the live control flow.
• Treat notes/voidbot-implementation-plan.md as the current larger-organ sequence.
• Update state/map.yaml when project understanding changes.
• Add evidence after meaningful research, implementation, verification, or rejected paths, but keep it distilled. Routine “I just did this” proof belongs in git history, commits, smoke artifacts, or targeted logs unless it changes what the next session should believe.

Important Paths

• Project root: E:\Projects\VoidBot
• Canonical map: E:\Projects\VoidBot\state\map.yaml
• Scratch surface: E:\Projects\VoidBot\state\scratch.md
• Distilled evidence ledger: E:\Projects\VoidBot\state\evidence.jsonl
• Branch ledger: E:\Projects\VoidBot\state\branches.json
• Handoff summary: E:\Projects\VoidBot\notes\fresh-workspace-handoff.md
• System map: E:\Projects\VoidBot\notes\voidbot-current-system-map.md
• Implementation plan: E:\Projects\VoidBot\notes\voidbot-implementation-plan.md
• State CLI: E:\Projects\VoidBot\tools\voidbot_state.ts
• Pre-compaction helper: E:\Projects\VoidBot\tools\voidbot_prepare_compaction.ts

Useful Commands

npm run state:status
npx tsx .\tools\voidbot_state.ts add-evidence --type research --status ok --note "..."
npx tsx .\tools\voidbot_state.ts add-branch --id branch-id --hypothesis "..."
npm run state:prepare-compaction

Session Bootstrap And Re-entry Protocol

On fresh session load, do this before wandering into implementation:

1. read:
   • state/map.yaml
   • notes/fresh-workspace-handoff.md
   • notes/voidbot-current-system-map.md
   • notes/voidbot-implementation-plan.md
2. run:
   • npm run state:status
3. restate the current next action from the persisted state before starting edits

After compaction, resume, or suspicious continuity loss:

1. rerun npm run state:status
2. reread state/map.yaml and notes/fresh-workspace-handoff.md
3. treat the persisted next action as authoritative unless fresh repo evidence contradicts it

When context pressure is clearly rising:

1. stop broad exploration
2. narrow the active move to one bounded organ
3. persist map or handoff updates, plus distilled evidence only when the lesson changes future belief, before the blackout lands

When the user says to prepare for imminent compaction:

1. run npm run state:prepare-compaction before editing persistence surfaces
2. use its warnings as the checklist for map, handoff, scratch, evidence, and git hygiene
3. update only the state that actually needs to change
4. rerun npm run state:prepare-compaction after edits
5. fix errors, address warnings, and commit the completed persistence pass unless the work is deliberately mid-surgery

Prefer these tools over raw file inspection when they can answer the question:

• list_indexed_repos to discover valid indexed repository names before narrowing a source search
• search_history for semantic retrieval across archived Discord messages
• get_message_context for the surrounding conversation window around a message
• search_sources for semantic retrieval across indexed source trees and lore repositories
• get_source_context for the surrounding chunk window inside an indexed source document
• notify_owner for explicit Discord pings or long-running completion notices

When searching GameCult repos or lore, start with voidbot retrieval instead of rg --files plus file-by-file reads unless you need exact edit targets or the indexed results are clearly insufficient.

Do not inspect .voidbot/rag/messages.json, .voidbot/rag/source-documents.json, .voidbot/history-vector-store.json, or .voidbot/source-vectors/ directly unless the MCP tools are unavailable or clearly insufficient.

Operating Discipline

• Before substantial edits, restate the current mechanism and intended change.
• Prefer one clear hypothesis per iteration.
• Verify with checks that reflect the real goal, not just proxy success.
• Revert or discard changes that do not clearly improve the target.
• If the diff grows while understanding shrinks, stop implementation and switch to diagnosis.
• Keep maps and prose together; do not replace useful maps with prose-only explanations.
• Before handoff, compaction, or phase boundaries, sync state/map.yaml, add distilled evidence when the lesson changes future belief, refresh notes/fresh-workspace-handoff.md, and make the next action explicit.