### Install Sugar

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/quick-start.md

Methods for installing the Sugar package via PyPI or from the source repository for development purposes.

```bash
pip install sugarai
```

```bash
git clone https://github.com/roboticforce/sugar.git
cd sugar
pip install -e .
```

--------------------------------

### Configure Project-Specific Settings

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/installation-guide.md

YAML configuration examples for different technology stacks to define file discovery, test coverage, and error log monitoring.

```yaml
# Python Project
discovery:
  code_quality:
    file_extensions: [".py"]
    excluded_dirs: ["venv", ".venv", "__pycache__", ".pytest_cache"]

# JavaScript/Node Project
discovery:
  code_quality:
    file_extensions: [".js", ".ts", ".jsx", ".tsx"]
    excluded_dirs: ["node_modules", "dist", "build"]
```

--------------------------------

### Sugar Configuration Schema

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/quick-start.md

Example YAML configuration for customizing Sugar's behavior, including dry-run settings, Claude CLI paths, and discovery modules.

```yaml
sugar:
  dry_run: true
  loop_interval: 300
  max_concurrent_work: 3
  claude:
    command: "/path/to/claude"
    timeout: 1800
  discovery:
    error_logs:
      enabled: true
      paths: ["logs/errors/"]
    code_quality:
      enabled: true
      source_dirs: ["src", "lib", "app"]
```

--------------------------------

### Quick Setup and Repository Formats

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/github-integration.md

Examples for quick CLI-based setup and various repository string formats supported by the configuration.

```bash
gh auth login
cat >> .sugar/config.yaml << 'EOF'
sugar:
  discovery:
    github:
      enabled: true
      repo: "myusername/myproject"
      auth_method: "gh_cli"
      issue_labels: ["bug", "enhancement"]
EOF
sugar run --dry-run --once
```

```yaml
repo: "username/repository"
repo: "organization/repository"
repo: "enterprise.github.com/org/repo"
```

--------------------------------

### Install Sugar Library

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/installation-guide.md

Provides two methods for installing the Sugar Python library: using pip from PyPI (recommended) or installing from source for development purposes.

```bash
# Option 1: PyPI Installation (Recommended)
pip install sugarai

# Option 2: Install from Source (For Development)
# Clone or download the sugar package
git clone https://github.com/roboticforce/sugar.git

# Install in development mode (allows for easy updates)
cd sugar
pip install -e .

# Or install directly without cloning
pip install -e git+https://github.com/roboticforce/sugar.git#egg=sugar
```

--------------------------------

### Development Setup

Source: https://github.com/roboticforce/sugar/blob/main/README.md

Commands to clone the repository, install dependencies, and run the test suite for contributors.

```bash
git clone https://github.com/roboticforce/sugar.git
cd sugar
uv pip install -e ".[dev,test,github]"
pytest tests/ -v
```

--------------------------------

### sugar help

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/cli-reference.md

Displays comprehensive Sugar help and a getting started guide.

```APIDOC
## `sugar help`

### Description
Show comprehensive Sugar help and getting started guide.

### Method
N/A (CLI Command)

### Endpoint
N/A (CLI Command)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
sugar help
```

### Response
#### Success Response (0)
Displays detailed help information, including quick start steps, command summaries, configuration basics, and more.

