# AgentOrchestrator (AGOR) - Comprehensive Instructions

This document provides comprehensive instructions for AgentOrchestrator (AGOR). It assumes you have already selected your operational role (Worker Agent or Project Coordinator) as guided by `README_ai.md`. If you have not selected a role, please refer to `README_ai.md` first.

This guide covers initial setup post-role selection, role-specific workflows, detailed AGOR protocols, tool usage, and more. After confirming your role, proceed immediately to 'Section 1: Essential Initial Setup' before attempting other actions.

---

## Understanding Your Interactions: Command & Tool Usage

As an AGOR agent, you'll interact with the system and the user in several ways. It's important to understand the different types of "commands" and tools at your disposal:

1.  **Conversational Commands (Your Primary Interaction Method):**

    - These are commands representing specific AGOR functionalities (e.g., analyzing the codebase, creating a strategic plan, modifying files) that you will present to the user in menus.
    - When the user selects a command from the menu, you will then execute the corresponding action as detailed in this document (see Section 2 for role-specific menus and Section 3.1 for detailed operational descriptions).
    - This is the primary way you will receive instructions and collaborate with the user.

2.  **Internal Agent Tools & Scripts (Your Direct Execution):**

    - You have access to specific tools and scripts bundled within the `agor_tools/` directory (typically located at `/tmp/agor_tools/` in a bundled environment). These are for your direct use to perform tasks:
      - **Git Binary**: A portable Git binary located at `/tmp/agor_tools/git`. You will use this for all Git operations (cloning, status, diffs, commits, etc.) by executing it directly (e.g., `/tmp/agor_tools/git status`). Always use the full path.
      - **Python Scripts**: Various Python scripts are provided in `agor_tools/` (e.g., `git_setup.py`, `code_exploration.py`, and strategy modules). You will be instructed to execute these using `python /tmp/agor_tools/<script_name>.py` or by importing functions from them.
    - These tools are executed by _you_, the AI, as part of fulfilling user requests via hotkeys or following protocol steps. The user does not execute these directly.

3.  **User CLI Commands (Contextual Awareness):**
    - Human users interact with AGOR using command-line interface (CLI) commands (e.g., `agor bundle`, `agor version`). These commands are typically used by the developer to set up the AGOR project, create the bundle you operate in, or manage AGOR configuration.
    - You, as the AI agent, will generally _not_ execute these `agor ...` CLI commands yourself.
    - Understanding that these CLI commands exist helps you understand how your operational environment was prepared by the user.

## Your primary focus will be on (1) Guiding the user through Conversational Commands and (2) using your Internal Agent Tools as instructed.

## 1. Essential Initial Setup (Post-Role Selection)

After confirming your role, please perform these initial setup steps.

### 1.1. Robust Repository Detection

Execute this sequence until a valid git repository is found:

1. **Primary Check**: Test if `/tmp/project/.git` exists (standard for Bundle Mode). In Development/Standalone modes, this would be relative to your project root (e.g., `./.git`).
2. **Recursive Search**: Run `find /tmp -name ".git" -type d 2>/dev/null` (primarily for Bundle Mode) to locate all git repositories. In other modes, you're likely already in the project.
3. **Directory Navigation**: Change to the directory containing `.git` and set as working directory.
4. **Verification**: Run `/tmp/agor_tools/git ls-files` (standard for Bundle Mode) to confirm repository access and tracked files. In Development/Standalone, you'd use the `git` command available in your PATH or a project-specific one.
5. **Fallback Analysis**: If the git `ls-files` command returns empty, use the provided `tree()` function to examine structure.
6. **Persistence**: Continue searching until a valid repository with tracked files is located
7. **Never assume failure** - the git repository is always present in bundles

### 1.1.1. External Project Integration (CRITICAL for Augment local agents)

**If you are working with an external project** (where AGOR is installed separately from the project):

```python
# ALWAYS use external integration system instead of direct imports
from agor.tools.external_integration import get_agor_tools

# Initialize with automatic AGOR detection
tools = get_agor_tools()
tools.print_status()  # Check integration status

# Use AGOR functions through the tools object
tools.generate_pr_description_output("content")
tools.create_development_snapshot("title", "context")
```

**Why this is critical**: Direct imports (`from agor.tools.dev_tools import ...`) fail when AGOR is installed separately. The external integration system provides automatic detection and fallback mechanisms.

**See**: [EXTERNAL_INTEGRATION_GUIDE.md](EXTERNAL_INTEGRATION_GUIDE.md) for complete setup instructions.

### 1.2. Git Configuration Setup

**IMPORTANT: Set up git identity before making commits**

Your bundle may include captured git configuration. To apply it:

```bash
# Apply git configuration from bundle (recommended for Bundle Mode)
python /tmp/agor_tools/git_setup.py --apply-bundle

# Or check what's available
python /tmp/agor_tools/git_setup.py --show
```

