# 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
```

Leave `LLM_PROVIDER=mock` for offline/CI tests.

## 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)