# Agent Nova — Complete Client Guide

**Audience:** Non-technical stakeholders and business owners  
**Purpose:** Explain what Agent Nova is, how it works step by step, and what every important term means  
**Date:** 15 September 2026  

---

## 1. What is Agent Nova? (in plain language)

**Agent Nova** is a supervised AI assistant for Salesforce work.

When your team creates a Jira ticket (a work request) and marks it for Agent Nova, the system:

1. Reads the request  
2. Checks for problems (missing details, duplicate tickets, or features that already exist)  
3. Proposes a technical design  
4. Waits for a human to approve that design  
5. Builds the Salesforce change  
6. Checks that the change is safe and correct  
7. Opens a **draft** code review package for a human to merge  

**Important:** Agent Nova does **not** replace your Salesforce developers or release managers. It speeds up the middle of the work and **stops whenever a person must decide**.

It also does **not** deploy anything to production by itself.

---

## 2. How the project works (big picture)

Think of Agent Nova like a careful junior team member who:

- Only starts when you invite it  
- Asks questions when the request is unclear  
- Shows you a plan before building anything  
- Builds only what you approved  
- Double-checks its own work  
- Hands you a draft for final review  

### Simple journey

```
You create a Jira ticket and invite Agent Nova
        ↓
Agent Nova starts (ticket usually moves to “In Progress”)
        ↓
Safety checks (duplicate ticket? already in Confluence?)
        ↓
If the story is unclear → asks questions on Jira → you answer
        ↓
Creates a design document + posts a plan on Jira
        ↓
You approve or reject the design
        ↓
If approved → builds Salesforce files
        ↓
Validates in a sandbox (safe test environment)
        ↓
Code review + automated quality checks
        ↓
QA checks against your acceptance criteria
        ↓
Opens a draft Pull Request on GitHub for humans to merge
```

If something fails along the way, Agent Nova comments on the Jira ticket and stops. It does **not** open a pull request after a failed check.

---

## 3. How you invite Agent Nova to work on a ticket

Agent Nova only starts when **all** of these are true:

| Rule | Meaning in plain English |
|------|---------------------------|
| Right Jira project | The ticket is in a project you configured (for example `AN`) |
| Right ticket type | Usually a **Story** or **Task** |
| Invitation signal | The ticket has the label **`agent-nova`**, **or** status **Ready for Agent** |
| Not already busy | There is no other active Agent Nova run on that same ticket |

When it starts, it typically:

- Moves the Jira status toward **In Progress** (so the board shows work has begun)  
- Mentions the **assignee** in comments (so the right person gets notified)  

---

## 4. The full workflow (each stage explained)

### Stage A — Start / intake

Agent Nova receives a signal from Jira that a ticket is ready.

**What you see:** Ticket activity begins; often status becomes **In Progress**.

---

### Stage B — Duplicate ticket check

Before deep work, Agent Nova looks for similar existing Jira tickets.

**If it thinks this is a duplicate:**

- It comments on the new ticket  
- Names the **original / main ticket ID** (example: `AN-46`)  
- Pauses and waits for you  

**Your reply options:**

| You write | What happens |
|-----------|--------------|
| `continue` | Treat it as a new request and keep going |
| `duplicate` or `close as duplicate` | Stop this run |

---

### Stage C — Confluence documentation check

Agent Nova searches your **Confluence** project documentation.

**If it thinks the feature already exists / is already documented:**

- It comments with links to the relevant Confluence pages  
- Pauses and waits for you  

**Your reply options:**

| You write | What happens |
|-----------|--------------|
| `continue` | Proceed anyway (maybe you want a change or extension) |
| `already done` or `close` | Stop this run |

---

### Stage D — Requirement analysis (understanding the ask)

Agent Nova reads:

- Ticket title and description  
- Acceptance criteria (the “definition of done”)  
- Comments  
- Helpful Confluence context (standards, naming, architecture notes)  

**If the request is clear:** it continues.  
**If the request is incomplete:** it posts numbered questions and pauses.

**Your job:** answer in a Jira comment. Agent Nova resumes from your answers.

---

### Stage E — Solution design (the plan)

Agent Nova creates a technical design, including:

- A **metadata plan** (what Salesforce pieces to create/change)  
- Approach (how it intends to solve the request)  
- **Risks / escalations** (things that need human judgment or are out of policy)  

It usually:

1. Publishes a **Confluence design document**  
2. Posts a design-review comment on Jira with a summary  

Then it **pauses for design approval**.

**Your reply options:**

| You write | What happens |
|-----------|--------------|
| Any normal approval comment (for example `approve`, `looks good`) | Start building |
| `reject` or `rejected` (optionally with a short reason) | Agent Nova asks what should change; after you clarify, it creates a **new** design and asks again |

