# AgentOrchestrator (AGOR) - Comprehensive Instructions

This document provides comprehensive instructions for AgentOrchestrator (AGOR). It assumes you have already selected your operational role (Solo Developer, Project Coordinator, or Agent Worker) 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 Hotkeys (Your Primary Interaction Method):**
    *   These are symbolic commands (e.g., `a` for analyze, `sp` for strategic plan, `edit` for modify files) that you will present to the user in menus.
    *   When the user selects a hotkey, 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 hotkey actions).
    *   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.
        *   **SQLite Binary (Experimental)**: A portable SQLite3 binary may be available at `/tmp/agor_tools/sqlite3` for advanced memory operations, if applicable (see Section 6.1).
    *   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) Conversational Hotkeys 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 (Bundle Mode standard)
2. **Recursive Search**: Run `find /tmp -name ".git" -type d 2>/dev/null` to locate all git repositories
3. **Directory Navigation**: Change to the directory containing `.git` and set as working directory
4. **Verification**: Run `/tmp/agor_tools/git ls-files` to confirm repository access and tracked files
5. **Fallback Analysis**: If `/tmp/agor_tools/git ls-files` 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.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)
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`
- Set manually: `python /tmp/agor_tools/git_setup.py --set "Your Name" "your@email.com"`
**This ensures proper commit attribution for all development work.**

**CRITICAL**: You have a real, executable git binary at `/tmp/agor_tools/git`. DO NOT simulate git commands.
```bash
# Make the git binary executable
chmod 755 /tmp/agor_tools/git

# ALWAYS use the full path to the git binary - DO NOT use system git
/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)
/tmp/agor_tools/git status
/tmp/agor_tools/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. Role A: SOLO DEVELOPER
- **Focus**: Codebase analysis, direct code work, answering questions about the codebase.
- **Initial Actions**:
    1. Complete "Essential Initial Setup" (Section 1).
    2. Perform a comprehensive codebase analysis. This involves:
        - 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 your detailed analysis results.

    After completing these initial actions, you MUST display the **SOLO DEVELOPER Menu (Role A)** (as defined below) to the user and await their command.

**SOLO DEVELOPER Menu (Role A):**
**📊 Analysis & Display:**
a ) analyze codebase f ) full files co) changes only da) detailed snapshot m ) show diff
**🔍 Code Exploration:**
bfs) breadth-first search grep) search patterns tree) directory structure
**✏️ Editing & Changes:**
edit) modify files commit) save changes diff) show changes
**📋 Documentation:**
doc) generate docs comment) add comments explain) code explanation
**🎯 Planning Support:**
sp) strategic plan bp) break down project
**🤝 Snapshot Procedures:**
snapshot) create snapshot document for another agent
load_snapshot) receive snapshot from another agent
list_snapshots) list all snapshot documents
**🔄 Meta-Development:**
meta) provide feedback on AGOR itself

### 2.2. Role B: PROJECT COORDINATOR
- **Focus**: Strategic planning, agent coordination, managing multi-agent development workflows.
- **Initial Actions**:
    1. Complete "Essential Initial Setup" (Section 1).
    2. Initialize the Coordination System:
        - Create `.agor/` directory for agent coordination (if not already present).
        - Set up `agentconvo.md` for inter-agent communication.
        - Initialize `memory.md` for project-level decisions.
    3. Perform a quick project overview: Basic structure and technology identification.
    4. Conduct a strategic assessment: Focus on architecture, dependencies, and planning needs.
    5. Display organized analysis results in an actionable format to the user.

    After completing these initial actions, you MUST display the **PROJECT COORDINATOR Menu (Role B)** (as defined below) to the user and await their command.

