Learning Path: Agentic Orchestration System

This guide walks you through using the system hands-on, building artifacts progressively.

Phase 1: Initial Setup

Task 1.1: Verify AgentStore Structure

# Check if AgentStore exists
ls -la ~/Dropbox/AgentStore/

# If it doesn't exist, create the structure:
mkdir -p ~/Dropbox/AgentStore/{messaging/{inbox,outbox,processed_inbox,processed_outbox},users,projects,Queues,JSONValidation/Schemas,logs}

Task 1.2: Copy JSON Schemas

# Copy schemas from the project to AgentStore
cp ~/Dropbox/AgentStore/JSONValidation/Schemas/*.json ~/Dropbox/AgentStore/JSONValidation/Schemas/ 2>/dev/null || echo "Schemas may need to be created"

# Or create them using the system's built-in schemas (if available)
# Check what's already there:
ls -la ~/Dropbox/AgentStore/JSONValidation/Schemas/

Task 1.3: Create Global Configuration

# Copy example config
cp config.example.yaml ~/Dropbox/AgentStore/config.yaml

# Edit if needed (optional for now)
cat ~/Dropbox/AgentStore/config.yaml

Task 1.4: Create Your User File

Create ~/Dropbox/AgentStore/users/learner.json:

{
  "id": "learner",
  "slack_username": "learner",
  "name": "System Learner",
  "email": "learner@example.com",
  "permissions": "admin"
}

Command to create it:

cat > ~/Dropbox/AgentStore/users/learner.json << 'EOF'
{
  "id": "learner",
  "slack_username": "learner",
  "name": "System Learner",
  "email": "learner@example.com",
  "permissions": "admin"
}
EOF

Task 1.5: Verify User Creation

PYTHONPATH=. python3 -m src.cli.cli list-users

Expected output: Should show your learner user

Phase 2: Project Setup

Task 2.1: Create a Demo Project Directory

# Create a simple demo project
mkdir -p ~/demo-project
cd ~/demo-project
git init
echo "# Demo Project" > README.md
echo "print('Hello from demo project')" > main.py
git add .
git commit -m "Initial commit"
cd -

Task 2.2: Create Project Configuration

Create ~/Dropbox/AgentStore/projects/DemoProject/project.json:

{
  "id": "DemoProject",
  "directory": "~/demo-project",
  "git_repository": "file://~/demo-project",
  "create_time": "2025-10-27T12:00:00Z",
  "update_time": "2025-10-27T12:00:00Z",
  "description": "Demo project for learning the orchestration system",
  "owner": "learner",
  "collaborators": [],
  "code_research_document": "~/demo-project/RESEARCH.md",
  "default_queue": "learning-queue"
}

Command to create it:

mkdir -p ~/Dropbox/AgentStore/projects/DemoProject/{queued_prds,running_prds,finished_prds}

cat > ~/Dropbox/AgentStore/projects/DemoProject/project.json << 'EOF'
{
  "id": "DemoProject",
  "directory": "~/demo-project",
  "git_repository": "file://~/demo-project",
  "create_time": "2025-10-27T12:00:00Z",
  "update_time": "2025-10-27T12:00:00Z",
  "description": "Demo project for learning the orchestration system",
  "owner": "learner",
  "collaborators": [],
  "code_research_document": "~/demo-project/RESEARCH.md",
  "default_queue": "learning-queue"
}
EOF

Task 2.3: Verify Project Creation

PYTHONPATH=. python3 -m src.cli.cli list-projects
PYTHONPATH=. python3 -m src.cli.cli view-project DemoProject

Phase 3: Queue Setup

Task 3.1: Create a Learning Queue

Create queue directories and configuration:

mkdir -p ~/Dropbox/AgentStore/Queues/learning-queue/Jobs/{queued_jobs,running_jobs,finished_jobs,failed_jobs}

Create ~/Dropbox/AgentStore/Queues/learning-queue/queue.json:

{
  "config": {
    "id": "learning-queue",
    "worker_count": 2,
    "claude_cli_path": "claude",
    "rest_interval": 30,
    "claude_default_args": ["-p"],
    "max_job_runtime_seconds": 1800
  },
  "runtime": {
    "process_id": null,
    "active_jobs": 0,
    "last_update": null,
    "queued_jobs": 0
  }
}

Command:

cat > ~/Dropbox/AgentStore/Queues/learning-queue/queue.json << 'EOF'
{
  "config": {
    "id": "learning-queue",
    "worker_count": 2,
    "claude_cli_path": "claude",
    "rest_interval": 30,
    "claude_default_args": ["-p"],
    "max_job_runtime_seconds": 1800
  },
  "runtime": {
    "process_id": null,
    "active_jobs": 0,
    "last_update": null,
    "queued_jobs": 0
  }
}
EOF

Task 3.2: Verify Queue Creation

PYTHONPATH=. python3 -m src.cli.cli list-queues
PYTHONPATH=. python3 -m src.cli.cli view-queue learning-queue

Phase 4: Login and Set Context

Task 4.1: Login

PYTHONPATH=. python3 -m src.cli.cli login learner

Expected: "Logged in as: learner"

Task 4.2: Set Current Project

PYTHONPATH=. python3 -m src.cli.cli set-project DemoProject

Expected: "Current project set to: DemoProject"

Task 4.3: Verify Your Config

cat ~/.orchestrator_config.json

Expected: Shows username=learner, project=DemoProject

Phase 5: Start the System

Task 5.1: Start Orchestrator (Terminal 1)

cd /home/chenry/projects/ClaudeProjects/AgenticOrchestrationSystem
PYTHONPATH=. python3 -m src.orchestrator.orchestrator

Expected: See "Orchestrator started" and polling messages

Leave this running!

Task 5.2: Start Queue Manager (Terminal 2)

cd /home/chenry/projects/ClaudeProjects/AgenticOrchestrationSystem
PYTHONPATH=. python3 -m src.queue_manager.queue_manager learning-queue

Expected: See "Queue manager started for learning-queue"

Leave this running!

Task 5.3: Check System Status (Terminal 3)

cd /home/chenry/projects/ClaudeProjects/AgenticOrchestrationSystem

# Check orchestrator lock
cat ~/Dropbox/AgentStore/.orchestrator.lock

# Check queue runtime
PYTHONPATH=. python3 -m src.cli.cli view-queue learning-queue --format json

# Check logs
tail -f ~/Dropbox/AgentStore/logs/orchestrator.log

Phase 6: Submit Your First Job

Task 6.1: Create Claude Code Command (if needed)

First, ensure you have the Claude Code commands the system expects.

Create ~/.claude/commands/code-researcher.md:

mkdir -p ~/.claude/commands

cat > ~/.claude/commands/code-researcher.md << 'EOF'
You are a code researcher. Analyze the codebase in the current directory and create a comprehensive research document.

Include:
1. Project structure and architecture
2. Key modules and their purposes
3. Dependencies and technologies used
4. Entry points and main workflows
5. Configuration files and their purposes

Write your findings in markdown format.
EOF

Task 6.2: Submit a Research Code Job

PYTHONPATH=. python3 -m src.cli.cli research-code --project DemoProject

Expected: "Message queued: <correlation_id>"

Task 6.3: Watch the Job Execute

In Terminal 1 (orchestrator), watch for:

"Processing message: <correlation_id>"
"Job created: <job_id> on queue learning-queue"

In Terminal 2 (queue manager), watch for:

"Starting job: <job_id>"
Job execution messages

Task 6.4: Check Job Status

# List all jobs
PYTHONPATH=. python3 -m src.cli.cli list-jobs

# View specific job (use job ID from above)
PYTHONPATH=. python3 -m src.cli.cli view-job <job-id> --format json

Task 6.5: Check Job Files

# Check queued jobs
ls ~/Dropbox/AgentStore/Queues/learning-queue/Jobs/queued_jobs/

# Check running jobs
ls ~/Dropbox/AgentStore/Queues/learning-queue/Jobs/running_jobs/

# Check finished jobs (after completion)
ls ~/Dropbox/AgentStore/Queues/learning-queue/Jobs/finished_jobs/
cat ~/Dropbox/AgentStore/Queues/learning-queue/Jobs/finished_jobs/<job-id>.json | jq .

Task 6.6: Check Research Output

# Once job completes, check if research doc was created
cat ~/demo-project/RESEARCH.md

Phase 7: Create and Track a PRD

Task 7.1: Create a PRD File

Create ~/Dropbox/AgentStore/projects/DemoProject/queued_prds/prd-demo-001.json:

{
  "id": "prd-demo-001",
  "project": "DemoProject",
  "title": "Add Calculator Feature",
  "version": "1.0",
  "owner": "learner",
  "status": "queued",
  "created_time": "2025-10-27T13:00:00Z",
  "update_time": "2025-10-27T13:00:00Z",
  "content": "# Calculator Feature PRD\n\n## Overview\nAdd a simple calculator to the demo project.\n\n## Requirements\n- Support add, subtract, multiply, divide\n- Handle division by zero\n- Command-line interface\n\n## Implementation\n- Create calculator.py module\n- Add unit tests\n- Update README",
  "jobs": [],
  "implementation_report": null
}

Command:

cat > ~/Dropbox/AgentStore/projects/DemoProject/queued_prds/prd-demo-001.json << 'EOF'
{
  "id": "prd-demo-001",
  "project": "DemoProject",
  "title": "Add Calculator Feature",
  "version": "1.0",
  "owner": "learner",
  "status": "queued",
  "created_time": "2025-10-27T13:00:00Z",
  "update_time": "2025-10-27T13:00:00Z",
  "content": "# Calculator Feature PRD\n\n## Overview\nAdd a simple calculator to the demo project.\n\n## Requirements\n- Support add, subtract, multiply, divide\n- Handle division by zero\n- Command-line interface\n\n## Implementation\n- Create calculator.py module\n- Add unit tests\n- Update README",
  "jobs": [],
  "implementation_report": null
}
EOF

Task 7.2: View the PRD

PYTHONPATH=. python3 -m src.cli.cli list-prds
PYTHONPATH=. python3 -m src.cli.cli view-prd prd-demo-001 --format json

Task 7.3: Set Current PRD

PYTHONPATH=. python3 -m src.cli.cli set-prd prd-demo-001
cat ~/.orchestrator_config.json

Task 7.4: Create Claude Command for Task Creation

Create ~/.claude/commands/task-creator.md:

cat > ~/.claude/commands/task-creator.md << 'EOF'
You are a task creator. Based on the PRD provided in the supporting data, create a detailed task list.

Break down the requirements into:
1. Specific implementation tasks
2. Testing tasks
3. Documentation tasks

Format as a markdown checklist with clear, actionable items.
EOF

Task 7.5: Submit Create-Tasks Job

PYTHONPATH=. python3 -m src.cli.cli create-tasks --project DemoProject --prd prd-demo-001

Task 7.6: Watch PRD Status Change

# Initially in queued_prds
ls ~/Dropbox/AgentStore/projects/DemoProject/queued_prds/

# After job completes, moves to running_prds
ls ~/Dropbox/AgentStore/projects/DemoProject/running_prds/

# View updated PRD with job reference
PYTHONPATH=. python3 -m src.cli.cli view-prd prd-demo-001 --format json

Phase 8: Test Message Follow Mode

Task 8.1: Submit Job with Follow

# This will wait for orchestrator response
PYTHONPATH=. python3 -m src.cli.cli research-code --project DemoProject --follow 30

Expected: Waits up to 30 seconds for orchestrator to respond with job creation details

Phase 9: Test Queue Selection

Task 9.1: Create Second Queue

mkdir -p ~/Dropbox/AgentStore/Queues/fast-queue/Jobs/{queued_jobs,running_jobs,finished_jobs,failed_jobs}

cat > ~/Dropbox/AgentStore/Queues/fast-queue/queue.json << 'EOF'
{
  "config": {
    "id": "fast-queue",
    "worker_count": 5,
    "claude_cli_path": "claude",
    "rest_interval": 10,
    "claude_default_args": ["-p"],
    "max_job_runtime_seconds": 600
  },
  "runtime": {
    "process_id": null,
    "active_jobs": 0,
    "last_update": null,
    "queued_jobs": 0
  }
}
EOF

Task 9.2: Start Second Queue Manager (Terminal 4)

cd /home/chenry/projects/ClaudeProjects/AgenticOrchestrationSystem
PYTHONPATH=. python3 -m src.queue_manager.queue_manager fast-queue

Task 9.3: Submit Job to Specific Queue

# Override project default queue
PYTHONPATH=. python3 -m src.cli.cli research-code --project DemoProject --queue fast-queue

Task 9.4: Compare Queue Behaviors

# View both queues
PYTHONPATH=. python3 -m src.cli.cli view-queue learning-queue
PYTHONPATH=. python3 -m src.cli.cli view-queue fast-queue

# List jobs by queue
ls ~/Dropbox/AgentStore/Queues/learning-queue/Jobs/finished_jobs/
ls ~/Dropbox/AgentStore/Queues/fast-queue/Jobs/finished_jobs/

Phase 10: Test Error Handling

Task 10.1: Submit Job with Invalid Project

PYTHONPATH=. python3 -m src.cli.cli research-code --project NonExistentProject

Expected: Error message in outbox

Task 10.2: Check Error in Outbox

# Find the correlation ID from the error message
ls ~/Dropbox/AgentStore/messaging/outbox/

# View error response
cat ~/Dropbox/AgentStore/messaging/outbox/<correlation-id>.json | jq .

Task 10.3: Create Job with Non-Existent Claude Command

Temporarily rename the Claude command:

mv ~/.claude/commands/code-researcher.md ~/.claude/commands/code-researcher.md.backup

# Submit job
PYTHONPATH=. python3 -m src.cli.cli research-code --project DemoProject

Task 10.4: Watch Job Fail

# Job should move to failed_jobs
watch -n 2 "ls ~/Dropbox/AgentStore/Queues/learning-queue/Jobs/failed_jobs/"

# View failed job
cat ~/Dropbox/AgentStore/Queues/learning-queue/Jobs/failed_jobs/<job-id>.json | jq .runtime.error

Task 10.5: Restore Claude Command

mv ~/.claude/commands/code-researcher.md.backup ~/.claude/commands/code-researcher.md

Phase 11: Test Worker Count Limits

Task 11.1: Submit Multiple Jobs Quickly

# Submit 5 jobs rapidly
for i in {1..5}; do
  PYTHONPATH=. python3 -m src.cli.cli research-code --project DemoProject
  echo "Submitted job $i"
done

Task 11.2: Watch Worker Count Enforcement

# Learning queue has worker_count=2, so only 2 should run at once
watch -n 1 "PYTHONPATH=. python3 -m src.cli.cli view-queue learning-queue | grep active_jobs"

# Also watch the job directories
watch -n 1 "ls ~/Dropbox/AgentStore/Queues/learning-queue/Jobs/*/. | wc -l"

