# Antigravity Automated Issue-Resolution Workflow

This guide details the automated pipeline for listening to, processing, resolving, and verifying GitHub issues using the Antigravity agentic system.

---

## 1. Workflow Architecture

```mermaid
sequenceDiagram
    participant GH as GitHub Webhook / Action
    participant OR as Orchestrator Agent
    participant IP as Implementation Planner Agent
    participant DEV as Developer Agent
    participant CI as CI Build & Browser Verifier
    
    GH->>OR: Webhook: Issue Labeled ('agent-resolve')
    Note over OR: Parses issue details &<br/>checks config
    OR->>OR: Git Branch Checkout (feature/issue-N)
    OR->>IP: Spawns Planner Agent with prompt
    IP->>IP: Researches codebase & generates plan
    IP-->>OR: Returns plan
    OR->>DEV: Invokes Developer Agent to write code
    DEV->>DEV: Modifies files & implements feature
    DEV-->>OR: Code complete
    OR->>CI: Runs verification (npm run build & test)
    CI-->>OR: Compilation / Test Success
    OR->>GH: Git Commit & Push. Auto-creates Pull Request
    Note over GH: GitHub Action checks pass.<br/>Human reviews & merges PR.
```

---

## 2. Webhook Payload Specifications
When an issue is labeled (e.g. `agent-resolve`, `enhancement`, `bug`), GitHub triggers a webhook with the following JSON structure sent to the Orchestrator endpoint:

```json
{
  "action": "labeled",
  "issue": {
    "number": 12,
    "title": "IMPLEMENT RISK MANAGEMENT UPGRADE: #ISSUE-005 - Kelly Allocation",
    "body": "Detailed objective description...",
    "state": "open",
    "labels": [
      {
        "name": "agent-resolve"
      }
    ]
  },
  "repository": {
    "full_name": "jannr/investment-sandbox",
    "html_url": "https://github.com/jannr/investment-sandbox"
  },
  "sender": {
    "login": "jannr"
  }
}
```

---

## 3. Step-by-Step Execution Lifecycle

### Step 3.1: Parsing and Routing
The Orchestrator Agent parses the webhook payload, maps labels using `github-agent-config.json`, and triggers the workflow.

### Step 3.2: Branching Strategy
The system automatically creates a branch:
- For enhancements: `feature/issue-{issue_number}`
- For bugs: `bugfix/issue-{issue_number}`

### Step 3.3: Planning & Coding
1. The Orchestrator launches an **Implementation Planner Agent** to search the codebase and write an `implementation_plan.md` draft.
2. Once the plan is approved (autonomously or by a maintainer), the **Developer Agent** modifies the target code files.

### Step 3.4: Automated Verification
Before pushing changes, the Orchestrator runs:
- `npm run build` to verify Next.js/TypeScript compilations.
- Virtual browser tests (Playwright/Puppeteer stubs) to simulate UI button interactions, state modifications, and graph renderings.

### Step 3.5: PR Creation and Merge
1. The agent pushes the branch to remote and creates a PR using the GitHub API:
   `POST /repos/{owner}/{repo}/pulls`
2. Once merged by a human, the branch is deleted and the issue is closed.