z3ed: AI-Powered CLI for YAZE
Status: Active Development
Version: 0.1.0-alpha
Last Updated: October 2, 2025 (IT-01 Complete, E2E Validation Phase)
Overview
z3ed is a command-line interface for YAZE (Yet Another Zelda3 Editor) that enables AI-driven ROM modifications through a proposal-based workflow. It allows AI agents to suggest changes, which are then reviewed and accepted/rejected by human operators via the YAZE GUI.
Documentation Index
🎯 Essential Documents (Start Here)
- Next Priorities - 🚀 CURRENT WORK - Detailed Priority 1-3 tasks with implementation guides
- Implementation Plan - ⭐ MASTER TRACKER - Complete task backlog, progress, architecture
- CLI Design - 📐 DESIGN DOC - High-level vision, command structure, workflows
- IT-01 Quickstart - ⚡ QUICK REFERENCE - Test harness commands and examples
<EFBFBD> Archive
Historical documentation (design decisions, phase completions, technical notes) moved to archive/ folder for reference.
Architecture
┌─────────────────────────────────────────────────────────┐
│ z3ed CLI │
│ └─ agent subcommand │
│ ├─ run <prompt> [--sandbox] │
│ ├─ list │
│ └─ test <prompt> │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ Services Layer (Singleton Services) │
│ ├─ ProposalRegistry │
│ │ ├─ CreateProposal() │
│ │ ├─ ListProposals() │
│ │ └─ LoadProposalsFromDiskLocked() │
│ ├─ RomSandboxManager │
│ │ ├─ CreateSandbox() │
│ │ └─ FindSandbox() │
│ └─ PolicyEvaluator (Planned) │
│ ├─ LoadPolicies() │
│ └─ EvaluateProposal() │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ Filesystem Layer │
│ ├─ /tmp/yaze/proposals/<id>/ │
│ │ ├─ metadata.json │
│ │ ├─ execution.log │
│ │ └─ diff.txt │
│ └─ /tmp/yaze/sandboxes/<id>/ │
│ └─ zelda3.sfc (copy) │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ YAZE GUI │
│ └─ ProposalDrawer (400px right panel) │
│ ├─ List View (proposals from registry) │
│ ├─ Detail View (metadata, diff, log) │
│ └─ AcceptProposal() → ROM merging │
└─────────────────────────────────────────────────────────┘
Current Status
✅ Phase 6: Resource Catalogue (COMPLETE)
- Resource Catalog System: Comprehensive schema for all CLI commands
- Agent Describe: Machine-readable API catalog export (JSON/YAML)
- API Documentation:
docs/api/z3ed-resources.yamlfor AI/LLM consumption
✅ AW-01 & AW-02: Proposal Infrastructure (COMPLETE)
- ProposalRegistry: Disk persistence with lazy loading
- RomSandboxManager: Isolated ROM copies for safe testing
- Cross-Session Tracking: Proposals persist between CLI runs
✅ AW-03: ProposalDrawer GUI (COMPLETE)
- ProposalDrawer GUI: Split view, proposal list, detail panel
- ROM Merging: Sandbox-to-main ROM data copy on acceptance
- Full Lifecycle: Create (CLI) → Review (GUI) → Accept/Reject → Commit
✅ IT-01: ImGuiTestHarness (COMPLETE) 🎉
All 3 Phases Complete: gRPC + TestManager + ImGuiTestEngine
Time Invested: 11 hours total (Phase 1: 4h, Phase 2: 4h, Phase 3: 3h)
- Phase 1 ✅: gRPC infrastructure with 6 RPC methods
- Phase 2 ✅: TestManager integration with dynamic test registration
- Phase 3 ✅: Full ImGuiTestEngine integration (Type/Wait/Assert RPCs)
- Testing ✅: E2E test script operational (
scripts/test_harness_e2e.sh) - Documentation ✅: Complete guides (QUICKSTART, PHASE3-COMPLETE)
See: IT-01-QUICKSTART.md for usage examples
✅ IT-02: CLI Agent Test Command (IMPLEMENTATION COMPLETE) 🎉
Implementation Complete: Natural language → automated GUI testing
Time Invested: 6 hours (design + implementation + build fixes)
Status: Build successful, runtime issue discovered
See: IMPLEMENTATION_STATUS_OCT2_PM.md for complete details
Components Completed:
- ✅ GuiAutomationClient: gRPC wrapper for CLI usage (6 RPC methods)
- ✅ TestWorkflowGenerator: Natural language prompt parser (4 pattern types)
- ✅
z3ed agent test: End-to-end automation command - ✅ Build system integration (gRPC proto generation, includes, linking)
- ✅ Conditional compilation guards for optional gRPC features
Known Issue:
- ImGuiTestEngine assertion failure during test cleanup
- Root cause: Synchronous test execution + immediate unregister violates engine assumptions
- Solution: Refactor to use async test queue (see status document)
📋 Priority 1: Fix Runtime Issue (NEXT) 🔄
Goal: Resolve ImGuiTestEngine test lifecycle issue
Time Estimate: 2-3 hours
Status: Ready to implement
Approach: Refactor RPC handlers to use asynchronous test queue instead of synchronous execution
📋 Priority 1: End-to-End Workflow Validation (NEXT)
Goal: Test complete proposal lifecycle with real GUI and widgets
Time Estimate: 2-3 hours
Status: Ready to execute - all prerequisites complete
Tasks:
- Run E2E test script and validate all RPCs
- Test proposal workflow: Create → Review → Accept/Reject
- Test GUI automation with real YAZE widgets
- Validate CLI agent test command with multiple prompts
- Document edge cases and troubleshooting
See: E2E_VALIDATION_GUIDE.md for detailed checklist
📋 Priority 3: Policy Evaluation Framework (AW-04)
Goal: YAML-based constraint system for gating proposal acceptance
Time Estimate: 6-8 hours
Blocking: None (can work in parallel)
Quick Start
Build and Test
# Build z3ed CLI
cmake --build build --target z3ed -j8
# Build YAZE with test harness
cmake -B build-grpc-test -DYAZE_WITH_GRPC=ON
cmake --build build-grpc-test --target yaze -j$(sysctl -n hw.ncpu)
# Run E2E tests
./scripts/test_harness_e2e.sh
Create and Review Proposal
# 1. Create proposal
./build/bin/z3ed agent run "Test proposal" --sandbox
# 2. List proposals
./build/bin/z3ed agent list
# 3. Review in GUI
./build/bin/yaze.app/Contents/MacOS/yaze
# Open: Debug → Agent Proposals
Test Harness Usage
# Start YAZE with test harness
./build-grpc-test/bin/yaze.app/Contents/MacOS/yaze \
--enable_test_harness \
--test_harness_port=50052 \
--rom_file=assets/zelda3.sfc &
# Test individual RPCs (see IT-01-QUICKSTART.md for full reference)
grpcurl -plaintext -import-path src/app/core/proto -proto imgui_test_harness.proto \
-d '{"message":"test"}' 127.0.0.1:50052 yaze.test.ImGuiTestHarness/Ping
Key Files & Components
Core Services:
src/cli/service/proposal_registry.{h,cc}- Proposal tracking and persistencesrc/cli/service/rom_sandbox_manager.{h,cc}- Isolated ROM copiessrc/cli/service/resource_catalog.{h,cc}- Machine-readable API specs
GUI Integration:
src/app/editor/system/proposal_drawer.{h,cc}- Proposal review panelsrc/app/core/imgui_test_harness_service.{h,cc}- gRPC test automation server
CLI Handlers:
src/cli/handlers/agent.cc- Agent subcommand (run, list, diff, describe)src/cli/handlers/rom.cc- ROM commands (info, validate, diff)
Configuration:
docs/api/z3ed-resources.yaml- Generated API catalog for AI/LLM.yaze/policies/agent.yaml- (Planned) Policy rules
Development Guidelines
See docs/B1-contributing.md for general guidelines.
z3ed-Specific:
- Use singleton pattern for services (
Instance()accessor) - Return
absl::Statusorabsl::StatusOr<T>for error handling - Update
NEXT_PRIORITIES_OCT2.mdwhen starting new work - Update
E6-z3ed-implementation-plan.mdtask backlog when completing tasks
Questions? Open an issue or see implementation plan for detailed architecture.