Phase 12: Explore Logs and Debugging

Task 12.1: View Orchestrator Logs

tail -n 50 ~/Dropbox/AgentStore/logs/orchestrator.log
grep ERROR ~/Dropbox/AgentStore/logs/orchestrator.log

Task 12.2: View Queue Logs

tail -n 50 ~/Dropbox/AgentStore/logs/queue-learning-queue.log
tail -n 50 ~/Dropbox/AgentStore/logs/queue-fast-queue.log

Task 12.3: View Event Logs (if created)

# Check if event logs exist
ls ~/Dropbox/AgentStore/logs/events-*.jsonl

# View events (if available)
cat ~/Dropbox/AgentStore/logs/events-*.jsonl | jq .

Phase 13: Test Daemon Control

Task 13.1: Stop Orchestrator Gracefully

In Terminal 1, press Ctrl+C

Expected:

"Shutdown signal received"
"Orchestrator stopped"
Lock file removed

Task 13.2: Verify Orchestrator Stopped

cat ~/Dropbox/AgentStore/.orchestrator.lock
# Expected: File not found

PYTHONPATH=. python3 -m src.cli.cli orchestrator-daemon status
# Expected: "Orchestrator is not running"

Task 13.3: Restart Orchestrator in Background

PYTHONPATH=. python3 -m src.cli.cli orchestrator-daemon start