#### Response Example
```
# Output includes:
# - Quick start steps
# - Overview of Sugar's dual operation modes (autonomous + manual)
# - Core commands summary
# - Configuration basics
# - Project structure
# - Safety features
# - Documentation links
# - Tips and troubleshooting
```
```

--------------------------------

### Setup Development Environment

Source: https://github.com/roboticforce/sugar/blob/main/action/CONTRIBUTING.md

Commands to clone the repository, install necessary Python dependencies, and initialize pre-commit hooks for code quality.

```bash
git clone https://github.com/YOUR_USERNAME/sugar.git
cd sugar
uv pip install -e ".[dev,test,github]"
pre-commit install
```

--------------------------------

### Sugar Configuration Example

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/installation-guide.md

An example YAML configuration file for Sugar, detailing settings for core loop, Claude Code integration, work discovery (error logs, code quality, test coverage, GitHub), storage, safety, and logging.

```yaml
sugar:
  # Core Loop Settings
  loop_interval: 300  # 5 minutes between cycles
  max_concurrent_work: 3  # Execute multiple tasks per cycle
  dry_run: true       # Set to false when ready for real execution
  
  # Claude Code Integration
  claude:
    command: "/path/to/claude"  # Auto-detected, but can be customized
    timeout: 1800       # 30 minutes max per task
    context_file: ".sugar/context.json"
    
  # Work Discovery
  discovery:
    error_logs:
      enabled: true
      paths:
        - "logs/errors/"      # Your error log directories
        - "logs/feedback/"
        - ".sugar/logs/"
      patterns: ["*.json", "*.log"]
      max_age_hours: 24
    
    code_quality:
      enabled: true
      root_path: "."          # Project root to analyze
      file_extensions: [".py", ".js", ".ts", ".jsx", ".tsx"]
      source_dirs: ["src", "lib", "app"]  # Your source directories
      excluded_dirs: ["node_modules", ".git", "__pycache__", "venv", ".venv", ".sugar"]
      max_files_per_scan: 50
      
    test_coverage:
      enabled: true
      root_path: "."
      source_dirs: ["src", "lib", "app", "api", "server"]
      test_dirs: ["tests", "test", "__tests__", "spec"]
      
    github:
      enabled: false          # Enable for GitHub integration
      repo: "owner/repo"      # Your repository
      token: "ghp_..."        # GitHub token
      
  # Storage
  storage:
    database: ".sugar/sugar.db"  # Project-specific database
    backup_interval: 3600  # 1 hour
    
  # Safety
  safety:
    max_retries: 3
    excluded_paths: ["/System", "/usr/bin", "/etc", ".sugar"]
    
  # Logging
  logging:
    level: "INFO"
    file: ".sugar/sugar.log"  # Project-specific logs

```

--------------------------------

### Add Tasks to Sugar

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/installation-guide.md

Demonstrates how to add various types of tasks to Sugar using the `sugar add` command. Includes examples for features, bug fixes, tests, documentation, and refactoring, with options for priority and urgency.

```bash
# Add various types of tasks
sugar add "Implement user authentication" --type feature --priority 4
sugar add "Fix memory leak in auth module" --type bug_fix --urgent
sugar add "Add unit tests for payments" --type test --priority 3
sugar add "Update API documentation" --type documentation --priority 2
sugar add "Refactor user service" --type refactor --priority 3
```

--------------------------------

### Install and Install Pre-commit Hooks (Bash)

Source: https://github.com/roboticforce/sugar/blob/main/docs/dev/testing.md

Installs the pre-commit framework and then installs the git hooks. This ensures linting and formatting checks are run automatically before each commit, maintaining code quality.

```bash
pip install pre-commit
pre-commit install
```

--------------------------------

### Manage Tasks and Execution

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/quick-start.md

CLI commands for adding manual tasks, checking system status, and executing the autonomous development loop.

```bash
sugar add "Implement user authentication" --type feature --priority 4
sugar add "Fix memory leak in auth module" --type bug_fix --urgent
sugar add "Add unit tests for payments" --type test --priority 3
sugar status
sugar list
sugar view TASK_ID
sugar run --dry-run --once
sugar run
```

--------------------------------

### Initialize and Configure Sugar

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/quick-start.md

Commands to initialize a project for Sugar and register the MCP server with Claude Code to enable memory features.

```bash
cd /path/to/your/project
sugar init
```

```bash
claude mcp add sugar -- sugar mcp memory
```

--------------------------------

### Install Sugar CLI

Source: https://github.com/roboticforce/sugar/blob/main/examples/claude-code-plugin/README.md

Installs the Sugar CLI tool using pip. This is a prerequisite for using Sugar's command-line functionalities.

```bash
pip install sugarai
```

--------------------------------

### Install Claude Code CLI

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/installation-guide.md

Installs the Claude Code CLI using npm or provides a link to the official installation guide. It also includes a command to verify the installation.

```bash
# Install via npm (recommended)
npm install -g @anthropic-ai/claude-code-cli

# Or follow official installation guide
# Visit: https://docs.anthropic.com/en/docs/claude-code

claude --version
```

--------------------------------

### Quality Gate Configuration by Framework

Source: https://github.com/roboticforce/sugar/blob/main/sugar/quality_gates/USER_GUIDE.md

Configuration examples for setting up quality gates, mandatory testing, and pre-flight checks for Python/Django and Ruby on Rails projects.

```yaml
# Python/Django Example
quality_gates:
  enabled: true
  mandatory_testing:
    enabled: true
    test_commands:
      default: "pytest"
      unit: "pytest tests/unit/"
      integration: "pytest tests/integration/"
    auto_detect_required_tests:
      enabled: true
      patterns:
        - pattern: "**/*_controller.py"
          required_tests: ["integration"]
        - pattern: "**/models/*.py"
          required_tests: ["unit", "integration"]
  functional_verification:
    enabled: true
    methods:
      http_requests:
        enabled: true
    auto_detect:
      enabled: true
      patterns:
        - pattern: "**/views/*.py"
          verification: "http_requests"
          test_urls: ["/"]
