76 lines
4.7 KiB
Markdown
76 lines
4.7 KiB
Markdown
# 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](./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](../../../AGENTS.md) for rules on communication, task logging, and handoffs.
|
||
4. **Check Status**: Review the [coordination-board.md](./coordination-board.md) for active tasks and blockers.
|
||
5. **Keep docs lean**: Use [doc-hygiene.md](./doc-hygiene.md) and avoid creating duplicate specs; archive idle docs.
|
||
|
||
## Documentation Index
|
||
|
||
### Core Coordination (Keep Visible)
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| [AGENTS.md](../../../AGENTS.md) | **The Core Protocol.** Read this first. Defines how to work. |
|
||
| [personas.md](./personas.md) | **Who is Who.** Canonical list of Agent IDs and their scopes. |
|
||
| [.claude/agents/*](../../../.claude/agents) | **System Prompts.** Persona-specific prompts for all agents. |
|
||
| [coordination-board.md](./coordination-board.md) | **The Live Board.** Shared state, active tasks, and requests. |
|
||
| [collaboration-framework.md](./collaboration-framework.md) | **Team Organization.** Architecture vs Automation team structure and protocols. |
|
||
|
||
### Active Projects
|
||
| File | Purpose | Status |
|
||
|------|---------|--------|
|
||
| [initiative-v040.md](./initiative-v040.md) | v0.4.0 development plan with 5 parallel workstreams | ACTIVE |
|
||
| [handoff-sidebar-menubar-sessions.md](./handoff-sidebar-menubar-sessions.md) | UI systems architecture reference | Active Reference |
|
||
| [wasm-development-guide.md](./wasm-development-guide.md) | WASM build and development guide | UPDATED |
|
||
| [wasm-antigravity-playbook.md](./wasm-antigravity-playbook.md) | WASM with Gemini integration and debugging | UPDATED |
|
||
| [web-port-handoff.md](./web-port-handoff.md) | WASM web build status and blockers | IN_PROGRESS |
|
||
|
||
### Documentation Hygiene
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| [doc-hygiene.md](./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.**
|