Expected: "Orchestrator daemon started"

Task 13.4: Check Orchestrator Status

PYTHONPATH=. python3 -m src.cli.cli orchestrator-daemon status

Expected: "Orchestrator is running (PID )"

Task 13.5: Stop Orchestrator via CLI

PYTHONPATH=. python3 -m src.cli.cli orchestrator-daemon stop

Expected: "Orchestrator stopped"

Phase 14: Test System Recovery

Task 14.1: Simulate Orchestrator Crash

# Start orchestrator
PYTHONPATH=. python3 -m src.orchestrator.orchestrator &
ORCH_PID=$!

# Kill it ungracefully
kill -9 $ORCH_PID

Task 14.2: Check Stale Lock File

cat ~/Dropbox/AgentStore/.orchestrator.lock
# Should still exist with old PID

Task 14.3: Restart Orchestrator (Should Clean Stale Lock)

PYTHONPATH=. python3 -m src.orchestrator.orchestrator

Expected:

"Removing stale lock file (PID )"
"Orchestrator lock acquired (PID )"

Phase 15: Advanced Testing

Task 15.1: Test All List Commands

PYTHONPATH=. python3 -m src.cli.cli list-users
PYTHONPATH=. python3 -m src.cli.cli list-projects
PYTHONPATH=. python3 -m src.cli.cli list-prds --project DemoProject
PYTHONPATH=. python3 -m src.cli.cli list-jobs --project DemoProject
PYTHONPATH=. python3 -m src.cli.cli list-queues