pre_flight_checks:
  enabled: true
  checks:
    - name: "django_server"
      type: "port_check"
      port: 8000
    - name: "database"
      type: "command"
      command: "python manage.py check --database default"
```

```yaml
# Ruby on Rails Example
quality_gates:
  enabled: true
  mandatory_testing:
    enabled: true
    test_commands:
      default: "bundle exec rspec"
      unit: "bundle exec rspec spec/models"
      integration: "bundle exec rspec spec/requests"
  functional_verification:
    enabled: true
    auto_detect:
      patterns:
        - pattern: "app/controllers/**/*.rb"
          verification: "http_requests"
          test_urls: ["/"]
pre_flight_checks:
  enabled: true
  checks:
    - name: "rails_server"
      type: "port_check"
      port: 3000
    - name: "database"
      type: "command"
      command: "rails runner 'ActiveRecord::Base.connection'"
```

--------------------------------

### Install Sugar Plugin in Claude Code

Source: https://github.com/roboticforce/sugar/blob/main/examples/claude-code-plugin/README.md

Demonstrates how to install the Sugar plugin within the Claude Code environment, either via a direct command or by manually linking the plugin repository.

```bash
/plugin install sugar@roboticforce
```

```bash
# Clone Sugar repository
git clone https://github.com/roboticforce/sugar.git

# Link plugin (from your project directory)
ln -s /path/to/sugar/.claude-plugin ./.claude-plugins/sugar
```

--------------------------------

### Install and Verify Claude CLI

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/troubleshooting.md

Installs the Claude CLI globally using npm and verifies the installation by checking its version. This is a prerequisite for Sugar to interact with Claude.

```bash
npm install -g @anthropic-ai/claude-code-cli
claude --version  # Verify installation
```

--------------------------------

### Install and Initialize Sugar CLI

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/faq.md

Instructions for installing the Sugar AI package via pip and initializing the project environment.

```bash
pip install sugarai
cd your-project
sugar init
```

--------------------------------

### Start Development Server

Source: https://github.com/roboticforce/sugar/blob/main/sugar/quality_gates/USER_GUIDE.md

Starts the development server for Rails or Python projects. This is a common solution for 'Port 3000 not listening' errors.

```shell
rails server
```

```shell
python manage.py runserver
```

--------------------------------

### Initialize and Configure Solo Developer Workflow

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/examples.md

Provides a setup script for solo developers to initialize a project and configure Sugar for background maintenance tasks. It includes setting up the configuration file and running the process in the background.

```bash
sugar init
sugar add "Implement user dashboard" --type feature --priority 4
sugar add "Fix responsive layout" --type bug_fix --priority 3
sugar add "Add integration tests" --type test --priority 2

cat > .sugar/config.yaml << EOF
sugar:
  loop_interval: 600
  max_concurrent_work: 1
  discovery:
    error_logs:
      enabled: true
    code_quality:
      enabled: true
    test_coverage:
      enabled: true
EOF

sugar run &
```

--------------------------------

### Optimize Sugar for Large Codebases

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/examples.md

YAML configuration examples to tune performance for large projects by adjusting scan intervals, concurrency, and file exclusion patterns.

```yaml
sugar:
  loop_interval: 3600
  max_concurrent_work: 1
  discovery:
    code_quality:
      max_files_per_scan: 25
      excluded_dirs: ["node_modules", "venv", ".git", ".sugar"]
  claude:
    timeout: 1800
```

--------------------------------

### Action Versioning Reference

Source: https://github.com/roboticforce/sugar/blob/main/action/DEPLOYMENT.md

Examples of how users can reference different versions of the GitHub Action in their workflow files.

```yaml
# Specific version (recommended for production)
uses: roboticforce/sugar@v1.0.0

# Major version (gets patches/features automatically)
uses: roboticforce/sugar@v1

# Latest (not recommended)
uses: roboticforce/sugar@main
```

--------------------------------

### Initialize Sugar in Project

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/installation-guide.md

Command to initialize Sugar within a project directory. This creates necessary configuration files and directories for Sugar's operation.

```bash
cd /path/to/your/project
sugar init
```

--------------------------------

### Initialize and Run Sugar for Team Collaboration

Source: https://github.com/roboticforce/sugar/blob/main/examples/claude-code-plugin/README.md

These bash commands demonstrate how multiple developers can collaborate on the same Sugar project. 'sugar init' initializes the project, and 'sugar run &' starts the Sugar process in the background. Developers can then see the shared task queue using 'sugar list'.

```bash
# Developer A
cd project
sugar init
sugar run &