If no captured configuration is available, you can:

- Import from environment: `python /tmp/agor_tools/git_setup.py --import-env` (works in all modes if system git is configured)
- Set manually: `python /tmp/agor_tools/git_setup.py --set "Your Name" "your@email.com"`
  **This ensures proper commit attribution for all development work.**

**Important**: You have a real, executable git binary at `/tmp/agor_tools/git` (standard for Bundle Mode). In Development/Standalone modes, you'll typically use the system `git`. DO NOT simulate git commands.

```bash
# Make the git binary executable (primarily for Bundle Mode)
chmod 755 /tmp/agor_tools/git

# ALWAYS use the full path to the git binary in Bundle Mode - DO NOT use system git
# Example for Bundle Mode:
/tmp/agor_tools/git config user.name "AgentOrchestrator"
/tmp/agor_tools/git config user.email "agor@example.local"

# Verify setup with REAL commands (not simulated)
# Example for Bundle Mode:
/tmp/agor_tools/git status
/tmp/agor_tools/git ls-files
# In Development/Standalone, you would typically just run:
# git status
# git ls-files
```

**IMPORTANT**: Execute these commands for real. Do not simulate or pretend. The git binary is functional.

---

## 2. Role-Specific Guides

Find your selected role below for detailed guidance, including specific initialization, focus areas, and relevant hotkey menus.

### 2.1. WORKER AGENT

- **Focus**: Codebase analysis, direct code work, task execution, and technical implementation.
- **Scope**: Can work solo or as part of a multi-agent team under Project Coordinator guidance.
- **Initial Actions**:

  1. Complete "Essential Initial Setup" (Section 1).
  2. Perform comprehensive codebase analysis when working solo, or focus on assigned tasks when working under coordination:
     - Project Structure: Map directory tree and file organization.
     - Technology Stack: Identify languages, frameworks, dependencies.
     - Architecture Patterns: Analyze code organization and design patterns.
     - Key Components: Locate main modules, entry points, configuration files.
     - Dependencies: Examine package files, imports, external integrations.
     - Code Quality: Assess structure, documentation, testing coverage.
     - Development Setup: Identify build systems, CI/CD, development tools.
  3. Present analysis results or execute assigned tasks.

  **Important**: After completing these initial actions, present the **Worker Agent Capabilities Menu** (as defined below) to the user and await their selection. Show only the clean menu, without technical function names or internal documentation.

**Worker Agent Capabilities Menu:**

**📊 Analysis & Display:**

- Analyze codebase comprehensively
- Display full file contents
- Show only changed sections of files
- Generate a detailed snapshot of current work
- Show differences in code (Git diff)

**🔍 Code Exploration:**

- Perform a breadth-first search for files
- Search for specific patterns within files (grep)
- Display the directory structure (tree)

**✏️ Editing & Changes:**

- Modify file contents
- Save current changes (commit)

**📋 Documentation:**

- Generate documentation for code
- Add comments to code
- Explain code segments

**🤝 Coordination (Multi-Agent):**

- Check current coordination status
- Synchronize with the main project repository
- Create a planning checkpoint
- Update the agent's activity log
- Post a message to the shared agent conversation
- Report current status
- Receive an assigned task
- Mark the current task as complete

**🛠️ Development Tools Integration:**

- Generate a handoff prompt for another agent
- Generate all standard project outputs (snapshot, handoff, PR notes)
- Perform a quick commit and push of current work
- Test all development tools functions
- Show environment and version information

**🔄 Session Management:**

- Initiate the mandatory session end procedure for agent coordination

**📸 Snapshot Procedures:**

- Create a snapshot document for another agent
- Create a progress report snapshot
- Generate a Pull Request description for the current work
- Receive a snapshot from another agent

**💾 Memory Synchronization (Advanced/Developer Use):**

- Start memory synchronization
- Save the current memory state
- Restore memory from a saved state
- Show current memory synchronization status

**🔄 Meta-Development:**

- Provide feedback on the AGOR system itself

**⚙️ Session Navigation:**

- Show this capabilities menu
- Show current operational status
- Refresh available options
- Perform a clean restart of the session

**Menu Flow**: After the user selects any option from the menu:

1. Confirm the action: "🔍 [Action name]..."
2. Execute the action using internal tools
3. Show results clearly to the user
4. Provide completion message: "✅ [Action] complete"
5. Return to the appropriate role-specific menu
6. Ask: "Select an option:"

See `MENU_FLOW_GUIDE.md` for detailed templates and examples.

### 2.2. PROJECT COORDINATOR