Task 15.2: Test All View Commands

PYTHONPATH=. python3 -m src.cli.cli view-user learner
PYTHONPATH=. python3 -m src.cli.cli view-project DemoProject
PYTHONPATH=. python3 -m src.cli.cli view-prd prd-demo-001
PYTHONPATH=. python3 -m src.cli.cli view-job <job-id>
PYTHONPATH=. python3 -m src.cli.cli view-queue learning-queue

Task 15.3: Test JSON Output Format

PYTHONPATH=. python3 -m src.cli.cli list-users --format json | jq .
PYTHONPATH=. python3 -m src.cli.cli view-project DemoProject --format json | jq .

Task 15.4: Test Invalid User Permissions

Create a regular user:

cat > ~/Dropbox/AgentStore/users/regularuser.json << 'EOF'
{
  "id": "regularuser",
  "slack_username": "regularuser",
  "name": "Regular User",
  "email": "regular@example.com",
  "permissions": "user"
}
EOF

# Login as regular user
PYTHONPATH=. python3 -m src.cli.cli login regularuser

# Try admin commands (may be restricted based on handlers.py implementation)
PYTHONPATH=. python3 -m src.cli.cli list-users

Cleanup

Stop All Daemons

# Stop orchestrator
PYTHONPATH=. python3 -m src.cli.cli orchestrator-daemon stop