# Developer B (same project, different machine)
cd project
sugar init  # Uses same .sugar/ via git
sugar list  # Sees shared task queue
```

--------------------------------

### Initialize and Start Sugar SDK Integration (TypeScript)

Source: https://github.com/roboticforce/sugar/blob/main/docs/phase3_sdk_integration.md

Initializes the SugarSDKIntegration class with configuration and starts the SDK integration features. This includes optionally subscribing to OpenCode events for synchronization.

```typescript
import { createOpencodeClient } from '@opencode-ai/sdk'
import type { Session, Event } from '@opencode-ai/sdk'

export interface SugarSDKConfig {
  sugarApiUrl: string
  opencodeApiUrl: string
  autoInjectContext: boolean
  eventSync: boolean
}

export class SugarSDKIntegration {
  private opencodeClient: any
  private sugarApiUrl: string
  private config: SugarSDKConfig
  private eventSubscription: any

  constructor(config: SugarSDKConfig) {
    this.config = config
    this.sugarApiUrl = config.sugarApiUrl
    this.opencodeClient = createOpencodeClient({
      baseUrl: config.opencodeApiUrl
    })
  }

  /**
   * Start SDK integration features.
   */
  async start(): Promise<void> {
    console.log('[Sugar SDK] Starting integration...')

    // Subscribe to OpenCode events if enabled
    if (this.config.eventSync) {
      await this.startEventSync()
    }

    console.log('[Sugar SDK] Integration active')
  }

  /**
   * Subscribe to OpenCode events and relay to Sugar.
   */
  private async startEventSync(): Promise<void> {
    try {
      const events = await this.opencodeClient.event.subscribe()

      for await (const event of events.stream) {
        await this.handleOpencodeEvent(event)
      }
    } catch (error) {
      console.error('[Sugar SDK] Event sync error:', error)
    }
  }

  /**
   * Handle OpenCode events and relay relevant ones to Sugar.
   */
  private async handleOpencodeEvent(event: Event): Promise<void> {
    // Only relay specific event types to Sugar
    const relayTypes = [
      'session.created',
      'session.closed',
      'file.changed',
      'command.executed'
    ]

    if (!relayTypes.includes(event.type)) {
      return
    }

    try {
      await fetch(`${this.sugarApiUrl}/events/opencode`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          type: event.type,
          session_id: event.sessionId,
          timestamp: new Date().toISOString(),
          data: event.properties
        })
      })
    } catch (error) {
      console.error('[Sugar SDK] Failed to relay event:', error)
    }
  }

  /**
   * Request context injection from Sugar.
   */
  async requestContext(sessionId: string, topic: string): Promise<boolean> {
    try {
      const response = await fetch(`${this.sugarApiUrl}/context/inject`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          session_id: sessionId,
          topic: topic,
          max_results: 5
        })
      })

      return response.ok
    } catch (error) {
      console.error('[Sugar SDK] Context request failed:', error)
      return false
    }
  }

  /**
   * Notify Sugar of task completion for OpenCode-delegated tasks.
   */
  async notifyTaskCompletion(taskId: string, result: any): Promise<void> {
    try {
      await fetch(`${this.sugarApiUrl}/tasks/${taskId}/complete`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          success: result.success,
          output: result.output,
          completed_at: new Date().toISOString()
        })
      })
    } catch (error) {
      console.error('[Sugar SDK] Failed to notify completion:', error)
    }
  }

  /**
   * Get current session context for Sugar.
   */
  async getSessionContext(sessionId: string): Promise<any> {
    try {
      const session = await this.opencodeClient.session.get({ sessionId })
      const fileStatus = await this.opencodeClient.file.status({ sessionId })

      return {
        directory: session.directory,
        message_count: session.messages?.length || 0,
        modified_files: fileStatus.modified || [],
        created_files: fileStatus.created || []
      }
    } catch (error) {
      console.error('[Sugar SDK] Failed to get session context:', error)
      return null
    }
  }

  /**
   * Stop integration and cleanup.
   */
  async stop(): Promise<void> {
    if (this.eventSubscription) {
      // Cleanup event subscription
      this.eventSubscription = null
    }
    console.log('[Sugar SDK] Integration stopped')
  }
}

```

--------------------------------

### Advanced CLI Setup and Notification Commands

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/opencode.md

Detailed CLI usage for non-interactive setup, dry-runs, and sending custom notifications to the OpenCode TUI.

```bash
# Non-interactive setup
sugar opencode setup --yes

