# Agent Instructions — Salesforce Appraiser Review Letter

> Read this file at the start of every iteration. It is the canonical operating guide.

---

## Role

You are a senior Salesforce developer working autonomously on the appraiser review letter project.
You have full access to the codebase and can read, write, and run shell commands.

---

## Core Loop

### 1. Orient

- Read `PROJECT-SPEC.md` — requirements and acceptance criteria for Phase 2
- Read `IMPLEMENTATION_PLAN.md` — task list and current status
- Read `DECISIONS.md` — architecture decisions already in force
- Run `git log --oneline -10` — see what has been done
- Check for any prior escalations in `IMPLEMENTATION_PLAN.md`

### 2. Pick ONE Task

- Find the first unchecked task `- [ ]` in `IMPLEMENTATION_PLAN.md`
- If all tasks are checked, output `<promise>DONE</promise>` and exit
- Work only on this one task — do not pick up the next one

### 3. Implement

- Follow the existing code patterns in the project
- Read the relevant existing classes/LWCs before writing new code
- Study the CLM tracking pattern as the model for eSignature tracking

### 4. Verify — BLOCKING before commit

```bash
# Set up the CLI path (system Node v12 is too old — always use nvm Node)
NODE=/home/paulh/.nvm/versions/node/v22.22.0/bin/node
SF=/home/paulh/.nvm/versions/node/v22.22.0/lib/node_modules/@salesforce/cli/bin/run.js

# Deploy source to org
$NODE $SF project deploy start \
  --source-dir force-app \
  --target-org appraiser-dev

# Run Apex tests (synchronous, human-readable output)
$NODE $SF apex run test \
  --target-org appraiser-dev \
  --class-names DocusignESignatureServiceTest,CLMAdminServiceTest,AppraiserCasePayloadBuilderTest,CLMDocGenCalloutTest \
  --result-format human \
  --synchronous
```

**Do not commit if deploy fails or tests fail.**

For metadata-only tasks (adding custom fields, no Apex changes): deploy and confirm the object deploys cleanly, but you do not need to run all test classes — run a smoke test against the affected test class only.

### 5. Commit and Mark Done

Commit with this exact trailer format:

```
<type>(<scope>): <description>

<optional body>

Agent: claude-sonnet-4-6
Tests: N/N passing | N/A (metadata-only)
Tests-Added: +N | 0
TypeScript: N/A (Apex project)
```

Then mark the task `- [x]` in `IMPLEMENTATION_PLAN.md` and commit that update in the same commit.

### 6. Exit

Output a brief summary (what you did, test results, what is next) and exit.
The loop will restart you with fresh context for the next task.

---

## Rules

1. **One task per iteration.** Never work on multiple tasks.
2. **Read before writing.** Always read the existing class/LWC before modifying it.
3. **Follow existing patterns.** The CLM tracking pattern is the model for eSignature tracking.
4. **Tests are mandatory for every Apex change.** Add to the existing test classes — do not create new ones unless the spec says to.
5. **Never add fields or methods not required by the spec.** Implement what is asked, nothing more.
6. **Never modify production data.** All DML in tests uses `@isTest` and `Test.startTest()/stopTest()`.
7. **Mock HTTP callouts in tests.** Use `HttpCalloutMock` — same pattern as existing test classes.
8. **Deploy before committing.** Never commit code that does not deploy cleanly.
9. **Follow DECISIONS.md.** Do not change approaches listed as Accepted without escalating.
10. **If stuck, escalate.** Do not invent missing requirements.

---

## Escalation Protocol

Stop and add this block at the top of `IMPLEMENTATION_PLAN.md`, then output `<promise>STUCK</promise>`:

```markdown
## ESCALATION REQUIRED
- **Task:** [current task]
- **Issue:** [what is ambiguous/missing/conflicting]
- **What I need:** [specific question or decision]
- **What I'd do if I had to guess:** [best guess]
```

Escalate when:
- The spec has no FR covering a required decision
- A constraint in DECISIONS.md conflicts with the spec
- A Salesforce platform limit or API behavior is unclear
- A named credential or metadata record is missing from the org
- Any task requires deleting or overwriting existing custom fields already in use

---

## Output Signals

- `<promise>PLANNED</promise>` — plan created, ready for build
- `<promise>DONE</promise>` — all tasks complete
- `<promise>STUCK</promise>` — needs human intervention
- `<promise>ERROR</promise>` — unrecoverable error

---

## Project Structure

```
force-app/main/default/
├── classes/
│   ├── CLMAdminService.cls          ← orchestration + persistDocGenResult pattern
│   ├── CLMAdminServiceTest.cls      ← test pattern to follow
│   ├── CLMDocGenCallout.cls
│   ├── CLMDocGenCalloutTest.cls
│   ├── DocusignESignatureService.cls  ← add createEnvelope() here
│   ├── DocusignESignatureServiceTest.cls
│   ├── AppraiserCasePayloadBuilder.cls
│   └── AppraiserCasePayloadBuilderTest.cls
├── lwc/
│   ├── clmDocGenWorkbench/          ← add Send for Signature button here
│   └── docusignEsignWorkbench/      ← read-only browsing (do not modify Phase 2)
└── objects/
    └── Appraiser_Case__c/
        └── fields/                  ← add 5 eSignature tracking fields here
```

---

## SF CLI Invocation (Always Use This Pattern)

```bash
NODE=/home/paulh/.nvm/versions/node/v22.22.0/bin/node
SF=/home/paulh/.nvm/versions/node/v22.22.0/lib/node_modules/@salesforce/cli/bin/run.js
$NODE $SF <subcommand> <args>
```

Target org alias: `appraiser-dev`

---

## Context Anchor

- **Phase 1 is complete** — CLM doc generation works end-to-end. Do not modify it.
- **Phase 2 goal** — after a CLM doc is generated and attached, enable sending it for eSignature using a DocuSign template (Option A).
- **The authoritative plan** is in `NEXT_STEPS_DOCGEN.md` under Phase 2. `IMPLEMENTATION_PLAN.md` is the execution tracker derived from it.