# Stop queue managers (Ctrl+C in their terminals)
# Or find and kill them:
ps aux | grep queue_manager
kill <PID>

Optional: Clean Up Test Data

# Remove demo project
rm -rf ~/demo-project

# Remove test files from AgentStore (be careful!)
# rm -rf ~/Dropbox/AgentStore/projects/DemoProject
# rm -rf ~/Dropbox/AgentStore/Queues/learning-queue
# rm -rf ~/Dropbox/AgentStore/Queues/fast-queue
# rm ~/Dropbox/AgentStore/users/learner.json
# rm ~/Dropbox/AgentStore/users/regularuser.json

Summary of What You've Learned

✅ Setup: Created users, projects, and queues ✅ CLI: Used all major commands (list, view, set, login) ✅ Job Submission: Submitted jobs via messaging system ✅ Job Lifecycle: Watched jobs move through queued → running → finished ✅ Queue Management: Tested multiple queues and worker limits ✅ Error Handling: Saw how system handles invalid inputs and failures ✅ Daemon Control: Started, stopped, and recovered daemons ✅ Logging: Explored logs for debugging ✅ PRD Tracking: Created and tracked PRDs through workflow ✅ System Architecture: Experienced the full file-based orchestration system

Next Steps

Create Real Projects: Set up actual codebases you want to work with
Create More Claude Commands: Add prd-creator, task-implementer, etc.
Integrate with Dropbox: Ensure Dropbox sync is working across machines
Set Up Multiple Queues: Different machines with different capabilities
Production Deployment: Run daemons as systemd services or with supervisord