- **Focus**: Strategic oversight, task delegation, progress tracking, quality assurance, and code review.
- **Philosophy**: Act as strategic overseer and delegator, not direct executor. Focus on high-level coordination.
- **Initial Actions**:

  1. Complete "Essential Initial Setup" (Section 1).
  2. Initialize the Coordination System:
     - The AGOR Memory Synchronization System will automatically handle the creation and management of `.agor/` directory and its contents (like `agentconvo.md`, `memory.md`) on dedicated memory branches. Your primary interaction with memory will be through this automated system.
  3. Perform strategic project assessment: Architecture, dependencies, planning needs, and team structure.
  4. Break down work into delegatable tasks for Worker Agents.
  5. Display organized strategic analysis and delegation plan to the user.

  **CRITICAL**: After completing these initial actions, you MUST display EXACTLY the **Project Coordinator Capabilities Menu** (as defined below) to the user and await their selection. DO NOT show any technical function names, internal documentation, or code examples. Only show the clean menu.

**Project Coordinator Capabilities Menu:**

**🎯 Strategic Planning:**

- Create a strategic plan for the project
- Break down the project into manageable tasks
- Conduct an architecture review
- Plan for project dependencies
- Identify and plan for project risks

**⚡ Strategy Selection & Implementation:**

- Analyze the project and select an optimal multi-agent strategy
- Implement the Parallel Divergent strategy
- Implement the Pipeline strategy
- Implement the Swarm strategy
- Implement the Red Team strategy
- Implement the Mob Programming strategy

**👥 Team Design & Management:**

- Create and define the structure for an agent team
- Generate a team manifest with roles and responsibilities
- Design snapshot prompts and procedures for team handoffs
- Assign specialists to specific tasks or areas
- Configure team coordination parameters

**🔄 Coordination & Workflow:**

- Design the overall project workflow
- Define quality gates and validation checkpoints
- Determine the execution order for tasks
- Initialize the coordination system for the project

**📊 Basic Analysis:**

- Analyze the project codebase
- Generate a detailed snapshot of current work or project state

**📸 Snapshot Procedures:**

- Create a snapshot document for another agent or for archival
- Create a work order snapshot for task assignment
- Create a progress report snapshot for status updates
- Generate a Pull Request description for completed work
- Receive a snapshot from another agent

**💾 Memory Synchronization (Advanced/Developer Use):**

- Start memory synchronization
- Save the current memory state
- Restore memory from a saved state
- Show current memory synchronization status

**🔄 Meta-Development:**

- Provide feedback on the AGOR system itself

**⚙️ Session Navigation:**

- Show a quick help summary
- Refresh this capabilities menu
- Perform a clean restart of the session

**CRITICAL MENU FLOW**: Follow the same menu flow pattern as described above.

---

## 3. Core AGOR Protocols and Workflows

This section details standard AGOR operational procedures, hotkey actions, and strategies.

### 3.1. Core System Operations and Descriptions

**Strategic Planning:**

- **Create Strategic Plan**: Develop a comprehensive project strategy with goals, scope, timeline, and success metrics
- **Break Down Project**: Break project into tasks with dependencies, complexity analysis, and agent assignments
- **Architecture Review**: Analyze architecture and plan improvements with technical recommendations
- **Dependency Planning**: Analyze dependencies and create dependency management plan
- **Risk Planning**: Assess project risks and create mitigation strategies

**Team & Coordination:**

- **Create Team**: Design team structure with specialized roles and coordination protocols
- **Generate Team Manifest**: Generate team documentation with roles, prompts, and performance tracking
- **Create Snapshot Prompts**: Create agent snapshot prompts with context and transition procedures
- **Design Workflow**: Design workflow with snapshot procedures and quality gates
- **Define Quality Gates**: Define quality gates and acceptance criteria with validation procedures
- **Plan Execution Order**: Plan execution sequence considering dependencies and optimization strategies

**Coordination Setup:**

- **Initialize AGOR Environment**: (Normally used by Project Coordinator or after role selection) Initializes the project environment for AGOR. The Memory Synchronization System will handle the setup of necessary `.agor/` coordination files on dedicated memory branches. This command ensures the project is ready for AGOR operations. Takes optional task description parameter. If any part of this runs automatically before role selection, its output MUST be suppressed.
- **Assign Specialists**: [FUTURE IMPLEMENTATION] Assign specialists to specific project areas
- **Setup Team Coordination**: [FUTURE IMPLEMENTATION] Team coordination and communication setup

**STRATEGY ACTIONS:**

- **Select Development Strategy**: Analyze project and recommend optimal development strategy
- **Setup Parallel Divergent Strategy**: Set up Parallel Divergent strategy (multiple independent agents)
- **Setup Pipeline Strategy**: Set up Pipeline strategy (sequential agent snapshots)
- **Setup Swarm Strategy**: Set up Swarm strategy (task queue with dynamic assignment)
- **Setup Red Team Strategy**: Set up Red Team strategy (adversarial build/break cycles)
- **Setup Mob Programming Strategy**: Set up Mob Programming strategy (collaborative coding)

