# Agent Nova — Project Progress Report

**Prepared for:** Client stakeholders  
**Date:** 8 September 2026  
**Project:** Agent Nova — Jira-triggered, human-supervised Salesforce development automation  
**Status:** Phases 0–4 complete. The supervised pipeline runs end-to-end from a Jira story to a **draft GitHub pull request**. Nothing deploys to production.

---

## 1. Executive summary

Agent Nova is a supervised AI platform that turns a qualifying Jira story into Salesforce metadata, validates it against a **sandbox / lower org**, reviews and tests the change, and opens a **draft pull request** for a human to merge.

It does **not** replace Salesforce developers or release managers. It automates the repeatable middle of the work — analysis, design, generation, validate, review, and QA — and **stops** whenever a human must decide.

**Where we are today**

- The full supervised loop is built and covered by automated tests (**53 tests passing**, verified 8 September 2026).
- Two human gates are live: **clarification** (if the story is incomplete) and **design review** (before any metadata is written).
- Live connectors exist for Jira, Confluence, GitHub, Salesforce CLI, PMD, Apex tests, and the LLM — each can run in mock mode for local/CI or live mode when credentials are provided.
- Remaining work is hardening (review escalation, richer generation, CI) and a **joint live run** on your Jira, Confluence, GitHub, and sandbox — not a new core pipeline.

We are ready to walk through a demo and, once credentials are in place, execute the first live client story.

---

## 2. What Agent Nova does for you

| You do | The platform does |
|--------|-------------------|
| Label a Story or Task `agent-nova` (or move it to “Ready for Agent”) | Starts a run; ignores unrelated tickets |
| Answer questions on the Jira ticket if the story is incomplete | Resumes analysis from your comment |
| Review the Confluence design page and comment on Jira to approve (or `reject`) | Implements only the approved, allowlisted plan |
| Review the draft pull request | Code review and QA have already run; the PR is **draft**, not merged |

Unrelated tickets, bot comments, and duplicate webhook deliveries are ignored. Only one active run is allowed per Jira issue.

---

## 3. End-to-end pipeline (as built)

```
Jira webhook
  → Requirement Analyst
      → (if unclear) pause → human comment on Jira → resume
  → Solution Architect → Confluence design page
      → pause for DESIGN REVIEW → human approve / reject
  → Salesforce Developer (SFDX metadata under force-app)
  → Sandbox deploy validate (dry-run; production aliases refused)
  → Code Reviewer + static analysis (auto-fix up to 3 cycles)
  → QA Engineer (acceptance-criteria matrix + Apex tests)
  → Draft GitHub pull request  →  PR_CREATED
```

A failed deploy, unfixable review, or failed QA posts a comment on Jira and marks the run **FAILED**. No pull request is opened.

Every run keeps an audit trail and artifacts (`requirements.json`, `design.json`, `deploy.json`, `review.json`, `qa-report.json`, plus the generated Salesforce files).

---

## 4. Work completed

### Phase 0 — Guardrails and operating rules

Built before any autonomous generation so the agent cannot quietly expand scope.

- **Trigger rules.** Only configured Jira project keys; Story/Task; label `agent-nova` or status “Ready for Agent”; one active run per issue.
- **Metadata allowlist.** The agent may plan and implement only agreed Salesforce types (see section 5). Profiles, sharing-model changes, connected apps, destructive deletes, and production deploys are out of autonomous scope.
- **Access model.** Jira, Confluence, GitHub, sandbox Salesforce, and LLM are all switchable. Secrets stay in environment configuration, not in the repository.
- **Sample evaluation stories.** Clear, incomplete, out-of-scope, and resume-after-clarification cases for judging analyst quality.

### Phase 1 — Platform foundation