# Preview changes
sugar opencode setup --dry-run

# Send notifications
sugar opencode notify "Build started"
sugar opencode notify "All tests passed" --level success
```

--------------------------------

### Install GitHub CLI

Source: https://github.com/roboticforce/sugar/blob/main/docs/issue-responder.md

Instructions for installing the GitHub CLI (gh) on macOS and Linux environments to enable project interactions.

```bash
# macOS
brew install gh

# Linux
sudo apt-get install gh
```

--------------------------------

### Install Sugar OpenCode Plugin Locally

Source: https://github.com/roboticforce/sugar/blob/main/packages/opencode-plugin/README.md

This bash command demonstrates how to install the Sugar OpenCode plugin locally by copying the plugin files to the OpenCode plugins directory. Ensure the path `~/.config/opencode/plugins/sugar` is correct for your OpenCode installation.

```bash
cp -r packages/opencode-plugin ~/.config/opencode/plugins/sugar
```

--------------------------------

### Troubleshoot Sugar Plugin Loading

Source: https://github.com/roboticforce/sugar/blob/main/examples/claude-code-plugin/README.md

These bash commands assist in troubleshooting Sugar plugin loading issues. They involve verifying the plugin structure, checking the manifest file (plugin.json), and reinstalling the plugin using the '/plugin uninstall' and '/plugin install' commands.

```bash
# Verify plugin structure
ls -la .claude-plugins/sugar/.claude-plugin/

# Check manifest
cat .claude-plugins/sugar/.claude-plugin/plugin.json

# Reinstall
/plugin uninstall sugar
/plugin install sugar@roboticforce
```

--------------------------------

### Install OpenCode Dependencies (Bash)

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/opencode.md

These bash commands show how to install the necessary dependencies for OpenCode integration with Sugar. You can either inject 'aiohttp' into an existing 'sugarai' installation or install 'sugarai' with the 'opencode' extra.

```bash
pipx inject sugarai aiohttp
# Or
pip install 'sugarai[opencode]'
```

--------------------------------

### Manage Background Services

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/installation-guide.md

Standard shell commands for managing the Sugar process lifecycle, including starting as a service, stopping via PID, and log monitoring.

```bash
nohup sugar run > sugar.log 2>&1 &
echo $! > sugar.pid
kill $(cat sugar.pid)
ps aux | grep "sugar run"
tail -f .sugar/sugar.log
```

--------------------------------

### Initialize Sugar Project

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/cli-reference.md

Initializes the Sugar environment in a directory, creating the necessary configuration files, SQLite database, and log directories.

```bash
# Initialize in current directory
sugar init

# Initialize in specific directory
sugar init --project-dir /path/to/my/project
```

--------------------------------

### Sugar Configuration Example (YAML)

Source: https://github.com/roboticforce/sugar/blob/main/docs/phase3_sdk_integration.md

A comprehensive example of the Sugar configuration file in YAML format. This configuration covers core settings, storage, Claude integration, OpenCode integration details (context injection, event sync, delegation), API server settings, and memory system parameters.

```yaml
sugar:
  version: "3.6.0"

  # Core settings
  dry_run: false
  loop_interval: 300
  max_concurrent_work: 3

  # Storage
  storage:
    database: ".sugar/sugar.db"

  # Claude configuration
  claude:
    executor: "sdk"
    model: "claude-sonnet-4-20250514"
    timeout: 300
    permission_mode: "acceptEdits"

  # OpenCode Integration (Phase 3)
  opencode:
    enabled: true
    base_url: "http://localhost:4096"
    timeout: 30

    context_injection:
      auto_inject: true
      trigger_keywords: ["remember", "decided", "how do we", "context"]
      max_memories: 5
      max_tokens: 2000

    event_sync:
      enabled: true
      relay_events: ["session.created", "file.changed", "command.executed"]
      store_as_memories: true

    delegation:
      allow_from_opencode: true
      default_priority: 3
      notification_on_complete: true

  # API Server
  api:
    enabled: true
    host: "127.0.0.1"
    port: 4097
    key: "your-api-key-here"
    rate_limit: 60  # requests per minute
    cors_origins: ["http://localhost:4096"]

  # Memory system
  memory:
    enabled: true
    embedder: "sentence-transformers/all-MiniLM-L6-v2"
    max_memories: 10000
    ttl_days: 90

```

--------------------------------

### Install or Update Claude CLI (Bash)

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/installation-guide.md

Provides commands to check if the Claude CLI is installed and accessible. If not, it offers instructions to install it globally using npm or to update the Sugar configuration with the correct path to the Claude executable.

```bash
# Check if Claude CLI is accessible
claude --version