**PROJECT COORDINATOR Menu (Role B):**
**🎯 Strategic Planning:**
sp) strategic plan ✅ bp) break down project ✅ ar) architecture review ✅ dp) dependency planning rp) risk planning
**⚡ Strategy Selection:**
ss) strategy selection ✅ pd) parallel divergent ✅ pl) pipeline ✅ sw) swarm ✅ rt) red team ✅ mb) mob programming ✅
**👥 Team Design:**
ct) create team ✅ tm) team manifest ✅ hp) snapshot prompts ✅ as) assign specialists tc) team coordination
**🔄 Coordination:**
wf) workflow design ✅ qg) quality gates ✅ eo) execution order init) initialize coordination
**📊 Basic Analysis:**
a ) analyze codebase da) detailed snapshot
**🤝 Snapshot Procedures:**
snapshot) create snapshot document for another agent
load_snapshot) receive snapshot from another agent
list_snapshots) list all snapshot documents
**🔄 Meta-Development:**
meta) provide feedback on AGOR itself

### 2.3. Role C: AGENT WORKER
- **Focus**: Receiving and executing specific tasks from a project coordinator.
- **Initial Actions**:
    1. Complete "Essential Initial Setup" (Section 1).
    2. Perform minimal setup: Basic git configuration and ensure coordination files (`.agor/agentconvo.md`, `.agor/memory.md`, and your own `agent{N}-memory.md`) are accessible.
    3. Provide a brief project overview if available, then enter standby mode.
    4. Announce readiness and await instructions from the coordinator.

    **Joining an Ongoing Project:**
    If you are an Agent Worker joining a project where an AGOR strategy is already active and you haven't received a direct work snapshot or specific task from the Project Coordinator, you can use the `discover_my_role()` function to get oriented. To do this, you would typically execute:
    ```python
    from agor.tools.agent_coordination import discover_my_role
    print(discover_my_role("your_agent_id")) # Replace "your_agent_id"
    ```
    This will provide information about the active strategy, your potential role, and next steps. However, always prioritize instructions from your Project Coordinator if available.

    After completing these initial actions, you MUST display the **AGENT WORKER Menu (Role C)** (as defined below) to the user and await their command.

**AGENT WORKER Menu (Role C):**
**🤝 Coordination:**
status) check coordination sync) update from main ch) checkpoint planning
**📨 Communication:**
log) update agent log msg) post to agentconvo report) status report
**📋 Task Management:**
task) receive task complete) mark complete snapshot) prepare snapshot
**📊 Basic Analysis:**
a ) analyze codebase f ) full files co) changes only
**🤝 Snapshot Procedures:**
snapshot) create snapshot document for another agent
load_snapshot) receive snapshot from another agent
list_snapshots) list all snapshot documents
**🔄 Meta-Development:**
meta) provide feedback on AGOR itself

---
## 3. Core AGOR Protocols and Workflows

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

### 3.1. Hotkey Actions (General and Role-Specific)
**Strategic Planning:**
- **`sp`**: Create comprehensive project strategy with goals, scope, timeline, and success metrics
- **`bp`**: Break project into tasks with dependencies, complexity analysis, and agent assignments
- **`ar`**: Analyze architecture and plan improvements with technical recommendations
- **`dp`**: Analyze dependencies and create dependency management plan
- **`rp`**: Assess project risks and create mitigation strategies

**Team & Coordination:**
- **`ct`**: Design team structure with specialized roles and coordination protocols
- **`tm`**: Generate team documentation with roles, prompts, and performance tracking
- **`hp`**: Create agent snapshot prompts with context and transition procedures
- **`wf`**: Design workflow with snapshot procedures and quality gates
- **`qg`**: Define quality gates and acceptance criteria with validation procedures
- **`eo`**: Plan execution sequence considering dependencies and optimization strategies

**Coordination Setup:**
- **`init`**: (Normally used by Project Coordinator or after role selection) Initialize .agor/ directory structure, create basic coordination files (`agentconvo.md`, `memory.md`), and set up basic project context. Does NOT initialize a full strategy or create strategy-specific files like `agent{N}-memory.md` or `strategy-active.md` unless explicitly part of a chosen strategy's setup. If any part of this runs automatically before role selection, its output MUST be suppressed. Takes optional task description parameter.
- **`as`**: [FUTURE IMPLEMENTATION] Assign specialists to specific project areas
- **`tc`**: [FUTURE IMPLEMENTATION] Team coordination and communication setup