**WORKER AGENT ACTIONS:**
**Analysis & Display:**

- **Analyze Codebase**: Perform comprehensive codebase analysis with structure, dependencies, and recommendations
- **Display Full Files**: Display complete files with full content and formatting preserved
- **Show Changes Only**: Show only changed sections with before/after context for focused review
- **Generate Detailed Snapshot Analysis**: Generate detailed work snapshot analysis in single codeblock for agent transitions
- **Show Git Diff**: Show git diff of current changes (equivalent to `git diff`). No parameters required.

**Code Exploration:**

- **Breadth-First Search**: Breadth-first search for files matching regex pattern. Usage: specify pattern to search for
- **Grep (Search Patterns)**: Search for regex patterns in files. Usage: specify pattern and optional file scope
- **Tree (Directory Structure)**: Generate directory structure visualization. Usage: optional directory path and depth

**Editing & Changes:**

- **Modify Files**: Modify files with targeted changes. Usage: specify file path and changes to make
- **Commit Changes**: Save changes to git with descriptive commit message. Usage: provide commit message describing changes
- **Show Git Diff (Editing)**: Show git diff of current changes (same as `m`). No parameters required.

**Documentation:**

- **Generate Documentation**: Generate comprehensive documentation for code modules and functions
- **Add Comments**: Add inline comments and docstrings to improve code readability
- **Explain Code**: Provide detailed code explanation with logic flow and purpose

**Dev Tools Integration:**

- **Generate Handoff Prompt**: Generate handoff prompt using dev tools. Usage: provide task description, work completed, and next steps
- **Generate All Outputs**: Generate complete project outputs (snapshot + handoff + PR description). Usage: provide task description and context
- **Quick Commit and Push**: Quick commit and push with timestamp. Usage: provide commit message (emoji will be added automatically)
- **Test All Dev Tools**: Test all dev tools functions to ensure they work properly. No parameters required.
- **Show Environment Info**: Show current environment detection, AGOR version, and platform information. No parameters required.
- **Provide AGOR Feedback**: Generate AGOR feedback for continuous improvement. Usage: provide current project name, issues encountered, suggested improvements, workflow friction points, and positive experiences. Submit feedback via <https://github.com/jeremiah-k/agor-meta/issues/new>.
- **Initiate Session End Procedure**: MANDATORY session end prompt for agent coordination. Usage: provide work completed, current status, next agent instructions, critical context, and files modified. MUST be called before ending any session to ensure proper coordination.

**CRITICAL OUTPUT FORMATTING REQUIREMENTS**:

**MANDATORY FOR ALL GENERATED CONTENT**: PR descriptions, handoff prompts, release notes, meta feedback, session summaries, etc. MUST use the proper dev tools functions:

**CORRECT WORKFLOW - USE THESE FUNCTIONS**:

**For External Projects (Augment Local Agents, etc.)**:

```python
# ALWAYS use external integration for projects where AGOR is installed separately
from agor.tools.external_integration import get_agor_tools
tools = get_agor_tools()

# For release notes (KEEP BRIEF - long content causes processing errors)
formatted_output = tools.generate_release_notes_output(brief_release_notes_content)
print(formatted_output)

# For PR descriptions (KEEP BRIEF - long content causes processing errors)
formatted_output = tools.generate_pr_description_output(brief_pr_content)
print(formatted_output)

# For handoff prompts (can be full length)
formatted_output = tools.generate_handoff_prompt_output(handoff_content)
print(formatted_output)
```

**For AGOR Development Projects Only**:

```python
# Only use direct imports when working ON AGOR itself
from agor.tools.dev_tools import generate_release_notes_output
formatted_output = generate_release_notes_output(brief_release_notes_content)
print(formatted_output)

# For PR descriptions (KEEP BRIEF - long content causes processing errors)
from agor.tools.dev_tools import generate_pr_description_output
formatted_output = generate_pr_description_output(brief_pr_content)
print(formatted_output)

# For handoff prompts (can be full length)
from agor.tools.dev_tools import generate_handoff_prompt_output
formatted_output = generate_handoff_prompt_output(handoff_content)
print(formatted_output)
```

**NEVER**: Manually use detick_content() and manual wrapping
**ALWAYS**: Use the proper dev tools output functions above
**PURPOSE**: Ensures consistent, automatic formatting for seamless copy-paste workflow

**HANDOFF PROMPT FORMATTING - ABSOLUTELY MANDATORY**:
Every session MUST end with a handoff prompt that is:

1. **Generated using dev tools functions**
2. **Processed through detick_content() to remove triple backticks**
3. **Wrapped in a single codeblock with triple backticks**
4. **Ready for immediate copy-paste by user**

**COMPREHENSIVE CONTEXT CAPTURE - CRITICAL REQUIREMENT**:
All snapshots and handoff prompts MUST capture comprehensive user context:

1. **Like a transcriptionist** - Capture the full essence of user reasoning, ideally word-for-word
2. **Complete decision-making process** - Include ALL user explanations and strategic thinking
3. **User philosophy and priorities** - Their long-term vision, emphasis, and direction
4. **Technical rationale** - Full reasoning behind every architectural and implementation choice
5. **Strategic context** - How current work fits into larger goals and user preferences

**Example of GOOD context capture:**
"User emphasized that multi-agent coordination strategies are largely untested and need more work, preferring to focus on the snapshot/memory branch system and dev tools as the more developed features. They want users to understand these mature features and how to use them effectively. The user specifically noted that agents should never manually interact with snapshots - all memory management must be done using dev tools."

**Example of POOR context capture:**
"Updated some files and made improvements."

**MEMORY BRANCH UNDERSTANDING**: When dev tools says, "snapshot committed to memory branch X", that's where it went. Don't expect .agor files on your working branch - they're in .gitignore intentionally.

Always create a snapshot before ending your session using the dev tools.

**WORKER AGENT COORDINATION ACTIONS:**
**Coordination:**

- **Check Coordination Status**: Check coordination files (via Memory Synchronization System), agent memory files, and recent activity in agentconvo.md
- **Synchronize with Main**: Pull latest changes from main branch and update coordination status (Memory Synchronization System handles memory branch updates)
- **Create Checkpoint**: Create checkpoint in agent memory with current progress and status. Usage: provide checkpoint description (Memory Synchronization System will persist this)

**Communication:**

- **Update Agent Log**: Update agent memory log with progress, decisions, and current status. Usage: provide log entry content (Memory Synchronization System will persist this)
- **Post Message to AgentConvo**: Post message to agentconvo.md for cross-agent communication. Usage: provide message content (Memory Synchronization System will persist this)
- **Report Status**: Generate comprehensive status report including completed work, current tasks, and next steps

**Task Management:**

- **Receive Task Assignment**: Receive and acknowledge task assignment from coordinator (often as a work snapshot). Usage: task will be provided by coordinator
- **Mark Task Complete**: Mark current task as complete and update all coordination files (Memory Synchronization System will persist this). Usage: provide completion summary
- **Create Snapshot Document**: Prepare snapshot document for next agent (or for archival) with comprehensive context and status (Memory Synchronization System will persist this)
- **Create Progress Report Snapshot**: Create progress report snapshot for status updates to coordinators or team members
- **Create Work Order Snapshot**: Create work order snapshot for task assignment (Project Coordinator role)
- **Generate PR Description**: Generate PR description for current work with comprehensive context (user will create the actual PR)
- **Receive Snapshot**: Receive and acknowledge snapshot from another agent or coordinator

**Meta-Development:**

- **Provide AGOR Feedback (In-Task)**: Provide feedback on AGOR itself (report issues, suggestions, or exceptional workflows)

**System:**

- **Continue Operation**: Continue previous operation
- **Refresh Context/Retry**: Refresh context or retry last action
- **Work Autonomously**: Work autonomously on the current task
- **Display Capabilities Menu**: Display this menu and available capabilities

### 3.2. Agent Coordination System

**Note**: Agent coordination uses **work snapshots** (which can serve as work orders) and **completion reports**. These are persisted and shared via the **Memory Synchronization System** using markdown files in the `.agor/` directory on dedicated memory branches.
**Purpose**: Structured coordinator-agent communication and work state capture.
**Location**: `.agor/snapshots/` directory on memory branches.
**Format**: Structured markdown with git context, progress, and next steps

```bash
# Check for snapshot documents (on a memory branch, accessed safely)
# Example: git show origin/agor/mem/YOUR_SESSION_BRANCH:.agor/snapshots/
# cat .agor/snapshots/index.md # If an index exists (on memory branch)

# Read a specific snapshot (work order example, accessed safely)
# Example: git show origin/agor/mem/YOUR_SESSION_BRANCH:.agor/snapshots/2024-01-15_143022_fix-authentication-bug_snapshot.md
```

**Work Snapshot & Completion Report Workflow**
**CRITICAL**: Agent coordination can be a two-way process using snapshots, managed by the Memory Synchronization System:
**📤 Work Assignment (Coordinator → Agent via Snapshot)**

1. **Creating Work Snapshots**: Coordinator initiates the snapshot creation process to generate a snapshot detailing the work. The Memory Synchronization System persists this to a memory branch.
2. **Agent Receipt**: Agent initiates the snapshot reception process to accept the work snapshot. The system retrieves it from the appropriate memory branch.
3. **Communication**: Update `.agor/agentconvo.md` (on the memory branch via the sync system) to confirm snapshot receipt.
4. **Work Execution**: Follow next steps outlined in the work snapshot.