Nothing Salesforce-related is written until design is approved.

---

### Stage F — Implementation (building)

After approval, Agent Nova generates Salesforce project files (fields, rules, Apex, Flows, LWCs, permission sets — only within the agreed allowlist).

---

### Stage G — Deploy validate (safe test deploy)

Agent Nova tries a **dry-run deploy** into a **sandbox** (a non-production Salesforce org).

- This checks whether the change *would* install cleanly  
- It does **not** push to production  
- If validate fails → run stops; no pull request  

---

### Stage H — Code review

Agent Nova reviews the generated change for quality and risk (security, bulk safety, naming, mismatch with the approved plan, etc.).

- Serious issues can trigger automatic fix attempts (limited number of tries)  
- If it still cannot pass → run stops; no pull request  

---

### Stage I — QA (quality assurance)

Agent Nova checks the work against your **acceptance criteria** and related tests (including Apex tests when relevant).

- If QA fails → run stops; no pull request  

---

### Stage J — Draft Pull Request (hand-off to humans)

If everything passed, Agent Nova:

1. Creates a **branch**  
2. Commits the Salesforce files  
3. Opens a **draft Pull Request (PR)** on GitHub  

A human then reviews and merges when ready.

---

## 5. Glossary — what each term means

### Everyday business terms

| Term | Meaning |
|------|---------|
| **Jira ticket / issue** | A work item (Story/Task) describing what you want built |
| **Assignee** | The person responsible for the ticket; Agent Nova @mentions them in comments |
| **Label `agent-nova`** | The invitation tag that tells Agent Nova to start |
| **Status (To Do / In Progress / Done)** | Where the ticket sits on your Jira board |
| **Acceptance criteria** | Clear “done means…” checklist for the request |
| **Run** | One Agent Nova execution for one ticket, from start to finish (or stop) |
| **Comment** | A message on the Jira ticket; used for questions, approvals, and decisions |
| **Confluence** | Your company wiki / documentation space |
| **Sandbox** | A safe Salesforce test org (not production customers) |
| **Allowlist** | The list of Salesforce change types Agent Nova is allowed to create by itself |

---

### Design & planning terms

| Term | Meaning |
|------|---------|
| **Metadata plan** | The shopping list of Salesforce pieces Agent Nova intends to create or change (for example: a custom field, a validation rule, a permission set). You approve this before build. |
| **Approach** | Short explanation of *how* Agent Nova proposes to solve the ticket |
| **Risks / escalations** | Warnings such as “this touches something outside policy” or “a human should decide.” These are flags for people, not automatic green lights. |
| **Out of allowlist** | Requested work that Agent Nova is **not** allowed to do alone (example: production deploy, profile edits, destructive deletes) |
| **Design review** | The pause where a human approves or rejects the plan |
| **Clarification** | The pause where Agent Nova asks questions because the ticket is incomplete |
| **Duplicate review** | The pause when a ticket looks like another existing ticket |
| **Doc review** | The pause when Confluence suggests the feature already exists |

---

### Build & delivery terms

| Term | Meaning |
|------|---------|
| **Branch** | A separate line of code changes for this ticket (usually named like `agent-nova/an-45`). It keeps work isolated until someone merges it. |
| **Commit** | A saved snapshot of the generated files on that branch |
| **Pull Request (PR)** | A formal request to merge the branch into the main codebase after human review. Agent Nova opens it as a **draft** (not finished / not auto-merged). |
| **Draft PR** | A PR marked “not ready to merge yet” — humans still own the final merge decision |
| **Deploy validate** | A practice deploy (dry-run) to a sandbox to prove the package installs cleanly, without changing production |
| **Code review** | Automated quality/security review of the generated change |
| **QA** | Checks that the change meets acceptance criteria and related tests |
| **Apex** | Salesforce’s programming language for advanced business logic |
| **Apex tests** | Automated tests that prove Apex logic behaves correctly |
| **Static analysis / PMD** | Automated scanners that catch common coding problems |
| **Force-app / Salesforce metadata** | The actual Salesforce configuration and code files Agent Nova generates |
| **Custom field** | A new data field on a Salesforce object (example: `Customer_Tier__c` on Account) |
| **Validation rule** | A Salesforce rule that blocks bad data (example: Gold tier requires high revenue) |
| **Permission set** | Access rights package that grants users permission to see/edit certain fields |
| **Flow** | Salesforce automation (Agent Nova focuses on record-triggered Flows in v1) |
| **LWC (Lightning Web Component)** | A Salesforce UI component |
| **Artifacts** | Saved records of what happened in a run (requirements, design, review, QA results). Useful for audit and debugging. |
| **Audit trail** | Timestamped log of major events in a run (started analysis, posted design, failed QA, etc.) |

