Examples

Real-world usage examples to help you get the most out of Sugar.

Basic Task Management

Adding Simple Tasks

# Add a feature task
sugar add "Implement user authentication" --type feature --priority 4

# Add an urgent bug fix
sugar add "Fix login crash" --type bug_fix --urgent

# Add a test task
sugar add "Add unit tests for payments" --type test --priority 3

# Add with description
sugar add "Refactor API" --type refactor --description "Clean up REST endpoints"

Managing the Queue

# List all tasks
sugar list

# List pending tasks only
sugar list --status pending

# List bug fixes
sugar list --type bug_fix

# View task details
sugar view task-abc123

# Update task priority
sugar priority task-abc123 --urgent

# Remove a task
sugar remove task-abc123

Rich Task Context

For better autonomous execution, provide rich context with your tasks:

JSON File Input

Create a task.json file:

{
  "title": "Implement OAuth2 Authentication",
  "type": "feature",
  "priority": 4,
  "description": "Add OAuth2 authentication system",
  "context": {
    "requirements": [
      "JWT tokens",
      "Refresh token logic",
      "User session management"
    ],
    "technical_requirements": [
      "Use existing auth library",
      "Add database migration for tokens"
    ],
    "success_criteria": [
      "Users can login with OAuth2",
      "Tokens are properly refreshed",
      "All auth tests pass"
    ]
  }
}

Then add it:

sugar add "OAuth2 Auth" --input-file task.json

Inline JSON Description

sugar add "User Dashboard" --json --description '{
  "priority": 5,
  "type": "feature",
  "context": "Complete dashboard redesign",
  "technical_requirements": [
    "React 18 with TypeScript",
    "Responsive design",
    "Real-time data updates"
  ],
  "success_criteria": [
    "Dashboard loads in < 2 seconds",
    "Mobile responsive",
    "Passes accessibility audit"
  ]
}'

Workflow Examples

Solo Developer: Overnight Work

# Before leaving for the day
sugar add "Fix authentication timeout" --type bug_fix --urgent
sugar add "Add user profile page" --type feature --priority 4
sugar add "Write API documentation" --type documentation --priority 3

# Check queue
sugar status

# Start autonomous execution
sugar run

# Next morning - check results
sugar list --status completed

Bug Fixing Sprint

# Add all known bugs
sugar add "Fix memory leak in cache" --type bug_fix --priority 5
sugar add "Handle null pointer in auth" --type bug_fix --priority 4
sugar add "Fix race condition in queue" --type bug_fix --priority 4
sugar add "Correct timezone handling" --type bug_fix --priority 3

# Run single cycle to fix highest priority
sugar run --once

# Check what was fixed
sugar list --status completed --type bug_fix

Test Coverage Improvement

# Add test tasks
sugar add "Add unit tests for User model" --type test --priority 3
sugar add "Add integration tests for API" --type test --priority 3
sugar add "Add e2e tests for checkout" --type test --priority 4

# Run in dry-run first to see plan
sugar run --dry-run --once

# Then execute
sugar run

Configuration Examples

Web Application Setup

# .sugar/config.yaml
sugar:
  dry_run: false
  loop_interval: 300

  discovery:
    error_logs:
      enabled: true
      paths: ["logs/errors/", "logs/exceptions/"]

    code_quality:
      enabled: true
      source_dirs: ["src", "components", "pages"]
      excluded_dirs: [
        "node_modules", ".next", "dist",
        "coverage", "public/uploads"
      ]

    github:
      enabled: true
      repo: "myorg/webapp"
      issue_labels: ["bug", "enhancement", "sugar-task"]

Python Package Setup

# .sugar/config.yaml
sugar:
  dry_run: false
  loop_interval: 600

  discovery:
    code_quality:
      enabled: true
      source_dirs: ["src", "lib"]
      excluded_dirs: [
        "venv", ".venv", "build", "dist",
        "*.egg-info", ".tox", ".nox"
      ]

    test_coverage:
      enabled: true
      source_dirs: ["src"]
      test_dirs: ["tests"]

CI/CD Integration

# In your CI pipeline, create tasks from test failures
if [ $TEST_EXIT_CODE -ne 0 ]; then
  sugar add "Fix failing tests from CI build #$BUILD_NUMBER" \
    --type bug_fix \
    --urgent \
    --description "Tests failed in CI. See build log for details."
fi

Monitoring and Maintenance

Daily Status Check

# Morning routine
sugar status
sugar list --status completed --limit 10
sugar list --status failed

Weekly Review

# See all completed work
sugar list --status completed --limit 50

# Check for stuck tasks
sugar list --status active

# Review failed tasks
sugar list --status failed

Debug Issues

# Enable debug logging
export SUGAR_LOG_LEVEL=DEBUG
sugar run --dry-run --once

# Check logs
tail -f .sugar/sugar.log

# Validate setup
sugar run --validate