topfreegames · hspedro · Oct 29, 2025
diff --git a/docs/memory-bank/README.md b/docs/memory-bank/README.md
@@ -0,0 +1,106 @@
+# Memory Bank Index
+
+This directory contains the memory bank documentation for the Maestro project. These
+files serve as the persistent memory for AI agents working on this project.
+
+## 🚨 MANDATORY EXECUTION WORKFLOW
+
+**EVERY AI AGENT MUST FOLLOW THIS WORKFLOW FOR ALL REQUESTS:**
+
+### Step 1: Memory Bank Loading
+- **ALWAYS** read ALL memory bank files at the start of EVERY task
+- Load context from: `system-patterns.md`
+- This is **NOT OPTIONAL** - memory resets completely between sessions
+
+### Step 2: Deep Understanding & Clarification
+- **2.a** Understand the request profoundly, ask clarifying questions if needed
+- **2.b** State explicitly what was understood from the request
+- **2.c** Ask: "Should we proceed to create the execution plan?"
+
+### Step 3: Execution Plan Creation
+- **3.a** Break down the work into small, testable phases
+- For each phase, define:
+  - **Specific deliverables**
+  - **Test cases** (unit, integration, manual verification)
+  - **Linting validation** (`golangci-lint`, `gofmt`)
+  - **Compilation verification** (`go build`, `go test`)
+- **3.b** Present the complete plan and ask: "Should we proceed with implementation?"
+
+### Step 4: Plan Review & Approval
+- Wait for explicit approval before starting implementation
+- Address any feedback or modifications to the plan
+- Only proceed after clear confirmation
+
+### Step 5: Implementation with Progress Tracking
+- **5.a** Execute each phase sequentially. If the phase includes writing new tests, be sure to ask for feedback and approval on implementation before proceeding to writing tests.
+- For each completed phase:
+  - ✅ Run all defined tests
+  - ✅ Validate linting (`make lint/go` or equivalent)
+  - ✅ Ensure compilation (`go build ./...`)
+  - ✅ Update progress checklist in the plan
+- Maintain detailed progress tracking for context preservation if agent is interrupted
+
+### File Interdependencies
+To maximize effectiveness:
+- Start with `README.md` for workflow overview.
+- Load `system-patterns.md` for architectural context.
+- Use `execution-workflow-template.md` for task execution guidance.
+This sequence ensures full context before planning or implementing changes.
+
+## Core Files
+
+### 🏗️ [system-patterns.md](system-patterns.md)
+Documents the Maestro system architecture, design patterns, component relationships,
+and critical implementation paths.
+
+### 📝 [execution-workflow-template.md](execution-workflow-template.md)
+Template for structuring execution workflow - copy and use for every request to ensure
+consistent, high-quality delivery.
+
+## Quick Reference - Maestro
+
+- **Starting ANY task?** Use `execution-workflow-template.md` to structure your approach
+- **Need Maestro system patterns?** Check `system-patterns.md` for layered architecture
+and Maestro-specific patterns
+
+## Navigation Flow - Maestro Backend
+
+```
+1. system-patterns.md (How is Maestro architected?)
+   ↓
+2. execution-workflow-template.md (How do we execute tasks?)
+```
+
+## Maestro-Specific Execution Workflow
+
+```
+🔄 EVERY REQUEST MUST FOLLOW THIS FLOW:
+
+1. 📚 Load Memory Bank (ALL files)
+   ↓
+2. 🎾 Deep Understanding
+   ├── Clarify Maestro feature requirements
+   ├── State Maestro understanding explicitly
+   └── Ask: "Proceed to Maestro planning?"
+   ↓
+3. 📋 Create Execution Plan
+   ├── Break into small testable phases
+   ├── Define unit and integration tests
+   ├── Include linting & compilation
+   └── Ask: "Proceed with Maestro implementation?"
+   ↓
+4. ✅ Get Plan Approval
+   ├── Address feedback
+   ├── Validate architecture compliance
+   └── Wait for explicit confirmation
+   └── Create the task progress file
+   ↓
+5. 🚀 Implementation with Tracking
+   ├── Execute phase sequentially
+   ├── Run tests, lint, compile for each phase
+   ├── Validate Maestro patterns compliance
+   ├── Update progress checklist
+   └── Maintain context for interruptions
+```
+**Important**: Remember, After any memory reset, start by reading ALL Maestro memory
+bank files to restore full Maestro Backend project context.
diff --git a/docs/memory-bank/execution-workflow-template.md b/docs/memory-bank/execution-workflow-template.md
@@ -0,0 +1,217 @@
+# Execution Workflow Template
+
+Use this template for every request to ensure consistent, high-quality execution.
+
+## Step 1: Memory Bank Loading ✅
+- [ ] Read `docs/memory-bank/system-patterns.md`
+- [ ] Read `docs/memory-bank/tech-context.md`
+- [ ] Context fully loaded and understood
+
+## Step 2: Deep Understanding & Clarification
+
+### Request Analysis
+**Original Request:**
+```
+[Copy the user's exact request here]
+```
+
+**My Understanding:**
+```
+[Explain in detail what you understand the user is asking for]
+```
+
+**Clarifying Questions (if any):**
+```
+[List any questions needed to fully understand the request]
+```
+
+**Final Understanding Statement:**
+```
+[Clear, explicit statement of what will be implemented]
+```
+
+**Confirmation:** Should we proceed to create the execution plan?
+
+## Step 3: Execution Plan Creation
+
+### Phase Breakdown
+
+#### Phase 1: [Phase Name]
+**Deliverables:**
+- [ ] [Specific deliverable 1]
+- [ ] [Specific deliverable 2]
+
+**Test Cases:**
+- [ ] Unit tests: [describe tests]
+- [ ] Integration tests: [describe tests]
+- [ ] Manual verification: [describe verification steps]
+
+**Interface Testing Coverage (CRITICAL for interface implementations):**
+- [ ] All interface methods identified: [list all methods]
+- [ ] Complex methods prioritized
+- [ ] Success scenarios tested for all methods
+- [ ] Error scenarios tested for all methods
+- [ ] Dependencies mocked properly
+- [ ] Business logic verified, not just method signatures
+
+**Quality Checks:**
+- [ ] Linting: `make lint/go` or `golangci-lint run`
+- [ ] Formatting: `gofmt -s -w .`
+- [ ] Compilation: `go build ./...`
+- [ ] Tests: `go test ./...`
+
+#### Phase 2: [Phase Name]
+**Deliverables:**
+- [ ] [Specific deliverable 1]
+- [ ] [Specific deliverable 2]
+
+**Test Cases:**
+- [ ] Unit tests: [describe tests]
+- [ ] Integration tests: [describe tests]
+- [ ] Manual verification: [describe verification steps]
+
+**Interface Testing Coverage (CRITICAL for interface implementations):**
+- [ ] All interface methods identified: [list all methods]
+- [ ] Complex methods prioritized
+- [ ] Success scenarios tested for all methods
+- [ ] Error scenarios tested for all methods
+- [ ] Dependencies mocked properly
+- [ ] Business logic verified, not just method signatures
+
+**Quality Checks:**
+- [ ] Linting: `make lint/go` or `golangci-lint run`
+- [ ] Formatting: `gofmt -s -w .`
+- [ ] Compilation: `go build ./...`
+- [ ] Tests: `go test ./...`
+
+#### Phase N: [Final Phase]
+**Deliverables:**
+- [ ] [Final deliverable]
+- [ ] Documentation updates
+- [ ] Integration verification
+
+**Test Cases:**
+- [ ] End-to-end testing
+- [ ] Performance verification
+- [ ] Security validation
+
+**Quality Checks:**
+- [ ] Final linting validation
+- [ ] Complete compilation check
+- [ ] Full test suite execution
+- [ ] Code review checklist
+
+### Risk Assessment
+**Potential Risks:**
+- [ ] [Risk 1 and mitigation strategy]
+- [ ] [Risk 2 and mitigation strategy]
+
+**Dependencies:**
+- [ ] [External dependency 1]
+- [ ] [External dependency 2]
+
+**Confirmation:** Should we proceed with implementation?
+
+## Step 4: Plan Review & Approval
+
+**User Feedback:**
+```
+[Record any feedback or modifications requested]
+```
+
+**Plan Adjustments:**
+```
+[Document any changes made to the plan based on feedback]
+```
+
+**Final Approval:** ✅ Confirmed to proceed with implementation
+
+## Step 5: Implementation Progress Tracking
+
+### Phase 1: [Phase Name] - Status: [Not Started/In Progress/Completed]
+- [ ] **Implementation:** [Implementation details]
+- [ ] **Tests Executed:** [Test results]
+- [ ] **Linting:** ✅ Passed / ❌ Failed - [Details]
+- [ ] **Compilation:** ✅ Passed / ❌ Failed - [Details]
+- [ ] **Phase Complete:** ✅ / ❌
+
+**Notes:**
+```
+[Any important notes, issues encountered, or decisions made]
+```
+
+### Phase 2: [Phase Name] - Status: [Not Started/In Progress/Completed]
+- [ ] **Implementation:** [Implementation details]
+- [ ] **Tests Executed:** [Test results]
+- [ ] **Linting:** ✅ Passed / ❌ Failed - [Details]
+- [ ] **Compilation:** ✅ Passed / ❌ Failed - [Details]
+- [ ] **Phase Complete:** ✅ / ❌
+
+**Notes:**
+```
+[Any important notes, issues encountered, or decisions made]
+```
+
+### Phase N: [Final Phase] - Status: [Not Started/In Progress/Completed]
+- [ ] **Implementation:** [Implementation details]
+- [ ] **Tests Executed:** [Test results]
+- [ ] **Linting:** ✅ Passed / ❌ Failed - [Details]
+- [ ] **Compilation:** ✅ Passed / ❌ Failed - [Details]
+- [ ] **Phase Complete:** ✅ / ❌
+
+**Notes:**
+```
+[Any important notes, issues encountered, or decisions made]
+```
+
+## Final Verification
+
+### Overall Project Status
+- [ ] All phases completed successfully
+- [ ] All tests passing
+- [ ] No linting errors
+- [ ] Successful compilation
+- [ ] Documentation updated
+- [ ] Ready for review/deployment
+
+### Summary
+**What was accomplished:**
+```
+[Summary of all work completed]
+```
+
+**Files modified/created:**
+```
+[List of all files that were changed or created]
+```
+
+**Tests added/modified:**
+```
+[List of test files and test cases]
+```
+
+**Verification commands:**
+```bash
+# Commands to verify the implementation works
+make run/tests
+make lint
+make build
+# Any additional verification steps
+```
+
+**Next steps (if any):**
+```
+[Any follow-up work or recommendations]
+```
+
+---
+
+## Template Usage Notes
+
+1. **Copy this template** for each new request
+2. **Fill in each section** as you progress through the workflow
+3. **Update progress in real-time** to maintain context
+4. **Use checkboxes** to track completion status
+5. **Document everything** - assume the agent might be interrupted
+6. **Be specific** - avoid vague descriptions
+7. **Include commands** - provide exact commands for verification