AGENTS.md — WAIGenie AI Agent Documentation

This file documents all 5 Agno-powered agents in the WAIGenie framework. Each agent has a dedicated service, prompt file, and Pydantic output model.

Agent Overview

┌─────────────────────────────────────────────────────────┐
│                    QA Master Orchestrator               │
│              (Agno Team — coordinate mode)              │
│                     orchestrator.py                     │
└─────────┬──────────────┬───────────────┬───────────────┘
          │              │               │
    ┌─────▼──────┐  ┌────▼──────┐  ┌────▼──────────┐
    │ StoryForge │  │ TestCraft │  │  GherkinGen   │
    │  (story)   │  │  (tests)  │  │  (gherkin)    │
    └────────────┘  └─────┬─────┘  └──────┬────────┘
                          │               │
                    ┌─────▼───────────────▼──────┐
                    │      Agno Workflow 2.0      │
                    │   (parallel TestCraft +     │
                    │      GherkinGen)            │
                    └─────────────┬───────────────┘
                                  │
                    ┌─────────────▼───────────────┐
                    │       BrowserAgent          │
                    │   (Playwright/CDP/CDP)      │
                    └─────────────┬───────────────┘
                                  │
                    ┌─────────────▼───────────────┐
                    │        CodeSmith            │
                    │  (Selenium/Playwright/      │
                    │       Cypress code)         │
                    └─────────────────────────────┘

Agent 1: StoryForge

Purpose: Enhance raw user stories into structured, testable specifications.

Output fields:

• title, as_a, i_want, so_that, elaboration
• acceptance_criteria: List[str]
• implementation_notes: List[str]
• testability_considerations: List[str]
• related_stories: List[str]

Agent 2: TestCraft

Purpose: Convert enhanced user stories into comprehensive manual test cases.

Output fields (TestCase):

• id, title, description, pre_conditions
• steps: List[str], expected_results: List[str]
• test_data, priority, test_type, status
• post_conditions, environment, automation_status
• Traceability: user_story_id, acceptance_criterion_ref, tags: List[str], severity

Coverage requirements per acceptance criterion: Happy path, negative, boundary min/max, boundary violation, empty/null, special chars, concurrent/state.

Agent 3: GherkinGen

Purpose: Convert manual test cases into executable Gherkin .feature scenarios.

Output fields (GherkinScenario):

• title, feature, background, entry_point_url
• tags: List[str]
• given: List[str] — precondition steps (MUST start with real URL)
• when: List[str] — action steps (one user action = one scenario)
• then: List[str] — DOM-assertable outcome steps
• and_steps: List[str] (alias: and), but: str

Critical schema rule: given/when/then are ALWAYS List[str], never bare strings.

Agent 4: BrowserAgent

Purpose: Execute Gherkin scenarios against a live browser using Playwright + CDP.

Output fields (BrowserExecutionResult):

• results: List[ScenarioResult]
• total_scenarios, passed, failed, raw_response

Execution modes:

• Parallel execution (default) via MCP service job queue
• CDP attach mode: connect to existing Chrome via cdp_port
• Vision mode: screenshot-based element detection

Agent 5: CodeSmith

Purpose: Generate production-ready automation code from Gherkin + browser execution history.

Output fields:

• framework (Selenium/Playwright/Cypress)
• language, code, file_name
• imports: List[str], notes

Supported frameworks: Selenium (Python), Playwright (Python/JS), Cypress (JS)

Orchestration Layer

QA Pipeline (sequential, 5-stage)

• File: backend/app/services/pipeline_service.py
• Route: POST /api/v1/pipeline/start
• Returns: task_id — poll GET /api/v1/pipeline/status/{task_id} for progress

Agno Workflow 2.0 (parallel TestCraft + GherkinGen)

• File: backend/app/workflows/qa_pipeline.py
• Route: POST /api/v1/pipeline/workflow
• Runs TestCraft and GherkinGen in parallel, then sequential browser + code stages

QA Master Orchestrator (Team coordinate mode)

• File: backend/app/agents/orchestrator.py
• Route: POST /api/v1/pipeline/orchestrate
• Uses Agno Team with a coordinator agent routing tasks to sub-agents

Adding a New Agent

1. backend/app/agents/<name>_agent.py — create_<name>_agent() factory
2. backend/app/prompts/<name>_agent_instructions.md — instructions loaded at runtime
3. backend/app/models/agent_outputs.py — Pydantic output model
4. backend/app/services/<name>_service.py — business logic
5. backend/app/api/v1/<name>.py — FastAPI route with Depends(verify_api_key)
6. Wire into pipeline_service.py if it belongs in the main pipeline