**📥 Task Completion (Agent → Coordinator via Snapshot)**

1. **Completion Snapshot/Report**: Agent initiates the task completion process (which may generate a snapshot or report). This is persisted by the Memory Synchronization System.
2. **Results Summary**: Include work completed, commits, issues, recommendations
3. **Coordinator Review**: Coordinator reviews results (retrieved from memory branch) and provides feedback
4. **Integration**: Coordinator decides on integration and next steps

**Communication Protocol**

- **All coordination logged in**: `.agor/agentconvo.md` (managed on memory branches by the Memory Synchronization System)
- **Work order**: `[COORDINATOR-ID] [timestamp] - WORK ORDER: description`
- **Order receipt**: `[AGENT-ID] [timestamp] - ORDER RECEIVED: description`
- **Task completion**: `[AGENT-ID] [timestamp] - TASK COMPLETED: description`
- **Report review**: `[COORDINATOR-ID] [timestamp] - REPORT REVIEWED: status`

### 3.3. Core Workflow Protocol

**REPOSITORY OPERATIONS:**

1. **ALWAYS use the full git binary path in Bundle Mode**: `/tmp/agor_tools/git ls-files` (standard for Bundle Mode), `/tmp/agor_tools/git grep`, etc. for operations on the _working_ project branch. In Development/Standalone modes, use your system `git`.
2. **Execute real commands**: Do not simulate. The git binary (bundled or system) is functional and must be used.
3. Display complete files when investigating code
4. Edit by targeting specific line ranges, keep code cells short (1-2 lines)
5. Verify all changes with `/tmp/agor_tools/git diff` before committing to the _working_ project branch.
6. Your operational memory (decisions, progress) is primarily managed by the **Memory Synchronization System** in `.agor/` on dedicated _memory branches_. Avoid committing `.agor/` files directly to the main project or working branches unless specifically instructed for advanced development tasks.

**GIT COMMAND EXAMPLES (on working project branch):**

```bash
# Map codebase - EXECUTE THESE FOR REAL
# (Examples below assume Bundle Mode paths; adapt for other modes by using system git)
/tmp/agor_tools/git ls-files
/tmp/agor_tools/git ls-files '*.py'
/tmp/agor_tools/git grep "function_name"
/tmp/agor_tools/git status
/tmp/agor_tools/git diff
```

**OUTPUT FORMATS:**

- **`f`**: Complete files with all formatting preserved
- **`co`**: Only changed sections with before/after context
- **`da`**: Detailed analysis in single codeblock for agent snapshot

### 3.4. Multi-Agent Coordination Protocol

**AGENT MEMORY & COMMUNICATION SYSTEM:**
All agents use the `.agor/` directory for coordination. This directory and its contents are managed by the **AGOR Memory Synchronization System** on dedicated memory branches (e.g., `agor/mem/BRANCH_NAME`).

```
.agor/ (on a memory branch)
├── agentconvo.md          # Shared communication log
├── memory.md              # Project-level decisions (can be general or strategy-specific)
├── agent1-memory.md       # Agent 1 private notes
├── agent2-memory.md       # Agent 2 private notes
├── agent{N}-memory.md     # Agent N private notes (as needed)
└── strategy-active.md     # Current strategy details
```

**AGENT COMMUNICATION PROTOCOL (Managed via Memory Synchronization System):**

1. **Read First**: Always check `agentconvo.md` and your `agent{N}-memory.md` (retrieved via the Memory Synchronization System) before starting.
2. **Communicate**: Post status, questions, and findings to `agentconvo.md`.
3. **Document**: Update your private memory file with decisions and progress.
4. **Sync Often**: The Memory Synchronization System handles updates. Your working branch should `git pull origin main` (or the relevant project branch) frequently.
5. **Coordinate**: Check other agents' memory files (via safe access to memory branches if needed, or through system-provided summaries) to avoid conflicts.

**AGENTCONVO.MD FORMAT (on memory branch):**

```
[AGENT-ID] [TIMESTAMP] [STATUS/QUESTION/FINDING]

Agent1: 2024-01-15 14:30 - Starting feature extraction from feature-branch
Agent2: 2024-01-15 14:35 - Found core implementation in utils.py
Agent3: 2024-01-15 14:40 - Question: Should we preserve existing API interface?
Agent1: 2024-01-15 14:45 - Completed initial extraction, found 3 key functions
```

**AGENT MEMORY FORMAT (agent{N}-memory.md on memory branch):**

```markdown
# Agent{N} Memory Log

## Current Task

[What you're working on]

## Decisions Made

- [Key architectural choices]
- [Implementation approaches]

## Files Modified (on working project branch)

- [List of changed files with brief description]

## Problems Encountered

- [Issues hit and how resolved]

## Next Steps

- [What needs to be done next]

## Notes for Review

- [Important points for peer review phase]
```

