Drupal Module Update Use Case

A complete end-to-end demonstration of Aether's agent workflow using a realistic but simple Drupal maintenance task: updating the Webform module from version 6.2.7 to 6.2.8.

Overview

This use-case demonstrates:

Ticket Creation - Jira issue with security update requirements
PM Triage - Project Manager agent provides initial assessment
Technical Discovery - Technical Architect analyzes the update
QA Verification - QA agent validates completion criteria

Estimated Duration: 3-5 minutes (excluding LLM response time) Complexity Level: Beginner Prerequisites: Basic Docker and curl knowledge

Objectives

Validate the complete webhook → PM → TA → QA flow
Demonstrate agent collaboration on a maintenance task
Provide a reproducible example for testing and onboarding
Establish baseline for agent comparison and optimization

Prerequisites

Required Services

Docker and docker-compose installed
Aether backend running (docker-compose up)
PostgreSQL database with migrations applied
NATS message broker running
LiteLLM proxy configured with a model (e.g., ollama/phi4)

Issue Tracker Configuration

Choose one:

Jira (Cloud or Server) - Recommended for this use-case
Plane - Alternative project management tool
GitHub Issues - Simplified workflow

Required environment variables in goway/.env:

bash

# Jira Cloud
JIRA_URL=https://yourcompany.atlassian.net
JIRA_EMAIL=user@example.com
JIRA_API_TOKEN=your-api-token
JIRA_IS_CLOUD=true

# Or Jira Server
JIRA_URL=https://jira.yourcompany.com
JIRA_EMAIL=username
JIRA_API_TOKEN=password
JIRA_IS_CLOUD=false

# Enable tracker updates
TRACKER_UPDATES_ENABLED=true

Seeded Configuration

Ensure base configuration is loaded:

bash

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
curl -X POST http://localhost:8000/api/webhook-mappings/seed

Setup

Automated Setup

Use the API endpoint to create the test project and prepare the environment:

bash

curl -X POST http://localhost:8000/api/use-cases/drupal-module-update/setup \
  -H "Content-Type: application/json" | jq

Expected Response:

json

{
  "status": "success",
  "project": {
    "project_id": "test_project_drupal",
    "name": "Test Drupal Site",
    "id": 123
  },
  "agents_verified": [
    "pm_sarah",
    "ta_leo",
    "qa_quinn"
  ],
  "jira_issue": {
    "key": "PROJ-456",
    "url": "https://yourcompany.atlassian.net/browse/PROJ-456"
  },
  "next_steps": [
    "Open the Jira issue in your browser",
    "Observe PM agent comment (automatic)",
    "Move issue to 'Discovery' state",
    "Observe TA agent comment",
    "Move issue to 'Done' state",
    "Observe QA agent comment"
  ]
}

Manual Setup (Alternative)

If you prefer to create the issue manually:

Create Jira Issue:
- Project: Your test project
- Issue Type: Task
- Summary: [TEST] Update Webform module to 6.2.8
- Labels: test-use-case, drupal, module-update
Set Description:

markdown

## Context
The Webform module needs to be updated from version 6.2.7 to 6.2.8 to address security fixes.

## Requirements
- Update Webform module via Composer
- Run database updates
- Verify no breaking changes
- Test existing webforms still function

## Acceptance Criteria
- Webform module updated to 6.2.8
- All existing webforms functional
- No PHP errors or warnings
- Regression tests pass

Execution Workflow

Stage 1: PM Agent Triage (Automatic)

Trigger: Issue created in "To Do" or "Open" state

Expected Behavior:

PM agent (Sarah) automatically analyzes the ticket
Posts initial triage comment within 30-60 seconds
Identifies this as a maintenance task
Assesses complexity and risk

Example PM Comment:

markdown

## Initial Triage

### Task Classification
- **Type:** Maintenance - Security Update
- **Complexity:** Low
- **Risk Level:** Low (minor version update)
- **Priority:** Medium (security-related)

### Quick Assessment
This is a straightforward module update task. Webform 6.2.8 includes security fixes
and should be a drop-in replacement for 6.2.7. The update process is standard:

1. Update via Composer
2. Run database updates
3. Regression test existing forms

### Recommendation
Move to Discovery for TA to verify compatibility and provide implementation steps.

### Dependencies
- Access to production Composer
- Database backup before update
- Test environment for validation

---
*PM Agent: pm_sarah*

Verification:

bash

# Check if PM comment was added
curl "https://yourcompany.atlassian.net/rest/api/2/issue/PROJ-456/comment" \
  -u "user@example.com:$JIRA_API_TOKEN" | jq '.comments[-1].body'

Stage 2: TA Agent Discovery

