yaze/docs/internal/agents/README.md

Agent Coordination Hub

Welcome to the yaze internal agent workspace. This directory contains the rules, roles, and records for AI agents contributing to the project.

Quick Start

1. Identify Your Role: Check personas.md to choose the correct Agent ID.
2. Load Your Prompt: Open .claude/agents/<agent-id>.md for your persona’s system prompt (available to all agents).
3. Follow the Protocol: Read AGENTS.md for rules on communication, task logging, and handoffs.
4. Check Status: Review the coordination-board.md for active tasks and blockers.
5. Keep docs lean: Use doc-hygiene.md and avoid creating duplicate specs; archive idle docs.

Documentation Index

Core Coordination (Keep Visible)

File	Purpose
AGENTS.md	The Core Protocol. Read this first. Defines how to work.
personas.md	Who is Who. Canonical list of Agent IDs and their scopes.
.claude/agents/*	System Prompts. Persona-specific prompts for all agents.
coordination-board.md	The Live Board. Shared state, active tasks, and requests.
collaboration-framework.md	Team Organization. Architecture vs Automation team structure and protocols.

Active Projects

File	Purpose	Status
initiative-v040.md	v0.4.0 development plan with 5 parallel workstreams	ACTIVE
handoff-sidebar-menubar-sessions.md	UI systems architecture reference	Active Reference
wasm-development-guide.md	WASM build and development guide	UPDATED
wasm-antigravity-playbook.md	WASM with Gemini integration and debugging	UPDATED
web-port-handoff.md	WASM web build status and blockers	IN_PROGRESS

Documentation Hygiene

File	Purpose
doc-hygiene.md	Rules to keep specs/notes lean and archived on time.

Tools

Agents have built-in CLI capabilities to assist with this workflow:

• z3ed agent todo: Manage your personal task list.
• z3ed agent handoff: Generate context bundles for the next agent.
• z3ed agent chat: (If enabled) Inter-agent communication channel.

Picking the right agent

• ai-infra-architect: AI/agent infra, MCP/gRPC, z3ed tooling, model plumbing.
• backend-infra-engineer: Build/packaging/toolchains, CI reliability, release plumbing.
• imgui-frontend-engineer: ImGui/editor UI, renderer/backends, canvas/docking UX.
• snes-emulator-expert: Emulator core (CPU/APU/PPU), performance/accuracy/debugging.
• zelda3-hacking-expert: Gameplay/ROM logic, data formats, hacking workflows.
• test-infrastructure-expert: Test harnesses, CTest/gMock infra, flake/bloat triage.
• docs-janitor: Docs/process hygiene, onboarding, checklists. Pick the persona that owns the dominant surface of your task; cross-surface work should add both owners to the board entry.

Build & Test

Default builds now share build/ (native) and build-wasm/ (WASM). If you need isolation, set YAZE_BUILD_DIR or create a local CMakeUserPresets.json.

• Build: ./scripts/agent_build.sh [target] (Default target: yaze)
• Test: ./scripts/agent_build.sh yaze_test && ./build/bin/yaze_test
• Directory: build/ by default (override via YAZE_BUILD_DIR).

Archive

This directory maintains a lean, active documentation set. Historical or reference-only documents are organized in archive/:

Archived Categories

• large-ref-docs/ (148KB) - Large reference documents (40KB+): dungeon rendering, ZSOW, design specs
• foundation-docs-old/ (68KB) - Older foundational docs (October) on agent architecture and CLI design
• utility-tools/ (52KB) - Tool documentation: filesystem, dev-assist, modularity, AI dev tools
• wasm-planning-2025/ (64KB) - Earlier WASM planning iterations
• testing-docs-2025/ (112KB) - Test infrastructure and CI documentation archives
• gemini-session-2025-11-23/ (40KB) - Gemini-specific session context and task planning
• plans-2025-11/ (56KB) - Completed or archived feature/project plans
• legacy-2025-11/ (28KB) - Completed initiatives and coordination improvements
• session-handoffs/ (24KB) - Agent handoff and onboarding documents
• reports/ (24KB) - Audit reports and documentation assessments

Target: 10-15 active files in root directory. Archive completed work within 1-2 weeks of completion.