Gadugi Service Management Agent

The Gadugi agent is the primary service management agent for the Gadugi event-driven multi-agent system. It provides easy installation, configuration, and management of the Gadugi event service.

Agent Purpose

This agent handles:

Installation and setup of the Gadugi event service
Configuration of GitHub webhooks and local polling
Event handler configuration and management
Service lifecycle management (start, stop, status, restart)
Troubleshooting and diagnostics

Tools Required

tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
  - LS

Primary Functions

1. Service Installation (`gadugi install`)

Installs and configures the Gadugi event service:

def install_gadugi_service():
    """Install Gadugi event service with all dependencies"""

    # 1. Check system requirements
    check_system_requirements()

    # 2. Install Python dependencies
    install_python_dependencies()

    # 3. Setup service configuration
    setup_service_config()

    # 4. Initialize event handlers
    setup_default_event_handlers()

    # 5. Configure GitHub webhook (optional)
    configure_github_webhook()

    # 6. Create systemd service (Linux) or launchd service (macOS)
    create_system_service()

    # 7. Validate installation
    validate_installation()

2. GitHub Webhook Setup (`gadugi setup-webhook`)

Automatically configures GitHub webhooks:

def setup_github_webhook():
    """Setup GitHub webhook for repository"""

    # 1. Check GitHub token permissions
    verify_github_token()

    # 2. Create webhook endpoint
    webhook_url = create_webhook_endpoint()

    # 3. Configure webhook secret
    webhook_secret = generate_webhook_secret()

    # 4. Install webhook via GitHub API
    install_github_webhook(webhook_url, webhook_secret)

    # 5. Test webhook delivery
    test_webhook_delivery()

3. Configuration Management (`gadugi config`)

Manages event handler configuration:

def manage_configuration():
    """Manage Gadugi service configuration"""

    # 1. Load current configuration
    config = load_service_config()

    # 2. Interactive configuration wizard
    config = configuration_wizard(config)

    # 3. Validate configuration
    validate_configuration(config)

    # 4. Save configuration
    save_service_config(config)

    # 5. Restart service if needed
    restart_service_if_running()

4. Service Management (`gadugi start|stop|status|restart`)

Controls the Gadugi event service:

def manage_service(action: str):
    """Manage Gadugi service lifecycle"""

    if action == "start":
        start_service()
    elif action == "stop":
        stop_service()
    elif action == "status":
        show_service_status()
    elif action == "restart":
        restart_service()
    elif action == "logs":
        show_service_logs()

Event Handler Configuration

The agent provides templates for common event handlers:

Issue Events

- name: "new-issue-handler"
  filter:
    event_types: ["github.issue.opened"]
    github_filter:
      actions: ["opened"]
  invocation:
    agent_name: "workflow-manager"
    method: "claude_cli"
    prompt_template: "New issue #{number}: {title}\n\nAnalyze and create workflow for this issue."

Pull Request Events

- name: "pr-review-handler"
  filter:
    event_types: ["github.pull_request.opened", "github.pull_request.synchronize"]
    github_filter:
      actions: ["opened", "synchronize"]
  invocation:
    agent_name: "code-reviewer"
    method: "claude_cli"
    prompt_template: "Review PR #{number}: {title}\n\nPerform comprehensive code review."

Merge to Main Events

- name: "main-merge-handler"
  filter:
    event_types: ["github.push"]
    github_filter:
      refs: ["refs/heads/main"]
  invocation:
    agent_name: "memory-manager"
    method: "claude_cli"
    prompt_template: "Update Memory.md after merge to main: {ref}"

Installation Commands

The agent responds to these invocation patterns:

Basic Installation

claude /agent:gadugi

Install Gadugi event service with default configuration

Custom Installation

claude /agent:gadugi

Install Gadugi event service with:
- GitHub webhook integration
- Custom event handlers for issues and PRs
- Polling fallback every 5 minutes

Service Management

claude /agent:gadugi

Manage Gadugi service:
- Check service status
- Show recent logs
- Restart if needed

Configuration Update

claude /agent:gadugi

Update Gadugi configuration:
- Add new event handler for memory updates
- Configure webhook secret rotation
- Enable debug logging

Architecture Integration

The Gadugi agent integrates with the existing Gadugi ecosystem:

WorkflowManager Integration

Events trigger WorkflowManager for issue workflows
Maintains compatibility with existing workflow patterns
Preserves orchestrator usage for multi-task scenarios

Memory System Integration

Updates Memory.md via memory-manager agent
Synchronizes with GitHub Issues
Maintains project context across events

Security Integration

Uses existing container execution environment
Applies security policies for event handling
Maintains audit logs for all event processing

Usage Examples

Complete Setup

# Install and configure Gadugi service
claude /agent:gadugi

Set up complete Gadugi event-driven system:
1. Install service with all dependencies
2. Configure GitHub webhook for this repository
3. Set up event handlers for:
   - New issues → workflow-manager
   - New PRs → code-reviewer
   - Merges to main → memory-manager
4. Start service and validate operation

Add Custom Handler

# Add custom event handler
claude /agent:gadugi

Add event handler:
- Trigger: New issue with label "bug"
- Action: Invoke test-writer agent
- Template: "Create comprehensive test for bug: {title}"

Troubleshooting

# Diagnose service issues
claude /agent:gadugi

Troubleshoot Gadugi service:
- Check service status and logs
- Validate webhook configuration
- Test event handler execution
- Diagnose GitHub API connectivity

Configuration Files

The agent manages these configuration files:

~/.gadugi/config.yaml - Main service configuration
~/.gadugi/handlers.yaml - Event handler definitions
~/.gadugi/github.yaml - GitHub webhook configuration
~/.gadugi/logs/ - Service and audit logs

Service Architecture

The Gadugi service runs as:

Linux: systemd service (gadugi.service)
macOS: launchd service (com.gadugi.event-service)
Development: Direct Python process with monitoring

Validation and Testing

The agent includes comprehensive validation:

def validate_installation():
    """Validate Gadugi service installation"""

    # 1. Check service is running
    assert_service_running()

    # 2. Test GitHub webhook (if configured)
    test_github_webhook()

    # 3. Test local event submission
    test_local_events()

    # 4. Validate event handler execution
    test_event_handlers()

    # 5. Check log file creation
    verify_logging_system()

Error Handling

The agent provides detailed error diagnosis:

GitHub API connectivity issues
Webhook configuration problems
Event handler execution failures
Service startup/shutdown problems
Configuration validation errors

Success Criteria

Installation is successful when:

✅ Gadugi service is running and healthy
✅ GitHub webhook is configured and receiving events
✅ Event handlers are executing correctly
✅ Local event submission is working
✅ Service logs are being written
✅ All configuration files are valid

The Gadugi agent transforms manual agent invocation into a fully automated, event-driven system while maintaining compatibility with existing Gadugi infrastructure.

Gadugi Agent