Trigger: Issue moved to "Discovery" or "In Progress" state

Expected Behavior:

TA agent (Leo) performs technical analysis
Reviews Webform changelog and compatibility
Provides detailed implementation steps
Estimates effort and identifies risks

Example TA Comment:

markdown

## Technical Analysis

### Version Compatibility
- **Current:** Webform 6.2.7
- **Target:** Webform 6.2.8
- **Change Type:** Security patch release
- **Breaking Changes:** None identified

### Implementation Steps

1. **Pre-Update Checks**
   ```bash
   # Backup database
   drush sql:dump > backup-$(date +%Y%m%d).sql

   # Review current status
   drush pml | grep webform
   composer show drupal/webform

Update Module
bash
```
composer update drupal/webform
```
Run Database Updates
bash
```
drush updatedb -y
drush cr
```

Verification

bash

# Verify version
drush pml | grep webform

# Check for errors
drush watchdog:show --severity=Error --count=10

Testing Checklist

[ ] Webform admin UI loads without errors
[ ] Existing webforms display correctly
[ ] Form submissions work (test 2-3 forms)
[ ] Email handlers trigger correctly
[ ] Conditional logic functions as expected

Effort Estimate

Implementation: 15 minutes
Testing: 30 minutes
Total: 45 minutes

Risk Assessment

Low Risk: Minor version security patch
Rollback: Restore database backup and revert composer.json

TA Agent: ta_leo


**Verification:**
```bash
# Check TA comment
curl "https://yourcompany.atlassian.net/rest/api/2/issue/PROJ-456/comment" \
  -u "user@example.com:$JIRA_API_TOKEN" | jq '.comments[-1].body'

Stage 3: QA Agent Verification

Trigger: Issue moved to "Done" or "Closed" state

Expected Behavior:

QA agent (Quinn) reviews completion
Generates testing checklist
Validates acceptance criteria
Confirms documentation

Example QA Comment:

markdown

## QA Verification

### Acceptance Criteria Review
✓ **Webform module updated to 6.2.8** - Verified via composer.json and Drupal status
✓ **All existing webforms functional** - Manual testing completed
✓ **No PHP errors or warnings** - Watchdog log clean
✓ **Regression tests pass** - Test suite executed successfully

### Test Results

**Module Version Verification:**
```bash
$ drush pml | grep webform
Webform (webform)                                        Enabled   8.x-6.2.8

Functional Tests:

✓ Contact form - submission successful
✓ Registration form - email handler triggered
✓ Survey form - conditional logic working
✓ File upload form - attachments processed

Error Check:

bash

$ drush watchdog:show --severity=Error --count=10
No errors found.

Test Coverage

Unit Tests: N/A (module update)
Integration Tests: Webform CRUD operations
Regression Tests: Existing form functionality
Security Tests: Dependency scan clean

Sign-Off

All acceptance criteria met. Module successfully updated to 6.2.8 with no issues identified.

Documentation

[ ] Update CHANGELOG.md
[ ] Update composer.lock in repository
[ ] Note in deployment log

QA Agent: qa_quinn


**Verification:**
```bash
# Check QA comment
curl "https://yourcompany.atlassian.net/rest/api/2/issue/PROJ-456/comment" \
  -u "user@example.com:$JIRA_API_TOKEN" | jq '.comments[-1].body'

Automated Verification

Use the provided script for automated verification:

bash

./goway/scripts/verify_use_case.sh drupal-module-update

Script checks:

✓ Jira issue exists and accessible
✓ PM comment added after creation
✓ TA comment added after Discovery transition
✓ QA comment added after Done transition
✓ All comments contain expected keywords
✓ Issue workflow progressed correctly

Exit Codes:

0 - All verifications passed
1 - Setup failure (issue not found, auth failed)
2 - PM agent verification failed
3 - TA agent verification failed
4 - QA agent verification failed

Cleanup

Remove test data after verification:

bash

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

Cleanup actions:

Deletes test project from database
Optionally closes Jira issue (if configured)
Preserves agent and task configurations

Troubleshooting

PM Agent Not Commenting

Symptoms:

Jira issue created but no PM comment appears

Diagnosis:

bash

# Check webhook delivery
docker-compose logs goway | grep "webhook.*PROJ-456"

# Check task resolution
curl "http://localhost:8000/api/tasks/resolve?source=jira&event=issue&action=created"

# Check agent audit trail
curl "http://localhost:8000/api/agents/pm_sarah/audit-trail" | jq

Solutions:

Verify webhook mapping exists for Jira issue creation
Check source event mapping: jira.issue.created → ticket.created
Ensure PM task mapped to ticket.created trigger
Verify TRACKER_UPDATES_ENABLED=true
Check LiteLLM service is responding

