# Agent Nova

Jira-triggered, human-supervised AI platform for Salesforce development automation.

Phase 1–4: webhook intake → job queue → orchestrator → Requirement Analyst → clarification → Solution Architect → design review → Salesforce Developer → deploy validate → Code Reviewer → QA → GitHub draft PR.

## Quick start

```bash
# Start Postgres (pgvector) + Redis
docker compose up -d

# Install
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Configure
cp .env.example .env

# Migrate
alembic upgrade head

# API
uvicorn apps.api.main:app --reload --port 8000

# Worker (separate terminal)
arq apps.worker.main.WorkerSettings
```

## Defaults

- Git: mock (set `GIT_PROVIDER=github` for live)
- Salesforce deploy: mock (set `SALESFORCE_PROVIDER=cli` for `sf` dry-run)
- Static analysis: mock (set `STATIC_ANALYSIS_PROVIDER=pmd` for PMD CLI)
- Apex tests: mock (set `APEX_TEST_PROVIDER=cli` for `sf apex run test`)
- LLM: OpenAI (set `LLM_PROVIDER=mock` for offline)
- Integrations: use `*_PROVIDER=mock` for local development without live credentials

## After `.env` changes

Restart **both** processes so settings reload (they are cached at process start):

```bash
# API
uvicorn apps.api.main:app --reload --port 8001

# Worker (separate terminal)
arq apps.worker.main.WorkerSettings
```

Startup logs print `jira_provider` and `llm_provider` — confirm they match `.env`.

## Live Confluence

```env
CONFLUENCE_PROVIDER=http
CONFLUENCE_BASE_URL=https://your-domain.atlassian.net/wiki
CONFLUENCE_SPACE_KEYS=ENG,ARCH
CONFLUENCE_WRITE_SPACE_KEY=
CONFLUENCE_EMAIL=you@example.com
CONFLUENCE_API_TOKEN=atlassian-api-token
```

If `CONFLUENCE_EMAIL` / `CONFLUENCE_API_TOKEN` are empty, the retriever/publisher fall back to Jira credentials.
At design review, Agent Nova creates a Confluence page (requirements + design) in `CONFLUENCE_WRITE_SPACE_KEY`, or the first `CONFLUENCE_SPACE_KEYS` entry when that is empty, and posts the URL on the Jira ticket.

## Live GitHub (Phase 3b)

```env
GIT_PROVIDER=github
GIT_REPO_URL=https://github.com/your-org/sfdx-repo
GIT_DEFAULT_BRANCH=main
GITHUB_TOKEN=ghp_...
```

Creates branch `agent-nova/<jira-key>`, commits `force-app/**` via the Git Data API, and opens a **draft** PR. Token needs `contents:write` and `pull_requests:write`.

## Salesforce lower-org deploy validate (Phase 3b)

```env
SALESFORCE_PROVIDER=cli
SALESFORCE_ORG_ALIAS=dev-sandbox
SALESFORCE_DEPLOY_CHECK_ONLY=true
```

Runs `sf project deploy start --dry-run` against the run artifact `force-app` before opening the PR. Production-like aliases (`prod`, `production`) are refused. Results are written to `deploy.json`. Leave `SALESFORCE_PROVIDER=mock` for CI.

Requires Salesforce CLI (`sf`) authenticated to the target lower org.

## Live LLM

```env
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini
```

Leave `LLM_PROVIDER=mock` for offline/CI tests (no OpenAI spend).

## Existing solution, data model, and metadata retrieval

- **Repository inspection** — with `GIT_PROVIDER=github`, the Analyst and Architect get a live inventory of `force-app` (Apex, triggers, Flows, LWCs, fields, validation rules) plus the best-matching files for the story.
- **Data model** — the Architect detects objects in the requirements and loads their schema (`data-model.json`). Existing fields/validation rules switch `create` → `update`; missing objects are flagged as risks.
- **Metadata retrieval** — before generating files, the Developer retrieves current versions of every planned component (`retrieved/`, `retrieved-metadata.json`). Existing source is kept instead of being overwritten by a stub, and the Code Reviewer compares against it.

```env
SALESFORCE_SCHEMA_PROVIDER=auto    # cli: sf sobject describe | repo: parse field XML on GitHub | mock
SALESFORCE_RETRIEVE_PROVIDER=auto  # cli: sf project retrieve start | repo: GitHub default branch | mock
```

`cli` uses `SALESFORCE_ORG_ALIAS` and refuses production-like aliases.

## Git "already implemented" check

Intake order: duplicate Jira check → Confluence "already documented" check → **Git check** → Requirement Analyst.
With `GIT_PROVIDER=github` and a `GITHUB_TOKEN`, the Git check gathers evidence from GitHub:

