Obligation Team

---
name: obligation-team
description: >
  Spawn a team of agents to write per-obligation behavioral tests in parallel.
  Each agent researches, writes, runs, and fixes their test independently.
  Leader consolidates verified tests, runs quality gates, and commits.
arguments:
  - name: obligations
    description: >
      Obligation IDs or prefix with --count. Examples:
      UC-004 --count 10
      UC-004-ALT-WEBHOOK-PUSH-REPORTING-03 UC-004-ALT-WEBHOOK-PUSH-REPORTING-04
    required: true
---

# Team-Based Obligation Test Generation: $ARGUMENTS

Spawn one agent per obligation. Each agent researches production code, writes a
test to a temp file, runs it, fixes it until green, and reports back verified
working code. Leader consolidates into the final test file and commits.

## Architecture

- **Agents**: Research + write temp test file + run pytest + fix until green (parallel)
- **Team lead**: Consolidates verified tests into final file, quality gates, commit

Agents are full team members with shell access. They each write to their own
temp file (`tests/unit/_tmp_test_{OID_SUFFIX}.py`) so there are no conflicts.
The leader appends verified code to the shared test file after all agents report.

## Protocol

### Step 0: Resolve obligation IDs

Parse `$ARGUMENTS` to extract obligation IDs.

**If prefix mode** (args look like `UC-004 --count 10` — no trailing sequence number):

```bash
python3 -c "
import json
al = json.loads(open('tests/unit/obligation_coverage_allowlist.json').read())
prefix = '$PREFIX'
matches = sorted(oid for oid in al if oid.startswith(prefix))
count = $COUNT  # default 10 if --count not specified
selected = matches[:count]
print('Selected obligations:')
for oid in selected:
    print(f'  {oid}')
print(f'Total matching: {len(matches)}, selected: {len(selected)}')
"

If direct IDs (args are full obligation IDs separated by spaces): Verify each ID exists in docs/test-obligations/ or the allowlist.

Store the resolved list as OBLIGATION_IDS.

Step 1: Gather shared context

Read these once — they'll be included in every agent's prompt:

1. Test file header (imports + helpers):

   # Identify the test file from the use case prefix
   # UC-004 → tests/unit/test_delivery_behavioral.py
   head -110 tests/unit/test_delivery_behavioral.py
   

2. Obligation scenarios for all resolved IDs:

   for OID in $OBLIGATION_IDS; do
     grep -A 30 "$OID" docs/test-obligations/*.md
   done
   

3. Production files to read (list for the agent prompt):

   • src/core/tools/media_buy_delivery.py
   • src/core/schemas/delivery.py
   • src/core/webhook_delivery.py
   • src/core/webhook_authenticator.py

Step 2: Create team

TeamCreate:
  team_name: "ob-{prefix}-{timestamp}"
  description: "Obligation tests: {N} obligations from {prefix}"

Step 3: Create tasks (one per obligation)

For each OID in OBLIGATION_IDS:

TaskCreate:
  subject: "Research + write + verify test for {OID}"
  description: "Agent researches obligation, writes test, runs it, fixes until green"
  activeForm: "Building test for {OID}"

Step 4: Spawn N agents (parallel, single message)

Launch ALL agents simultaneously using Agent tool calls in one message. Each agent is subagent_type: "general-purpose" with model: "opus".

MANDATORY: model must be "opus" — do not use sonnet or haiku for team agents.

---

BEGIN AGENT PROMPT TEMPLATE (substitute {OID}, {OID_SUFFIX}, {SCENARIO}, {TEST_HEADER}, {TARGET_TEST_FILE}):

You are writing ONE behavioral test for obligation {OID}.
You have full shell access. You will research, write, run, and fix your test
until it passes before reporting back.

## Obligation Scenario

{SCENARIO — exact Given/When/Then from docs/test-obligations/}

## Production Code

Read these files and trace the behavior described in the obligation:
- src/core/tools/media_buy_delivery.py (start at _get_media_buy_delivery_impl)
- src/core/schemas/delivery.py
- src/core/webhook_delivery.py
- src/core/webhook_authenticator.py

Find the SPECIFIC LINES that implement (or would implement) the Given/When/Then.

## Existing Test Context

Your test will eventually be appended to {TARGET_TEST_FILE}.
Here are the imports and helpers already available in that file
(DO NOT redefine these in your final test class):

{TEST_HEADER — first ~110 lines of the test file}

## Your Workflow

### Phase 1: Research
1. Read the production code files listed above
2. Trace the exact code path for this obligation's Given/When/Then
3. Identify: which function to call, what to mock, what to assert

### Phase 2: Write temp test file
Write your test to a TEMPORARY file:

tests/unit/tmp_test{OID_SUFFIX}.py

This temp file MUST be self-contained — copy the necessary imports and helpers
from the test header into it so pytest can run it standalone. Include:
- All imports from the test header that your test needs
- The helper functions (_make_identity, _make_buy, _make_adapter_response, _PATCH)
- Your test class

### Phase 3: Run and fix
```bash
uv run pytest tests/unit/_tmp_test_{OID_SUFFIX}.py -x -v

If the test fails:

• ImportError/NameError/TypeError: Fix the test code (wrong types, wrong method, etc.)
• AssertionError where your assertion is correct per the obligation scenario: This means production doesn't implement the designed behavior. Mark @pytest.mark.xfail with a reason describing WHAT is missing and WHERE it would go.
• AssertionError where your assumption was wrong: Fix the test to match actual production behavior. Re-read the production code more carefully.

Iterate until the test PASSES or is correctly marked XFAIL.

Phase 4: Clean up temp file

rm tests/unit/_tmp_test_{OID_SUFFIX}.py

Phase 5: Answer Right Questions and report

6 Hard Rules

Your test MUST satisfy ALL of these:

#	Rule	Check
1	MUST import from src.	Has from src. impor
```