TA Comment Missing After Discovery

Symptoms:

Moved to Discovery but TA doesn't comment

Diagnosis:

bash

# Check state transition webhook
docker-compose logs goway | grep "state.*change"

# Verify workflow configuration
curl "http://localhost:8000/api/projects/123/workflow-context" | jq

Solutions:

Ensure Discovery state exists in workflow
Check source event mapping for state changes
Verify TA task mapped to discovery trigger
Check NATS event publishing: docker-compose logs nats

QA Verification Delayed

Symptoms:

Issue marked Done but QA comment takes > 2 minutes

Diagnosis:

bash

# Check LLM response time
curl "http://localhost:4000/health"

# Check pending tasks
curl "http://localhost:8000/api/nats/events/pending" | jq

Solutions:

LLM may be slow - wait up to 5 minutes
Check LiteLLM logs for errors
Verify model is loaded: docker-compose logs litellm
Consider using faster model (e.g., haiku vs opus)

Variations & Extensions

Test Different Agents

Compare agent configurations:

bash

# Use different PM agent
curl -X POST http://localhost:8000/api/use-cases/drupal-module-update/setup \
  -H "Content-Type: application/json" \
  -d '{"pm_agent_id": "pm_alternate"}'

Add Custom Context

Provide additional context to agents:

bash

curl -X POST http://localhost:8000/api/use-cases/drupal-module-update/setup \
  -H "Content-Type: application/json" \
  -d '{
    "project_context": {
      "tech_stack": "Drupal 10 + PostgreSQL",
      "deployment": "Platform.sh",
      "team_size": "5"
    }
  }'

Simulate Errors

Test agent error handling:

Missing Dependency: Update description to mention missing webform_ui module
Version Conflict: Request incompatible version (e.g., 7.x branch)
Test Failure: Add requirement for passing specific test that doesn't exist

Cost Analysis

Track LLM costs for different models:

bash

# Run with GPT-4
LLM_MODEL=gpt-4 docker-compose up -d goway
./goway/scripts/verify_use_case.sh drupal-module-update

# Run with Claude
LLM_MODEL=claude-3-sonnet docker-compose up -d goway
./goway/scripts/verify_use_case.sh drupal-module-update

# Compare token usage
curl "http://localhost:8000/api/agents/pm_sarah/usage-stats" | jq

Learning Outcomes

After completing this use-case, you should understand:

Webhook Flow - How external events trigger agent execution
Task Resolution - How canonical triggers map to agent tasks
Agent Collaboration - How PM → TA → QA workflow operates
Context Passing - How agents receive issue details
Response Routing - How agent outputs return to issue tracker
Verification - How to validate agent behavior

Next Steps

Try the GitHub Actions Workflow use-case
Read Agent Development Guide
Explore Adding Custom Tasks
Learn about Agent Memory

Workflow Guide - Internal workflow details
Task Configuration - Task setup guide
Issue Tracker Integration - Adding trackers
Testing Guide - Writing tests

Drupal Module Update Use Case ​

Overview ​

Objectives ​

Prerequisites ​

Required Services ​

Issue Tracker Configuration ​

Seeded Configuration ​

Setup ​

Automated Setup ​

Manual Setup (Alternative) ​

Execution Workflow ​

Stage 1: PM Agent Triage (Automatic) ​

Stage 2: TA Agent Discovery ​

Testing Checklist ​

Effort Estimate ​

Risk Assessment ​

Stage 3: QA Agent Verification ​

Test Coverage ​

Sign-Off ​

Documentation ​

Automated Verification ​

Cleanup ​

Troubleshooting ​

PM Agent Not Commenting ​

TA Comment Missing After Discovery ​

QA Verification Delayed ​

Variations & Extensions ​

Test Different Agents ​

Add Custom Context ​

Simulate Errors ​

Cost Analysis ​

Learning Outcomes ​

Next Steps ​

Related Documentation ​

Drupal Module Update Use Case

Overview

Objectives

Prerequisites

Required Services

Issue Tracker Configuration

Seeded Configuration

Setup

Automated Setup

Manual Setup (Alternative)

Execution Workflow

Stage 1: PM Agent Triage (Automatic)

Stage 2: TA Agent Discovery

Testing Checklist

Effort Estimate

Risk Assessment

Stage 3: QA Agent Verification

Test Coverage

Sign-Off

Documentation

Automated Verification

Cleanup

Troubleshooting

PM Agent Not Commenting

TA Comment Missing After Discovery

QA Verification Delayed

Variations & Extensions

Test Different Agents

Add Custom Context

Simulate Errors

Cost Analysis

Learning Outcomes

Next Steps

Related Documentation