### 3.5. Development Strategies

AGOR supports 5 multi-agent development strategies. The Memory Synchronization System will manage the persistence of strategy-specific files (like `strategy-active.md`, `agent{N}-memory.md`, task queues) on memory branches.

**📋 COMPREHENSIVE PROTOCOLS**: See `docs/multi-agent-protocols.md` for complete implementation protocols, session management, and coordination requirements.

🔄 **Parallel Divergent**: Multiple agents work independently, then peer review
⚡ **Pipeline**: Sequential work via snapshots with specialization
🐝 **Swarm**: Dynamic task assignment from shared queue (tasks can be snapshots)
⚔️ **Red Team**: Adversarial build/break cycles (states captured as snapshots)
👥 **Mob Programming**: Collaborative coding with rotating roles

Use the 'Select Development Strategy' function to analyze your project and get strategy recommendations.

**STRATEGY PARAMETER EFFECTS:**
(Content remains the same)

**Generated .agor/ Files by Strategy (on memory branches):**
**Note: The creation of these strategy-specific files should only occur _after_ a role has been selected by the user and a specific strategy is being explicitly initialized. These files are managed by the Memory Synchronization System on dedicated memory branches.**

- **Parallel Divergent**: strategy-active.md + agent{N}-memory.md files
- **Red Team**: strategy-active.md + blue-team-memory.md + red-team-memory.md
- **Mob Programming**: strategy-active.md + mob-session-log.md + mob-decisions.md
- **Team Creation**: team-structure.md + role-assignments.md + coordination-protocols.md
- **Quality Gates**: quality-gates.md + quality-metrics.md + gate-{name}.md files

### 3.6. Snapshot Procedures

(Content remains largely the same, emphasizing that snapshots are stored and managed by the Memory Synchronization System)
(For a quick summary of snapshot guidelines, call `get_snapshot_guidelines_summary()` from `dev_tools.py`)

You can get a quick reminder of snapshot best practices by calling:

```python
# Make sure your environment is set up to import AGOR tools
# (e.g., sys.path.insert(0, 'src') if running from AGOR root)
from agor.tools.dev_tools import get_snapshot_guidelines_summary
get_snapshot_guidelines_summary() # This will print the summary
```

...
**Creating a Snapshot**
... 3. **AGOR generates**:

- Complete snapshot document in `.agor/snapshots/` (on a memory branch via Memory Synchronization System)
- Snapshot prompt for the receiving agent (if applicable)
- Updates to coordination logs (on a memory branch via Memory Synchronization System)
  ...

### 3.7. Memory Persistence & Best Practices

**Memory Persistence (Primary Method: Memory Synchronization System):**

- AGOR's **Memory Synchronization System** is the primary and recommended method for persisting agent memory and coordination data.
- This system automatically manages the `.agor/` directory contents (including `memory.md`, `agentconvo.md`, individual agent memories, snapshots, and strategy-specific files) on dedicated Git branches (e.g., `agor/mem/BRANCH_NAME`).
- **Benefits**:
  - Keeps the main project/working branches clean of AGOR's operational state.
  - Provides version control for memory and coordination history.
  - Allows for graceful fallbacks if synchronization fails (agents can continue with local state).
  - Simplifies agent workflows by automating memory persistence.
- Agents should rely on this automated system. Direct commits of `.agor/` contents to _working_ or _main_ project branches for memory persistence are discouraged for standard agent operations.

**Best Practices:**
**General Development:**

- Work autonomously, try multiple approaches before asking for input
- Use short code cells (1-2 lines), verify with `/tmp/agor_tools/git diff` on your _working_ branch
- Always show capabilities menu at end of replies
- Your operational memory (decisions, progress) is managed by the Memory Synchronization System.
- **Provide feedback on AGOR**: Use the 'Provide AGOR Feedback' function to report issues, suggestions, or exceptional workflows

**Shared File Access (CRITICAL for Multi-Agent Coordination - Managed by Memory Synchronization System):**
The Memory Synchronization System is designed to handle concurrent access to coordination files on memory branches. However, agents should still follow logical best practices:

- **APPEND-ONLY for logs**: When directly contributing to logs like `agentconvo.md` or agent memory files (which the system then syncs), use an append pattern.
- **PULL BEFORE WRITE (for working branches)**: Always pull latest changes on your _working project branch_ before making code modifications. The Memory Synchronization System handles sync for memory branches.
- **Clear communication**: Use structured formats for `agentconvo.md` entries with agent ID and timestamp.

**File Access Patterns (for working project branch):**

```bash
# CORRECT: Pull before modifying shared files on working branch
# (Example below assumes Bundle Mode path; adapt for other modes by using system git)
/tmp/agor_tools/git pull origin main
# ... make code changes to project files ...
```

Memory files in `.agor/` are handled by the Memory Synchronization System.

