Use Cases

Use cases provide concrete, reproducible examples of how Aether processes real-world scenarios from ticket creation through agent execution to verification. They serve multiple purposes:

Purpose

1. End-to-End Testing - Validate the complete webhook → agent → response flow
2. Agent Comparison - Test different agent configurations for cost and accuracy analysis
3. Developer Onboarding - Show new developers how the system works in practice
4. Documentation - Provide concrete examples of platform capabilities
5. CI/CD Integration - Enable automated regression testing

Available Use Cases

Drupal Module Update

Update the Webform module from 6.2.7 to 6.2.8 - a simple, low-risk maintenance task that demonstrates the full agent workflow:

• PM Agent - Initial triage and planning
• TA Agent - Technical discovery and implementation guidance
• QA Agent - Verification and testing checklist

Estimated time: < 5 minutes Complexity: Beginner Purpose: E2E workflow demonstration

Running Use Cases Locally

Prerequisites

1. Aether services running via docker-compose
2. Issue tracker configured (Jira, Plane, or GitHub)
3. LLM service available (LiteLLM with configured model)

Quick Start

# 1. Start services
docker-compose up --build -d

# 2. Seed base configuration
curl -X POST http://localhost:8000/api/agents/seed
curl -X POST http://localhost:8000/api/tasks/seed
curl -X POST http://localhost:8000/api/tasks/triggers/seed
curl -X POST http://localhost:8000/api/tasks/sources/seed

# 3. Setup a specific use-case
curl -X POST http://localhost:8000/api/use-cases/drupal-module-update/setup

# 4. Follow the use-case specific steps
# (See individual use-case documentation)

# 5. Run verification script
./goway/scripts/verify_use_case.sh drupal-module-update

# 6. Cleanup
curl -X POST http://localhost:8000/api/use-cases/drupal-module-update/teardown

Creating New Use Cases

To add a new use-case:

1. Define the use-case YAML in goway/seeding/use_case_<name>.yaml

   • Include project configuration
   • Define issue template structure
   • List verification steps

2. Create documentation in docs-site/use-cases/<name>.md

   • Overview and objectives
   • Prerequisites
   • Step-by-step execution guide
   • Expected agent behaviors
   • Verification procedures

3. Add setup/teardown endpoints in goway/internal/infrastructure/adapter/http/handler/use_case.go

   • Implement Setup<Name> handler
   • Implement Teardown<Name> handler

4. Create verification script in goway/scripts/verify_use_case_<name>.sh

   • Automated checks for each workflow stage
   • Clear success/failure reporting

5. Write integration tests in goway/internal/infrastructure/adapter/http/handler/use_case_test.go

   • Test setup/teardown endpoints
   • Simulate webhook events
   • Verify database state

6. Update navigation in docs-site/.vitepress/config.ts

   • Add to sidebar under /use-cases/

Troubleshooting

Setup Failed

Symptom: Setup endpoint returns 500 error

Solutions:

• Check DATABASE_URL is configured correctly
• Verify agents are seeded: curl http://localhost:8000/api/agents
• Check task mappings: curl http://localhost:8000/api/tasks/triggers
• Review logs: docker-compose logs -f goway

Agent Not Responding

Symptom: No comment appears on the issue after state transition

Solutions:

• Check LiteLLM is running: curl http://localhost:4000/health
• Verify TRACKER_UPDATES_ENABLED=true in goway/.env
• Check NATS connection: docker-compose logs nats
• Review agent audit logs: curl http://localhost:8000/api/agents/{agent_id}/audit-trail

Webhook Not Triggering

Symptom: State transition doesn't trigger agent execution

Solutions:

• Verify webhook mapping exists for your issue tracker
• Check source event mappings: curl http://localhost:8000/api/tasks/sources
• Test webhook manually: curl -X POST http://localhost:8000/api/webhooks/{source} -d @test_payload.json
• Enable debug logging in docker-compose.yml

Verification Script Fails

Symptom: verify_use_case.sh exits with non-zero code

Solutions:

• Check script has execution permissions: chmod +x goway/scripts/verify_use_case.sh
• Verify jq and curl are installed
• Check issue tracker API credentials are valid
• Review script output for specific failure step
• Run with debug mode: DEBUG=1 ./goway/scripts/verify_use_case.sh <name>

Best Practices

Use-Case Design

• Keep execution time under 5 minutes
• Focus on observable, verifiable outcomes
• Use realistic but simple scenarios
• Include both happy path and common error cases
• Document expected agent behaviors at each stage

Seeding

• Make all seeding operations idempotent
• Skip existing entries rather than failing
• Return clear created/skipped counts
• Use consistent YAML schema across use-cases

Verification

• Check both API responses and database state
• Validate issue tracker comments/updates
• Use polling with timeout for async operations
• Provide detailed failure messages
• Exit with meaningful status codes

Documentation

• Include clear prerequisites section
• Provide step-by-step instructions
• Show expected vs actual output examples
• Document common failure scenarios
• Link to related troubleshooting guides

Future Enhancements

Planned improvements to the use-case system:

• Cost Analysis Tool - Compare LLM model costs for same use-case
• Accuracy Metrics - Track agent response quality over time
• Web UI - Interactive use-case execution with real-time progress
• Parameterization - Allow customization (versions, modules, etc.)
• Performance Benchmarks - Track execution time, token usage, API calls
• Use-Case Library - Additional scenarios for different tech stacks

Related Documentation

• Installation Guide - Setting up Aether
• Configuration Guide - Environment variables
• Testing Guide - Writing tests
• Architecture Guide - System design
• API Reference - REST API documentation