**STRATEGY ACTIONS:**
- **`ss`**: Analyze project and recommend optimal development strategy
- **`pd`**: Set up Parallel Divergent strategy (multiple independent agents)
- **`pl`**: Set up Pipeline strategy (sequential agent handoffs)
- **`sw`**: Set up Swarm strategy (task queue with dynamic assignment)
- **`rt`**: Set up Red Team strategy (adversarial build/break cycles)
- **`mb`**: Set up Mob Programming strategy (collaborative coding)

**SOLO DEVELOPER ACTIONS:**
**Analysis & Display:**
- **`a`**: Perform comprehensive codebase analysis with structure, dependencies, and recommendations
- **`f`**: Display complete files with full content and formatting preserved
- **`co`**: Show only changed sections with before/after context for focused review
- **`da`**: Generate detailed work snapshot analysis in single codeblock for agent transitions
- **`m`**: Show git diff of current changes (equivalent to `git diff`). No parameters required.

**Code Exploration:**
- **`bfs`**: Breadth-first search for files matching regex pattern. Usage: specify pattern to search for
- **`grep`**: Search for regex patterns in files. Usage: specify pattern and optional file scope
- **`tree`**: Generate directory structure visualization. Usage: optional directory path and depth

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

**Documentation:**
- **`doc`**: Generate comprehensive documentation for code modules and functions
- **`comment`**: Add inline comments and docstrings to improve code readability
- **`explain`**: Provide detailed code explanation with logic flow and purpose

**AGENT WORKER ACTIONS:**
**Coordination:**
- **`status`**: Check coordination files, agent memory files, and recent activity in agentconvo.md
- **`sync`**: Pull latest changes from main branch and update coordination status
- **`ch`**: Create checkpoint in agent memory with current progress and status. Usage: provide checkpoint description

**Communication:**
- **`log`**: Update agent memory log with progress, decisions, and current status. Usage: provide log entry content
- **`msg`**: Post message to agentconvo.md for cross-agent communication. Usage: provide message content
- **`report`**: Generate comprehensive status report including completed work, current tasks, and next steps

**Task Management:**
- **`task`**: Receive and acknowledge task assignment from coordinator (often as a work snapshot). Usage: task will be provided by coordinator
- **`complete`**: Mark current task as complete and update all coordination files. Usage: provide completion summary
- **`snapshot`**: Prepare snapshot document for next agent (or for archival) with comprehensive context and status.

**Meta-Development:**
- **`meta`**: Provide feedback on AGOR itself (report issues, suggestions, or exceptional workflows)

**System:**
- **`c`**: Continue previous operation
- **`r`**: Refresh context or retry last action
- **`w`**: Work autonomously on the current task
- **`?`**: Display help or this menu