---

## 6. What Agent Nova is allowed to build (and what it is not)

### Allowed (typical v1 scope)

- Custom fields  
- Validation rules  
- Permission sets  
- Apex classes and triggers (with safe patterns)  
- Record-triggered Flows  
- Lightning Web Components  

### Not allowed without human escalation

- Production deployment  
- Profile changes  
- Sharing / org-wide default redesigns  
- Connected apps / auth providers  
- Destructive deletes (removing existing metadata) unless a human explicitly approves  

This keep Agent Nova useful **and** safe.

---

## 7. Human decision points (your control panel)

| Moment | Why it pauses | What you do |
|--------|----------------|-------------|
| Duplicate found | Avoid double work | `continue` or `close as duplicate` |
| Already in Confluence | Avoid rebuilding existing features | `continue` or `already done` / `close` |
| Story unclear | Need missing business detail | Answer the questions in a comment |
| Design ready | Approve the plan before code is written | Approve, or `reject` + explain changes |
| Draft PR open | Final human ownership of merge | Review and merge (or request changes) |

Agent Nova comments are written to notify the **assignee** when one is set.

---

## 8. What success looks like

A successful run typically ends with:

1. A clear design document in Confluence  
2. Generated Salesforce files on a dedicated branch  
3. Evidence that sandbox validate, review, and QA passed  
4. A **draft GitHub Pull Request** linked on the Jira ticket  

Your team’s final step is always human: review and merge.

---

## 9. What failure looks like (and why that is good)

If deploy validate, review, or QA fails, Agent Nova:

- Posts an explanation on Jira  
- Marks the run as failed  
- Does **not** open a PR  

That is intentional. It prefers stopping over shipping a risky draft.

---

## 10. Roles inside Agent Nova (the “team”)

These are software skills, not separate people — but thinking of them as roles helps:

| Role | Job |
|------|-----|
| **Requirement Analyst** | Understands the Jira ask; asks clarifying questions if needed |
| **Solution Architect** | Creates the metadata plan and design document |
| **Salesforce Developer** | Generates the Salesforce files from the approved plan |
| **Code Reviewer** | Checks quality/security and can request limited auto-fixes |
| **QA Engineer** | Checks acceptance criteria and test results |
| **Orchestrator** | The “project manager” that moves the ticket through stages and enforces pauses |

---

## 11. Systems Agent Nova connects to

| System | Why it is used |
|--------|----------------|
| **Jira** | Where work starts, pauses, and gets human answers |
| **Confluence** | Reads standards/docs; publishes design pages |
| **GitHub** | Stores branches and draft pull requests |
| **Salesforce sandbox** | Safe place to validate the change |
| **LLM (AI model)** | Powers analysis, design judgment, review/QA reasoning |

Each connection can run in **demo/mock mode** (for testing) or **live mode** (with your credentials).

---

## 12. Frequently asked questions

**Does Agent Nova merge code by itself?**  
No. It opens a **draft** pull request. Humans merge.

**Does it deploy to production?**  
No. Production deploy is out of autonomous scope.

**Can it invent requirements?**  
It should not invent acceptance criteria. If the story is thin, it asks you.

**What if I reject the design?**  
It asks for clarification, then produces a new design and asks for approval again.

**What if two tickets ask for the same thing?**  
It tries to detect that, points to the original ticket, and waits for your decision.

**What if Confluence already documents the feature?**  
It cites the pages and waits for your decision to continue or stop.

**Who gets notified on comments?**  
When the ticket has an assignee, Agent Nova @mentions that person.

---

## 13. One-page cheat sheet for ticket comments

| Situation | Comment to write |
|-----------|------------------|
| Duplicate pause — proceed | `continue` |
| Duplicate pause — stop | `duplicate` or `close as duplicate` |
| Already-documented pause — proceed | `continue` |
| Already-documented pause — stop | `already done` or `close` |
| Design looks good | `approve` (or any clear approval comment) |
| Design is wrong | `reject — <what should change>` |
| After reject, provide details | Reply with the corrected requirements |

---

## 14. Bottom line

Agent Nova is a **supervised Salesforce delivery assistant**:

- You invite it through Jira  
- It plans before it builds  
- You approve the plan  
- It validates and checks quality  
- You own the final merge  

It is designed to save time on repeatable work while keeping humans in control of scope, risk, and production.

---

*If you want a live walkthrough, the recommended demo is: create a clear Story with label `agent-nova` → review the design pause → approve → inspect the draft PR.*