- **Repository files** — `force-app` paths in `GIT_REPO_URL` matching the ticket (summary + `__c` API names).
- **Code contents** — GitHub code search for the ticket's `__c` API names and summary keywords (default branches).
- **Ticket key** — the Jira key (e.g. `SALES-101`) in commit messages, PR titles/bodies (open, merged, closed), and branch names.
- **Open PR branches** — changed files on open PRs that match the ticket terms (every file for PRs that carry the key), since code search only indexes default branches.

```env
GITHUB_SEARCH_SCOPE=org        # org: every repo the token can read in GITHUB_ORG | repo: only GIT_REPO_URL
GITHUB_ORG=                    # defaults to the owner of GIT_REPO_URL
GITHUB_SEARCH_MAX_QUERIES=5    # code search is limited to 10 requests/minute
```

The LLM returns one of three verdicts:

- **Already implemented** (for example, a merged PR for the key plus matching code) → Agent Nova comments with links grouped by files / commits / PRs / branches and pauses in `GIT_REVIEW`:
  - `continue` → proceed to analysis/design
  - `already done` / `close` → stop the run
- **Partially implemented** (related code to extend, or an open PR/branch for the key) → Agent Nova posts an informational comment, saves the evidence to `existing-code.json`, and continues. The Architect sees that code in its prompt, switches matching plan items from `create` to `update`, and flags open PRs/branches as risks.
- **Not implemented** → continue as normal.

GitHub API errors or rate limits are recorded in the `git.check` audit event and the run continues with whatever evidence was gathered.

## Governor limit checks

Every review cycle scans generated Apex and Flows (`governor.json`, no external tools needed): SOQL/SOSL/DML/email/async calls inside loops, Flow Get/Create/Update/Delete Records inside loops, unbounded SOQL, and triggers that only handle `Trigger.new[0]`. Violations are merged into the static analysis results the Code Reviewer acts on.

## Coding standards

Team rules live in [`docs/CODING_STANDARDS.md`](docs/CODING_STANDARDS.md). Each rule is one bullet under a section heading (Apex, Triggers, Flows, …):

```markdown
- **APEX-01** MUST [auto]: Every top-level Apex class declares `with sharing` or `inherited sharing` ...
- **APEX-09** SHOULD: Every public class and public method has an ApexDoc comment ...
```

- `ID` — unique rule ID, referenced in review findings (e.g. `APEX-01: ...`).
- `LEVEL` — `MUST` violations are blocking (`high`) and send the code back through the fix loop; `SHOULD` violations are informational (`medium`).
- `[auto]` — also checked by code, not only by the LLM (sharing declarations, test class annotations/asserts, hardcoded record IDs, `System.debug`, trigger logic size, field naming/description, validation rule error messages, Flow description/IDs, `console.log` in LWC). Removing a rule from the file disables its automatic check too.

Where the rules are used:

- **Solution Architect** — naming and metadata rules (fields, validation rules, Flows, triggers, permission sets) are in the design prompt.
- **Review** — automatic checks run every cycle and are written to `standards.json`; violations are merged into the static analysis results. The LLM reviewer gets every rule and reports violations with `category="standards"`.
- **Fix loop** — the fix prompt includes the rules so fixed code satisfies them, not only the reported findings.

```env
CODING_STANDARDS_PATH=docs/CODING_STANDARDS.md
```

Relative paths resolve from the project root. Edits to the file are picked up on the next run without restarting the API or worker. If the file is missing, a warning is logged and the run continues without standards.

## Code review and QA (Phase 4)

```env
STATIC_ANALYSIS_PROVIDER=mock
PMD_BIN=pmd
MAX_REVIEW_CYCLES=3

APEX_TEST_PROVIDER=mock
```

After deploy validate, the orchestrator runs static analysis (`pmd.json`), code review (`review.json`), and QA (`qa-report.json`) before creating the draft PR. Failed review with fixable findings triggers an LLM fix loop (max 3 cycles). Review or QA failure → `FAILED` + Jira comment.

Set `STATIC_ANALYSIS_PROVIDER=pmd` when PMD CLI is installed. Set `APEX_TEST_PROVIDER=cli` to run Apex tests against `SALESFORCE_ORG_ALIAS` (reuses sandbox auth from Phase 3b).

## Docs

- [Phase 0 access checklist](docs/phase-0/ACCESS_CHECKLIST.md)
- [Trigger rules](docs/phase-0/TRIGGER_RULES.md)
- [Metadata allowlist](docs/phase-0/ALLOWLIST.md)
- [Phase 3 handoff](docs/phase-2/PHASE3_HANDOFF.md)
- [Phase 4 handoff](docs/phase-2/PHASE4_HANDOFF.md)
- [Session 2026-08-24](docs/phase-1/SESSION_2026-08-24.md)
- [Session 2026-08-25](docs/phase-1/SESSION_2026-08-25.md)
- [Session 2026-08-26](docs/phase-1/SESSION_2026-08-26.md)
- [Session 2026-08-27](docs/phase-1/SESSION_2026-08-27.md)
- [Session 2026-08-31](docs/phase-1/SESSION_2026-08-31.md)