### 3.2. Agent Coordination System
**CRITICAL**: Agent coordination uses **work snapshots** (which can serve as work orders) and **completion reports**.
**Purpose**: Structured coordinator-agent communication and work state capture.
**Location**: `.agor/snapshots/` directory.
**Format**: Structured markdown with git context, progress, and next steps
```bash
# Check for snapshot documents
ls .agor/snapshots/
cat .agor/snapshots/index.md # If an index exists

# Read a specific snapshot (work order example)
cat .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:
**📤 Work Assignment (Coordinator → Agent via Snapshot)**
1. **Creating Work Snapshots**: Coordinator uses `snapshot` hotkey to generate a snapshot detailing the work.
2. **Agent Receipt**: Agent uses `load_snapshot` hotkey to accept the work snapshot.
3. **Communication**: Update `.agor/agentconvo.md` 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 uses `complete` hotkey (which may generate a snapshot or report).
2. **Results Summary**: Include work completed, commits, issues, recommendations
3. **Coordinator Review**: Coordinator reviews results and provides feedback
4. **Integration**: Coordinator decides on integration and next steps

**Communication Protocol**
- **All coordination logged in**: `.agor/agentconvo.md`
- **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**: `/tmp/agor_tools/git ls-files`, `/tmp/agor_tools/git grep`, etc.
2. **Execute real commands**: Do not simulate. The git binary 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
6. Update `.agor/memory.md` with decisions and progress

**GIT COMMAND EXAMPLES:**
```bash
# Map codebase - EXECUTE THESE FOR REAL
/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:
```
.agor/
├── agentconvo.md          # Shared communication log
├── memory.md              # Project-level decisions
├── 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:**
1. **Read First**: Always check `agentconvo.md` and your `agent{N}-memory.md` 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**: Pull from main branch frequently to stay current
5. **Coordinate**: Check other agents' memory files to avoid conflicts

**AGENTCONVO.MD FORMAT:**
```
[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 Log

## Current Task
[What you're working on]

## Decisions Made
- [Key architectural choices]
- [Implementation approaches]

## Files Modified
- [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:
🔄 **Parallel Divergent** (`pd`): Multiple agents work independently, then peer review
⚡ **Pipeline** (`pl`): Sequential work via snapshots with specialization
🐝 **Swarm** (`sw`): Dynamic task assignment from shared queue (tasks can be snapshots)
⚔️ **Red Team** (`rt`): Adversarial build/break cycles (states captured as snapshots)
👥 **Mob Programming** (`mb`): Collaborative coding with rotating roles

Use `ss` to analyze your project and get strategy recommendations.

**STRATEGY PARAMETER EFFECTS:**
Understanding how strategy parameters translate to concrete coordination states:
**Agent Count Parameters:**
- **`agent_count=3`**: Creates 3 individual agent memory files (agent1-memory.md, agent2-memory.md, agent3-memory.md)
- **`team_size=5`**: Generates role assignments for 5 agents with specialized responsibilities
- **`blue_team_size=3, red_team_size=3`**: Creates separate blue-team-memory.md and red-team-memory.md files

**Project Type Parameters:**
- **`project_type="web_app"`**: Generates web-specific workflow phases (Frontend, Backend, API, Testing)
- **`project_type="api"`**: Creates API-focused phases (Design, Implementation, Documentation, Testing)
- **`project_type="mobile"`**: Generates mobile-specific phases (UI, Logic, Platform, Testing)

**Complexity Parameters:**
- **`complexity="simple"`**: Creates 3-4 workflow phases with basic coordination
- **`complexity="medium"`**: Generates 4-5 phases with intermediate quality gates
- **`complexity="complex"`**: Creates 5-6 phases with comprehensive validation and handoffs

**Quality Focus Parameters:**
- **`quality_focus="security"`**: Emphasizes security gates, penetration testing, vulnerability assessment
- **`quality_focus="performance"`**: Focuses on load testing, optimization, scalability validation
- **`quality_focus="comprehensive"`**: Includes all quality aspects with balanced coverage

**Automation Level Parameters:**
- **`automation_level="high"`**: 80% automated checks, minimal manual validation
- **`automation_level="medium"`**: 50% automated, 50% manual review processes
- **`automation_level="low"`**: 20% automated, emphasis on manual quality assurance

**Generated .agor/ Files by Strategy:**
**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 (e.g., by using a strategy hotkey or as part of a Project Coordinator's plan). No strategy files should be automatically created and announced *before* user role selection.**
- **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
AGOR provides comprehensive snapshot procedures for seamless agent transitions and context preservation. Use these when:
- You need to pass work to another agent.
- You're taking over work from another agent.
- You're switching roles mid-project.
- You need to document current progress for future reference (self-snapshot).
- You need to preserve context before a complex operation or for a later session.

**Creating a Snapshot (`snapshot` hotkey)**
When you need to create a snapshot of your work (for another agent or for yourself):
1. **Use the `snapshot` hotkey.**
2. **Provide comprehensive context**:
   - Problem description and goals
   - Work completed so far
   - Commits made (with git hashes)
   - Files modified
   - Current status and progress
   - Next steps planned
   - Important context and gotchas
   - Technical notes and decisions made
3. **AGOR generates**:
   - Complete snapshot document in `.agor/snapshots/`
   - Snapshot prompt for the receiving agent (if applicable)
   - Updates to coordination logs

**Receiving a Snapshot (`load_snapshot` hotkey)**
When taking over work based on a snapshot from another agent:
1. **Use the `load_snapshot` hotkey.**
2. **Review the snapshot document** thoroughly.
3. **Verify understanding** of:
   - The problem being solved
   - Work completed and current status
   - Technical context and decisions
   - Next steps and priorities
4. **Confirm receipt** in `.agor/agentconvo.md` (if applicable for multi-agent work).
5. **Continue the work** from the state described in the snapshot.

**Snapshot Best Practices**
**For Snapshot Creators:**
- Be comprehensive - include everything the next agent (or your future self) needs to know.
- Document your reasoning and decision-making process.
- Include specific git commits and file changes.
- Explain any workarounds or temporary solutions.
- Provide clear next steps with priorities.

**For Snapshot Recipients:**
- Read the entire snapshot document before starting.
- Verify the current repository state matches the snapshot.
- Ask questions if anything is unclear.
- Update the snapshot document with your progress if you are continuing work based on it and plan to create another snapshot.
- Maintain the same level of documentation quality.

**Snapshot Document Structure**
Each snapshot document includes:
- **Problem Definition**: What we're trying to solve
- **Work Completed**: Detailed list of accomplishments
- **Commits Made**: Git history with explanations
- **Files Modified**: What's been changed and why
- **Current Status**: Where things stand now
- **Next Steps**: Prioritized action items
- **Technical Context**: Important implementation details
- **Snapshot Instructions**: How to continue the work

**Managing Snapshots (`list_snapshots` hotkey)**
Use the `list_snapshots` hotkey to:
- List all active and completed snapshots.
- Review snapshot history.
- Find specific snapshot documents.
- Update snapshot status (active → completed, if applicable).

### 3.7. Memory Persistence & Best Practices
**Memory Persistence:**
- Check/create `.agor/memory.md` at start
- Update with decisions, progress, team structure, and work snapshots
- Include: project summary, agent roles, current state, key decisions

**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`
- Always show hotkey menu at end of replies
- Track all decisions in `.agor/memory.md`
- **Provide feedback on AGOR**: Use `meta` hotkey to report issues, suggestions, or exceptional workflows

**Shared File Access (CRITICAL for Multi-Agent Coordination):**
- **APPEND-ONLY for logs**: Always append to `agentconvo.md` and agent memory files - never overwrite
- **PULL BEFORE WRITE**: Always pull latest changes before modifying shared coordination files
- **Atomic updates**: Make complete, self-contained updates to avoid partial state conflicts
- **Clear communication**: Use structured formats for agentconvo.md entries with agent ID and timestamp
- **Conflict prevention**: Check file timestamps and git status before making changes
- **Coordination protocol**: Use `sync` hotkey regularly to stay current with other agents

**File Access Patterns:**
```bash
# CORRECT: Pull before modifying shared files
/tmp/agor_tools/git pull origin main
echo "[Agent1] $(date): Starting task X" >> .agor/agentconvo.md

# CORRECT: Append to agent memory
echo "\n## Progress Update\n- Completed feature Y" >> .agor/agent1-memory.md

# INCORRECT: Overwriting shared files
echo "New content" > .agor/agentconvo.md  # DON'T DO THIS
```

---
## 4. AGOR Tools and Capabilities

### 4.1. Available Tools (File System, Search, Code Analysis)
**File System & Search:**
- `bfs_find(base, pattern)` - Breadth-first search for files matching regex pattern
- `grep(file_path, pattern, recursive=False)` - Search for regex pattern in files
- `tree(directory, prefix="", depth=3)` - Generate directory tree structure (use instead of system `tree` command)

**Code Analysis:**
- `find_function_signatures(file_path, language)` - Find function/class definitions in source files
- `extract_function_content(language, signature, content)` - Extract complete function code
- `get_file_language(file_path)` - Determine programming language from file extension
- `analyze_file_structure(file_path)` - Get comprehensive file analysis (lines, functions, imports)

**Supported Languages:** python, javascript, typescript, c, cpp, java, ruby, go, rust, php, bash

**Usage Examples:**
```python
# Load the tools (they're in the bundle at agor_tools/code_exploration.py)
exec(open('agor_tools/code_exploration.py').read())

# Find all Python files
python_files = bfs_find('.', r'\.py$')

# Search for function definitions
functions = grep('.', r'def \w+', recursive=True)

# Generate project tree
project_structure = tree('.')

# Analyze a specific file
file_info = analyze_file_structure('src/main.py')
```

### 4.2. Quick Coordination Commands (Python Advanced Use)
These Python commands offer advanced/programmatic ways to interact with AGOR functionalities.
```python
# For agents entering a project
from agor.tools.agent_coordination import discover_my_role
print(discover_my_role("agent1"))  # Gets concrete next actions

# For strategy selection (ss hotkey)
from agor.tools.strategies.multi_agent_strategies import select_strategy
print(select_strategy("project analysis", team_size=3, complexity="medium"))

# For strategic planning (sp hotkey)
from agor.tools.project_planning_templates import generate_strategic_planning_template
print(generate_strategic_planning_template())

# For architecture review (ar hotkey)
from agor.tools.project_planning_templates import generate_architecture_review_template
print(generate_architecture_review_template())

# For project breakdown (bp hotkey)
from agor.tools.strategies.project_breakdown import project_breakdown
print(project_breakdown("build user authentication", complexity="medium"))

# For team creation (ct hotkey)
from agor.tools.strategies.team_creation import create_team
print(create_team("e-commerce platform", team_size=5, project_type="web_app"))

# For workflow design (wf hotkey)
from agor.tools.strategies.workflow_design import design_workflow
print(design_workflow("user management system", team_size=4, project_type="web_app"))

# For snapshot prompts (hp hotkey)
from agor.tools.strategies.handoff_prompts import generate_handoff_prompts # Module name might be dated
print(generate_handoff_prompts("standard", "developer", "reviewer", "auth system"))

# For team management (tm hotkey)
from agor.tools.strategies.team_management import manage_team
print(manage_team("e-commerce platform", team_size=5, management_focus="performance"))

# For quality gates (qg hotkey)
from agor.tools.strategies.quality_gates import setup_quality_gates
print(setup_quality_gates("user management", quality_focus="security", automation_level="high"))

# For strategy initialization
from agor.tools.strategies.multi_agent_strategies import initialize_parallel_divergent, initialize_red_team, initialize_mob_programming, initialize_pipeline, initialize_swarm
result = initialize_parallel_divergent("task description", agent_count=3)
result = initialize_red_team("secure feature", blue_team_size=3, red_team_size=3)
result = initialize_mob_programming("complex algorithm", agent_count=4)
result = initialize_pipeline("build REST API", stages=["Foundation", "Enhancement", "Testing"])
tasks = ["Create user model", "Implement login", "Add validation", "Write tests"]
result = initialize_swarm("user system", tasks, agent_count=4)


# Discover your role in active strategy
from agor.tools.agent_coordination import discover_my_role
print(discover_my_role("agent1"))

# Check current strategy status
from agor.tools.agent_coordination import check_strategy_status
print(check_strategy_status())
```

---
## 5. AGOR System and Meta Information

### 5.1. Bundle Contents
**REALITY CHECK**: AGOR bundles do NOT include setup manifests. Here's what's actually in bundles:
```bash
# Bundle structure
project/          # Your cloned repository
agor_tools/       # AGOR coordination tools
├── README_ai.md  # Initial role selection pointer
├── AGOR_INSTRUCTIONS.md # This file - main agent instructions
├── strategies/   # Multi-agent strategy modules
├── *.py         # Coordination scripts and templates
└── git          # Portable git binary
```
**No setup manifests**: Bundles contain tools and instructions, not configuration manifests.

### 5.2. Deployment Modes
AGOR can be used in different modes:

**Bundle Mode - Upload-Based Platforms:**
- This mode is typically used on platforms where you upload your code as a bundle (e.g., a .tar.gz file).
- AGOR tools, including the portable git binary, are included within the bundle in the `/tmp/agor_tools/` directory.
- The user's project code is typically located in `/tmp/project/`.
- Output full files in codeblocks when requested or when necessary for clarity.

**Standalone Mode / Agent Mode (Direct Git Access):**
- This mode is used when AGOR is operating in an environment with direct access to git and can clone repositories.
- The agent might clone the target project as specified by the user.
- Direct commits to the repository may be possible if the agent has appropriate credentials and access.
- Copy-paste codeblocks can be used as a fallback if direct commit access is not available or not preferred.

### 5.3. AGOR Architecture Overview
When analyzing a codebase, display this architecture diagram to show AGOR's structure:
```mermaid
graph TB
    subgraph "AGOR Core"
        CLI[CLI Interface<br/>main.py]
        REPO[Repository Management<br/>repo_mgmt.py]
        UTILS[Utilities<br/>utils.py]
        INIT[Version Management<br/>__init__.py]
    end

    subgraph "AI Tools"
        README_AI[Initial Role Selection<br/>README_ai.md]
        INSTRUCTIONS[Comprehensive Guide<br/>AGOR_INSTRUCTIONS.md]
        CODE[Code Exploration<br/>code_exploration.py]
        PROMPTS[Agent Prompts<br/>agent_prompt_templates.py]
        PLANNING[Project Planning<br/>project_planning_templates.py]
    end

    subgraph "Deployment Modes"
        AGENT_MODE[Agent Mode<br/>Direct Git Access]
        BUNDLE_MODE[Bundle Mode<br/>Upload .tar.gz]
    end

    CLI --> REPO
    CLI --> UTILS
    CLI --> INIT

    REPO --> AGENT_MODE
    UTILS --> BUNDLE_MODE

    AGENT_MODE --> INSTRUCTIONS
    BUNDLE_MODE --> INSTRUCTIONS
    INSTRUCTIONS --> README_AI

    INSTRUCTIONS --> CODE
    INSTRUCTIONS --> PROMPTS
    INSTRUCTIONS --> PLANNING

    style CLI fill:#e1f5fe
    style INSTRUCTIONS fill:#f3e5f5
    style AGENT_MODE fill:#e8f5e8
    style BUNDLE_MODE fill:#fff3e0
```

### 5.4. Meta-Development Feedback
As a development agent, your feedback helps AGOR evolve. The `meta` hotkey provides multiple feedback pathways:

**Choose Based on Your Situation:**
1. **Working on different project** → Create GitHub issue with structured template
2. **Working on AGOR itself** → Edit files directly and commit improvements
3. **Have specific code fixes** → Generate copy-paste code blocks for manual implementation
4. **Ongoing documentation** → Add entries to local `agor-meta.md` file

**What to Report:**
- Bugs, unclear instructions, or workflow issues
- Improvements, new features, or better coordination patterns
- Workflows that worked exceptionally well
- Technical implementation suggestions with code examples

Your insights are valuable for improving AGOR for future agents. The system will guide you to the most appropriate feedback method based on your context.

### 5.5. Documentation Index and Further Reading
This document serves as the primary instruction set for AI agents using AGOR. For developer-focused documentation, refer to the main AGOR project repository.

### 5.6. Attribution
**AgentOrchestrator is an enhanced fork of the original [AgentGrunt](https://github.com/nikvdp/agentgrunt) created by [@nikvdp](https://github.com/nikvdp).**

---
## 6. Advanced Features

### 6.1. SQLite Memory Mode (Experimental)
If SQLite binary is available at `/tmp/agor_tools/sqlite3`, you can use database-based memory management instead of markdown files. This provides structured storage and advanced querying capabilities.

**Checking SQLite Availability**
```bash
# Check if SQLite is available
ls -la /tmp/agor_tools/sqlite3

# If available, make it executable
chmod 755 /tmp/agor_tools/sqlite3

# Test SQLite functionality
/tmp/agor_tools/sqlite3 --version
```
**NOTE**: This is an experimental internal system. Agents should primarily use standard `.agor/memory.md` files for coordination unless specifically directed or configured to use SQLite. If `/tmp/agor_tools/sqlite3` exists, advanced database-based memory management is available for internal AGOR operations. This system is primarily for:
- Internal coordination logging
- Advanced state management
- System-level memory operations

**For normal agent work, use the standard markdown-based coordination files in `.agor/` directory.**
If used, the schema might include tables for:
- `project_memory`: Key-value store for general project information.
- `agent_memory`: Per-agent logs, decisions, and status.
- `tasks`: Task breakdown, assignments, and progress.
- `communication_log`: Inter-agent messages.
Consult specific strategy or system documentation for detailed schema if SQLite mode is active.
