docs: Update implementation plan and README for clarity and recent accomplishments
This commit is contained in:
scawful
@@ -1,224 +1,53 @@
|
||||
# z3ed: AI-Powered CLI for YAZE
|
||||
|
||||
**Status**: Active Development
|
||||
**Version**: 0.1.0-alpha
|
||||
**Last Updated**: October 2, 2025 (E2E Validation 80% Complete)
|
||||
**Status**: Active Development
|
||||
|
||||
## Overview
|
||||
|
||||
z3ed is a command-line interface for YAZE that enables AI-driven ROM modifications through a proposal-based workflow. It provides both human-accessible commands and machine-readable APIs for LLM integration.
|
||||
`z3ed` is a command-line interface for YAZE that enables AI-driven ROM modifications through a proposal-based workflow. It provides both human-accessible commands for developers and machine-readable APIs for LLM integration, forming the backbone of an agentic development ecosystem.
|
||||
|
||||
This directory contains the primary documentation for the `z3ed` system.
|
||||
|
||||
## Core Documentation
|
||||
|
||||
### Essential Documents (Read These First)
|
||||
Start here to understand the architecture, learn how to use the commands, and see the current development status.
|
||||
|
||||
1. **[E6-z3ed-cli-design.md](E6-z3ed-cli-design.md)** - **SOURCE OF TRUTH**
|
||||
- Architecture overview
|
||||
- Design goals and principles
|
||||
- Command structure
|
||||
- Agentic workflow framework
|
||||
1. **[E6-z3ed-cli-design.md](E6-z3ed-cli-design.md)** - **Design & Architecture**
|
||||
* The "source of truth" for the system's architecture, design goals, and the agentic workflow framework. Read this first to understand *why* the system is built the way it is.
|
||||
|
||||
2. **[E6-z3ed-reference.md](E6-z3ed-reference.md)** - **TECHNICAL REFERENCE**
|
||||
- Complete command reference
|
||||
- API documentation
|
||||
- Implementation guides
|
||||
- Troubleshooting
|
||||
2. **[E6-z3ed-reference.md](E6-z3ed-reference.md)** - **Technical Reference & Guides**
|
||||
* A complete command reference, API documentation, implementation guides, and troubleshooting tips. Use this as your day-to-day manual for working with `z3ed`.
|
||||
|
||||
3. **[E6-z3ed-implementation-plan.md](E6-z3ed-implementation-plan.md)** - **IMPLEMENTATION TRACKER**
|
||||
- Task backlog and roadmap
|
||||
- Progress tracking
|
||||
- Known issues
|
||||
- Next priorities
|
||||
|
||||
### Quick Start Guides
|
||||
|
||||
4. **[IT-01-QUICKSTART.md](IT-01-QUICKSTART.md)** - Test harness quick start
|
||||
- Starting the gRPC server
|
||||
- Testing with grpcurl
|
||||
- Common workflows
|
||||
|
||||
5. **[AGENT_TEST_QUICKREF.md](AGENT_TEST_QUICKREF.md)** - CLI agent test command
|
||||
- Supported prompt patterns
|
||||
- Example workflows
|
||||
- Error handling
|
||||
|
||||
6. **[E2E_VALIDATION_GUIDE.md](E2E_VALIDATION_GUIDE.md)** - Complete validation checklist
|
||||
- Testing procedures
|
||||
- Success criteria
|
||||
- Issue reporting
|
||||
|
||||
### Implementation Guides
|
||||
|
||||
7. **[IMGUI_ID_MANAGEMENT_REFACTORING.md](IMGUI_ID_MANAGEMENT_REFACTORING.md)** - GUI ID management refactoring
|
||||
- Hierarchical widget ID system
|
||||
- Widget registry for test automation
|
||||
- Migration guide for editors
|
||||
- Integration with z3ed agent
|
||||
|
||||
### Status Documents
|
||||
|
||||
8. **[PROJECT_STATUS_OCT2.md](PROJECT_STATUS_OCT2.md)** - Current project status
|
||||
- Component completion percentages
|
||||
- Performance metrics
|
||||
- Known limitations
|
||||
|
||||
9. **[NEXT_PRIORITIES_OCT2.md](NEXT_PRIORITIES_OCT2.md)** - Detailed next steps
|
||||
- Priority 0-3 task breakdowns
|
||||
- Implementation guides
|
||||
- Time estimates
|
||||
3. **[E6-z3ed-implementation-plan.md](E6-z3ed-implementation-plan.md)** - **Roadmap & Status**
|
||||
* The project's task backlog, roadmap, progress tracking, and a list of known issues. Check this document for current priorities and to see what's next.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Build z3ed
|
||||
|
||||
```bash
|
||||
# Basic build (without gRPC)
|
||||
cmake --build build --target z3ed -j8
|
||||
# Basic build (without GUI automation support)
|
||||
cmake --build build --target z3ed
|
||||
|
||||
# With gRPC support (for GUI automation)
|
||||
# Build with gRPC support (for GUI automation)
|
||||
cmake -B build-grpc-test -DYAZE_WITH_GRPC=ON
|
||||
cmake --build build-grpc-test --target z3ed -j$(sysctl -n hw.ncpu)
|
||||
cmake --build build-grpc-test --target z3ed
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
### Common Commands
|
||||
|
||||
```bash
|
||||
# Display ROM info
|
||||
z3ed rom info --rom=zelda3.sfc
|
||||
# Create an agent proposal in a safe sandbox
|
||||
z3ed agent run --prompt "Make all soldier armor red" --rom=zelda3.sfc --sandbox
|
||||
|
||||
# Export a palette
|
||||
z3ed palette export sprites_aux1 4 soldier.col
|
||||
|
||||
# Create an agent proposal
|
||||
z3ed agent run --prompt "Make soldiers red" --rom=zelda3.sfc --sandbox
|
||||
|
||||
# List all proposals
|
||||
# List all active and past proposals
|
||||
z3ed agent list
|
||||
|
||||
# View proposal changes
|
||||
# View the changes for the latest proposal
|
||||
z3ed agent diff
|
||||
|
||||
# Automated GUI testing (requires test harness)
|
||||
z3ed agent test --prompt "Open Overworld editor and verify it loads"
|
||||
# Run an automated GUI test (requires test harness to be running)
|
||||
z3ed agent test --prompt "Open the Overworld editor and verify it loads"
|
||||
```
|
||||
|
||||
### Start Test Harness (Optional)
|
||||
|
||||
```bash
|
||||
# Terminal 1: 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 &
|
||||
|
||||
# Terminal 2: Run automated test
|
||||
./build-grpc-test/bin/z3ed agent test \
|
||||
--prompt "Open Overworld editor"
|
||||
```
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
```
|
||||
docs/z3ed/
|
||||
├── Core Documentation (3 files)
|
||||
│ ├── E6-z3ed-cli-design.md [Source of Truth]
|
||||
│ ├── E6-z3ed-reference.md [Technical Reference]
|
||||
│ └── E6-z3ed-implementation-plan.md [Tracker]
|
||||
│
|
||||
├── Quick Start Guides (3 files)
|
||||
│ ├── IT-01-QUICKSTART.md [Test Harness]
|
||||
│ ├── AGENT_TEST_QUICKREF.md [CLI Agent Test]
|
||||
│ └── E2E_VALIDATION_GUIDE.md [Validation]
|
||||
│
|
||||
├── Implementation Guides (1 file)
|
||||
│ └── IMGUI_ID_MANAGEMENT_REFACTORING.md [GUI ID System]
|
||||
│
|
||||
├── Status Documents (4 files)
|
||||
│ ├── README.md [This file]
|
||||
│ ├── PROJECT_STATUS_OCT2.md [Current Status]
|
||||
│ ├── NEXT_PRIORITIES_OCT2.md [Next Steps]
|
||||
│ └── WORK_SUMMARY_OCT2.md [Recent Work]
|
||||
│
|
||||
└── Archive (15+ files)
|
||||
└── Historical documentation and implementation notes
|
||||
```
|
||||
|
||||
## Key Features
|
||||
|
||||
### ✅ Completed (Production-Ready on macOS)
|
||||
|
||||
- **Resource-Oriented CLI**: Clean command structure (`z3ed <resource> <action>`)
|
||||
- **Resource Catalogue**: Machine-readable API specs (`docs/api/z3ed-resources.yaml`)
|
||||
- **Acceptance Workflow**: Proposal tracking, sandbox management, GUI review
|
||||
- **ImGuiTestHarness (IT-01)**: gRPC-based GUI automation (6 RPC methods)
|
||||
- **CLI Agent Test (IT-02)**: Natural language → automated GUI tests
|
||||
- **ProposalDrawer**: Integrated proposal review UI in YAZE
|
||||
- **ROM Operations**: info, validate, diff, generate-golden
|
||||
- **Palette Operations**: export, import, list
|
||||
- **Overworld Operations**: get-tile, set-tile
|
||||
- **Dungeon Operations**: list-rooms, add-object
|
||||
|
||||
### 🔄 In Progress (80% Complete)
|
||||
|
||||
- **E2E Validation**: Full workflow testing (window detection needs fix)
|
||||
|
||||
### 📋 Planned (Next Priorities)
|
||||
|
||||
1. **Policy Evaluation Framework (AW-04)**: YAML-based constraints
|
||||
2. **Windows Cross-Platform Testing**: Validate on Windows with vcpkg
|
||||
3. **Production Readiness**: Telemetry, screenshot, expanded tests
|
||||
|
||||
## Architecture Highlights
|
||||
|
||||
### Proposal-Based Workflow
|
||||
|
||||
```
|
||||
User Prompt → AI Service → Sandbox ROM → Execute Commands →
|
||||
Create Proposal → Review in GUI → Accept/Reject → Commit to ROM
|
||||
```
|
||||
|
||||
### Component Stack
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ AI Agent (LLM) │
|
||||
├─────────────────────────────────┤
|
||||
│ z3ed CLI │
|
||||
├─────────────────────────────────┤
|
||||
│ Service Layer │
|
||||
│ • ProposalRegistry │
|
||||
│ • RomSandboxManager │
|
||||
│ • GuiAutomationClient │
|
||||
│ • TestWorkflowGenerator │
|
||||
├─────────────────────────────────┤
|
||||
│ ImGuiTestHarness (gRPC) │
|
||||
├─────────────────────────────────┤
|
||||
│ YAZE GUI + ProposalDrawer │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
**Machine-Readable API**: `docs/api/z3ed-resources.yaml`
|
||||
**Proto Schema**: `src/app/core/proto/imgui_test_harness.proto`
|
||||
**Test Script**: `scripts/test_harness_e2e.sh`
|
||||
|
||||
## Contributing
|
||||
|
||||
See **[B1-contributing.md](../B1-contributing.md)** for general contribution guidelines.
|
||||
|
||||
For z3ed-specific development:
|
||||
1. Read **E6-z3ed-cli-design.md** for architecture
|
||||
2. Check **E6-z3ed-implementation-plan.md** for open tasks
|
||||
3. Use **E6-z3ed-reference.md** for API details
|
||||
4. Follow **NEXT_PRIORITIES_OCT2.md** for current work
|
||||
|
||||
## License
|
||||
|
||||
Same as YAZE - see `LICENSE` in repository root.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: October 2, 2025
|
||||
**Contributors**: @scawful, GitHub Copilot
|
||||
**Next Milestone**: E2E Validation Complete (Est. Oct 3, 2025)
|
||||
See the **[Technical Reference](E6-z3ed-reference.md)** for a full command list.
|
||||
|
||||
Reference in New Issue
Block a user