# If not found, install Claude CLI first:
npm install -g @anthropic-ai/claude-code-cli

# Or update config with full path:
# Edit .sugar/config.yaml to set correct path:
# claude:
#   command: "/full/path/to/claude"
```

--------------------------------

### Setup and Status CLI Commands for Sugar OpenCode

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/opencode.md

Commands to initialize the OpenCode integration and verify the current status of the connection.

```bash
sugar opencode setup
sugar opencode status
```

--------------------------------

### Initialize and Run Sugar

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/execution-context.md

Standard commands to initialize the Sugar environment, add tasks, and start the autonomous execution process.

```bash
cd /path/to/your/project
sugar init
sugar add "Implement feature" --type feature --priority 4
sugar run
```

--------------------------------

### Start Sugar Autonomous Execution

Source: https://github.com/roboticforce/sugar/blob/main/examples/claude-code-plugin/README.md

Initiates Sugar's autonomous development mode to process and execute tasks from the queue. This command starts the automated workflow.

```bash
/sugar-run
```

--------------------------------

### Task Example with Success Criteria (Python)

Source: https://github.com/roboticforce/sugar/blob/main/sugar/quality_gates/USER_GUIDE.md

An example Python dictionary representing a task, including a list of success criteria such as HTTP status, no redirects, and test suite execution.

```python
task = {
    "title": "Fix /login redirect",
    "success_criteria": [
        {
            "type": "http_status",
            "url": "http://localhost:3000/login",
            "expected": 200
        },
        {
            "type": "http_no_redirect",
            "url": "http://localhost:3000/login",
            "disallowed_status": [301, 302]
        },
        {
            "type": "test_suite",
            "command": "pytest tests/test_login.py",
            "expected_failures": 0
        }
    ]
}
```

--------------------------------

### Correct Way to Run Sugar

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/troubleshooting.md

Illustrates the correct architecture for running Sugar, emphasizing that it should be executed in a regular terminal, not within a Claude Code session, to avoid recursion and conflicts.

```text
✅ Correct: Terminal → Sugar → Claude Code CLI (for tasks)
❌ Incorrect: Claude Code → Sugar → Claude Code CLI (recursive)
```

--------------------------------

### Commit Message Enhancement Example (feat)

Source: https://github.com/roboticforce/sugar/blob/main/sugar/quality_gates/INTEGRATION.md

An example of an automatically enhanced commit message when quality gates pass. It includes the feature type, a description, work ID, Sugar version, quality gate status, and evidence links.

```markdown
feat: Implement new feature

Work ID: abc123
Generated with Sugar v2.0.0

Quality Gates:
- Tests: ✅ PASSED
- Success Criteria: ✅ VERIFIED
- Claims Proven: ✅ YES
- Total Evidence: 5 items

Evidence:
- file:///path/to/.sugar/test_evidence/abc123.txt
- file:///path/to/.sugar/evidence/abc123.json
```

--------------------------------

### Clone and Set Up Sugar Project

Source: https://github.com/roboticforce/sugar/blob/main/docs/dev/contributing.md

Instructions to clone the Sugar repository, switch to the develop branch, and set up a Python virtual environment with development dependencies. It also includes installing pre-commit hooks for code quality.

```bash
git clone https://github.com/yourusername/sugar.git
cd sugar
git checkout develop  # Always work from develop

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install
```

--------------------------------

### Control Autonomous Operation

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/installation-guide.md

Commands to initiate, test, and run the Sugar autonomous engine in the foreground or background.

```bash
sugar run --dry-run --once
sugar run
nohup sugar run > sugar-autonomous.log 2>&1 &
```

--------------------------------

### Example Usage of Sugar OpenCode Commands

Source: https://github.com/roboticforce/sugar/blob/main/packages/opencode-plugin/README.md

These are example commands for interacting with the Sugar plugin within OpenCode. They demonstrate how to add tasks, list the task queue, check system status, and run the Sugar autonomous cycle.

```bash
# Add a task
/sugar-add "Fix the authentication timeout bug"

# View queue
/sugar-list

# Check status
/sugar-status