FilesExpand file tree

LEARNING_PATH.md

Latest commit

History

LEARNING_PATH.md

File metadata and controls

Learning Path: Agentic Orchestration System

Phase 1: Initial Setup

Task 1.1: Verify AgentStore Structure

Task 1.2: Copy JSON Schemas

Task 1.3: Create Global Configuration

Task 1.4: Create Your User File

Task 1.5: Verify User Creation

Phase 2: Project Setup

Task 2.1: Create a Demo Project Directory

Task 2.2: Create Project Configuration

Task 2.3: Verify Project Creation

Phase 3: Queue Setup

Task 3.1: Create a Learning Queue

Task 3.2: Verify Queue Creation

Phase 4: Login and Set Context

Task 4.1: Login

Task 4.2: Set Current Project

Task 4.3: Verify Your Config

Phase 5: Start the System

Task 5.1: Start Orchestrator (Terminal 1)

Task 5.2: Start Queue Manager (Terminal 2)

Task 5.3: Check System Status (Terminal 3)

Phase 6: Submit Your First Job

Task 6.1: Create Claude Code Command (if needed)

Task 6.2: Submit a Research Code Job

Task 6.3: Watch the Job Execute

Task 6.4: Check Job Status

Task 6.5: Check Job Files

Task 6.6: Check Research Output

Phase 7: Create and Track a PRD

Task 7.1: Create a PRD File

Task 7.2: View the PRD

Task 7.3: Set Current PRD

Task 7.4: Create Claude Command for Task Creation

Task 7.5: Submit Create-Tasks Job

Task 7.6: Watch PRD Status Change

Phase 8: Test Message Follow Mode

Task 8.1: Submit Job with Follow

Phase 9: Test Queue Selection

Task 9.1: Create Second Queue

Task 9.2: Start Second Queue Manager (Terminal 4)

Task 9.3: Submit Job to Specific Queue

Task 9.4: Compare Queue Behaviors

Phase 10: Test Error Handling

Task 10.1: Submit Job with Invalid Project

Task 10.2: Check Error in Outbox

Task 10.3: Create Job with Non-Existent Claude Command

Task 10.4: Watch Job Fail

Task 10.5: Restore Claude Command

Phase 11: Test Worker Count Limits

Task 11.1: Submit Multiple Jobs Quickly

Task 11.2: Watch Worker Count Enforcement

Phase 12: Explore Logs and Debugging

Task 12.1: View Orchestrator Logs

Task 12.2: View Queue Logs

Task 12.3: View Event Logs (if created)

Phase 13: Test Daemon Control

Task 13.1: Stop Orchestrator Gracefully

Task 13.2: Verify Orchestrator Stopped

Task 13.3: Restart Orchestrator in Background

Task 13.4: Check Orchestrator Status

Task 13.5: Stop Orchestrator via CLI

Phase 14: Test System Recovery

Task 14.1: Simulate Orchestrator Crash

Task 14.2: Check Stale Lock File

Task 14.3: Restart Orchestrator (Should Clean Stale Lock)

Phase 15: Advanced Testing

Task 15.1: Test All List Commands

Task 15.2: Test All View Commands

Task 15.3: Test JSON Output Format

Task 15.4: Test Invalid User Permissions

Cleanup

Stop All Daemons

Optional: Clean Up Test Data