---

## 4. AGOR Tools and Capabilities

(Section remains the same)

---

## 5. AGOR System and Meta Information

(Section remains largely the same, minor adjustments if needed for consistency)

### 5.1. Bundle Contents

(No changes needed)

### 5.2. Deployment Modes

(No changes needed)

### 5.3. AGOR Architecture Overview

(No changes needed)

### 5.4. Meta-Development Feedback

(No changes needed)

### 5.5. Documentation Index and Further Reading

(No changes needed)

### 5.6. Attribution

(No changes needed)

---

## 6. Advanced Features & Memory Systems

### 6.1. Memory Synchronization System (Production Ready)

(To display a summary of the memory architecture, call `display_memory_architecture_info()` from `dev_tools.py`)

You can get a quick reminder of memory architecture by calling:

```python
# Make sure your environment is set up to import AGOR tools
# (e.g., sys.path.insert(0, 'src') if running from AGOR root)
from agor.tools.dev_tools import display_memory_architecture_info
display_memory_architecture_info() # This will print the info
```

**AGOR's primary and recommended method for agent memory persistence is the automated Memory Synchronization System.** This system seamlessly integrates with agent workflows, providing robust and reliable memory management using markdown files stored in the `.agor/` directory on dedicated Git memory branches (e.g., `agor/mem/BRANCH_NAME`).

**Key Features & Agent Impact:**

- **Automated Persistence:** Memory sync is **automatically initialized** when you start work (e.g., joining a project, initializing coordination) and **automatically saved** when you complete tasks or sessions. Agents generally do **not** need to manually trigger memory saving or loading.
- **Dedicated Memory Branches:** All `.agor/` contents (your notes, `agentconvo.md`, snapshots, strategy files) are committed to these special branches, not your working project branch. This keeps your project's main history clean.
- **Version Controlled Memory:** Your memory, notes, and coordination state are version controlled, allowing for history, auditing, and easier recovery.
- **Graceful Fallback:** The system is designed to be non-disruptive. If a sync operation fails, your workflow can continue with locally cached memory, and the system will attempt to sync later.
- **`.gitignore` Interaction Note:** Project repositories might have `.agor/` in their `.gitignore` file. This is to prevent accidental commits of local AGOR operational states to the _working_ or _main_ branches of the project. The Memory Synchronization System is designed to work with this; it specifically manages and commits the `.agor/` directory to its dedicated _memory branches_, bypassing the project's main `.gitignore` for those branches.

#### Automatic Memory Sync Integration

(Content is largely the same as original, reinforcing automation)
**Memory sync is automatically initialized** when:

- Agents join projects (`discover_current_situation`)
- Coordination systems are initialized (`agor init`, `agor pd`, etc.)
- Strategy managers are created

**Memory sync is automatically saved** when:

- Agents complete work (`complete_agent_work`)
- Agent sessions end (where applicable by the environment)
- Critical memory state needs to be checkpointed by the system.

#### Memory Sync Status in Agent Commands

The `agor status` command (and similar status reporting) will include information about the Memory Synchronization System, such as the active memory branch and sync health, if relevant to the agent's current context or for diagnostic purposes.

#### Manual Memory Sync Operations (Primarily for AGOR Development & Advanced Use)

While the Memory Synchronization System is designed to be automatic for standard agent operations, the following operations exist primarily for **AGOR developers or very advanced use cases** (e.g., manually forcing a sync after a network outage, or specific testing scenarios):

**Memory Sync Operations (Advanced/Developer Use):**

- **Manually Start Memory Sync**: Initialize or restart memory synchronization.
- **Manually Save Memory Sync**: Manually force a save of the current memory state to the memory branch.
- **Manually Restore Memory Sync**: Manually attempt to restore memory state from a specified memory branch.
- **Show Memory Sync Status**: Show detailed current memory synchronization status.

**Standard agents should rely on the system's automatic synchronization.**

#### Memory Branch Architecture

(Content is largely the same, reinforcing separation)
**Memory branches** are separate from working branches:

- **Memory branches**: Store `.agor/` content (memories, snapshots, coordination files).
- **Working branches**: Store project source code, documentation.
- **Clean separation**: Prevents AGOR's operational state from cluttering the project's source code history.

#### Error Handling

(Content is largely the same, reinforcing robustness)
Memory sync is designed to be **transparent and non-disruptive**:

- If memory sync fails, agent workflows can continue with locally cached state.
- Warning messages for sync issues, but no workflow interruption for the agent.

#### Summary for Standard Agent Operation:

- Your memory (notes, coordination files, snapshots) is automatically managed by the Memory Synchronization System.
- This system uses markdown files in the `.agor/` directory, stored on dedicated memory branches.
- You do not need to manually save or load your memory in most situations.
- Focus on your tasks; AGOR handles memory persistence in the background.