# Run Sugar
/sugar-run
```

--------------------------------

### Task File Expectation Definition

Source: https://github.com/roboticforce/sugar/blob/main/sugar/quality_gates/USER_GUIDE.md

Example of defining expected file modifications within a task object for validation purposes.

```python
task = {
    "title": "Fix user model",
    "files_to_modify": {
        "expected": [
            "app/models/user.py",
            "tests/test_user.py"
        ]
    }
}
```

--------------------------------

### Example Sugar Configurations (JSON)

Source: https://github.com/roboticforce/sugar/blob/main/docs/issue-responder.md

Demonstrates different JSON configurations for Sugar, showcasing how to define persona, instructions, guidelines, and constraints for various use cases like open-source projects, enterprise APIs, and developer tools.

```json
{
  "instructions": "You are a friendly assistant for this open source project. Welcome new contributors warmly. Point beginners to issues labeled 'good first issue'. Thank people for detailed bug reports.",
  "guidelines": [
    "Be encouraging and welcoming",
    "Use emoji sparingly but warmly",
    "Suggest contributing guidelines when appropriate"
  ]
}
```

```json
{
  "persona": {
    "role": "Technical Support Engineer",
    "expertise": ["REST APIs", "OAuth 2.0", "Rate Limiting"]
  },
  "instructions": "You are a technical support assistant for the Acme API. Be professional and precise. Reference API documentation at docs.acme.com. For billing questions, direct users to support@acme.com.",
  "constraints": [
    "Don't discuss pricing or enterprise tiers",
    "Don't speculate about roadmap or release dates",
    "Don't share internal implementation details"
  ]
}
```

```json
{
  "persona": {
    "role": "CLI Tool Expert",
    "expertise": ["Python", "CLI Design", "Unix"]
  },
  "instructions": "You assist users with this CLI tool. Provide command examples. Reference man pages and --help output when relevant.",
  "guidelines": [
    "Include full command examples",
    "Show expected output when helpful",
    "Mention related commands"
  ]
}
```

--------------------------------

### Initialize Sugar Project

Source: https://context7.com/roboticforce/sugar/llms.txt

Sets up the local project environment by creating a .sugar directory containing the task database, configuration, and custom prompts.

```bash
cd ~/dev/my-app
sugar init
```

--------------------------------

### Monitor Sugar Instances Across Projects (Shell)

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/installation-guide.md

This script iterates through all project directories, checks for a .sugar subdirectory, and displays the status of Sugar tasks (Total Tasks, Pending, Active, Completed) for each project. It requires the 'sugar' command-line tool to be installed and accessible.

```shell
echo "=== Sugar Status Across All Projects ==="