- REST API (FastAPI) for Jira webhooks and run status, plus a background worker.
- Orchestrator that moves each ticket through explicit workflow states, with an audit trail.
- Postgres and Redis (Docker Compose) for runs, artifacts, and the job queue.
- Idempotent webhooks (duplicate Jira deliveries are ignored).
- All live systems are **switchable**: mock for local/CI, live via environment settings.

### Phase 2 — Requirement Analyst and Solution Architect

**Requirement Analyst**

- Reads the Jira issue (summary, description, acceptance criteria, comments).
- Pulls relevant Confluence pages (naming, architecture standards) as context.
- If the story is implementable, proceeds. If not, posts numbered questions on Jira and pauses.
- Does not invent acceptance criteria. Prefers reasonable defaults over questions about layouts, record types, or naming style.
- If a human has already answered on the ticket, those answers are treated as locked decisions.
- Live clarification was exercised on Jira issue **AN-6** (thin description → questions posted → human-style reply → design produced).

**Solution Architect and design review**

- Produces a Salesforce metadata plan from the approved requirements.
- Enforces the v1 allowlist: out-of-policy types and destructive actions are stripped; an empty plan fails the run.
- Pauses in **DESIGN REVIEW**. A Jira comment starting with `reject` / `rejected` fails the run; any other human comment **approves** and starts implementation.
- At design review, Agent Nova **creates a Confluence page** (requirements + design) and posts the URL on the Jira ticket.
- Jira comments are formatted for readability (headings, lists, bold labels, clickable links).

### Phase 3 — Salesforce Developer, GitHub, and sandbox validate

**Salesforce Developer** generates Salesforce DX stubs under `force-app` for allowlisted types only (custom fields, validation rules, permission sets, Apex classes and triggers, record-triggered Flows, Lightning Web Components). After a failed code review, it can apply a bounded LLM-driven fix pass.

**GitHub**

- Creates branch `agent-nova/<jira-key>`.
- Commits only Salesforce metadata (`force-app`); internal summaries stay in run artifacts.
- Opens a **draft** pull request (mock GitHub for CI; live GitHub API when configured).

**Salesforce validate**

- Runs a **dry-run** deploy against a named sandbox / DEV org.
- Results are stored as a deploy artifact.
- Production-like org aliases (`prod`, `production`) are refused.
- Deploy failure → run fails, Jira is commented, **no PR**.

### Phase 4 — Code Reviewer and QA

- Static analysis (PMD CLI or mock) merged into review findings.
- Code review against requirements, design, and analysis (security, bulkification, naming, test coverage, design drift).
- **Blocking severities:** critical and high. Medium and low are informational.
- Failed review with fixable findings → automatic fix loop, **maximum 3 cycles**.
- QA builds a test matrix from acceptance criteria and Apex test results.
- Metadata-only changes (fields / rules / permission sets) are not failed solely because no Apex tests ran.
- Review or QA failure blocks the draft PR.

### Quality and robustness (September 2026)

- Webhook comments after approve are ignored so a second Jira event cannot overwrite a successful run.
- LLM outputs that use mixed casing (for example `High` vs `high`) are normalized so runs do not crash.
- Confluence design-doc publisher and formatted Jira comments.
- **53 automated tests passing** (verified 8 September 2026).

---


## 7. Integration status

| System | What is built | Default for CI / local | Live switch |
|--------|----------------|------------------------|-------------|
| Jira | Intake, comments, resume | Mock | Live HTTP provider |
| Confluence | Search + design-page publish | Mock | Live HTTP provider |
| GitHub | Branch, commit, draft PR | Mock | Live GitHub API |
| Salesforce deploy | Sandbox dry-run validate | Mock | Salesforce CLI |
| Apex tests | Run Apex tests on the org | Mock | Salesforce CLI |
| PMD | Violations into review | Mock | PMD CLI |
| LLM | Analyze / design / review / fix / QA | Mock | OpenAI (or agreed provider) |

Live GitHub and sandbox smoke on a **client** story is implemented in code but not yet run jointly — that needs your credentials (section 10).

-