for project in ~/projects/*; do
  if [ -d "$project/.sugar" ]; then
    echo "📂 Project: $(basename $project)"
    cd "$project"
    sugar status | grep -E "(Total Tasks|Pending|Active|Completed)"
    echo
  fi
done
```

--------------------------------

### Configure Basic Quality Gates

Source: https://github.com/roboticforce/sugar/blob/main/sugar/quality_gates/USER_GUIDE.md

Enables basic quality gates and mandatory testing. This is a starting point for implementing quality checks in a project.

```yaml
quality_gates:
  enabled: true
  mandatory_testing:
    enabled: true
```

--------------------------------

### sugar init

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/cli-reference.md

Initializes Sugar in a project directory, creating necessary configuration and database files.

```APIDOC
## `sugar init`

### Description
Initialize Sugar in a project directory.

### Method
N/A (CLI Command)

### Endpoint
N/A (CLI Command)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Options
- `--project-dir PATH` - Project directory to initialize (default: current directory)

### Request Example
```bash
# Initialize in current directory
sugar init

# Initialize in specific directory
sugar init --project-dir /path/to/my/project
```

### Response
#### Success Response (0)
Creates the following structure:
- `.sugar/` directory with configuration and database
- `.sugar/config.yaml` - project configuration
- `.sugar/sugar.db` - SQLite task database
- `.sugar/logs/` - Sugar-specific logs
- `logs/errors/` - Error log monitoring directory

#### Response Example
(No direct output, but file structure is created.)
```

--------------------------------

### Enable All Sugar Features

Source: https://github.com/roboticforce/sugar/blob/main/sugar/quality_gates/USER_GUIDE.md

Enables pre-flight checks and git diff validation, representing a comprehensive setup of Sugar's quality enforcement features.

```yaml
pre_flight_checks:
  enabled: true
git_diff_validation:
  enabled: true
```

--------------------------------

### Setup Test Environment Configuration

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/configuration-best-practices.md

Configures a dry-run environment with minimal exclusions to validate discovery logic without affecting production source files.

```yaml
sugar:
  dry_run: true
  discovery:
    code_quality:
      enabled: true
      max_files_per_scan: 10
      excluded_dirs: ["venv", ".venv", "node_modules", ".git", "__pycache__", ".sugar"]
    test_coverage:
      enabled: false
```

--------------------------------

### Initialize Sugar in Project

Source: https://github.com/roboticforce/sugar/blob/main/examples/claude-code-plugin/README.md

Initializes Sugar within your project directory. This command sets up Sugar for use in your current project context.

```bash
cd your-project
sugar init
```

--------------------------------

### Define Task Functional Verification

Source: https://github.com/roboticforce/sugar/blob/main/sugar/quality_gates/USER_GUIDE.md

An example of a Python task structure containing functional verification requirements such as HTTP requests and port availability checks.

```python
task = {
    "title": "Fix API endpoint",
    "functional_verifications": [
        {
            "type": "http_request",
            "url": "http://localhost:8000/api/users",
            "method": "GET",
            "expected_status": 200,
            "headers": {
                "Authorization": "Bearer test-token"
            }
        },
        {
            "type": "port_listening",
            "port": 8000,
            "host": "localhost"
        }
    ]
}
```

--------------------------------

### Sugar Integration Scenarios

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/execution-context.md

Configuration examples for running Sugar in solo development, CI/CD pipelines, and team environments.

```yaml
# .github/workflows/autonomous-dev.yml
- name: Run Sugar for maintenance tasks
  run: |
    sugar init
    sugar add "Update dependencies" --type maintenance --priority 2
    sugar run --once
```

--------------------------------

### GitHub Action Workflow Configuration

Source: https://github.com/roboticforce/sugar/blob/main/action/DEPLOYMENT.md

Example YAML configuration for integrating the Sugar Issue Responder into a GitHub Actions workflow.

```yaml
- uses: roboticforce/sugar@v1
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
```

--------------------------------

### Tag and Publish Release via Git

Source: https://github.com/roboticforce/sugar/blob/main/action/DEPLOYMENT.md

Commands to create and push a semantic version tag to a GitHub repository to trigger a release.

```bash
git checkout main
git pull origin main
git tag -a v1.0.0 -m "Release v1.0.0 - Initial GitHub Marketplace release"
git push origin v1.0.0
```

--------------------------------

### Port Listening Functional Verification (Python)

Source: https://github.com/roboticforce/sugar/blob/main/sugar/quality_gates/USER_GUIDE.md

Example of configuring a port listening check for functional verification. It specifies the port and host to verify if a service is running.

```python
"functional_verifications": [
    {
        "type": "port_listening",
        "port": 3000,
        "host": "localhost"
    }
]
```

--------------------------------

### Tips for Using Sugar CLI

Source: https://github.com/roboticforce/sugar/blob/main/docs/user/cli-reference.md

Provides helpful tips and best practices for effectively using the Sugar CLI.

```APIDOC
## Tips

💡 Use `--dry-run --once` to safely test Sugar behavior
💡 Check `.sugar/sugar.log` for detailed execution logs
💡 Tasks are isolated per project - each project needs its own `sugar init`
💡 Use `sugar status` to monitor progress and queue health
💡 Use `sugar learnings` to review execution patterns and recommendations
💡 Specify `--acceptance-criteria` for tasks requiring specific verification
```

--------------------------------

### Write Python Tests with Pytest

Source: https://github.com/roboticforce/sugar/blob/main/docs/dev/testing.md

Examples of writing standard unit tests, async tests, fixtures, and parameterized tests using the pytest framework.

```python
def test_task_creation():
    """Test creating a new task."""
    task = create_task("Test task", type="feature", priority=3)

    assert task.title == "Test task"
    assert task.type == "feature"
    assert task.priority == 3

@pytest.mark.asyncio
async def test_agent_execution():
    from sugar.agent.base import SugarAgent, SugarAgentConfig
    config = SugarAgentConfig(model="claude-sonnet-4-20250514")
    agent = SugarAgent(config)
    await agent.start_session()
    assert agent._session_active is True
    await agent.end_session()
    assert agent._session_active is False

@pytest.fixture
def sample_work_item():
    return {"id": "test-123", "type": "feature", "title": "Test task"}

@pytest.mark.parametrize("priority,expected", [(1, "low"), (3, "medium"), (5, "urgent")])
def test_priority_labels(priority, expected):
    assert get_priority_label(priority) == expected
```

--------------------------------

### OpenCode Setup with Sugar MCP

Source: https://github.com/roboticforce/sugar/blob/main/README.md

This command sets up Sugar's integration with OpenCode, including MCP integration. After running this command, OpenCode needs to be restarted for the changes to take effect. This facilitates bidirectional communication and memory injection.

```bash
sugar opencode setup  # Automatically configures OpenCode
# Then restart OpenCode
```